509 lines
20 KiB
Python
509 lines
20 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 execution_engine.adk.runtime import (
|
|
FILES_SCHEMA,
|
|
NeedsInput,
|
|
Submitted,
|
|
ToolResult,
|
|
ToolSpec,
|
|
TurnEnded,
|
|
files_from_argument,
|
|
)
|
|
from execution_engine.states.ledger import Ledger, LedgerRefusal, PhaseStatus
|
|
from execution_engine.tools.scoping import (
|
|
REGISTER_HEADING,
|
|
Scoping,
|
|
render_register,
|
|
scope_tools,
|
|
unsettled,
|
|
)
|
|
from execution_engine.tools.scoping import attachments as scope_attachments
|
|
from execution_engine.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 execution_engine.workflows.workflow import Bench, Workflow
|
|
|
|
ORCHESTRATOR = "orchestrator"
|
|
logger = logging.getLogger(__name__)
|
|
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._workflow: Workflow = ledger.workflow
|
|
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[str, 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 = [self._workflow.kind(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(self._workflow.deliverables).index(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 = self._workflow.phase(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,
|
|
"summary": summary,
|
|
"deliverables": [
|
|
str(kind) for kind in self._workflow.deliverables_in(phase_id)
|
|
],
|
|
}
|
|
if self._baseline:
|
|
self.approval["baseline"] = self._baseline.get("execution_id")
|
|
if self._workflow.approval_details:
|
|
# Worked out from the data, not written by an agent: what the user is
|
|
# approving, and in a Change request what this Phase changes.
|
|
self.approval.update(
|
|
self._workflow.approval_details(
|
|
phase_id, self._deliverables, self._baseline
|
|
)
|
|
)
|
|
return ToolResult(
|
|
f"Asked the user to approve {phase_id}.", TurnEnded("request_approval")
|
|
)
|
|
|
|
async def reopen(self, kind: str, reason: str) -> ToolResult:
|
|
try:
|
|
result = self.ledger.reopen(
|
|
self._workflow.kind(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("the last Phase has not been approved")
|
|
return ToolResult("Finishing the Execution.", TurnEnded("finish"))
|
|
|
|
|
|
def specialist_tools(
|
|
workflow: Workflow,
|
|
kind: str,
|
|
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,
|
|
scoping: Scoping | 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 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.
|
|
`scoping` is the spec's catalogue; with it the spec Deliverable's two files and
|
|
its information register are written from what was recorded.
|
|
"""
|
|
working = {} if working is None else working
|
|
spec = workflow.deliverables[kind]
|
|
shape = spec.graph
|
|
own_files = spec.working_copy == kind
|
|
reviewed = False
|
|
validation = workflow.validation
|
|
is_validation = validation is not None and kind == validation.kind
|
|
judged = (
|
|
((upstream or {}).get(validation.implementation) or {}).get("attachments")
|
|
if validation
|
|
else None
|
|
) or {}
|
|
# The validator's own copy of what it judges 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 work
|
|
check_ids: Sequence[str] = (
|
|
validation.check_ids(upstream)
|
|
if is_validation and validation and validation.check_ids
|
|
else ()
|
|
)
|
|
is_scope = kind == workflow.spec_deliverable and scoping is not None
|
|
bench = Bench(kind, working, upstream, baseline)
|
|
finish = workflow.on_submit.get(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}")
|
|
if is_scope and scoping is not None:
|
|
# Nothing essential may be left unknown, and the files are written
|
|
# from what was recorded: they cannot disagree with it.
|
|
missing_fields = unsettled(working, scoping)
|
|
if missing_fields:
|
|
return ToolResult(
|
|
"Not submitted. Essential fields of the scope spec are not "
|
|
"settled: " + ", ".join(missing_fields) + ". Ask the user for "
|
|
"each with `needs_input`; when you may not ask, choose a value "
|
|
"and record it with `source` assumed and a note."
|
|
)
|
|
attachments = scope_attachments(working, scoping)
|
|
content = (
|
|
content.split(f"\n## {REGISTER_HEADING}")[0].rstrip()
|
|
+ "\n\n"
|
|
+ render_register(working, scoping)
|
|
)
|
|
# The working copy is the submission; a file passed here replaces its copy.
|
|
if own_files:
|
|
attachments = {**working_files(working), **attachments}
|
|
if shape and shape.attachment not in attachments:
|
|
text = graph_text(working, shape)
|
|
if text:
|
|
attachments[shape.attachment] = text
|
|
if (
|
|
is_validation
|
|
and validation
|
|
and validation.data_file not in attachments
|
|
and verdicts_text(working)
|
|
):
|
|
attachments[validation.data_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 = workflow.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 shape and shape.attachment in attachments:
|
|
keep_graph(working, attachments[shape.attachment], shape)
|
|
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 finish:
|
|
# Views of the submission's own data, written by the Workflow's code:
|
|
# they cannot disagree with it.
|
|
content, attachments = finish(bench, content, dict(attachments))
|
|
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 ()
|
|
),
|
|
*(scope_tools(working, scoping) if is_scope and scoping else ()),
|
|
*(graph_tools(working, shape) if shape else ()),
|
|
*(verdict_tools(working, basis, check_ids) if is_validation else ()),
|
|
*(file_tools(working) if own_files else ()),
|
|
*(
|
|
gate_cloud_read(tool, allow_cloud_read)
|
|
for tool in extra
|
|
# Reading the cloud was refused for this Execution, so those tools are
|
|
# not offered: their definitions alone were half of what the
|
|
# requirements analyst was sent, for calls that could only be refused.
|
|
if not (tool.tier == CLOUD_READ and allow_cloud_read is False)
|
|
),
|
|
]
|
|
|
|
|
|
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)
|