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:
29
.agents/plans/iter-02-orchestration-engine/steps/step-K1.md
Normal file
29
.agents/plans/iter-02-orchestration-engine/steps/step-K1.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user