"""The nodes of the Execution graph (ADR-0003); app/workflows/execution_graph.py wires them. 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 import dataclasses import json import logging import re import time from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence from dataclasses import dataclass from pathlib import Path from typing import Any from langgraph.types import Command, Send, interrupt from app.adk.runtime import ( REJECTION_PREFIXES, AgentRuntime, AgentTask, BudgetExhausted, NeedsInput, Outcome, RoleSpec, RunLimiter, Stopped, Submitted, ToolFactory, ToolSpec, TurnEnded, ) from app.customer_case import close_intent from app.nodes.router import ModelOrchestrator, OrchestratorPolicy, TurnView from app.recorder import ExecutionRecorder from app.states.execution_state import ( UNASSIGNED_CASE, ExecutionState, execution_dir, lessons_file, ) from app.states.ledger import DeliverableStatus, Ledger, LedgerRefusal from app.states.lessons import collect_lesson_candidates, refusal from app.tools import workspace from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools from app.workflows.chain import ( IMPLEMENTATION_FILE, VERDICTS_FILE, unimplementable_checks, validation_outcome, ) from app.workflows.deliverables import ( DEPENDENCY_GRAPH, PHASE_ORDER, DeliverableKind, dependencies_for, ) logger = logging.getLogger(__name__) 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" MANIFEST_FILENAME = "execution.json" # request, status and files of one Execution def _no_tools( role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any] ) -> Sequence[ToolSpec]: return () @dataclass(frozen=True) class ExecutionNodes: """The node functions of one Execution graph, bound to its runtime and recorder.""" orchestrator_turn: Callable[[ExecutionState], Awaitable[Command]] # Receives its Send payload, not the Execution state. specialist_task: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]] await_user: Callable[[ExecutionState], Awaitable[Command]] finalize: Callable[[ExecutionState], Awaitable[dict[str, Any]]] end_with_warnings: Callable[[ExecutionState], Awaitable[dict[str, Any]]] def make_execution_nodes( *, runtime: AgentRuntime, roles: Mapping[str, RoleSpec], recorder: ExecutionRecorder, output_root: Path, max_orchestrator_turns: int = 100, tool_factory: ToolFactory | None = None, limiter: RunLimiter | None = None, skill_versions: Mapping[str, str] | None = None, orchestrator: OrchestratorPolicy | None = None, ) -> ExecutionNodes: tool_factory = tool_factory or _no_tools # How an Orchestrator turn is decided. The default drives the tools from the # Orchestrator role on the runtime; the assembly supplies the router (ADR-0007). orchestrator = orchestrator or ModelOrchestrator(runtime, roles[ORCHESTRATOR]) def close(state: ExecutionState, status: str, *, has_files: bool) -> None: close_intent( output_root, _case(state), execution_id=state["execution_id"], status=status, has_files=has_files, ) async def record_lessons( state: ExecutionState, ledger: Ledger, status: str ) -> None: record = collect_lesson_candidates( execution_id=state["execution_id"], customer_case=_case(state), status=status, ledger=ledger, outcomes=state.get("outcomes", []), orchestrator_refusals=state.get("refusals", []), role_skills={name: role.skills for name, role in roles.items()}, skill_versions=skill_versions or {}, ) # Kept apart from deliverables/: an Execution that ends with warnings writes # no Deliverable files, but what went wrong in it is still worth keeping. path = lessons_file(output_root, state["execution_id"], _case(state)) path.parent.mkdir(parents=True, exist_ok=True) path.write_text( json.dumps(record, indent=2, ensure_ascii=False), encoding="utf-8" ) await recorder.record_lesson_candidates(state["execution_id"], record) async def record_progress( state: ExecutionState, ledger: Ledger, status: str | None = None ) -> int: recorded = state.get("events_recorded", 0) for event in ledger.events[recorded:]: logger.info( "[%s] ledger %s %s by %s%s", state["execution_id"], event.type, event.subject, event.actor, f" ({event.detail})" if event.detail else "", ) 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", []), "customer_case": _case(state), }, ) 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", [])) drafts = dict(state.get("drafts", {})) 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"], } drafts.pop(kind.value, None) 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 if record.get("draft"): drafts[kind.value] = { "content": record["draft"], "attachments": record.get("draft_attachments", {}), } 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, "drafts": drafts, "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) refusals = list(state.get("refusals", [])) update["refusals"] = refusals view = TurnView( execution_id=state["execution_id"], pre_approved=bool(state.get("pre_approved")), ledger=ledger, deliverables=deliverables, pending_questions=pending_questions, outcomes=outcomes, last_reply=state.get("last_reply"), pending_change=state.get("pending_change"), awaiting_gap_decision=bool(state.get("awaiting_gap_decision")), validation_settled=int(state.get("validation_settled", 0)), context=_orchestrator_context( state, ledger, deliverables, pending_questions, notes ), ) started = time.monotonic() decided = await orchestrator.turn( view, _noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None) ) outcome = decided.outcome update.update(decided.updates) if decided.decisions: # Every decision is kept: what was read, which group applied, what was done. update["decisions"] = [ *state.get("decisions", []), *({"turn": turns, **decision} for decision in decided.decisions), ] logger.info( "[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s", state["execution_id"], turns, _current_phase(ledger), time.monotonic() - started, _summarise_outcome(outcome), ) 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, drafts, 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"]) working: dict[str, Any] = dict(task_input.get("working") or {}) upstream = task_input["context"].get("dependencies") or {} source = DEPENDENCY_GRAPH[kind].working_copy if source and source is not kind: # The tools work on the files as they were last submitted. working[workspace.FILES] = dict( upstream.get(source.value, {}).get("attachments", {}) ) refusals: list[dict[str, Any]] = [] tools = _noting_refusals( specialist_tools( kind, extra=tool_factory(role, kind.value, working), allow_cloud_read=task_input["allow_cloud_read"], upstream=upstream, working=working, library=task_input.get("library"), ), refusals, role.name, kind.value, ) task = AgentTask( role=role.name, prompt=f"Produce the {kind} Deliverable.", context=task_input["context"], deliverable=kind.value, ) logger.info( "[%s] %s started %s (attempt %d)", task_input["execution_id"], role.name, kind, task_input["attempt"], ) started = time.monotonic() try: if limiter: async with limiter.slot(): outcome: Outcome = await runtime.run(role, task, tools) else: outcome = await runtime.run(role, task, tools) except Exception as exc: logger.exception("Specialist %s failed on %s", role.name, kind) outcome = Stopped(f"it failed with {type(exc).__name__}: {exc}") logger.info( "[%s] %s finished %s in %.0fs: %s", task_input["execution_id"], role.name, kind, time.monotonic() - started, _summarise_outcome(outcome), ) return { "outcomes": [ { **_outcome_record(role.name, kind, task_input["attempt"], outcome), "refusals": refusals, } ], "working": {kind.value: working}, } async def await_user(state: ExecutionState) -> Command: prompt = state["prompt"] or {} if state.get("pre_approved"): reply = automatic_reply(prompt, state.get("scripted_answers", [])) else: reply = interrupt(prompt) ledger = Ledger.from_dict(state["ledger"]) conversation = list(state.get("conversation", [])) update: dict[str, Any] = {"prompt": None} said: dict[str, Any] | None = None # what the user said, for the next turn 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}" said = {"kind": "changes", "phase": phase, "text": feedback} conversation.append({"from": "user", "text": text}) else: conversation.append({"from": "user", "text": _reply_text(reply)}) said = {"kind": "reply", "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}) said = {"kind": "reply", "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=[]) # Only a real user's words are routed; a pre-approved Execution has none. update["last_reply"] = None if state.get("pre_approved") else said 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, state) close(state, "completed", has_files=True) await record_progress(state, ledger, "completed") await record_lessons(state, ledger, "completed") return {"status": "completed"} async def end_with_warnings(state: ExecutionState) -> dict[str, Any]: ledger = Ledger.from_dict(state["ledger"]) close(state, "completed_with_warnings", has_files=False) await record_progress(state, ledger, "completed_with_warnings") await record_lessons(state, ledger, "completed_with_warnings") return {"status": "completed_with_warnings"} return ExecutionNodes( orchestrator_turn=orchestrator_turn, specialist_task=specialist_task, await_user=await_user, finalize=finalize, end_with_warnings=end_with_warnings, ) # --- helpers --------------------------------------------------------------------------- def _noting_refusals( tools: Sequence[ToolSpec], sink: list[dict[str, Any]], role: str, deliverable: str | None, ) -> list[ToolSpec]: """The same tools, noting each reply that means the call did nothing.""" def noting(tool: ToolSpec) -> ToolSpec: async def handler(**kwargs: Any) -> Any: result = await tool.handler(**kwargs) if result.outcome is None and result.message.startswith(REJECTION_PREFIXES): sink.append( refusal(role, deliverable, tool.name, tool.tier, result.message) ) return result return dataclasses.replace(tool, handler=handler) return [noting(tool) for tool in tools] def _summarise_outcome(outcome: Outcome) -> str: if isinstance(outcome, TurnEnded): return f"called {outcome.tool}" if isinstance(outcome, Submitted): return f"submitted ({len(outcome.content)} chars)" if isinstance(outcome, NeedsInput): return f"needs input ({len(outcome.questions)} questions)" if isinstance(outcome, BudgetExhausted): return f"budget exhausted: {outcome.summary[:200]}" return f"stopped: {outcome.message[:200]}" 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, deliverables: Mapping[str, Mapping[str, Any]], pending_questions: Sequence[Mapping[str, Any]], notes: Sequence[str], ) -> dict[str, Any]: # Only a validation that still stands: once anything it judged is reopened, its # verdicts are about work that no longer exists. validation = ( deliverables.get(DeliverableKind.VALIDATION_RESULTS.value) if ledger.status(DeliverableKind.VALIDATION_RESULTS) is DeliverableStatus.SUBMITTED else None ) code = DeliverableKind.DEPLOYMENT_GUIDANCE return { # Checks the code's author reported cannot be met as written: faults in the # Target architecture, known before any validation. "unimplementable_checks": unimplementable_checks( deliverables.get(code.value, {}) .get("attachments", {}) .get(IMPLEMENTATION_FILE, "") ) if ledger.status(code) is DeliverableStatus.SUBMITTED else [], # The verdict on each Check, once validation is submitted: failed Checks are # faults in the code; the rest are gaps in the Target architecture. "validation": validation_outcome( validation.get("attachments", {}).get(VERDICTS_FILE, "") ) if validation else None, "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]], drafts: Mapping[str, Mapping[str, Any]], kind: DeliverableKind, attempt: int, ) -> dict[str, Any]: spec = DEPENDENCY_GRAPH[kind] given = dependencies_for(kind, deliverables) return { "execution_id": state["execution_id"], # The Deliverables given as data files alone, whole, for reading on demand. "library": { name: dict(deliverables[name]) for name, deliverable in given.items() if "content" not in deliverable }, "role": spec.specialist, "kind": kind.value, "attempt": attempt, "allow_cloud_read": state.get("allow_cloud_read"), "working": dict(state.get("working", {}).get(kind.value, {})), "context": { "workflow_request": state["workflow_request"], "pre_approved": bool(state.get("pre_approved")), "contract": spec.contract(), "dependencies": given, "feedback": list(ledger.feedback(kind)), "answers": list(state.get("answers", {}).get(kind.value, [])), "draft": dict(drafts[kind.value]) if kind.value in drafts else None, # What the Specialist's own tools already hold from earlier attempts. "working_copy": workspace.summary( state.get("working", {}).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, "draft": outcome.draft, "draft_attachments": dict(outcome.draft_attachments), } 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], scripted_answers: Sequence[Sequence[str]] = () ) -> dict[str, Any]: """The reply in a pre-approved Execution: approve, deny cloud reads, and answer questions from scripted (pattern, answer) pairs where one matches.""" if "approval" in prompt: return { "approval": {"phase": prompt["approval"]["phase"], "decision": "approve"} } if "permission" in prompt: return {"permission": {prompt["permission"]["tier"]: False}} lines = [] unanswered = False for item in prompt.get("questions", []): answer = next( ( scripted for pattern, scripted in scripted_answers if re.search(pattern, item["question"], re.IGNORECASE) ), None, ) if answer is None: unanswered = True else: lines.append(f"Q: {item['question']}\nA: {answer}") if unanswered or not lines: lines.append(NO_USER_REPLY) return {"reply": "\n\n".join(lines)} 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 _case(state: ExecutionState) -> str: return state.get("customer_case") or UNASSIGNED_CASE def _write_outputs(output_root: Path, state: ExecutionState) -> None: """Write a finished Execution's files under its Customer case, with a manifest that ties the request to what was generated for it.""" customer_case = _case(state) execution_id = state["execution_id"] out_dir = execution_dir(output_root, execution_id, customer_case) deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {}) files: dict[str, str] = {} by_kind: dict[str, dict[str, Any]] = {} guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value) if guide: files[GUIDE_FILENAME] = guide["content"] for kind, deliverable in deliverables.items(): document = f"deliverables/{kind}.md" files[document] = deliverable["content"] attachments = dict(deliverable.get("attachments", {})) files.update(attachments) by_kind[kind] = {"document": document, "attachments": sorted(attachments)} for name, content in files.items(): path = out_dir / name path.parent.mkdir(parents=True, exist_ok=True) path.write_text(content, encoding="utf-8") manifest = { "customer_case": customer_case, "execution_id": execution_id, "session_id": state.get("session_id"), "intent_version": state.get("intent_version"), "workflow_request": state["workflow_request"], "status": "completed", "solution_guide": GUIDE_FILENAME if guide else None, "deliverables": by_kind, } out_dir.mkdir(parents=True, exist_ok=True) (out_dir / MANIFEST_FILENAME).write_text( json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8" )