@animalabs/membrane 0.5.83 → 0.5.85

package/src/providers/anthropic.ts

@@ -24,6 +24,7 @@ import {
 } from '../types/index.js';
 import { flattenRootSchemaUnion } from './anthropic-tool-schema.js';
 import { assertTerminalEventObserved } from './utils.js';
+import { fetchWithCredentials, validateCredential, type CredentialContext, type CredentialResolver } from './credentials.js';
 import { CacheKeepalive, type CacheKeepaliveConfig } from '../cache-keepalive.js';
 
 // ============================================================================
@@ -151,7 +152,12 @@ export interface AnthropicAdapterConfig {
    * is allowed to resolve environment auth). If explicitly provided, API-key
    * auth is disabled so requests do not send both auth schemes.
    */
-  authToken?: string | null;
+  authToken?: string | null | ((context: CredentialContext) => string | Promise<string>);
+
+  /** Resolve a bearer token and associated headers per HTTP attempt. Takes
+   * precedence over authToken/apiKey; refreshed once after HTTP 401. Applies
+   * to complete, stream, and cache-keepalive requests. */
+  credentials?: CredentialResolver;
   
   /** Base URL override */
   baseURL?: string;
@@ -199,6 +205,7 @@ export class AnthropicAdapter implements ProviderAdapter {
    */
   readonly usageCacheConvention = 'cache-excluded' as const;
   private client: Anthropic;
+  private readonly credentials?: CredentialResolver;
   private defaultMaxTokens: number;
   /** Any anthropic-beta value from defaultHeaders (e.g. the oauth beta for
    *  subscription tokens). Per-request headers REPLACE same-key defaults in
@@ -218,8 +225,19 @@ export class AnthropicAdapter implements ProviderAdapter {
     this.defaultBeta = extractBetaHeader(config.defaultHeaders);
     this.dynamicHeaders = config.dynamicHeaders;
 
-    if (config.authToken !== undefined) {
-      clientOptions.authToken = config.authToken;
+    const authToken = config.authToken;
+    const credentials: CredentialResolver | undefined = config.credentials ?? (typeof authToken === 'function'
+      ? async (context: CredentialContext) => ({ token: await authToken(context) })
+      : undefined);
+    this.credentials = credentials;
+    if (credentials) {
+      // Satisfy SDK auth validation without freezing a real credential. The
+      // fetch seam replaces this placeholder before every network attempt,
+      // including the SDK's stream and cache-keepalive transports.
+      clientOptions.authToken = 'membrane-resolved-at-request-time';
+      clientOptions.apiKey = null;
+    } else if (authToken !== undefined) {
+      clientOptions.authToken = authToken as string | null;
       clientOptions.apiKey = null;
     } else {
       clientOptions.apiKey = config.apiKey;
@@ -234,14 +252,62 @@ export class AnthropicAdapter implements ProviderAdapter {
           // Replay path. Deliberately bypasses buildRequest(): the payload is
           // the already-built wire request from a real call, and rebuilding it
           // risks a byte diff that silently converts a 0.1x read into a 2x write.
-          async (wire, headers) => await this.client.messages.create(
-            wire as unknown as Anthropic.MessageCreateParamsNonStreaming,
-            headers ? { headers } : undefined,
+          async (wire, headers) => this.createMessage(
+            wire as unknown as Anthropic.MessageCreateParamsNonStreaming, headers,
           ),
           config.cacheKeepalive ?? {},
         );
   }
 
+  /** One SDK operation owns its failure state: concurrent calls cannot
+   * overwrite each other's auth error or cancel each other's requests. */
+  private credentialSession(signal?: AbortSignal) {
+    const credentials = this.credentials;
+    if (!credentials) return { client: this.client, signal, failure: () => undefined };
+    const abort = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+    let failure: MembraneError | undefined;
+    const client = this.client.withOptions({
+      fetch: (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.delete('x-api-key');
+        return fetchWithCredentials(input, { ...init, headers }, async context => {
+          try {
+            const credential = await credentials(context);
+            validateCredential(credential);
+            const resolvedHeaders = new Headers(credential.headers);
+            resolvedHeaders.delete('x-api-key');
+            return { ...credential, headers: Object.fromEntries(resolvedHeaders) };
+          } catch (error) {
+            if (combined.aborted) throw error;
+            failure = error instanceof MembraneError ? error : authError(
+              `Credential resolution failed: ${error instanceof Error ? error.message : String(error)}`, error,
+            );
+            // SDK 0.52 retries thrown fetch errors as connection failures.
+            // Abort this operation to bypass that loop, then restore the
+            // original error at the complete/stream/keepalive boundary.
+            abort.abort(failure);
+            throw failure;
+          }
+        });
+      },
+    });
+    return { client, signal: combined, failure: () => failure };
+  }
+
+  private async createMessage(
+    request: Anthropic.MessageCreateParamsNonStreaming,
+    headers?: Record<string, string>,
+    signal?: AbortSignal,
+  ): Promise<Anthropic.Message> {
+    const session = this.credentialSession(signal);
+    try {
+      return await session.client.messages.create(request, { headers, signal: session.signal });
+    } catch (error) {
+      throw session.failure() ?? error;
+    }
+  }
+
   supportsModel(modelId: string): boolean {
     return modelId.startsWith('claude-');
   }
@@ -260,10 +326,9 @@ export class AnthropicAdapter implements ProviderAdapter {
     );
 
     try {
-      const response = await this.client.messages.create(fullRequest, {
-        signal: options?.signal,
-        headers: this.liveHeaders(headers, 'complete'),
-      });
+      const response = await this.createMessage(
+        fullRequest, this.liveHeaders(headers, 'complete'), options?.signal,
+      );
 
       return this.parseResponse(response, fullRequest);
     } catch (error) {
@@ -331,10 +396,11 @@ export class AnthropicAdapter implements ProviderAdapter {
     };
 
     resetIdleTimer();
+    const session = this.credentialSession(idleAbort.signal);
 
     try {
-      const stream = await this.client.messages.stream(anthropicRequest, {
-        signal: idleAbort.signal,
+      const stream = await session.client.messages.stream(anthropicRequest, {
+        signal: session.signal,
         headers: this.liveHeaders(this.betaHeaders(request), 'stream'),
       });
 
@@ -572,7 +638,7 @@ export class AnthropicAdapter implements ProviderAdapter {
           rawRequest: fullRequest,
         });
       }
-      throw this.handleError(error, fullRequest);
+      throw this.handleError(session.failure() ?? error, fullRequest);
     }
   }
 

package/src/providers/credentials.ts

@@ -0,0 +1,77 @@
+import { authError } from '../types/index.js';
+
+/** Credential acquisition stays with the application; transports resolve per attempt. */
+export interface ResolvedCredential {
+  token: string;
+  /** Headers tied to this token, e.g. ChatGPT-Account-Id. Returned atomically. */
+  headers?: Record<string, string>;
+}
+
+export interface CredentialContext {
+  /** False for the first attempt; true for the single retry after HTTP 401. */
+  forceRefresh: boolean;
+  /** The request's combined cancellation/deadline signal. */
+  signal?: AbortSignal;
+}
+
+export type CredentialResolver = (
+  context: CredentialContext,
+) => ResolvedCredential | Promise<ResolvedCredential>;
+
+/** Internal shared HTTP seam: refresh only a 401, before a body is consumed.
+ * Static credentials retain their single-attempt behavior. SDK-backed callers
+ * can use this as their fetch implementation without rebuilding a client. */
+export async function fetchWithCredentials(
+  input: string | URL | Request,
+  init: RequestInit,
+  credentials: CredentialResolver | ResolvedCredential,
+): Promise<Response> {
+  const signal = init.signal ?? undefined;
+  for (const forceRefresh of [false, true]) {
+    signal?.throwIfAborted();
+    const credential = typeof credentials === 'function'
+      ? await resolveWithSignal(credentials, forceRefresh, signal)
+      : credentials;
+    signal?.throwIfAborted();
+    validateCredential(credential);
+    const headers = new Headers(init.headers);
+    for (const [key, value] of Object.entries(credential.headers ?? {})) headers.set(key, value);
+    if (typeof credentials === 'function' || !headers.has('Authorization')) {
+      headers.set('Authorization', `Bearer ${credential.token}`);
+    }
+    const response = await fetch(input, { ...init, headers });
+    if (response.status !== 401 || typeof credentials !== 'function' || forceRefresh) return response;
+    void response.body?.cancel().catch(() => {});
+  }
+  throw new Error('Unreachable credential retry state');
+}
+
+/** Bound credential acquisition by the same cancellation/deadline as HTTP. */
+async function resolveWithSignal(
+  resolver: CredentialResolver,
+  forceRefresh: boolean,
+  signal?: AbortSignal,
+) {
+  if (!signal) return resolver({ forceRefresh });
+  signal.throwIfAborted();
+  let onAbort: () => void = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return resolver({ forceRefresh, signal });
+    }), aborted]);
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
+}
+
+/** Runtime validation also protects JavaScript callers and external resolvers. */
+export function validateCredential(credential: ResolvedCredential): void {
+  if (!credential || typeof credential.token !== 'string' || credential.token.trim().length === 0) {
+    throw authError('Credential resolver must return a non-empty string token');
+  }
+}

