Files
orchestration_engine/.agents/plans/iter-02-orchestration-engine/steps/step-K1.md
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

3.6 KiB

Step K1: what agents deliver, kept and linked (ADR-0004, phase 1)

Built 2026-10-21 on feat/delivery-store, the owner having chosen option 3 of three ways to make agents' outputs available in the KAB platform.

What was built

  • store.py: every completed agent Execution relayed is kept under <STORE_DIR>/tenants/<tenant>/cases/<case>/executions/<id>/: its files as the agent named them, and record.json (work, how it ended, the request, tenant, Customer case, project, the guide's name, the files, when). Written once; a second write is refused. File names that leave the Execution, and tenants or cases that are not slugs, are refused. latest is the newest Execution of a work that ended completed.
  • links.py: a link is the path with exp and sig, an HMAC of both under LINK_SECRET; LINK_TTL_SECONDS, 30 days by default, 0 for never.
  • delivery.py: keeping for the relay, with the tenant from the platform's tenant_id (local otherwise) and the Customer case (unassigned otherwise), and the links to a record, its guide, each file, the latest of its work and its Customer case. A failure to keep is logged and never fails the caller's task.
  • serving.py: GET /tenants/{tenant}/cases/{case}, …/executions/{id}, …/executions/{id}/files/{name} and …/latest/{work}. Each checks its link's signature against the path it was made for, or answers 403; a record is served with fresh links to its files.
  • The relay: a completed agent's files are kept, whatever the caller asked for. deliver: links gives the caller one artifact, result.json: the status, the work named, the Customer case, and links to the last agent's record, guide, files, latest and case, with each agent's under results. A KAB workflow step (it sends workflow_id and step_number) is given links unless it asks for files; any other caller, files. The guide is the file the agent sent as markdown, as the Execution engine sends its final Deliverable. sources given as data, as a platform step maps an earlier output, are sent to the agent as text.
  • The card: deliver and sources among the inputs, and an outputSchema for the document of links.
  • Deployment: STORE_DIR=/data/store and a /data volume in the image; in the dev kit, the orchestration-data volume, PUBLIC_URL=http://localhost:10030, and LINK_SECRET from ORCHESTRATION_LINK_SECRET in the kit's .env, which is not committed.

What differed from the plan

  • The tests of option 1 (test_document.py, on main) are replaced by test_links.py: a platform step is given links, not the files' content.
  • A file's link carries the name as it was quoted, and is checked against the request's raw path.

Verified

  • 25 tests in test_store.py and test_links.py: keeping, media types, never changing what was kept, refusing names and slugs, latest, signing, expiry; a platform step given links that serve what was delivered; the guide; unsigned and changed links refused; files still kept when files are asked for; a sequence's links, and a stopped sequence's; latest and the case listing; sources as data sent as text; the card.
  • 577 tests pass; ruff and mypy clean.
  • Deployed on the local platform: healthy, the store on its volume, the secret and the public URL set, the card declaring deliver and the document. An unsigned link is refused.

Not done

  • No run through the platform yet: the owner runs it from a workflow.
  • Phase 2, sources_from (a request naming kept work instead of carrying files); phase 3, object storage, the platform's sign-in, retention, and each file as a platform artifact.