@animalabs/membrane 0.5.80 → 0.5.82

package/src/providers/openai.ts

@@ -29,7 +29,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
@@ -188,6 +188,14 @@ function noStopSupport(model: string): boolean {
 
 export class OpenAIAdapter implements ProviderAdapter {
   readonly name = 'openai';
+
+  /**
+   * Verified live 2026-08-25 (gpt-4o-mini, 1,732-token prompt): prompt_tokens
+   * stayed at 1732 across a cache hit reporting
+   * prompt_tokens_details.cached_tokens 1664 — the cached span is a SUBSET of
+   * prompt_tokens, not an addition to it.
+   */
+  readonly usageCacheConvention = 'cache-inclusive' as const;
   private apiKey: string;
   private baseURL: string;
   private organization?: string;
@@ -263,61 +271,98 @@ export class OpenAIAdapter implements ProviderAdapter {
       const sseParser = new SSELineParser();
       let accumulated = '';
       let finishReason = 'stop';
+      let sawTerminalEvent = false;
       let toolCalls: OpenAIToolCall[] = [];
       let streamUsage: OpenAIResponse['usage'] | undefined;
+      // The model the provider actually served, echoed on every SSE
+      // chunk. Reporting the requested id instead hides alias
+      // resolution (and, on OpenRouter, which provider it routed to).
+      let servedModel: string | 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, 'OpenAI', 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);
+          }
 
-            // 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;
-            }
+          if (parsed.choices?.[0]?.finish_reason) {
+            finishReason = parsed.choices[0].finish_reason;
+            sawTerminalEvent = true;
+          }
 
