A graded question per pillar (not at all, only indirectly, directly) picks the pillar advisors to consult again on a Revision or a Change request; the design advisor is told which, and keeps its earlier advice for the rest. As a yes or no the answer was yes for nearly every pillar of every change. A completed Execution now writes working.json with each pillar's advice and checklist review, and a Change request starts from its Baseline's, so only the pillars a change touches are consulted afresh. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1066 lines
42 KiB
Python
1066 lines
42 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,
|
|
Decider,
|
|
NeedsInput,
|
|
Outcome,
|
|
RoleSpec,
|
|
RunLimiter,
|
|
Stopped,
|
|
SubmissionReview,
|
|
Submitted,
|
|
ToolFactory,
|
|
ToolSpec,
|
|
TurnEnded,
|
|
)
|
|
from app.baseline import WORKING_FILENAME
|
|
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.tools.pillars import ADVICE_KEY, KEPT_FOR_CHANGES, pillars_touched
|
|
from app.workflows.chain import (
|
|
IMPLEMENTATION_FILE,
|
|
VERDICTS_FILE,
|
|
unimplementable_checks,
|
|
validation_outcome,
|
|
)
|
|
from app.workflows.changes import CHANGES_FILE, change_summary, is_empty
|
|
from app.workflows.deliverables import (
|
|
DEPENDENCY_GRAPH,
|
|
PHASE_ORDER,
|
|
DeliverableKind,
|
|
dependencies_for,
|
|
)
|
|
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
|
|
|
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,
|
|
decider: Decider | None = None,
|
|
pillar_threshold: float = 1.5,
|
|
) -> 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, state.get("baseline")
|
|
)
|
|
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":
|
|
hints = await _pillar_hints(
|
|
state, ledger, deliverables, toolbox.started, decider, pillar_threshold
|
|
)
|
|
sends = [
|
|
Send(
|
|
"specialist_task",
|
|
_specialist_input(
|
|
state, ledger, deliverables, drafts, kind, attempt, hints
|
|
),
|
|
)
|
|
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 {}
|
|
before = task_input.get("baseline")
|
|
if before and not working:
|
|
# A Change request starts from the Baseline's version, not from nothing:
|
|
# its graph, its files and its description are the working copy.
|
|
_start_from(kind, before, working, task_input.get("baseline_basis"))
|
|
# And from its working material: the advice it was written from.
|
|
working.update(task_input.get("baseline_working") 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,
|
|
baseline=before,
|
|
# 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,
|
|
hints: Mapping[str, Any] | None = None,
|
|
) -> dict[str, Any]:
|
|
spec = DEPENDENCY_GRAPH[kind]
|
|
given = dependencies_for(kind, deliverables)
|
|
baseline = state.get("baseline") or None
|
|
before = (baseline or {}).get("deliverables", {}).get(kind.value)
|
|
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", []),
|
|
# The Baseline's version of this Deliverable, in a Change request.
|
|
"baseline": before,
|
|
"baseline_working": dict(
|
|
(baseline or {}).get("working", {}).get(kind.value, {})
|
|
),
|
|
# What the Baseline's version was written from, to tell whether it still stands.
|
|
"baseline_basis": spec.written_from((baseline or {}).get("deliverables"))
|
|
if baseline and spec.written_from
|
|
else None,
|
|
"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,
|
|
# The pillars a change touches, when that could be judged: the design
|
|
# advisor consults those and keeps its earlier advice for the rest.
|
|
"pillars_to_consult": (hints or {}).get(kind.value),
|
|
# Set only in a Change request: what this Execution changes, and from what.
|
|
"baseline": _baseline_context(kind, baseline, before, deliverables)
|
|
if baseline
|
|
else None,
|
|
},
|
|
}
|
|
|
|
|
|
async def _pillar_hints(
|
|
state: ExecutionState,
|
|
ledger: Ledger,
|
|
deliverables: Mapping[str, Mapping[str, Any]],
|
|
started: Mapping[DeliverableKind, int],
|
|
decider: Decider | None,
|
|
threshold: float,
|
|
) -> dict[str, list[str]]:
|
|
"""Which pillars the design advisor should consult again, when it is being
|
|
started on a Revision or a Change request and advice from before exists."""
|
|
kind = DeliverableKind.DESIGN_RECOMMENDATIONS
|
|
if decider is None or kind not in started:
|
|
return {}
|
|
baseline = state.get("baseline") or {}
|
|
remembered = state.get("working", {}).get(kind.value, {}).get(
|
|
ADVICE_KEY
|
|
) or baseline.get("working", {}).get(kind.value, {}).get(ADVICE_KEY)
|
|
if not remembered:
|
|
return {} # a first consultation: every pillar
|
|
change = "\n".join(ledger.feedback(kind))
|
|
if not change and baseline:
|
|
summary = change_summary(baseline.get("deliverables"), deliverables)
|
|
change = "\n".join(
|
|
f"Requirement {item['id']} {item['change']}: {item['text']} "
|
|
f"({item['reason']})"
|
|
for item in summary["requirements"]
|
|
)
|
|
chosen = await pillars_touched(
|
|
decider,
|
|
list(remembered),
|
|
change,
|
|
threshold=threshold,
|
|
scope=state["execution_id"],
|
|
)
|
|
# None: no decision, so no hint and every pillar. An empty list is an answer.
|
|
return {} if chosen is None else {kind.value: chosen}
|
|
|
|
|
|
# The solution guide is assembled afresh from the revised Deliverables, so the
|
|
# Baseline's guide, the longest document there is, is not handed back to its author.
|
|
_NOT_HANDED_BACK = {DeliverableKind.SOLUTION_GUIDE}
|
|
|
|
|
|
def _baseline_context(
|
|
kind: DeliverableKind,
|
|
baseline: Mapping[str, Any],
|
|
before: Mapping[str, Any] | None,
|
|
deliverables: Mapping[str, Mapping[str, Any]],
|
|
) -> dict[str, Any]:
|
|
summary = change_summary(baseline.get("deliverables"), deliverables)
|
|
return {
|
|
"execution_id": baseline.get("execution_id"),
|
|
"original_request": baseline.get("workflow_request"),
|
|
"deliverable": dict(before)
|
|
if before and kind not in _NOT_HANDED_BACK
|
|
else None,
|
|
# What has changed so far, upstream of this Deliverable.
|
|
"changes": None if is_empty(summary) else summary,
|
|
}
|
|
|
|
|
|
def _start_from(
|
|
kind: DeliverableKind,
|
|
before: Mapping[str, Any],
|
|
working: dict[str, Any],
|
|
basis: str | None = None,
|
|
) -> None:
|
|
"""Make the Baseline's version of a Deliverable its working copy."""
|
|
attachments = dict(before.get("attachments", {}))
|
|
spec = DEPENDENCY_GRAPH[kind]
|
|
if kind is DeliverableKind.TARGET_ARCHITECTURE and GRAPH_ATTACHMENT in attachments:
|
|
workspace.keep_graph(working, attachments[GRAPH_ATTACHMENT])
|
|
if spec.working_copy is kind:
|
|
working[workspace.FILES] = attachments
|
|
if basis:
|
|
# Kept as it stands when what it was written from is the same as before.
|
|
working[STANDING] = {
|
|
"basis": basis,
|
|
"feedback": [],
|
|
"content": before.get("content", ""),
|
|
"attachments": attachments,
|
|
}
|
|
|
|
|
|
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,
|
|
}
|
|
kept = {
|
|
kind: {key: memory[key] for key in KEPT_FOR_CHANGES if memory.get(key)}
|
|
for kind, memory in state.get("working", {}).items()
|
|
}
|
|
kept = {kind: memory for kind, memory in kept.items() if memory}
|
|
if kept:
|
|
# Working material a Change request starts from, such as each pillar's advice.
|
|
files[WORKING_FILENAME] = json.dumps(kept, indent=2, ensure_ascii=False)
|
|
baseline = state.get("baseline") or None
|
|
if baseline:
|
|
# What this Change request changed against its Baseline, worked out from
|
|
# the ids in the two versions' data files.
|
|
files[CHANGES_FILE] = json.dumps(
|
|
change_summary(baseline.get("deliverables"), deliverables),
|
|
indent=2,
|
|
ensure_ascii=False,
|
|
)
|
|
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"],
|
|
# The Execution this one changes, for a Change request.
|
|
"baseline": (state.get("baseline") or {}).get("execution_id"),
|
|
"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,
|
|
"changes": CHANGES_FILE if baseline 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
|