@tangle-network/agent-provider-cli-bridge 2.0.1 → 2.0.3

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.

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/wire.d.ts

@@ -27,11 +27,14 @@ export declare function toolCallsFromDelta(value: unknown): Array<{
 }>;
 export declare function safeJson(value: string): Record<string, unknown> | null;
 export declare function usageFromOpenAi(value: unknown): TokenUsage | undefined;
+export declare function providerUsageFromOpenAi(value: unknown): Record<string, unknown> | undefined;
 export declare function modelRequestsFromOpenAi(value: unknown): number | undefined;
-/** Preserve the provider identity that cli-bridge returns on each completion frame. */
+/** Compatibility model and explicit provider observations have different authority. */
 export declare function responseIdentityFromOpenAi(value: unknown): {
     model?: string;
     system_fingerprint?: string;
+    provider_models?: string[];
+    provider_model?: string;
 } | undefined;
 export declare function modelRequestCount(value: unknown): number | undefined;
 export declare function cliBridgeRunId(environmentId: string, turn: AgentTurnInput, turnId: string): string;

package/dist/wire.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { AgentExactRunControlRefSchema, RequestedInteractionsSchema, WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface";
+import { AgentExactRunControlRefSchema, CONTRACT_MAX_ARRAY_LENGTH, RequestedInteractionsSchema, WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface";
 export function toChatCompletionsBody(options, environmentInput, turn, coordinates) {
     const profile = inlineProfile(environmentInput.profile);
     const execution = executionFromInput(options, environmentInput);
@@ -257,47 +257,61 @@ export function safeJson(value) {
     }
 }
 export function usageFromOpenAi(value) {
-    if (!value || typeof value !== "object")
+    const record = providerUsageFromOpenAi(value);
+    if (!record)
         return undefined;
-    const record = value;
-    const inputTokens = nonNegativeSafeInteger(record.prompt_tokens) ??
-        nonNegativeSafeInteger(record.input_tokens);
-    const outputTokens = nonNegativeSafeInteger(record.completion_tokens) ??
-        nonNegativeSafeInteger(record.output_tokens);
+    const inputTokens = nonNegativeSafeInteger(record.prompt_tokens) ?? nonNegativeSafeInteger(record.input_tokens);
+    const outputTokens = nonNegativeSafeInteger(record.completion_tokens) ?? nonNegativeSafeInteger(record.output_tokens);
     if (inputTokens === undefined || outputTokens === undefined)
         return undefined;
-    const totalTokens = nonNegativeSafeInteger(record.total_tokens);
-    const cacheReadInputTokens = nonNegativeSafeInteger(record.cache_read_input_tokens);
-    const cacheCreationInputTokens = nonNegativeSafeInteger(record.cache_creation_input_tokens);
-    const reasoningTokens = nonNegativeSafeInteger(record.reasoning_tokens);
+    const usage = { inputTokens, outputTokens };
+    for (const [key, wireKey] of [
+        ["totalTokens", "total_tokens"], ["cacheReadInputTokens", "cache_read_input_tokens"],
+        ["cacheCreationInputTokens", "cache_write_input_tokens"], ["reasoningTokens", "reasoning_tokens"],
+    ]) {
+        const count = nonNegativeSafeInteger(record[wireKey]) ??
+            (key === "cacheCreationInputTokens" ? nonNegativeSafeInteger(record.cache_creation_input_tokens) : undefined);
+        if (count !== undefined)
+            usage[key] = count;
+    }
     const cost = finiteNonNegativeNumber(record.cost);
-    return {
-        inputTokens,
-        outputTokens,
-        ...(totalTokens !== undefined ? { totalTokens } : {}),
-        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
-        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
-        ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
-        ...(cost !== undefined ? { cost } : {}),
-    };
+    if (cost !== undefined)
+        usage.cost = cost;
+    return usage;
+}
+export function providerUsageFromOpenAi(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
 }
 export function modelRequestsFromOpenAi(value) {
     if (!value || typeof value !== "object")
         return undefined;
     return modelRequestCount(value.model_requests);
 }
-/** Preserve the provider identity that cli-bridge returns on each completion frame. */
+/** Compatibility model and explicit provider observations have different authority. */
 export function responseIdentityFromOpenAi(value) {
-    if (!value || typeof value !== "object")
-        return undefined;
-    const record = value;
-    const model = nonEmptyString(record.model);
-    const systemFingerprint = nonEmptyString(record.system_fingerprint);
-    if (model === undefined && systemFingerprint === undefined)
+    const record = providerUsageFromOpenAi(value);
+    if (!record)
         return undefined;
+    if (record.provider_model !== undefined && nonEmptyString(record.provider_model) === undefined) {
+        throw new Error("cli-bridge returned an invalid provider model observation");
+    }
+    const models = record.provider_models;
+    if (models !== undefined && (!Array.isArray(models) || models.length > CONTRACT_MAX_ARRAY_LENGTH ||
+        models.some(model => nonEmptyString(model) === undefined))) {
+        throw new Error("cli-bridge returned invalid provider model observations");
+    }
+    const observations = [...new Set([
+            ...(models ?? []),
+            ...(nonEmptyString(record.provider_model) ? [record.provider_model] : []),
+        ])];
+    if (observations.length > CONTRACT_MAX_ARRAY_LENGTH)
+        throw new Error("cli-bridge provider model observations exceed contract bounds");
     return {
-        ...(model === undefined ? {} : { model }),
-        ...(systemFingerprint === undefined ? {} : { system_fingerprint: systemFingerprint }),
+        ...(nonEmptyString(record.model) ? { model: record.model } : {}),
+        ...(nonEmptyString(record.system_fingerprint) ? { system_fingerprint: record.system_fingerprint } : {}),
+        ...(observations.length ? { provider_models: observations } : {}),
+        ...(observations.length === 1 ? { provider_model: observations[0] } : {}),
     };
 }
 export function modelRequestCount(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -64,20 +64,20 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^5.5.0",
-    "undici": "8.11.2"
+    "@tangle-network/agent-interface": "^5.10.2",
+    "undici": "8.12.3"
   },
   "devDependencies": {
-    "@tangle-network/agent-provider-testkit": "0.12.0",
-    "@types/node": "26.6.3",
-    "typescript": "7.0.2",
-    "vitest": "5.0.2"
+    "@tangle-network/agent-provider-testkit": "0.12.1",
+    "@types/node": "26.6.5",
+    "typescript": "6.0.3",
+    "vitest": "5.0.5"
   },
   "scripts": {
     "build": "pnpm run clean && tsc -p tsconfig.build.json",
     "check-types": "tsc --noEmit",
     "clean": "rm -rf dist",
     "test": "vitest run src",
-    "test:integration": "test -n \"$CLI_BRIDGE_INTEGRATION_ROOT\" || { echo 'CLI_BRIDGE_INTEGRATION_ROOT is required; see README' >&2; exit 1; }; pnpm run build && vitest run tests/cli-bridge.integration.test.ts"
+    "test:integration": "test -n \"$CLI_BRIDGE_INTEGRATION_ROOT\" || { echo 'CLI_BRIDGE_INTEGRATION_ROOT is required; see README' >&2; exit 1; }; pnpm run build && vitest run tests"
   }
 }