Iteration 4: - Overlay Skills (step 12): an Execution names an organisation's standards Skill from the folders the deployment configures; recorded with its version. An example standards Skill and an evaluation case that uses it. - Lessons (step 10): a prove command that compares a run with lessons against one without, and triage of evidence an existing lesson already covers. Iteration 5: - Step 8: the references of a Specialist's Skills its task needs are named in its context as read_first. - Step 14: a remote MCP server's reply that instructs the agent is withheld; the user's own text is flagged as a risk and nothing more. - Step 15: in a Change request, items only reworded are listed apart from real changes. - Step 19: each Execution's design recommendations are judged when it ends and the scores kept in its record. The evaluation takes its rubric from the same place. Each question was calibrated against live Jev; none has run in a case. Steps 6, 7, 9, 13 and 18 stay planned, with the reasons in the plan map. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1263 lines
50 KiB
Python
1263 lines
50 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 asyncio
|
|
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.assessment import assess
|
|
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
|
|
from app.tools.guardrail import EXECUTION_SCOPE, instructs_agent
|
|
from app.tools.meaning import settle_meaning
|
|
from app.tools.pillars import ADVICE_KEY, KEPT_FOR_CHANGES, pillars_touched
|
|
from app.tools.skill_routing import read_first
|
|
from app.workflows.chain import (
|
|
IMPLEMENTATION_FILE,
|
|
VERDICTS_FILE,
|
|
unimplementable_checks,
|
|
validation_outcome,
|
|
)
|
|
from app.workflows.changes import CHANGES_FILE, _graph, 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,
|
|
reworded_threshold: float = 0.25,
|
|
guard_user_text: bool = False,
|
|
guard_threshold: float = 0.75,
|
|
skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
|
|
skill_threshold: float = 1.25,
|
|
assess_at_end: 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 {}),
|
|
**(state.get("overlay_skills") 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)
|
|
|
|
update["risks"] = await _flagged(state, turns)
|
|
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
|
|
)
|
|
reading = await _reading_hints(
|
|
state,
|
|
ledger,
|
|
deliverables,
|
|
toolbox.started,
|
|
decider,
|
|
skill_references or {},
|
|
skill_threshold,
|
|
)
|
|
sends = [
|
|
Send(
|
|
"specialist_task",
|
|
_specialist_input(
|
|
state,
|
|
ledger,
|
|
deliverables,
|
|
drafts,
|
|
kind,
|
|
attempt,
|
|
hints,
|
|
reading.get(kind),
|
|
),
|
|
)
|
|
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 _flagged(state: ExecutionState, turn: int) -> list[dict[str, Any]]:
|
|
"""Risk flags on what the user wrote: recorded for a person, never acted on."""
|
|
risks = list(state.get("risks", []))
|
|
if not guard_user_text or decider is None:
|
|
return risks
|
|
reply = state.get("last_reply") or {}
|
|
text = state["workflow_request"] if turn == 1 else str(reply.get("text", ""))
|
|
if not text.strip():
|
|
return risks
|
|
try:
|
|
likelihood = await instructs_agent(decider, text, state["execution_id"])
|
|
except Exception: # a flag is never worth an Execution
|
|
logger.exception("The guardrail failed on the user's text")
|
|
return risks
|
|
if likelihood is not None and likelihood >= guard_threshold:
|
|
risks.append(
|
|
{
|
|
"risk": "instructs_agent",
|
|
"where": "workflow_request" if turn == 1 else "user_reply",
|
|
"turn": turn,
|
|
"likelihood": round(likelihood, 2),
|
|
}
|
|
)
|
|
logger.warning(
|
|
"[%s] the user's text reads as instructions to the agent (%.2f)",
|
|
state["execution_id"],
|
|
likelihood,
|
|
)
|
|
return risks
|
|
|
|
async def specialist_task(task_input: dict[str, Any]) -> dict[str, Any]:
|
|
role = roles[task_input["role"]]
|
|
named = tuple(task_input["context"].get("overlay_skills") or ())
|
|
if named:
|
|
# The Execution's overlay Skills, on top of the role's own (ADR-0004).
|
|
role = dataclasses.replace(
|
|
role, skills=(*role.skills, *(n for n in named if n not in role.skills))
|
|
)
|
|
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()
|
|
EXECUTION_SCOPE.set(task_input["execution_id"])
|
|
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 settled_changes(state: ExecutionState) -> dict[str, Any] | None:
|
|
"""What a Change request changed, with rewordings told from real changes
|
|
where a decision is available."""
|
|
baseline = state.get("baseline") or None
|
|
if not baseline:
|
|
return None
|
|
deliverables = state.get("deliverables", {})
|
|
summary = change_summary(baseline.get("deliverables"), deliverables)
|
|
if decider is None:
|
|
return summary
|
|
try:
|
|
return await settle_meaning(
|
|
decider,
|
|
summary,
|
|
baseline.get("deliverables"),
|
|
deliverables,
|
|
unchanged_at=reworded_threshold,
|
|
scope=state["execution_id"],
|
|
)
|
|
except Exception: # the summary must be written whatever the decider does
|
|
logger.exception("Settling what was reworded failed; listing as changed")
|
|
return summary
|
|
|
|
async def assessed(state: ExecutionState) -> dict[str, Any] | None:
|
|
"""How the design recommendations are judged, for the Execution's record."""
|
|
if decider is None or not assess_at_end:
|
|
return None
|
|
try:
|
|
return await assess(
|
|
decider, state.get("deliverables", {}), scope=state["execution_id"]
|
|
)
|
|
except Exception: # an Execution ends whatever its assessment does
|
|
logger.exception("Assessing the Execution failed; it carries none")
|
|
return None
|
|
|
|
async def finalize(state: ExecutionState) -> dict[str, Any]:
|
|
ledger = Ledger.from_dict(state["ledger"])
|
|
assessment = await assessed(state)
|
|
_write_outputs(
|
|
output_root,
|
|
state,
|
|
"completed",
|
|
ledger,
|
|
await settled_changes(state),
|
|
assessment,
|
|
)
|
|
close(state, "completed", has_files=True)
|
|
await record_progress(state, ledger, "completed")
|
|
await record_lessons(state, ledger, "completed")
|
|
return {"status": "completed", "assessment": assessment}
|
|
|
|
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.
|
|
assessment = await assessed(state)
|
|
wrote = _write_outputs(
|
|
output_root,
|
|
state,
|
|
"completed_with_warnings",
|
|
ledger,
|
|
await settled_changes(state),
|
|
assessment,
|
|
)
|
|
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", "assessment": assessment}
|
|
|
|
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,
|
|
read_first: Sequence[Mapping[str, str]] | 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,
|
|
# Skills carrying the organisation's standards or this engagement's
|
|
# constraints. Where one disagrees with general guidance, it wins.
|
|
"overlay_skills": sorted(state.get("overlay_skills") or {}),
|
|
# 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),
|
|
# The references of its Skills this task needs, when that could be
|
|
# judged: where to start reading, not all it may read.
|
|
"read_first": list(read_first) if read_first else None,
|
|
# 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}
|
|
|
|
|
|
async def _reading_hints(
|
|
state: ExecutionState,
|
|
ledger: Ledger,
|
|
deliverables: Mapping[str, Mapping[str, Any]],
|
|
started: Mapping[DeliverableKind, int],
|
|
decider: Decider | None,
|
|
references: Mapping[str, Mapping[str, Mapping[str, str]]],
|
|
threshold: float,
|
|
) -> dict[DeliverableKind, list[dict[str, str]]]:
|
|
"""For each Specialist being started whose Skills hold many references, the ones
|
|
its task needs (iteration 5 step 8)."""
|
|
if decider is None:
|
|
return {}
|
|
asked = {
|
|
kind: references[DEPENDENCY_GRAPH[kind].specialist]
|
|
for kind in started
|
|
if references.get(DEPENDENCY_GRAPH[kind].specialist)
|
|
}
|
|
if not asked:
|
|
return {}
|
|
elements = _graph(deliverables)["elements"]
|
|
design = "\n".join(
|
|
f"- {item.get('name', item.get('id', ''))} ({item.get('product', '')}, "
|
|
f"{item.get('resource_type', '')})"
|
|
for item in elements
|
|
)
|
|
|
|
def task(kind: DeliverableKind) -> str:
|
|
feedback = list(ledger.feedback(kind))
|
|
doing = "Revise" if feedback else "Write"
|
|
parts = [
|
|
(
|
|
f"{doing} the {kind.value.replace('_', ' ')} Deliverable of a cloud "
|
|
f"solution architecture, as its {DEPENDENCY_GRAPH[kind].specialist}."
|
|
)
|
|
]
|
|
if feedback:
|
|
parts.append("Feedback to address:\n" + "\n".join(feedback))
|
|
parts.append(
|
|
f"Elements of the Target architecture:\n{design}"
|
|
if design
|
|
else f"The request:\n{state['workflow_request']}"
|
|
)
|
|
return "\n".join(parts)
|
|
|
|
chosen = await asyncio.gather(
|
|
*(
|
|
read_first(
|
|
decider,
|
|
task(kind),
|
|
skills,
|
|
threshold=threshold,
|
|
scope=state["execution_id"],
|
|
)
|
|
for kind, skills in asked.items()
|
|
)
|
|
)
|
|
return {kind: found for kind, found in zip(asked, chosen, strict=True) if found}
|
|
|
|
|
|
# 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,
|
|
changes: Mapping[str, Any] | None = None,
|
|
assessment: Mapping[str, Any] | None = None,
|
|
) -> 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(
|
|
changes or 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"),
|
|
# The overlay Skills it loaded, with the version of each.
|
|
"overlay_skills": dict(state.get("overlay_skills") or {}),
|
|
"status": status,
|
|
"warnings": list(state.get("warnings", [])),
|
|
# Flags a person should look at; nothing was done about them.
|
|
"risks": list(state.get("risks", [])),
|
|
# How its design recommendations were judged when it ended, if they were.
|
|
"assessment": dict(assessment) if assessment else None,
|
|
"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
|