"""The agent-runtime interface (ADR-0003). Everything an Orchestrator or Specialist needs crosses this seam as plain data: a RoleSpec, an AgentTask and ToolSpecs in; an Outcome back. No framework types. """ from __future__ import annotations import asyncio import contextvars from collections.abc import ( AsyncIterator, Awaitable, Callable, Mapping, MutableMapping, Sequence, ) from contextlib import asynccontextmanager from dataclasses import dataclass, field from typing import Any, Protocol @dataclass(frozen=True) class RoleSpec: """One agent role, parsed from agents/.md.""" name: str instructions: str budget: int skills: tuple[str, ...] = () tools: tuple[str, ...] = () # local tool names, e.g. terraform_validate mcp_servers: tuple[str, ...] = () model: str | None = None # Seconds one model request may take; None takes the runtime's default. model_timeout_seconds: float | None = None # A lighter model for the first attempt at a Deliverable, when the bundle # names one and model tiers are on (iteration 5 step 6). first_attempt_model: str | None = None # The Skill on published Terraform modules, for a role that may call them. It # is added to the role's Skills only in an Execution that opted into modules. modules_skill: str | None = None @dataclass(frozen=True) class AgentTask: """What one run of an agent is asked to do, with the context it may use.""" role: str prompt: str context: Mapping[str, Any] = field(default_factory=dict) deliverable: str | None = None # --- outcomes ---------------------------------------------------------------------- @dataclass(frozen=True) class Submitted: """A Specialist's contract-complete Deliverable.""" content: str attachments: Mapping[str, str] = field(default_factory=dict) @dataclass(frozen=True) class NeedsInput: """The agent can't continue without the user. `permission` names a tool tier to grant. `draft` is work the agent wants back when it is started again with the answers. """ questions: tuple[str, ...] permission: str | None = None draft: str | None = None draft_attachments: Mapping[str, str] = field(default_factory=dict) @dataclass(frozen=True) class BudgetExhausted: summary: str @dataclass(frozen=True) class Stopped: """The agent stopped without calling a tool that ends its turn.""" message: str @dataclass(frozen=True) class TurnEnded: """The Orchestrator ended its turn by calling `tool`; the tool recorded its effect.""" tool: str Outcome = Submitted | NeedsInput | BudgetExhausted | Stopped | TurnEnded # --- tools ------------------------------------------------------------------------- @dataclass(frozen=True) class ToolResult: """What a tool returns to the agent. A non-None `outcome` ends the agent's run.""" message: str outcome: Outcome | None = None # Files cross tool calls as a list of {path, content}, never a map keyed by path: # models rewrite object keys (Gemini turns "main.tf" into "main_tf"). FILES_SCHEMA: Mapping[str, Any] = { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Relative path, e.g. terraform/main.tf", }, "content": {"type": "string"}, }, "required": ["path", "content"], }, } def files_from_argument(value: Any) -> dict[str, str]: """A FILES_SCHEMA argument as {path: content}. A {path: content} map is accepted too.""" if not value: return {} if isinstance(value, Mapping): return {str(path): str(content) for path, content in value.items()} files: dict[str, str] = {} for item in value: if not isinstance(item, Mapping) or "path" not in item: raise TypeError("each file needs a 'path' and 'content'") files[str(item["path"])] = str(item.get("content", "")) return files @dataclass(frozen=True) class ToolSpec: name: str description: str parameters: Mapping[str, Any] # JSON schema for the keyword arguments handler: Callable[..., Awaitable[ToolResult]] tier: str = "general" # general | cloud_read | execution # The tools a role gets beyond the Execution tools, given the Deliverable it is producing # and that Deliverable's working memory: JSON-compatible data a tool may read and write, # kept with the Execution across attempts. ToolFactory = Callable[ [RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec] ] class RunLimiter: """Caps how many agent runs are in flight at once. A run that fans out to further runs lends its slot while it waits, so the cap holds across the whole hierarchy and a cap of 1 cannot deadlock. """ def __init__(self, limit: int) -> None: if limit < 1: raise ValueError("limit must be at least 1") self.limit = limit self._semaphore = asyncio.Semaphore(limit) self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar( "run_limiter_holding", default=False ) @asynccontextmanager async def slot(self) -> AsyncIterator[None]: async with self._semaphore: token = self._holding.set(True) try: yield finally: self._holding.reset(token) @asynccontextmanager async def lend(self) -> AsyncIterator[None]: """Give up the caller's slot, if it holds one, while its own fan-out runs.""" if not self._holding.get(): yield return self._semaphore.release() token = self._holding.set(False) try: yield finally: self._holding.reset(token) await self._semaphore.acquire() # Tool replies that mean the call did nothing. Runtimes log them, and the Execution # keeps them as lesson candidates. REJECTION_PREFIXES = ( "Not submitted", "Refused", "Discovery gap", "terraform validate failed", ) # --- decisions ----------------------------------------------------------------------- @dataclass(frozen=True) class Question: """A closed question about a state. Its answer is typed, never prose. choice pick one of `options` score rate against `options`, ordered from lowest to highest noul yes or no; the answer is the probability that it is yes """ kind: str # choice | score | noul instructions: str options: tuple[str, ...] = () @dataclass(frozen=True) class Answer: """`value` is the chosen option (choice), the level reached (score, as a number from 0 for the lowest option) or the probability of yes (noul).""" value: str | float confidence: float probabilities: Mapping[str, float] = field(default_factory=dict) def is_yes(self, threshold: float = 0.5) -> bool: return isinstance(self.value, (int, float)) and self.value >= threshold class Decider(Protocol): """Answers closed questions about a state (ADR-0007). Returns None when no decision could be made: the service is not configured, unreachable, over its budget, or the request is too large. The caller then takes its fallback; a decider never blocks an Execution. `scope` names what a budget is counted against, usually the Execution. """ async def decide( self, state: str, questions: Mapping[str, Question], *, scope: str = "" ) -> Mapping[str, Answer] | None: ... class NoDecider: """The decider when none is configured: every caller takes its fallback.""" async def decide( self, state: str, questions: Mapping[str, Question], *, scope: str = "" ) -> Mapping[str, Answer] | None: return None class SubmissionReview(Protocol): """A review of a submission's meaning, beyond what its structure shows. Returns what it would have the Specialist look at again, one line each; empty when it has nothing to raise or could not decide. `kind` is the Deliverable's kind, `upstream` the Deliverables it builds on. """ async def __call__( self, kind: Any, attachments: Mapping[str, str], upstream: Mapping[str, Mapping[str, Any]] | None, scope: str = "", ) -> Sequence[str]: ... class AgentRuntime(Protocol): async def run( self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec] ) -> Outcome: """Run one ReAct loop until a tool ends the turn, the budget is spent, or it stops.""" ...