All checks were successful
check agents / check (push) Successful in 10s
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>
177 lines
6.7 KiB
Python
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
|