manual_slop/MMA_Support/Orchestrator_Engine.md

The Orchestrator Engine & UI

To transition from a linear, single-agent chat box to a multi-agent control center, the GUI must be decoupled from the LLM execution loops. A single-agent UI assumes a linear flow (User types -> UI waits -> LLM responds -> UI updates), which freezes the application if a Tier 1 PM waits for human approval while Tier 3 Workers run local tests in the background.

1. The Async Event Bus (Decoupling UI from Agents)

The GUI acts as a "dumb" renderer. It only renders state; it never manages state.

• The Agent Bus (Message Queue): A thread-safe signaling system (e.g., asyncio.Queue, pyqtSignal) passes messages between agents, UI, and the filesystem.
• Background Workers: When Tier 1 spawns a Tier 2 Tech Lead, the GUI does not wait. It pushes a UserRequestEvent to the Conductor's queue. The Conductor runs the LLM call asynchronously and fires StateUpdateEvents back for the GUI to redraw.

2. The Execution Clutch (HITL)

Every spawned worker panel implements an execution state toggle based on the trust_level defined in agents.toml.

• Step Mode (Lock-step): The worker pauses twice per cycle:
  1. After generating a response/tool-call, but before executing the tool. The GUI renders a preview (e.g., diff of lines 40-50) and offers [Approve], [Edit Payload], or [Abort].
  2. After executing the tool, but before sending output back to the LLM (allows verification of the system output).
• Auto Mode (Fire-and-forget): The worker loops continuously until it outputs a "Task Complete" status to the Router.

3. Memory Mutation (The "Debug" Superpower)

If a worker generates a flawed plan in Step Mode, the "Memory Mutator" allows the user to click the last message and edit the raw JSON/text directly before hitting "Approve." By rewriting the AI's brain mid-task, the model proceeds as if it generated the correct idea, saving the context window from restarting due to a minor hallucination.

4. The Global Execution Toggle

A Global Execution Toggle overrides all individual agent trust levels for debugging race conditions or context leaks.

• Mode = "async" (Production): The Dispatcher throws Tickets into an asyncio.TaskGroup. They spawn instantly, fight for API rate limits, read the skeleton, and run in parallel.
• Mode = "linear" (Debug): The Dispatcher iterates through the array sequentially using a strict for loop. It awaits absolute completion of Ticket 1 (including QA loops and code review) before instantiating the WorkerAgent for Ticket 2. This enforces a deterministic state machine and outputs state snapshots (debug_state.json) for manual verification.

5. State Machine (Dataclasses)

The Conductor relies on strict definitions for Track and Ticket to enforce state and UI rendering (e.g., using dataclasses or pydantic).

• Ticket: Contains id, target_file, prompt, worker_archetype, status (pending, running, blocked, step_paused, completed), and a dependencies list of Ticket IDs that must finish first.
• Track: Contains id, title, description, status, and a list of Tickets.