"""What agents delivered, kept by tenant, Customer case and Execution (ADR-0004). /tenants//cases//executions//record.json /files/ An Execution is written once. Its files are what the agent delivered, by the names it gave them; its record says what it was. """ from __future__ import annotations import datetime as dt import json import re import time from collections.abc import Mapping from pathlib import Path, PurePosixPath from typing import Any _SLUG = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$") _MEDIA_TYPES = { ".md": "text/markdown; charset=utf-8", ".json": "application/json", ".yaml": "application/yaml", ".yml": "application/yaml", ".html": "text/html; charset=utf-8", ".csv": "text/csv; charset=utf-8", } _TEXT = "text/plain; charset=utf-8" def slug(value: str, what: str) -> str: """`value`, when it can name a folder: letters, digits, dot, dash, underscore.""" if not _SLUG.match(value or "") or value in {".", ".."}: raise ValueError(f"{what} {value!r} must be letters, digits, '.', '-' or '_'") return value def file_name(name: str) -> PurePosixPath: """A delivered file's name as a path inside its Execution, or ValueError.""" path = PurePosixPath(name) if ( not name or "\\" in name or path.is_absolute() or any(part in {"", ".", ".."} for part in name.split("/")) ): raise ValueError(f"{name!r} is not a file name inside an Execution") return path def media_type(name: str) -> str: return _MEDIA_TYPES.get(PurePosixPath(name).suffix.lower(), _TEXT) class Store: def __init__(self, root: str | Path) -> None: self.root = Path(root) def _case(self, tenant: str, case: str) -> Path: return ( self.root / "tenants" / slug(tenant, "Tenant") / "cases" / slug(case, "Case") ) def _execution(self, tenant: str, case: str, execution_id: str) -> Path: return self._case(tenant, case) / "executions" / slug(execution_id, "Execution") def keep( self, *, tenant: str, case: str, execution_id: str, work: str, status: str, request: str, files: Mapping[str, str], guide: str | None = None, project_id: str | None = None, ) -> dict[str, Any]: """Keep one Execution's files and record it. Written once: an Execution already kept is refused.""" folder = self._execution(tenant, case, execution_id) paths = {name: file_name(name) for name in files} if folder.exists(): raise ValueError(f"Execution {execution_id} is already kept") for name, path in paths.items(): target = folder / "files" / path target.parent.mkdir(parents=True, exist_ok=True) target.write_text(files[name], encoding="utf-8") record = { "tenant": tenant, "customer_case": case, "execution_id": execution_id, "work": work, "status": status, "request": request, "project_id": project_id, "guide": guide if guide in files else None, "files": sorted(files), "kept_at": dt.datetime.now(dt.UTC).isoformat(), "kept_ns": time.time_ns(), } folder.mkdir(parents=True, exist_ok=True) (folder / "record.json").write_text(json.dumps(record, indent=2), "utf-8") return record def record( self, tenant: str, case: str, execution_id: str ) -> dict[str, Any] | None: try: path = self._execution(tenant, case, execution_id) / "record.json" except ValueError: return None if not path.is_file(): return None record: dict[str, Any] = json.loads(path.read_text("utf-8")) return record def file( self, tenant: str, case: str, execution_id: str, name: str ) -> tuple[bytes, str] | None: """A kept file's content and media type, or None.""" try: folder = self._execution(tenant, case, execution_id) / "files" target = folder / file_name(name) except ValueError: return None if not target.is_file() or folder.resolve() not in target.resolve().parents: return None return target.read_bytes(), media_type(name) def case(self, tenant: str, case: str) -> list[dict[str, Any]]: """The Customer case's Executions, newest first.""" try: folder = self._case(tenant, case) / "executions" except ValueError: return [] records = [ json.loads(path.read_text("utf-8")) for path in folder.glob("*/record.json") ] return sorted(records, key=lambda r: r.get("kept_ns", 0), reverse=True) def latest(self, tenant: str, case: str, work: str) -> dict[str, Any] | None: """The newest Execution of `work` in the Customer case that completed.""" return next( ( record for record in self.case(tenant, case) if record["work"] == work and record["status"] == "completed" ), None, )