"""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/// manifest.jsonl one line per record, each hash-chained to the last /.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 (/), 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 /, 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