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:
2026-09-16 09:38:13 +01:00
parent c8410946b8
commit d9214c671a
15 changed files with 2143 additions and 1 deletions

145
app/execution/engine.py Normal file
View File

@@ -0,0 +1,145 @@
"""ExecutionEngine: start and resume Executions.
The one interface the A2A server, /generate and the evaluation harness use. Each
call runs the Execution until it needs the user or finishes, and returns an
Interaction describing which.
"""
from __future__ import annotations
import uuid
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.base import BaseCheckpointSaver
from langgraph.types import Command
from app.agents.runtime import AgentRuntime, RoleSpec
from app.execution.deliverables import DEPENDENCY_GRAPH
from app.execution.graph import ToolFactory, build_execution_graph
from app.execution.ledger import Ledger
from app.execution.recorder import ExecutionRecorder
from app.execution.tools import ORCHESTRATOR
_RECURSION_LIMIT = 10_000 # loops are bounded by max_orchestrator_turns instead
@dataclass(frozen=True)
class Interaction:
execution_id: str
status: str # awaiting_user | completed | completed_with_warnings
prompt: Mapping[str, Any] | None # questions | approval | permission
state: Mapping[str, Any]
class ExecutionNotAwaitingUser(RuntimeError):
pass
class ExecutionEngine:
def __init__(
self,
*,
runtime: AgentRuntime,
roles: Mapping[str, RoleSpec],
recorder: ExecutionRecorder,
checkpointer: BaseCheckpointSaver,
output_root: Path,
max_revisions: int = 3,
max_orchestrator_turns: int = 100,
tool_factory: ToolFactory | None = None,
) -> None:
required = {
ORCHESTRATOR,
*(spec.specialist for spec in DEPENDENCY_GRAPH.values()),
}
missing = sorted(required - set(roles))
if missing:
raise ValueError(f"Missing roles: {', '.join(missing)}")
self._max_revisions = max_revisions
self._graph = build_execution_graph(
runtime=runtime,
roles=roles,
recorder=recorder,
output_root=output_root,
max_orchestrator_turns=max_orchestrator_turns,
tool_factory=tool_factory,
).compile(checkpointer=checkpointer)
async def start(
self,
workflow_request: str,
*,
session_id: str | None = None,
pre_approved: bool = False,
allow_cloud_read: bool | None = None,
) -> Interaction:
execution_id = str(uuid.uuid4())
if pre_approved and allow_cloud_read is None:
allow_cloud_read = False
initial: dict[str, Any] = {
"execution_id": execution_id,
"session_id": session_id or str(uuid.uuid4()),
"workflow_request": workflow_request,
"pre_approved": pre_approved,
"allow_cloud_read": allow_cloud_read,
"ledger": Ledger(
pre_approved=pre_approved, max_revisions=self._max_revisions
).to_dict(),
"deliverables": {},
"conversation": [{"from": "user", "text": workflow_request}],
"notes": [],
"pending_questions": [],
"awaiting_questions": [],
"answers": {},
"pending_permission": None,
"prompt": None,
"outcomes": [],
"outcomes_applied": 0,
"events_recorded": 0,
"turns": 0,
"status": "running",
"warnings": [],
}
await self._graph.ainvoke(initial, self._config(execution_id))
return await self.interaction(execution_id)
async def resume(self, execution_id: str, reply: Mapping[str, Any]) -> Interaction:
"""Answer the Execution's current prompt: {"reply"} | {"approval"} | {"permission"}."""
current = await self.interaction(execution_id)
if current.status != "awaiting_user":
raise ExecutionNotAwaitingUser(
f"Execution {execution_id} is {current.status}, not awaiting the user"
)
await self._graph.ainvoke(
Command(resume=dict(reply)), self._config(execution_id)
)
return await self.interaction(execution_id)
async def interaction(self, execution_id: str) -> Interaction:
snapshot = await self._graph.aget_state(self._config(execution_id))
if not snapshot.values:
raise KeyError(f"Unknown Execution {execution_id}")
if snapshot.interrupts:
return Interaction(
execution_id,
"awaiting_user",
snapshot.interrupts[0].value,
snapshot.values,
)
return Interaction(
execution_id,
snapshot.values.get("status", "running"),
None,
snapshot.values,
)
@staticmethod
def _config(execution_id: str) -> RunnableConfig:
return {
"configurable": {"thread_id": execution_id},
"recursion_limit": _RECURSION_LIMIT,
}