feat: add the hierarchical Execution engine on LangGraph
Increment 4 of .scratch/solution-architect-agent/spec.md, test-first. - app/agents/runtime.py: framework-neutral AgentRuntime interface (RoleSpec, AgentTask, ToolSpec, outcomes); fake_runtime.py replays scripted tool calls through the real tools with step budgets. - app/execution/graph.py: Orchestrator turn fans out to parallel Specialist tasks (Send), pauses with interrupt() for questions, Approvals and cloud-read permission, and finalizes or ends with warnings. Only the Orchestrator turn writes the Ledger. - app/execution/tools.py: Orchestrator tools, Specialist submit and needs_input, and the cloud-read permission gate. - app/execution/engine.py: ExecutionEngine.start/resume returning an Interaction; the single interface for A2A, /generate and eval. - Recorders (in-memory, DatabaseManager), configurable checkpointer (memory, sqlite, postgres), engine settings, langgraph checkpoint dependencies. - 19 new tests; full suite 121 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -569,3 +569,44 @@ Slowest tests: eval benchmark 7.3 s, then 3–4.5 s each for the orchestrator, e
|
||||
- `solution_guide`: the template's 8 top-level sections.
|
||||
- `architecture_diagram`: attachment `architecture.mmd`.
|
||||
- `technical_decomposition` and `architecture_description`: non-empty content only.
|
||||
|
||||
### 2026-09-15 · Increment 4: Execution graph
|
||||
|
||||
**Done (test-first)**
|
||||
- `app/agents/runtime.py`: the `AgentRuntime` protocol, `RoleSpec`, `AgentTask`, `ToolSpec`/`ToolResult`, and the outcomes `Submitted | NeedsInput | BudgetExhausted | Stopped | TurnEnded`.
|
||||
- `app/agents/fake_runtime.py`: `FakeAgentRuntime`, which replays scripted tool calls per role through the real `ToolSpec`s, enforces `RoleSpec.budget`, and records every run (task, tools offered, tool messages, outcome).
|
||||
- `app/execution/state.py`: `ExecutionState` (JSON-compatible). `outcomes` uses an append reducer, so parallel Specialist tasks never write the Ledger.
|
||||
- `app/execution/tools.py`:
|
||||
- `OrchestratorToolbox`: `ready_work`, `delegate`, `ask_user`, `request_approval`, `reopen`, `read_deliverable`, `finish`.
|
||||
- `specialist_tools`: `submit_deliverable` (checks the contract and refuses unsafe attachment paths) and `needs_input`, plus the role's extra tools.
|
||||
- `gate_cloud_read`: allow / refuse / ask permission.
|
||||
- `app/execution/graph.py`: `orchestrator_turn` → `Send` × N `specialist_task` → `orchestrator_turn`; `await_user` (`interrupt`); `finalize`; `end_with_warnings`.
|
||||
- `app/execution/engine.py`: **`ExecutionEngine.start(request, session_id, pre_approved, allow_cloud_read)` / `resume(execution_id, reply)` / `interaction(execution_id)` → `Interaction(status, prompt, state)`**. This is the one interface for A2A, `/generate` and the eval harness. The tests use only it.
|
||||
- `app/execution/recorder.py`: the `ExecutionRecorder` protocol with `InMemoryRecorder` and `DatabaseRecorder` (the existing tables via `asyncio.to_thread`).
|
||||
- `app/execution/checkpointing.py`: `open_checkpointer(settings)` for `memory | sqlite | postgres`.
|
||||
- Settings `ORCHESTRATOR_BUDGET`, `SPECIALIST_BUDGET`, `MAX_REVISIONS`, `MAX_ORCHESTRATOR_TURNS`, `CHECKPOINTER` (default `sqlite`) and `CHECKPOINT_DB_PATH`, plus `.env.example`. `requirements.txt`: `langgraph>=1.2`, `langgraph-checkpoint-sqlite`, `langgraph-checkpoint-postgres`, `psycopg[binary]`.
|
||||
- Tests:
|
||||
- `tests/execution/test_engine.py`: 17 tests covering the pre-approved happy path with written files, parallel start, dependency context, refusal messages, incomplete submissions, Approval pause/resume, free text never approving, changes → Revision → re-approval, one voice, Revision after a validation failure, pre-approved escalation, Orchestrator and Specialist budgets, cloud-read ask/grant/deny, clean Executions, and resuming from a durable SQLite checkpoint.
|
||||
- `tests/execution/test_recording.py`: 2 tests covering `DatabaseRecorder` against a temp SQLite database, and the checkpointer factory.
|
||||
- Full suite: **121 passed**. `ruff` and `mypy` are clean on `app/agents` and `app/execution`.
|
||||
- **Checking the tests bite.** I broke each of these in the code on purpose, and each break failed at least one test:
|
||||
- no cloud-read gate
|
||||
- permission never asked
|
||||
- Specialist questions dropped
|
||||
- submission contract unchecked
|
||||
|
||||
**Added to or changed from the spec text**
|
||||
- **Engine and file names.** There's a new `app/execution/engine.py` facade, and tests live in `test_engine.py`/`test_recording.py`, not `test_graph.py`. The graph is an internal detail behind the engine.
|
||||
- **`Stopped` outcome.** An agent that ends without a turn-ending tool is `Stopped`. Tools end a run by returning `ToolResult(outcome=...)`, so ending can depend on the result: pre-approved `request_approval` doesn't end the turn, and refusals never do. Engine-owned tools use `tier="execution"`.
|
||||
- **Prompt and reply shapes.**
|
||||
- `Interaction.prompt` is `{"questions": [{"from": <kind|orchestrator>, "question"}]}`, `{"approval": {"phase", "summary", "deliverables"}}` or `{"permission": {"tier", "requested_by"}}`.
|
||||
- `resume` takes `{"reply": str}`, `{"approval": {"phase", "decision": approve|changes, "feedback"}}` or `{"permission": {"cloud_read": bool}}`.
|
||||
- An approval reply that isn't structured goes into the conversation and never grants.
|
||||
- **Single writer.** Specialist outcomes are applied by the next `orchestrator_turn` in graph order, using `outcomes_applied`. A superseded result (stale attempt) is discarded and noted to the Orchestrator.
|
||||
- **Specialist problems as questions.** A Specialist that runs out of budget or stops is released and relayed as a question from its Deliverable, keeping one voice. A permission `NeedsInput` becomes a single permission prompt, not a question.
|
||||
- **Pre-approved mode.** `allow_cloud_read=None` becomes `False`. An escalation, or an Orchestrator that can't continue, ends as `completed_with_warnings` with no files written.
|
||||
- **Loop guard.** `MAX_ORCHESTRATOR_TURNS` (default 100) bounds loops, and the LangGraph `recursion_limit` is raised to 10 000.
|
||||
- **Conversation.** It records the Orchestrator's rendered prompts as well as user replies.
|
||||
- **Session name.** `DatabaseRecorder` session rows use `agent_name="solution-architect"`.
|
||||
- **Deferred to increment 5:** the design advisor's pillar fan-out tool, which needs the `pillar-advisor` role file.
|
||||
- **Not tested:** `AsyncPostgresSaver` against a real PostgreSQL (none runs locally). The import and wiring are in place.
|
||||
|
||||
Reference in New Issue
Block a user