@tangle-network/agent-provider-cli-bridge 2.0.2 → 2.0.4

package/README.md

@@ -104,6 +104,21 @@ The provider uses the explicit SSE event field to select the format and rejects
 The provider rejects a terminal response when its run id or request digest does not match the accepted stream.
 Usage events and terminal result metadata include `modelRequests` only when the bridge measured an exact non-negative integer count.
 Missing, malformed, partial, or estimated request counts remain unknown.
+
+`metadata.model` and event `data.model` retain Bridge's compatibility response value; they do not prove which model served a request.
+Explicit provider-response observations appear as `provider_models` in event data and result metadata.
+`provider_model` is present only for one distinct observation, and never on a failed result.
+The collector retains disagreements independently of its bounded result event history; overflow or malformed evidence refuses certification.
+Requested routes, init records, fingerprints, configured session models and application JSON never establish provider identity.
+Opaque native records remain in their existing envelope and cannot promote their own fields into host evidence.
+
+On the qualified OpenAI wire path, raw Bridge usage is retained in `event.providerEvent.usage` even when a partial receipt cannot form `TokenUsage`.
+`metadata.provider_usage` folds those receipts outside the bounded event history: a missing count stays unknown across later deltas, and a cumulative receipt replaces counts and coverage.
+Events declare this distinction with the existing `usageMode` field.
+Measured usage requires explicit `estimated: false` and valid reported input and output totals; `estimated: true` is an estimate, and absent provenance remains unknown.
+Observed zero is retained. Missing cache classes and cost remain unknown; `cost_scope` applies only to cost.
+The numeric `result.usage` compatibility projection alone does not certify complete measured usage.
+Old peers and opaque canonical native envelopes remain readable with uncertified provenance; nested native or application records cannot assert host observation authority.
 When `dispatch()` receives no `sessionId`, it creates one from that turn's stable run id and returns it.
 Replay and result reads fail loudly after cli-bridge's configured replay retention expires.
 Stopping a `session.events()` reader detaches only that replay observer.
@@ -180,3 +195,21 @@ Those five surfaces are never claimed in the capability document and always carr
 The usage of one run is summed across its events and attributed to that run's execution id, which the observation carries as the provenance source.
 An environment rebuilt with `provider.get(id)` has measured nothing yet, so it reports the usage surface as unavailable until a turn completes through it.
 The endpoint holds only a scheme, a host, and an explicit port; userinfo, path, and query are dropped, and the bearer beside the base URL is never read.
+
+## Cloud sandboxes (`./sandbox`)
+
+`@tangle-network/agent-provider-cli-bridge/sandbox` turns a vendor sandbox that runs CLI Bridge into an `AgentEnvironmentProvider`.
+The vendor adapter implements `BridgeSandboxVendor`: `create`, `connect`, `list`, and per sandbox `exec`, `spawn`, `read`, `write`, `endpoint`, `status` and `destroy`.
+`createBridgeSandboxProvider({ vendor, router: { key } })` does the rest:
+
+- It refuses every create field the vendor cannot honor with an `EnvironmentProviderError` that names the field, before any vendor call, and validates the profile with the materializer the Bridge in the box uses.
+- It creates the sandbox from the box image with a finite lifetime and a run tag, starts the Bridge with a random bearer and the per-run Router key on that process only, waits for the selected backend to report ready, checks the harness CLI against the registry's pin, clones `workspace.repoUrl`, and creates the environment through `createCliBridgeProvider` at the exposed URL.
+- Any failure after the vendor create destroys the sandbox before the error surfaces; a destroy that fails carries the sandbox id as `cleanupHandle`.
+- Turns run through the Bridge. `turn.timeoutMs` cancels the run and ends the stream with a failed `result` that names the timeout, an abort rejects with `AbortError`, and a second turn on a busy environment is refused with `conflict`.
+- Events carry `execution.started` with the declared model and a terminal `result` with the model the harness reported serving. The Bridge's dollar figure is the harness's catalog estimate, so events omit `usage.cost`.
+
+The box image is `renderBoxDockerfile()`: Node, CLI Bridge at the commit in `BOX_PINS`, and each harness CLI at the version `@tangle-network/cli-agent-registry` pins.
+A harness joins `BOX_HARNESSES` only after a live turn through the Router completed in a box; `claude-code` is the proven row.
+Build the image for a cloud with `pnpm build:sandbox-image --target e2b|daytona|docker` from the repository root.
+`@tangle-network/agent-provider-testkit` runs the live profile conformance suite against the result.
+

