manual_slop/docs/guide_app_controller.md

src/app_controller.py — Headless Orchestrator & State Hub

Top | Architecture | Discussions | State Lifecycle | Context Aggregation | MMA | Testing

---

Overview

src/app_controller.py (~166KB) is the headless controller that owns the application's state and business logic. It decouples the GUI (gui_2.py) from the underlying subsystems (AI, presets, personas, RAG, history, MMA, paths, hot reload).

When --enable-test-hooks is passed, the controller also spins up the HookServer so external tests/scripts can drive the running app.

---

Architecture

┌─────────────────────────────────────────────────┐
│  gui_2.py (App)                                   │
│  - Pure immediate-mode UI                        │
│  - Reads app_state for rendering                  │
│  - Calls controller methods for mutations         │
└─────────────────┬───────────────────────────────┘
                  │ delegates to
                  ▼
┌─────────────────────────────────────────────────┐
│  app_controller.py: AppController                 │
│  - State container (AppState)                     │
│  - Subsystem coordination (presets, personas, ...) │
│  - Headless mode: skips GUI init, starts hook     │
│    server on port 8999                            │
│  - Provides _predefined_callbacks and             │
│    _gettable_fields for the Hook API              │
└─────────────────┬───────────────────────────────┘
                  │ owns/uses
                  ▼
┌─────────────────────────────────────────────────┐
│  Subsystems                                       │
│  - PresetManager (src/presets.py)                  │
│  - PersonaManager (src/personas.py)                │
│  - ContextPresetManager (src/context_presets.py)   │
│  - ToolPresetManager (src/tool_presets.py)         │
│  - ToolBiasEngine (src/tool_bias.py)               │
│  - RAGEngine (src/rag_engine.py)                   │
│  - HistoryManager (src/history.py)                 │
│  - WorkspaceManager (src/workspace_manager.py)     │
│  - HookServer (src/api_hooks.py)                   │
│  - HotReloader (src/hot_reload.py)                 │
│  - PathManager (src/paths.py)                      │
└─────────────────────────────────────────────────┘

---

The AppController Class

__init__(self, defer_warmup: bool = False, log_to_stderr: Optional[bool] = None)

