feat: keep what agents deliver, build on it by reference, in object storage (ADR-0004) #1

Merged
demo-bot merged 4 commits from docs/handoff-run into main 2026-10-23 17:29:51 +00:00
Owner

Summary

The Orchestration engine keeps what agents deliver and serves it at signed links (ADR-0004), lets a request build on kept work by reference, and keeps it in S3-compatible object storage. Four stacked commits: the delivery store, sources_from, object storage, and the record of the first run with real models.

orchestration/
├── store.py      # kept Executions: tenants/<t>/cases/<c>/executions/<id>/{record.json, files/…}, on a folder or a bucket
├── links.py      # HMAC-signed, expiring links
├── delivery.py   # keep, link, resolve `sources_from`, sources with the completion record
├── serving.py    # GET /tenants/{t}/cases/{c}[/executions/{id}[/files/{name}] | /latest/{work}]
├── relay.py      # keeps each completed agent's files; `deliver: links | files`
└── card.py       # `deliver`, `sources`, `sources_from` inputs; output schema of the links document
 relay a request
   route to the agents for the work
+  if sources_from: resolve kept work -> sources (refuse what is not completed, another tenant or case)
   relay each agent's turns
+  on each completed agent: keep its files in the store
-  next agent of a sequence: the files relayed
+  next agent of a sequence: what was kept, with the completion record
+  a KAB workflow step (or deliver: links): one artifact, result.json, of links

execution_engine/ is unchanged: no agent's behaviour changes.

Evidence

  • Before: main has the tests of option 1 (tests/orchestration/test_document.py), 7 failing: the one-document delivery was never implemented.
    After: they are replaced by test_links.py, test_store.py (every store test on both a folder and S3 via moto) and test_sources_from.py; 606 tests pass, ruff and mypy clean.
  • Real run, 2026-10-21: one pre-approved architecture_and_operating_model request: the solution architecture agent's Execution completed in about 50 minutes, its 15 files were kept in MinIO and given to the operating model agent as sources, which completed; 74.9 minutes end to end; both Executions fetched back through their links.

Merge Danger

Door: two-way

Revert restores relaying without keeping. What has been kept in a store stays there, unread, until removed.

Blast Radius: Orchestration-engine

A deployment needs a volume or a bucket (STORE_BACKEND, STORE_DIR or S3_*), a PUBLIC_URL a browser reaches, and a LINK_SECRET; without the secret, links stop working on restart. Kept files name what a Customer case's agents delivered, so the store's access matters (signed links only today). ADR-0003 is still proposed.

🤖 Generated with Claude Code

## Summary The Orchestration engine keeps what agents deliver and serves it at signed links (ADR-0004), lets a request build on kept work by reference, and keeps it in S3-compatible object storage. Four stacked commits: the delivery store, `sources_from`, object storage, and the record of the first run with real models. ```text orchestration/ ├── store.py # kept Executions: tenants/<t>/cases/<c>/executions/<id>/{record.json, files/…}, on a folder or a bucket ├── links.py # HMAC-signed, expiring links ├── delivery.py # keep, link, resolve `sources_from`, sources with the completion record ├── serving.py # GET /tenants/{t}/cases/{c}[/executions/{id}[/files/{name}] | /latest/{work}] ├── relay.py # keeps each completed agent's files; `deliver: links | files` └── card.py # `deliver`, `sources`, `sources_from` inputs; output schema of the links document ``` ```diff relay a request route to the agents for the work + if sources_from: resolve kept work -> sources (refuse what is not completed, another tenant or case) relay each agent's turns + on each completed agent: keep its files in the store - next agent of a sequence: the files relayed + next agent of a sequence: what was kept, with the completion record + a KAB workflow step (or deliver: links): one artifact, result.json, of links ``` `execution_engine/` is unchanged: no agent's behaviour changes. ## Evidence - **Before:** `main` has the tests of option 1 (`tests/orchestration/test_document.py`), 7 failing: the one-document delivery was never implemented. **After:** they are replaced by `test_links.py`, `test_store.py` (every store test on both a folder and S3 via moto) and `test_sources_from.py`; 606 tests pass, `ruff` and `mypy` clean. - **Real run, 2026-10-21:** one pre-approved `architecture_and_operating_model` request: the solution architecture agent's Execution completed in about 50 minutes, its 15 files were kept in MinIO and given to the operating model agent as `sources`, which completed; 74.9 minutes end to end; both Executions fetched back through their links. ## Merge Danger **Door:** two-way Revert restores relaying without keeping. What has been kept in a store stays there, unread, until removed. **Blast Radius:** Orchestration-engine A deployment needs a volume or a bucket (`STORE_BACKEND`, `STORE_DIR` or `S3_*`), a `PUBLIC_URL` a browser reaches, and a `LINK_SECRET`; without the secret, links stop working on restart. Kept files name what a Customer case's agents delivered, so the store's access matters (signed links only today). ADR-0003 is still `proposed`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
demo-bot added 4 commits 2026-10-23 17:21:57 +00:00
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>
A request names work the Orchestration engine kept instead of carrying its
files: a record or latest link from an earlier document of links (checked,
and of the request's tenant and Customer case), latest/<work>, or an
Execution's id. The kept files and the record that the work completed are
the agent's sources. Nothing starts, and the caller is told why, when the
reference does not resolve to completed work it may use.

A sequence's next agent is given what was kept of the one before, the same
way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The store's rules now sit on a Blobs layer: a folder, as before, or a
prefix in an S3-compatible bucket (MinIO locally), chosen by STORE_BACKEND.
The layout is the same in both; the record is written last.

- S3_BUCKET, S3_PREFIX, S3_ENDPOINT_URL, S3_REGION; AWS credentials
- an s3 extra (boto3), installed in the image; moto for tests
- every store test runs on both kinds of storage

Retention, the platform's sign-in and each kept file as a platform
artifact are left: the last needs the platform's S3 backend, which it does
not yet have.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
demo-bot merged commit 5ea4fa4065 into main 2026-10-23 17:29:51 +00:00
Sign in to join this conversation.
No Reviewers
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: agents/orchestration_engine#1