Files
gcp_solution_architecture_a…/app/nodes/execution_nodes.py
Jonathan Boniface 654370bb46 feat: all four evaluation cases pass; intake, checklist review, thresholds
Case 04 (interactive)
- A scripted answer may name who it is for, so facts written for
  requirements discovery are not given to a Specialist confirming a draft.
- A reply that restates what the agreed requirements already say is read
  as an answer, not a request for changes.
- With a user present, a first submission is refused until the user has
  been shown a draft of that Deliverable (CONFIRM_DRAFTS).

Routing and reviews
- Intake: a message that starts something is read first. A question is
  answered and starts nothing; a change to delivered work starts as a new
  request with a note, until Change requests are built.
- Requirements and recommendations list what infrastructure code can show
  (conditions) apart from what it cannot (outside_code); the latter needs
  no Check and validation proposes nothing for it.
- A requirements review, "names no products", behind its own switch (off).
- Each pillar advisor reviews its pillar's checklist; the engine writes the
  reviews into the design recommendations. The judged checklist check went
  from 9-45% a pillar to 100% in one run of case 04.

Evaluation
- Per-case thresholds for Revisions, seconds and tokens, set from every
  completed run on this build.
- A progress file after every agent run, so an interrupted run keeps its
  time and tokens.
- eval/calibrate_judge.py with a 32-question set awaiting a person's
  labels. Unlabelled: Jev stable at 1.00, Gemini 0.92, agreeing on 0.91.

Smaller
- An Execution that ends with warnings writes its Deliverables, with the
  warnings and each status in the manifest.
- CI installs the application's dependencies before linting and testing.
- A load-balancer pattern in the IaC patterns Skill.

Plans record nine runs of 2026-10-08. Iteration 6 is complete.

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

923 lines
36 KiB
Python

