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>
168 lines
5.7 KiB
Python
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,
|
|
)
|