package/dist/retained-canonical-event.d.ts

@@ -1,6 +1,6 @@
 import { type StreamEvent } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentEvent } from "@tangle-network/agent-interface/environment-provider";
-import type { CliBridgeSseFrame } from "./wire.js";
+import { type CliBridgeSseFrame } from "./wire.js";
 interface CanonicalEventContext {
     readonly runId: string;
     readonly sessionId: string;

package/dist/retained-canonical-event.js

@@ -1,4 +1,5 @@
 import { RuntimeEventEnvelopeSchema, } from "@tangle-network/agent-interface";
+import { providerUsageFromOpenAi as recordValue, usageFromOpenAi } from "./wire.js";
 /** Decode one explicitly typed retained-run frame without guessing its wire format. */
 export function retainedCanonicalEvent(frame, context) {
     if (frame.event === undefined)
@@ -82,39 +83,12 @@ function usageFromCanonicalEvent(event) {
     const usage = recordValue(providerEvent.usage) ?? recordValue(data?.usage);
     if (!usage)
         return undefined;
-    const inputTokens = nonNegativeInteger(usage.inputTokens);
-    const outputTokens = nonNegativeInteger(usage.outputTokens);
-    if (inputTokens === undefined || outputTokens === undefined)
-        return undefined;
-    return {
-        inputTokens,
-        outputTokens,
-        ...optionalInteger(usage, "totalTokens"),
-        ...optionalInteger(usage, "cacheReadInputTokens"),
-        ...optionalInteger(usage, "cacheCreationInputTokens"),
-        ...optionalInteger(usage, "reasoningTokens"),
-        ...optionalNumber(usage, "cost"),
-    };
-}
-function optionalInteger(source, key) {
-    const value = nonNegativeInteger(source[key]);
-    return value === undefined ? {} : { [key]: value };
-}
-function optionalNumber(source, key) {
-    const value = source[key];
-    return typeof value === "number" && Number.isFinite(value) && value >= 0
-        ? { [key]: value }
-        : {};
-}
-function nonNegativeInteger(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
-        ? value
-        : undefined;
-}
-function recordValue(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value
-        : undefined;
+    return usageFromOpenAi({
+        prompt_tokens: usage.inputTokens, completion_tokens: usage.outputTokens,
+        total_tokens: usage.totalTokens, cache_read_input_tokens: usage.cacheReadInputTokens,
+        cache_write_input_tokens: usage.cacheCreationInputTokens, reasoning_tokens: usage.reasoningTokens,
+        cost: usage.cost,
+    });
 }
 function isBaseTenInteger(value) {
     return /^(0|[1-9][0-9]*)$/u.test(value) && Number.isSafeInteger(Number(value));

package/dist/retained-environment.js

@@ -46,11 +46,10 @@ export function createCliBridgeEnvironment(args) {
         }
         assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
         const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions, args.acceptedContextTransfer);
-        // A streamed run reports usage across its events, so the totals are summed
-        // here and recorded as one execution's measurement.
+        // Delta receipts add; cumulative receipts replace this execution's measurement.
         let streamedUsage;
         for await (const event of streamTrackedCliBridgeTurn(options, environmentInput, providerName, prepared, transport, runs, sessions, readers, nativeSessions, useNativeInteractions)) {
-            streamedUsage = addTokenUsage(streamedUsage, event.usage);
+            streamedUsage = addTokenUsage(streamedUsage, event.usage, event.usageMode);
             usageLog.record(prepared.run.executionId, streamedUsage);
             yield event;
         }

package/dist/retained-execution.d.ts

@@ -14,5 +14,5 @@ export declare function streamCliBridgeSessionEvents(options: CliBridgeProviderO
 export declare function collectCliBridgeTurnResult(source: AsyncIterable<AgentEnvironmentEvent>, run: CliBridgeRun, options: CliBridgeProviderOptions, transport: CliBridgeTransport, signal?: AbortSignal): Promise<AgentTurnResult>;
 /** Keep reasoning and tool updates out of the assistant's visible result text. */
 export declare function visibleTextDelta(event: AgentEnvironmentEvent): string | undefined;
-/** Sum the usage a run reported across its events into one total. */
-export declare function addTokenUsage(current: TokenUsage | undefined, next: TokenUsage | undefined): TokenUsage | undefined;
+/** Respect cumulative receipts and keep missing optional classes unknown. */
+export declare function addTokenUsage(current: TokenUsage | undefined, next: TokenUsage | undefined, mode?: "delta" | "cumulative"): TokenUsage | undefined;

package/dist/retained-execution.js

@@ -1,10 +1,9 @@
-import { AgentTurnResultSchema, } from "@tangle-network/agent-interface";
+import { AgentTurnResultSchema, CONTRACT_MAX_ARRAY_LENGTH, } from "@tangle-network/agent-interface";
 import { cancelCliBridgeRun, captureCliBridgeRunIdentity, cliBridgeCancellationSignal, detachCliBridgeReader, getCliBridgeRun, } from "./retained-control.js";
 import { bindCliBridgeRun, bindCliBridgeSession, exactControlRefForRun, restoreCliBridgeRun, restoreCliBridgeSession, } from "./retained-run-state.js";
-import { CliBridgeRequestRejectedError, streamCliBridgeTurn, } from "./retained-stream.js";
+import { CliBridgeRequestRejectedError, openCliBridgeStream, streamCliBridgeTurn, } from "./retained-stream.js";
 import { beginCliBridgeNativeTurn, } from "./retained-native.js";
-import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
-import { modelRequestCount } from "./wire.js";
+import { modelRequestCount, providerUsageFromOpenAi, responseIdentityFromOpenAi, usageFromOpenAi } from "./wire.js";
 import { lookupCliBridgeContext } from "./context-transfer.js";
 const MAX_CLI_BRIDGE_RESULT_EVENTS = 1_024;
 export async function* streamTrackedCliBridgeTurn(options, environmentInput, providerName, prepared, transport, runs, sessions, readers, nativeSessions, useNativeInteractions) {
@@ -119,26 +118,9 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
             });
         }
         else {
-            const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/chat/completions`, {
-                method: "POST",
-                headers: {
-                    ...requestHeaders(options),
-                    accept: "text/event-stream",
-                    ...(run.sessionId ? { "x-session-id": run.sessionId } : {}),
-                },
-                body: run.requestBody,
-                ...(signal ? { signal } : {}),
-            });
-            if (!response.ok) {
-                let detail = "request rejected";
-                try {
-                    detail = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
-                }
-                catch {
-                    // The HTTP status already proves this request was rejected.
-                }
-                throw new CliBridgeRequestRejectedError(response.status, detail);
-            }
+            const response = await openCliBridgeStream([
+                options, { ...prepared.turn, sessionId: run.sessionId }, run.requestBody, transport, run.id, undefined, signal,
+            ]);
             accepted = true;
             if (!response.body)
                 throw new Error("cli-bridge response body is empty");
@@ -261,6 +243,9 @@ export async function collectCliBridgeTurnResult(source, run, options, transport
     let eventCount = 0;
     let text = "";
     let usage;
+    let providerUsage;
+    let providerTokensSeen = false;
+    const providerModels = new Set();
     let observedModelRequests = 0;
     let modelRequestsKnown = false;
     let terminalModelRequests;
@@ -283,7 +268,20 @@ export async function collectCliBridgeTurnResult(source, run, options, transport
                 if (delta !== undefined)
                     text += delta;
             }
-            usage = addTokenUsage(usage, event.usage);
+            const observedUsage = providerUsageFromOpenAi(providerUsageFromOpenAi(event.providerEvent)?.usage);
+            const rawUsage = observedUsage ??
+                (event.usage ? { prompt_tokens: event.usage.inputTokens, completion_tokens: event.usage.outputTokens } : undefined);
+            if (rawUsage) {
+                providerUsage = foldProviderUsage(providerUsage, rawUsage, event.usageMode, providerTokensSeen);
+                providerTokensSeen = event.usageMode === "cumulative"
+                    ? hasTokenReceipt(rawUsage) : providerTokensSeen || hasTokenReceipt(rawUsage);
+            }
+            usage = observedUsage ? usageFromOpenAi(providerUsage) : addTokenUsage(usage, event.usage, event.usageMode);
+            for (const model of responseIdentityFromOpenAi(event.data)?.provider_models ?? []) {
+                providerModels.add(model);
+                if (providerModels.size > CONTRACT_MAX_ARRAY_LENGTH)
+                    throw new Error("cli-bridge provider model observations exceed contract bounds");
+            }
             const eventModel = event.data.model;
             const eventFingerprint = event.data.system_fingerprint;
             if (typeof eventModel === "string" && eventModel.length > 0)
@@ -350,6 +348,9 @@ export async function collectCliBridgeTurnResult(source, run, options, transport
                     ? { modelRequests: observedModelRequests }
                     : {}),
             ...(servedModel === undefined ? {} : { model: servedModel }),
+            ...(providerModels.size ? { provider_models: [...providerModels] } : {}),
+            ...(success && providerModels.size === 1 ? { provider_model: [...providerModels][0] } : {}),
+            ...(providerUsage === undefined ? {} : { provider_usage: providerUsage }),
             ...(systemFingerprint === undefined ? {} : { system_fingerprint: systemFingerprint }),
         },
         events: resultEvents,
@@ -374,39 +375,56 @@ export function visibleTextDelta(event) {
     }
     return typeof event.data.delta === "string" ? event.data.delta : undefined;
 }
-/** Sum the usage a run reported across its events into one total. */
-export function addTokenUsage(current, next) {
+/** Respect cumulative receipts and keep missing optional classes unknown. */
+export function addTokenUsage(current, next, mode) {
+    if (mode === "cumulative")
+        return next ? { ...next } : undefined;
     if (!next)
         return current;
     if (!current)
         return { ...next };
-    return {
-        inputTokens: current.inputTokens + next.inputTokens,
-        outputTokens: current.outputTokens + next.outputTokens,
-        ...(current.totalTokens !== undefined || next.totalTokens !== undefined
-            ? { totalTokens: (current.totalTokens ?? 0) + (next.totalTokens ?? 0) }
-            : {}),
-        ...(current.cacheReadInputTokens !== undefined ||
-            next.cacheReadInputTokens !== undefined
-            ? {
-                cacheReadInputTokens: (current.cacheReadInputTokens ?? 0) +
-                    (next.cacheReadInputTokens ?? 0),
-            }
-            : {}),
-        ...(current.cacheCreationInputTokens !== undefined ||
-            next.cacheCreationInputTokens !== undefined
-            ? {
-                cacheCreationInputTokens: (current.cacheCreationInputTokens ?? 0) +
-                    (next.cacheCreationInputTokens ?? 0),
-            }
-            : {}),
-        ...(current.reasoningTokens !== undefined || next.reasoningTokens !== undefined
-            ? {
-                reasoningTokens: (current.reasoningTokens ?? 0) + (next.reasoningTokens ?? 0),
+    return Object.fromEntries(Object.entries(next).flatMap(([key, count]) => {
+        const prior = current[key];
+        return prior === undefined ? [] : [[key, prior + count]];
+    }));
+}
+const TOKEN_FIELDS = ["prompt_tokens", "input_tokens", "completion_tokens", "output_tokens", "total_tokens",
+    "fresh_input_tokens", "cache_read_input_tokens", "cache_write_input_tokens", "cache_creation_input_tokens", "reasoning_tokens"];
+const hasTokenReceipt = (usage) => TOKEN_FIELDS.some(key => key in usage) || "estimated" in usage;
+/** Coverage lives outside the bounded event ring: a later delta cannot fill an earlier omission. */
+function foldProviderUsage(current, next, mode, hasPriorTokens) {
+    if (!current || mode === "cumulative")
+        return { ...next };
+    const folded = { ...current, ...next };
+    if (hasTokenReceipt(next)) {
+        for (const key of [...TOKEN_FIELDS, "model_requests"]) {
+            const value = next[key], prior = current[key];
+            if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0 &&
+                (!hasPriorTokens || (typeof prior === "number" && Number.isSafeInteger(prior) && prior >= 0))) {
+                const count = value + (hasPriorTokens ? prior : 0);
+                if (Number.isSafeInteger(count)) {
+                    folded[key] = count;
+                    continue;
+                }
             }
-            : {}),
-        ...(current.cost !== undefined || next.cost !== undefined
-            ? { cost: (current.cost ?? 0) + (next.cost ?? 0) }
-            : {}),
-    };
+            delete folded[key];
+        }
+        const estimated = current.estimated === true || next.estimated === true ? true :
+            next.estimated === false && (!hasPriorTokens || current.estimated === false) ? false : undefined;
+        if (estimated === undefined)
+            delete folded.estimated;
+        else
+            folded.estimated = estimated;
+    }
+    if (next.cost_scope !== "total") {
+        const cost = current.cost, delta = next.cost;
+        if (current.cost_known === true && next.cost_known === true && typeof cost === "number" && typeof delta === "number") {
+            folded.cost = cost + delta;
+        }
+        else {
+            delete folded.cost;
+            folded.cost_known = false;
+        }
+    }
+    return folded;
 }

package/dist/retained-stream.d.ts

@@ -7,3 +7,5 @@ export declare class CliBridgeRequestRejectedError extends Error {
     constructor(status: number, detail: string);
 }
 export declare function streamCliBridgeTurn(options: CliBridgeProviderOptions, turn: AgentTurnInput, requestBody: string | undefined, transport: CliBridgeTransport, runId: string, lastEventId?: string, signal?: AbortSignal, onResponse?: (response: CliBridgeResponse) => void, readAuthoritativeRun?: () => Promise<CliBridgeRunSnapshot | null>, validateCanonicalEvent?: (event: AgentEnvironmentEvent) => void): AsyncIterable<AgentEnvironmentEvent>;
+/** Both dispatch and live readers use the same admission and bounded HTTP refusal. */
+export declare function openCliBridgeStream([options, turn, requestBody, transport, runId, lastEventId, signal, onResponse]: Parameters<typeof streamCliBridgeTurn>): Promise<CliBridgeResponse>;

package/dist/retained-stream.js

@@ -2,7 +2,7 @@ import { retainedEventsWithIdentity, retainedReplayRequest, } from "./retained-e
 import { isTerminalCanonicalEvent, retainedCanonicalEvent, } from "./retained-canonical-event.js";
 import { detachCliBridgeReader } from "./retained-control.js";
 import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, MAX_CLI_BRIDGE_RESULT_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
-import { modelRequestsFromOpenAi, parseSse, responseIdentityFromOpenAi, safeJson, toolCallsFromDelta, usageFromOpenAi, } from "./wire.js";
+import { modelRequestsFromOpenAi, parseSse, providerUsageFromOpenAi, responseIdentityFromOpenAi, safeJson, toolCallsFromDelta, usageFromOpenAi, } from "./wire.js";
 export class CliBridgeRequestRejectedError extends Error {
     status;
     constructor(status, detail) {
@@ -20,47 +20,8 @@ class CliBridgeRunCancelledError extends Error {
     }
 }
 export async function* streamCliBridgeTurn(options, turn, requestBody, transport, runId, lastEventId, signal, onResponse, readAuthoritativeRun, validateCanonicalEvent) {
-    const reconnect = requestBody === undefined;
     const replay = retainedReplayRequest(lastEventId);
-    const response = await transport.fetch(reconnect
-        ? `${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(runId)}/events`
-        : `${trimSlash(options.baseUrl)}/v1/chat/completions`, {
-        method: reconnect ? "GET" : "POST",
-        headers: {
-            ...requestHeaders(options),
-            accept: "text/event-stream",
-            ...(!reconnect && turn.sessionId ? { "x-session-id": turn.sessionId } : {}),
-            ...(replay.serverCursor === undefined
-                ? {}
-                : { "last-event-id": replay.serverCursor }),
-        },
-        ...(requestBody === undefined ? {} : { body: requestBody }),
-        ...(signal ? { signal } : {}),
-    });
-    if (!response.ok) {
-        let detail = "request rejected";
-        try {
-            detail = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
-        }
-        catch {
-            // The HTTP status already proves this request was rejected.
-        }
-        throw new CliBridgeRequestRejectedError(response.status, detail);
-    }
-    try {
-        onResponse?.(response);
-    }
-    catch (error) {
-        if (response.body) {
-            try {
-                await detachCliBridgeReader(response.body);
-            }
-            catch (detachError) {
-                throw new AggregateError([error, detachError], `cli-bridge rejected response identity for run "${runId}" and could not detach its reader`);
-            }
-        }
-        throw error;
-    }
+    const response = await openCliBridgeStream([options, turn, requestBody, transport, runId, lastEventId, signal, onResponse]);
     if (!response.body)
         throw new Error("cli-bridge response body is empty");
     let text = "";
@@ -68,7 +29,6 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
     const messageId = turn.turnId ?? `${sessionId}:assistant`;
     const emittedToolCalls = new Set();
     let completed = false;
-    let sawUsage = false;
     let observedModelRequests = 0;
     let modelRequestsKnown = false;
     let servedModel;
@@ -156,6 +116,8 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
             systemFingerprint = responseIdentity.system_fingerprint;
         }
         const identityData = {
+            ...(responseIdentity?.provider_models ? { provider_models: responseIdentity.provider_models } : {}),
+            ...(responseIdentity?.provider_model ? { provider_model: responseIdentity.provider_model } : {}),
             ...(servedModel === undefined ? {} : { model: servedModel }),
             ...(systemFingerprint === undefined ? {} : { system_fingerprint: systemFingerprint }),
         };
@@ -171,12 +133,11 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
             : rawChunk;
         if (rawChunk && toolCallDeltas.length === 0)
             textBoundaryPending = false;
-        const nextUsage = usageFromOpenAi(parsed.usage);
+        const rawUsage = providerUsageFromOpenAi(parsed.usage);
+        const nextUsage = usageFromOpenAi(rawUsage);
         const nextModelRequests = modelRequestsFromOpenAi(parsed.usage);
         const frameEvents = [];
-        if (nextUsage || nextModelRequests !== undefined) {
-            if (nextUsage)
-                sawUsage = true;
+        if (rawUsage || nextModelRequests !== undefined) {
             if (nextModelRequests !== undefined) {
                 observedModelRequests += nextModelRequests;
                 modelRequestsKnown = true;
@@ -188,6 +149,8 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
                     ...(nextModelRequests === undefined ? {} : { modelRequests: nextModelRequests }),
                 },
                 ...(nextUsage ? { usage: nextUsage } : {}),
+                usageMode: "delta",
+                providerEvent: { usage: rawUsage },
             });
         }
         if (chunk) {
@@ -236,6 +199,9 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
         }
         if (toolCallDeltas.length > 0)
             textBoundaryPending = true;
+        if (responseIdentity?.provider_models && !frameEvents.some(event => event.data.provider_models !== undefined)) {
+            frameEvents.push({ type: "raw", data: identityData, providerEvent: parsed });
+        }
         if (choice?.finish_reason) {
             terminalFrameSeen = true;
             if (choice.finish_reason === "error") {
@@ -261,6 +227,58 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
         }
         yield* retainedEventsWithIdentity(frameEvents, frame.id, runId, sessionId, turn.executionId, replay.anchor);
     }
+    yield* finishCliBridgeStream([options, turn, requestBody, transport, runId, lastEventId, signal, onResponse, readAuthoritativeRun], { protocol, canonicalTerminalStatus, canonicalTerminalEvent, sawProtocolEnd, completed,
+        cancelledTerminalSeen, terminalFrame, text, modelRequestsKnown, observedModelRequests, servedModel, systemFingerprint }, replay.anchor);
+}
+/** Both dispatch and live readers use the same admission and bounded HTTP refusal. */
+export async function openCliBridgeStream([options, turn, requestBody, transport, runId, lastEventId, signal, onResponse]) {
+    const reconnect = requestBody === undefined;
+    const replay = retainedReplayRequest(lastEventId);
+    const response = await transport.fetch(reconnect
+        ? `${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(runId)}/events`
+        : `${trimSlash(options.baseUrl)}/v1/chat/completions`, {
+        method: reconnect ? "GET" : "POST",
+        headers: {
+            ...requestHeaders(options),
+            accept: "text/event-stream",
+            ...(!reconnect && turn.sessionId ? { "x-session-id": turn.sessionId } : {}),
+            ...(replay.serverCursor === undefined
+                ? {}
+                : { "last-event-id": replay.serverCursor }),
+        },
+        ...(requestBody === undefined ? {} : { body: requestBody }),
+        ...(signal ? { signal } : {}),
+    });
+    if (!response.ok) {
+        let detail = "request rejected";
+        try {
+            detail = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
+        }
+        catch {
+            // The HTTP status already proves this request was rejected.
+        }
+        throw new CliBridgeRequestRejectedError(response.status, detail);
+    }
+    try {
+        onResponse?.(response);
+    }
+    catch (error) {
+        if (response.body) {
+            try {
+                await detachCliBridgeReader(response.body);
+            }
+            catch (detachError) {
+                throw new AggregateError([error, detachError], `cli-bridge rejected response identity for run "${runId}" and could not detach its reader`);
+            }
+        }
+        throw error;
+    }
+    return response;
+}
+/** Confirm terminal authority before releasing the final frame and its cumulative receipt. */
+async function* finishCliBridgeStream([options, turn, requestBody, transport, runId, lastEventId, signal, onResponse, readAuthoritativeRun], { protocol, canonicalTerminalStatus, canonicalTerminalEvent, sawProtocolEnd, completed, cancelledTerminalSeen, terminalFrame, text, modelRequestsKnown, observedModelRequests, servedModel, systemFingerprint }, anchor) {
+    const sessionId = turn.sessionId ?? runId;
+    const reconnect = requestBody === undefined;
     if (protocol === "canonical") {
         if (canonicalTerminalStatus === undefined) {
             throw new Error("cli-bridge canonical stream ended without terminal status");
@@ -359,7 +377,7 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
                     finalText: lastEventId === undefined ? text : result.text,
                     finishReason: lastEventId === undefined ? terminalFrame.finishReason : result.finishReason,
                     status: "completed",
-                    ...(result.model === undefined ? {} : { model: result.model }),
+                    ...result.identity,
                     ...(result.system_fingerprint === undefined
                         ? {}
                         : { system_fingerprint: result.system_fingerprint }),
@@ -367,7 +385,9 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
                         ? {}
                         : { modelRequests: finalModelRequests }),
                 },
-                ...(result.usage && !sawUsage ? { usage: result.usage } : {}),
+                ...(result.usage ? { usage: result.usage } : {}),
+                ...(result.providerUsage ? { usageMode: "cumulative" } : {}),
+                ...(result.providerUsage ? { providerEvent: { usage: result.providerUsage } } : {}),
             };
         }
     }
@@ -401,7 +421,7 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
         throw new Error("cli-bridge terminal state did not produce a terminal event");
     }
     terminalFrame.events.push(terminalEvent);
-    yield* retainedEventsWithIdentity(terminalFrame.events, terminalFrame.id, runId, sessionId, turn.executionId, replay.anchor);
+    yield* retainedEventsWithIdentity(terminalFrame.events, terminalFrame.id, runId, sessionId, turn.executionId, anchor);
     if (terminalFailure)
         throw terminalFailure;
 }
@@ -476,6 +496,8 @@ async function readFullCliBridgeResult(options, requestBody, transport, signal,
         text: message.content,
         finishReason: choice.finish_reason,
         ...(usage ? { usage } : {}),
+        providerUsage: providerUsageFromOpenAi(parsed?.usage),
+        identity: responseIdentity,
         ...(modelRequests === undefined ? {} : { modelRequests }),
         ...(responseIdentity?.model === undefined ? {} : { model: responseIdentity.model }),
         ...(responseIdentity?.system_fingerprint === undefined

package/dist/sandbox/box.d.ts

@@ -0,0 +1,60 @@
+import type { HarnessType } from "@tangle-network/agent-interface";
+/**
+ * The box: one image every cloud runs, holding Node, CLI Bridge and the pinned
+ * harness CLIs. The Bridge listens on {@link BRIDGE_PORT}, materializes the
+ * exact profile and starts the selected harness exactly as it does for Braid
+ * on a local machine.
+ */
+export declare const BRIDGE_PORT = 3344;
+/** The box user's home. */
+export declare const BOX_HOME = "/home/node";
+/** The default workspace directory; `workspace.cwd` with `base: "repository"` resolves under it. */
+export declare const BOX_WORKSPACE_DIR = "/home/node/workspace";
+export declare const BRIDGE_DATA_DIR = "/home/node/.cli-bridge";
+export declare const BOX_NODE_IMAGE = "node:24.22.1-trixie-slim";
+/**
+ * The CLI Bridge source revision the box installs, reviewed as a commit.
+ * `agentProfileMaterialize` is the exact version of the planner that revision
+ * pins; {@link createBridgeSandboxProvider} plans with the same version, and
+ * the image build refuses a revision whose pin differs.
+ */
+export declare const BOX_PINS: {
+    readonly cliBridgeRepository: "drewstone/cli-bridge";
+    readonly cliBridgeCommit: "263f700dc5ca8b7b6e53b986d376102e0d82b42f";
+    readonly agentProfileMaterialize: "1.1.4";
+};
+export interface BoxRouter {
+    /** Router root URL, without a path. */
+    baseUrl: string;
+    /** The per-run capped Router key. */
+    key: string;
+}
+/**
+ * A harness the box carries and routes through the Tangle Router.
+ *
+ * A harness joins this table only after a live turn through the Router
+ * completed in a box, so the declared set is the proven set.
+ */
+export interface BoxHarness {
+    readonly harness: HarnessType;
+    /** The Bridge backend name in `BRIDGE_BACKENDS`. */
+    readonly bridgeBackend: string;
+    /** The npm package that installs the CLI. */
+    readonly npmPackage: string;
+    /** The CLI binary; `<bin> --version` prints the pinned version first. */
+    readonly bin: string;
+    /** Environment that points this harness at the Router, set on the Bridge process only. */
+    routerEnv(router: BoxRouter): Record<string, string>;
+}
+export declare const BOX_HARNESSES: Readonly<Partial<Record<HarnessType, BoxHarness>>>;
+export declare function boxHarness(harness: string | undefined): BoxHarness | undefined;
+/** The CLI version the harness registry pins; the box image installs exactly this. */
+export declare function boxHarnessVersion(harness: HarnessType): string;
+/** The command that starts the Bridge; its settings come from the process environment. */
+export declare const BRIDGE_START_COMMAND = "cli-bridge";
+/**
+ * The Bridge process environment. `bearer` guards the exposed port; the Router
+ * variables reach the harness through the Bridge's child environment and
+ * appear in no command line or file.
+ */
+export declare function bridgeProcessEnv(harness: BoxHarness, bearer: string, router: BoxRouter): Record<string, string>;

package/dist/sandbox/box.js

@@ -0,0 +1,68 @@
+import { NATIVE_SESSION_CONTRACTS } from "@tangle-network/cli-agent-registry/native-session-contracts";
+/**
+ * The box: one image every cloud runs, holding Node, CLI Bridge and the pinned
+ * harness CLIs. The Bridge listens on {@link BRIDGE_PORT}, materializes the
+ * exact profile and starts the selected harness exactly as it does for Braid
+ * on a local machine.
+ */
+export const BRIDGE_PORT = 3344;
+/** The box user's home. */
+export const BOX_HOME = "/home/node";
+/** The default workspace directory; `workspace.cwd` with `base: "repository"` resolves under it. */
+export const BOX_WORKSPACE_DIR = `${BOX_HOME}/workspace`;
+export const BRIDGE_DATA_DIR = `${BOX_HOME}/.cli-bridge`;
+export const BOX_NODE_IMAGE = "node:24.22.1-trixie-slim";
+/**
+ * The CLI Bridge source revision the box installs, reviewed as a commit.
+ * `agentProfileMaterialize` is the exact version of the planner that revision
+ * pins; {@link createBridgeSandboxProvider} plans with the same version, and
+ * the image build refuses a revision whose pin differs.
+ */
+export const BOX_PINS = {
+    cliBridgeRepository: "drewstone/cli-bridge",
+    cliBridgeCommit: "263f700dc5ca8b7b6e53b986d376102e0d82b42f",
+    agentProfileMaterialize: "1.1.4",
+};
+export const BOX_HARNESSES = {
+    "claude-code": {
+        harness: "claude-code",
+        bridgeBackend: "claude",
+        npmPackage: "@anthropic-ai/claude-code",
+        bin: "claude",
+        // The Router authenticates a Bearer token. ANTHROPIC_API_KEY sends x-api-key, which it rejects.
+        routerEnv: (router) => ({
+            ANTHROPIC_BASE_URL: router.baseUrl,
+            ANTHROPIC_AUTH_TOKEN: router.key,
+        }),
+    },
+};
+export function boxHarness(harness) {
+    return harness === undefined ? undefined : BOX_HARNESSES[harness];
+}
+/** The CLI version the harness registry pins; the box image installs exactly this. */
+export function boxHarnessVersion(harness) {
+    const contract = NATIVE_SESSION_CONTRACTS[harness];
+    if (contract?.cliVersion === undefined) {
+        throw new Error(`cli-agent-registry pins no CLI version for harness ${harness}`);
+    }
+    return contract.cliVersion;
+}
+/** The command that starts the Bridge; its settings come from the process environment. */
+export const BRIDGE_START_COMMAND = "cli-bridge";
+/**
+ * The Bridge process environment. `bearer` guards the exposed port; the Router
+ * variables reach the harness through the Bridge's child environment and
+ * appear in no command line or file.
+ */
+export function bridgeProcessEnv(harness, bearer, router) {
+    return {
+        BRIDGE_HOST: "0.0.0.0",
+        BRIDGE_PORT: String(BRIDGE_PORT),
+        BRIDGE_BEARER: bearer,
+        BRIDGE_BACKENDS: harness.bridgeBackend,
+        BRIDGE_DATA_DIR: BRIDGE_DATA_DIR,
+        BRIDGE_JAIL_MODE: "off",
+        HOME: BOX_HOME,
+        ...harness.routerEnv(router),
+    };
+}