"""The agent: the ExecutionEngine that starts and resumes Executions, and its assembly. ExecutionEngine is 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. open_assembly is the composition root: the only place concrete runtimes, tools, checkpointers and recorders are chosen, from settings and the provider bundle. """ from __future__ import annotations import uuid from collections.abc import Mapping, Sequence 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.core.deliverables import DEPENDENCY_GRAPH, NO_CONTRACT, ProviderContract from app.core.ledger import Ledger from app.core.scope import ESSENTIAL, Catalogue, Scope, read_scope, slug from app.engine.baseline import load_baseline from app.engine.customer_case import record_intent from app.engine.execution_graph import build_execution_graph from app.engine.execution_state import check_customer_case from app.engine.recorder import ExecutionRecorder, InMemoryRecorder from app.engine.router import OrchestratorPolicy from app.engine.runtime import ( AgentRuntime, Decider, RoleSpec, RunLimiter, SubmissionReview, ToolFactory, ) from app.engine.scoping import Scoping, to_working from app.engine.toolbox import ORCHESTRATOR @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] _RECURSION_LIMIT = 10_000 # loops are bounded by max_orchestrator_turns instead AGENTS_DIR = Path(__file__).resolve().parent.parent.parent / "prompts" 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, limiter: RunLimiter | None = None, skill_versions: Mapping[str, str] | None = None, orchestrator: OrchestratorPolicy | None = None, submission_review: SubmissionReview | None = None, confirm_drafts: bool = False, decider: Decider | None = None, pillar_threshold: float = 1.5, reworded_threshold: float = 0.25, overlays: Mapping[str, str] | None = None, default_overlays: Sequence[str] = (), guard_user_text: bool = False, guard_threshold: float = 0.75, skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None, skill_threshold: float = 1.25, assess_at_end: bool = False, modules_available: bool = False, default_modules: bool = False, scope_catalogue: Catalogue | None = None, scope_values: Mapping[str, Sequence[str]] | None = None, scope_skill: str | None = None, contract: ProviderContract = NO_CONTRACT, ) -> 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 # The catalogue a scope spec is read against (ADR-0008); None when this # deployment's Cloud provider has none. self._scope_catalogue = scope_catalogue self._scope_values = dict(scope_values or {}) self._scope_skill = scope_skill # Whether the Cloud provider approves any module sources, and whether an # Execution uses them when its caller does not say. self._modules_available = modules_available self._default_modules = default_modules and modules_available self._output_root = output_root # Overlay Skills an Execution may name, with the version of each (ADR-0004). self._overlays = dict(overlays or {}) self._default_overlays = tuple(default_overlays) unknown = sorted(set(self._default_overlays) - set(self._overlays)) if unknown: raise ValueError(f"Unknown default overlay Skills: {', '.join(unknown)}") 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, limiter=limiter, skill_versions=skill_versions, orchestrator=orchestrator, submission_review=submission_review, confirm_drafts=confirm_drafts, decider=decider, pillar_threshold=pillar_threshold, reworded_threshold=reworded_threshold, guard_user_text=guard_user_text, guard_threshold=guard_threshold, skill_references=skill_references, skill_threshold=skill_threshold, assess_at_end=assess_at_end, scoping=Scoping(scope_catalogue, dict(scope_values or {}), scope_skill) if scope_catalogue is not None else None, contract=contract, ).compile(checkpointer=checkpointer) async def start( self, workflow_request: str, *, session_id: str | None = None, customer_case: str | None = None, pre_approved: bool | None = None, allow_cloud_read: bool | None = None, execution_id: str | None = None, scripted_answers: Sequence[Sequence[str]] = (), baseline: str | None = None, overlay_skills: Sequence[str] = (), terraform_modules: bool | None = None, scope: str | Mapping[str, Any] | None = None, time_left: Any = None, ) -> Interaction: """Start an Execution. `scripted_answers` are (regex, answer[, asker]) entries a pre-approved Execution uses to answer questions, for evaluation runs. `baseline` names a completed Execution of the same Customer case and makes this a Change request (ADR-0006): the request says what has changed, and the Execution starts from that Baseline's Deliverables. It is refused, before anything runs or is recorded, when the Baseline cannot be one. `overlay_skills` names Skills that carry an organisation's standards or this engagement's constraints. Each must be one the deployment has configured; an unknown name refuses the start. Every Specialist loads them with the ones the deployment loads by default. `terraform_modules` opts the Execution into published Terraform modules from the sources the Cloud provider approves. Left unset, a Change request does as its Baseline did and any other Execution takes the deployment's default, which is plain resources. Opting in is refused when the provider approves no sources. `scope` is a scope spec (ADR-0008), as YAML text or already parsed. It may be complete or partly filled. The start is refused when it names a field the catalogue does not have or holds a value of the wrong type, and, for a pre-approved Execution, when an essential field is not settled: nobody is there to ask. What the spec states under `run` applies where the caller gave no value of their own. Its statement of intent is the request when none is given. """ read = self._read_scope(scope) if scope is not None else None if read is not None: run = read.values if pre_approved is None: pre_approved = bool(run.get("run.pre_approved", False)) if allow_cloud_read is None and "run.allow_cloud_read" in run: allow_cloud_read = bool(run["run.allow_cloud_read"]) if terraform_modules is None and "run.terraform_modules" in run: terraform_modules = bool(run["run.terraform_modules"]) overlay_skills = [*overlay_skills, *run.get("run.overlay_skills", [])] if ( customer_case and read.customer_case and slug(customer_case) != (read.customer_case) ): raise ValueError( f"The scope spec is for {read.customer_case}, and this was " f"started for {customer_case}." ) customer_case = customer_case or read.customer_case # The spec's statement is the customer's; it is what gets recorded. workflow_request = read.statement or workflow_request missing = read.gaps(ESSENTIAL) if pre_approved and missing: raise ValueError( "The scope spec leaves essential fields unsettled, and a " "pre-approved Execution has nobody to ask: " + ", ".join(gap["field"] for gap in missing) + ". Give each a value, or `decide` to leave it to the agent." ) pre_approved = bool(pre_approved) if not workflow_request.strip(): raise ValueError( "A request is needed: text, or a scope spec with a statement." ) customer_case = check_customer_case(customer_case) execution_id = execution_id or str(uuid.uuid4()) if await self._exists(execution_id): raise ValueError(f"Execution {execution_id} already exists") if isinstance(overlay_skills, str) or not all( isinstance(name, str) for name in overlay_skills ): raise ValueError("overlay_skills must be a list of Skill names") chosen = list(dict.fromkeys([*self._default_overlays, *overlay_skills])) unknown = sorted(set(chosen) - set(self._overlays)) if unknown: raise ValueError( f"Unknown overlay Skills: {', '.join(unknown)}. Available: " f"{', '.join(sorted(self._overlays)) or 'none'}" ) loaded = ( load_baseline(self._output_root, customer_case, baseline) if baseline else None ) if terraform_modules is None: terraform_modules = ( bool(loaded.get("terraform_modules")) if loaded else self._default_modules ) if not isinstance(terraform_modules, bool): # A ValueError is what callers turn into a refused start. raise ValueError("terraform_modules must be true or false") # noqa: TRY004 if terraform_modules and not self._modules_available: raise ValueError( "terraform_modules: this Cloud provider has no approved module sources" ) if pre_approved and allow_cloud_read is None: allow_cloud_read = False session_id = session_id or str(uuid.uuid4()) intent_version = record_intent( self._output_root, customer_case, execution_id=execution_id, session_id=session_id, workflow_request=workflow_request, baseline=baseline or None, scope_supplied=scope if isinstance(scope, str) else None, scope_completed=read.completed(read.status(pre_approved)) if read else None, ) initial: dict[str, Any] = { "execution_id": execution_id, "session_id": session_id, "customer_case": customer_case, "intent_version": intent_version, "workflow_request": workflow_request, # The Baseline of a Change request, as read from its files; else None. "baseline": loaded, # Overlay Skills this Execution loads, each with the version it had. "overlay_skills": {name: self._overlays[name] for name in chosen}, "terraform_modules": terraform_modules, # What the customer's scope spec settles and leaves open; None without one. "scope": { "skill": self._scope_skill, "status": read.status(pre_approved), "readiness": read.readiness(), "context": read.for_context(), # What the scope analyst starts from and completes. "working": to_working(read), } if read else None, "risks": [], "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": {}, "drafts": {}, "drafts_shown": [], "working": {}, "pending_permission": None, "prompt": None, "last_reply": None, "pending_change": None, "awaiting_gap_decision": False, "validation_settled": 0, "awaiting_limit_decision": False, "revision_limit_asked": [], "idle_asks": 0, "ask_fingerprint": "", "decisions": [], "outcomes": [], "refusals": [], "outcomes_applied": 0, "events_recorded": 0, "turns": 0, "status": "running", "warnings": [], "scripted_answers": [list(entry) for entry in scripted_answers], } await self._advance(initial, execution_id, time_left) return await self.interaction(execution_id) def _read_scope(self, supplied: str | Mapping[str, Any]) -> Scope: if self._scope_catalogue is None: raise ValueError("This deployment has no scope spec catalogue.") return read_scope( supplied, self._scope_catalogue, provider_values=self._scope_values ) async def resume( self, execution_id: str, reply: Mapping[str, Any], time_left: Any = None ) -> 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._advance(Command(resume=dict(reply)), execution_id, time_left) return await self.interaction(execution_id) async def carry_on(self, execution_id: str, time_left: Any = None) -> Interaction: """Carry on with an Execution a request left between two steps.""" current = await self.interaction(execution_id) if current.status == "running": await self._advance(None, execution_id, time_left) return await self.interaction(execution_id) async def _advance(self, given: Any, execution_id: str, time_left: Any) -> None: """Run the graph. With `time_left`, stop between two steps once it reaches zero, so the runtime's limit never cuts a step off: every finished step is checkpointed, and `carry_on` continues from there.""" async for _ in self._graph.astream( given, self._config(execution_id), stream_mode="updates", durability="sync" ): if time_left is not None and time_left() <= 0: break 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, }