After case 02 (completed at 100%, but with two Revisions of the Target architecture for gaps validation found one pass at a time): - A Deliverable stands while what it was written from is unchanged. The architecture description is written from the Elements and Relationships, so a Revision that only adds or rewords Checks no longer runs the describer. - Non-functional requirements and recommendations list their conditions, one entry per separate thing that must be true; submission requires them. - A coverage review at submission (JEV_COVERAGE_REVIEW, off by default): for each condition, Jev chooses which Check verifies it, or none. Asked as one broad yes-or-no per requirement it could not tell a complete design from one with known gaps; asked as a choice per condition it raised all four known gaps of case 02 and nothing on the complete graph. An opt-in live test (LIVE_JEV=1) repeats that. - The validator is told to report every gap in its first pass. Plans record the case 02 run and both forms of the review with figures. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
828 lines
32 KiB
Python
828 lines
32 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"
|
|
|
|
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,
|
|
) -> 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", []))
|
|
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", {}),
|
|
}
|
|
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,
|
|
"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)),
|
|
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":
|
|
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,
|
|
),
|
|
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})
|
|
said = {"kind": "reply", "text": text}
|
|
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)
|
|
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"])
|
|
close(state, "completed_with_warnings", has_files=False)
|
|
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, {})),
|
|
"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 (pattern, answer) pairs where one matches."""
|
|
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", []):
|
|
answer = next(
|
|
(
|
|
scripted
|
|
for pattern, scripted in scripted_answers
|
|
if re.search(pattern, item["question"], 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 _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) -> None:
|
|
"""Write a finished Execution's files under its Customer case, with a manifest
|
|
that ties the request to what was generated for it."""
|
|
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", {})
|
|
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)}
|
|
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": "completed",
|
|
"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"
|
|
)
|