Increment 5 of .scratch/solution-architect-agent/spec.md, test-first. - agents/*.md: provider-neutral role files for the Orchestrator, nine Specialists and the pillar advisor, with a shared Specialist protocol. - app/agents/roles.py: load and validate role files; Skills, MCP servers and models come from the provider bundle. - app/agents/adk_runtime.py: AgentRuntime on google-adk 2.9 with a per-run LlmAgent, role-scoped SkillToolset (no run_skill_script), step budgets, early stop on turn-ending tools, LiteLLM models. - app/execution/pillars.py + toolkit.py: design advisor fans out to one advisor per WAF pillar in parallel. - Specialists receive every earlier-Phase Deliverable as input. - Bundle gains role_skills, pillar_skills and -latest Gemini aliases; pin google-adk[extensions]==2.9.0. - 37 new tests; full suite 158 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
484 lines
19 KiB
Python
484 lines
19 KiB
Python
"""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,
|
|
inputs_of,
|
|
)
|
|
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 inputs_of(kind)
|
|
},
|
|
"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")
|