refactor(runtime): make the tool-result archive capability indivisible #2026

Activity

1. Astro-Han

   added

   enhancementNew feature or requestNew feature or request

   on Aug 3, 2026
2. Astro-Han commented on Aug 5, 2026

   

   Astro-Han

   on Aug 5, 2026

   ContributorAuthor

   More actions

   Claiming this — starting work now.

   Two corrections to the premises in the issue body, both verified against current main:

   1. CHILD_RECOVERY_TOOL_NAMES is not a working patch. It adds ArchiveRead to the candidate pool returned by buildChildAgentTools, but every child surface is then re-narrowed by the strict allowlist buildToolsForAgentDefinition (packages/runtime/src/agent-catalog.ts:293) against definition.tools, and none of the three builtin agent definitions lists ArchiveRead. The durable snapshot records [...definition.tools] (session-manager.ts:2490,2549,3077), so resume behaves the same. Children cannot call ArchiveRead today. The child path is not "patched locally" — it is the same defect as #2025, still live, and the only test covering it (subagent-tools.test.ts:457) asserts the pool rather than the child surface, sharing the same one-directional blind spot the implementation has.

   2. Four capability assembly authorities, not three: embedded desktop, runtime-host server, CLI, and headless/Harbor. Desktop's runtime-host client path is protocol-only and assembles no backend capability. CLI supplies none of the three fields — the legitimate "no archive at all" state, which stays expressible with no escape hatch.

   Adjustment to the proposal

   The factory as originally specified returns tools: [ArchiveRead] for the host to bind. That still leaves the capability with two delivery addresses — backend options and the tool surface — constructed at different layers (desktop: session-stream.ts:332 vs tool-assembly.ts:189). A host can hold a complete bundle and deliver it to one address only, which reproduces exactly the state we are trying to eliminate. The factory makes a half-built capability unconstructible; it does not make a half-delivered one unrepresentable.

   So the capability carries the tool, and the backend binds it:

   export interface ToolResultArchiveServices {
     archiveToolResult: ToolResultArchiveRecorder;
     readToolResultArchive: ToolResultArchiveReader;
     readArchivedToolResultResource:
       ToolResultArchiveResourceReader['readArchivedToolResultResource'];
   }
   
   export interface ToolResultArchiveCapability {
     readonly services: ToolResultArchiveServices;
     readonly archiveReadTool: MakaTool & { readonly name: 'ArchiveRead' };
   }
   
   export function createToolResultArchiveCapability(
     services: ToolResultArchiveServices,
   ): ToolResultArchiveCapability;

   AiSdkBackendInput drops archiveToolResult (ai-sdk-compaction-contract.ts:160) and readToolResultArchive (ai-sdk-backend.ts:604) for a single optional toolResultArchive, and resolves its own effective tool set from it. archiveResources disappears from builtin-tools.ts:147,301 and headless/src/tools.ts:44,113.

   One address, so nothing to forget; no invariant assertion needed, because there is no longer a second surface to check against. The reasoning is that the placeholder is a runtime-generated protocol value and ArchiveRead is its decoder — which host binds it was never a legitimate configuration question.

   This also removes the need for any AgentDefinition or durable-snapshot change: ArchiveRead never enters definition.tools, so child sessions inherit it from the same backend seam and CHILD_RECOVERY_TOOL_NAMES is deleted rather than fixed.

   What this changes on purpose, and must not slip through review

   BackendFactoryContext.tools (session-manager.ts:705) is currently documented as a hard ceiling: a host "may remove tools for stricter local policy, but must never append, substitute, or otherwise expose a tool outside this exact set." Binding a runtime protocol decoder inside the backend needs that contract rewritten explicitly to carve out runtime recovery tools as not-an-agent-permission, rather than quietly leaning on the fact that the constraint addresses hosts.

   Product-surface identity is computed before the backend, so it will not list the bound ArchiveRead unless it is either derived from the backend's effective tools or given an explicit protocolCapabilities field. Benchmark execution identity should not silently under-report the real tool surface.

   Expected non-behavioral churn: request-shape hash baselines, and writer-only unit fixtures that currently construct the illegal state and will need a whole capability.

   Delivery

   One draft PR. This is an atomic type migration across runtime, runtime-host, desktop and headless; splitting it produces intermediate states where the new capability exists but the old split entry points still accept a half-wired archive. The child-surface fix is not a separable behavior change here — it falls out of the same seam.
3. Astro-Han

   closed this as completedin #2255on Aug 5, 2026
4. Astro-Han

   added a commit that references this issue on Aug 5, 2026

   refactor(runtime): make the tool-result archive capability indivisible (

   ...

   2acbc07