--- status: accepted --- # The Orchestration engine keeps what agents deliver An agent on the Execution engine delivers its work as named files: a guide, the data files behind it, infrastructure code. The KAB platform takes one output per workflow step and keeps it as one artifact; a set of named files reaches it as one unnamed string. Nothing delivered had an address of its own, so a guide could not be shared or cited, and a later request could not build on earlier work without the caller carrying its files. We decide that **the Orchestration engine keeps every file an agent delivers through it, and serves each at a stable address.** - **What is kept:** the files of every agent's Execution that completes, as the agent delivered them, with a record: the work, the status the agent ended with, the request, when, the Customer case, and the tenant and project a platform step names. - **Where:** a store of its own, by tenant, Customer case and Execution. Files are copied in, not referred to in an agent's container, so they outlive any agent's deployment. - **Never changed.** An Execution's files are written once. A Change request is a new Execution. Only `latest` moves: the newest completed Execution of a kind of work in a Customer case. - **Addresses:** `/tenants/{tenant}/cases/{case}` lists a Customer case; `…/executions/{id}` is one Execution's record with links to its files; `…/executions/{id}/files/{path}` is a file with its media type; `…/latest/{work}` is the record of the newest completed Execution of that work. - **Read only by signed link.** Every address carries an expiring signature the Orchestration engine made, because the files name customers, people and suppliers. The base of every link is a setting, as the address a browser uses is not the one inside the platform's network. - **A caller that takes one output per step is given links.** A KAB workflow step, or any caller that asks (`deliver: links`), is given one JSON document of links to what was kept. A caller that asks for files is given them one by one, as before; they are kept either way. This keeps ADR-0003's rule that the Orchestration engine produces nothing: it keeps what agents produced. It replaces ADR-0003's consequence that nothing outlives a restart for delivered work; tasks in flight are still held in memory. Accepted by the owner on 2026-10-21, as option 3 of three ways to make agents' outputs available in the platform. ## Considered Options - **One JSON document with every file's content (option 1):** rejected. Nothing has an address, a large architecture can pass the platform's inline limit, and earlier work is reusable only by wiring steps on a canvas. - **The platform keeps each named artifact (option 2):** not rejected, and not ours to make: a change to how the platform's worker treats every agent. Kept as the platform team's to consider; a shared object store later lets each kept file become a platform artifact without moving it. - **Links into each agent's own deliverables folder:** rejected. Those folders are private to a container and go with it. ## Consequences - The Orchestration engine has a volume, a public base URL and a signing secret. Without a secret set, one is made at start-up and links stop working on a restart. - Links expire (`LINK_TTL_SECONDS`, 30 days by default; 0 for never). A record fetched with a valid link carries fresh links to its files. - A request may name earlier work by reference rather than carry its files (`sources_from`): the next step, with the sequence moved onto it. - Object storage, the platform's own sign-in and retention follow, in that order.