@animalabs/membrane 0.5.80 → 0.5.81

package/src/providers/anthropic.ts

@@ -20,8 +20,10 @@ import {
   authError,
   serverError,
   abortError,
+  unsupportedError,
 } from '../types/index.js';
 import { flattenRootSchemaUnion } from './anthropic-tool-schema.js';
+import { assertTerminalEventObserved } from './utils.js';
 import { CacheKeepalive, type CacheKeepaliveConfig } from '../cache-keepalive.js';
 
 // ============================================================================
@@ -144,6 +146,18 @@ export interface AnthropicAdapterConfig {
 
   /** Default headers to include with Anthropic requests */
   defaultHeaders?: ClientOptions['defaultHeaders'];
+
+  /**
+   * Live per-request headers, evaluated at request time — for values that
+   * change between calls (e.g. household telemetry stamps such as
+   * `x-gate-debt-chunks`, read by an inference gateway and stripped there
+   * before the vendor ever sees them). Merged over the per-request beta
+   * headers for the OUTGOING request only; cache-keepalive replays
+   * deliberately resend their recorded headers, so a telemetry stamp is
+   * never replayed stale — an unstamped touch is honest, a stale stamp lies.
+   * null/undefined/'' values are dropped.
+   */
+  dynamicHeaders?: () => Record<string, string | number | null | undefined>;
   
   /** Default max tokens */
   defaultMaxTokens?: number;
@@ -164,6 +178,14 @@ export interface AnthropicAdapterConfig {
 
 export class AnthropicAdapter implements ProviderAdapter {
   readonly name = 'anthropic';
+
+  /**
+   * Verified live 2026-08-25 (claude-haiku-4-5, 4,650-token cached system
+   * prompt): call 1 returned input_tokens 8 / cache_creation_input_tokens 4650,
+   * call 2 input_tokens 8 / cache_read_input_tokens 4650. `input_tokens` never
+   * counts the cached span.
+   */
+  readonly usageCacheConvention = 'cache-excluded' as const;
   private client: Anthropic;
   private defaultMaxTokens: number;
   /** Any anthropic-beta value from defaultHeaders (e.g. the oauth beta for
@@ -173,6 +195,8 @@ export class AnthropicAdapter implements ProviderAdapter {
   private defaultBeta: string | undefined;
   /** Holds idle agents' cached prefixes warm; undefined when disabled. */
   readonly cacheKeepalive: CacheKeepalive | undefined;
+  /** Live per-request header source (see AnthropicAdapterConfig.dynamicHeaders). */
+  private readonly dynamicHeaders?: () => Record<string, string | number | null | undefined>;
 
   constructor(config: AnthropicAdapterConfig = {}) {
     const clientOptions: ClientOptions = {
@@ -180,6 +204,7 @@ export class AnthropicAdapter implements ProviderAdapter {
       defaultHeaders: config.defaultHeaders,
     };
     this.defaultBeta = extractBetaHeader(config.defaultHeaders);
+    this.dynamicHeaders = config.dynamicHeaders;
 
     if (config.authToken !== undefined) {
       clientOptions.authToken = config.authToken;
@@ -225,7 +250,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const response = await this.client.messages.create(fullRequest, {
         signal: options?.signal,
-        headers,
+        headers: this.liveHeaders(headers),
       });
 
       return this.parseResponse(response, fullRequest);
@@ -298,7 +323,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const stream = await this.client.messages.stream(anthropicRequest, {
         signal: idleAbort.signal,
-        headers: this.betaHeaders(request),
+        headers: this.liveHeaders(this.betaHeaders(request)),
       });
 
       // Accumulate response metadata from SSE events directly, so we can
@@ -314,6 +339,7 @@ export class AnthropicAdapter implements ProviderAdapter {
       let inferenceGeo: string | undefined;
       let serviceTier: string | undefined;
       let stopReason: string = 'end_turn';
+      let sawTerminalEvent = false;
       let stopSequence: string | undefined;
       let stopDetails: unknown;
 
@@ -329,6 +355,43 @@ export class AnthropicAdapter implements ProviderAdapter {
       // thinking blocks with no thinking_delta at all (signature only).
       const wrapThinkingTags = options?.wrapThinkingTags === true;
       let thinkingTagOpen = false;
+      // Index of a block that has started and not yet been stopped. A stream
+      // can end with one still open: measured live against claude-haiku-4-5
+      // (2026-08-25), a tool call truncated by max_tokens emits
+      // content_block_start + input_json_delta fragments and then goes
+      // straight to message_delta — no content_block_stop at all.
+      let openBlockIndex = -1;
+
+      const finalizeContentBlock = (blockIdx: number, sawBlockStop: boolean): void => {
+        const block = contentBlocks[blockIdx];
+        if (block) {
+          if (block.type === 'text') {
+            block.text = currentBlockContent;
+          } else if (block.type === 'thinking') {
+            block.thinking = currentBlockContent;
+            if (thinkingTagOpen) {
+              callbacks.onChunk('</thinking>\n');
+              thinkingTagOpen = false;
+            }
+          } else if (block.type === 'tool_use') {
+            if (!sawBlockStop) {
+              // Arguments never finished arriving, so `input` is still the
+              // empty object content_block_start carried — a plausible no-arg
+              // call that nothing downstream can distinguish from a real one.
+              block.unparseableInput = currentBlockInputJson;
+            } else if (currentBlockInputJson) {
+              try {
+                block.input = JSON.parse(currentBlockInputJson);
+              } catch {
+                // Same fabrication, reached by a block that did stop: keep the
+                // raw accumulation and mark it so consumers can refuse.
+                block.unparseableInput = currentBlockInputJson;
+              }
+            }
+          }
+        }
+        callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
+      };
 
       for await (const event of stream) {
         sawEvent = true;
@@ -354,6 +417,7 @@ export class AnthropicAdapter implements ProviderAdapter {
 
         } else if (event.type === 'content_block_start') {
           currentBlockIndex = event.index;
+          openBlockIndex = event.index;
           currentBlockContent = '';
           currentBlockInputJson = '';
           contentBlocks[currentBlockIndex] = { ...event.content_block };
@@ -387,22 +451,8 @@ export class AnthropicAdapter implements ProviderAdapter {
 
         } else if (event.type === 'content_block_stop') {
           // Finalize block — use event.index for defensive correctness
-          const blockIdx = (event as { index: number }).index;
-          const block = contentBlocks[blockIdx];
-          if (block) {
-            if (block.type === 'text') {
-              block.text = currentBlockContent;
-            } else if (block.type === 'thinking') {
-              block.thinking = currentBlockContent;
-              if (thinkingTagOpen) {
-                callbacks.onChunk('</thinking>\n');
-                thinkingTagOpen = false;
-              }
-            } else if (block.type === 'tool_use' && currentBlockInputJson) {
-              try { block.input = JSON.parse(currentBlockInputJson); } catch { /* partial JSON */ }
-            }
-          }
-          callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
+          finalizeContentBlock((event as { index: number }).index, true);
+          openBlockIndex = -1;
 
         } else if (event.type === 'message_delta') {
           // All content blocks are finalized by the time message_delta arrives.
@@ -414,6 +464,7 @@ export class AnthropicAdapter implements ProviderAdapter {
             stop_details?: unknown;
           };
           stopReason = delta.stop_reason ?? 'end_turn';
+          sawTerminalEvent = true;
           stopSequence = delta.stop_sequence ?? undefined;
           // stop_details carries refusal metadata (e.g., category: 'reasoning_extraction')
           stopDetails = delta.stop_details ?? undefined;
@@ -438,9 +489,22 @@ export class AnthropicAdapter implements ProviderAdapter {
       if (idleTimer) clearTimeout(idleTimer);
       options?.signal?.removeEventListener('abort', onExternalAbort);
 
+      // A block still open here never received its content_block_stop: the
+      // turn ended mid-block. Finalize it so the accumulated text is not lost
+      // and a truncated tool call is marked rather than persisted as `{}`.
+      if (openBlockIndex >= 0) {
+        finalizeContentBlock(openBlockIndex, false);
+        openBlockIndex = -1;
+      }
+
       // Force-close the HTTP connection so we don't block on SSE drain
       try { stream.controller.abort(); } catch { /* already closed */ }
 
+      // message_delta is this adapter's terminal event — the loop breaks on
+      // it. Falling out of the for-await without one means the SSE connection
+      // closed mid-turn, and stopReason is still its 'end_turn' initialiser.
+      assertTerminalEventObserved(sawTerminalEvent, 'Anthropic', fullRequest);
+
       return {
         content: contentBlocks,
         stopReason,
@@ -506,6 +570,19 @@ export class AnthropicAdapter implements ProviderAdapter {
    *  the SDK replaces same-key defaults instead of merging, and the API
    *  accepts comma-separated betas. Undefined when nothing to add, so the
    *  defaults apply untouched. */
+  /** Base headers + the live dynamicHeaders stamp. Request time only: the
+   *  keepalive recorder receives the base headers BEFORE this merge, so
+   *  replayed touches never carry a stale telemetry value. */
+  private liveHeaders(base: Record<string, string> | undefined): Record<string, string> | undefined {
+    const dyn = this.dynamicHeaders?.();
+    if (!dyn) return base;
+    const out: Record<string, string> = { ...(base ?? {}) };
+    for (const [k, v] of Object.entries(dyn)) {
+      if (v !== null && v !== undefined && v !== '') out[k] = String(v);
+    }
+    return Object.keys(out).length ? out : undefined;
+  }
+
   private betaHeaders(request: ProviderRequest): Record<string, string> | undefined {
     if (!thinkingEnabled(request) || !needsInterleavedThinkingBeta(request.model)) {
       return undefined;
@@ -672,6 +749,10 @@ export class AnthropicAdapter implements ProviderAdapter {
   }
 
   private handleError(error: unknown, rawRequest?: unknown): MembraneError {
+    // Already-classified failures (e.g. the stream-integrity guards) keep
+    // their type and retryability instead of being re-derived from a string.
+    if (error instanceof MembraneError) return error;
+
     if (error instanceof Anthropic.APIError) {
       // Mid-stream SSE `error` events are rethrown by the SDK as APIError
       // with status === undefined (sdk core/streaming.js), so the HTTP
@@ -880,6 +961,23 @@ export function toAnthropicContent(blocks: ContentBlock[]): Anthropic.ContentBlo
             media_type: block.source.mediaType as 'application/pdf',
             data: block.source.data,
           },
+          // Anthropic's document block carries the filename as `title`; it was
+          // being dropped, so the model lost the one hint about what the PDF is.
+          ...(block.filename ? { title: block.filename } : {}),
+        });
+        break;
+
+      case 'generated_image':
+        // A provider-generated image is a base64 image with a MIME type, which
+        // is exactly Anthropic's image block — carrying it across costs nothing
+        // and lets an image Gemini produced re-enter Anthropic history.
+        result.push({
+          type: 'image',
+          source: {
+            type: 'base64',
+            media_type: block.mimeType as 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp',
+            data: block.data,
+          },
         });
         break;
         
@@ -919,12 +1017,53 @@ export function toAnthropicContent(blocks: ContentBlock[]): Anthropic.ContentBlo
           data: (block as any).data,
         } as any);
         break;
+
+      default: {
+        // The REQUEST path cannot degrade gracefully: a dropped block reaches
+        // the model as an absence, and it answers about content it was never
+        // shown. `audio` and `video` have no Anthropic Messages representation
+        // at all, and a block type added later would silently join them. Fail
+        // loudly at the boundary instead — the caller can strip or transcode.
+        const unsupportedType = (block as { type?: string }).type ?? 'unknown';
+        throw unsupportedError(
+          `Anthropic has no representation for a "${unsupportedType}" content block, and dropping`
+          + ' it would send the model a message missing content the caller supplied.'
+          + ' Remove or convert the block before sending it on this provider.'
+        );
+      }
     }
   }
 
   return result;
 }
 
+/** Unrecognised response block types warn once each, not once per conversion. */
+const warnedUnconvertibleResponseBlocks = new Set<string>();
+
+/**
+ * The RESPONSE path can degrade gracefully where the request path cannot: the
+ * provider's own block is in hand, so keeping it verbatim on a zero-width
+ * carrier loses nothing recoverable and lets formatters replay it. Warn once
+ * per type so a new provider block type surfaces without flooding the log.
+ */
+function preserveUnconvertibleBlock(block: unknown, sourceLabel: string): ContentBlock {
+  const blockType = (block as { type?: string })?.type ?? 'unknown';
+  if (!warnedUnconvertibleResponseBlocks.has(blockType)) {
+    warnedUnconvertibleResponseBlocks.add(blockType);
+    console.warn(
+      `[membrane:${sourceLabel}] no normalized ContentBlock for provider block type`
+      + ` "${blockType}" — preserving it verbatim as a rawItem carrier so it can be`
+      + ' replayed, but its content is not visible to normalized consumers.'
+    );
+  }
+  return { type: 'text', text: '', rawItem: block } as ContentBlock;
+}
+
+/** Test seam: the once-per-type warn latch is process-wide otherwise. */
+export function resetUnconvertibleBlockWarnings(): void {
+  warnedUnconvertibleResponseBlocks.clear();
+}
+
 /**
  * Convert Anthropic response content to normalized format
  */
@@ -955,11 +1094,14 @@ export function fromAnthropicContent(blocks: Anthropic.ContentBlock[]): ContentB
         break;
         
       default:
-        // Handle redacted_thinking or unknown types
         if ((block as any).type === 'redacted_thinking') {
           // Preserve the encrypted `data` payload — without it the block
           // cannot be round-tripped and prior reasoning is lost.
           result.push({ type: 'redacted_thinking', data: (block as any).data } as any);
+        } else {
+          // server_tool_use, web_search_tool_result, search_result, mcp_tool_use
+          // and anything Anthropic adds later used to fall out here silently.
+          result.push(preserveUnconvertibleBlock(block, 'anthropic'));
         }
         break;
     }

package/src/providers/bedrock.ts

@@ -20,7 +20,7 @@ import {
   serverError,
   abortError,
 } from '../types/index.js';
-import { createCombinedSignal } from './utils.js';
+import { createCombinedSignal, isDeadlineAbort, deadlineTimeoutError, assertTerminalEventObserved } from './utils.js';
 import {
   INTERLEAVED_THINKING_BETA,
   needsInterleavedThinkingBeta,
@@ -273,6 +273,15 @@ async function signRequest(
 export class BedrockAdapter implements ProviderAdapter {
   readonly name = 'bedrock';
 
+  /**
+   * Bedrock serves Anthropic models over the Anthropic Messages payload shape
+   * and this adapter reads Anthropic's own field names
+   * (`cache_read_input_tokens` / `cache_creation_input_tokens`), so it inherits
+   * the convention verified live against api.anthropic.com on 2026-08-25.
+   * Derived from the wire contract, not measured against Bedrock directly.
+   */
+  readonly usageCacheConvention = 'cache-excluded' as const;
+
   private accessKeyId: string;
   private secretAccessKey: string;
   private sessionToken?: string;
@@ -610,6 +619,7 @@ export class BedrockAdapter implements ProviderAdapter {
     let cacheCreationTokens: number | undefined;
     let cacheReadTokens: number | undefined;
     let stopReason: string = 'end_turn';
+    let sawTerminalEvent = false;
     let stopSequence: string | undefined;
     let fullText = '';
 
@@ -782,6 +792,7 @@ export class BedrockAdapter implements ProviderAdapter {
                   }
                   callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
                 } else if (eventData.type === 'message_delta') {
+                  sawTerminalEvent = true;
                   if (eventData.usage) {
                     outputTokens = eventData.usage.output_tokens;
                     // message_delta carries cumulative cache metrics — use as
@@ -833,6 +844,11 @@ export class BedrockAdapter implements ProviderAdapter {
       );
     }
 
+    // The empty-response guard above only catches a stream that produced
+    // NOTHING; a stream truncated after any content passed it and was
+    // reported as a clean end_turn. message_delta is the terminal event.
+    assertTerminalEventObserved(sawTerminalEvent, 'Bedrock', { modelId, ...request });
+
     // Build response from accumulated data
     finalMessage = {
       id: 'msg_stream',
@@ -917,6 +933,14 @@ export class BedrockAdapter implements ProviderAdapter {
   }
 
   private handleError(error: unknown, rawRequest?: unknown): MembraneError {
+    // A deadline abort is a timeout and stays one. Collapsing it into a bare
+    // abortError() here is what erased the identity before Membrane's
+    // caller-signal > timeout > error ladder could read it.
+    if (isDeadlineAbort(error)) return deadlineTimeoutError(error, rawRequest);
+    // Already-classified failures (e.g. the stream-integrity guards) keep
+    // their type and retryability instead of being re-derived from a string.
+    if (error instanceof MembraneError) return error;
+
     if (error instanceof BedrockError) {
       const status = error.status;
       const message = error.message;

package/src/providers/gemini.ts

@@ -28,7 +28,7 @@ import {
   abortError,
   networkError,
 } from '../types/index.js';
-import { createCombinedSignal } from './utils.js';
+import { createCombinedSignal, isDeadlineAbort, deadlineTimeoutError, throwOnStreamErrorFrame, assertTerminalEventObserved } from './utils.js';
 
 // ============================================================================
 // Gemini API Types
@@ -77,11 +77,58 @@ interface GeminiResponse {
     candidatesTokenCount?: number;
     totalTokenCount?: number;
     cachedContentTokenCount?: number;
+    /**
+     * Reasoning ("thinking") tokens. DISJOINT from candidatesTokenCount and
+     * billed at the output rate, so generated output is candidates + thoughts.
+     * Live receipt 2026-08-25, gemini-3.5-flash-lite, thinkingBudget 512:
+     * prompt 35, candidates 2, thoughts 228, total 265 — 35+2+228 === 265.
+     */
+    thoughtsTokenCount?: number;
   };
   modelVersion?: string;
   error?: { code: number; message: string; status: string };
 }
 
+/**
+ * Map Gemini's `usageMetadata` onto membrane's usage shape.
+ *
+ * `thoughtsTokenCount` is disjoint from `candidatesTokenCount` and billed at
+ * the output rate, so generated output is the SUM of the two; reading only
+ * candidates reported a thinking turn at a fraction of its real size. The
+ * reconciliation check makes the next such omission loud rather than silent:
+ * Google's own total is the independent witness, and a mismatch means a
+ * usageMetadata field membrane does not read is carrying tokens.
+ */
+function geminiUsageToProviderUsage(
+  usageMetadata: GeminiResponse['usageMetadata']
+): ProviderResponse['usage'] {
+  const promptTokens = usageMetadata?.promptTokenCount ?? 0;
+  const candidatesTokens = usageMetadata?.candidatesTokenCount ?? 0;
+  const thoughtsTokens = usageMetadata?.thoughtsTokenCount;
+  const totalTokens = usageMetadata?.totalTokenCount;
+
+  if (usageMetadata && totalTokens != null) {
+    const accountedTokens = promptTokens + candidatesTokens + (thoughtsTokens ?? 0);
+    if (accountedTokens !== totalTokens) {
+      console.warn(
+        `[membrane:gemini] usageMetadata does not reconcile: promptTokenCount(${promptTokens})`
+        + ` + candidatesTokenCount(${candidatesTokens}) + thoughtsTokenCount(${thoughtsTokens ?? 0})`
+        + ` = ${accountedTokens}, but totalTokenCount = ${totalTokens}.`
+        + ' Some billed tokens are in a usageMetadata field membrane does not read.'
+      );
+    }
+  }
+
+  return {
+    inputTokens: promptTokens,
+    outputTokens: candidatesTokens + (thoughtsTokens ?? 0),
+    ...(thoughtsTokens != null ? { thinkingTokens: thoughtsTokens } : {}),
+    cacheReadTokens: usageMetadata?.cachedContentTokenCount
+      ? usageMetadata.cachedContentTokenCount
+      : undefined,
+  };
+}
+
 // ============================================================================
 // Adapter Configuration
 // ============================================================================
@@ -103,6 +150,18 @@ export interface GeminiAdapterConfig {
 
 export class GeminiAdapter implements ProviderAdapter {
   readonly name = 'gemini';
+
+  /**
+   * NOT ESTABLISHED. Google documents `cachedContentTokenCount` but the probes
+   * available on 2026-08-25 could not produce a cache hit to measure against:
+   * three identical 10,893-token calls to gemini-3.5-flash-lite never reported
+   * the field (implicit caching did not trigger), and explicit `cachedContents`
+   * is refused on the free tier (429,
+   * TotalCachedContentStorageTokensPerModelFreeTier limit=0). Declared honestly
+   * rather than guessed — membrane passes the counts through and warns once if
+   * a cache read ever arrives.
+   */
+  readonly usageCacheConvention = 'unknown' as const;
   private apiKey: string;
   private baseURL: string;
   private defaultMaxTokens: number;
@@ -188,11 +247,65 @@ export class GeminiAdapter implements ProviderAdapter {
       const decoder = new TextDecoder();
       let accumulated = '';
       let finishReason = 'STOP';
+      let sawTerminalEvent = false;
       let toolCalls: { name: string; args: Record<string, unknown> }[] = [];
       let images: { data: string; mimeType: string }[] = [];
       let lastUsage: GeminiResponse['usageMetadata'] | undefined;
+      // The resolved model Google actually served, echoed on stream frames.
+      // Reporting the requested id instead hides alias/auto-upgrade routing.
+      let lastModelVersion: string | undefined;
       let buffer = '';
 
+      // One frame handler for both the streaming lines and the trailing
+      // buffer — the two used to carry byte-identical copies of this logic,
+      // so any fix (error frames, terminal observation) had to be made twice.
+      const processDataLine = (dataLine: string): void => {
+        let parsed: GeminiResponse;
+        try {
+          parsed = JSON.parse(dataLine) as GeminiResponse;
+        } catch {
+          return; // Ignore parse errors in stream chunks
+        }
+
+        throwOnStreamErrorFrame(parsed, 'Gemini', geminiRequest);
+
+        const candidate = parsed.candidates?.[0];
+
+        if (candidate?.content?.parts) {
+          for (const part of candidate.content.parts) {
+            if (part.text) {
+              accumulated += part.text;
+              callbacks.onChunk(part.text);
+            }
+            if (part.inlineData) {
+              images.push({
+                data: part.inlineData.data,
+                mimeType: part.inlineData.mimeType,
+              });
+            }
+            if (part.functionCall) {
+              toolCalls.push({
+                name: part.functionCall.name,
+                args: part.functionCall.args,
+              });
+            }
+          }
+        }
+
+        if (candidate?.finishReason) {
+          finishReason = candidate.finishReason;
+          sawTerminalEvent = true;
+        }
+
+        if (parsed.usageMetadata) {
+          lastUsage = parsed.usageMetadata;
+        }
+
+        if (parsed.modelVersion) {
+          lastModelVersion = parsed.modelVersion;
+        }
+      };
+
       while (true) {
         const { done, value } = await reader.read();
         if (done) break;
@@ -206,42 +319,7 @@ export class GeminiAdapter implements ProviderAdapter {
           if (!line.startsWith('data: ')) continue;
           const data = line.slice(6).trim();
           if (!data || data === '[DONE]') continue;
-
-          try {
-            const parsed = JSON.parse(data) as GeminiResponse;
-            const candidate = parsed.candidates?.[0];
-
-            if (candidate?.content?.parts) {
-              for (const part of candidate.content.parts) {
-                if (part.text) {
-                  accumulated += part.text;
-                  callbacks.onChunk(part.text);
-                }
-                if (part.inlineData) {
-                  images.push({
-                    data: part.inlineData.data,
-                    mimeType: part.inlineData.mimeType,
-                  });
-                }
-                if (part.functionCall) {
-                  toolCalls.push({
-                    name: part.functionCall.name,
-                    args: part.functionCall.args,
-                  });
-                }
-              }
-            }
-
-            if (candidate?.finishReason) {
-              finishReason = candidate.finishReason;
-            }
-
-            if (parsed.usageMetadata) {
-              lastUsage = parsed.usageMetadata;
-            }
-          } catch {
-            // Ignore parse errors in stream chunks
-          }
+          processDataLine(data);
         }
       }
 
@@ -250,56 +328,18 @@ export class GeminiAdapter implements ProviderAdapter {
         const remaining = buffer.trim();
         const dataLine = remaining.startsWith('data: ') ? remaining.slice(6).trim() : remaining;
         if (dataLine && dataLine !== '[DONE]') {
-          try {
-            const parsed = JSON.parse(dataLine) as GeminiResponse;
-            const candidate = parsed.candidates?.[0];
-
-            if (candidate?.content?.parts) {
-              for (const part of candidate.content.parts) {
-                if (part.text) {
-                  accumulated += part.text;
-                  callbacks.onChunk(part.text);
-                }
-                if (part.inlineData) {
-                  images.push({
-                    data: part.inlineData.data,
-                    mimeType: part.inlineData.mimeType,
-                  });
-                }
-                if (part.functionCall) {
-                  toolCalls.push({
-                    name: part.functionCall.name,
-                    args: part.functionCall.args,
-                  });
-                }
-              }
-            }
-
-            if (candidate?.finishReason) {
-              finishReason = candidate.finishReason;
-            }
-
-            if (parsed.usageMetadata) {
-              lastUsage = parsed.usageMetadata;
-            }
-          } catch {
-            // Final buffer wasn't valid JSON — nothing to do
-          }
+          processDataLine(dataLine);
         }
       }
 
+      assertTerminalEventObserved(sawTerminalEvent, 'Gemini', geminiRequest);
+
       return {
         content: this.buildContentBlocks(accumulated, toolCalls, images),
         stopReason: this.mapFinishReason(finishReason),
         stopSequence: undefined,
-        usage: {
-          inputTokens: lastUsage?.promptTokenCount ?? 0,
-          outputTokens: lastUsage?.candidatesTokenCount ?? 0,
-          cacheReadTokens: lastUsage?.cachedContentTokenCount
-            ? lastUsage.cachedContentTokenCount
-            : undefined,
-        },
-        model: request.model,
+        usage: geminiUsageToProviderUsage(lastUsage),
+        model: lastModelVersion ?? request.model,
         rawRequest: geminiRequest,
         raw: { finishReason, usage: lastUsage },
       };
@@ -563,13 +603,7 @@ export class GeminiAdapter implements ProviderAdapter {
       content: this.buildContentBlocks(text, toolCalls, images),
       stopReason: this.mapFinishReason(candidate?.finishReason),
       stopSequence: undefined,
-      usage: {
-        inputTokens: response.usageMetadata?.promptTokenCount ?? 0,
-        outputTokens: response.usageMetadata?.candidatesTokenCount ?? 0,
-        cacheReadTokens: response.usageMetadata?.cachedContentTokenCount
-          ? response.usageMetadata.cachedContentTokenCount
-          : undefined,
-      },
+      usage: geminiUsageToProviderUsage(response.usageMetadata),
       model: response.modelVersion ?? requestedModel,
       rawRequest,
       raw: response,
@@ -630,6 +664,10 @@ export class GeminiAdapter implements ProviderAdapter {
   // --------------------------------------------------------------------------
 
   private handleError(error: unknown, rawRequest?: unknown): MembraneError {
+    // A deadline abort is a timeout and stays one. Collapsing it into a bare
+    // abortError() here is what erased the identity before Membrane's
+    // caller-signal > timeout > error ladder could read it.
+    if (isDeadlineAbort(error)) return deadlineTimeoutError(error, rawRequest);
     if (error instanceof MembraneError) return error;
 
     if (error instanceof Error) {

package/src/providers/mock.ts

@@ -52,6 +52,9 @@ const DEFAULT_CONFIG: Required<Omit<MockAdapterConfig, 'responseGenerator'>> = {
 export class MockAdapter implements ProviderAdapter {
   readonly name = 'mock';
 
+  /** Test double; it reports no cache tokens, so the convention never bites. */
+  readonly usageCacheConvention = 'cache-excluded' as const;
+
   private config: Required<Omit<MockAdapterConfig, 'responseGenerator'>> & Pick<MockAdapterConfig, 'responseGenerator'>;
   private responseQueue: string[];
   private requestLog: Array<{ timestamp: number; request: ProviderRequest }> = [];