Files
orchestration_engine/orchestration/store.py
Jonathan Boniface 1ec939f4fd feat: build on kept work by reference with sources_from (ADR-0004 phase 2)
A request names work the Orchestration engine kept instead of carrying its
files: a record or latest link from an earlier document of links (checked,
and of the request's tenant and Customer case), latest/<work>, or an
Execution's id. The kept files and the record that the work completed are
the agent's sources. Nothing starts, and the caller is told why, when the
reference does not resolve to completed work it may use.

A sequence's next agent is given what was kept of the one before, the same
way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 21:00:26 +01:00

168 lines
5.7 KiB
Python

"""What agents delivered, kept by tenant, Customer case and Execution (ADR-0004).
<root>/tenants/<tenant>/cases/<case>/executions/<id>/record.json
/files/<name as delivered>
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 files(self, tenant: str, case: str, execution_id: str) -> dict[str, str]:
"""Every file kept for an Execution, by name."""
record = self.record(tenant, case, execution_id) or {}
found: dict[str, str] = {}
for name in record.get("files", []):
kept = self.file(tenant, case, execution_id, name)
if kept is not None:
found[name] = kept[0].decode("utf-8")
return found
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,
)