@animalabs/membrane 0.5.84 → 0.5.86

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

@@ -9,6 +9,10 @@
  * exposes the response's ordered output array verbatim for the next turn.
  */
 
+import { createHash, randomUUID } from 'node:crypto';
+import { normalizeResponsesInput } from './responses-input.js';
+import { fetchWithCredentials, type CredentialResolver } from './credentials.js';
+
 import type {
   ContentBlock,
   ProviderAdapter,
@@ -114,7 +118,26 @@ 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;
+  /** Subscription mode: base of the prompt-cache routing id sent as the
+   * `session_id` header and as `prompt_cache_key`. Each request appends a digest
+   * of its instructions and first input item, which groups requests by
+   * serialized head: requests that share a head share an id (and a prefix, so
+   * that is the right grouping), tools and later items are not considered.
+   * Streams that need isolation beyond that (same-head forks or subagents on
+   * one adapter) should set `extra.prompt_cache_key`, which is used instead.
+   * Defaults to a random id held for the adapter's lifetime, so a restart
+   * pays one uncached read per head; pin it to survive restarts. */
+  sessionId?: string;
+  /** API base URL (defaults to the selected mode's endpoint). */
   baseURL?: string;
   /** Optional OpenAI organization ID. */
   organization?: string;
@@ -126,12 +149,20 @@ export interface OpenAIResponsesAPIAdapterConfig {
   extraHeaders?: Record<string, string>;
 }
 
+/** A cache key is any JSON string, a header value is not: anything beyond
+ * short visible ASCII is sent as a digest, which is just as stable. */
+function headerSafeSessionId(key: string): string {
+  return /^[\x21-\x7e]{1,128}$/.test(key)
+    ? key
+    : createHash('sha256').update(key).digest('hex').slice(0, 32);
+}
+
 // ============================================================================
 // Adapter
 // ============================================================================
 
 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 +175,13 @@ 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 sessionId: string;
   private readonly baseURL: string;
   private readonly organization?: string;
   private readonly project?: string;
@@ -151,39 +189,52 @@ 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.sessionId = config.sessionId ?? randomUUID();
     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 +256,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 +312,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 +351,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 +377,32 @@ 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> {
+    // Built with set() because header names are case-insensitive: spreading into
+    // an object lets `Session_Id` in extraHeaders coexist with the computed
+    // `session_id`, and Headers then joins the two into one comma-separated value.
+    const headers = new Headers({ 'Content-Type': 'application/json' });
+    if (this.organization) headers.set('OpenAI-Organization', this.organization);
+    if (this.project) headers.set('OpenAI-Project', this.project);
+    if (this.subscription) {
+      // The subscription backend keys its prompt cache on this header and
+      // ignores the body's prompt_cache_key: without it every response gets a
+      // fresh random key and a byte-stable prefix still reads cached_tokens 0
+      // (probed live 2026-09-21: 0 of 9.2k without, 9088 of 9256 with). Warm
+      // calls still miss sporadically whatever the id: 3 of 28 on a dedicated
+      // id, 3 of 13 on one shared by two interleaved prefixes.
+      headers.set('session_id', headerSafeSessionId(String(request.prompt_cache_key)));
+    }
+    for (const [name, value] of Object.entries(this.extraHeaders)) headers.set(name, value);
+    return fetchWithCredentials(`${this.baseURL}/responses`, {
+      method: 'POST',
+      body: JSON.stringify(request),
+      signal,
+      headers,
+    }, this.credentials ?? { token: this.apiKey });
   }
 
   private buildRequest(request: ProviderRequest): OpenAIResponsesAPIRequest {
@@ -366,9 +447,26 @@ 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;
+      if (typeof responsesRequest.prompt_cache_key !== 'string' || !responsesRequest.prompt_cache_key) {
+        const head = createHash('sha256')
+          .update(this.sessionId)
+          .update(JSON.stringify([responsesRequest.instructions ?? '', responsesRequest.input[0] ?? null]))
+          .digest('hex')
+          .slice(0, 12);
+        responsesRequest.prompt_cache_key = `${this.sessionId}:${head}`;
+      }
+    }
     return responsesRequest;
   }
 
