feat: keep what agents deliver and serve it at signed links (ADR-0004)
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>
This commit is contained in:
157
orchestration/store.py
Normal file
157
orchestration/store.py
Normal file
@@ -0,0 +1,157 @@
|
||||
"""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,
|
||||
)
|
||||
Reference in New Issue
Block a user