Files
Jonathan Boniface 416c66ced4
All checks were successful
check agents / check (push) Successful in 10s
Add CP1 Discovery agents in both patterns
ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight
individual declarative agents (individual-agents/), with their KAB workflow
exports. Shared check, render and import scripts, the alz-discovery-sample
MCP server, the crucible-kab-dev deploy profile, deployment docs, platform
issue reports and the source material. Agent steps time out at 20 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 18:25:57 +00:00

177 lines
6.7 KiB
Python

"""The run workspace: the data, context and memory one discovery run shares.
Sub-agents see only the request written for them, and a request lasts one
phase, so whatever must outlive a model call -- the scope, the raw tool
results, every sub-agent's reply -- is written here instead. Later phases of
the same run, and the sub-agents, read it back by reference.
Layout, under the shared execution storage the deployment already mounts:
$EXECUTION_STORAGE_ROOT/alz-discovery/<engagement_id>/<run_id>/
manifest.jsonl one line per record, each hash-chained to the last
<phase>/<name>.json one record: who produced it, from what, and its content
Records are write-once. A name already taken is refused rather than replaced,
so nothing an earlier step stored can be changed by a later one, and the
manifest chain shows if a file was edited outside the agent.
The run a call belongs to comes from `bind_run`, called by pre_process for
each request -- never from the model's arguments, so a tool result cannot
point the agent at another engagement's data.
"""
from __future__ import annotations
import contextvars
import fcntl
import hashlib
import json
import os
import re
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, Iterator, List, Optional
_ROOT_ENV = "EXECUTION_STORAGE_ROOT"
_DEFAULT_ROOT = "/tmp/executions" # the runtime's own fallback when the volume is absent
_NAME = re.compile(r"^[a-z0-9][a-z0-9_.-]{0,95}$")
GENESIS = "0" * 64
@dataclass(frozen=True)
class Run:
engagement_id: str
run_id: str
phase: str
batch: Optional[int] = None
_run: contextvars.ContextVar[Optional[Run]] = contextvars.ContextVar("alz_discovery_run", default=None)
class WorkspaceError(ValueError):
"""A request the workspace refuses: no run bound, a bad name, a taken name."""
def bind_run(run: Run) -> None:
_run.set(run)
def current_run() -> Run:
run = _run.get()
if run is None:
raise WorkspaceError("no discovery run is bound to this request")
return run
def canonical(content: Any) -> bytes:
"""The bytes a record's hash is taken over: sorted keys, no whitespace."""
return json.dumps(content, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
def sha256(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def run_dir(run: Run) -> Path:
root = Path(os.getenv(_ROOT_ENV) or _DEFAULT_ROOT)
return root / "alz-discovery" / run.engagement_id / run.run_id
def _manifest(run: Run) -> Path:
return run_dir(run) / "manifest.jsonl"
def entries(run: Run) -> List[Dict[str, Any]]:
"""Every manifest entry of the run, oldest first."""
path = _manifest(run)
if not path.exists():
return []
with path.open(encoding="utf-8") as fh:
return [json.loads(line) for line in fh if line.strip()]
def head(run: Run) -> str:
found = entries(run)
return found[-1]["entry_hash"] if found else GENESIS
def _entry_hash(entry: Dict[str, Any]) -> str:
body = {k: v for k, v in entry.items() if k != "entry_hash"}
return sha256(canonical(body))
def verify_chain(run: Run) -> List[str]:
"""Problems with the manifest: a broken link, an edited entry, an edited record. [] when sound."""
problems: List[str] = []
prev = GENESIS
for entry in entries(run):
if entry.get("prev") != prev:
problems.append(f"manifest entry {entry.get('seq')} does not follow the one before it")
if _entry_hash(entry) != entry.get("entry_hash"):
problems.append(f"manifest entry {entry.get('seq')} was changed after it was written")
record = run_dir(run) / f"{entry['ref']}.json"
if not record.exists():
problems.append(f"record {entry['ref']} is missing")
else:
stored = json.loads(record.read_text(encoding="utf-8"))
if sha256(canonical(stored.get("content"))) != entry.get("sha256"):
problems.append(f"record {entry['ref']} was changed after it was written")
prev = entry.get("entry_hash", "")
return problems
def put(run: Run, name: str, content: Any, produced_by: str,
inputs: Optional[List[str]] = None, evidence_refs: Optional[List[str]] = None) -> Dict[str, Any]:
"""Store one record in the current phase and chain it into the manifest. Write-once."""
if not _NAME.match(name or ""):
raise WorkspaceError(
f"bad record name {name!r}: lower case letters, digits, '.', '_' and '-', 96 characters at most")
ref = f"{run.phase}/{name}"
base = run_dir(run)
(base / run.phase).mkdir(parents=True, exist_ok=True)
record_path = base / f"{ref}.json"
digest = sha256(canonical(content))
with (base / ".lock").open("a+") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
if record_path.exists():
raise WorkspaceError(f"{ref} is already stored and records are write-once; use another name")
found = entries(run)
now = datetime.now(timezone.utc).isoformat()
record = {
"ref": ref, "name": name, "phase": run.phase, "produced_by": produced_by,
"inputs": list(inputs or []), "evidence_refs": list(evidence_refs or []),
"created_at": now, "content": content,
}
record_path.write_text(json.dumps(record, ensure_ascii=False, indent=1), encoding="utf-8")
entry = {
"seq": len(found) + 1, "ref": ref, "sha256": digest, "produced_by": produced_by,
"phase": run.phase, "batch": run.batch, "inputs": list(inputs or []), "at": now,
"prev": found[-1]["entry_hash"] if found else GENESIS,
}
entry["entry_hash"] = _entry_hash(entry)
with _manifest(run).open("a", encoding="utf-8") as fh:
fh.write(json.dumps(entry, sort_keys=True) + "\n")
return {"ref": ref, "sha256": digest, "produced_by": produced_by}
def get(run: Run, ref: str) -> Dict[str, Any]:
"""One stored record, by ref (<phase>/<name>), in the current run only."""
if not re.match(r"^(plan|collect|analyse|critique)/[a-z0-9][a-z0-9_.-]{0,95}$", ref or ""):
raise WorkspaceError(f"bad ref {ref!r}: expected <phase>/<name>, e.g. plan/scope")
path = run_dir(run) / f"{ref}.json"
if not path.exists():
raise WorkspaceError(f"{ref} is not stored in this run")
return json.loads(path.read_text(encoding="utf-8"))
def find(run: Run, phase: Optional[str] = None, produced_by: Optional[str] = None) -> Iterator[Dict[str, Any]]:
"""Manifest entries, optionally only one phase's or one producer's."""
for entry in entries(run):
if phase and entry["phase"] != phase:
continue
if produced_by and entry["produced_by"] != produced_by:
continue
yield entry