@animalabs/membrane 0.5.79 → 0.5.81

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 }> = [];

package/src/providers/openai-compatible.ts

@@ -30,7 +30,7 @@ import {
   abortError,
   networkError,
 } from '../types/index.js';
-import { safeParseJson, createCombinedSignal, SSELineParser } from './utils.js';
+import { safeParseJson, createCombinedSignal, SSELineParser, isDeadlineAbort, deadlineTimeoutError, throwOnStreamErrorFrame, assertTerminalEventObserved } from './utils.js';
 
 // ============================================================================
 // Types
@@ -129,6 +129,14 @@ export interface OpenAICompatibleAdapterConfig {
 
 export class OpenAICompatibleAdapter implements ProviderAdapter {
   readonly name: string;
+
+  /**
+   * NOT ESTABLISHED, and not establishable per-adapter: this fronts arbitrary
+   * OpenAI-shaped third-party endpoints whose caching semantics vary by vendor.
+   * Moot today — the adapter never populates `cacheReadTokens`, so the warn
+   * never fires; it becomes live the moment cache reporting is added here.
+   */
+  readonly usageCacheConvention = 'unknown' as const;
   private baseURL: string;
   private apiKey: string;
   private defaultMaxTokens: number;
@@ -174,6 +182,9 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
   ): Promise<ProviderResponse> {
     const openAIRequest = this.buildRequest(request);
     openAIRequest.stream = true;
+    // Ask for usage in the stream — without this the endpoint sends no usage
+    // frame at all and every streamed call reports 0/0 tokens.
+    openAIRequest.stream_options = { include_usage: true };
     options?.onRequest?.(openAIRequest);
 
     const { signal: combinedSignal, cleanup } = createCombinedSignal(options?.signal, options?.timeoutMs);
@@ -200,60 +211,95 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
       let accumulated = '';
       let reasoning = '';
       let finishReason = 'stop';
+      let sawTerminalEvent = false;
       let toolCalls: OpenAIToolCall[] = [];
+      let streamUsage: OpenAIResponse['usage'] | undefined;
+
+      // One frame handler for both the streamed lines and the EOF flush — the
+      // trailing buffer carries real terminal frames, not leftovers.
+      const processDataLine = (data: string): void => {
+        if (data === '[DONE]') {
+          sawTerminalEvent = true;
+          return;
+        }
 
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        const chunk = decoder.decode(value, { stream: true });
-        const dataLines = sseParser.feed(chunk);
+        // Parse first; only JSON noise is ignorable. Everything after the
+        // parse must NOT be swallowed by the catch below.
+        let parsed: Record<string, any>;
+        try {
+          parsed = JSON.parse(data);
+        } catch {
+          return; // Ignore parse errors (partial/keep-alive lines)
+        }
 
-        for (const data of dataLines) {
-          if (data === '[DONE]') continue;
+        throwOnStreamErrorFrame(parsed, this.name, openAIRequest);
 
-          try {
-            const parsed = JSON.parse(data);
-            const delta = parsed.choices?.[0]?.delta;
+        try {
+          const delta = parsed.choices?.[0]?.delta;
 
-            if (delta?.content) {
-              accumulated += delta.content;
-              callbacks.onChunk(delta.content);
-            }
+          if (delta?.content) {
+            accumulated += delta.content;
+            callbacks.onChunk(delta.content);
+          }
 
-            // Reasoning-model trace arrives on its own channel (not `content`).
-            if (typeof delta?.reasoning === 'string') {
-              reasoning += delta.reasoning;
-            }
+          // Reasoning-model trace arrives on its own channel (not `content`).
+          if (typeof delta?.reasoning === 'string') {
+            reasoning += delta.reasoning;
+          }
 
-            // Handle streaming tool calls
-            if (delta?.tool_calls) {
-              for (const tc of delta.tool_calls) {
-                const index = tc.index ?? 0;
-                if (!toolCalls[index]) {
-                  toolCalls[index] = {
-                    id: tc.id ?? '',
-                    type: 'function',
-                    function: { name: '', arguments: '' },
-                  };
-                }
-                if (tc.id) toolCalls[index].id = tc.id;
-                if (tc.function?.name) toolCalls[index].function.name = tc.function.name;
-                if (tc.function?.arguments) {
-                  toolCalls[index].function.arguments += tc.function.arguments;
-                }
+          // Handle streaming tool calls
+          if (delta?.tool_calls) {
+            for (const tc of delta.tool_calls) {
+              const index = tc.index ?? 0;
+              if (!toolCalls[index]) {
+                toolCalls[index] = {
+                  id: tc.id ?? '',
+                  type: 'function',
+                  function: { name: '', arguments: '' },
+                };
+              }
+              if (tc.id) toolCalls[index].id = tc.id;
+              if (tc.function?.name) toolCalls[index].function.name = tc.function.name;
+              if (tc.function?.arguments) {
+                toolCalls[index].function.arguments += tc.function.arguments;
               }
             }
+          }
 
-            if (parsed.choices?.[0]?.finish_reason) {
-              finishReason = parsed.choices[0].finish_reason;
-            }
-          } catch {
-            // Ignore parse errors in stream
+          if (parsed.choices?.[0]?.finish_reason) {
+            finishReason = parsed.choices[0].finish_reason;
+            sawTerminalEvent = true;
           }
+
+          // Usage rides the final chunk when stream_options.include_usage is set
+          if (parsed.usage) {
+            streamUsage = parsed.usage;
+          }
+        } catch {
+          // Ignore parse errors in stream
+        }
+      };
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        for (const data of sseParser.feed(chunk)) {
+          processDataLine(data);
         }
       }
 
+      // A final `data:` line that arrived without its trailing newline is still
+      // buffered here. Servers and proxies do close right after writing the
+      // last event, so dropping it would report a finished turn as a dropped
+      // connection at the guard below.
+      for (const data of sseParser.flush()) {
+        processDataLine(data);
+      }
+
+      assertTerminalEventObserved(sawTerminalEvent, this.name, openAIRequest);
+
       // Build response with accumulated data
       const message: OpenAIMessage = {
         role: 'assistant',
@@ -266,7 +312,7 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
         message.tool_calls = toolCalls;
       }
 
-      return this.parseStreamedResponse(message, finishReason, request.model, openAIRequest);
+      return this.parseStreamedResponse(message, finishReason, request.model, streamUsage, openAIRequest);
 
     } catch (error) {
       throw this.handleError(error, openAIRequest);
@@ -522,6 +568,7 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
     message: OpenAIMessage,
     finishReason: string,
     requestedModel: string,
+    streamUsage?: OpenAIResponse['usage'],
     rawRequest?: unknown
   ): ProviderResponse {
     return {
@@ -529,12 +576,14 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
       stopReason: this.mapFinishReason(finishReason),
       stopSequence: undefined,
       usage: {
-        inputTokens: 0, // Not available in streaming
-        outputTokens: 0,
+        // Zeros only as the genuinely-absent fallback: an endpoint that
+        // ignores stream_options sends no usage frame.
+        inputTokens: streamUsage?.prompt_tokens ?? 0,
+        outputTokens: streamUsage?.completion_tokens ?? 0,
       },
       model: requestedModel,
       rawRequest,
-      raw: { message, finish_reason: finishReason },
+      raw: { message, finish_reason: finishReason, usage: streamUsage },
     };
   }
 
@@ -585,6 +634,14 @@ export class OpenAICompatibleAdapter 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 Error) {
       const message = error.message;