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:
478
app/execution/graph.py
Normal file
478
app/execution/graph.py
Normal file
@@ -0,0 +1,478 @@
|
||||
"""The LangGraph that holds an Execution (ADR-0003).
|
||||
|
||||
START -> orchestrator_turn
|
||||
orchestrator_turn -> specialist_task x N (Send, parallel) -> orchestrator_turn
|
||||
orchestrator_turn -> await_user (interrupt) -> orchestrator_turn
|
||||
orchestrator_turn -> finalize -> END
|
||||
orchestrator_turn -> end_with_warnings -> END
|
||||
|
||||
Only orchestrator_turn and await_user change the Ledger; parallel Specialist tasks
|
||||
append outcomes that the next Orchestrator turn applies in order.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from pathlib import Path
|
||||
from typing import Any, cast
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
from langgraph.types import Command, Send, interrupt
|
||||
|
||||
from app.agents.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
NeedsInput,
|
||||
Outcome,
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
Submitted,
|
||||
ToolSpec,
|
||||
TurnEnded,
|
||||
)
|
||||
from app.execution.deliverables import DEPENDENCY_GRAPH, PHASE_ORDER, DeliverableKind
|
||||
from app.execution.ledger import Ledger, LedgerRefusal
|
||||
from app.execution.recorder import ExecutionRecorder
|
||||
from app.execution.state import ExecutionState
|
||||
from app.execution.tools import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
|
||||
|
||||
ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]]
|
||||
|
||||
NO_USER_REPLY = (
|
||||
"No user is available. State your assumption, record it in the Deliverable under "
|
||||
"'Assumptions', and proceed."
|
||||
)
|
||||
GUIDE_FILENAME = "solution-architecture-guide.md"
|
||||
|
||||
|
||||
def _no_tools(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
|
||||
return ()
|
||||
|
||||
|
||||
def build_execution_graph(
|
||||
*,
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
recorder: ExecutionRecorder,
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
) -> StateGraph:
|
||||
tool_factory = tool_factory or _no_tools
|
||||
|
||||
async def record_progress(
|
||||
state: ExecutionState, ledger: Ledger, status: str | None = None
|
||||
) -> int:
|
||||
recorded = state.get("events_recorded", 0)
|
||||
await recorder.record_events(state["execution_id"], ledger.events[recorded:])
|
||||
if status:
|
||||
await recorder.record_status(
|
||||
state["execution_id"],
|
||||
session_id=state["session_id"],
|
||||
workflow_request=state["workflow_request"],
|
||||
status=status,
|
||||
current_phase=_current_phase(ledger),
|
||||
details={
|
||||
"revisions": sum(
|
||||
ledger.revisions(kind) for kind in DEPENDENCY_GRAPH
|
||||
),
|
||||
"warnings": state.get("warnings", []),
|
||||
},
|
||||
)
|
||||
return len(ledger.events)
|
||||
|
||||
async def orchestrator_turn(state: ExecutionState) -> Command:
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
deliverables = dict(state.get("deliverables", {}))
|
||||
pending_questions = list(state.get("pending_questions", []))
|
||||
notes = list(state.get("notes", []))
|
||||
pending_permission = state.get("pending_permission")
|
||||
warnings = list(state.get("warnings", []))
|
||||
|
||||
outcomes = state.get("outcomes", [])
|
||||
for record in outcomes[state.get("outcomes_applied", 0) :]:
|
||||
kind = DeliverableKind(record["kind"])
|
||||
try:
|
||||
if record["type"] == "submitted":
|
||||
ledger.submit(kind, record["attempt"], actor=record["role"])
|
||||
deliverables[kind.value] = {
|
||||
"content": record["content"],
|
||||
"attachments": record["attachments"],
|
||||
}
|
||||
await recorder.record_submission(
|
||||
state["execution_id"],
|
||||
kind.value,
|
||||
record["content"],
|
||||
record["attachments"],
|
||||
)
|
||||
continue
|
||||
ledger.release(kind, record["attempt"], reason=record["type"])
|
||||
except LedgerRefusal as exc:
|
||||
notes.append(f"Discarded a superseded result for {kind}: {exc}")
|
||||
continue
|
||||
if record["type"] == "needs_input" and record.get("permission"):
|
||||
if state.get("allow_cloud_read") is None:
|
||||
requested = (pending_permission or {}).get("requested_by", [])
|
||||
pending_permission = {
|
||||
"tier": record["permission"],
|
||||
"requested_by": [*requested, kind.value],
|
||||
}
|
||||
continue
|
||||
questions = record.get("questions") or [
|
||||
(
|
||||
f"The {record['role']} stopped: {record['summary']} "
|
||||
"How should it proceed?"
|
||||
)
|
||||
]
|
||||
pending_questions.append({"kind": kind.value, "questions": questions})
|
||||
|
||||
turns = state.get("turns", 0) + 1
|
||||
update: dict[str, Any] = {
|
||||
"deliverables": deliverables,
|
||||
"pending_questions": pending_questions,
|
||||
"pending_permission": pending_permission,
|
||||
"outcomes_applied": len(outcomes),
|
||||
"turns": turns,
|
||||
}
|
||||
|
||||
def finish_with(goto: str, **extra: Any) -> Command:
|
||||
return Command(
|
||||
update={**update, "ledger": ledger.to_dict(), "notes": notes, **extra},
|
||||
goto=goto,
|
||||
)
|
||||
|
||||
if pending_permission and not state.get("pre_approved"):
|
||||
update["events_recorded"] = await record_progress(
|
||||
state, ledger, "awaiting_user"
|
||||
)
|
||||
return finish_with("await_user", prompt={"permission": pending_permission})
|
||||
|
||||
if turns > max_orchestrator_turns:
|
||||
warnings.append(
|
||||
f"Stopped after {max_orchestrator_turns} Orchestrator turns without "
|
||||
"finishing."
|
||||
)
|
||||
return finish_with("end_with_warnings", warnings=warnings)
|
||||
|
||||
toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions)
|
||||
task = AgentTask(
|
||||
role=ORCHESTRATOR,
|
||||
prompt="Decide the next step for this Execution using your tools.",
|
||||
context=_orchestrator_context(state, ledger, pending_questions, notes),
|
||||
)
|
||||
outcome = await runtime.run(roles[ORCHESTRATOR], task, toolbox.tools())
|
||||
notes = []
|
||||
pre_approved = bool(state.get("pre_approved"))
|
||||
conversation = list(state.get("conversation", []))
|
||||
|
||||
def ask(prompt: dict[str, Any], **extra: Any) -> Command:
|
||||
conversation.append({"from": ORCHESTRATOR, "text": _render_prompt(prompt)})
|
||||
return finish_with(
|
||||
"await_user", prompt=prompt, conversation=conversation, **extra
|
||||
)
|
||||
|
||||
if isinstance(outcome, TurnEnded) and outcome.tool == "delegate":
|
||||
sends = [
|
||||
Send(
|
||||
"specialist_task",
|
||||
_specialist_input(state, ledger, deliverables, kind, attempt),
|
||||
)
|
||||
for kind, attempt in toolbox.started.items()
|
||||
]
|
||||
update["events_recorded"] = await record_progress(state, ledger)
|
||||
return Command(
|
||||
update={**update, "ledger": ledger.to_dict(), "notes": notes},
|
||||
goto=sends,
|
||||
)
|
||||
|
||||
if isinstance(outcome, TurnEnded) and outcome.tool == "finish":
|
||||
update["events_recorded"] = await record_progress(state, ledger)
|
||||
return finish_with("finalize")
|
||||
|
||||
if isinstance(outcome, TurnEnded) and outcome.tool == "escalate":
|
||||
warnings.append(toolbox.escalation or "Escalated without detail.")
|
||||
update["events_recorded"] = await record_progress(state, ledger)
|
||||
return finish_with("end_with_warnings", warnings=warnings)
|
||||
|
||||
if isinstance(outcome, TurnEnded) and outcome.tool == "request_approval":
|
||||
update["events_recorded"] = await record_progress(
|
||||
state, ledger, None if pre_approved else "awaiting_user"
|
||||
)
|
||||
return ask({"approval": toolbox.approval})
|
||||
|
||||
if isinstance(outcome, TurnEnded) and outcome.tool == "ask_user":
|
||||
update["events_recorded"] = await record_progress(
|
||||
state, ledger, None if pre_approved else "awaiting_user"
|
||||
)
|
||||
return ask(
|
||||
{"questions": toolbox.questions},
|
||||
pending_questions=[],
|
||||
awaiting_questions=pending_questions,
|
||||
)
|
||||
|
||||
message = _describe_unfinished(outcome)
|
||||
if pre_approved:
|
||||
warnings.append(f"The Orchestrator could not continue: {message}")
|
||||
update["events_recorded"] = await record_progress(state, ledger)
|
||||
return finish_with("end_with_warnings", warnings=warnings)
|
||||
update["events_recorded"] = await record_progress(
|
||||
state, ledger, "awaiting_user"
|
||||
)
|
||||
return ask({"questions": [{"from": ORCHESTRATOR, "question": message}]})
|
||||
|
||||
async def specialist_task(task_input: dict[str, Any]) -> dict[str, Any]:
|
||||
role = roles[task_input["role"]]
|
||||
kind = DeliverableKind(task_input["kind"])
|
||||
tools = specialist_tools(
|
||||
kind,
|
||||
extra=tool_factory(role, kind.value),
|
||||
allow_cloud_read=task_input["allow_cloud_read"],
|
||||
)
|
||||
task = AgentTask(
|
||||
role=role.name,
|
||||
prompt=f"Produce the {kind} Deliverable.",
|
||||
context=task_input["context"],
|
||||
deliverable=kind.value,
|
||||
)
|
||||
outcome = await runtime.run(role, task, tools)
|
||||
return {
|
||||
"outcomes": [
|
||||
_outcome_record(role.name, kind, task_input["attempt"], outcome)
|
||||
]
|
||||
}
|
||||
|
||||
async def await_user(state: ExecutionState) -> Command:
|
||||
prompt = state["prompt"] or {}
|
||||
if state.get("pre_approved"):
|
||||
reply = _automatic_reply(prompt)
|
||||
else:
|
||||
reply = interrupt(prompt)
|
||||
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
conversation = list(state.get("conversation", []))
|
||||
update: dict[str, Any] = {"prompt": None}
|
||||
|
||||
if "approval" in prompt:
|
||||
phase = prompt["approval"]["phase"]
|
||||
decision = reply.get("approval") if isinstance(reply, Mapping) else None
|
||||
if (
|
||||
isinstance(decision, Mapping)
|
||||
and decision.get("phase") == phase
|
||||
and decision.get("decision") in {"approve", "changes"}
|
||||
):
|
||||
phase_id = next(p for p in PHASE_ORDER if p.value == phase)
|
||||
if decision["decision"] == "approve":
|
||||
ledger.approve(phase_id, actor="user")
|
||||
text = f"Approved {phase}."
|
||||
else:
|
||||
feedback = str(decision.get("feedback", ""))
|
||||
ledger.request_changes(phase_id, feedback, actor="user")
|
||||
text = f"Requested changes to {phase}: {feedback}"
|
||||
conversation.append({"from": "user", "text": text})
|
||||
else:
|
||||
conversation.append({"from": "user", "text": _reply_text(reply)})
|
||||
elif "permission" in prompt:
|
||||
tier = prompt["permission"]["tier"]
|
||||
permission = reply.get("permission") if isinstance(reply, Mapping) else None
|
||||
grant = permission.get(tier) if isinstance(permission, Mapping) else None
|
||||
if isinstance(grant, bool):
|
||||
update["allow_cloud_read"] = grant
|
||||
update["pending_permission"] = None
|
||||
verdict = "granted" if grant else "denied"
|
||||
conversation.append(
|
||||
{
|
||||
"from": "user",
|
||||
"text": f"Permission to use {tier} tools {verdict}.",
|
||||
}
|
||||
)
|
||||
else:
|
||||
conversation.append({"from": "user", "text": _reply_text(reply)})
|
||||
else:
|
||||
text = _reply_text(reply)
|
||||
conversation.append({"from": "user", "text": text})
|
||||
answers = {
|
||||
kind: list(items) for kind, items in state.get("answers", {}).items()
|
||||
}
|
||||
for asked in state.get("awaiting_questions", []):
|
||||
answers.setdefault(asked["kind"], []).append(
|
||||
{"questions": list(asked["questions"]), "reply": text}
|
||||
)
|
||||
update.update(answers=answers, awaiting_questions=[])
|
||||
|
||||
update["events_recorded"] = await record_progress(state, ledger)
|
||||
update.update(ledger=ledger.to_dict(), conversation=conversation)
|
||||
return Command(update=update, goto="orchestrator_turn")
|
||||
|
||||
async def finalize(state: ExecutionState) -> dict[str, Any]:
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
_write_outputs(
|
||||
output_root / "deliverables" / "executions" / state["execution_id"],
|
||||
state.get("deliverables", {}),
|
||||
)
|
||||
await record_progress(state, ledger, "completed")
|
||||
return {"status": "completed"}
|
||||
|
||||
async def end_with_warnings(state: ExecutionState) -> dict[str, Any]:
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
await record_progress(state, ledger, "completed_with_warnings")
|
||||
return {"status": "completed_with_warnings"}
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
graph.add_node("orchestrator_turn", orchestrator_turn)
|
||||
# Specialist tasks receive their Send payload, not the Execution state.
|
||||
graph.add_node("specialist_task", cast(Any, specialist_task))
|
||||
graph.add_node("await_user", await_user)
|
||||
graph.add_node("finalize", finalize)
|
||||
graph.add_node("end_with_warnings", end_with_warnings)
|
||||
graph.add_edge(START, "orchestrator_turn")
|
||||
graph.add_edge("specialist_task", "orchestrator_turn")
|
||||
graph.add_edge("finalize", END)
|
||||
graph.add_edge("end_with_warnings", END)
|
||||
return graph
|
||||
|
||||
|
||||
# --- helpers ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _current_phase(ledger: Ledger) -> str:
|
||||
for phase in PHASE_ORDER:
|
||||
if ledger.phase_status(phase).value != "approved":
|
||||
return phase.value
|
||||
return PHASE_ORDER[-1].value
|
||||
|
||||
|
||||
def _orchestrator_context(
|
||||
state: ExecutionState,
|
||||
ledger: Ledger,
|
||||
pending_questions: Sequence[Mapping[str, Any]],
|
||||
notes: Sequence[str],
|
||||
) -> dict[str, Any]:
|
||||
return {
|
||||
"workflow_request": state["workflow_request"],
|
||||
"pre_approved": bool(state.get("pre_approved")),
|
||||
"allow_cloud_read": state.get("allow_cloud_read"),
|
||||
"deliverables": {
|
||||
kind.value: {
|
||||
"phase": spec.phase.value,
|
||||
"status": ledger.status(kind).value,
|
||||
"revisions": ledger.revisions(kind),
|
||||
"feedback": list(ledger.feedback(kind)),
|
||||
}
|
||||
for kind, spec in DEPENDENCY_GRAPH.items()
|
||||
},
|
||||
"phases": {
|
||||
phase.value: ledger.phase_status(phase).value for phase in PHASE_ORDER
|
||||
},
|
||||
"ready_work": [kind.value for kind in ledger.ready_work()],
|
||||
"phases_ready_for_approval": [
|
||||
p.value for p in ledger.phases_ready_for_approval()
|
||||
],
|
||||
"pending_questions": list(pending_questions),
|
||||
"conversation": list(state.get("conversation", []))[-20:],
|
||||
"notes": list(notes),
|
||||
}
|
||||
|
||||
|
||||
def _specialist_input(
|
||||
state: ExecutionState,
|
||||
ledger: Ledger,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
kind: DeliverableKind,
|
||||
attempt: int,
|
||||
) -> dict[str, Any]:
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
return {
|
||||
"role": spec.specialist,
|
||||
"kind": kind.value,
|
||||
"attempt": attempt,
|
||||
"allow_cloud_read": state.get("allow_cloud_read"),
|
||||
"context": {
|
||||
"workflow_request": state["workflow_request"],
|
||||
"pre_approved": bool(state.get("pre_approved")),
|
||||
"dependencies": {
|
||||
dependency.value: dict(deliverables[dependency.value])
|
||||
for dependency in spec.depends_on
|
||||
},
|
||||
"feedback": list(ledger.feedback(kind)),
|
||||
"answers": list(state.get("answers", {}).get(kind.value, [])),
|
||||
"attempt": attempt,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def _outcome_record(
|
||||
role: str, kind: DeliverableKind, attempt: int, outcome: Outcome
|
||||
) -> dict[str, Any]:
|
||||
base = {"role": role, "kind": kind.value, "attempt": attempt}
|
||||
if isinstance(outcome, Submitted):
|
||||
return {
|
||||
**base,
|
||||
"type": "submitted",
|
||||
"content": outcome.content,
|
||||
"attachments": dict(outcome.attachments),
|
||||
}
|
||||
if isinstance(outcome, NeedsInput):
|
||||
return {
|
||||
**base,
|
||||
"type": "needs_input",
|
||||
"questions": list(outcome.questions),
|
||||
"permission": outcome.permission,
|
||||
}
|
||||
if isinstance(outcome, BudgetExhausted):
|
||||
return {**base, "type": "budget_exhausted", "summary": outcome.summary}
|
||||
return {**base, "type": "stopped", "summary": _describe_unfinished(outcome)}
|
||||
|
||||
|
||||
def _describe_unfinished(outcome: Outcome) -> str:
|
||||
if isinstance(outcome, BudgetExhausted):
|
||||
return f"I paused: {outcome.summary} How should I proceed?"
|
||||
if isinstance(outcome, Stopped):
|
||||
return outcome.message
|
||||
if isinstance(outcome, NeedsInput):
|
||||
return " ".join(outcome.questions)
|
||||
return f"Ended with an unexpected outcome: {type(outcome).__name__}."
|
||||
|
||||
|
||||
def _automatic_reply(prompt: Mapping[str, Any]) -> dict[str, Any]:
|
||||
if "approval" in prompt:
|
||||
return {
|
||||
"approval": {"phase": prompt["approval"]["phase"], "decision": "approve"}
|
||||
}
|
||||
if "permission" in prompt:
|
||||
return {"permission": {prompt["permission"]["tier"]: False}}
|
||||
return {"reply": NO_USER_REPLY}
|
||||
|
||||
|
||||
def _reply_text(reply: object) -> str:
|
||||
if isinstance(reply, str):
|
||||
return reply
|
||||
if isinstance(reply, Mapping) and isinstance(reply.get("reply"), str):
|
||||
return reply["reply"]
|
||||
return str(reply)
|
||||
|
||||
|
||||
def _render_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
if "approval" in prompt:
|
||||
approval = prompt["approval"]
|
||||
return f"Please approve {approval['phase']}: {approval['summary']}"
|
||||
if "permission" in prompt:
|
||||
return f"May I use {prompt['permission']['tier']} tools?"
|
||||
return "\n".join(item["question"] for item in prompt.get("questions", []))
|
||||
|
||||
|
||||
def _write_outputs(
|
||||
out_dir: Path, deliverables: Mapping[str, Mapping[str, Any]]
|
||||
) -> None:
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value)
|
||||
if guide:
|
||||
(out_dir / GUIDE_FILENAME).write_text(guide["content"], encoding="utf-8")
|
||||
for kind, deliverable in deliverables.items():
|
||||
path = out_dir / "deliverables" / f"{kind}.md"
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(deliverable["content"], encoding="utf-8")
|
||||
for name, content in deliverable.get("attachments", {}).items():
|
||||
attachment = out_dir / name
|
||||
attachment.parent.mkdir(parents=True, exist_ok=True)
|
||||
attachment.write_text(content, encoding="utf-8")
|
||||
Reference in New Issue
Block a user