37 lines
3.1 KiB
Markdown
37 lines
3.1 KiB
Markdown
# 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`. |