The Orchestration engine keeps every completed agent Execution it relays, by tenant, Customer case and Execution, and serves its record and files at signed, expiring links. A KAB workflow step, which takes one output per step, is given one JSON document of links (`deliver: links`); other callers still get each file, and what they are given is kept either way. - store.py, links.py, delivery.py, serving.py; the relay keeps and links - the card declares `deliver`, `sources` and an output schema - image: STORE_DIR on a /data volume; PUBLIC_URL and LINK_SECRET settings - option 1's tests replaced by tests of the links document Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
158 lines
5.3 KiB
Python
158 lines
5.3 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 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,
|
|
)
|