Files
gcp_solution_architecture_a…/app/tools/execution.py
Jonathan Boniface e9246828b3 feat: establish the Target architecture as a graph before code
Design is now approved before any infrastructure code is written (ADR-0005).
A new target-architect Specialist produces one graph of Elements,
Relationships and Checks; the diagram is rendered from it, deployment
guidance must account for every Check, and validation gives a verdict per
Check. Requirements, components, products and recommendations carry ids in
data files, and a submission with a gap in the Requirements chain is refused.

Also in this commit:
- Customer cases group Executions, with an intent history per case
- lesson candidates are captured when an Execution ends
- evaluation gains chain, verdict, judged and interactive checks, and
  per-case thresholds
- Terraform providers are cached between checks
- the requirements analyst proposes defaults instead of asking
- the legacy-baseline case and the checks that only read it are removed
- ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed
- plans for iterations 4 to 7 under .agents/plans/

Unproven with a real model: no evaluation run has completed on this design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 13:59:09 +01:00

368 lines
13 KiB
Python

"""Execution tools: how agents act on an Execution.
Tools enforce the Ledger's rules at the moment an agent acts, and return refusals as
messages so a ReAct agent can recover. A tool ends the agent's turn by returning an
outcome.
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from pathlib import PurePosixPath
from typing import Any
from app.adk.runtime import (
FILES_SCHEMA,
NeedsInput,
Submitted,
ToolResult,
ToolSpec,
TurnEnded,
files_from_argument,
)
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
DeliverableKind,
PhaseId,
check_submission,
deliverables_in,
)
from app.workflows.target_architecture import (
DIAGRAM_ATTACHMENT,
GRAPH_ATTACHMENT,
GraphError,
TargetArchitecture,
parse_graph,
render_mermaid,
)
ORCHESTRATOR = "orchestrator"
_TARGET = DeliverableKind.TARGET_ARCHITECTURE
CLOUD_READ = "cloud_read"
_NO_ARGS: Mapping[str, Any] = {"type": "object", "properties": {}}
def _schema(properties: Mapping[str, Any], required: Sequence[str]) -> dict[str, Any]:
return {
"type": "object",
"properties": dict(properties),
"required": list(required),
}
def _refused(reason: object) -> ToolResult:
return ToolResult(f"Refused: {reason}")
class OrchestratorToolbox:
"""The Orchestrator's tools, bound to a working copy of the Ledger for one turn."""
def __init__(
self,
ledger: Ledger,
deliverables: Mapping[str, Mapping[str, Any]],
pending_questions: Sequence[Mapping[str, Any]],
) -> None:
self.ledger = ledger
self._deliverables = deliverables
self._pending_questions = pending_questions
self.started: dict[DeliverableKind, int] = {}
self.questions: list[dict[str, str]] = []
self.approval: dict[str, Any] | None = None
self.escalation: str | None = None
def tools(self) -> list[ToolSpec]:
return [
ToolSpec(
"ready_work",
"List Deliverables ready to delegate and Phases ready for Approval.",
_NO_ARGS,
self.ready_work,
tier="execution",
),
ToolSpec(
"delegate",
"Start Specialists on ready Deliverables, in parallel. Ends your turn.",
_schema(
{"kinds": {"type": "array", "items": {"type": "string"}}},
["kinds"],
),
self.delegate,
tier="execution",
),
ToolSpec(
"ask_user",
"Ask the user your questions together with any waiting Specialist "
"questions. Ends your turn.",
_schema(
{"questions": {"type": "array", "items": {"type": "string"}}}, []
),
self.ask_user,
tier="execution",
),
ToolSpec(
"request_approval",
"Ask the user to approve a Phase whose Deliverables are all "
"submitted. Ends your turn unless the Execution is pre-approved.",
_schema(
{"phase": {"type": "string"}, "summary": {"type": "string"}},
["phase", "summary"],
),
self.request_approval,
tier="execution",
),
ToolSpec(
"reopen",
"Revise a submitted Deliverable; everything depending on it returns "
"to draft.",
_schema(
{"kind": {"type": "string"}, "reason": {"type": "string"}},
["kind", "reason"],
),
self.reopen,
tier="execution",
),
ToolSpec(
"read_deliverable",
"Read a submitted Deliverable's content.",
_schema({"kind": {"type": "string"}}, ["kind"]),
self.read_deliverable,
tier="execution",
),
ToolSpec(
"finish",
"Complete the Execution once packaging is approved. Ends your turn.",
_NO_ARGS,
self.finish,
tier="execution",
),
]
async def ready_work(self) -> ToolResult:
ready = ", ".join(self.ledger.ready_work()) or "none"
phases = ", ".join(self.ledger.phases_ready_for_approval()) or "none"
return ToolResult(
f"Ready to delegate: {ready}. Phases ready for approval: {phases}."
)
async def delegate(self, kinds: Sequence[str]) -> ToolResult:
try:
parsed = [DeliverableKind(kind) for kind in kinds]
if not parsed:
raise LedgerRefusal("name at least one Deliverable")
started = self.ledger.start(parsed, actor=ORCHESTRATOR)
except (ValueError, LedgerRefusal) as exc:
return _refused(exc)
self.started.update(started)
return ToolResult(f"Started: {', '.join(started)}.", TurnEnded("delegate"))
async def ask_user(self, questions: Sequence[str] = ()) -> ToolResult:
waiting = sorted(
self._pending_questions,
key=lambda item: list(DEPENDENCY_GRAPH).index(
DeliverableKind(item["kind"])
),
)
combined = [
{"from": item["kind"], "question": question}
for item in waiting
for question in item["questions"]
]
combined += [{"from": ORCHESTRATOR, "question": q} for q in questions if q]
if not combined:
return _refused("there is nothing to ask the user")
self.questions = combined
return ToolResult("Asked the user.", TurnEnded("ask_user"))
async def request_approval(self, phase: str, summary: str) -> ToolResult:
try:
phase_id = PhaseId(phase)
except ValueError as exc:
return _refused(exc)
if self.ledger.phase_status(phase_id) is not PhaseStatus.AWAITING_APPROVAL:
try:
self.ledger.request_approval(phase_id, actor=ORCHESTRATOR)
except LedgerRefusal as exc:
return _refused(exc)
if self.ledger.phase_status(phase_id) is PhaseStatus.APPROVED:
return ToolResult(
f"Phase {phase_id} approved (pre-approved Execution)."
)
self.approval = {
"phase": phase_id.value,
"summary": summary,
"deliverables": [kind.value for kind in deliverables_in(phase_id)],
}
graph = self._target_architecture()
if graph and phase_id is DEPENDENCY_GRAPH[_TARGET].phase:
# What the user is approving before any code is written.
self.approval["target_architecture"] = graph.summary()
return ToolResult(
f"Asked the user to approve {phase_id}.", TurnEnded("request_approval")
)
def _target_architecture(self) -> TargetArchitecture | None:
deliverable = self._deliverables.get(_TARGET.value)
if not deliverable:
return None
try:
return parse_graph(deliverable.get("attachments", {})[GRAPH_ATTACHMENT])
except (KeyError, GraphError):
return None
async def reopen(self, kind: str, reason: str) -> ToolResult:
try:
result = self.ledger.reopen(
DeliverableKind(kind), reason, actor=ORCHESTRATOR
)
except (ValueError, LedgerRefusal) as exc:
return _refused(exc)
if result.escalation:
if self.ledger.pre_approved:
self.escalation = result.escalation
return ToolResult(result.escalation, TurnEnded("escalate"))
return ToolResult(
f"{result.escalation} Use ask_user to put this to the user."
)
withdrawn = ", ".join(result.withdrawn_approvals) or "none"
return ToolResult(
f"Reopened {kind}. Returned to draft: {', '.join(result.reset)}. "
f"Approvals withdrawn: {withdrawn}."
)
async def read_deliverable(self, kind: str) -> ToolResult:
deliverable = self._deliverables.get(kind)
if deliverable is None:
return ToolResult(f"{kind} has not been submitted.")
return ToolResult(deliverable["content"])
async def finish(self) -> ToolResult:
if not self.ledger.can_finish():
return _refused("packaging has not been approved")
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,
) -> list[ToolSpec]:
"""A Specialist's tools: submit, ask, 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.
"""
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)]
if unsafe:
return _refused(
"attachment names must be relative paths without '..': "
+ ", ".join(unsafe)
)
missing = check_submission(kind, content, attachments, upstream)
if missing:
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])
)
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
async def needs_input(
questions: Sequence[str], draft: str | None = None, attachments: Any = None
) -> ToolResult:
questions = tuple(q for q in questions if q)
if not questions:
return _refused("ask at least one question")
try:
draft_attachments = files_from_argument(attachments)
except TypeError as exc:
return _refused(f"attachments: {exc}")
return ToolResult(
"Questions sent to the user.",
NeedsInput(
questions, draft=draft or None, draft_attachments=draft_attachments
),
)
return [
ToolSpec(
"submit_deliverable",
f"Submit the {kind} Deliverable once it meets its contract. Ends your turn.",
_schema(
{
"content": {"type": "string"},
"attachments": FILES_SCHEMA,
},
["content"],
),
submit_deliverable,
tier="execution",
),
ToolSpec(
"needs_input",
"Ask the user questions you can't proceed without. Ends your turn. When "
"you are asking them to confirm a draft, pass it as `draft` (with its "
"`attachments`): it is returned to you with their answers.",
_schema(
{
"questions": {"type": "array", "items": {"type": "string"}},
"draft": {"type": "string"},
"attachments": FILES_SCHEMA,
},
["questions"],
),
needs_input,
tier="execution",
),
*(gate_cloud_read(tool, allow_cloud_read) for tool in extra),
]
def gate_cloud_read(tool: ToolSpec, allow_cloud_read: bool | None) -> ToolSpec:
"""Apply the Execution's cloud-read permission to a tool in that tier."""
if tool.tier != CLOUD_READ or allow_cloud_read is True:
return tool
if allow_cloud_read is False:
async def refuse(**_: Any) -> ToolResult:
return _refused(
"reading live cloud resources is not permitted for this Execution. "
"Work from what the user has told you and record the gap."
)
handler = refuse
else:
async def ask_permission(**_: Any) -> ToolResult:
return ToolResult(
"Permission to read live cloud resources is needed first.",
NeedsInput(
(
f"May I read live resources in your cloud environment? ({tool.name})",
),
permission=CLOUD_READ,
),
)
handler = ask_permission
return ToolSpec(tool.name, tool.description, tool.parameters, handler, tool.tier)