Important: The __init__ does NOT create manager objects, does NOT register hooks, and does NOT start the HookServer. The previous documentation in this section was fictional (a fabricated AppState dataclass, fabricated enable_test_hooks parameter, fabricated register_hooks method, and manager objects that don't exist on the controller).

Initializes the controller. Real state created here:

The actual __init__ (src/app_controller.py:778-836) does the following:

1. Startup timeline anchors — Captures _init_start_ts for the startup_timeline() diagnostics. Other timeline anchors are filled in lazily as events occur.
2. Locks — Creates 12 thread-safety locks (_send_thread_lock, _disc_entries_lock, _pending_*_lock for comms/tool_calls/history/gui_tasks/dialog/api_event_queue, _rag_engine_lock, _rag_sync_lock/_rag_sync_token/_rag_sync_dirty for FR3 coalescing, _project_switch_lock/_project_switch_in_progress/_project_switch_pending_path/_project_switch_error).
3. GUI health state — _gui_degraded_reason and _last_imgui_assert (set when immapp.run raises RuntimeError; see guide_gui_2.md).
4. Shared io_pool — make_io_pool() creates a 4-thread ThreadPoolExecutor named controller-io-N. This is the SOLE background pool for all async work (no threading.Thread() calls anywhere else in src/).
5. Warmup manager — WarmupManager(self._io_pool, log_to_stderr=log_to_stderr) with an on-complete callback to stamp warmup_done_ts. defer_warmup=True defers the actual start_warmup() call until the first frame is painted (the desktop GUI pattern; headless mode starts immediately).
6. Various flags — _warmup_started, _pending_fetch_provider, _defer_warmup.

Manager objects (preset_manager, persona_manager, context_preset_manager, tool_preset_manager, tool_bias_engine, history_manager, workspace_manager, rag_engine) are NOT created in __init__. They are lazy attributes accessed via __getattr__ and created on first reference (typically from _load_active_project at src/app_controller.py:2150 or from App._post_init at src/gui_2.py:492).

Hook API surface is NOT populated by a register_hooks method. The actual flow:

1. AppController._init_actions() (called from init_state at src/app_controller.py:1740) populates self._predefined_callbacks and self._gettable_fields registries via module-level handler registration functions.
2. src/api_hooks.py:HookHandler.do_GET / do_POST reads from these registries to expose App methods as /api/gui custom_callback actions.
3. The sloppy.py CLI parses --enable-test-hooks and passes it to HookServer (a separate class, not the controller).

For the actual init flow, read src/app_controller.py:778-1212 (__init__; the long range is mostly _post_init-style wiring for the 12 locks, GUI health state, io_pool, warmup manager, and lazy manager defs), :1606 (_init_actions), :1740 (init_state), and :2150 (_load_active_project).

This is the only bridge between the GUI's app methods and the external Hook API. If a method is not in _predefined_callbacks, external callers cannot invoke it.

Subsystem Coordination Methods

The controller has methods that span multiple subsystems:

• reload_presets() — re-reads preset TOML files from disk
• reload_personas() — same for personas
• reload_context_presets() — validates files exist
• apply_persona(persona_name, target) — switches model, system prompt, and tool weights for a target
• dispatch_mma_track(track_id) — kicks off a multi-agent track
• reset_session() — clears discussion history, resets UI state, etc.
• save_state_to_disk() / load_state_from_disk() — for historical session replay
• inject_context_files(paths) — adds files to the active context composition

---

The AppState Dataclass

app_state is a flat dataclass holding all GUI-visible state. Examples:

@dataclass
class AppState:
    current_provider: str = "gemini"
    current_model: str = "gemini-3-flash-preview"
    temperature: float = 0.7
    top_p: float = 0.95
    max_output_tokens: int = 8192
    system_prompt: str = ""
    discussion_history: list[DiscussionEntry] = field(default_factory=list)
    context_files: list[ContextFileEntry] = field(default_factory=list)
    context_screenshots: list[str] = field(default_factory=list)
    show_command_palette: bool = False
    show_preset_manager: bool = False
    show_persona_editor: bool = False
    show_context_preview: bool = False
    show_diagnostics: bool = False
    show_mma_dashboard: bool = False
    # ... many more

The App reads from app_state for rendering and writes back via setter methods. All setters are exposed to the Hook API via _gettable_fields and other "settable" registries.

---

Preset & Persona Management

PresetManager (in src/presets.py)

The controller delegates preset CRUD to PresetManager. The controller itself only coordinates when presets change (re-apply to active session, update system prompt, etc.).

# In controller
def on_preset_changed(self, new_preset_name: str) -> None:
    preset = self.presets.get(new_preset_name)
    self.app_state.system_prompt = preset.full_text  # Base + persona
    self.app_state.temperature = preset.temperature
    self.app_state.top_p = preset.top_p
    self.app_state.max_output_tokens = preset.max_output_tokens

PersonaManager (in src/personas.py)

Consolidates model settings + system prompt + tool weights into a single named entity.

# In controller
def apply_persona(self, persona_name: str, target: str = "tier3") -> None:
    persona = self.personas.get(persona_name)
    if persona.model:
        self.app_state.current_model = persona.model
    if persona.system_prompt:
        self.app_state.system_prompt = persona.system_prompt
    if persona.tool_weights:
        self.tool_bias.apply_weights(persona.tool_weights, target=target)
    if persona.bias_profile:
        self.tool_bias.apply_profile(persona.bias_profile)

target is the MMA tier ("tier1", "tier2", "tier3", "tier4"). This is how MMA agents get isolated cognitive load.

ContextPresetManager (in src/context_presets.py)

Saves/loads complete context compositions (files, screenshots, view modes). Validates that referenced files still exist on load.

ToolPresetManager (in src/tool_presets.py)

Manages tool enable/disable + weights. Persisted to tool_presets.toml.

ToolBiasEngine (in src/tool_bias.py)

Applies weights and global bias profiles. Generates the "Tooling Strategy" section appended to system prompts.

---

History Management

HistoryManager (in src/history.py) implements the non-provider undo/redo system.

def on_ui_state_change(self) -> None:
    """Called when the UI changes (e.g., text input). Pushes a snapshot."""
    snapshot = self.history.capture(self.app_state)
    self.history.push(snapshot)
    self.app_state.can_undo = self.history.can_undo()
    self.app_state.can_redo = self.history.can_redo()

Snapshots include:

• All text inputs (system prompt, AI input, code blocks)
• Model parameters (Temperature, Top-P, Max Output Tokens)
• Context (files, screenshots)
• Discussion history (for discussion mutations)

Capacity is fixed (default: 50 snapshots). Older entries are evicted.

Branching History ("Takes")

HistoryManager also tracks timeline branching. When the user reverts and then takes a new action, a new "take" is created. The full history graph is preserved for back-navigation.

---

RAG Engine Integration

RAGEngine (in src/rag_engine.py) is owned by the controller but lazy-loaded on first use:

def get_rag_engine(self) -> RAGEngine:
    if self._rag_engine is None:
        from src.rag_engine import RAGEngine
        self._rag_engine = RAGEngine(self.paths)
    return self._rag_engine

The GUI exposes a RAG settings panel that calls controller.get_rag_engine().set_provider(...), set_chunk_size(...), etc.

RAG Lifecycle

1. Indexing: controller.index_project() walks the project workspace, chunks files, embeds them, writes to ChromaDB (or external MCP).
2. Search: controller.search_context_files(query) returns top-k fragments with source paths.
3. Injection: Fragments are prepended to the AI's prompt via ai_client.send(...). The controller orchestrates the flow.

---

MMA Conductor Integration

MultiAgentConductor (in src/multi_agent_conductor.py) is also lazy-loaded:

def get_mma_conductor(self) -> 'MultiAgentConductor':
    if self._mma_conductor is None:
        from src.multi_agent_conductor import MultiAgentConductor
        self._mma_conductor = MultiAgentConductor(self)
    return self._mma_conductor

The controller passes itself into the conductor so workers can access presets/personas/RAG during execution.

Dispatch Flow

controller.dispatch_mma_track(track_id)
  -> conductor.load_track(track_id)
  -> conductor.start_workers(track)
  -> workers run in parallel via WorkerPool
  -> workers call back into controller (presets, personas, etc.)
  -> results pushed to controller.app_state.discussion_history
  -> conductor emits events to controller.event_queue

The event_queue is consumed by the GUI on the main thread to update display.

---

Hot Reload

The controller can hot-reload Python modules while preserving state. This is critical for GUI iteration:

def hot_reload(self, module_name: str) -> None:
    """Reload a module and re-apply its render functions to the app."""
    from src.hot_reload import HotReloader
    reloader = HotReloader(self.app)
    reloader.reload(module_name)

gui_2.py registers all its render functions with the reloader at startup. On reload, the reloader swaps the function references without losing app state.

See docs/guide_hot_reload.md for the full mechanism.

---

The SyncEventQueue

A queue.Queue-based bridge between the daemon threads (AI workers, MMA workers) and the GUI main thread.

class SyncEventQueue:
    def put(self, event: Event) -> None: ...
    def get_nowait(self) -> Event | None: ...
    def get_all(self) -> list[Event]: ...

The GUI polls controller.event_queue.get_all() once per frame and dispatches events to render functions.

Event Types

• MMA_TICKET_COMPLETED
• MMA_LOG_MESSAGE
• AI_RESPONSE_CHUNK
• AI_RESPONSE_COMPLETE
• TOOL_CALL_STARTED
• TOOL_CALL_COMPLETED
• PERSONA_APPLIED
• WORKSPACE_LOADED
• RAG_INDEX_COMPLETE
• HOOK_CALLBACK_RECEIVED

The controller translates subsystem-specific events into these generic types.

---

The Headless Mode

When sloppy.py is launched with --headless, the controller is instantiated without an App:

# In sloppy.py --headless
controller = AppController(enable_test_hooks=True)
# ... run server-only logic ...
# No GUI, no ImGui context, but full subsystem access

This is the Headless Backend Service mode. The controller still listens on :8999 and serves all Hook API endpoints. Tests and external scripts can drive the headless service.

---

Hook API Surface (Defined Here)

The controller is the single source of truth for what the Hook API can do. Three registries:

_predefined_callbacks: dict[str, Callable]

Maps hook name → App method. Populated by register_hooks(app).

self._predefined_callbacks['_toggle_command_palette'] = app._toggle_command_palette
self._predefined_callbacks['_open_command_palette'] = app._open_command_palette
self._predefined_callbacks['save_context_preset'] = app.save_context_preset
self._predefined_callbacks['load_context_preset'] = app.load_context_preset
# ... ~30 entries

_gettable_fields: dict[str, str]

Maps hook name → AppState field name. Used by get_value Hook API action.

self._gettable_fields['show_command_palette'] = 'show_command_palette'
self._gettable_fields['current_provider'] = 'current_provider'
self._gettable_fields['current_model'] = 'current_model'
# ... etc

_action_handlers: dict[str, Callable]

Maps action name (e.g., "click", "set_value", "custom_callback") → handler.

self._action_handlers['click'] = self._handle_click
self._action_handlers['set_value'] = self._handle_set_value
self._action_handlers['custom_callback'] = self._handle_custom_callback
# ... etc

The HookServer in src/api_hooks.py consumes these registries to route incoming requests.

---

Testing

The controller is tested via the live_gui fixture (full integration) and targeted unit tests.

Unit Tests

• tests/test_app_controller_init.py — instantiation, subsystem wiring
• tests/test_preset_manager.py — preset CRUD
• tests/test_persona_manager.py — persona CRUD + application
• tests/test_context_presets.py — context preset CRUD + file validation
• tests/test_history.py — undo/redo
• tests/test_workspace_manager.py — workspace profile CRUD

Integration Tests (live_gui)

Use the ApiHookClient to drive the controller and verify state mutations.

def test_apply_persona(live_gui):
    client = ApiHookClient()
    client.push_event("custom_callback", {"callback": "apply_persona", "args": ["code-reviewer"]})
    time.sleep(0.5)
    model = client.get_value("current_model")
    assert "code" in model.lower() or model == "code-reviewer-model"

---

Common Pitfalls

1. Don't instantiate AppController twice in the same process: The singleton holds RAG engine, MMA conductor, hook server. A second instance would conflict.
2. Don't read app_state from a daemon thread without locking: Use event_queue for cross-thread communication.
3. Always go through the controller for subsystem changes: Don't call self.presets.save(...) from the GUI directly; call controller.save_preset(...) so the event is broadcast.
4. When adding a new Hook API callback, register it in BOTH _predefined_callbacks AND register_hooks: The latter is what populates the registry from an App instance.

---

See Also

• guide_architecture.md — Threading and event flow
• guide_mma.md — How MMA workers use the controller
• guide_ai_client.md — How ai_client integrates
• guide_api_hooks.md — The Hook API the controller exposes
• guide_hot_reload.md — How the controller supports state-preserving reloads
• guide_discussions.md — The Discussion system (Takes, branching, _switch_discussion, _branch_discussion, _rename_discussion, _delete_discussion, _flush_disc_entries_to_project)
• guide_state_lifecycle.md — The _handle_reset_session and _handle_compress_discussion flows, the App.__getattr__/__setattr__ state delegation pattern, and the HistoryManager integration
• guide_context_aggregation.md — The aggregate.py pipeline that the controller calls per send (per-provider + Tier 3 worker)
• src/presets.py, src/personas.py, src/context_presets.py, src/tool_presets.py, src/tool_bias.py — Subsystem managers
• src/history.py — HistoryManager
• src/rag_engine.py — RAGEngine
• src/multi_agent_conductor.py — MultiAgentConductor
• src/hot_reload.py — HotReloader
• src/api_hooks.py — HookServer (uses the controller's registries)
• src/paths.py — PathManager
• conductor/tracks/nagent_review_20260608/report.md — Deep-dive analysis of the controller's per-provider history globals and other state patterns