Design is now approved before any infrastructure code is written (ADR-0005). A new target-architect Specialist produces one graph of Elements, Relationships and Checks; the diagram is rendered from it, deployment guidance must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations carry ids in data files, and a submission with a gap in the Requirements chain is refused. Also in this commit: - Customer cases group Executions, with an intent history per case - lesson candidates are captured when an Execution ends - evaluation gains chain, verdict, judged and interactive checks, and per-case thresholds - Terraform providers are cached between checks - the requirements analyst proposes defaults instead of asking - the legacy-baseline case and the checks that only read it are removed - ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed - plans for iterations 4 to 7 under .agents/plans/ Unproven with a real model: no evaluation run has completed on this design. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
209 lines
5.8 KiB
Python
209 lines
5.8 KiB
Python
"""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/<role>.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.
|
|
|
|
`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",
|
|
)
|
|
|
|
|
|
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."""
|
|
...
|