117 lines
5.4 KiB
Python
117 lines
5.4 KiB
Python
"""The checkpointed state of one Execution. Plain, JSON-compatible data only."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import operator
|
|
import re
|
|
from pathlib import Path
|
|
from typing import Annotated, Any, TypedDict
|
|
|
|
# A Customer case id becomes a directory name, so it is a short lowercase slug.
|
|
CUSTOMER_CASE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$")
|
|
# Executions started without a Customer case are grouped here, so every Execution's
|
|
# files sit under a case.
|
|
UNASSIGNED_CASE = "unassigned"
|
|
|
|
|
|
def check_customer_case(customer_case: object) -> str:
|
|
"""The Customer case id, defaulting to UNASSIGNED_CASE; a ValueError when it is
|
|
not a safe slug."""
|
|
if customer_case is None:
|
|
return UNASSIGNED_CASE
|
|
if not isinstance(customer_case, str) or not CUSTOMER_CASE.match(customer_case):
|
|
raise ValueError(
|
|
"customer_case must be 1 to 64 lowercase letters, digits or hyphens, "
|
|
f"starting and ending with a letter or digit; got {customer_case!r}"
|
|
)
|
|
return customer_case
|
|
|
|
|
|
def case_dir(output_root: Path, customer_case: str) -> Path:
|
|
"""Everything generated for one Customer case."""
|
|
return output_root / "deliverables" / "cases" / customer_case
|
|
|
|
|
|
def execution_dir(output_root: Path, execution_id: str, customer_case: str) -> Path:
|
|
"""Where one Execution's files go, under its Customer case."""
|
|
return case_dir(output_root, customer_case) / "executions" / execution_id
|
|
|
|
|
|
def lessons_file(output_root: Path, execution_id: str, customer_case: str) -> Path:
|
|
return (
|
|
output_root / "lessons" / "candidates" / customer_case / f"{execution_id}.json"
|
|
)
|
|
|
|
|
|
def merge_by_key(
|
|
current: dict[str, dict[str, Any]] | None, update: dict[str, dict[str, Any]] | None
|
|
) -> dict[str, dict[str, Any]]:
|
|
"""Parallel Specialist tasks each write their own Deliverable's entry."""
|
|
return {**(current or {}), **(update or {})}
|
|
|
|
|
|
class ExecutionState(TypedDict, total=False):
|
|
execution_id: str
|
|
session_id: str
|
|
customer_case: str # the Customer case this Execution belongs to
|
|
intent_version: int # which statement of the case's intent started this Execution
|
|
workflow_request: str
|
|
risks: list[dict[str, Any]] # flags on what the user wrote, for a person to see
|
|
overlay_skills: dict[str, str] # overlay Skills this Execution loads -> version
|
|
options: dict[str, Any] # the choices made for this Execution, by name
|
|
# The customer's scope spec as read at the start: its Skill, status, readiness
|
|
# and what a Specialist is shown of it. None when no spec was supplied.
|
|
scope: dict[str, Any] | None
|
|
# What the spec was digested from: name -> its hash, and whether code read it.
|
|
sources: dict[str, dict[str, Any]]
|
|
# The sources code did not read, for the Specialist that completes the spec.
|
|
source_documents: dict[str, str]
|
|
baseline: dict[str, Any] | None # a Change request's Baseline, read from its files
|
|
pre_approved: bool
|
|
allow_cloud_read: bool | None
|
|
|
|
ledger: dict[str, Any] # Ledger.to_dict()
|
|
deliverables: dict[str, dict[str, Any]] # kind -> {content, attachments}
|
|
|
|
conversation: list[dict[str, str]] # {"from": "user" | "orchestrator", "text"}
|
|
notes: list[str] # facts for the Orchestrator's next turn
|
|
pending_questions: list[dict[str, Any]] # {kind, questions} not yet asked
|
|
awaiting_questions: list[dict[str, Any]] # {kind, questions} asked, not answered
|
|
answers: dict[str, list[dict[str, Any]]] # kind -> [{questions, reply}]
|
|
drafts_shown: list[str] # Deliverables a draft of which the user has been shown
|
|
drafts: dict[
|
|
str, dict[str, Any]
|
|
] # kind -> {content, attachments} awaiting the user
|
|
# kind -> working memory its tools keep across attempts (e.g. pillar advice)
|
|
working: Annotated[dict[str, dict[str, Any]], merge_by_key]
|
|
pending_permission: dict[str, Any] | None # {tier, requested_by}
|
|
prompt: dict[str, Any] | None # what the user is being asked
|
|
|
|
# Specialist outcomes, appended concurrently by parallel Specialist tasks and
|
|
# applied to the Ledger by the next Orchestrator turn.
|
|
outcomes: Annotated[list[dict[str, Any]], operator.add]
|
|
outcomes_applied: int
|
|
refusals: list[dict[str, Any]] # the Orchestrator's refused tool calls
|
|
events_recorded: int
|
|
|
|
# Routing (ADR-0007).
|
|
last_reply: dict[str, Any] | None # the user's message, until a turn routes it
|
|
pending_change: dict[str, Any] | None # a change the user was asked to confirm
|
|
awaiting_gap_decision: bool # the user was asked whether to close gaps
|
|
validation_settled: int # the validation attempt already decided on
|
|
awaiting_limit_decision: bool # the user was told a Revision limit was reached
|
|
revision_limit_asked: list[str] # Deliverables the user has been told that about
|
|
idle_asks: int # questions put to the user running, with nothing changing between
|
|
# kind -> runs of its Specialist running that ended without a submission, in an
|
|
# Execution with nobody to answer
|
|
unfinished_runs: dict[str, int]
|
|
ask_fingerprint: str # the Ledger's state when the user was last asked
|
|
decisions: list[dict[str, Any]] # every routing decision, in order
|
|
# How the finished work was judged when the Execution ended.
|
|
assessment: dict[str, Any] | None
|
|
|
|
turns: int
|
|
status: str # running | completed | completed_with_warnings
|
|
warnings: list[str]
|
|
scripted_answers: list[list[str]] # [regex, answer], pre-approved runs only
|