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:
@@ -7,7 +7,7 @@ One directory per iteration. Each holds the plan for that iteration and, for fin
|
||||
| # | Directory | Status | What it is |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | `iter-01-execution-engine/` | steps 1 to 6 built on 2026-10-13; 7 planned | The Execution engine: brought from the Reference, given a Workflow, and proved on a toy Workflow and on the Reference's own. |
|
||||
| 2 | `iter-02-orchestration-engine/` | F1 proposed; F2 and F4 built on 2026-10-20 | The Orchestration engine: routes each request to the agent for its work and relays everything back. |
|
||||
| 2 | `iter-02-orchestration-engine/` | F1 proposed; F2 and F4 built on 2026-10-20; K1 (ADR-0004) built on 2026-10-21 | The Orchestration engine: routes each request to the agent for its work and relays everything back. |
|
||||
|
||||
The plan across both repositories is `../tom_analysis/IMPLEMENTATION_PLAN.md`.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**Iteration:** 2, the Orchestration engine
|
||||
**Intent:** The service every request comes through. It decides which agent the work belongs to, dispatches it, and relays every question and Approval. First behind it: the operating model agent (`../tom_analysis`).
|
||||
**Status:** F1 proposed; F2 and F4 built 2026-10-20
|
||||
**Status:** F1 proposed; F2 and F4 built 2026-10-20; K1 built 2026-10-21
|
||||
|
||||
## Decided by the owner, 2026-10-20
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
|
||||
- `../tom_analysis/IMPLEMENTATION_PLAN.md`, sections 2 and 4, and steps F1 to F5 in section 10.
|
||||
- `docs/adr/0003-one-orchestration-engine-above-the-agents.md`.
|
||||
- `docs/adr/0004-the-orchestration-engine-keeps-what-agents-deliver.md`.
|
||||
- `../tom_analysis/.agents/plans/iter-02-platform-deployment/`: how an agent runs on the local KAB platform.
|
||||
|
||||
## Status
|
||||
@@ -24,3 +25,6 @@
|
||||
| F3 | The decision: readings in code, the Jev question, thresholds, the fallbacks, the record | A labelled set of messages is routed correctly; low confidence asks; no Jev key still routes what is named | planned |
|
||||
| F4 | "Both": architecture, then its files as `sources` to the operating model agent | One request yields both sets of Deliverables under one Customer case | built against scripted agents (`steps/step-4.md`), ahead of F3 at the owner's request; not yet run with real models |
|
||||
| F5 | Later messages to the agent that owns the work | A change to the architecture is followed by a change to the operating model | planned |
|
||||
| K1 | What agents deliver, kept and served at signed links; a platform step given one document of links (ADR-0004, phase 1) | A platform step's output links to each delivered file, and each link serves it | built (`steps/step-K1.md`); the owner's run through the platform to follow |
|
||||
| K2 | `sources_from`: a request names kept work instead of carrying its files; the sequence moved onto it | An operating model started from the latest architecture of a Customer case | planned |
|
||||
| K3 | Object storage shared with the platform, the platform's sign-in, retention, each file as a platform artifact | A kept guide is listed among the project's artifacts | planned |
|
||||
|
||||
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