package/src/providers/index.ts

@@ -72,3 +72,5 @@ export {
   type OpenAIResponsesInputItem,
   type OpenAIResponsesOutputItem,
 } from './openai-responses-api.js';
+
+export type { CredentialContext, CredentialResolver, ResolvedCredential } from './credentials.js';

package/src/providers/openai-responses-api.ts

@@ -9,6 +9,9 @@
  * exposes the response's ordered output array verbatim for the next turn.
  */
 
+import { normalizeResponsesInput } from './responses-input.js';
+import { fetchWithCredentials, type CredentialResolver } from './credentials.js';
+
 import type {
   ContentBlock,
   ProviderAdapter,
@@ -114,7 +117,16 @@ export interface OpenAIResponsesAPIProviderResponse extends Omit<ProviderRespons
 export interface OpenAIResponsesAPIAdapterConfig {
   /** API key (defaults to OPENAI_API_KEY). */
   apiKey?: string;
-  /** API base URL (default: https://api.openai.com/v1). */
+  /** Resolve a bearer token and associated headers for each request/401 retry.
+   * Overrides apiKey; acquiring and persisting credentials belongs to the caller. */
+  credentials?: CredentialResolver;
+  /** ChatGPT subscription transport requires credentials and always uses SSE. */
+  mode?: 'api' | 'subscription';
+  /** Request priority service in subscription mode (default: false). */
+  fastMode?: boolean;
+  /** Called once if a subscription response reports a non-priority tier. */
+  onFastModeFallback?: (serviceTier: string) => void;
+  /** API base URL (defaults to the selected mode's endpoint). */
   baseURL?: string;
   /** Optional OpenAI organization ID. */
   organization?: string;
@@ -131,7 +143,7 @@ export interface OpenAIResponsesAPIAdapterConfig {
 // ============================================================================
 
 export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
-  readonly name = 'openai-responses-api';
+  readonly name: string = 'openai-responses-api';
 
   /**
    * Reads `usage.input_tokens_details.cached_tokens` from OpenAI's account-wide
@@ -144,6 +156,12 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
   readonly usageCacheConvention = 'cache-inclusive' as const;
 
   private readonly apiKey: string;
+  private readonly credentials?: CredentialResolver;
+  private readonly subscription: boolean;
+  readonly requiresNativeResponsesInput: boolean;
+  private fastMode: boolean;
+  private readonly onFastModeFallback?: (serviceTier: string) => void;
+  private warnedFastFallback = false;
   private readonly baseURL: string;
   private readonly organization?: string;
   private readonly project?: string;
@@ -151,39 +169,51 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
   private readonly extraHeaders: Record<string, string>;
 
   constructor(config: OpenAIResponsesAPIAdapterConfig = {}) {
+    this.subscription = config.mode === 'subscription';
+    this.requiresNativeResponsesInput = !this.subscription;
+    this.credentials = config.credentials;
+    if (this.subscription && !this.credentials) {
+      throw new Error('Subscription mode requires a credential resolver');
+    }
+    this.fastMode = config.fastMode ?? false;
+    this.onFastModeFallback = config.onFastModeFallback;
     this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? '';
-    this.baseURL = (config.baseURL ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+    this.baseURL = (config.baseURL ?? (this.subscription ? 'https://chatgpt.com/backend-api/codex' : 'https://api.openai.com/v1')).replace(/\/$/, '');
     this.organization = config.organization;
     this.project = config.project;
     this.defaultMaxTokens = config.defaultMaxTokens ?? 4096;
     this.extraHeaders = config.extraHeaders ?? {};
 
-    if (!this.apiKey) {
+    if (!this.apiKey && !this.credentials) {
       throw new Error('OpenAI API key not provided');
     }
   }
 
-  supportsModel(_modelId: string): boolean {
-    return true;
+  supportsModel(modelId: string): boolean {
+    return !this.subscription || modelId.startsWith('gpt-') || modelId.includes('codex');
+  }
+
+  isFastMode(): boolean {
+    return this.fastMode;
+  }
+
+  setFastMode(enabled: boolean): void {
+    this.fastMode = enabled;
   }
 
   async complete(
     request: ProviderRequest,
     options?: ProviderRequestOptions
   ): Promise<OpenAIResponsesAPIProviderResponse> {
+    if (this.subscription) return this.stream(request, { onChunk: () => {} }, options);
     const responsesRequest = this.buildRequest(request);
     options?.onRequest?.(responsesRequest);
 
     const { signal, cleanup } = createCombinedSignal(options?.signal, options?.timeoutMs);
     try {
-      const response = await fetch(`${this.baseURL}/responses`, {
-        method: 'POST',
-        headers: this.getHeaders(),
-        body: JSON.stringify(responsesRequest),
-        signal,
-      });
-
-      await this.assertSuccessfulHTTPResponse(response);
+      const response = await this.fetchResponse(responsesRequest, signal);
+
+      await this.assertSuccessfulHTTPResponse(response, responsesRequest);
       const data = (await response.json()) as OpenAIResponsesAPIResponse;
       this.assertSuccessfulAPIResponse(data, responsesRequest, 'response error');
       return this.parseResponse(data, request.model, responsesRequest);
@@ -205,19 +235,14 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
 
     const { signal, cleanup } = createCombinedSignal(options?.signal, options?.timeoutMs);
     try {
-      const response = await fetch(`${this.baseURL}/responses`, {
-        method: 'POST',
-        headers: this.getHeaders(),
-        body: JSON.stringify(responsesRequest),
-        signal,
-      });
-
-      await this.assertSuccessfulHTTPResponse(response);
+      const response = await this.fetchResponse(responsesRequest, signal);
+
+      await this.assertSuccessfulHTTPResponse(response, responsesRequest);
       const reader = response.body?.getReader();
       if (!reader) throw new Error('OpenAI Responses API returned no response body');
 
       const decoder = new TextDecoder();
-      const parser = new SSELineParser();
+      const parser = new SSELineParser({ multiline: true });
       const events: unknown[] = [];
       const output: OpenAIResponsesOutputItem[] = [];
       let terminalResponse: OpenAIResponsesAPIResponse | undefined;
@@ -266,22 +291,27 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
           // 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' } },
+            { error: event.error ?? { code: event.code, message: event.message ?? 'Streaming request failed' } },
             'OpenAI Responses API',
             responsesRequest
           );
         }
       };
 
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        for (const data of parser.feed(decoder.decode(value, { stream: true }))) {
-          processData(data);
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          for (const data of parser.feed(decoder.decode(value, { stream: true }))) {
+            processData(data);
+          }
         }
+        for (const data of parser.feed(decoder.decode())) processData(data);
+        for (const data of parser.flush()) processData(data);
+      } finally {
+        void reader.cancel().catch(() => {});
+        reader.releaseLock();
       }
-      for (const data of parser.feed(decoder.decode())) processData(data);
-      for (const data of parser.flush()) processData(data);
 
       // A well-formed stream always ends with a terminal event
       // (response.completed / response.incomplete; response.failed and error
@@ -300,6 +330,18 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
 
       this.assertSuccessfulAPIResponse(terminalResponse, responsesRequest);
 
+      // Codex may deliver authoritative items only via output_item.done.
+      // A non-empty terminal output remains authoritative when supplied.
+      if (!terminalResponse.output?.length) {
+        terminalResponse = { ...terminalResponse, output: output.filter(Boolean) };
+      }
+      const returnedTier = terminalResponse.service_tier;
+      if (this.subscription && responsesRequest.service_tier === 'priority' &&
+          typeof returnedTier === 'string' && returnedTier && returnedTier !== 'priority' &&
+          !this.warnedFastFallback) {
+        this.warnedFastFallback = true;
+        this.onFastModeFallback?.(returnedTier);
+      }
       const parsed = this.parseResponse(terminalResponse, request.model, responsesRequest);
       parsed.content.forEach((block, index) => callbacks.onContentBlock?.(index, block));
       return parsed;
@@ -314,14 +356,21 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
   // Request construction
   // --------------------------------------------------------------------------
 
-  private getHeaders(): Record<string, string> {
-    return {
-      Authorization: `Bearer ${this.apiKey}`,
-      'Content-Type': 'application/json',
-      ...(this.organization ? { 'OpenAI-Organization': this.organization } : {}),
-      ...(this.project ? { 'OpenAI-Project': this.project } : {}),
-      ...this.extraHeaders,
-    };
+  private async fetchResponse(
+    request: OpenAIResponsesAPIRequest,
+    signal?: AbortSignal,
+  ): Promise<Response> {
+    return fetchWithCredentials(`${this.baseURL}/responses`, {
+      method: 'POST',
+      body: JSON.stringify(request),
+      signal,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.organization ? { 'OpenAI-Organization': this.organization } : {}),
+        ...(this.project ? { 'OpenAI-Project': this.project } : {}),
+        ...this.extraHeaders,
+      },
+    }, this.credentials ?? { token: this.apiKey });
   }
 
   private buildRequest(request: ProviderRequest): OpenAIResponsesAPIRequest {
@@ -366,9 +415,18 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
 
     // These invariants define the adapter's stateless native-item contract and
     // cannot be overridden through provider params.
-    responsesRequest.input = request.messages as OpenAIResponsesInputItem[];
+    responsesRequest.input = this.subscription
+      ? normalizeResponsesInput(request.messages)
+      : request.messages as OpenAIResponsesInputItem[];
     responsesRequest.store = false;
     responsesRequest.include = this.mergeEncryptedReasoningInclude(responsesRequest.include);
+    if (this.subscription) {
+      for (const key of ['temperature', 'top_p', 'top_k', 'max_output_tokens', 'max_tokens', 'max_completion_tokens']) {
+        delete responsesRequest[key];
+      }
+      if (this.fastMode) responsesRequest.service_tier = 'priority';
+      else delete responsesRequest.service_tier;
+    }
     return responsesRequest;
   }
 
@@ -605,10 +663,27 @@ export class OpenAIResponsesAPIAdapter implements ProviderAdapter {
   // Errors
   // --------------------------------------------------------------------------
 
-  private async assertSuccessfulHTTPResponse(response: Response): Promise<void> {
+  private async assertSuccessfulHTTPResponse(response: Response, rawRequest: unknown): Promise<void> {
     if (response.ok) return;
-    const errorText = await response.text();
-    throw new Error(`OpenAI Responses API error: ${response.status} ${errorText}`);
+    const detail = await response.text();
+    const message = `OpenAI Responses API error: ${response.status} ${detail}`;
+    const status = response.status;
+    if (status === 401 || status === 403) {
+      throw new MembraneError({ type: 'auth', message, retryable: false, httpStatus: status, rawError: detail, rawRequest });
+    }
+    if (status === 429) {
+      const retryAfter = response.headers.get('retry-after');
+      const seconds = retryAfter == null ? NaN : Number(retryAfter);
+      const date = retryAfter == null ? NaN : Date.parse(retryAfter);
+      const delay = Number.isFinite(seconds) ? Math.max(0, seconds * 1000)
+        : Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
+      throw rateLimitError(message, delay, detail, rawRequest);
+    }
+    if (status >= 500) throw serverError(message, status, detail, rawRequest);
+    if (status === 400 && /context_length|maximum context|token limit|too long/i.test(detail)) {
+      throw contextLengthError(message, detail, rawRequest);
+    }
+    throw new MembraneError({ type: 'invalid_request', message, retryable: false, httpStatus: status, rawError: detail, rawRequest });
   }
 
   /**