@@ -605,10 +703,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 });
   }
 
   /**

package/src/providers/openai-responses.ts

@@ -307,6 +307,8 @@ export class OpenAIResponsesAdapter implements ProviderAdapter {
   /**
    * Collect every base64 image in the conversation, in order, remembering
    * which message/block it came from so the transcript can reference it.
+   * Both `image` blocks and `generated_image` blocks (this adapter's own
+   * earlier outputs, when a consumer carries them forward as-is) count.
    */
   private collectImages(request: ProviderRequest): ImageRef[] {
     const refs: ImageRef[] = [];
@@ -315,11 +317,18 @@ export class OpenAIResponsesAdapter implements ProviderAdapter {
     (request.messages as any[]).forEach((msg, msgIndex) => {
       if (!Array.isArray(msg.content)) return;
       msg.content.forEach((block: any, blockIndex: number) => {
-        if (block?.type !== 'image') return;
-        const source = block.source;
-        if (source?.type === 'base64' && source.data) {
-          const mimeType = source.media_type ?? source.mediaType ?? 'image/png';
-          refs.push({ dataUrl: `data:${mimeType};base64,${source.data}`, msgIndex, blockIndex });
+        if (block?.type === 'image') {
+          const source = block.source;
+          if (source?.type === 'base64' && source.data) {
+            const mimeType = source.media_type ?? source.mediaType ?? 'image/png';
+            refs.push({ dataUrl: `data:${mimeType};base64,${source.data}`, msgIndex, blockIndex });
+          }
+        } else if (block?.type === 'generated_image' && typeof block.data === 'string' && block.data) {
+          // A previous output of this adapter carried forward verbatim in
+          // history (consumers that keep ProviderResponse content rather
+          // than rebuilding from a channel). It is an image like any other.
+          const mimeType = block.mimeType ?? 'image/png';
+          refs.push({ dataUrl: `data:${mimeType};base64,${block.data}`, msgIndex, blockIndex });
         }
       });
     });
@@ -481,7 +490,7 @@ export class OpenAIResponsesAdapter implements ProviderAdapter {
         msg.content.forEach((block: any, blockIndex: number) => {
           if (block?.type === 'text' && block.text) {
             lines.push(block.text);
-          } else if (block?.type === 'image') {
+          } else if (block?.type === 'image' || block?.type === 'generated_image') {
             const n = attachedIndex.get(`${msgIndex}:${blockIndex}`);
             lines.push(n !== undefined ? `[Image ${n}]` : '[Image omitted]');
           }

package/src/providers/responses-input.ts

@@ -0,0 +1,131 @@
+import type { ProviderRequest } from '../types/index.js';
+import type { OpenAIResponsesInputItem } from './openai-responses-api.js';
+
+type JsonObject = Record<string, unknown>;
+
+/**
+ * Most agent turns arrive already formatted as provider-native Responses
+ * items. Internal maintenance calls, however, can bypass that formatter and
+ * carry Membrane's normalized `text`/`image`/tool blocks. Normalize at the
+ * final transport boundary so every call shape accepted by ProviderAdapter is
+ * valid on the Codex Responses endpoint.
+ */
+export function normalizeResponsesInput(messages: ProviderRequest['messages']): OpenAIResponsesInputItem[] {
+  const output: unknown[] = [];
+
+  for (const rawMessage of messages as unknown[]) {
+    if (!isObject(rawMessage)) {
+      output.push(rawMessage);
+      continue;
+    }
+    if (rawMessage.type !== 'message' && rawMessage.role === undefined) {
+      output.push(normalizeStandaloneItem(rawMessage));
+      continue;
+    }
+
+    // Native messages (including phase, status and developer/system roles)
+    // must survive replay verbatim. Only translate normalized content blocks.
+    if (Array.isArray(rawMessage.content) && !rawMessage.content.some((block) =>
+      isObject(block) && ['text', 'image', 'tool_use', 'tool_result', 'redacted_thinking'].includes(asString(block.type))
+    )) {
+      output.push(rawMessage);
+      continue;
+    }
+    const role = typeof rawMessage.role === 'string' ? rawMessage.role : 'user';
+    const blocks = Array.isArray(rawMessage.content)
+      ? rawMessage.content
+      : typeof rawMessage.content === 'string'
+        ? [{ type: 'text', text: rawMessage.content }]
+        : [];
+    let parts: unknown[] = [];
+    const flush = () => {
+      if (parts.length === 0) return;
+      output.push({
+        type: 'message',
+        ...rawMessage,
+        role,
+        content: parts,
+      });
+      parts = [];
+    };
+
+    for (const rawBlock of blocks) {
+      if (!isObject(rawBlock)) continue;
+      if (rawBlock.type === 'text') {
+        parts.push({ type: role === 'assistant' ? 'output_text' : 'input_text', text: asString(rawBlock.text) });
+      } else if (rawBlock.type === 'image') {
+        const imageUrl = responsesImageUrl(rawBlock);
+        if (imageUrl && role !== 'assistant') parts.push({ type: 'input_image', image_url: imageUrl });
+      } else if (rawBlock.type === 'tool_use') {
+        flush();
+        output.push(normalizeStandaloneItem(rawBlock));
+      } else if (rawBlock.type === 'tool_result') {
+        flush();
+        output.push(normalizeStandaloneItem(rawBlock));
+      } else if (rawBlock.type === 'redacted_thinking') {
+        flush();
+        output.push(reasoningInputItem(rawBlock));
+      } else {
+        // Already-native input_text/output_text/input_image/refusal parts.
+        parts.push(rawBlock);
+      }
+    }
+    flush();
+  }
+
+  return output as OpenAIResponsesInputItem[];
+}
+
+function normalizeStandaloneItem(item: JsonObject): unknown {
+  if (item.type === 'tool_use') {
+    return {
+      type: 'function_call',
+      call_id: asString(item.id),
+      name: asString(item.name),
+      arguments: JSON.stringify(isObject(item.input) ? item.input : {}),
+    };
+  }
+  if (item.type === 'tool_result') {
+    const content = item.content;
+    return {
+      type: 'function_call_output',
+      call_id: asString(item.toolUseId) || asString(item.tool_use_id),
+      output: typeof content === 'string' ? content : JSON.stringify(content ?? null),
+    };
+  }
+  if (item.type === 'redacted_thinking') {
+    return reasoningInputItem(item);
+  }
+  return item;
+}
+
+/** Replay a captured reasoning carrier as a Responses input item.
+ *
+ * Prefer the provider-native item verbatim when the block still carries it
+ * (`rawItem` from response parsing). Otherwise reconstruct the minimum the
+ * Responses API accepts: `summary` is a REQUIRED field on reasoning input
+ * items (empty array = "no summaries") — omitting it 400s with
+ * "Missing required parameter: 'input[N].summary'". */
+function reasoningInputItem(block: JsonObject): unknown {
+  const raw = block.rawItem;
+  if (isObject(raw) && raw.type === 'reasoning') return raw;
+  return { type: 'reasoning', summary: [], encrypted_content: asString(block.data) };
+}
+
+function responsesImageUrl(block: JsonObject): string | undefined {
+  const source = isObject(block.source) ? block.source : undefined;
+  if (!source) return typeof block.image_url === 'string' ? block.image_url : undefined;
+  if (source.type === 'url') return asString(source.url) || undefined;
+  if (source.type !== 'base64') return undefined;
+  const mediaType = asString(source.mediaType) || asString(source.media_type) || 'image/png';
+  const data = asString(source.data);
+  return data ? `data:${mediaType};base64,${data}` : undefined;
+}
+
+function asString(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/providers/utils.ts

@@ -291,6 +291,9 @@ export function createCombinedSignal(
  */
 export class SSELineParser {
   private buffer: string = '';
+  private data: string[] = [];
+
+  constructor(private readonly options: { multiline?: boolean } = {}) {}
 
   /**
    * Feed a raw chunk from the stream reader and get back complete SSE data lines.
@@ -305,6 +308,10 @@ export class SSELineParser {
     this.buffer = lines.pop() || '';
 
     for (const line of lines) {
+      if (this.options.multiline) {
+        this.processEventLine(line.replace(/\r$/, ''), results);
+        continue;
+      }
       const trimmed = line.trim();
       if (trimmed.startsWith('data: ')) {
         results.push(trimmed.slice(6));
@@ -315,10 +322,24 @@ export class SSELineParser {
     return results;
   }
 
-  /**
-   * Flush any remaining buffered content (call when stream ends).
-   */
+  private processEventLine(line: string, results: string[]): void {
+    if (line === '') {
+      if (this.data.length) results.push(this.data.join('\n'));
+      this.data = [];
+    } else if (line.startsWith('data:')) {
+      this.data.push(line.slice(5).replace(/^ /, ''));
+    }
+  }
+
+  /** Flush any remaining event/tail when the stream ends. */
   flush(): string[] {
+    if (this.options.multiline) {
+      const results: string[] = [];
+      if (this.buffer) this.processEventLine(this.buffer.replace(/\r$/, ''), results);
+      this.buffer = '';
+      this.processEventLine('', results);
+      return results;
+    }
     if (!this.buffer.trim()) return [];
     const trimmed = this.buffer.trim();
     this.buffer = '';

package/src/types/provider.ts

@@ -207,6 +207,11 @@ export interface ProviderAdapter {
    */
   usageCacheConvention?: UsageCacheConvention;
 
+  /** Whether this transport requires the configured Responses formatter.
+   * False permits generic per-request formatter overrides (e.g. named
+   * maintenance messages). Wrappers must forward this capability. */
+  readonly requiresNativeResponsesInput?: boolean;
+
   /** Check if this adapter handles a model */
   supportsModel(modelId: string): boolean;