Files
orchestration_engine/orchestration/delivery.py
Jonathan Boniface 6d32bc696d 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>
2026-10-21 20:05:47 +01:00

112 lines
3.9 KiB
Python

"""Keeping what an agent delivered and linking to it (ADR-0004): the store, the
signer and the address a caller reaches them at, together."""
from __future__ import annotations
import logging
import re
from collections.abc import Mapping
from typing import Any
from urllib.parse import quote
from orchestration.links import Signer
from orchestration.store import Store
logger = logging.getLogger(__name__)
LOCAL_TENANT = "local" # what is kept for a caller that names no tenant
UNASSIGNED = "unassigned" # for a request that names no Customer case
_NOT_SLUG = re.compile(r"[^A-Za-z0-9._-]+")
def _slug(value: Any, default: str) -> str:
text = _NOT_SLUG.sub("-", str(value or "")).strip("-.")
return text or default
class Delivery:
def __init__(self, store: Store, signer: Signer, public_url: str) -> None:
self.store = store
self.signer = signer
self.public_url = public_url.rstrip("/")
@staticmethod
def place(fields: Mapping[str, Any]) -> tuple[str, str]:
"""The tenant and Customer case what a request delivers is kept under."""
return (
_slug(fields.get("tenant_id"), LOCAL_TENANT),
_slug(fields.get("customer_case"), UNASSIGNED),
)
def keep(
self,
fields: Mapping[str, Any],
*,
work: str,
execution_id: str,
status: str,
request: str,
files: Mapping[str, str],
guide: str | None,
) -> dict[str, Any] | None:
"""Keep an agent's Execution; None, logged, when it cannot be kept, so a
caller still gets the agent's answer."""
tenant, case = self.place(fields)
try:
return self.store.keep(
tenant=tenant,
case=case,
execution_id=execution_id,
work=work,
status=status,
request=request,
files=files,
guide=guide,
project_id=fields.get("project_id"),
)
except (OSError, ValueError):
logger.exception("Could not keep %s Execution %s", work, execution_id)
return None
# --- addresses -------------------------------------------------------------
@staticmethod
def case_path(tenant: str, case: str) -> str:
return f"/tenants/{tenant}/cases/{case}"
def execution_path(self, tenant: str, case: str, execution_id: str) -> str:
return f"{self.case_path(tenant, case)}/executions/{execution_id}"
def file_path(self, tenant: str, case: str, execution_id: str, name: str) -> str:
return f"{self.execution_path(tenant, case, execution_id)}/files/{quote(name)}"
def latest_path(self, tenant: str, case: str, work: str) -> str:
return f"{self.case_path(tenant, case)}/latest/{quote(work)}"
def link(self, path: str) -> str:
return self.signer.link(self.public_url, path)
def links(self, record: Mapping[str, Any]) -> dict[str, Any]:
"""Signed links to a kept Execution: its record, its guide, each file, the
latest of its work and its Customer case."""
tenant, case = record["tenant"], record["customer_case"]
execution_id = record["execution_id"]
files = {
name: self.link(self.file_path(tenant, case, execution_id, name))
for name in record["files"]
}
return {
"record": self.link(self.execution_path(tenant, case, execution_id)),
"guide": files.get(record.get("guide") or ""),
"files": files,
"latest": self.link(self.latest_path(tenant, case, record["work"])),
"case": self.link(self.case_path(tenant, case)),
}
def shown(self, record: Mapping[str, Any]) -> dict[str, Any]:
"""A record as it is served: what was kept, with links, without internals."""
return {
**{k: v for k, v in record.items() if k != "kept_ns"},
"links": self.links(record),
}