fixed multile issues
Some checks failed
validation / verify (push) Failing after 8s

This commit is contained in:
2026-10-07 17:33:36 +01:00
parent 4c4d44ef87
commit 5bb22d984e
76 changed files with 5799 additions and 179 deletions

View File

@@ -238,7 +238,7 @@ class AdkAgentRuntime:
instruction=lambda _context: instructions,
tools=agent_tools,
before_tool_callback=control.before_tool,
generate_content_config=self._content_config(),
generate_content_config=self._content_config(role),
)
runner = Runner(
app_name=APP_NAME,
@@ -293,13 +293,13 @@ class AdkAgentRuntime:
or f"{role.name} ended without calling a tool that ends its turn."
)
def _content_config(self) -> types.GenerateContentConfig | None:
if self._model_timeout_seconds is None:
def _content_config(self, role: RoleSpec) -> types.GenerateContentConfig | None:
# A role whose replies are long is given longer than the default.
seconds = role.model_timeout_seconds or self._model_timeout_seconds
if seconds is None:
return None
return types.GenerateContentConfig(
http_options=types.HttpOptions(
timeout=int(self._model_timeout_seconds * 1000)
)
http_options=types.HttpOptions(timeout=int(seconds * 1000))
)

View File

@@ -15,8 +15,10 @@ from typing import Any
from app.adk.runtime import (
AgentTask,
Answer,
BudgetExhausted,
Outcome,
Question,
RoleSpec,
Stopped,
ToolSpec,
@@ -180,3 +182,27 @@ class FakeAgentRuntime:
RunRecord(role.name, task, tuple(by_name), tuple(results), outcome)
)
return outcome
class FakeDecider:
"""A scripted Decider: answers by question id, or declines so callers fall back.
`answers` maps a question id to an Answer, or to a function of (state, question)
returning one. An id with no entry makes the whole decision unavailable.
"""
def __init__(self, answers: Mapping[str, Any] | None = None) -> None:
self.answers = dict(answers or {})
self.asked: list[tuple[str, dict[str, Question], str]] = []
async def decide(
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
) -> Mapping[str, Answer] | None:
self.asked.append((state, dict(questions), scope))
decided = {}
for name, question in questions.items():
if name not in self.answers:
return None
answer = self.answers[name]
decided[name] = answer(state, question) if callable(answer) else answer
return decided

View File

@@ -16,6 +16,7 @@ from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
ORCHESTRATOR = "orchestrator"
PILLAR_ADVISOR = "pillar-advisor"
REPLY_WRITER = "reply-writer"
PARTIALS_DIR = "partials"
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
@@ -34,7 +35,7 @@ def load_roles(
include_preview_mcp: bool = True,
) -> dict[str, RoleSpec]:
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
required = {ORCHESTRATOR, PILLAR_ADVISOR, *specialists}
required = {ORCHESTRATOR, PILLAR_ADVISOR, REPLY_WRITER, *specialists}
roles = {}
for path in sorted(agents_dir.glob("*.md")):
@@ -129,4 +130,5 @@ def _load_role(
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
),
model=bundle.models.for_role(name),
model_timeout_seconds=bundle.models.timeout_for(name),
)

View File

@@ -32,6 +32,8 @@ class RoleSpec:
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
@dataclass(frozen=True)
@@ -200,6 +202,59 @@ REJECTION_PREFIXES = (
)
# --- 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 AgentRuntime(Protocol):
async def run(
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]

View File

