861 lines
34 KiB
Python
861 lines
34 KiB
Python
"""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 json
|
||
import logging
|
||
import re
|
||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||
from dataclasses import dataclass, field
|
||
from typing import Any, Protocol
|
||
|
||
from execution_engine.adk.runtime import (
|
||
AgentRuntime,
|
||
AgentTask,
|
||
Decider,
|
||
Outcome,
|
||
Question,
|
||
RoleSpec,
|
||
Stopped,
|
||
Submitted,
|
||
ToolResult,
|
||
ToolSpec,
|
||
)
|
||
from execution_engine.states.ledger import DeliverableStatus, Ledger, PhaseStatus
|
||
from execution_engine.tools.scoping import SCOPE_DATA_FILE
|
||
from execution_engine.workflows.workflow import ValidationPolicy, Workflow
|
||
|
||
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
|
||
# The user's reply answers "this Deliverable reached its Revision limit".
|
||
awaiting_limit_decision: bool = False
|
||
# Deliverables at their Revision limit that the user has been told about.
|
||
revision_limit_asked: Sequence[str] = ()
|
||
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[str, ...] = ()
|
||
phases_awaiting: tuple[str, ...] = () # asked for Approval, not yet decided
|
||
ready_work: tuple[str, ...] = ()
|
||
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: str | 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
|
||
|
||
|
||
# How much of the agreed requirements is shown to the decider with a user's message.
|
||
_AGREED_LIMIT = 24_000
|
||
|
||
# The actions that reopen a Deliverable, and which one.
|
||
_REOPENS = (
|
||
"revise_requested",
|
||
"revise_code",
|
||
"revise_target_architecture",
|
||
"revise_unimplementable",
|
||
)
|
||
|
||
|
||
def _reopened_by(action: str, readings: Readings, workflow: Workflow) -> str | None:
|
||
if action == "revise_requested":
|
||
return readings.change_target
|
||
validation = workflow.validation
|
||
if validation is None:
|
||
return None
|
||
if action == "revise_code":
|
||
return validation.implementation
|
||
if action in {"revise_target_architecture", "revise_unimplementable"}:
|
||
return validation.design
|
||
return None
|
||
|
||
|
||
def _attempt(ledger: Ledger, kind: str) -> int:
|
||
return int(ledger.to_dict()["deliverables"][str(kind)].get("attempt", 0))
|
||
|
||
|
||
def _submitted(ledger: Ledger) -> list[str]:
|
||
return [
|
||
kind
|
||
for kind in ledger.workflow.deliverables
|
||
if ledger.status(kind) is DeliverableStatus.SUBMITTED
|
||
]
|
||
|
||
|
||
def _mentioned(text: str, candidates: Sequence[str]) -> list[str]:
|
||
"""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 str(kind).replace("_", " ") in lowered]
|
||
|
||
|
||
def _failed_before(
|
||
outcomes: Sequence[Mapping[str, Any]], validation: ValidationPolicy
|
||
) -> 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") == validation.kind
|
||
]
|
||
if len(validations) < 2:
|
||
return set()
|
||
previous = validation.read(
|
||
validations[-2].get("attachments", {}).get(validation.data_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,
|
||
"awaiting_limit_decision": False,
|
||
}
|
||
readings = await self._read(view, result)
|
||
blocked: set[str] = set()
|
||
settled = view.validation_settled
|
||
# Told once, the user is not asked again: a Deliverable at its limit is no
|
||
# longer reopened, and the Execution carries on with it as it stands.
|
||
at_limit = set(view.revision_limit_asked)
|
||
|
||
async def call(tool: str, **arguments: Any) -> ToolResult:
|
||
return await by_name[tool].handler(**arguments)
|
||
|
||
for _ in range(MAX_STEPS):
|
||
barred = blocked | {
|
||
name
|
||
for name in _REOPENS
|
||
if (kind := _reopened_by(name, readings, view.ledger.workflow))
|
||
and str(kind) in at_limit
|
||
}
|
||
group, action = self._choose(view, readings, barred, 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 is told, once. Their reply is
|
||
# read as the answer to this, never as a new request for changes.
|
||
kind = _reopened_by(action, readings, view.ledger.workflow)
|
||
if kind:
|
||
at_limit.add(str(kind))
|
||
result.updates["revision_limit_asked"] = sorted(at_limit)
|
||
result.updates["awaiting_limit_decision"] = True
|
||
limit = await call(
|
||
"ask_user",
|
||
questions=[
|
||
reply.message.split(" Use ")[0]
|
||
+ " It will not be revised again in this Execution; I will "
|
||
"carry on with it as it stands. Reply to continue."
|
||
],
|
||
)
|
||
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 ledger.workflow.phases
|
||
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
|
||
readings.unimplementable = []
|
||
policy = ledger.workflow.validation
|
||
if policy is None:
|
||
return
|
||
if (
|
||
policy.unimplementable
|
||
and ledger.status(policy.implementation) is DeliverableStatus.SUBMITTED
|
||
):
|
||
readings.unimplementable = policy.unimplementable(view.deliverables)
|
||
|
||
validation = policy.kind
|
||
phase = ledger.workflow.deliverables[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 = policy.read(
|
||
view.deliverables.get(validation, {})
|
||
.get("attachments", {})
|
||
.get(policy.data_file, "")
|
||
)
|
||
before = _failed_before(view.outcomes, policy)
|
||
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 or view.awaiting_limit_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
|
||
asked = [str(question) for question in reply.get("asked") or ()]
|
||
# 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)
|
||
|
||
workflow = view.ledger.workflow
|
||
agreed = (
|
||
""
|
||
if structured or not workflow.agreed
|
||
else workflow.agreed(view.deliverables)[:_AGREED_LIMIT]
|
||
)
|
||
questions = {
|
||
"change_target": Question(
|
||
"choice",
|
||
"Which submitted Deliverable would have to change first to do what "
|
||
"the user asks?",
|
||
tuple(str(kind) 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?",
|
||
)
|
||
if agreed:
|
||
# Someone who restates what is already agreed is answering, however
|
||
# much it sounds like a requirement.
|
||
questions["already_agreed"] = Question(
|
||
"noul",
|
||
"Does the user's message only confirm or repeat what the agreed "
|
||
"requirements above already say, asking for nothing different?",
|
||
)
|
||
state = (
|
||
f"Submitted Deliverables: {', '.join(str(kind) for kind in candidates)}.\n"
|
||
+ (f"The agreed requirements:\n{agreed}\n" if agreed else "")
|
||
+ f"Questions waiting for the user: {len(view.pending_questions)}.\n"
|
||
# What we asked is background. Only the user's own words are their
|
||
# message: our question echoed back is not something they said.
|
||
+ (
|
||
"The user was replying to these questions from the agents:\n"
|
||
+ "\n".join(f"- {question}" for question in asked)
|
||
+ "\n"
|
||
if asked
|
||
else ""
|
||
)
|
||
+ 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)
|
||
restated = answers.get("already_agreed")
|
||
if restated is not None and restated.is_yes(self._thresholds.act):
|
||
# It restates what is agreed: an answer, not a change.
|
||
disposition = CLOSE
|
||
target_answer = answers["change_target"]
|
||
target = view.ledger.workflow.kind(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
|
||
policy = view.ledger.workflow.validation
|
||
known = (
|
||
policy.known_ids(view.deliverables)
|
||
if policy and policy.known_ids
|
||
else set()
|
||
)
|
||
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:
|
||
workflow = view.ledger.workflow
|
||
if action == "proceed":
|
||
return ToolResult("Proceeding.")
|
||
if action == "revise_requested":
|
||
assert r.change_target is not None
|
||
return await call(
|
||
"reopen", kind=str(r.change_target), reason=r.change_reason
|
||
)
|
||
if action == "confirm_change":
|
||
guess = str(r.change_target) if r.change_target else None
|
||
result.updates["pending_change"] = {"text": r.change_reason, "guess": guess}
|
||
options = ", ".join(str(kind) 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=str(_reopened_by(action, r, workflow)), 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
|
||
)
|
||
# In the run of 2026-10-09 a second Check with the same fault came back
|
||
# one Revision later, for the same reason word for word.
|
||
reason += (
|
||
" The same fault may be in other Checks: read every Check against "
|
||
"each reason given here and correct every one it applies to."
|
||
)
|
||
return await call(
|
||
"reopen", kind=str(_reopened_by(action, r, workflow)), reason=reason
|
||
)
|
||
if action == "revise_target_architecture":
|
||
return await call(
|
||
"reopen",
|
||
kind=str(_reopened_by(action, r, workflow)),
|
||
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=str(phase),
|
||
summary=await self._summary(phase, view, r),
|
||
)
|
||
if action == "delegate":
|
||
return await call("delegate", kinds=[str(kind) 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: str, view: TurnView, r: Readings) -> str:
|
||
facts = approval_facts(phase, view, r)
|
||
if self._writer is not None:
|
||
try:
|
||
written = await self._writer.approval_summary(str(phase), 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, view.ledger.workflow)
|
||
|
||
|
||
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: str, view: TurnView, r: Readings) -> dict[str, Any]:
|
||
"""What an Approval summary is written from: data, never Deliverable prose."""
|
||
workflow = view.ledger.workflow
|
||
kinds = workflow.deliverables_in(phase)
|
||
facts: dict[str, Any] = {
|
||
"phase": str(phase),
|
||
"deliverables": [str(kind) for kind in kinds],
|
||
"revisions": {
|
||
str(kind): view.ledger.revisions(kind)
|
||
for kind in kinds
|
||
if view.ledger.revisions(kind)
|
||
},
|
||
}
|
||
if workflow.approval_facts:
|
||
facts.update(workflow.approval_facts(phase, view.deliverables))
|
||
spec = workflow.spec_deliverable
|
||
scope = (view.deliverables.get(spec) or {}).get("attachments", {}) if spec else {}
|
||
if (
|
||
spec
|
||
and phase == workflow.deliverables[spec].phase
|
||
and scope.get(SCOPE_DATA_FILE)
|
||
):
|
||
# What approving the spec commits to: how much the customer stated, how
|
||
# much was assumed for them, and what is still unknown.
|
||
try:
|
||
agreed = json.loads(scope[SCOPE_DATA_FILE])
|
||
except ValueError:
|
||
agreed = {}
|
||
facts["scope"] = {
|
||
"kind": agreed.get("kind"),
|
||
"assumed": [item.get("field") for item in agreed.get("assumed", [])],
|
||
"left_to_decide": [
|
||
item.get("field") for item in agreed.get("to_decide", [])
|
||
],
|
||
"unknown": [item.get("field") for item in agreed.get("to_ask", [])],
|
||
}
|
||
policy = workflow.validation
|
||
validation = view.deliverables.get(policy.kind) if policy else None
|
||
if policy and validation and phase == workflow.deliverables[policy.kind].phase:
|
||
outcome = policy.read(
|
||
validation.get("attachments", {}).get(policy.data_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: str, facts: Mapping[str, Any], workflow: Workflow | None = None
|
||
) -> str:
|
||
"""An Approval summary from the facts alone, used when no writer is available."""
|
||
lines = [
|
||
(f"The {phase} Phase is ready: {', '.join(facts['deliverables'])} submitted.")
|
||
]
|
||
if workflow and workflow.summary_lines:
|
||
lines += list(workflow.summary_lines(phase, facts))
|
||
scope = facts.get("scope")
|
||
if scope:
|
||
lines.append(
|
||
f"Scope of a {scope.get('kind') or 'workload'}: "
|
||
f"{len(scope['assumed'])} fields assumed, "
|
||
f"{len(scope['unknown'])} still unknown. Requirements are derived "
|
||
"from it once you approve."
|
||
)
|
||
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
|