"""The nodes of the Execution graph (ADR-0003); app/workflows/execution_graph.py wires them.
Only orchestrator_turn and await_user change the Ledger; parallel Specialist tasks
append outcomes that the next Orchestrator turn applies in order.
"""
from __future__ import annotations
import dataclasses
import json
import logging
import re
import time
from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from langgraph.types import Command, Send, interrupt
from app.adk.runtime import (
REJECTION_PREFIXES,
AgentRuntime,
AgentTask,
BudgetExhausted,
NeedsInput,
Outcome,
RoleSpec,
RunLimiter,
Stopped,
SubmissionReview,
Submitted,
ToolFactory,
ToolSpec,
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,
ExecutionState,
execution_dir,
lessons_file,
)
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 (
IMPLEMENTATION_FILE,
VERDICTS_FILE,
unimplementable_checks,
validation_outcome,
)
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
PHASE_ORDER,
DeliverableKind,
dependencies_for,
)
logger = logging.getLogger(__name__)
# Working-memory key: the last submission of a Deliverable with what it was written from.
STANDING = "standing"
# Questions put to the user running, with no work done between, before stopping.
MAX_IDLE_ASKS = 3
NO_USER_REPLY = (
"No user is available. State your assumption, record it in the Deliverable under "
"'Assumptions', and proceed."
)
GUIDE_FILENAME = "solution-architecture-guide.md"
MANIFEST_FILENAME = "execution.json" # request, status and files of one Execution
def _no_tools(
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
) -> Sequence[ToolSpec]:
return ()
@dataclass(frozen=True)
class ExecutionNodes:
"""The node functions of one Execution graph, bound to its runtime and recorder."""
orchestrator_turn: Callable[[ExecutionState], Awaitable[Command]]
# Receives its Send payload, not the Execution state.
specialist_task: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]]
await_user: Callable[[ExecutionState], Awaitable[Command]]
finalize: Callable[[ExecutionState], Awaitable[dict[str, Any]]]
end_with_warnings: Callable[[ExecutionState], Awaitable[dict[str, Any]]]
def make_execution_nodes(
*,
runtime: AgentRuntime,
roles: Mapping[str, RoleSpec],
recorder: ExecutionRecorder,
output_root: Path,
max_orchestrator_turns: int = 100,
tool_factory: ToolFactory | None = None,
limiter: RunLimiter | None = None,
skill_versions: Mapping[str, str] | None = None,
orchestrator: OrchestratorPolicy | None = None,
submission_review: SubmissionReview | None = None,
confirm_drafts: bool = False,
) -> 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(
output_root,
_case(state),
execution_id=state["execution_id"],
status=status,
has_files=has_files,
)
async def record_lessons(
state: ExecutionState, ledger: Ledger, status: str
) -> None:
record = collect_lesson_candidates(
execution_id=state["execution_id"],
customer_case=_case(state),
status=status,
ledger=ledger,
outcomes=state.get("outcomes", []),
orchestrator_refusals=state.get("refusals", []),
role_skills={name: role.skills for name, role in roles.items()},
skill_versions=skill_versions or {},
)
# Kept apart from deliverables/: an Execution that ends with warnings writes
# no Deliverable files, but what went wrong in it is still worth keeping.
path = lessons_file(output_root, state["execution_id"], _case(state))
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
json.dumps(record, indent=2, ensure_ascii=False), encoding="utf-8"
)
await recorder.record_lesson_candidates(state["execution_id"], record)
async def record_progress(
state: ExecutionState, ledger: Ledger, status: str | None = None
) -> int:
recorded = state.get("events_recorded", 0)
for event in ledger.events[recorded:]:
logger.info(
"[%s] ledger %s %s by %s%s",
state["execution_id"],
event.type,
event.subject,
event.actor,
f" ({event.detail})" if event.detail else "",
)
await recorder.record_events(state["execution_id"], ledger.events[recorded:])
if status:
await recorder.record_status(
state["execution_id"],
session_id=state["session_id"],
workflow_request=state["workflow_request"],
status=status,
current_phase=_current_phase(ledger),
details={
"revisions": sum(
ledger.revisions(kind) for kind in DEPENDENCY_GRAPH
),
"warnings": state.get("warnings", []),
"customer_case": _case(state),
},
)
return len(ledger.events)
async def orchestrator_turn(state: ExecutionState) -> Command:
ledger = Ledger.from_dict(state["ledger"])
deliverables = dict(state.get("deliverables", {}))
pending_questions = list(state.get("pending_questions", []))
notes = list(state.get("notes", []))
pending_permission = state.get("pending_permission")
warnings = list(state.get("warnings", []))
shown = list(state.get("drafts_shown", []))
drafts = dict(state.get("drafts", {}))
outcomes = state.get("outcomes", [])
for record in outcomes[state.get("outcomes_applied", 0) :]:
kind = DeliverableKind(record["kind"])
try:
if record["type"] == "submitted":
ledger.submit(kind, record["attempt"], actor=record["role"])
deliverables[kind.value] = {
"content": record["content"],
"attachments": record["attachments"],
}
drafts.pop(kind.value, None)
await recorder.record_submission(
state["execution_id"],
kind.value,
record["content"],
record["attachments"],
)
continue
ledger.release(kind, record["attempt"], reason=record["type"])
except LedgerRefusal as exc:
notes.append(f"Discarded a superseded result for {kind}: {exc}")
continue
if record["type"] == "needs_input" and record.get("permission"):
if state.get("allow_cloud_read") is None:
requested = (pending_permission or {}).get("requested_by", [])
pending_permission = {
"tier": record["permission"],
"requested_by": [*requested, kind.value],
}
continue
if record.get("draft"):
drafts[kind.value] = {
"content": record["draft"],
"attachments": record.get("draft_attachments", {}),
}
# The user is being shown this Deliverable.
if kind.value not in shown:
shown.append(kind.value)
questions = record.get("questions") or [
(
f"The {record['role']} stopped: {record['summary']} "
"How should it proceed?"
)
]
pending_questions.append({"kind": kind.value, "questions": questions})
turns = state.get("turns", 0) + 1
update: dict[str, Any] = {
"deliverables": deliverables,
"drafts": drafts,
"drafts_shown": shown,
"pending_questions": pending_questions,
"pending_permission": pending_permission,
"outcomes_applied": len(outcomes),
"turns": turns,
}
def finish_with(goto: str, **extra: Any) -> Command:
return Command(
update={**update, "ledger": ledger.to_dict(), "notes": notes, **extra},
goto=goto,
)
if pending_permission and not state.get("pre_approved"):
update["events_recorded"] = await record_progress(
state, ledger, "awaiting_user"
)
return finish_with("await_user", prompt={"permission": pending_permission})
if turns > max_orchestrator_turns:
warnings.append(
f"Stopped after {max_orchestrator_turns} Orchestrator turns without "
"finishing."
)
return finish_with("end_with_warnings", warnings=warnings)
toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions)
refusals = list(state.get("refusals", []))
update["refusals"] = refusals
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)),
awaiting_limit_decision=bool(state.get("awaiting_limit_decision")),
revision_limit_asked=tuple(state.get("revision_limit_asked", ())),
context=_orchestrator_context(
state, ledger, deliverables, pending_questions, notes
),
)
started = time.monotonic()
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"],
turns,
_current_phase(ledger),
time.monotonic() - started,
_summarise_outcome(outcome),
)
notes = []
pre_approved = bool(state.get("pre_approved"))
conversation = list(state.get("conversation", []))
def ask(prompt: dict[str, Any], **extra: Any) -> Command:
conversation.append({"from": ORCHESTRATOR, "text": _render_prompt(prompt)})
return finish_with(
"await_user", prompt=prompt, conversation=conversation, **extra
)
if isinstance(outcome, TurnEnded) and outcome.tool == "delegate":
sends = [
Send(
"specialist_task",
_specialist_input(
state, ledger, deliverables, drafts, kind, attempt
),
)
for kind, attempt in toolbox.started.items()
]
update["events_recorded"] = await record_progress(state, ledger)
return Command(
update={**update, "ledger": ledger.to_dict(), "notes": notes},
goto=sends,
)
if isinstance(outcome, TurnEnded) and outcome.tool == "finish":
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("finalize")
if isinstance(outcome, TurnEnded) and outcome.tool == "escalate":
warnings.append(toolbox.escalation or "Escalated without detail.")
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("end_with_warnings", warnings=warnings)
if isinstance(outcome, TurnEnded) and outcome.tool == "request_approval":
update["events_recorded"] = await record_progress(
state, ledger, None if pre_approved else "awaiting_user"
)
return ask({"approval": toolbox.approval})
if isinstance(outcome, TurnEnded) and outcome.tool == "ask_user":
# Asking again and again with nothing done in between is a loop, not a
# conversation: stop it, whatever caused it.
fingerprint = _progress(ledger)
idle = (
state.get("idle_asks", 0) + 1
if fingerprint == state.get("ask_fingerprint")
else 0
)
update.update(idle_asks=idle, ask_fingerprint=fingerprint)
if idle >= MAX_IDLE_ASKS:
warnings.append(
f"Stopped: the user was asked {idle + 1} times running with "
"no work done in between."
)
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("end_with_warnings", warnings=warnings)
update["events_recorded"] = await record_progress(
state, ledger, None if pre_approved else "awaiting_user"
)
return ask(
{"questions": toolbox.questions},
pending_questions=[],
awaiting_questions=pending_questions,
)
message = _describe_unfinished(outcome)
if pre_approved:
warnings.append(f"The Orchestrator could not continue: {message}")
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("end_with_warnings", warnings=warnings)
update["events_recorded"] = await record_progress(
state, ledger, "awaiting_user"
)
return ask({"questions": [{"from": ORCHESTRATOR, "question": message}]})
async def specialist_task(task_input: dict[str, Any]) -> dict[str, Any]:
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", {})
)
spec = DEPENDENCY_GRAPH[kind]
# Feedback on this Deliverable itself. A note that a dependency was revised
# is not a reason to write it again; the basis says whether that matters.
feedback = [
item
for item in task_input["context"].get("feedback") or []
if not str(item).startswith("Dependency ")
]
basis = spec.written_from(upstream) if spec.written_from else None
standing = working.get(STANDING)
if (
basis
and isinstance(standing, Mapping)
and standing.get("basis") == basis
and standing.get("feedback") == feedback
):
# What it was written from has not changed, so the last submission
# still stands: no Specialist is run.
logger.info(
"[%s] %s kept %s (attempt %d): written from an unchanged basis",
task_input["execution_id"],
role.name,
kind,
task_input["attempt"],
)
kept = Submitted(standing["content"], dict(standing["attachments"]))
return {
"outcomes": [
{
**_outcome_record(role.name, kind, task_input["attempt"], kept),
"refusals": [],
}
],
"working": {kind.value: working},
}
async def review(attachments: Mapping[str, str]) -> Sequence[str]:
assert submission_review is not None
return await submission_review(
kind, attachments, upstream, task_input["execution_id"]
)
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=upstream,
working=working,
library=task_input.get("library"),
review=review if submission_review else None,
# With a user present, their first sight of a Deliverable comes
# before it is submitted, whatever the Specialist intends.
confirm_first=confirm_drafts
and not task_input["context"].get("pre_approved", True)
and not task_input.get("shown"),
),
refusals,
role.name,
kind.value,
)
task = AgentTask(
role=role.name,
prompt=f"Produce the {kind} Deliverable.",
context=task_input["context"],
deliverable=kind.value,
)
logger.info(
"[%s] %s started %s (attempt %d)",
task_input["execution_id"],
role.name,
kind,
task_input["attempt"],
)
started = time.monotonic()
try:
if limiter:
async with limiter.slot():
outcome: Outcome = await runtime.run(role, task, tools)
else:
outcome = await runtime.run(role, task, tools)
except Exception as exc:
logger.exception("Specialist %s failed on %s", role.name, kind)
outcome = Stopped(f"it failed with {type(exc).__name__}: {exc}")
logger.info(
"[%s] %s finished %s in %.0fs: %s",
task_input["execution_id"],
role.name,
kind,
time.monotonic() - started,
_summarise_outcome(outcome),
)
if basis and isinstance(outcome, Submitted):
working[STANDING] = {
"basis": basis,
"feedback": feedback,
"content": outcome.content,
"attachments": dict(outcome.attachments),
}
return {
"outcomes": [
{
**_outcome_record(role.name, kind, task_input["attempt"], outcome),
"refusals": refusals,
}
],
"working": {kind.value: working},
}
async def await_user(state: ExecutionState) -> Command:
prompt = state["prompt"] or {}
if state.get("pre_approved"):
reply = automatic_reply(prompt, state.get("scripted_answers", []))
else:
reply = interrupt(prompt)
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"]
decision = reply.get("approval") if isinstance(reply, Mapping) else None
if (
isinstance(decision, Mapping)
and decision.get("phase") == phase
and decision.get("decision") in {"approve", "changes"}
):
phase_id = next(p for p in PHASE_ORDER if p.value == phase)
if decision["decision"] == "approve":
ledger.approve(phase_id, actor="user")
text = f"Approved {phase}."
else:
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
grant = permission.get(tier) if isinstance(permission, Mapping) else None
if isinstance(grant, bool):
update["allow_cloud_read"] = grant
update["pending_permission"] = None
verdict = "granted" if grant else "denied"
conversation.append(
{
"from": "user",
"text": f"Permission to use {tier} tools {verdict}.",
}
)
else:
conversation.append({"from": "user", "text": _reply_text(reply)})
else:
text = _reply_text(reply)
conversation.append({"from": "user", "text": text})
put = [item["question"] for item in prompt.get("questions", [])]
# What is routed is what the user said, not our questions quoted back.
said = {"kind": "reply", "text": _own_words(text, put), "asked": put}
answers = {
kind: list(items) for kind, items in state.get("answers", {}).items()
}
for asked in state.get("awaiting_questions", []):
answers.setdefault(asked["kind"], []).append(
{"questions": list(asked["questions"]), "reply": text}
)
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")
async def finalize(state: ExecutionState) -> dict[str, Any]:
ledger = Ledger.from_dict(state["ledger"])
_write_outputs(output_root, state, "completed", ledger)
close(state, "completed", has_files=True)
await record_progress(state, ledger, "completed")
await record_lessons(state, ledger, "completed")
return {"status": "completed"}
async def end_with_warnings(state: ExecutionState) -> dict[str, Any]:
ledger = Ledger.from_dict(state["ledger"])
# What was produced is kept, marked as unfinished: a person deciding what to
# do next needs to read it, and it is the evidence of what went wrong.
wrote = _write_outputs(output_root, state, "completed_with_warnings", ledger)
close(state, "completed_with_warnings", has_files=wrote)
await record_progress(state, ledger, "completed_with_warnings")
await record_lessons(state, ledger, "completed_with_warnings")
return {"status": "completed_with_warnings"}
return ExecutionNodes(
orchestrator_turn=orchestrator_turn,
specialist_task=specialist_task,
await_user=await_user,
finalize=finalize,
end_with_warnings=end_with_warnings,
)
# --- helpers ---------------------------------------------------------------------------
def _noting_refusals(
tools: Sequence[ToolSpec],
sink: list[dict[str, Any]],
role: str,
deliverable: str | None,
) -> list[ToolSpec]:
"""The same tools, noting each reply that means the call did nothing."""
def noting(tool: ToolSpec) -> ToolSpec:
async def handler(**kwargs: Any) -> Any:
result = await tool.handler(**kwargs)
if result.outcome is None and result.message.startswith(REJECTION_PREFIXES):
sink.append(
refusal(role, deliverable, tool.name, tool.tier, result.message)
)
return result
return dataclasses.replace(tool, handler=handler)
return [noting(tool) for tool in tools]
def _summarise_outcome(outcome: Outcome) -> str:
if isinstance(outcome, TurnEnded):
return f"called {outcome.tool}"
if isinstance(outcome, Submitted):
return f"submitted ({len(outcome.content)} chars)"
if isinstance(outcome, NeedsInput):
return f"needs input ({len(outcome.questions)} questions)"
if isinstance(outcome, BudgetExhausted):
return f"budget exhausted: {outcome.summary[:200]}"
return f"stopped: {outcome.message[:200]}"
def _current_phase(ledger: Ledger) -> str:
for phase in PHASE_ORDER:
if ledger.phase_status(phase).value != "approved":
return phase.value
return PHASE_ORDER[-1].value
def _orchestrator_context(
state: ExecutionState,
ledger: Ledger,
deliverables: Mapping[str, Mapping[str, Any]],
pending_questions: Sequence[Mapping[str, Any]],
notes: Sequence[str],
) -> dict[str, Any]:
# Only a validation that still stands: once anything it judged is reopened, its
# verdicts are about work that no longer exists.
validation = (
deliverables.get(DeliverableKind.VALIDATION_RESULTS.value)
if ledger.status(DeliverableKind.VALIDATION_RESULTS)
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(
validation.get("attachments", {}).get(VERDICTS_FILE, "")
)
if validation
else None,
"workflow_request": state["workflow_request"],
"pre_approved": bool(state.get("pre_approved")),
"allow_cloud_read": state.get("allow_cloud_read"),
"deliverables": {
kind.value: {
"phase": spec.phase.value,
"status": ledger.status(kind).value,
"revisions": ledger.revisions(kind),
"feedback": list(ledger.feedback(kind)),
}
for kind, spec in DEPENDENCY_GRAPH.items()
},
"phases": {
phase.value: ledger.phase_status(phase).value for phase in PHASE_ORDER
},
"ready_work": [kind.value for kind in ledger.ready_work()],
"phases_ready_for_approval": [
p.value for p in ledger.phases_ready_for_approval()
],
"pending_questions": list(pending_questions),
"conversation": list(state.get("conversation", []))[-20:],
"notes": list(notes),
}
def _specialist_input(
state: ExecutionState,
ledger: Ledger,
deliverables: Mapping[str, Mapping[str, Any]],
drafts: Mapping[str, Mapping[str, Any]],
kind: DeliverableKind,
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,
"allow_cloud_read": state.get("allow_cloud_read"),
"working": dict(state.get("working", {}).get(kind.value, {})),
# Whether the user has been shown a draft of this Deliverable. Answering some
# other question about it, such as what to do after it stopped, is not that.
"shown": kind.value in state.get("drafts_shown", []),
"context": {
"workflow_request": state["workflow_request"],
"pre_approved": bool(state.get("pre_approved")),
"contract": spec.contract(),
"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,
},
}
def _outcome_record(
role: str, kind: DeliverableKind, attempt: int, outcome: Outcome
) -> dict[str, Any]:
base = {"role": role, "kind": kind.value, "attempt": attempt}
if isinstance(outcome, Submitted):
return {
**base,
"type": "submitted",
"content": outcome.content,
"attachments": dict(outcome.attachments),
}
if isinstance(outcome, NeedsInput):
return {
**base,
"type": "needs_input",
"questions": list(outcome.questions),
"permission": outcome.permission,
"draft": outcome.draft,
"draft_attachments": dict(outcome.draft_attachments),
}
if isinstance(outcome, BudgetExhausted):
return {**base, "type": "budget_exhausted", "summary": outcome.summary}
return {**base, "type": "stopped", "summary": _describe_unfinished(outcome)}
def _describe_unfinished(outcome: Outcome) -> str:
if isinstance(outcome, BudgetExhausted):
return f"I paused: {outcome.summary} How should I proceed?"
if isinstance(outcome, Stopped):
return outcome.message
if isinstance(outcome, NeedsInput):
return " ".join(outcome.questions)
return f"Ended with an unexpected outcome: {type(outcome).__name__}."
def automatic_reply(
prompt: Mapping[str, Any], scripted_answers: Sequence[Sequence[str]] = ()
) -> dict[str, Any]:
"""The reply in a pre-approved Execution: approve, deny cloud reads, and answer
questions from scripted answers where one matches.
A scripted answer is (pattern, answer) or (pattern, answer, asker). It answers a
question its pattern matches; with an asker, only when that pattern also matches
who is asking (a Deliverable kind, or the orchestrator). The first that applies
wins. So facts written for requirements discovery are not given to a later
Specialist that only wants its draft confirmed.
"""
if "approval" in prompt:
return {
"approval": {"phase": prompt["approval"]["phase"], "decision": "approve"}
}
if "permission" in prompt:
return {"permission": {prompt["permission"]["tier"]: False}}
lines = []
unanswered = False
for item in prompt.get("questions", []):
asker = str(item.get("from", ""))
answer = next(
(
scripted[1]
for scripted in scripted_answers
if re.search(scripted[0], item["question"], re.IGNORECASE)
and (len(scripted) < 3 or re.search(scripted[2], asker, re.IGNORECASE))
),
None,
)
if answer is None:
unanswered = True
else:
lines.append(f"Q: {item['question']}\nA: {answer}")
if unanswered or not lines:
lines.append(NO_USER_REPLY)
return {"reply": "\n\n".join(lines)}
def _reply_text(reply: object) -> str:
if isinstance(reply, str):
return reply
if isinstance(reply, Mapping) and isinstance(reply.get("reply"), str):
return reply["reply"]
return str(reply)
def _own_words(text: str, asked: Sequence[str]) -> str:
"""A reply without the questions it quotes, and without Q: and A: labels."""
for question in sorted(asked, key=len, reverse=True):
text = text.replace(question, "")
lines = []
for line in text.splitlines():
line = re.sub(r"^\s*(?:Q|A)\s*:\s*", "", line).strip()
if line:
lines.append(line)
return "\n".join(lines)
def _progress(ledger: Ledger) -> str:
"""The work done so far, as one comparable value: each Deliverable's status and
attempt, and each Phase's status."""
data = ledger.to_dict()
return json.dumps(
{
"deliverables": {
kind: [record.get("status"), record.get("attempt")]
for kind, record in data["deliverables"].items()
},
"phases": data.get("phases"),
},
sort_keys=True,
default=str,
)
def _render_prompt(prompt: Mapping[str, Any]) -> str:
if "approval" in prompt:
approval = prompt["approval"]
return f"Please approve {approval['phase']}: {approval['summary']}"
if "permission" in prompt:
return f"May I use {prompt['permission']['tier']} tools?"
return "\n".join(item["question"] for item in prompt.get("questions", []))
def _case(state: ExecutionState) -> str:
return state.get("customer_case") or UNASSIGNED_CASE
def _write_outputs(
output_root: Path, state: ExecutionState, status: str, ledger: Ledger
) -> bool:
"""Write an Execution's files under its Customer case, with a manifest that ties
the request to what was generated for it. Returns whether anything was written.
An Execution that ended with warnings is written too. Its manifest carries the
warnings and each Deliverable's status, so nothing unapproved reads as final.
"""
customer_case = _case(state)
execution_id = state["execution_id"]
out_dir = execution_dir(output_root, execution_id, customer_case)
deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {})
if not deliverables:
return False
files: dict[str, str] = {}
by_kind: dict[str, dict[str, Any]] = {}
guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value)
if guide:
files[GUIDE_FILENAME] = guide["content"]
for kind, deliverable in deliverables.items():
document = f"deliverables/{kind}.md"
files[document] = deliverable["content"]
attachments = dict(deliverable.get("attachments", {}))
files.update(attachments)
by_kind[kind] = {
"document": document,
"attachments": sorted(attachments),
# submitted, or back in draft after something it depends on was reopened
"status": ledger.status(DeliverableKind(kind)).value,
}
for name, content in files.items():
path = out_dir / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8")
manifest = {
"customer_case": customer_case,
"execution_id": execution_id,
"session_id": state.get("session_id"),
"intent_version": state.get("intent_version"),
"workflow_request": state["workflow_request"],
"status": status,
"warnings": list(state.get("warnings", [])),
"phases": {
phase.value: ledger.phase_status(phase).value for phase in PHASE_ORDER
},
"solution_guide": GUIDE_FILENAME if guide else None,
"deliverables": by_kind,
}
out_dir.mkdir(parents=True, exist_ok=True)
(out_dir / MANIFEST_FILENAME).write_text(
json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8"
)
return True