A caller restates a request to say how requirements have changed, naming a completed Execution of the same Customer case as the Baseline. - app/baseline.py reads a Baseline from its files and refuses one that does not exist, did not complete or belongs to another case, before anything runs or is recorded. A Baseline is never modified. - Requirements carry a change (unchanged, added, changed, removed) and a reason. Submission is refused when a Baseline requirement disappears, an id is reused, or an unchanged requirement's text differs. A removed requirement stays on record and asks nothing downstream. - Each Specialist starts from its delivered version; the graph and the code are its working copy, and the description is carried over when the design's shape is the same. - app/workflows/changes.py compares versions by id and traces what each changed requirement reaches; anything else that changed is listed as unrequested. Approvals show the change for their Phase, and changes.json is written with the full Deliverables. - Intake no longer starts a message read as a change: it names the Execution to give as the Baseline. - A fifth evaluation case runs a request and then a change to it, with four checks that the change is recorded, reaches Checks, stays contained and costs less than its Baseline. Tested with scripted agents only; no Change request has run with real models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
499 lines
19 KiB
Python
499 lines
19 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
|
|
|
|
import logging
|
|
from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence
|
|
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.tools.pillars import REVIEW_HEADING, render_checklist_review
|
|
from app.tools.workspace import (
|
|
FILES,
|
|
basis_of,
|
|
file_tools,
|
|
graph_text,
|
|
graph_tools,
|
|
keep_graph,
|
|
safe_relative,
|
|
verdict_tools,
|
|
verdicts_text,
|
|
working_files,
|
|
working_verdicts,
|
|
)
|
|
from app.workflows.chain import VERDICTS_FILE, read_graph
|
|
from app.workflows.changes import change_summary, changes_for
|
|
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,
|
|
render_tables,
|
|
)
|
|
|
|
ORCHESTRATOR = "orchestrator"
|
|
logger = logging.getLogger(__name__)
|
|
_TARGET = DeliverableKind.TARGET_ARCHITECTURE
|
|
_CODE = DeliverableKind.DEPLOYMENT_GUIDANCE
|
|
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]],
|
|
baseline: Mapping[str, Any] | None = None,
|
|
) -> None:
|
|
self.ledger = ledger
|
|
self._deliverables = deliverables
|
|
self._pending_questions = pending_questions
|
|
# A Change request's Baseline: with it, an Approval shows what changed.
|
|
self._baseline = baseline
|
|
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)],
|
|
}
|
|
if self._baseline:
|
|
# Worked out from the ids, not written by an agent: what this Phase's
|
|
# Deliverables add, change and remove against the Baseline.
|
|
self.approval["baseline"] = self._baseline.get("execution_id")
|
|
self.approval["changes"] = changes_for(
|
|
change_summary(self._baseline.get("deliverables"), self._deliverables),
|
|
self.approval["deliverables"],
|
|
)
|
|
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 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,
|
|
review: Callable[[Mapping[str, str]], Awaitable[Sequence[str]]] | None = None,
|
|
confirm_first: bool = False,
|
|
baseline: Mapping[str, Any] | None = None,
|
|
) -> list[ToolSpec]:
|
|
"""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. `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.
|
|
`review` looks at the meaning of a structurally complete submission; what it
|
|
raises is returned to the Specialist once per run, and never a second time.
|
|
`confirm_first` is set while a user is present and has not yet been asked about
|
|
this Deliverable: a submission is then refused until the Specialist has put its
|
|
draft to them. A rule, because an instruction alone was not always followed.
|
|
`baseline` is the Baseline's version of this Deliverable in a Change request.
|
|
"""
|
|
working = {} if working is None else working
|
|
is_graph = kind is DeliverableKind.TARGET_ARCHITECTURE
|
|
own_files = DEPENDENCY_GRAPH[kind].working_copy is kind
|
|
reviewed = False
|
|
is_validation = kind is DeliverableKind.VALIDATION_RESULTS
|
|
judged = ((upstream or {}).get(_CODE.value) or {}).get("attachments") or {}
|
|
# The validator's own copy of the code is the same files; either marks them.
|
|
basis = basis_of(judged or working.get(FILES) or {})
|
|
if is_validation:
|
|
working_verdicts(working, basis) # drops verdicts given on other code
|
|
graph_now = read_graph(upstream)
|
|
|
|
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}")
|
|
# 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)
|
|
if (
|
|
is_validation
|
|
and VERDICTS_FILE not in attachments
|
|
and verdicts_text(working)
|
|
):
|
|
attachments[VERDICTS_FILE] = verdicts_text(working)
|
|
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, baseline=baseline
|
|
)
|
|
if missing:
|
|
return ToolResult(
|
|
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
|
|
)
|
|
if own_files:
|
|
working_files(working).update(attachments)
|
|
if is_graph:
|
|
keep_graph(working, attachments[GRAPH_ATTACHMENT])
|
|
nonlocal reviewed
|
|
if review and not reviewed:
|
|
reviewed = True
|
|
try:
|
|
concerns = await review(attachments)
|
|
except Exception: # a review must never stop a submission
|
|
logger.exception("The submission review failed; accepting")
|
|
concerns = ()
|
|
if concerns:
|
|
return ToolResult(
|
|
"Not submitted. A review found: "
|
|
+ "; ".join(concerns)
|
|
+ ". Look at each one: add what is missing, or leave it when "
|
|
"it is already covered. This review runs once, so your next "
|
|
"submission is accepted."
|
|
)
|
|
if confirm_first:
|
|
return ToolResult(
|
|
"Not submitted. The user has not seen this Deliverable yet. Call "
|
|
"`needs_input` with a short summary asking them to approve it or "
|
|
"request changes, passing this content as `draft` with its "
|
|
"attachments. What you have recorded is kept. Submit when they "
|
|
"have replied."
|
|
)
|
|
if kind is DeliverableKind.DESIGN_RECOMMENDATIONS:
|
|
# The pillar advisors' checklist reviews, written from what they
|
|
# recorded. A Revision replaces the section, never stacks a second.
|
|
checklist_review = render_checklist_review(working)
|
|
content = content.split(f"\n## {REVIEW_HEADING}")[0].rstrip() + "\n"
|
|
if checklist_review:
|
|
content += "\n" + checklist_review
|
|
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])
|
|
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:
|
|
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",
|
|
),
|
|
*(
|
|
[
|
|
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 ()),
|
|
*(
|
|
verdict_tools(working, basis, graph_now.check_ids if graph_now else ())
|
|
if is_validation
|
|
else ()
|
|
),
|
|
*(file_tools(working) if own_files else ()),
|
|
*(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)
|