@animalabs/membrane 0.5.80 → 0.5.81

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;
 

package/src/providers/openai-completions.ts

@@ -27,7 +27,7 @@ import {
   abortError,
   networkError,
 } from '../types/index.js';
-import { createCombinedSignal, SSELineParser } from './utils.js';
+import { createCombinedSignal, SSELineParser, isDeadlineAbort, deadlineTimeoutError, throwOnStreamErrorFrame, assertTerminalEventObserved } from './utils.js';
 
 // ============================================================================
 // Types
@@ -44,6 +44,7 @@ interface CompletionsRequest {
   repetition_penalty?: number;
   stop?: string[];
   stream?: boolean;
+  stream_options?: { include_usage?: boolean };
 }
 
 interface CompletionsResponse {
@@ -118,6 +119,12 @@ export interface OpenAICompletionsAdapterConfig {
 
 export class OpenAICompletionsAdapter implements ProviderAdapter {
   readonly name: string;
+
+  /**
+   * NOT ESTABLISHED: legacy /v1/completions against arbitrary vendors. Moot
+   * today — the adapter never populates `cacheReadTokens`.
+   */
+  readonly usageCacheConvention = 'unknown' as const;
   private baseURL: string;
   private apiKey: string;
   private defaultMaxTokens: number;
@@ -169,6 +176,9 @@ export class OpenAICompletionsAdapter implements ProviderAdapter {
   ): Promise<ProviderResponse> {
     const completionsRequest = this.buildRequest(request);
     completionsRequest.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.
+    completionsRequest.stream_options = { include_usage: true };
     options?.onRequest?.(completionsRequest);
 
     const { signal: combinedSignal, cleanup } = createCombinedSignal(options?.signal, options?.timeoutMs);
@@ -194,6 +204,8 @@ export class OpenAICompletionsAdapter implements ProviderAdapter {
       const sseParser = new SSELineParser();
       let accumulated = '';
       let finishReason = 'stop';
+      let sawTerminalEvent = false;
+      let streamUsage: CompletionsResponse['usage'] | undefined;
 
       // Post-facto truncation of the adapter's own eotToken.
       // The adapter serializes the prompt with this.eotToken and sends it as an
@@ -207,53 +219,94 @@ export class OpenAICompletionsAdapter implements ProviderAdapter {
       let emittedLen = 0;
       let eotFound = false;
 
-      streamLoop:
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
+      // One frame handler for both the streamed lines and the EOF flush — the
+      // trailing buffer carries real terminal frames, not leftovers. `eotFound`
+      // is the stop signal each caller checks; it replaces the labelled break
+      // this body used while it was inline.
+      const processDataLine = (data: string): void => {
+        if (data === '[DONE]') {
+          sawTerminalEvent = true;
+          return;
+        }
 
-        const chunk = decoder.decode(value, { stream: true });
-        const dataLines = sseParser.feed(chunk);
-
-        for (const data of dataLines) {
-          if (data === '[DONE]') continue;
-
-          try {
-            const parsed = JSON.parse(data);
-            const text = parsed.choices?.[0]?.text;
-
-            if (text) {
-              accumulated += text;
-              if (eot) {
-                const idx = accumulated.indexOf(eot);
-                if (idx !== -1) {
-                  // Truncate at the token, flush the un-emitted prefix, stop
-                  accumulated = accumulated.slice(0, idx);
-                  if (accumulated.length > emittedLen) {
-                    callbacks.onChunk(accumulated.slice(emittedLen));
-                  }
-                  emittedLen = accumulated.length;
-                  eotFound = true;
-                  finishReason = 'stop';
-                  break streamLoop;
-                }
-                // Emit all but a held-back tail that could be a partial token
-                const safeLen = Math.max(emittedLen, accumulated.length - (eot.length - 1));
-                if (safeLen > emittedLen) {
-                  callbacks.onChunk(accumulated.slice(emittedLen, safeLen));
-                  emittedLen = safeLen;
+        // 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)
+        }
+
+        throwOnStreamErrorFrame(parsed, this.name, completionsRequest);
+
+        try {
+          const text = parsed.choices?.[0]?.text;
+
+          if (text) {
+            accumulated += text;
+            if (eot) {
+              const idx = accumulated.indexOf(eot);
+              if (idx !== -1) {
+                // Truncate at the token, flush the un-emitted prefix, stop
+                accumulated = accumulated.slice(0, idx);
+                if (accumulated.length > emittedLen) {
+                  callbacks.onChunk(accumulated.slice(emittedLen));
                 }
-              } else {
-                callbacks.onChunk(text);
+                emittedLen = accumulated.length;
+                eotFound = true;
+                // The adapter's own end-of-turn token IS a terminal
+                // observation: the turn ended where this layer said it ends.
+                sawTerminalEvent = true;
+                finishReason = 'stop';
+                return;
+              }
+              // Emit all but a held-back tail that could be a partial token
+              const safeLen = Math.max(emittedLen, accumulated.length - (eot.length - 1));
+              if (safeLen > emittedLen) {
+                callbacks.onChunk(accumulated.slice(emittedLen, safeLen));
+                emittedLen = safeLen;
               }
+            } else {
+              callbacks.onChunk(text);
             }
+          }
 
-            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);
+          if (eotFound) break;
+        }
+        if (eotFound) break;
+      }
+
+      // 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. A stream already ended by the eotToken
+      // has nothing left to read.
+      if (!eotFound) {
+        for (const data of sseParser.flush()) {
+          processDataLine(data);
+          if (eotFound) break;
         }
       }
 
@@ -265,7 +318,9 @@ export class OpenAICompletionsAdapter implements ProviderAdapter {
         try { await reader.cancel(); } catch { /* stream already closed */ }
       }
 
-      return this.buildStreamedResponse(accumulated, finishReason, request.model, completionsRequest);
+      assertTerminalEventObserved(sawTerminalEvent, this.name, completionsRequest);
+
+      return this.buildStreamedResponse(accumulated, finishReason, request.model, streamUsage, completionsRequest);
 
     } catch (error) {
       throw this.handleError(error, completionsRequest);
@@ -495,6 +550,7 @@ export class OpenAICompletionsAdapter implements ProviderAdapter {
     accumulated: string,
     finishReason: string,
     requestedModel: string,
+    streamUsage?: CompletionsResponse['usage'],
     rawRequest?: unknown
   ): ProviderResponse {
     return {
@@ -502,12 +558,14 @@ export class OpenAICompletionsAdapter 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: { text: accumulated, finish_reason: finishReason },
+      raw: { text: accumulated, finish_reason: finishReason, usage: streamUsage },
     };
   }
 
@@ -532,6 +590,14 @@ export class OpenAICompletionsAdapter 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/openai-responses-api.ts

@@ -26,7 +26,7 @@ import {
   rateLimitError,
   serverError,
 } from '../types/index.js';
-import { createCombinedSignal, SSELineParser, safeParseJson } from './utils.js';
+import { createCombinedSignal, SSELineParser, safeParseJson, isDeadlineAbort, deadlineTimeoutError, throwOnStreamErrorFrame } from './utils.js';
 
 // ============================================================================
 // Provider-native Responses API types
@@ -133,6 +133,16 @@ export interface OpenAIResponsesAPIAdapterConfig {
 export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
   readonly name = 'openai-responses-api';
 
+  /**
+   * Reads `usage.input_tokens_details.cached_tokens` from OpenAI's account-wide
+   * automatic prompt caching — the same mechanism verified live on
+   * /v1/chat/completions on 2026-08-25 (prompt_tokens constant at 1732 across a
+   * hit reporting cached_tokens 1664, so cached is a subset). A same-day probe
+   * of /v1/responses did not itself produce a cache hit to confirm on that
+   * endpoint.
+   */
+  readonly usageCacheConvention = 'cache-inclusive' as const;
+
   private readonly apiKey: string;
   private readonly baseURL: string;
   private readonly organization?: string;
@@ -175,7 +185,7 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
 
       await this.assertSuccessfulHTTPResponse(response);
       const data = (await response.json()) as OpenAIResponsesAPIResponse;
-      this.assertSuccessfulAPIResponse(data);
+      this.assertSuccessfulAPIResponse(data, responsesRequest, 'response error');
       return this.parseResponse(data, request.model, responsesRequest);
     } catch (error) {
       throw this.handleError(error, responsesRequest);
@@ -242,15 +252,23 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
         ) {
           terminalResponse = event.response;
         } else if (event.type === 'response.failed') {
+          // This adapter dispatches on event.type rather than running the
+          // shared SSE line loop, but its error frames are the same class of
+          // payload: a structured code the caller's retry policy needs. Route
+          // both throw sites through the one classifier so the token lists
+          // have a single source of truth. A response.failed carrying no error
+          // object at all falls through to the loud generic below.
           const failed = event.response as OpenAIResponsesAPIResponse | undefined;
-          throw new Error(
-            `OpenAI Responses API error: ${failed?.error?.code ?? 'response_failed'} ` +
-              `${failed?.error?.message ?? 'Response failed'}`
-          );
+          throwOnStreamErrorFrame(failed, 'OpenAI Responses API', responsesRequest);
+          throw new Error('OpenAI Responses API stream error (response_failed): Response failed');
         } else if (event.type === 'error') {
-          throw new Error(
-            `OpenAI Responses API error: ${event.code ?? 'stream_error'} ` +
-              `${event.message ?? 'Streaming request failed'}`
+          // The event's own `type` is the SSE event name ('error'), not a
+          // provider classification, so only code and message are handed over.
+          // The payload object is always present, so this always throws.
+          throwOnStreamErrorFrame(
+            { error: { code: event.code, message: event.message ?? 'Streaming request failed' } },
+            'OpenAI Responses API',
+            responsesRequest
           );
         }
       };
@@ -280,7 +298,7 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
         );
       }
 
-      this.assertSuccessfulAPIResponse(terminalResponse);
+      this.assertSuccessfulAPIResponse(terminalResponse, responsesRequest);
 
       const parsed = this.parseResponse(terminalResponse, request.model, responsesRequest);
       parsed.content.forEach((block, index) => callbacks.onContentBlock?.(index, block));
@@ -593,15 +611,27 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
     throw new Error(`OpenAI Responses API error: ${response.status} ${errorText}`);
   }
 
-  private assertSuccessfulAPIResponse(response: OpenAIResponsesAPIResponse): void {
+  /**
+   * A terminal response can carry a structured `error` object on a 200, from
+   * the stream's terminal frame or from a non-streaming body. That payload
+   * never reaches an HTTP-status boundary classifier — the status was 200 —
+   * so it is classified here, by the same helper and the same token lists as
+   * every other provider error payload.
+   */
+  private assertSuccessfulAPIResponse(
+    response: OpenAIResponsesAPIResponse,
+    rawRequest?: unknown,
+    errorNoun?: string
+  ): void {
     if (!response.error) return;
-    throw new Error(
-      `OpenAI Responses API error: ${response.error.code ?? 'api_error'} ` +
-        `${response.error.message ?? 'Unknown error'}`
-    );
+    throwOnStreamErrorFrame(response, 'OpenAI Responses API', rawRequest, errorNoun);
   }
 
   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) {
       const message = error.message;

package/src/providers/openai-responses.ts

@@ -39,7 +39,7 @@ import {
   abortError,
   networkError,
 } from '../types/index.js';
-import { createCombinedSignal } from './utils.js';
+import { createCombinedSignal, isDeadlineAbort, deadlineTimeoutError } from './utils.js';
 
 // ============================================================================
 // Images API Types
@@ -123,6 +123,9 @@ export interface OpenAIResponsesAdapterConfig {
 
 export class OpenAIResponsesAdapter implements ProviderAdapter {
   readonly name = 'openai-responses';
+
+  /** Images API adapter: it reports no token usage at all. */
+  readonly usageCacheConvention = 'cache-excluded' as const;
   private apiKey: string;
   private baseURL: string;
   private organization?: string;
@@ -423,6 +426,10 @@ export class OpenAIResponsesAdapter 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) {