"""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, execution_id: str | None = None, ) -> Interaction: execution_id = execution_id or str(uuid.uuid4()) if await self._exists(execution_id): raise ValueError(f"Execution {execution_id} already exists") 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, ) async def _exists(self, execution_id: str) -> bool: snapshot = await self._graph.aget_state(self._config(execution_id)) return bool(snapshot.values) @staticmethod def _config(execution_id: str) -> RunnableConfig: return { "configurable": {"thread_id": execution_id}, "recursion_limit": _RECURSION_LIMIT, }