@@ -10,10 +10,11 @@ checkpointers and recorders are chosen, from settings and the provider bundle.
from __future__ import annotations
import dataclasses
import uuid
from collections.abc import AsyncIterator, Mapping, Sequence
from contextlib import asynccontextmanager
from dataclasses import dataclass
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
@@ -22,16 +23,31 @@ from langgraph.checkpoint.base import BaseCheckpointSaver
from langgraph.types import Command
from app.adk.roles import load_roles
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
from app.adk.runtime import (
AgentRuntime,
Decider,
NoDecider,
RoleSpec,
RunLimiter,
ToolFactory,
)
from app.checkpointing import open_checkpointer
from app.config import Settings
from app.customer_case import record_intent
from app.nodes.router import (
REPLY_WRITER,
OrchestratorPolicy,
Router,
RuntimeReplyWriter,
Thresholds,
)
from app.providers import ProviderBundle, load_provider
from app.recorder import DatabaseRecorder, ExecutionRecorder
from app.skills.agent_skills import skill_version
from app.states.execution_state import check_customer_case
from app.states.ledger import Ledger
from app.tools.execution import ORCHESTRATOR
from app.tools.jev import JevDecider, JevLimits
from app.tools.local import TerraformRunner, local_tools
from app.tools.mcp import McpCatalog, auth_from_config
from app.tools.toolkit import make_tool_factory
@@ -67,6 +83,7 @@ class ExecutionEngine:
tool_factory: ToolFactory | None = None,
limiter: RunLimiter | None = None,
skill_versions: Mapping[str, str] | None = None,
orchestrator: OrchestratorPolicy | None = None,
) -> None:
required = {
ORCHESTRATOR,
@@ -86,6 +103,7 @@ class ExecutionEngine:
tool_factory=tool_factory,
limiter=limiter,
skill_versions=skill_versions,
orchestrator=orchestrator,
).compile(checkpointer=checkpointer)
async def start(
@@ -136,6 +154,11 @@ class ExecutionEngine:
"working": {},
"pending_permission": None,
"prompt": None,
"last_reply": None,
"pending_change": None,
"awaiting_gap_decision": False,
"validation_settled": 0,
"decisions": [],
"outcomes": [],
"refusals": [],
"outcomes_applied": 0,
@@ -203,6 +226,27 @@ class Assembly:
bundle: ProviderBundle
roles: dict[str, RoleSpec]
mcp_gaps: dict[str, str]
decider: Decider = field(default_factory=NoDecider)
def open_decider(settings: Settings) -> Decider:
"""The Jev client when a key is configured; otherwise a decider that always
sends its caller to the fallback."""
if not settings.TYPESAFE_API_KEY:
return NoDecider()
return JevDecider(
api_key=settings.TYPESAFE_API_KEY,
base_url=settings.TYPESAFE_BASE_URL,
model=settings.TYPESAFE_DEFAULT_MODEL,
limits=dataclasses.replace(
JevLimits(),
request_timeout=settings.JEV_TIMEOUT_SECONDS,
requests_per_second=settings.JEV_REQUESTS_PER_SECOND,
max_in_flight=settings.JEV_MAX_IN_FLIGHT,
budget_calls=settings.JEV_BUDGET_CALLS,
budget_tokens=settings.JEV_BUDGET_TOKENS,
),
)
@asynccontextmanager
@@ -242,6 +286,7 @@ async def open_assembly(
binary=settings.TERRAFORM_BINARY,
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
plugin_cache_dir=settings.terraform_plugin_cache(),
providers=bundle.terraform_providers,
)
offered = [name for names in bundle.tools.values() for name in names]
# One cap for Specialists and the pillar advisors they fan out to.
@@ -250,11 +295,30 @@ async def open_assembly(
runtime,
roles,
bundle.pillar_skills,
local_tools=local_tools(offered, runner),
local_tools=lambda working_copy: local_tools(offered, runner, working_copy),
catalog=catalog,
limiter=limiter,
)
decider = open_decider(settings)
orchestrator: OrchestratorPolicy | None = None
if settings.ORCHESTRATOR == "router":
# The Orchestrator routes: Jev reads, the playbook decides, and a model only
# writes what the user reads. With no Jev key the playbook runs on its rules.
orchestrator = Router(
decider,
RuntimeReplyWriter(runtime, roles[REPLY_WRITER]),
Thresholds(
act=settings.JEV_ACT_THRESHOLD,
close=settings.JEV_CLOSE_THRESHOLD,
confidence=settings.JEV_CONFIDENCE_THRESHOLD,
),
)
elif settings.ORCHESTRATOR != "model":
raise ValueError(
f"ORCHESTRATOR must be router or model, not {settings.ORCHESTRATOR!r}"
)
async with open_checkpointer(settings) as checkpointer:
engine = ExecutionEngine(
runtime=runtime,
@@ -269,5 +333,10 @@ async def open_assembly(
skill_versions={
name: skill_version(meta.path) for name, meta in bundle.skills.items()
},
orchestrator=orchestrator,
)
yield Assembly(engine, bundle, roles, dict(catalog.gaps))
try:
yield Assembly(engine, bundle, roles, dict(catalog.gaps), decider)
finally:
if isinstance(decider, JevDecider):
await decider.aclose()

View File

@@ -53,11 +53,33 @@ class Settings(BaseSettings):
SPECIALIST_BUDGET: int = 15
MAX_REVISIONS: int = 3
MAX_ORCHESTRATOR_TURNS: int = 100
# How an Orchestrator turn is decided (ADR-0007): "router" reads the Execution
# and follows its playbook, with Jev for the judgements; "model" has a language
# model choose the tool calls, as before, and is kept for comparison.
ORCHESTRATOR: str = "router"
# Agent runs in flight at once, pillar advisors included (model rate limits)
MAX_PARALLEL_SPECIALISTS: int = 4
CHECKPOINTER: str = "sqlite" # memory | sqlite | postgres
CHECKPOINT_DB_PATH: str = "checkpoints.db"
# Jev decision service (ADR-0007), reached through TypeSafe AI's Python SDK.
# With no key, every decision takes its fallback and the agent behaves as it does
# without Jev. The key comes from the environment or a secret store, never from
# the provider bundle or the repository.
TYPESAFE_API_KEY: str | None = None
TYPESAFE_BASE_URL: str | None = None # None: the SDK's default endpoint
TYPESAFE_DEFAULT_MODEL: str | None = None # None: the SDK's default model
JEV_TIMEOUT_SECONDS: float = 5.0 # one request
JEV_REQUESTS_PER_SECOND: float = 5.0
JEV_MAX_IN_FLIGHT: int = 8
JEV_BUDGET_CALLS: int = 500 # per Execution
JEV_BUDGET_TOKENS: int = 1_000_000 # per Execution
# A probability at or above ACT is acted on; at or below CLOSE is dropped; in
# between, the user is asked. A choice below CONFIDENCE is not relied on.
JEV_ACT_THRESHOLD: float = 0.75
JEV_CLOSE_THRESHOLD: float = 0.15
JEV_CONFIDENCE_THRESHOLD: float = 0.6
# Paths
BASE_DIR: Path = Path(__file__).resolve().parent.parent

View File

@@ -34,6 +34,7 @@ from app.adk.runtime import (
TurnEnded,
)
from app.customer_case import close_intent
from app.nodes.router import ModelOrchestrator, OrchestratorPolicy, TurnView
from app.recorder import ExecutionRecorder
from app.states.execution_state import (
UNASSIGNED_CASE,
@@ -43,13 +44,19 @@ from app.states.execution_state import (
)
from app.states.ledger import DeliverableStatus, Ledger, LedgerRefusal
from app.states.lessons import collect_lesson_candidates, refusal
from app.tools import workspace
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
from app.workflows.chain import VERDICTS_FILE, validation_outcome
from app.workflows.chain import (
IMPLEMENTATION_FILE,
VERDICTS_FILE,
unimplementable_checks,
validation_outcome,
)
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
PHASE_ORDER,
DeliverableKind,
inputs_of,
dependencies_for,
)
logger = logging.getLogger(__name__)
@@ -90,8 +97,12 @@ def make_execution_nodes(
tool_factory: ToolFactory | None = None,
limiter: RunLimiter | None = None,
skill_versions: Mapping[str, str] | None = None,
orchestrator: OrchestratorPolicy | None = None,
) -> ExecutionNodes:
tool_factory = tool_factory or _no_tools
# How an Orchestrator turn is decided. The default drives the tools from the
# Orchestrator role on the runtime; the assembly supplies the router (ADR-0007).
orchestrator = orchestrator or ModelOrchestrator(runtime, roles[ORCHESTRATOR])
def close(state: ExecutionState, status: str, *, has_files: bool) -> None:
close_intent(
@@ -239,19 +250,33 @@ def make_execution_nodes(
toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions)
refusals = list(state.get("refusals", []))
update["refusals"] = refusals
task = AgentTask(
role=ORCHESTRATOR,
prompt="Decide the next step for this Execution using your tools.",
view = TurnView(
execution_id=state["execution_id"],
pre_approved=bool(state.get("pre_approved")),
ledger=ledger,
deliverables=deliverables,
pending_questions=pending_questions,
outcomes=outcomes,
last_reply=state.get("last_reply"),
pending_change=state.get("pending_change"),
awaiting_gap_decision=bool(state.get("awaiting_gap_decision")),
validation_settled=int(state.get("validation_settled", 0)),
context=_orchestrator_context(
state, ledger, deliverables, pending_questions, notes
),
)
started = time.monotonic()
outcome = await runtime.run(
roles[ORCHESTRATOR],
task,
_noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None),
decided = await orchestrator.turn(
view, _noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None)
)
outcome = decided.outcome
update.update(decided.updates)
if decided.decisions:
# Every decision is kept: what was read, which group applied, what was done.
update["decisions"] = [
*state.get("decisions", []),
*({"turn": turns, **decision} for decision in decided.decisions),
]
logger.info(
"[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s",
state["execution_id"],
@@ -325,13 +350,22 @@ def make_execution_nodes(
role = roles[task_input["role"]]
kind = DeliverableKind(task_input["kind"])
working: dict[str, Any] = dict(task_input.get("working") or {})
upstream = task_input["context"].get("dependencies") or {}
source = DEPENDENCY_GRAPH[kind].working_copy
if source and source is not kind:
# The tools work on the files as they were last submitted.
working[workspace.FILES] = dict(
upstream.get(source.value, {}).get("attachments", {})
)
refusals: list[dict[str, Any]] = []
tools = _noting_refusals(
specialist_tools(
kind,
extra=tool_factory(role, kind.value, working),
allow_cloud_read=task_input["allow_cloud_read"],
upstream=task_input["context"].get("dependencies"),
upstream=upstream,
working=working,
library=task_input.get("library"),
),
refusals,
role.name,
@@ -388,6 +422,7 @@ def make_execution_nodes(
ledger = Ledger.from_dict(state["ledger"])
conversation = list(state.get("conversation", []))
update: dict[str, Any] = {"prompt": None}
said: dict[str, Any] | None = None # what the user said, for the next turn
if "approval" in prompt:
phase = prompt["approval"]["phase"]
@@ -405,9 +440,11 @@ def make_execution_nodes(
feedback = str(decision.get("feedback", ""))
ledger.request_changes(phase_id, feedback, actor="user")
text = f"Requested changes to {phase}: {feedback}"
said = {"kind": "changes", "phase": phase, "text": feedback}
conversation.append({"from": "user", "text": text})
else:
conversation.append({"from": "user", "text": _reply_text(reply)})
said = {"kind": "reply", "text": _reply_text(reply)}
elif "permission" in prompt:
tier = prompt["permission"]["tier"]
permission = reply.get("permission") if isinstance(reply, Mapping) else None
@@ -427,6 +464,7 @@ def make_execution_nodes(
else:
text = _reply_text(reply)
conversation.append({"from": "user", "text": text})
said = {"kind": "reply", "text": text}
answers = {
kind: list(items) for kind, items in state.get("answers", {}).items()
}
@@ -436,6 +474,8 @@ def make_execution_nodes(
)
update.update(answers=answers, awaiting_questions=[])
# Only a real user's words are routed; a pre-approved Execution has none.
update["last_reply"] = None if state.get("pre_approved") else said
update["events_recorded"] = await record_progress(state, ledger)
update.update(ledger=ledger.to_dict(), conversation=conversation)
return Command(update=update, goto="orchestrator_turn")
@@ -523,7 +563,17 @@ def _orchestrator_context(
is DeliverableStatus.SUBMITTED
else None
)
code = DeliverableKind.DEPLOYMENT_GUIDANCE
return {
# Checks the code's author reported cannot be met as written: faults in the
# Target architecture, known before any validation.
"unimplementable_checks": unimplementable_checks(
deliverables.get(code.value, {})
.get("attachments", {})
.get(IMPLEMENTATION_FILE, "")
)
if ledger.status(code) is DeliverableStatus.SUBMITTED
else [],
# The verdict on each Check, once validation is submitted: failed Checks are
# faults in the code; the rest are gaps in the Target architecture.
"validation": validation_outcome(
@@ -565,8 +615,15 @@ def _specialist_input(
attempt: int,
) -> dict[str, Any]:
spec = DEPENDENCY_GRAPH[kind]
given = dependencies_for(kind, deliverables)
return {
"execution_id": state["execution_id"],
# The Deliverables given as data files alone, whole, for reading on demand.
"library": {
name: dict(deliverables[name])
for name, deliverable in given.items()
if "content" not in deliverable
},
"role": spec.specialist,
"kind": kind.value,
"attempt": attempt,
@@ -576,13 +633,14 @@ def _specialist_input(
"workflow_request": state["workflow_request"],
"pre_approved": bool(state.get("pre_approved")),
"contract": spec.contract(),
"dependencies": {
dependency.value: dict(deliverables[dependency.value])
for dependency in inputs_of(kind)
},
"dependencies": given,
"feedback": list(ledger.feedback(kind)),
"answers": list(state.get("answers", {}).get(kind.value, [])),
"draft": dict(drafts[kind.value]) if kind.value in drafts else None,
# What the Specialist's own tools already hold from earlier attempts.
"working_copy": workspace.summary(
state.get("working", {}).get(kind.value, {})
),
"attempt": attempt,
},
}

779
app/nodes/router.py Normal file
View File

@@ -0,0 +1,779 @@
"""The Orchestrator as a router (ADR-0007): readings, a disposition, then a playbook.
1. Readings facts about the turn. Most come from the Ledger; the ones that need
judgement (what is the user asking for? does this gap matter?) are
typed answers from the decision model.
2. Disposition code turns a judged reading into act, queue or close, by threshold.
3. Playbook ordered groups. The first group that applies is taken, and within
it the strongest action whose conditions hold. When no group
applies, escalate to the user.
The decision model reads and never acts: every action goes through the Orchestrator's
tools, so the Ledger refuses anything that is not allowed, whatever was decided.
"""
from __future__ import annotations
import logging
import re
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any, Protocol
from app.adk.runtime import (
AgentRuntime,
AgentTask,
Decider,
Outcome,
Question,
RoleSpec,
Stopped,
Submitted,
ToolResult,
ToolSpec,
)
from app.states.ledger import DeliverableStatus, Ledger, PhaseStatus
from app.workflows.chain import (
IMPLEMENTATION_FILE,
RECOMMENDATIONS_FILE,
REQUIREMENTS_FILE,
VERDICTS_FILE,
read_graph,
read_list,
unimplementable_checks,
validation_outcome,
)
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind, PhaseId
logger = logging.getLogger(__name__)
ORCHESTRATOR = "orchestrator"
REPLY_WRITER = "reply-writer"
MAX_STEPS = 12 # actions in one turn; a turn that needs more is not making progress
ACT, QUEUE, CLOSE = "act", "queue", "close"
@dataclass(frozen=True)
class Thresholds:
"""Where a probability becomes a disposition."""
act: float = 0.75 # at or above: do it
close: float = 0.15 # at or below: there is nothing to do
confidence: float = 0.6 # a choice below this is not relied on
def disposition(self, probability: float) -> str:
if probability >= self.act:
return ACT
if probability <= self.close:
return CLOSE
return QUEUE
@dataclass(frozen=True)
class TurnView:
"""What one Orchestrator turn can see."""
execution_id: str
pre_approved: bool
ledger: Ledger
deliverables: Mapping[str, Mapping[str, Any]]
pending_questions: Sequence[Mapping[str, Any]]
outcomes: Sequence[Mapping[str, Any]]
last_reply: Mapping[str, Any] | None = None # the user's message, not yet routed
pending_change: Mapping[str, Any] | None = None # a change we asked them to confirm
awaiting_gap_decision: bool = False
validation_settled: int = 0 # the validation attempt already decided on
context: Mapping[str, Any] = field(default_factory=dict) # for a model Orchestrator
@dataclass
class TurnResult:
outcome: Outcome
decisions: list[dict[str, Any]] = field(default_factory=list)
updates: dict[str, Any] = field(default_factory=dict)
class OrchestratorPolicy(Protocol):
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult: ...
class ReplyWriter(Protocol):
async def approval_summary(
self, phase: str, facts: Mapping[str, Any]
) -> str | None: ...
# --- readings ------------------------------------------------------------------------
@dataclass
class Readings:
"""Everything the playbook decides from."""
# From the Ledger and the Execution's data.
questions_waiting: bool = False
phases_ready: tuple[PhaseId, ...] = ()
phases_awaiting: tuple[PhaseId, ...] = () # asked for Approval, not yet decided
ready_work: tuple[DeliverableKind, ...] = ()
can_finish: bool = False
validation_attempt: int = 0 # 0 when no validation stands undecided
failed: list[dict[str, Any]] = field(default_factory=list)
repeat_failed: list[dict[str, Any]] = field(default_factory=list)
unverifiable: list[dict[str, Any]] = field(default_factory=list)
additions: list[dict[str, Any]] = field(default_factory=list)
dry_run_failed: bool = False
# Checks the code's author reported cannot be met as the Target architecture
# words them.
unimplementable: list[dict[str, str]] = field(default_factory=list)
# Judged: what the user's message asks for.
change: str = CLOSE # act | queue | close
change_target: DeliverableKind | None = None
change_reason: str = ""
# Judged: whether a gap in the Target architecture is worth a Revision.
gap: str = CLOSE
judged: dict[str, Any] = field(default_factory=dict) # what the decider answered
def _attempt(ledger: Ledger, kind: DeliverableKind) -> int:
return int(ledger.to_dict()["deliverables"][kind.value].get("attempt", 0))
def _submitted(ledger: Ledger) -> list[DeliverableKind]:
return [
kind
for kind in DEPENDENCY_GRAPH
if ledger.status(kind) is DeliverableStatus.SUBMITTED
]
def _mentioned(
text: str, candidates: Sequence[DeliverableKind]
) -> list[DeliverableKind]:
"""Deliverables named outright in a message, as `deployment_guidance` or in words."""
lowered = re.sub(r"[\s_\-]+", " ", text.lower())
return [kind for kind in candidates if kind.value.replace("_", " ") in lowered]
def _failed_before(outcomes: Sequence[Mapping[str, Any]]) -> set[str]:
"""Check ids that failed in the validation before the one that stands now."""
validations = [
record
for record in outcomes
if record.get("type") == "submitted"
and record.get("kind") == DeliverableKind.VALIDATION_RESULTS.value
]
if len(validations) < 2:
return set()
previous = validation_outcome(
validations[-2].get("attachments", {}).get(VERDICTS_FILE, "")
)
return {item["check"] for item in previous["failed"]}
class Router:
"""Decides an Orchestrator turn from readings and a playbook, with no language
model choosing the action. A model, when one is given, only writes what the user
reads."""
def __init__(
self,
decider: Decider,
writer: ReplyWriter | None = None,
thresholds: Thresholds | None = None,
) -> None:
self._decider = decider
self._writer = writer
self._thresholds = thresholds or Thresholds()
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult:
by_name = {tool.name: tool for tool in tools}
result = TurnResult(Stopped("The router took no action."))
# A user message is routed once; a confirmation we asked for is consumed.
result.updates = {
"last_reply": None,
"pending_change": None,
"awaiting_gap_decision": False,
}
readings = await self._read(view, result)
blocked: set[str] = set()
settled = view.validation_settled
async def call(tool: str, **arguments: Any) -> ToolResult:
return await by_name[tool].handler(**arguments)
for _ in range(MAX_STEPS):
group, action = self._choose(view, readings, blocked, settled)
result.decisions.append(
{"group": group, "action": action, "judged": dict(readings.judged)}
)
readings.judged = {}
reply = await self._perform(action, view, readings, call, result)
if action == "proceed":
settled = readings.validation_attempt
result.updates["validation_settled"] = settled
self._read_ledger(view, readings, settled)
continue
if reply is None:
return result
if reply.outcome is not None:
result.outcome = reply.outcome
return result
if "revision limit" in reply.message and not view.pre_approved:
# Past the Revision limit the user decides.
limit = await call(
"ask_user", questions=[reply.message.split(" Use ")[0]]
)
if limit.outcome is not None:
result.outcome = limit.outcome
return result
if reply.message.startswith("Refused") or "revision limit" in reply.message:
# Permission is the Ledger's: take the next action that is allowed.
blocked.add(action)
# The action changed the Execution; read the Ledger's facts again.
self._read_ledger(view, readings, settled)
if action in {"revise_requested", "confirm_change"}:
readings.change = CLOSE
result.outcome = Stopped("The router made no progress in this turn.")
return result
# --- readings ---------------------------------------------------------------------
async def _read(self, view: TurnView, result: TurnResult) -> Readings:
readings = Readings()
self._read_ledger(view, readings, view.validation_settled)
await self._read_message(view, readings)
await self._read_gap(view, readings)
return readings
def _read_ledger(self, view: TurnView, readings: Readings, settled: int) -> None:
ledger = view.ledger
readings.questions_waiting = bool(view.pending_questions)
readings.phases_ready = ledger.phases_ready_for_approval()
readings.phases_awaiting = tuple(
phase
for phase in PhaseId
if ledger.phase_status(phase) is PhaseStatus.AWAITING_APPROVAL
)
readings.ready_work = ledger.ready_work()
readings.can_finish = ledger.can_finish()
readings.validation_attempt = 0
readings.failed, readings.repeat_failed = [], []
readings.unverifiable, readings.additions = [], []
readings.dry_run_failed = False
code = DeliverableKind.DEPLOYMENT_GUIDANCE
readings.unimplementable = (
unimplementable_checks(
view.deliverables.get(code.value, {})
.get("attachments", {})
.get(IMPLEMENTATION_FILE, "")
)
if ledger.status(code) is DeliverableStatus.SUBMITTED
else []
)
validation = DeliverableKind.VALIDATION_RESULTS
phase = DEPENDENCY_GRAPH[validation].phase
attempt = _attempt(ledger, validation)
if (
ledger.status(validation) is not DeliverableStatus.SUBMITTED
or ledger.phase_status(phase) is PhaseStatus.APPROVED
or attempt == settled
):
return
outcome = validation_outcome(
view.deliverables.get(validation.value, {})
.get("attachments", {})
.get(VERDICTS_FILE, "")
)
before = _failed_before(view.outcomes)
readings.validation_attempt = attempt
readings.failed = outcome["failed"]
readings.repeat_failed = [f for f in outcome["failed"] if f["check"] in before]
readings.unverifiable = outcome["not_verifiable"]
readings.additions = outcome["proposed_additions"]
readings.dry_run_failed = outcome["dry_run"].get("verdict") == "fail"
async def _read_message(self, view: TurnView, readings: Readings) -> None:
"""Triage of the user's message: is it asking for a change, to what, and how
clearly?"""
reply = view.last_reply
if not reply or view.awaiting_gap_decision:
return
text = str(reply.get("text", "")).strip()
pending = view.pending_change
if pending:
text = f"{pending.get('text', '')}\nThe user then said: {text}"
candidates = _submitted(view.ledger)
if not text or not candidates:
return
readings.change_reason = text
# A structured request for changes is known to be one, and so is the reply to
# our own question about a change they already asked for.
structured = reply.get("kind") == "changes" or bool(pending)
questions = {
"change_target": Question(
"choice",
"Which submitted Deliverable would have to change first to do what "
"the user asks?",
tuple(kind.value for kind in candidates),
),
"change_clarity": Question(
"score",
"How specific is the user about what should change?",
("vague", "partial", "specific"),
),
}
if not structured:
questions["asks_change"] = Question(
"noul",
"Is the user asking for a change to work that has already been "
"submitted, as opposed to answering a question or adding information?",
)
state = (
f"Submitted Deliverables: {', '.join(kind.value for kind in candidates)}.\n"
f"Questions waiting for the user: {len(view.pending_questions)}.\n"
f"The user's message: {text}"
)
answers = await self._decider.decide(state, questions, scope=view.execution_id)
named = _mentioned(text, candidates)
if answers is None:
# No judgement available: act only on what is certain.
if structured:
target = (
candidates[0]
if len(candidates) == 1
else named[0]
if len(named) == 1
else None
)
readings.change = ACT if target else QUEUE
readings.change_target = target
return
readings.judged = {
name: {"value": answer.value, "confidence": answer.confidence}
for name, answer in answers.items()
}
probability = 1.0 if structured else float(answers["asks_change"].value)
disposition = self._thresholds.disposition(probability)
target_answer = answers["change_target"]
target = DeliverableKind(str(target_answer.value))
readings.change_target = target
if disposition == ACT and (
target_answer.confidence < self._thresholds.confidence
or float(answers["change_clarity"].value) < 0.5
):
# They want a change, but which, or what, is not clear enough to act on.
disposition = QUEUE
if disposition == QUEUE and pending:
# Asked once already: act if they named it, otherwise let it go.
disposition = ACT if len(named) == 1 else CLOSE
readings.change_target = named[0] if named else target
readings.change = disposition
async def _read_gap(self, view: TurnView, readings: Readings) -> None:
"""Whether a gap in the Target architecture is worth revising it for."""
if (
readings.failed
or readings.dry_run_failed
or not readings.validation_attempt
):
return
if not (readings.additions or readings.unverifiable):
return
items = "\n".join(
[
f"- proposed addition on {item.get('applies_to')}: "
f"{item.get('statement')} (serves {item.get('reason')})"
for item in readings.additions
]
+ [
f"- Check {item.get('check')} could not be verified: "
f"{item.get('evidence')}"
for item in readings.unverifiable
]
)
reply = view.last_reply if view.awaiting_gap_decision else None
if reply:
question = Question(
"noul",
"Is the user asking for the Target architecture to be revised to "
"close these gaps?",
)
state = f"Gaps found by validation:\n{items}\nThe user's reply: {reply.get('text', '')}"
name = "wants_revision"
else:
question = Question(
"noul",
"Would leaving these gaps open mean a stated requirement or design "
"recommendation is not met?",
)
state = f"Gaps found by validation:\n{items}"
name = "gap_material"
answers = await self._decider.decide(
state, {name: question}, scope=view.execution_id
)
if answers is None:
readings.gap = self._gap_by_rule(view, readings) if not reply else CLOSE
return
readings.judged[name] = {
"value": answers[name].value,
"confidence": answers[name].confidence,
}
disposition = self._thresholds.disposition(float(answers[name].value))
if reply and disposition == QUEUE:
disposition = CLOSE # asked once already; an unclear answer means go on
readings.gap = disposition
@staticmethod
def _gap_by_rule(view: TurnView, readings: Readings) -> str:
"""Without a judgement: a Check that cannot be verified must be fixed, and an
addition counts when it names a real requirement or recommendation."""
if readings.unverifiable:
return ACT
known = {
item["id"]
for name, kind in (
(REQUIREMENTS_FILE, "requirements"),
(RECOMMENDATIONS_FILE, "design_recommendations"),
)
for item in read_list(view.deliverables, kind, name)
if "id" in item
}
for item in readings.additions:
words = set(re.findall(r"[A-Za-z]+-\d+", str(item.get("reason", ""))))
if words & known:
return ACT
return CLOSE
# --- the playbook -----------------------------------------------------------------
def _choose(
self, view: TurnView, r: Readings, blocked: set[str], settled: int
) -> tuple[str, str]:
"""The first group that applies, and within it the strongest action whose
conditions hold. No group applies: escalate."""
interactive = not view.pre_approved
playbook: list[tuple[str, bool, list[tuple[str, bool]]]] = [
(
"the user asked for a change",
r.change in {ACT, QUEUE},
[
(
"revise_requested",
r.change == ACT and r.change_target is not None,
),
("confirm_change", r.change == QUEUE and interactive),
],
),
(
"questions are waiting",
r.questions_waiting,
[("relay_questions", True)],
),
(
# Known as soon as the code is submitted, so no validation is spent
# on a Check that cannot pass.
"the code cannot meet a Check",
bool(r.unimplementable),
[("revise_unimplementable", True)],
),
(
"validation decided",
bool(r.validation_attempt),
[
(
"revise_target_architecture",
bool(r.repeat_failed) or (not r.failed and r.gap == ACT),
),
("revise_code", bool(r.failed) or r.dry_run_failed),
("ask_about_gaps", r.gap == QUEUE and interactive),
("proceed", True),
],
),
(
"a Phase is complete",
bool(r.phases_ready or r.phases_awaiting),
# An Approval is granted only by a structured decision, so a Phase
# still awaiting one is asked for again.
[("request_approval", True)],
),
("work is ready", bool(r.ready_work), [("delegate", True)]),
("packaging is approved", r.can_finish, [("finish", True)]),
]
for group, applies, actions in playbook:
if not applies:
continue
for action, holds in actions:
if holds and action not in blocked:
return group, action
return "no group applies", "escalate"
async def _perform(
self,
action: str,
view: TurnView,
r: Readings,
call: Callable[..., Awaitable[ToolResult]],
result: TurnResult,
) -> ToolResult | None:
if action == "proceed":
return ToolResult("Proceeding.")
if action == "revise_requested":
assert r.change_target is not None
return await call(
"reopen", kind=r.change_target.value, reason=r.change_reason
)
if action == "confirm_change":
guess = r.change_target.value if r.change_target else None
result.updates["pending_change"] = {"text": r.change_reason, "guess": guess}
options = ", ".join(kind.value for kind in _submitted(view.ledger))
question = (
f"Do you want {guess} changed? Reply naming the Deliverable to change "
f"and what should be different. Submitted so far: {options}."
if guess
else "Which Deliverable should change, and what should be different? "
f"Submitted so far: {options}."
)
return await call("ask_user", questions=[question])
if action == "relay_questions":
return await call("ask_user", questions=[])
if action == "revise_code":
items = r.failed or [
{"check": "dry-run", "evidence": "the deployment dry-run failed"}
]
reason = "; ".join(f"{i['check']} failed: {i['evidence']}" for i in items)
return await call(
"reopen", kind=DeliverableKind.DEPLOYMENT_GUIDANCE.value, reason=reason
)
if action == "revise_unimplementable":
reason = " ".join(
f"Check {item['check']} cannot be implemented as written "
f"({item['reason']}). Rewrite it so it can be met, or remove it with "
"a reason."
for item in r.unimplementable
)
return await call(
"reopen", kind=DeliverableKind.TARGET_ARCHITECTURE.value, reason=reason
)
if action == "revise_target_architecture":
return await call(
"reopen",
kind=DeliverableKind.TARGET_ARCHITECTURE.value,
reason=_graph_reason(r),
)
if action == "ask_about_gaps":
result.updates["awaiting_gap_decision"] = True
listed = "; ".join(
[str(i.get("statement")) for i in r.additions]
+ [
f"Check {i.get('check')} could not be verified"
for i in r.unverifiable
]
)
question = (
"Validation passed every Check it could, and found gaps in the "
f"Target architecture: {listed}. Should the Target architecture "
"be revised to close them, or shall I proceed as it stands?"
)
return await call("ask_user", questions=[question])
if action == "request_approval":
phase = (r.phases_ready or r.phases_awaiting)[0]
return await call(
"request_approval",
phase=phase.value,
summary=await self._summary(phase, view, r),
)
if action == "delegate":
return await call("delegate", kinds=[kind.value for kind in r.ready_work])
if action == "finish":
return await call("finish")
# escalate: no group applies.
if view.pre_approved:
result.outcome = Stopped(
"No next step applies and no user is available to decide."
)
return None
return await call(
"ask_user",
questions=["I have no next step to take. What would you like me to do?"],
)
async def _summary(self, phase: PhaseId, view: TurnView, r: Readings) -> str:
facts = approval_facts(phase, view, r)
if self._writer is not None:
try:
written = await self._writer.approval_summary(phase.value, facts)
except Exception: # a summary must never stop an Approval
logger.exception("The reply writer failed; using the assembled summary")
written = None
if written and written.strip():
return written.strip()
return assembled_summary(phase, facts)
def _graph_reason(r: Readings) -> str:
parts = [
f"Check {item['check']} failed in two validations in a row and may not be "
f"implementable as written ({item['evidence']}). Rewrite it so it can be met, "
"or remove it with a reason."
for item in r.repeat_failed
]
if not r.repeat_failed:
parts += [
f"Check {item.get('check')} could not be verified from the code "
f"({item.get('evidence')}). Rewrite it so it can be."
for item in r.unverifiable
]
parts += [
f"Add a Check on {item.get('applies_to')}: {item.get('statement')} "
f"(serves {item.get('reason')})."
for item in r.additions
]
return " ".join(parts)
def approval_facts(phase: PhaseId, view: TurnView, r: Readings) -> dict[str, Any]:
"""What an Approval summary is written from: data, never Deliverable prose."""
kinds = [kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase]
facts: dict[str, Any] = {
"phase": phase.value,
"deliverables": [kind.value for kind in kinds],
"revisions": {
kind.value: view.ledger.revisions(kind)
for kind in kinds
if view.ledger.revisions(kind)
},
}
counts = {
"requirements": len(
read_list(view.deliverables, "requirements", REQUIREMENTS_FILE)
),
"recommendations": len(
read_list(view.deliverables, "design_recommendations", RECOMMENDATIONS_FILE)
),
}
facts["counts"] = {name: count for name, count in counts.items() if count}
graph = read_graph(view.deliverables)
if graph is not None:
facts["target_architecture"] = graph.summary()
validation = view.deliverables.get(DeliverableKind.VALIDATION_RESULTS.value)
if (
validation
and phase is DEPENDENCY_GRAPH[DeliverableKind.VALIDATION_RESULTS].phase
):
outcome = validation_outcome(
validation.get("attachments", {}).get(VERDICTS_FILE, "")
)
facts["validation"] = {
"passed": len(outcome["passed"]),
"failed": [item["check"] for item in outcome["failed"]],
"not_verifiable": [item["check"] for item in outcome["not_verifiable"]],
"open_gaps": [
item.get("statement") for item in outcome["proposed_additions"]
],
}
return facts
def assembled_summary(phase: PhaseId, facts: Mapping[str, Any]) -> str:
"""An Approval summary from the facts alone, used when no writer is available."""
lines = [
(
f"The {phase.value} Phase is ready: "
f"{', '.join(facts['deliverables'])} submitted."
)
]
counts = facts.get("counts") or {}
if counts:
lines.append(
", ".join(f"{count} {name}" for name, count in counts.items()) + "."
)
graph = facts.get("target_architecture")
if graph:
lines.append(
f"Target architecture: {graph['elements']} Elements, "
f"{graph['relationships']} Relationships, {graph['checks']} Checks."
)
validation = facts.get("validation")
if validation:
lines.append(
f"Validation: {validation['passed']} Checks passed, "
f"{len(validation['failed'])} failed, "
f"{len(validation['not_verifiable'])} not verifiable."
)
if validation["open_gaps"]:
lines.append(
"Open gaps: " + "; ".join(map(str, validation["open_gaps"])) + "."
)
if facts.get("revisions"):
lines.append(
"Revised: "
+ ", ".join(
f"{kind} × {count}" for kind, count in facts["revisions"].items()
)
+ "."
)
return " ".join(lines)
# --- the two ways an Orchestrator turn can be driven ---------------------------------
class ModelOrchestrator:
"""The Orchestrator as a reasoning agent: a language model chooses the tool calls.
Kept so the Ledger's rules can be driven in any order by a scripted runtime in
tests, and so an evaluation can compare it with the router.
"""
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
self._runtime = runtime
self._role = role
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult:
task = AgentTask(
role=ORCHESTRATOR,
prompt="Decide the next step for this Execution using your tools.",
context=view.context,
)
return TurnResult(await self._runtime.run(self._role, task, tools))
class RuntimeReplyWriter:
"""Writes what the user reads, on a language model. It is given a decision that
has already been made and the facts, and it decides nothing."""
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
self._runtime = runtime
self._role = role
async def approval_summary(
self, phase: str, facts: Mapping[str, Any]
) -> str | None:
async def write_reply(text: str) -> ToolResult:
if not text.strip():
return ToolResult("Not submitted: the reply is empty.")
return ToolResult("Written.", Submitted(text))
tool = ToolSpec(
"write_reply",
"Give the text the user will read. Ends your turn.",
{
"type": "object",
"properties": {"text": {"type": "string"}},
"required": ["text"],
},
write_reply,
tier="execution",
)
task = AgentTask(
role=REPLY_WRITER,
prompt=f"Write the summary the user will approve the {phase} Phase from.",
context={"phase": phase, "facts": dict(facts)},
)
outcome = await self._runtime.run(self._role, task, [tool])
return outcome.content if isinstance(outcome, Submitted) else None

View File

@@ -42,10 +42,16 @@ class McpServerSpec:
class ModelConfig:
default: str
roles: Mapping[str, str] = field(default_factory=dict)
# Seconds one model request may take, for the roles whose replies are long. A
# role not named here gets the runtime's default.
timeouts: Mapping[str, float] = field(default_factory=dict)
def for_role(self, role: str) -> str:
return self.roles.get(role, self.default)
def timeout_for(self, role: str) -> float | None:
return self.timeouts.get(role)
@dataclass(frozen=True)
class ProviderBundle:
@@ -60,6 +66,9 @@ class ProviderBundle:
role_mcp_servers: Mapping[str, tuple[str, ...]]
role_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
pillar_skills: Mapping[str, str] = field(default_factory=dict)
# The Terraform providers generated code is written for, pinned so the schema
# lookup, the patterns and validation agree: {name: {source, version}}.
terraform_providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
def mcp_servers_for_role(
self, role: str, include_preview: bool = True
@@ -108,10 +117,34 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
models = config.get("models") or {}
if not isinstance(models.get("default"), str) or not models["default"]:
raise fail("'models.default' is required")
timeouts = {}
for role, seconds in (models.get("timeout_seconds") or {}).items():
if isinstance(seconds, bool) or not isinstance(seconds, (int, float)):
raise fail(f"'models.timeout_seconds' for {role!r} must be a number")
if seconds <= 0:
raise fail(f"'models.timeout_seconds' for {role!r} must be positive")
timeouts[str(role)] = float(seconds)
model_config = ModelConfig(
default=models["default"], roles=dict(models.get("roles") or {})
default=models["default"],
roles=dict(models.get("roles") or {}),
timeouts=timeouts,
)
terraform_providers = {}
pins = (config.get("terraform") or {}).get("required_providers") or {}
for provider, pin in pins.items():
if not isinstance(pin, dict) or not all(
isinstance(pin.get(key), str) and pin[key] for key in ("source", "version")
):
raise fail(
f"terraform provider {provider!r} needs a 'source' and an exact "
"'version', both strings"
)
terraform_providers[str(provider)] = {
"source": pin["source"],
"version": pin["version"],
}
tools = {}
for tier, tool_names in (config.get("tools") or {}).items():
if tier not in TIERS:
@@ -173,4 +206,5 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
role_mcp_servers=role_mcp_servers,
role_skills=role_skills,
pillar_skills=pillar_skills,
terraform_providers=terraform_providers,
)

View File

@@ -82,6 +82,13 @@ class ExecutionState(TypedDict, total=False):
refusals: list[dict[str, Any]] # the Orchestrator's refused tool calls
events_recorded: int
# Routing (ADR-0007).
last_reply: dict[str, Any] | None # the user's message, until a turn routes it
pending_change: dict[str, Any] | None # a change the user was asked to confirm
awaiting_gap_decision: bool # the user was asked whether to close gaps
validation_settled: int # the validation attempt already decided on
decisions: list[dict[str, Any]] # every routing decision, in order
turns: int
status: str # running | completed | completed_with_warnings
warnings: list[str]

View File

@@ -7,8 +7,7 @@ outcome.
from __future__ import annotations
from collections.abc import Mapping, Sequence
from pathlib import PurePosixPath
from collections.abc import Mapping, MutableMapping, Sequence
from typing import Any
from app.adk.runtime import (
@@ -21,6 +20,14 @@ from app.adk.runtime import (
files_from_argument,
)
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
from app.tools.workspace import (
file_tools,
graph_text,
graph_tools,
keep_graph,
safe_relative,
working_files,
)
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
DeliverableKind,
@@ -35,6 +42,7 @@ from app.workflows.target_architecture import (
TargetArchitecture,
parse_graph,
render_mermaid,
render_tables,
)
ORCHESTRATOR = "orchestrator"
@@ -244,29 +252,37 @@ class OrchestratorToolbox:
return ToolResult("Finishing the Execution.", TurnEnded("finish"))
def _safe_relative(name: str) -> bool:
path = PurePosixPath(name)
return bool(name) and not path.is_absolute() and ".." not in path.parts
def specialist_tools(
kind: DeliverableKind,
extra: Sequence[ToolSpec],
allow_cloud_read: bool | None,
upstream: Mapping[str, Mapping[str, Any]] | None = None,
working: MutableMapping[str, Any] | None = None,
library: Mapping[str, Mapping[str, Any]] | None = None,
) -> list[ToolSpec]:
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate.
"""A Specialist's tools: submit, ask, its working copy, and its role's tools with
the cloud-read gate.
`upstream` is the Deliverables this one builds on; with it, a submission's links
along the Requirements chain are checked.
along the Requirements chain are checked. `working` is the Deliverable's working
memory, where its working copy is kept. `library` is the earlier Deliverables
given to the Specialist as data files alone, to read whole when it needs one.
"""
working = {} if working is None else working
is_graph = kind is DeliverableKind.TARGET_ARCHITECTURE
own_files = DEPENDENCY_GRAPH[kind].working_copy is kind
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
try:
attachments = files_from_argument(attachments)
except TypeError as exc:
return _refused(f"attachments: {exc}")
unsafe = [name for name in attachments if not _safe_relative(name)]
# The working copy is the submission; a file passed here replaces its copy.
if own_files:
attachments = {**working_files(working), **attachments}
if is_graph and GRAPH_ATTACHMENT not in attachments and graph_text(working):
attachments[GRAPH_ATTACHMENT] = graph_text(working)
unsafe = [name for name in attachments if not safe_relative(name)]
if unsafe:
return _refused(
"attachment names must be relative paths without '..': "
@@ -277,13 +293,27 @@ def specialist_tools(
return ToolResult(
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
)
if kind is DeliverableKind.TARGET_ARCHITECTURE:
# The diagram is a view of the graph, so the engine draws it.
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(
parse_graph(attachments[GRAPH_ATTACHMENT])
)
if own_files:
working_files(working).update(attachments)
if is_graph:
# The tables and the diagram are views of the graph, so the engine
# writes them: they cannot disagree with it.
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
keep_graph(working, attachments[GRAPH_ATTACHMENT])
content = content.rstrip() + "\n\n" + render_tables(graph)
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(graph)
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
async def read_deliverable(kind: str) -> ToolResult:
deliverable = (library or {}).get(kind)
if deliverable is None:
available = ", ".join(library or {}) or "none"
return _refused(f"{kind} is not one you can read here: {available}")
attached = ", ".join(deliverable.get("attachments", {})) or "none"
return ToolResult(
f"{deliverable.get('content', '')}\n\nAttachments: {attached}"
)
async def needs_input(
questions: Sequence[str], draft: str | None = None, attachments: Any = None
) -> ToolResult:
@@ -331,6 +361,23 @@ def specialist_tools(
needs_input,
tier="execution",
),
*(
[
ToolSpec(
"read_deliverable",
"Read the full text of an earlier Deliverable that `dependencies` "
"gives you as its data file alone: "
f"{', '.join(library)}. Use it only when the ids are not enough.",
_schema({"kind": {"type": "string"}}, ["kind"]),
read_deliverable,
tier="execution",
)
]
if library
else ()
),
*(graph_tools(working) if is_graph else ()),
*(file_tools(working) if own_files else ()),
*(gate_cloud_read(tool, allow_cloud_read) for tool in extra),
]

327
app/tools/jev.py Normal file
View File

@@ -0,0 +1,327 @@
"""The Jev decision client: typed answers to closed questions, within strict limits.
Jev is TypeSafe AI's decision model. This module is the only one that speaks to it,
through the vendor's Python SDK (`typesafe-sdk`), which owns the request shape, the
timeout and the retries. Everything else here is ours: the service's limits are not
published, so the client assumes they are strict and never lets Jev hold up an
Execution. Any refusal, failure or timeout returns None and the caller takes its
fallback.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import time
from collections import OrderedDict, deque
from collections.abc import Awaitable, Callable, Mapping
from dataclasses import dataclass, field
from typing import Any
from typesafe_sdk import (
AsyncTypeSafeClient,
Choice,
ChoiceAnswer,
Noul,
NoulAnswer,
RetryPolicy,
Score,
ScoreAnswer,
TypeSafeError,
TypeSafeRateLimitError,
)
from app.adk.runtime import Answer, Question
logger = logging.getLogger(__name__)
@dataclass(frozen=True)
class JevLimits:
"""Every limit the client keeps. Starting values, to tune from measurement."""
max_tokens: int = 48_000 # state plus questions; the service allows 64,000
max_question_tokens: int = 24_000 # state plus the longest question; allows 32,000
request_timeout: float = 5.0 # one HTTP attempt
total_timeout: float = 15.0 # a decision, retries included
retries: int = 2
backoff_base: float = 0.5
backoff_cap: float = 8.0
requests_per_second: float = 5.0
burst: int = 10
max_in_flight: int = 8
breaker_failures: int = 5
breaker_window: float = 30.0
breaker_cooldown: float = 60.0
cache_size: int = 1024
budget_calls: int = 500 # per scope, usually one Execution
budget_tokens: int = 1_000_000 # per scope; about $0.42 at the published price
@dataclass
class DecisionRecord:
"""One attempt to decide, kept for the evaluation report and for tuning."""
scope: str
questions: tuple[str, ...]
# answered | cached | too_large | over_budget | breaker_open | failed
outcome: str = "failed"
seconds: float = 0.0
rate_limited: bool = False
input_tokens: int = 0
confidence: Mapping[str, float] = field(default_factory=dict)
def estimate_tokens(text: str) -> int:
"""A deliberately high estimate: refusing locally is cheaper than a rejected call."""
return len(text) // 3 + 1
def encode_question(question: Question) -> Noul | Choice | Score:
if question.kind == "choice":
return Choice(
instructions=question.instructions,
criteria=dict.fromkeys(question.options),
)
if question.kind == "score":
return Score(
instructions=question.instructions, criteria=list(question.options)
)
return Noul(instructions=question.instructions)
def decode_answer(question: Question, raw: object) -> Answer | None:
"""The SDK's answer as ours, or None when it does not answer the question asked."""
if question.kind == "choice" and isinstance(raw, ChoiceAnswer):
# A choice outside the options asked for is not an answer.
if raw.choice not in question.options:
return None
return Answer(raw.choice, raw.confidence, dict(raw.probabilities))
if question.kind == "score" and isinstance(raw, ScoreAnswer):
probabilities = {str(level): p for level, p in raw.probabilities.items()}
return Answer(raw.score, raw.confidence, probabilities)
if question.kind == "noul" and isinstance(raw, NoulAnswer):
# Jev gives a probability for a yes-or-no question and no separate
# confidence, so confidence is how far the probability is from even.
return Answer(raw.noul, abs(2 * raw.noul - 1))
return None
class JevDecider:
def __init__(
self,
*,
api_key: str,
base_url: str | None = None,
model: str | None = None,
limits: JevLimits | None = None,
transport: Any = None,
clock: Callable[[], float] = time.monotonic,
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
) -> None:
self.limits = limits or JevLimits()
self._clock = clock
self._sleep = sleep
self._client = AsyncTypeSafeClient(
api_key=api_key,
base_url=base_url,
model=model,
timeout=self.limits.request_timeout,
# The SDK retries 408, 429 and 5xx, and connection and timeout errors,
# with jittered backoff, and honours Retry-After.
retry=RetryPolicy(
max_retries=self.limits.retries,
backoff_initial=self.limits.backoff_base,
backoff_max=self.limits.backoff_cap,
timeout=self.limits.total_timeout,
),
transport=transport,
)
self._in_flight = asyncio.Semaphore(self.limits.max_in_flight)
# Token bucket: starts full, refills at `rate`, which drops when the service
# says we are going too fast.
self._rate = self.limits.requests_per_second
self._tokens = float(self.limits.burst)
self._refilled = clock()
self._bucket = asyncio.Lock()
self._failures: deque[float] = deque()
self._open_until = 0.0
self._probing = False
self._cache: OrderedDict[str, dict[str, Answer]] = OrderedDict()
self._calls: dict[str, int] = {}
self._tokens_used: dict[str, int] = {}
self._over_budget: set[str] = set()
self.records: list[DecisionRecord] = []
async def aclose(self) -> None:
await self._client.aclose()
async def decide(
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
) -> Mapping[str, Answer] | None:
record = DecisionRecord(scope=scope, questions=tuple(questions))
self.records.append(record)
started = self._clock()
try:
return await self._decide(state, questions, scope, record)
finally:
record.seconds = self._clock() - started
async def _decide(
self,
state: str,
questions: Mapping[str, Question],
scope: str,
record: DecisionRecord,
) -> Mapping[str, Answer] | None:
if not questions:
record.outcome = "answered"
return {}
asked = {
name: {
"kind": question.kind,
"instructions": question.instructions,
"options": list(question.options),
}
for name, question in questions.items()
}
sizes = [estimate_tokens(json.dumps(item)) for item in asked.values()]
state_size = estimate_tokens(state)
if (
state_size + sum(sizes) > self.limits.max_tokens
or state_size + max(sizes) > self.limits.max_question_tokens
):
# Never truncate: the caller must split by Deliverable or section.
record.outcome = "too_large"
return None
key = hashlib.sha256(
json.dumps({"state": state, "questions": asked}, sort_keys=True).encode()
).hexdigest()
if key in self._cache:
self._cache.move_to_end(key)
record.outcome = "cached"
return dict(self._cache[key])
if (
self._calls.get(scope, 0) >= self.limits.budget_calls
or self._tokens_used.get(scope, 0) >= self.limits.budget_tokens
):
if scope not in self._over_budget:
self._over_budget.add(scope)
logger.warning("Jev budget reached for %s; using fallbacks", scope)
record.outcome = "over_budget"
return None
if not self._breaker_allows():
record.outcome = "breaker_open"
return None
self._calls[scope] = self._calls.get(scope, 0) + 1
await self._take_token()
try:
async with self._in_flight:
response = await self._client.system_one(
state=state,
questions={
name: encode_question(question)
for name, question in questions.items()
},
)
except TypeSafeRateLimitError:
# Still rate limited after the SDK's retries: halve our own rate.
record.rate_limited = True
self._rate = max(self._rate / 2, 0.25)
self._note_failure()
return None
except TypeSafeError as exc:
logger.info("Jev request failed: %s", type(exc).__name__)
self._note_failure()
return None
self._note_success()
used = response.usage.input_tokens or 0
record.input_tokens = used
self._tokens_used[scope] = self._tokens_used.get(scope, 0) + used
answers: dict[str, Answer] = {}
for name, question in questions.items():
answer = decode_answer(question, response.answers.get(name))
if answer is None:
# A reply that does not answer every question answers none.
return None
answers[name] = answer
record.outcome = "answered"
record.confidence = {name: a.confidence for name, a in answers.items()}
self._cache[key] = answers
while len(self._cache) > self.limits.cache_size:
self._cache.popitem(last=False)
return dict(answers)
async def _take_token(self) -> None:
async with self._bucket:
while True:
now = self._clock()
self._tokens = min(
float(self.limits.burst),
self._tokens + (now - self._refilled) * self._rate,
)
self._refilled = now
if self._tokens >= 1:
self._tokens -= 1
return
await self._sleep((1 - self._tokens) / self._rate)
def _breaker_allows(self) -> bool:
now = self._clock()
if now < self._open_until:
return False
if self._open_until and not self._probing:
# Cool-down over: let exactly one call through to test the service.
self._probing = True
return True
def _note_failure(self) -> None:
now = self._clock()
if self._probing:
self._probing = False
self._open_until = now + self.limits.breaker_cooldown
return
self._failures.append(now)
while self._failures and now - self._failures[0] > self.limits.breaker_window:
self._failures.popleft()
if len(self._failures) >= self.limits.breaker_failures:
self._failures.clear()
self._open_until = now + self.limits.breaker_cooldown
logger.warning(
"Jev circuit open for %.0fs after repeated failures",
self.limits.breaker_cooldown,
)
def _note_success(self) -> None:
self._failures.clear()
self._open_until = 0.0
self._probing = False
def summary(self) -> dict[str, Any]:
"""Totals for the evaluation report."""
outcomes: dict[str, int] = {}
for record in self.records:
outcomes[record.outcome] = outcomes.get(record.outcome, 0) + 1
answered = [r for r in self.records if r.outcome == "answered"]
return {
"decisions": len(self.records),
"outcomes": outcomes,
"fallbacks": sum(
count
for name, count in outcomes.items()
if name not in {"answered", "cached"}
),
"rate_limited": sum(1 for r in self.records if r.rate_limited),
"seconds": round(sum(r.seconds for r in answered), 3),
"input_tokens": sum(r.input_tokens for r in self.records),
}

View File

@@ -1,16 +1,23 @@
"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory.
Terraform runs only fmt, init -backend=false, validate and plan. No command that
changes cloud resources is ever constructed.
Terraform runs only fmt, init -backend=false, validate, plan and providers schema. No
command that changes cloud resources is ever constructed.
A Specialist with a working copy (app/tools/workspace.py) runs the checks on it and
passes no files; `terraform_fmt` formats the working copy in place. That is what
keeps a fix cheap: the model changes a line and validates, without sending every file
again on each call.
"""
from __future__ import annotations
import asyncio
import difflib
import json
import os
import re
import tempfile
from collections.abc import Awaitable, Callable, Iterable, Mapping
from collections.abc import Awaitable, Callable, Iterable, Mapping, MutableMapping
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
from typing import Any
@@ -79,10 +86,19 @@ class TerraformRunner:
# Providers are downloaded here once and reused by every later check. Without it,
# each validate or plan downloads its providers again into a scratch directory.
plugin_cache_dir: str | None = None
# The providers the schema lookup answers for, as the provider bundle pins them:
# {local name: {"source": ..., "version": ...}}.
providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
# Terraform's plugin cache is not safe for concurrent installs.
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
_schema_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
# resource type -> (provider label, the resource's schema block)
_schemas: dict[str, tuple[str, dict[str, Any]]] | None = field(
default=None, repr=False
)
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
async def formatted(self, files: Mapping[str, str]) -> dict[str, str] | ToolResult:
"""The files formatting changes, with their new content; or why it failed."""
refusal = _check_files(files)
if refusal:
return refusal
@@ -93,19 +109,24 @@ class TerraformRunner:
)
if code != 0:
return ToolResult(f"terraform fmt failed:\n{output}")
changed = [
name for name in files if (root / name).read_text() != files[name]
]
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
formatted = "\n\n".join(
f"--- {name}\n{(root / name).read_text()}" for name in changed
)
return ToolResult(
_clip(
f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}"
)
)
return {
name: (root / name).read_text()
for name in files
if (root / name).read_text() != files[name]
}
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
changed = await self.formatted(files)
if isinstance(changed, ToolResult):
return changed
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
formatted = "\n\n".join(
f"--- {name}\n{content}" for name, content in changed.items()
)
return ToolResult(
_clip(f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}")
)
async def validate(self, files: Mapping[str, str]) -> ToolResult:
refusal = _check_files(files)
@@ -150,6 +171,87 @@ class TerraformRunner:
_clip(f"terraform plan {verdict} (nothing was applied):\n{output}")
)
async def schema(
self, resource_type: str, block: str = "", find: str = ""
) -> ToolResult:
"""What a resource type accepts, from the pinned provider's own schema."""
loaded = await self._load_schemas()
if isinstance(loaded, ToolResult):
return loaded
if resource_type not in loaded:
close = difflib.get_close_matches(resource_type, loaded, n=5, cutoff=0.6)
hint = f" Close matches: {', '.join(close)}." if close else ""
return ToolResult(
f"No resource type {resource_type} in {self._provider_labels()}.{hint}"
)
label, root = loaded[resource_type]
title = f"{resource_type} ({label})"
if find:
return ToolResult(_clip(_find_in_schema(title, root, find)))
node = root
for step in [part for part in block.split(".") if part]:
nested = node.get("block_types", {}).get(step)
if nested is None:
inside = ", ".join(sorted(node.get("block_types", {}))) or "none"
return ToolResult(
f"{title} has no block {block!r}: {step!r} is not a block there. "
f"Blocks at that level: {inside}."
)
node = nested["block"]
heading = f"{title}, block {block}" if block else title
return ToolResult(_clip(_render_schema(heading, node)))
def _provider_labels(self) -> str:
return (
", ".join(
f"{pin['source']} {pin['version']}" for pin in self.providers.values()
)
or "no pinned provider"
)
async def _load_schemas(self) -> dict[str, tuple[str, dict[str, Any]]] | ToolResult:
async with self._schema_lock:
if self._schemas is not None:
return self._schemas
if not self.providers:
return ToolResult(
"Schema lookup is unavailable: the Cloud provider bundle pins no "
"Terraform provider."
)
required = "\n".join(
f' {name} = {{ source = "{pin["source"]}", '
f'version = "{pin["version"]}" }}'
for name, pin in self.providers.items()
)
with tempfile.TemporaryDirectory(prefix="tf-schema-") as tmp:
root = Path(tmp)
(root / "versions.tf").write_text(
f"terraform {{\n required_providers {{\n{required}\n }}\n}}\n"
)
failure = await self._init(root)
if failure:
return failure
code, output = await self._run(
[self.binary, "providers", "schema", "-json"], root
)
if code != 0:
return ToolResult(
_clip(f"terraform providers schema failed:\n{output}")
)
try:
data = json.loads(output)
except ValueError:
return ToolResult("terraform providers schema returned no JSON.")
labels = {pin["source"]: pin["version"] for pin in self.providers.values()}
schemas: dict[str, tuple[str, dict[str, Any]]] = {}
for address, provider in (data.get("provider_schemas") or {}).items():
source = address.split("/", 1)[-1] # drop the registry host
label = f"{source} {labels.get(source, '')}".strip()
for name, resource in (provider.get("resource_schemas") or {}).items():
schemas[name] = (label, resource.get("block") or {})
self._schemas = schemas
return schemas
async def _init(self, root: Path) -> ToolResult | None:
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
if self.plugin_cache_dir:
@@ -236,6 +338,100 @@ def _clip(text: str) -> str:
return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]"
def _type(value: Any) -> str:
if isinstance(value, str):
return value
if isinstance(value, list) and len(value) == 2 and value[0] != "object":
return f"{value[0]} of {_type(value[1])}"
return "object"
def _use(attribute: Mapping[str, Any]) -> str:
if attribute.get("required"):
return "required"
return "optional" if attribute.get("optional") else "read-only"
def _arguments(node: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
"""The arguments code may set: everything but the read-only ones."""
return {
name: attribute
for name, attribute in sorted((node.get("attributes") or {}).items())
if _use(attribute) != "read-only"
}
def _block_note(nested: Mapping[str, Any]) -> str:
notes = [str(nested.get("nesting_mode", "block"))]
if nested.get("min_items"):
notes.append(f"at least {nested['min_items']}")
if nested.get("max_items"):
notes.append(f"at most {nested['max_items']}")
return ", ".join(notes)
def _render_schema(heading: str, node: Mapping[str, Any]) -> str:
"""One level in full, and the blocks beneath it as an outline of names."""
lines = [heading, "", "Arguments:"]
arguments = _arguments(node)
for name, attribute in arguments.items():
described = " ".join(str(attribute.get("description") or "").split())[:160]
deprecated = " DEPRECATED" if attribute.get("deprecated") else ""
lines.append(
f" {name} ({_type(attribute.get('type'))}, {_use(attribute)})"
f"{deprecated}" + (f": {described}" if described else "")
)
if not arguments:
lines.append(" none")
def outline(parent: Mapping[str, Any], depth: int) -> None:
for name, nested in sorted((parent.get("block_types") or {}).items()):
inner = nested.get("block") or {}
names = ", ".join(
f"{argument}*" if attribute.get("required") else argument
for argument, attribute in _arguments(inner).items()
)
lines.append(
f"{' ' * depth}{name} {{ }} ({_block_note(nested)}): {names or '-'}"
)
outline(inner, depth + 1)
lines += ["", "Blocks (* marks a required argument):"]
before = len(lines)
outline(node, 1)
if len(lines) == before:
lines.append(" none")
lines += ["", "Pass `block`, such as a.b, for one block's arguments in full."]
return "\n".join(lines)
def _find_in_schema(title: str, root: Mapping[str, Any], wanted: str) -> str:
"""Every argument or block whose name contains `wanted`, with where it sits."""
needle = wanted.lower()
found: list[str] = []
def search(node: Mapping[str, Any], path: str) -> None:
for name, attribute in sorted((node.get("attributes") or {}).items()):
if needle in name.lower():
where = f"{path}.{name}" if path else name
found.append(
f" {where} ({_type(attribute.get('type'))}, {_use(attribute)})"
)
for name, nested in sorted((node.get("block_types") or {}).items()):
where = f"{path}.{name}" if path else name
if needle in name.lower():
found.append(f" {where} {{ }} ({_block_note(nested)})")
search(nested.get("block") or {}, where)
search(root, "")
if not found:
return (
f"{title} has no argument or block named like {wanted!r}. It cannot be "
"set on this resource type."
)
return f"{title}: {wanted!r} is found at\n" + "\n".join(found)
_FILES_SCHEMA: dict[str, Any] = {
**FILES_SCHEMA,
"description": "Terraform files in one directory, e.g. terraform/main.tf",
@@ -244,19 +440,53 @@ _FILES_SCHEMA: dict[str, Any] = {
def _with_files(
method: Callable[..., Awaitable[ToolResult]],
working_copy: MutableMapping[str, str] | None = None,
) -> Callable[..., Awaitable[ToolResult]]:
"""Adapt a runner method to take the FILES_SCHEMA argument."""
"""Adapt a runner method to take the FILES_SCHEMA argument.
async def handler(files: Any, **kwargs: Any) -> ToolResult:
With a working copy, the files are the Terraform files in it and the argument is
optional: files passed anyway are written to the working copy first.
"""
async def handler(files: Any = None, **kwargs: Any) -> ToolResult:
try:
converted = files_from_argument(files)
except TypeError as exc:
return ToolResult(f"Refused: files: {exc}")
return await method(converted, **kwargs)
if working_copy is None:
return await method(converted, **kwargs)
working_copy.update(converted)
return await method(_terraform_files(working_copy), **kwargs)
return handler
def _terraform_files(files: Mapping[str, str]) -> dict[str, str]:
return {
name: content
for name, content in files.items()
if name.endswith(_TERRAFORM_SUFFIXES)
}
def _fmt_in_place(
runner: TerraformRunner, working_copy: MutableMapping[str, str]
) -> Callable[..., Awaitable[ToolResult]]:
async def format_working_copy(files: Mapping[str, str]) -> ToolResult:
changed = await runner.formatted(files)
if isinstance(changed, ToolResult):
return changed
working_copy.update(changed)
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
return ToolResult(
f"terraform fmt reformatted {len(changed)} file(s) in your working "
f"copy: {', '.join(sorted(changed))}."
)
return _with_files(format_working_copy, working_copy)
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
@@ -268,10 +498,48 @@ LOCAL_TOOLS: dict[str, tuple[str, str]] = {
"cloud_read",
"Preview Terraform against the live cloud environment with a plan. Never applies.",
),
"terraform_schema": (
"general",
(
"Look up what a Terraform resource type accepts, from the provider's own "
"schema: its arguments and blocks, one block in full with `block`, or "
"whether an argument exists anywhere in it with `find`."
),
),
}
_ON_WORKING_COPY = " Runs on your working copy; pass no files."
def local_tools(
names: Iterable[str],
runner: TerraformRunner,
working_copy: MutableMapping[str, str] | None = None,
) -> list[ToolSpec]:
"""The named tools. With a `working_copy`, the Terraform checks run on it."""
files_required = [] if working_copy is not None else ["files"]
suffix = _ON_WORKING_COPY if working_copy is not None else ""
def checks(name: str, method: Callable[..., Awaitable[ToolResult]]) -> ToolSpec:
properties: dict[str, Any] = {"files": _FILES_SCHEMA}
if name == "terraform_plan":
properties["variables"] = {
"type": "object",
"additionalProperties": {"type": "string"},
}
tier, description = LOCAL_TOOLS[name]
return ToolSpec(
name,
description + suffix,
{
"type": "object",
"properties": properties,
"required": files_required,
},
method,
tier=tier,
)
def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]:
builders = {
"mermaid_check": lambda: ToolSpec(
"mermaid_check",
@@ -284,44 +552,41 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
mermaid_check,
tier="general",
),
"terraform_fmt": lambda: ToolSpec(
"terraform_fmt": lambda: checks(
"terraform_fmt",
LOCAL_TOOLS["terraform_fmt"][1],
{
"type": "object",
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
_with_files(runner.fmt),
tier="general",
_fmt_in_place(runner, working_copy)
if working_copy is not None
else _with_files(runner.fmt),
),
"terraform_validate": lambda: ToolSpec(
"terraform_validate",
LOCAL_TOOLS["terraform_validate"][1],
{
"type": "object",
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
_with_files(runner.validate),
tier="general",
"terraform_validate": lambda: checks(
"terraform_validate", _with_files(runner.validate, working_copy)
),
"terraform_plan": lambda: ToolSpec(
"terraform_plan",
LOCAL_TOOLS["terraform_plan"][1],
"terraform_plan": lambda: checks(
"terraform_plan", _with_files(runner.plan, working_copy)
),
"terraform_schema": lambda: ToolSpec(
"terraform_schema",
LOCAL_TOOLS["terraform_schema"][1],
{
"type": "object",
"properties": {
"files": _FILES_SCHEMA,
"variables": {
"type": "object",
"additionalProperties": {"type": "string"},
"resource_type": {
"type": "string",
"description": "For example google_cloud_run_v2_service",
},
"block": {
"type": "string",
"description": "A nested block, such as template.containers",
},
"find": {
"type": "string",
"description": "An argument or block name to look for",
},
},
"required": ["files"],
"required": ["resource_type"],
},
_with_files(runner.plan),
tier="cloud_read",
runner.schema,
tier="general",
),
}
return [builders[name]() for name in names]

View File

@@ -2,19 +2,24 @@
A role gets the local tools its role file names, the tools of the remote MCP servers
the provider bundle assigns it, and, for the design advisor, the pillar consultation.
When the Deliverable has a working copy, the local tools are built on it.
Cloud-read gating is applied later, per Execution, by `specialist_tools`.
"""
from __future__ import annotations
from collections.abc import Mapping, MutableMapping, Sequence
from collections.abc import Callable, Mapping, MutableMapping, Sequence
from typing import Any
from app.adk.roles import PILLAR_ADVISOR
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory, ToolSpec
from app.tools.mcp import McpCatalog
from app.tools.pillars import pillar_consultation_tool
from app.workflows.deliverables import DeliverableKind
from app.tools.workspace import working_files
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
# The local tools, built on a working copy of files when the Deliverable has one.
LocalToolBuilder = Callable[[MutableMapping[str, str] | None], Sequence[ToolSpec]]
def make_tool_factory(
@@ -22,11 +27,14 @@ def make_tool_factory(
roles: Mapping[str, RoleSpec],
pillar_skills: Mapping[str, str],
*,
local_tools: Sequence[ToolSpec] = (),
local_tools: Sequence[ToolSpec] | LocalToolBuilder = (),
catalog: McpCatalog | None = None,
limiter: RunLimiter | None = None,
) -> ToolFactory:
local_by_name = {tool.name: tool for tool in local_tools}
def build_local(
working_copy: MutableMapping[str, str] | None,
) -> Sequence[ToolSpec]:
return local_tools(working_copy) if callable(local_tools) else local_tools
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
return catalog.tools_for(role.mcp_servers) if catalog else []
@@ -42,6 +50,16 @@ def make_tool_factory(
def tools_for(
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
) -> Sequence[ToolSpec]:
has_working_copy = any(
kind.value == deliverable and spec.working_copy is not None
for kind, spec in DEPENDENCY_GRAPH.items()
)
local_by_name = {
tool.name: tool
for tool in build_local(
working_files(working) if has_working_copy else None
)
}
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
tools += mcp_tools(role)
if (

289
app/tools/workspace.py Normal file
View File

@@ -0,0 +1,289 @@
"""A Specialist's working copy: files and a graph built up over several tool calls.
A model that must return a whole Deliverable in one reply spends most of its output
repeating itself, and a long reply is what times out. With a working copy it writes a
file once, changes only the lines that need changing, and adds to a graph a few items
at a time. The working copy is kept with the Execution, so a Revision starts from the
last attempt instead of from nothing.
It lives in the Deliverable's working memory:
working["files"] {path: content}
working["graph"] the Target architecture, as target-architecture.json holds it
"""
from __future__ import annotations
import json
from collections.abc import Mapping, MutableMapping, Sequence
from pathlib import PurePosixPath
from typing import Any
from app.adk.runtime import ToolResult, ToolSpec
FILES = "files"
GRAPH = "graph"
_GRAPH_LISTS = ("elements", "relationships", "checks", "not_applicable")
_MAX_READ = 40_000
def safe_relative(name: str) -> bool:
path = PurePosixPath(name)
return bool(name) and not path.is_absolute() and ".." not in path.parts
def working_files(working: MutableMapping[str, Any]) -> MutableMapping[str, str]:
files = working.get(FILES)
if not isinstance(files, MutableMapping):
files = working[FILES] = {}
return files
def _schema(properties: Mapping[str, Any], required: Sequence[str]) -> dict[str, Any]:
return {
"type": "object",
"properties": dict(properties),
"required": list(required),
}
def _lines(content: str) -> int:
return content.count("\n") + (1 if content and not content.endswith("\n") else 0)
def file_tools(working: MutableMapping[str, Any]) -> list[ToolSpec]:
"""Tools that write, change and read the files of a working copy."""
files = working_files(working)
async def write_file(path: str, content: str) -> ToolResult:
if not safe_relative(path):
return ToolResult(
f"Refused: {path!r} must be a relative path without '..'."
)
files[path] = content
return ToolResult(f"Wrote {path} ({_lines(content)} lines).")
async def edit_file(path: str, old: str, new: str) -> ToolResult:
if path not in files:
return ToolResult(f"Refused: {path} is not in your working copy.")
found = files[path].count(old) if old else 0
if found != 1:
return ToolResult(
f"Refused: `old` must match exactly one place in {path}; it matches "
f"{found}. Include more of the surrounding lines."
)
files[path] = files[path].replace(old, new)
return ToolResult(f"Edited {path}.")
async def read_file(path: str = "") -> ToolResult:
if not path:
if not files:
return ToolResult("Your working copy is empty.")
return ToolResult(
"Your working copy:\n"
+ "\n".join(
f"- {name} ({_lines(files[name])} lines)" for name in sorted(files)
)
)
if path not in files:
return ToolResult(f"Refused: {path} is not in your working copy.")
content = files[path]
if len(content) > _MAX_READ:
content = content[:_MAX_READ] + "\n[truncated]"
return ToolResult(content)
async def delete_file(path: str) -> ToolResult:
if files.pop(path, None) is None:
return ToolResult(f"Refused: {path} is not in your working copy.")
return ToolResult(f"Deleted {path}.")
text = {"type": "string"}
return [
ToolSpec(
"write_file",
"Write one file of your working copy, replacing it if it exists. Your "
"working copy is attached for you when you submit.",
_schema({"path": text, "content": text}, ["path", "content"]),
write_file,
),
ToolSpec(
"edit_file",
"Change part of one file: replace the single place `old` matches with "
"`new`. Use this for a fix instead of writing the file again.",
_schema({"path": text, "old": text, "new": text}, ["path", "old", "new"]),
edit_file,
),
ToolSpec(
"read_file",
"Read one file of your working copy, or list its files when `path` is "
"left out.",
_schema({"path": text}, []),
read_file,
),
ToolSpec(
"delete_file",
"Remove one file from your working copy.",
_schema({"path": text}, ["path"]),
delete_file,
),
]
# --- the graph -----------------------------------------------------------------------
def working_graph(working: MutableMapping[str, Any]) -> dict[str, list[dict[str, Any]]]:
graph = working.get(GRAPH)
if not isinstance(graph, dict):
graph = working[GRAPH] = {}
for name in _GRAPH_LISTS:
if not isinstance(graph.get(name), list):
graph[name] = []
return graph
def graph_text(working: MutableMapping[str, Any]) -> str:
"""The working graph as target-architecture.json, or "" when nothing is in it."""
graph = working.get(GRAPH)
if not isinstance(graph, dict) or not any(graph.get(n) for n in _GRAPH_LISTS):
return ""
return json.dumps(
{name: graph.get(name, []) for name in _GRAPH_LISTS},
indent=2,
ensure_ascii=False,
)
def keep_graph(working: MutableMapping[str, Any], text: str) -> None:
"""Make a submitted graph the working graph, so a Revision amends it."""
try:
data = json.loads(text)
except ValueError:
return
if isinstance(data, dict):
working[GRAPH] = {
name: [item for item in data.get(name, []) if isinstance(item, dict)]
for name in _GRAPH_LISTS
}
def _key(name: str) -> str:
return "recommendation" if name == "not_applicable" else "id"
def graph_tools(working: MutableMapping[str, Any]) -> list[ToolSpec]:
"""Tools that build the Target architecture a few items at a time."""
async def graph_put(
elements: Sequence[Any] = (),
relationships: Sequence[Any] = (),
checks: Sequence[Any] = (),
not_applicable: Sequence[Any] = (),
) -> ToolResult:
graph = working_graph(working)
given = dict(
zip(
_GRAPH_LISTS,
(elements, relationships, checks, not_applicable),
strict=True,
)
)
bad = [
f"{name}[{index}]"
for name, items in given.items()
for index, item in enumerate(items or ())
if not isinstance(item, Mapping)
or not isinstance(item.get(_key(name)), str)
or not item[_key(name)].strip()
]
if bad:
return ToolResult(
"Refused: each item must be an object with an `id` (a "
f"`recommendation` under not_applicable): {', '.join(bad)}"
)
added = replaced = 0
for name, items in given.items():
key = _key(name)
for item in items or ():
for index, existing in enumerate(graph[name]):
if existing.get(key) == item[key]:
graph[name][index] = dict(item)
replaced += 1
break
else:
graph[name].append(dict(item))
added += 1
return ToolResult(f"Added {added}, replaced {replaced}. {_counts(graph)}")
async def graph_remove(ids: Sequence[str]) -> ToolResult:
graph = working_graph(working)
wanted = set(ids)
removed = 0
for name in _GRAPH_LISTS:
kept = [item for item in graph[name] if item.get(_key(name)) not in wanted]
removed += len(graph[name]) - len(kept)
graph[name] = kept
return ToolResult(f"Removed {removed}. {_counts(graph)}")
async def graph_read() -> ToolResult:
return ToolResult(graph_text(working) or "Your working graph is empty.")
def items(*fields: str, optional: tuple[str, ...] = ()) -> dict[str, Any]:
return {
"type": "array",
"items": _schema(
{name: {"type": "string"} for name in (*fields, *optional)}, fields
),
}
lists = {
"elements": items(
"id", "name", "product", "resource_type", optional=("component",)
),
"relationships": items("id", "from", "to", "kind"),
"checks": items("id", "applies_to", "statement", "source"),
"not_applicable": items("recommendation", "reason"),
}
return [
ToolSpec(
"graph_put",
"Add items to your working graph, or replace the ones with the same id. "
"Call it several times with a few items each. Your working graph is "
"attached as target-architecture.json when you submit.",
_schema(lists, []),
graph_put,
),
ToolSpec(
"graph_remove",
"Remove items from your working graph by id (a not-applicable entry by "
"its recommendation id).",
_schema({"ids": {"type": "array", "items": {"type": "string"}}}, ["ids"]),
graph_remove,
),
ToolSpec(
"graph_read",
"Read your working graph.",
{"type": "object", "properties": {}},
graph_read,
),
]
def _counts(graph: Mapping[str, Sequence[Any]]) -> str:
return (
f"The graph has {len(graph['elements'])} Elements, "
f"{len(graph['relationships'])} Relationships and "
f"{len(graph['checks'])} Checks."
)
def summary(working: Mapping[str, Any]) -> dict[str, Any] | None:
"""What a Specialist is told it already has, at the start of a run."""
told: dict[str, Any] = {}
files = working.get(FILES)
if isinstance(files, Mapping) and files:
told["files"] = sorted(files)
graph = working.get(GRAPH)
if isinstance(graph, Mapping) and any(graph.get(name) for name in _GRAPH_LISTS):
told["graph"] = {name: len(graph.get(name) or ()) for name in _GRAPH_LISTS}
return told or None

View File

@@ -242,20 +242,51 @@ def _covers_every_check(
return problems
def _split_implementation(text: str, name: str) -> tuple[str, str]:
"""The entries that say where a Check is met, and those that say it cannot be."""
try:
data = json.loads(text)
except ValueError:
return text, "[]"
if not isinstance(data, list):
return text, "[]"
cannot = [
item for item in data if isinstance(item, dict) and "unimplementable" in item
]
met = [item for item in data if item not in cannot]
return json.dumps(met), json.dumps(cannot)
def check_implementation(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = IMPLEMENTATION_FILE
items, problems = _objects(attachments[name], name, ("check", "file", "address"))
problems += _covers_every_check(items, name, read_graph(upstream))
met_text, cannot_text = _split_implementation(attachments[name], name)
met, problems = _objects(met_text, name, ("check", "file", "address"))
cannot, faults = _objects(cannot_text, name, ("check", "unimplementable"))
problems += faults
problems += _covers_every_check([*met, *cannot], name, read_graph(upstream))
problems += [
f"{name}: {item['check']} names {item['file']}, which is not attached"
for item in items
for item in met
if item["file"] not in attachments
]
return problems
def unimplementable_checks(implementation_text: str) -> list[dict[str, str]]:
"""The Checks the code's author found cannot be met as written, with the reason.
Each is a fault in the Target architecture, not in the code: the Check names
something the resource does not have.
"""
_, cannot_text = _split_implementation(implementation_text, IMPLEMENTATION_FILE)
cannot, _ = _objects(cannot_text, IMPLEMENTATION_FILE, ("check", "unimplementable"))
return [
{"check": item["check"], "reason": item["unimplementable"]} for item in cannot
]
def check_verdicts(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:

View File

@@ -64,6 +64,14 @@ class DeliverableSpec:
depends_on: tuple[DeliverableKind, ...] = ()
sections: tuple[str, ...] = ()
attachments: tuple[str, ...] = ()
# Which earlier Deliverables the Specialist reads whole. None means the ones it
# depends on. Every other input arrives as its data file alone: the ids the
# Requirements chain runs through, without the prose written around them.
reads_in_full: tuple[DeliverableKind, ...] | None = None
# The Deliverable whose files this Specialist's tools work on. Its own kind: the
# files are its working copy, kept across attempts and attached on submission.
# Another kind: a fresh copy of that Deliverable's files on every attempt.
working_copy: DeliverableKind | None = None
def contract(self) -> dict[str, list[str]]:
"""What a submission must contain, as plain data for the Specialist's context."""
@@ -126,8 +134,10 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
PhaseId.SOLUTION_ARCHITECTURE,
"target-architect",
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
sections=("Elements", "Relationships", "Checks"),
# The engine adds architecture.mmd, rendered from the graph, on submission.
# The Specialist writes the reasoning and the graph. On submission the
# engine adds the Elements, Relationships and Checks tables to the content
# and architecture.mmd to the attachments, both rendered from the graph.
sections=("Design rationale",),
attachments=(GRAPH_ATTACHMENT,),
),
DeliverableSpec(
@@ -151,6 +161,9 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
"terraform/variables.tf",
IMPLEMENTATION_FILE,
),
# The graph is all the code is written from.
reads_in_full=(),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
DeliverableSpec(
_K.VALIDATION_RESULTS,
@@ -159,6 +172,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
sections=("Deployment dry-run", "Architecture and policy analysis"),
attachments=(VERDICTS_FILE,),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
DeliverableSpec(
_K.SOLUTION_GUIDE,
@@ -175,6 +189,8 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
"Validation plan",
"References",
),
# The guide is assembled from every Deliverable's prose.
reads_in_full=tuple(_K)[:-1],
),
)
}
@@ -218,6 +234,31 @@ def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]:
)
def dependencies_for(
kind: DeliverableKind, deliverables: Mapping[str, Mapping[str, object]]
) -> dict[str, dict[str, object]]:
"""What a Specialist is given of each Deliverable it works from.
A Deliverable read in full arrives as submitted. Any other arrives as its data
file alone, which is all the Requirements chain needs of it.
"""
spec = DEPENDENCY_GRAPH[kind]
in_full = spec.depends_on if spec.reads_in_full is None else spec.reads_in_full
given: dict[str, dict[str, object]] = {}
for dependency in inputs_of(kind):
deliverable = deliverables[dependency.value]
if dependency in in_full or dependency not in DATA_CHECKS:
given[dependency.value] = dict(deliverable)
continue
name = DATA_CHECKS[dependency][0]
attachments = deliverable.get("attachments")
files = attachments if isinstance(attachments, Mapping) else {}
given[dependency.value] = {
"attachments": {name: files[name]} if name in files else {}
}
return given
def deliverables_in(phase: PhaseId) -> tuple[DeliverableKind, ...]:
return tuple(kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase)

View File

@@ -20,6 +20,7 @@ from langgraph.graph import END, START, StateGraph
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
from app.nodes.execution_nodes import make_execution_nodes
from app.nodes.router import OrchestratorPolicy
from app.recorder import ExecutionRecorder
from app.states.execution_state import ExecutionState
@@ -34,6 +35,7 @@ def build_execution_graph(
tool_factory: ToolFactory | None = None,
limiter: RunLimiter | None = None,
skill_versions: Mapping[str, str] | None = None,
orchestrator: OrchestratorPolicy | None = None,
) -> StateGraph:
nodes = make_execution_nodes(
runtime=runtime,
@@ -44,6 +46,7 @@ def build_execution_graph(
tool_factory=tool_factory,
limiter=limiter,
skill_versions=skill_versions,
orchestrator=orchestrator,
)
graph = StateGraph(ExecutionState)

View File

@@ -6,7 +6,8 @@
to the requirement or design recommendation it comes from
This module is pure: it parses the graph, states what is wrong with it, renders it as
a diagram, and says whether the Requirements chain through it is complete.
a diagram and as tables a person can review, and says whether the Requirements chain
through it is complete.
"""
from __future__ import annotations
@@ -281,3 +282,64 @@ def render_mermaid(graph: TargetArchitecture) -> str:
f"{nodes[relationship.target]}"
)
return "\n".join(lines) + "\n"
# --- so are the tables a person reviews ----------------------------------------------
def _cell(text: str | None) -> str:
return " ".join((text or "").replace("|", "\\|").split())
def _table(
heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]]
) -> str:
lines = [
f"## {heading}",
"",
"| " + " | ".join(columns) + " |",
"|" + "|".join(" --- " for _ in columns) + "|",
]
lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows]
return "\n".join(lines)
def render_tables(graph: TargetArchitecture) -> str:
"""The graph as markdown tables: what a person approving the design reads.
Written by code, so the tables cannot disagree with the graph and no model spends
output repeating it.
"""
names = {element.id: element.name for element in graph.elements}
parts = [
_table(
"Elements",
("Id", "Name", "Product", "Resource type", "Component"),
(
(e.id, e.name, e.product, e.resource_type, e.component)
for e in graph.elements
),
),
_table(
"Relationships",
("Id", "From", "Kind", "To"),
(
(r.id, names[r.source], r.kind, names[r.target])
for r in graph.relationships
),
),
_table(
"Checks",
("Id", "Applies to", "Statement", "Source"),
((c.id, c.applies_to, c.statement, c.source) for c in graph.checks),
),
]
if graph.not_applicable:
parts.append(
_table(
"Not applicable",
("Recommendation", "Reason"),
((n.recommendation, n.reason) for n in graph.not_applicable),
)
)
return "\n\n".join(parts) + "\n"