"""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 from collections.abc import Awaitable, Callable, Mapping, Sequence 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 @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.""" questions: tuple[str, ...] permission: str | None = None @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. ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]] 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.""" ...