-            // Capture usage data (comes in final chunk with stream_options.include_usage)
-            if (parsed.usage) {
-              streamUsage = parsed.usage;
-            }
-          } catch {
-            // Ignore parse errors in stream
+          // Capture usage data (comes in final chunk with stream_options.include_usage)
+          if (parsed.usage) {
+            streamUsage = parsed.usage;
           }
+
+          if (parsed.model) {
+            servedModel = parsed.model;
+          }
+        } 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, 'OpenAI', openAIRequest);
+
       // Build response with accumulated data
       const message: OpenAIMessage = {
         role: 'assistant',
@@ -328,7 +373,7 @@ export class OpenAIAdapter implements ProviderAdapter {
         message.tool_calls = toolCalls;
       }
 
-      return this.parseStreamedResponse(message, finishReason, request.model, streamUsage, openAIRequest);
+      return this.parseStreamedResponse(message, finishReason, servedModel ?? request.model, streamUsage, openAIRequest);
 
     } catch (error) {
       throw this.handleError(error, openAIRequest);
@@ -650,6 +695,14 @@ export class OpenAIAdapter 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;
 

package/src/providers/openrouter.ts

@@ -12,6 +12,7 @@ import type {
   StreamCallbacks,
   ContentBlock,
   ToolDefinition,
+  UsageCacheConvention,
 } from '../types/index.js';
 import {
   MembraneError,
@@ -22,7 +23,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
@@ -144,8 +145,33 @@ export interface OpenRouterAdapterConfig {
 // OpenRouter Adapter
 // ============================================================================
 
+/**
+ * Which convention the tokens OpenRouter just handed back are in. OpenRouter
+ * passes the routed provider's usage payload through, so an Anthropic-routed
+ * call reports `cache_read_input_tokens` (disjoint from prompt_tokens) while an
+ * OpenAI-routed one reports `prompt_tokens_details.cached_tokens` (a subset of
+ * it). The field that carried the number therefore identifies the convention.
+ */
+function resolveRoutedCacheConvention(
+  anthropicShapedCacheRead: number | undefined,
+  resolvedCacheRead: number | undefined,
+): UsageCacheConvention | undefined {
+  if (resolvedCacheRead == null) return undefined;
+  return anthropicShapedCacheRead != null ? 'cache-excluded' : 'cache-inclusive';
+}
+
 export class OpenRouterAdapter implements ProviderAdapter {
   readonly name = 'openrouter';
+
+  /**
+   * OpenRouter fronts BOTH conventions: it passes through Anthropic's
+   * `cache_read_input_tokens` (cache-excluded) or OpenAI's
+   * `prompt_tokens_details.cached_tokens` (cache-inclusive) depending on which
+   * provider it routed to. The convention is therefore a per-response fact —
+   * each parse sets `usage.cacheConvention` from the field it actually read,
+   * and this adapter-level value is only the no-cache-tokens fallback.
+   */
+  readonly usageCacheConvention = 'unknown' as const;
   private apiKey: string;
   private baseURL: string;
   private httpReferer: string;
@@ -218,80 +244,102 @@ export class OpenRouterAdapter implements ProviderAdapter {
       const sseParser = new SSELineParser();
       let accumulated = '';
       let finishReason = 'stop';
+      let sawTerminalEvent = false;
       let toolCalls: OpenRouterToolCall[] = [];
       let streamUsage: OpenRouterResponse['usage'] | undefined;
+      // The model the provider actually served, echoed on every SSE
+      // chunk. Reporting the requested id instead hides alias
+      // resolution (and, on OpenRouter, which provider it routed to).
+      let servedModel: string | 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);
-
-        for (const data of dataLines) {
-          if (data === '[DONE]') continue;
-
-          // 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 {
-            continue; // Ignore parse errors (partial/keep-alive lines)
-          }
+        // 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)
+        }
 
-          // OpenRouter delivers mid-stream failures (e.g. upstream 429s) as an
-          // SSE data line with an `error` payload. Silently ignoring it would
-          // yield a fake-successful empty completion — surface it instead so
-          // retry logic can handle it.
-          if (typeof parsed === 'object' && parsed !== null && parsed.error) {
-            const err = parsed.error as { code?: number | string; message?: string };
-            throw new Error(
-              `OpenRouter stream error${err.code !== undefined ? ` (${err.code})` : ''}: ${err.message ?? JSON.stringify(err)}`
-            );
-          }
+        // OpenRouter delivers mid-stream failures (e.g. upstream 429s) as an
+        // SSE data line with an `error` payload. Silently ignoring it would
+        // yield a fake-successful empty completion — surface it instead so
+        // retry logic can handle it. Shared with every other SSE adapter.
+        throwOnStreamErrorFrame(parsed, 'OpenRouter', openRouterRequest);
 
-          try {
-            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);
+          }
 
-            // 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;
-            }
+          if (parsed.choices?.[0]?.finish_reason) {
+            finishReason = parsed.choices[0].finish_reason;
+            sawTerminalEvent = true;
+          }
 
-            // Capture usage data (comes in final chunk when stream_options.include_usage is set)
-            if (parsed.usage) {
-              streamUsage = parsed.usage;
-            }
-          } catch (e) {
-            // Ignore parse errors
+          // Capture usage data (comes in final chunk when stream_options.include_usage is set)
+          if (parsed.usage) {
+            streamUsage = parsed.usage;
+          }
+
+          if (parsed.model) {
+            servedModel = parsed.model;
           }
+        } catch (e) {
+          // Ignore parse errors
+        }
+      };
+
+      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, 'OpenRouter', openRouterRequest);
+
       // Build response with accumulated data
       const message: OpenRouterMessage = {
         role: 'assistant',
@@ -302,7 +350,7 @@ export class OpenRouterAdapter implements ProviderAdapter {
         message.tool_calls = toolCalls;
       }
 
-      return this.parseStreamedResponse(message, finishReason, request.model, streamUsage, openRouterRequest);
+      return this.parseStreamedResponse(message, finishReason, servedModel ?? request.model, streamUsage, openRouterRequest);
 
     } catch (error) {
       throw this.handleError(error, openRouterRequest);
@@ -602,8 +650,10 @@ export class OpenRouterAdapter implements ProviderAdapter {
     // Anthropic: cache_creation_input_tokens, cache_read_input_tokens
     // OpenAI: prompt_tokens_details.cached_tokens
     const cacheCreationTokens = response.usage?.cache_creation_input_tokens;
-    const cacheReadTokens = response.usage?.cache_read_input_tokens
+    const anthropicShapedCacheRead = response.usage?.cache_read_input_tokens;
+    const cacheReadTokens = anthropicShapedCacheRead
       ?? response.usage?.prompt_tokens_details?.cached_tokens;
+    const cacheConvention = resolveRoutedCacheConvention(anthropicShapedCacheRead, cacheReadTokens);
 
     return {
       content: this.messageToContent(message),
@@ -614,6 +664,7 @@ export class OpenRouterAdapter implements ProviderAdapter {
         outputTokens: response.usage?.completion_tokens ?? 0,
         cacheCreationTokens: cacheCreationTokens ?? undefined,
         cacheReadTokens: cacheReadTokens ?? undefined,
+        cacheConvention,
       },
       model: response.model ?? requestedModel,
       rawRequest,
@@ -630,8 +681,10 @@ export class OpenRouterAdapter implements ProviderAdapter {
   ): ProviderResponse {
     // Extract cache tokens if available from stream usage
     const cacheCreationTokens = streamUsage?.cache_creation_input_tokens;
-    const cacheReadTokens = streamUsage?.cache_read_input_tokens
+    const anthropicShapedCacheRead = streamUsage?.cache_read_input_tokens;
+    const cacheReadTokens = anthropicShapedCacheRead
       ?? streamUsage?.prompt_tokens_details?.cached_tokens;
+    const cacheConvention = resolveRoutedCacheConvention(anthropicShapedCacheRead, cacheReadTokens);
 
     return {
       content: this.messageToContent(message),
@@ -642,6 +695,7 @@ export class OpenRouterAdapter implements ProviderAdapter {
         outputTokens: streamUsage?.completion_tokens ?? 0,
         cacheCreationTokens: cacheCreationTokens ?? undefined,
         cacheReadTokens: cacheReadTokens ?? undefined,
+        cacheConvention,
       },
       model: requestedModel,
       rawRequest,
@@ -696,6 +750,14 @@ export class OpenRouterAdapter 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;