@aeye/openai 0.3.9 → 0.4.0

package/dist/openai.js

@@ -1,12 +1,17 @@
 /**
  * OpenAI Provider
  *
- * Provider for OpenAI's GPT models, DALL-E, Whisper, and TTS.
- * Also serves as base class for OpenAI-compatible providers.
+ * Provider for OpenAI's chat (Chat Completions and Responses), GPT Image,
+ * transcription, speech, and embedding models. Also serves as base class for
+ * OpenAI-compatible providers.
  */
-import { detectTier, isModelInfo, resolveStrictFormat } from '@aeye/ai';
-import { toFile, getDescriptor, getModel, LENIENT, SchemaBudget, strictestOf, strictify, strictPriority, toBase64, toJSONSchema, toText, toURL, getResponseFromChunks } from '@aeye/core';
+import { allocateToolDescriptors, buildSchemaBudget, clampReasoningEffort, detectTier, isModelInfo } from '@aeye/ai';
+import { deliverSchema, describeTool, getModel, getResponseFromChunks, schemaRejection, strictify, toBase64, toFile, toJSONSchema, toText, toURL } from '@aeye/core';
 import OpenAI from 'openai';
+import { chatUsage, MODERATION_MODEL, responsesUsage, toChatAudioFormat, toCitation, toModeration, toServiceTier, transcriptionUsage } from './convert';
+import { toDecisionAnswer, toDecisionQuestion } from './decisions';
+import { imageParams, imageUsage, partialImages } from './images';
+import { isResponsesOnly, outputItemChunk, responseChunks, responseEndChunk, textInput, toHostedTool, toInputContent, toReasoningItems } from './responses';
 import { isContextWindowError, parseContextWindowError, withRetry } from './retry';
 import { ContextWindowError, ProviderError } from './types';
 // ============================================================================
@@ -22,14 +27,20 @@ import { ContextWindowError, ProviderError } from './types';
  * return undefined in that case and the caller falls back to LENIENT.
  */
 function pickModelInfo(metadata, ctx, modelId) {
-    const candidates = [metadata?.model, ctx?.metadata?.model];
-    for (const c of candidates) {
-        if (c && typeof c === 'object' && isModelInfo(c) && c.id === modelId) {
-            return c;
-        }
-    }
-    return undefined;
+    return [metadata?.model, ctx?.metadata?.model].find((candidate) => !!candidate && isModelInfo(candidate) && candidate.id === modelId);
 }
+/**
+ * Models used when neither the request, the context, nor the config names one.
+ */
+const DEFAULT_MODELS = {
+    imageGenerate: 'gpt-image-2',
+    imageEdit: 'gpt-image-2',
+    imageAnalyze: 'gpt-5.4-mini',
+    transcription: 'gpt-transcribe',
+    speech: 'gpt-4o-mini-tts',
+    embedding: 'text-embedding-3-small',
+    decision: 'gpt-6-luna',
+};
 // ============================================================================
 // OpenAI Provider Class
 // ============================================================================
@@ -37,15 +48,14 @@ function pickModelInfo(metadata, ctx, modelId) {
  * OpenAI provider implementation for the @aeye framework.
  *
  * Supports the full range of OpenAI capabilities including:
- * - Chat completions with GPT-4, GPT-4 Turbo, GPT-3.5 Turbo
- * - Vision with GPT-4 Vision (GPT-4V)
- * - Reasoning models (o1, o3-mini)
- * - Image generation with DALL-E 2 and DALL-E 3
- * - Speech-to-text with Whisper
- * - Text-to-speech with TTS
+ * - Chat through Chat Completions, or the Responses API when a model or
+ *   request needs it (hosted tools, reasoning summaries or reasoning with
+ *   tools, Responses-only models)
+ * - Function calling and structured outputs, streaming, and reasoning
+ * - Image, audio, and file input; audio output
+ * - Image generation and editing with GPT Image
+ * - Transcription (with speaker diarization) and speech synthesis
  * - Text embeddings
- * - Function calling and structured outputs
- * - Streaming responses
  *
  * Can be extended by other OpenAI-compatible providers (e.g., Azure OpenAI, OpenRouter).
  *
@@ -67,7 +77,7 @@ function pickModelInfo(metadata, ctx, modelId) {
  *     ]
  *   },
  *   {},
- *   { model: 'gpt-4' }
+ *   { model: 'gpt-5.4-mini' }
  * );
  * ```
  *
@@ -92,7 +102,7 @@ function pickModelInfo(metadata, ctx, modelId) {
  *     toolChoice: 'auto',
  *   },
  *   {},
- *   { model: 'gpt-4' }
+ *   { model: 'gpt-5.4-mini' }
  * );
  * ```
  *
@@ -111,59 +121,7 @@ function pickModelInfo(metadata, ctx, modelId) {
  * ```
  *
  * @template TConfig Configuration type extending OpenAIConfig
- *
- * Subclasses can optionally override:
- * - `listModels(config)`: Custom model listing logic
- * - `createClient(config)`: Customize client creation
- * - `convertModel(model)`: Customize model conversion
- * - `customizeImageParams(params, config)`: Modify image params
- * - `customizeTranscriptionParams(params, config)`: Modify transcription params
- * - `customizeSpeechParams(params, config)`: Modify speech params
- * - `customizeEmbeddingParams(params, config)`: Modify embedding params
- */
-/**
- * Helper function to convert OpenAI-style usage to the new structured Usage format
  */
-function convertOpenAIUsage(openaiUsage) {
-    const usage = {};
-    // Text tokens (default category)
-    // Note: prompt_tokens already includes cached tokens, so we don't subtract them
-    // They're just reported separately in the details for pricing purposes
-    const textInput = (openaiUsage.prompt_tokens || 0) -
-        (openaiUsage.prompt_tokens_details?.audio_tokens || 0);
-    const textOutput = (openaiUsage.completion_tokens || 0) -
-        (openaiUsage.completion_tokens_details?.reasoning_tokens || 0) -
-        (openaiUsage.completion_tokens_details?.audio_tokens || 0);
-    if (textInput > 0 || textOutput > 0 || openaiUsage.prompt_tokens_details?.cached_tokens) {
-        usage.text = {};
-        // Only include non-cached input tokens
-        const nonCachedInput = textInput - (openaiUsage.prompt_tokens_details?.cached_tokens || 0);
-        if (nonCachedInput > 0)
-            usage.text.input = nonCachedInput;
-        if (textOutput > 0)
-            usage.text.output = textOutput;
-        if (openaiUsage.prompt_tokens_details?.cached_tokens) {
-            usage.text.cached = openaiUsage.prompt_tokens_details.cached_tokens;
-        }
-    }
-    // Reasoning tokens
-    if (openaiUsage.completion_tokens_details?.reasoning_tokens) {
-        usage.reasoning = {
-            output: openaiUsage.completion_tokens_details.reasoning_tokens
-        };
-    }
-    // Audio tokens
-    const audioInput = openaiUsage.prompt_tokens_details?.audio_tokens;
-    const audioOutput = openaiUsage.completion_tokens_details?.audio_tokens;
-    if (audioInput || audioOutput) {
-        usage.audio = {};
-        if (audioInput)
-            usage.audio.input = audioInput;
-        if (audioOutput)
-            usage.audio.output = audioOutput;
-    }
-    return usage;
-}
 export class OpenAIProvider {
     // Provider name for error messages and identification
     name = 'openai';
@@ -171,6 +129,8 @@ export class OpenAIProvider {
     config;
     // Default metadata to apply to all requests
     defaultMetadata;
+    // Models used when neither the request, the context, nor the config names one
+    defaults = DEFAULT_MODELS;
     constructor(config) {
         this.config = config;
     }
@@ -185,16 +145,6 @@ export class OpenAIProvider {
      *
      * @param config Provider configuration
      * @returns Configured OpenAI client instance
-     *
-     * @example
-     * ```typescript
-     * protected createClient(config: OpenAIConfig): OpenAI {
-     *   return new OpenAI({
-     *     apiKey: config.apiKey,
-     *     baseURL: 'https://custom-endpoint.example.com/v1',
-     *   });
-     * }
-     * ```
      */
     createClient(config) {
         return new OpenAI({
@@ -214,13 +164,12 @@ export class OpenAIProvider {
      * @returns Standardized ModelInfo object
      */
     convertModel(model) {
-        const tier = detectTier(model.id);
         return {
             provider: this.name,
             id: model.id,
             name: model.id,
             capabilities: new Set(['chat', 'streaming']), // Minimal default, enriched by model sources
-            tier,
+            tier: detectTier(model.id),
             pricing: {},
             contextWindow: 0, // Will be enriched by model sources
             maxOutputTokens: undefined,
@@ -230,59 +179,6 @@ export class OpenAIProvider {
             },
         };
     }
-    // ============================================================================
-    // Optional Override Methods for Request Customization
-    // ============================================================================
-    /**
-     * Customize image generation params before sending to API.
-     *
-     * @param params Image generation parameters
-     * @param config Provider configuration
-     * @returns Modified parameters
-     */
-    augmentImageGenerateRequest(params, request, config) {
-        // No-op by default
-    }
-    /**
-     * Customize image edit params before sending to API.
-     *
-     * @param params Image generation parameters
-     * @param config Provider configuration
-     * @returns Modified parameters
-     */
-    augmentImageEditRequest(params, request, config) {
-        // No-op by default
-    }
-    /**
-     * Customize transcription params before sending to API.
-     *
-     * @param params Transcription parameters
-     * @param config Provider configuration
-     * @returns Modified parameters
-     */
-    augmentTranscriptionRequest(params, request, config) {
-        // No-op by default
-    }
-    /**
-     * Customize speech generation params before sending to API.
-     *
-     * @param params Speech synthesis parameters
-     * @param config Provider configuration
-     * @returns Modified parameters
-     */
-    augmentSpeechRequest(params, request, config) {
-        // No-op by default
-    }
-    /**
-     * Customize embedding params before sending to API.
-     *
-     * @param params Embedding parameters
-     * @param config Provider configuration
-     * @returns Modified parameters
-     */
-    augmentEmbeddingRequest(params, request, config) {
-        // No-op by default
-    }
     /**
      * Customize chat completion params before sending to API.
      *
@@ -290,13 +186,21 @@ export class OpenAIProvider {
      * or to add provider-specific features.
      *
      * @param params OpenAI chat completion parameters
-     * @param config Provider configuration
      * @param request Original @aeye request
-     * @returns Modified parameters
+     * @param config Provider configuration
      */
     augmentChatRequest(params, request, config) {
         // No-op by default
     }
+    /**
+     * Extra HTTP headers for a chat completion request, such as a router's
+     * feature flags. None by default.
+     *
+     * @param params The params about to be sent
+     */
+    chatHeaders(params) {
+        return undefined;
+    }
     /**
      * Augment chat message with provider-specific data.
      *
@@ -309,11 +213,6 @@ export class OpenAIProvider {
     }
     /**
      * Get augmented chat message with provider-specific data.
-     *
-     * @param chatMessage - OpenAI chat message
-     * @param message - Original @aeye message
-     * @param config - Provider configuration
-     * @returns
      */
     getChatMessage(chatMessage, message, config) {
         this.augmentChatMessage(chatMessage, message, config);
@@ -330,22 +229,20 @@ export class OpenAIProvider {
         // No-op by default
     }
     /**
-     * Get augmented chat content part with provider-specific data.
-     *
-     * @param chatContent - OpenAI chat content part
-     * @param content - Original @aeye message content
-     * @param config - Provider configuration
-     * @returns
+     * Get augmented chat content part with provider-specific data. A cache
+     * breakpoint on the content marks the part.
      */
     getChatContent(chatContent, content, config) {
-        this.augmentChatContent(chatContent, content, config);
-        return chatContent;
+        const part = content.cacheBreakpoint ? { ...chatContent, prompt_cache_breakpoint: {} } : chatContent;
+        this.augmentChatContent(part, content, config);
+        return part;
     }
     /**
      * Augment chat chunk with provider-specific data.
      *
-     * @param expected
-     * @param chunk
+     * @param expected - The chunk as received
+     * @param chunk - @aeye chunk to augment
+     * @param config - Provider configuration
      */
     augmentChatChunk(expected, chunk, config) {
         // No-op by default
@@ -353,9 +250,9 @@ export class OpenAIProvider {
     /**
      * Augment chat response with provider-specific data.
      *
-     * @param openai OpenAI chat completion response
-     * @param response @aeye response object to augment
-     * @returns
+     * @param expected - The completion as received
+     * @param response - @aeye response object to augment
+     * @param config - Provider configuration
      */
     augmentChatResponse(expected, response, config) {
         // No-op by default
@@ -364,113 +261,76 @@ export class OpenAIProvider {
     // Message & Request Conversion (Protected - Reusable)
     // ============================================================================
     /**
-     * Convert @aeye MessageContent to OpenAI text content format.
-     * @param x
-     * @param name
-     * @returns
+     * Convert @aeye MessageContent to OpenAI text content format, for roles
+     * that only accept text.
+     *
+     * @param x - Message content
+     * @param name - Who sent it, for placeholder text
+     * @param config - Provider configuration
      */
     convertContentText(x, name, config) {
         if (typeof x === 'string') {
             return [{ type: 'text', text: x }];
         }
-        if (!Array.isArray(x)) {
-            console.warn(`[OpenAIProvider] convertContentText: Unsupported content type from ${name}.`);
-            return [];
-        }
-        return x.map((part) => {
-            if (part.type === 'text') {
-                return this.getChatContent({ type: 'text', text: String(part.content) }, part, config);
-            }
-            else if (part.type === 'image') {
-                return this.getChatContent({ type: 'text', text: `Image sent by ${name} not included in content.` }, part, config);
-            }
-            else if (part.type === 'file') {
-                return this.getChatContent({ type: 'text', text: `File sent by ${name} not included in content.` }, part, config);
-            }
-            else if (part.type === 'audio') {
-                return this.getChatContent({ type: 'text', text: `Audio sent by ${name} not included in content.` }, part, config);
-            }
-            return this.getChatContent({ type: 'text', text: `Unsupported content type from ${name}.` }, part, config);
-        });
+        return x.map((part) => this.getChatContent({
+            type: 'text',
+            text: part.type === 'text'
+                ? String(part.content)
+                : `${part.type[0].toUpperCase()}${part.type.slice(1)} sent by ${name} not included in content.`,
+        }, part, config));
     }
     /**
      * Convert @aeye MessageContent to OpenAI format.
-     * @param x
-     * @param name
-     * @returns
+     *
+     * @param x - Message content
+     * @param name - Who sent it, for placeholder text
+     * @param config - Provider configuration
      */
     async convertContent(x, name, config) {
         if (typeof x === 'string') {
             return [{ type: 'text', text: x }];
         }
         return Promise.all(x.map(async (part) => {
+            const note = (text) => this.getChatContent({ type: 'text', text }, part, config);
             switch (part.type) {
                 case 'text': {
                     const text = await toText(part.content).catch(() => `Text content sent by ${name} could not be converted to text.`);
-                    return this.getChatContent({
-                        type: 'text',
-                        text,
-                    }, part, config);
+                    return note(text);
                 }
                 case 'image': {
                     const url = await toURL(part.content, part.format, 'INVALID').catch(() => 'INVALID');
                     if (url === 'INVALID') {
-                        return this.getChatContent({
-                            type: 'text',
-                            text: `Image content sent by ${name} could not be converted to a URL.`,
-                        }, part, config);
+                        return note(`Image content sent by ${name} could not be converted to a URL.`);
                     }
-                    return this.getChatContent({
-                        type: 'image_url',
-                        image_url: { url },
-                    }, part, config);
+                    return this.getChatContent({ type: 'image_url', image_url: { url, detail: part.detail } }, part, config);
                 }
                 case 'audio': {
-                    // Convert audio content to base64 data
                     const base64 = await toBase64(part.content, undefined, 'INVALID').catch(() => 'INVALID');
                     if (base64 === 'INVALID') {
-                        return this.getChatContent({
-                            type: 'text',
-                            text: `Audio content sent by ${name} could not be converted to base64.`,
-                        }, part, config);
+                        return note(`Audio content sent by ${name} could not be converted to base64.`);
                     }
-                    const [, mimeType, data] = /^data:([^;]+);base64,(.+)$/.exec(base64) || [null, '', ''];
-                    const format = part.format || mimeType && mimeType.includes('wav') ? 'wav' : 'mp3';
-                    return this.getChatContent({
-                        type: 'input_audio',
-                        input_audio: { data, format },
-                    }, part, config);
+                    const [, mimeType = '', data = ''] = /^data:([^;]+);base64,(.+)$/.exec(base64) ?? [];
+                    const format = (part.format ?? mimeType).includes('wav') ? 'wav' : 'mp3';
+                    return this.getChatContent({ type: 'input_audio', input_audio: { data, format } }, part, config);
                 }
                 case 'file': {
-                    // Convert file content to base64 data (file IDs not supported)
                     const fileData = await toBase64(part.content, part.format, 'INVALID').catch(() => 'INVALID');
                     if (fileData === 'INVALID') {
-                        return this.getChatContent({
-                            type: 'text',
-                            text: `File content sent by ${name} could not be converted to base64.`,
-                        }, part, config);
+                        return note(`File content sent by ${name} could not be converted to base64.`);
                     }
                     return this.getChatContent({
                         type: 'file',
-                        file: {
-                            file_data: fileData,
-                            // TODO add filename
-                            filename: 'file' + (part.format ? `.${part.format}` : ''),
-                        },
+                        file: { file_data: fileData, filename: part.name ?? `file${part.format ? `.${part.format}` : ''}` },
                     }, part, config);
                 }
                 default:
-                    return this.getChatContent({
-                        type: 'text',
-                        text: `Unsupported content type from ${name}.`,
-                    }, part, config);
+                    return note(`${part.type} content sent by ${name} is not supported.`);
             }
         }));
     }
     /**
      * Convert @aeye ToolCall to OpenAI format.
      * @param x ToolCall object
-     * @returns
      */
     convertToolCall(x) {
         return {
@@ -498,67 +358,85 @@ export class OpenAIProvider {
             .substring(0, 64);
     }
     /**
-     * Convert @aeye Request messages to OpenAI format.
+     * Convert @aeye Request messages to Chat Completions messages.
      *
      * Handles conversion of all message types (system, user, assistant, tool)
      * and content types (text, image, audio, file).
      *
      * @param request @aeye request object
+     * @param config Provider configuration
      * @returns Array of OpenAI-formatted messages
      */
     async convertMessages(request, config) {
         return (await Promise.all(request.messages.map(async (msg) => {
             switch (msg.role) {
                 case 'system':
-                    return this.getChatMessage({
-                        role: 'developer',
-                        name: this.convertName(msg.name),
-                        content: this.convertContentText(msg.content, msg.name || 'system', config),
-                    }, msg, config);
+                    return [this.getChatMessage({
+                            role: 'developer',
+                            name: this.convertName(msg.name),
+                            content: this.convertContentText(msg.content, msg.name || 'system', config),
+                        }, msg, config)];
                 case 'tool':
-                    return this.getChatMessage({
-                        role: 'tool',
-                        tool_call_id: msg.toolCallId,
-                        content: this.convertContentText(msg.content, msg.name || 'tool', config),
-                    }, msg, config);
-                case 'assistant':
-                    const content = await this.convertContent(msg.content, msg.name || 'assistant', config);
-                    if (!content || typeof content === 'string' || content.every(c => c.type === 'text')) {
-                        return this.getChatMessage({
-                            role: msg.role,
+                    return [this.getChatMessage({
+                            role: 'tool',
+                            tool_call_id: msg.toolCallId ?? '',
+                            content: this.convertContentText(msg.content, msg.name || 'tool', config),
+                        }, msg, config)];
+                case 'user':
+                    return [this.getChatMessage({
+                            role: 'user',
                             name: this.convertName(msg.name),
-                            tool_calls: msg.toolCalls?.map((tc) => this.convertToolCall(tc)),
-                            content,
-                        }, msg, config);
-                    }
-                    else {
-                        // Mixed content - need to split into multiple messages where non-text parts are separate messages
-                        // sent as user messages because assistent role cannot have non-text content
-                        const firstText = content.findIndex(c => c.type === 'text');
-                        return content.map((contentPart, index) => {
-                            if (contentPart.type === 'text') {
-                                return this.getChatMessage({
-                                    role: 'assistant',
-                                    name: this.convertName(msg.name),
-                                    tool_calls: index === firstText ? msg.toolCalls?.map((tc) => this.convertToolCall(tc)) : undefined,
-                                    content: [contentPart],
-                                }, msg, config);
-                            }
-                            else {
-                                return this.getChatMessage({
-                                    role: 'user',
-                                    name: this.convertName(msg.name),
-                                    content: [contentPart],
-                                }, msg, config);
-                            }
-                        });
+                            content: await this.convertContent(msg.content, msg.name || 'user', config),
+                        }, msg, config)];
+                case 'assistant': {
+                    const name = this.convertName(msg.name);
+                    const toolCalls = msg.toolCalls?.map((tc) => this.convertToolCall(tc));
+                    // Some upstreams reject empty text, so a turn of only tool calls has no content
+                    const content = (await this.convertContent(msg.content, msg.name || 'assistant', config)).filter(c => c.type !== 'text' || c.text);
+                    if (content.every(c => c.type === 'text')) {
+                        return [this.getChatMessage({ role: 'assistant', name, tool_calls: toolCalls, content: content.length ? content : toolCalls?.length ? null : '' }, msg, config)];
                     }
+                    // The assistant role only takes text, so non-text parts are sent
+                    // as user messages in place
+                    const firstText = content.findIndex(c => c.type === 'text');
+                    return content.map((part, index) => part.type === 'text'
+                        ? this.getChatMessage({ role: 'assistant', name, tool_calls: index === firstText ? toolCalls : undefined, content: [part] }, msg, config)
+                        : this.getChatMessage({ role: 'user', name, content: [part] }, msg, config));
+                }
+            }
+        }))).flat();
+    }
+    /**
+     * Convert @aeye Request messages to Responses API input items. Assistant
+     * turns replay their Responses reasoning so stateless requests keep it, and
+     * tool results may carry images and files.
+     *
+     * @param request @aeye request object
+     * @param config Provider configuration
+     */
+    async convertResponsesInput(request, config) {
+        const content = async (msg) => (await this.convertContent(msg.content, msg.name || msg.role, config)).map(toInputContent);
+        // Calls to free-text tools replay as custom tool calls
+        const textTools = new Set((request.tools ?? []).flatMap(tool => tool.format ? [tool.name] : []));
+        const textCalls = new Set(request.messages.flatMap(msg => msg.toolCalls ?? []).flatMap(tc => textTools.has(tc.name) ? [tc.id] : []));
+        return (await Promise.all(request.messages.map(async (msg) => {
+            switch (msg.role) {
+                case 'system':
+                    return [{ role: 'developer', content: await content(msg) }];
                 case 'user':
-                    return this.getChatMessage({
-                        role: msg.role,
-                        name: this.convertName(msg.name),
-                        content: await this.convertContent(msg.content, msg.name || 'user', config),
-                    }, msg, config);
+                    return [{ role: 'user', content: await content(msg) }];
+                case 'tool': {
+                    const call_id = msg.toolCallId ?? '';
+                    return [{ type: textCalls.has(call_id) ? 'custom_tool_call_output' : 'function_call_output', call_id, output: await content(msg) }];
+                }
+                case 'assistant': {
+                    const text = this.convertContentText(msg.content, msg.name || 'assistant', config).map(part => part.text).join('');
+                    const message = text ? [{ role: 'assistant', content: text }] : [];
+                    const calls = (msg.toolCalls ?? []).map((tc) => textCalls.has(tc.id)
+                        ? { type: 'custom_tool_call', call_id: tc.id, name: tc.name, input: textInput(tc.arguments) }
+                        : { type: 'function_call', call_id: tc.id, name: tc.name, arguments: tc.arguments });
+                    return [...toReasoningItems(msg.reasoning, this.name), ...message, ...calls];
+                }
             }
         }))).flat();
     }
@@ -578,14 +456,12 @@ export class OpenAIProvider {
      *
      * @param request @aeye request (mutated: each tool's `descriptor` field is
      *                pinned for the validation roundtrip)
-     * @param model   the resolved model the request is targeting
      * @param budget  shared allocator (also fed by `convertResponseFormat`)
      */
-    convertTools(request, model, budget) {
+    convertTools(request, budget) {
         if (!request.tools || request.tools.length === 0)
             return undefined;
-        const localBudget = budget ?? this.buildSchemaBudget(model);
-        const descriptors = this.allocateToolDescriptors(request, localBudget);
+        const descriptors = allocateToolDescriptors(request.tools, budget);
         return request.tools.map((tool, i) => {
             const descriptor = descriptors[i];
             const strictifiedSchema = strictify(tool.parameters, descriptor);
@@ -593,16 +469,15 @@ export class OpenAIProvider {
             // strict-mode-compatible schema. Setting strict:true with a schema
             // that violates OpenAI's strict-mode rules is the failure mode we
             // are trying to avoid.
-            const result = {
+            return {
                 type: 'function',
                 function: {
                     name: tool.name,
-                    description: tool.description,
+                    description: describeTool(tool),
                     parameters: toJSONSchema(strictifiedSchema, descriptor),
                     ...(descriptor.strict ? { strict: true } : {}),
                 },
             };
-            return result;
         });
     }
     /**
@@ -614,70 +489,29 @@ export class OpenAIProvider {
      */
     supportedStrictFamilies = new Set(['openai']);
     /**
-     * Build a SchemaBudget tuned to the strictest of the model's tool /
-     * structured-output families. Anthropic-style per-request limits apply
-     * across BOTH tool schemas and the response_format schema, so the budget
-     * is shared between `convertTools` and `convertResponseFormat`.
-     *
-     * Strict mode engages only when the model's resolved family is in
-     * `supportedStrictFamilies` AND the model has the corresponding
-     * capability (`'toolsStrict'` for tools, `'structured'` for output).
-     * Mismatched families fall back to LENIENT silently — protects the
-     * wire from receiving a dialect the API doesn't understand.
-     */
-    buildSchemaBudget(model) {
-        const family = model ? resolveStrictFormat(model) : undefined;
-        const familySupported = family !== undefined && this.supportedStrictFamilies.has(family);
-        const tools = familySupported && model.capabilities.has('toolsStrict')
-            ? getDescriptor(family, true)
-            : LENIENT;
-        const out = familySupported && model.capabilities.has('structured')
-            ? getDescriptor(family, true)
-            : LENIENT;
-        return new SchemaBudget(strictestOf(tools, out));
-    }
-    /**
-     * Allocate per-tool descriptors in descending-priority order, then return
-     * them in original declaration order. Mutates `request.tools[i].descriptor`
-     * to record the chosen id for the Prompt's validation roundtrip.
+     * The schema budget for a call: from the selected model, or from the model
+     * id alone.
      */
-    allocateToolDescriptors(request, budget) {
-        const tools = request.tools;
-        const order = tools
-            .map((t, i) => ({ i, p: strictPriority(t.strict) }))
-            .sort((a, b) => b.p - a.p);
-        const descriptors = new Array(tools.length);
-        for (const { i } of order) {
-            const tool = tools[i];
-            descriptors[i] = budget.allocateTool(tool.parameters, tool.strict);
-            tool.descriptor = descriptors[i].id;
-        }
-        return descriptors;
+    schemaBudget(run) {
+        return buildSchemaBudget(run.modelInfo ?? { id: run.model.id, provider: this.name }, this.supportedStrictFamilies);
     }
     /**
      * Convert @aeye tool choice to OpenAI format.
      *
-     * Supports auto, required, none, and specific tool selection.
-     *
      * @param request @aeye request object
      * @returns OpenAI-formatted tool choice option or undefined
      */
     convertToolChoice(request) {
-        if (!request.toolChoice)
-            return undefined;
-        if (request.toolChoice === 'auto')
-            return 'auto';
-        if (request.toolChoice === 'required')
-            return 'required';
-        if (request.toolChoice === 'none')
-            return 'none';
-        if (typeof request.toolChoice === 'object') {
-            return {
-                type: 'function',
-                function: { name: request.toolChoice.tool },
-            };
+        const choice = request.toolChoice;
+        if (typeof choice !== 'object') {
+            return choice;
         }
-        return undefined;
+        return 'tool' in choice
+            ? { type: 'function', function: { name: choice.tool } }
+            : {
+                type: 'allowed_tools',
+                allowed_tools: { mode: choice.required ? 'required' : 'auto', tools: choice.allowed.map(name => ({ type: 'function', function: { name } })) },
+            };
     }
     /**
      * Convert @aeye response format to OpenAI format.
@@ -691,33 +525,27 @@ export class OpenAIProvider {
      * matching strictify before parsing model output.
      *
      * @param request @aeye request object (mutated to record descriptor)
-     * @param model the resolved model the request is targeting
+     * @param budget shared allocator (also fed by `convertTools`)
      * @returns OpenAI-formatted response format or undefined
      */
-    convertResponseFormat(request, model, budget) {
-        if (!request.responseFormat)
-            return undefined;
-        if (typeof request.responseFormat === 'string') {
-            if (request.responseFormat === 'text') {
-                return { type: 'text' };
-            }
-            if (request.responseFormat === 'json') {
-                return { type: 'json_object' };
-            }
+    convertResponseFormat(request, budget) {
+        const format = request.responseFormat;
+        if (!format)
             return undefined;
-        }
-        const localBudget = budget ?? this.buildSchemaBudget(model);
-        const descriptor = localBudget.allocateOutput(request.responseFormat.type, request.responseFormat.strict ?? 1);
-        request.responseFormat.descriptor = descriptor.id;
-        const strictifiedSchema = strictify(request.responseFormat.type, descriptor);
-        const json_schema = {
-            name: 'response',
-            schema: toJSONSchema(strictifiedSchema, descriptor),
+        if (format === 'text')
+            return { type: 'text' };
+        if (format === 'json')
+            return { type: 'json_object' };
+        const descriptor = budget.allocateOutput(format.type, format.strict ?? 1);
+        format.descriptor = descriptor.id;
+        return {
+            type: 'json_schema',
+            json_schema: {
+                name: 'response',
+                schema: toJSONSchema(strictify(format.type, descriptor), descriptor),
+                ...(descriptor.strict ? { strict: true } : {}),
+            },
         };
-        if (descriptor.strict) {
-            json_schema.strict = true;
-        }
-        return { type: 'json_schema', json_schema };
     }
     // ============================================================================
     // Provider Interface Implementation
@@ -730,15 +558,13 @@ export class OpenAIProvider {
      * @throws {ProviderError} If listing models fails
      */
     async listModels(config) {
-        const effectiveConfig = config || this.config;
-        const client = this.createClient(effectiveConfig);
+        const client = this.createClient({ ...this.config, ...config });
         try {
             const response = await client.models.list();
-            const models = response.data;
-            return models.map((m) => this.convertModel(m));
+            return response.data.map((m) => this.convertModel(m));
         }
         catch (error) {
-            throw new ProviderError(this.name, 'Failed to list models', error);
+            throw new ProviderError(this.name, 'Failed to list models', error instanceof Error ? error : undefined);
         }
     }
     /**
@@ -749,9 +575,7 @@ export class OpenAIProvider {
      */
     async checkHealth(config) {
         try {
-            const effectiveConfig = config || this.config;
-            const client = this.createClient(effectiveConfig);
-            await client.models.list();
+            await this.createClient({ ...this.config, ...config }).models.list();
             return true;
         }
         catch {
@@ -759,20 +583,26 @@ export class OpenAIProvider {
         }
     }
     /**
-     * Get request data common to all request types.
+     * Resolve what one API call needs: the effective config and its client,
+     * the model (request, then context, then metadata, then configured and
+     * built-in defaults), and retries.
      *
+     * @param operation - Operation name for retry events and errors
      * @param request - The request
      * @param ctx - The context
-     * @param effectiveConfig - The effective configuration
-     * @param defaultModel - Optional default model
-     * @returns
+     * @param metadata - Request metadata, for chat
+     * @param config - Per-call config override
+     * @param signal - Per-call abort signal
+     * @param defaultModel - Which configured default model applies
      */
-    getRequestData(request, requestSignal, ctx, effectiveConfig, operation, defaultModel) {
-        const model = getModel(request.model || ctx.metadata?.model || defaultModel);
+    prepare(operation, request, ctx, metadata, config, signal, defaultModel) {
+        const effectiveConfig = { ...this.config, ...config };
+        const model = getModel(request.model || ctx.metadata?.model || metadata?.model ||
+            effectiveConfig.defaultModels?.[defaultModel] || this.defaults[defaultModel]);
         if (!model) {
             throw new ProviderError(this.name, `Model is required for ${this.name} requests`);
         }
-        const retryConfig = { ...effectiveConfig.retry, ...(request.extra?.retry) };
+        const retryConfig = { ...effectiveConfig.retry, ...request.extra?.retry };
         const retryEvents = request.extra?.retryEvents || effectiveConfig.retryEvents || {};
         const retryContext = {
             operation,
@@ -780,1200 +610,858 @@ export class OpenAIProvider {
             provider: this.name,
             startTime: Date.now(),
         };
-        const signal = requestSignal || ctx.signal;
-        const retry = (fn) => {
-            return withRetry(() => fn(signal), retryContext, retryConfig, retryEvents, signal);
+        const effectiveSignal = signal || ctx.signal;
+        return {
+            config: effectiveConfig,
+            client: this.createClient(effectiveConfig),
+            ctx,
+            metadata,
+            model,
+            modelInfo: pickModelInfo(metadata, ctx, model.id),
+            signal: effectiveSignal,
+            retry: (call) => withRetry(() => call(effectiveSignal), retryContext, retryConfig, retryEvents, effectiveSignal),
         };
-        return { model, retry, signal };
     }
     /**
-     * Create an executor for chat completion requests.
-     *
-     * The executor handles non-streaming chat completions with support for:
-     * - Multi-turn conversations
-     * - Function calling
-     * - Structured outputs
-     * - Vision (images)
-     * - Audio inputs
-     *
-     * @param config Optional configuration override
-     * @returns Executor function for chat completions
-     * @throws {ProviderError} If request fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * Send one API call with retries, around the operation's before and error
+     * hooks. A context-window rejection becomes a ContextWindowError.
      */
-    createExecutor(config) {
-        const effectiveConfig = { ...this.config, ...config };
-        const client = this.createClient(effectiveConfig);
-        return async (request, ctx, metadata, requestSignal) => {
-            const { model, retry } = this.getRequestData(request, requestSignal, ctx, effectiveConfig, 'chat', metadata?.model || effectiveConfig.defaultModels?.chat);
-            // Resolve full ModelInfo for strict-format decisions. BaseAPI injects
-            // the selected ModelInfo into ctx.metadata.model after model selection;
-            // fall back to the lightweight model from getRequestData when no
-            // ModelInfo is available (e.g. external callers bypassing BaseAPI).
-            const modelInfo = pickModelInfo(metadata, ctx, model.id);
-            // One budget shared across tools + structured output. Anthropic-style
-            // per-request limits apply across the whole request, so allocations
-            // need to cooperate rather than each hold their own counter.
-            const budget = this.buildSchemaBudget(modelInfo);
-            const messages = await this.convertMessages(request, effectiveConfig);
-            const tools = this.convertTools(request, modelInfo, budget);
-            const tool_choice = tools?.length ? this.convertToolChoice(request) : undefined;
-            const parallel_tool_calls = tools?.length ? !request.toolsOneAtATime : undefined;
-            const response_format = this.convertResponseFormat(request, modelInfo, budget);
-            const params = {
-                model: model.id,
-                messages,
-                temperature: request.temperature,
-                top_p: request.topP,
-                max_completion_tokens: request.maxTokens,
-                frequency_penalty: request.frequencyPenalty,
-                presence_penalty: request.presencePenalty,
-                logit_bias: request.logitBias,
-                logprobs: request.logProbabilities,
-                prompt_cache_key: request.cacheKey,
-                safety_identifier: request.userKey,
-                store: effectiveConfig.store ?? false,
-                stop: request.stop,
-                tools,
-                tool_choice,
-                parallel_tool_calls,
-                response_format,
-                reasoning_effort: request.reason?.effort,
-                ...request.extra,
-                stream: false,
-            };
-            this.augmentChatRequest(params, request, effectiveConfig);
-            // Call pre-request hook with params
-            await effectiveConfig.hooks?.chat?.beforeRequest?.(request, params, ctx, metadata);
-            let completion;
-            try {
-                completion = await retry(async (signal) => {
-                    const data = await client.chat.completions.create(params, { signal });
-                    const choice = data.choices?.[0];
-                    if (!choice) {
-                        throw new ProviderError(this.name, 'No choices in response');
-                    }
-                    return data;
-                });
-            }
-            catch (e) {
-                if (isContextWindowError(e)) {
-                    const details = parseContextWindowError(e);
-                    const errorResponse = {
-                        content: '',
-                        toolCalls: [],
-                        finishReason: 'length',
-                        model,
-                        usage: { text: { input: details?.contextWindow } },
-                    };
-                    // Call post-request hook even on error
-                    await effectiveConfig.hooks?.chat?.afterRequest?.(request, params, errorResponse, ctx, metadata);
-                    return errorResponse;
-                }
-                else {
-                    await effectiveConfig.hooks?.chat?.onError?.(request, params, e, ctx, metadata);
-                }
+    async send(op, run, request, params, call) {
+        const hooks = run.config.hooks?.[op];
+        await hooks?.beforeRequest?.(request, params, run.ctx, run.metadata);
+        try {
+            return await run.retry(call);
+        }
+        catch (e) {
+            if (!(e instanceof Error)) {
                 throw e;
             }
-            const choice = completion.choices[0];
-            const toolCalls = choice.message.tool_calls
-                ?.filter((tc) => tc.type === 'function')
-                .map((tc) => ({
-                id: tc.id,
-                name: tc.function.name,
-                arguments: tc.function.arguments,
-            }));
-            const response = {
-                content: choice.message.content || '',
-                toolCalls,
-                finishReason: choice.finish_reason === 'function_call' /* deprecated */ ? 'stop' : toolCalls?.length ? 'tool_calls' : choice.finish_reason,
-                refusal: choice.finish_reason === 'content_filter' ? choice.message.content || undefined : undefined,
-                model,
-                usage: completion.usage ? convertOpenAIUsage(completion.usage) : undefined,
-            };
-            this.augmentChatResponse(completion, response, effectiveConfig);
-            // Call post-request hook with params
-            await effectiveConfig.hooks?.chat?.afterRequest?.(request, params, response, ctx, metadata);
-            return response;
-        };
+            if (isContextWindowError(e)) {
+                throw new ContextWindowError(this.name, `Context window exceeded during ${op}`, parseContextWindowError(e)?.contextWindow, e);
+            }
+            await hooks?.onError?.(request, params, e, run.ctx, run.metadata);
+            throw e;
+        }
     }
     /**
-     * Create a streamer for streaming chat completion requests.
-     *
-     * The streamer yields chunks as they arrive from OpenAI, enabling
-     * real-time response rendering.
-     *
-     * @param config Optional configuration override
-     * @returns Streamer async generator function
-     * @throws {ProviderError} If request fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * Report a response to the operation's after hook and return it.
      */
-    createStreamer(config) {
-        const effectiveConfig = { ...this.config, ...config };
-        const client = this.createClient(effectiveConfig);
-        return async function* (request, ctx, metadata, requestSignal) {
-            const { model, retry, signal } = this.getRequestData(request, requestSignal, ctx, effectiveConfig, 'streaming chat', metadata?.model || effectiveConfig.defaultModels?.chat);
-            const modelInfo = pickModelInfo(metadata, ctx, model.id);
-            const budget = this.buildSchemaBudget(modelInfo);
-            const messages = await this.convertMessages(request, effectiveConfig);
-            const tools = this.convertTools(request, modelInfo, budget);
-            const tool_choice = tools?.length ? this.convertToolChoice(request) : undefined;
-            const parallel_tool_calls = tools?.length ? !request.toolsOneAtATime : undefined;
-            const response_format = this.convertResponseFormat(request, modelInfo, budget);
-            const params = {
-                model: model.id,
-                messages,
-                temperature: request.temperature,
-                top_p: request.topP,
-                max_completion_tokens: request.maxTokens,
-                frequency_penalty: request.frequencyPenalty,
-                presence_penalty: request.presencePenalty,
-                logit_bias: request.logitBias,
-                logprobs: request.logProbabilities,
-                prompt_cache_key: request.cacheKey,
-                safety_identifier: request.userKey,
-                store: effectiveConfig.store ?? false,
-                stop: request.stop,
-                tools,
-                tool_choice,
-                parallel_tool_calls,
-                response_format,
-                ...request.extra,
-                stream: true,
-                stream_options: { include_usage: true },
-            };
-            this.augmentChatRequest(params, request, effectiveConfig);
-            // Call pre-request hook with params
-            await effectiveConfig.hooks?.chat?.beforeRequest?.(request, params, ctx, metadata);
-            let stream;
-            try {
-                stream = await retry(async (signal) => {
-                    const { response, data } = await client.chat.completions.create(params, { signal }).withResponse();
-                    if (!response.ok) {
-                        const headers = Object.fromEntries(response.headers);
-                        const body = await response.text().catch(() => '');
-                        const details = {
-                            status: response.status,
-                            statusText: response.statusText,
-                            headers,
-                            body,
-                        };
-                        throw new ProviderError(this.name, `Chat completion request failed: ${JSON.stringify(details)}`);
-                    }
-                    return data;
-                });
-            }
-            catch (e) {
-                if (isContextWindowError(e)) {
-                    const details = parseContextWindowError(e);
-                    const errorResponse = {
-                        content: '',
-                        toolCalls: [],
-                        finishReason: 'length',
-                        model,
-                        usage: { text: { input: details?.contextWindow } },
-                    };
-                    // Call post-request hook even on error
-                    await effectiveConfig.hooks?.chat?.afterRequest?.(request, params, errorResponse, ctx, metadata);
-                    return errorResponse;
-                }
-                else {
-                    await effectiveConfig.hooks?.chat?.onError?.(request, params, e, ctx, metadata);
-                }
-                throw e;
-            }
-            const toolCallsMap = new Map();
-            const toolCalls = [];
-            const chunks = [];
-            let maxIndexSeen = -1;
-            try {
-                for await (const chunk of stream) {
-                    if (signal?.aborted) {
-                        throw new Error('Request aborted');
-                    }
-                    const choice = chunk?.choices[0];
-                    const delta = choice?.delta;
-                    // OpenAI streams `finish_reason: null` on every intermediate chunk
-                    // and only sets a real value on the last chunk for the choice.
-                    // Normalize null → undefined so downstream `!== undefined` checks
-                    // (used by the tool-call finalization logic below) don't treat
-                    // every intermediate chunk as "the model is done".
-                    const finishReasonRaw = choice?.finish_reason ?? undefined;
-                    const yieldChunk = {
-                        content: delta?.content || undefined,
-                        finishReason: finishReasonRaw,
-                        refusal: delta?.refusal ?? undefined,
-                        usage: chunk.usage ? convertOpenAIUsage(chunk.usage) : undefined,
-                    };
-                    // Handle tool calls
-                    for (const toolCall of toolCalls) {
-                        toolCall.updated = false;
-                    }
-                    if (delta?.tool_calls) {
-                        for (const tc of delta.tool_calls) {
-                            const existing = toolCallsMap.get(tc.index);
-                            const toolCall = existing || { id: '', name: '', arguments: '', named: false, finished: false, updated: true, index: tc.index };
-                            if (tc.id) {
-                                toolCall.id = tc.id;
-                                toolCall.updated = true;
-                            }
-                            if (tc.function?.name) {
-                                toolCall.name = tc.function.name;
-                                toolCall.updated = true;
-                            }
-                            if (tc.function?.arguments) {
-                                toolCall.arguments += tc.function.arguments;
-                                toolCall.updated = true;
-                            }
-                            if (!existing) {
-                                toolCallsMap.set(tc.index, toolCall);
-                                toolCalls.push(toolCall);
-                            }
-                            if (typeof tc.index === 'number' && tc.index > maxIndexSeen) {
-                                maxIndexSeen = tc.index;
-                            }
-                            if (toolCall.arguments) {
-                                if (!toolCall.named) {
-                                    yieldChunk.toolCallNamed = toolCall;
-                                    toolCall.named = true;
-                                }
-                                else {
-                                    yieldChunk.toolCallArguments = toolCall;
-                                }
-                            }
-                        }
-                    }
-                    // Finalize tool calls only when we have positive evidence they're done.
-                    // The previous "updated == false this chunk" check was wrong: providers
-                    // (OpenRouter especially, with stream_options.include_usage) interleave
-                    // usage-only / keep-alive chunks that have no `choices`/`delta`, which
-                    // would prematurely flip a still-streaming tool_call to finished and
-                    // emit it with partial arguments — downstream parse() then rejected
-                    // it as "called with NO arguments". Only finalize when:
-                    //   1. finish_reason is set on this chunk (the whole response is done), or
-                    //   2. a higher tc.index appeared (per OpenAI streaming convention,
-                    //      tool_calls arrive in index order, so a newer index implies the
-                    //      older ones are complete).
-                    // Anything still unfinished by stream end is handled by the finally block.
-                    const hasFinishReason = yieldChunk.finishReason !== undefined;
-                    for (const toolCall of toolCalls) {
-                        if (!toolCall.finished && (hasFinishReason || toolCall.index < maxIndexSeen)) {
-                            toolCall.finished = true;
-                            yieldChunk.toolCall = toolCall;
-                            if (!toolCall.named) {
-                                yieldChunk.toolCallNamed = toolCall;
-                                yieldChunk.toolCallArguments = toolCall;
-                                toolCall.named = true;
-                            }
-                        }
-                    }
-                    // Augment chunk with provider-specific data
-                    this.augmentChatChunk(chunk, yieldChunk, effectiveConfig);
-                    // Keep track of all chunks for post-processing if needed
-                    chunks.push(yieldChunk);
-                    // Send it!
-                    yield yieldChunk;
-                }
-            }
-            finally {
-                // All tool calls should've been emitted, but just in case
-                for (const toolCall of toolCalls) {
-                    if (!toolCall.finished) {
-                        toolCall.finished = true;
-                        const chunk = { choices: [], created: 0, id: '', model: '', object: 'chat.completion.chunk' };
-                        const yieldChunk = { toolCall };
-                        if (!toolCall.named) {
-                            yieldChunk.toolCallNamed = toolCall;
-                            yieldChunk.toolCallArguments = toolCall;
-                            toolCall.named = true;
-                        }
-                        // Augment chunk with provider-specific data  
-                        this.augmentChatChunk(chunk, yieldChunk, effectiveConfig);
-                        // Keep track of all chunks for post-processing if needed
-                        chunks.push(yieldChunk);
-                        // Send it!
-                        yield yieldChunk;
-                    }
-                }
-                // Call post-request hook with accumulated response
-                if (effectiveConfig.hooks?.chat?.afterRequest) {
-                    const finalResponse = getResponseFromChunks(chunks);
-                    finalResponse.model = model;
-                    await effectiveConfig.hooks.chat.afterRequest(request, params, finalResponse, ctx, metadata);
-                }
-            }
-        }.bind(this);
+    async finish(op, run, request, params, response) {
+        await run.config.hooks?.[op]?.afterRequest?.(request, params, response, run.ctx, run.metadata);
+        return response;
     }
     /**
-     * Get image generation parameters based on model and request.
+     * The schema a bad request rejected, if any. OpenAI names it in the error
+     * message; OpenAI-compatible providers can look further.
      *
-     * @param request - Image generation request
-     * @param model - Model ID
-     * @returns
+     * @param request - The request as sent
+     * @param error - The API's 400 or 422 error
      */
-    getGenerateParameters(request, model) {
-        const modelId = model.includes('gpt-image-')
-            ? 'gpt-image'
-            : model.includes('dall-e-2')
-                ? 'dall-e-2'
-                : model.includes('dall-e-3')
-                    ? 'dall-e-3'
-                    : 'unknown';
-        const modelParameters = {
-            'gpt-image': {
-                style: {
-                    'vivid': undefined,
-                    'natural': undefined,
-                },
-                background: {
-                    'transparent': 'transparent',
-                    'opaque': 'opaque',
-                    'auto': 'auto',
-                },
-                quality: {
-                    'low': 'low',
-                    'medium': 'medium',
-                    'high': 'high',
-                },
-                responseFormat: {
-                    'url': undefined,
-                    'b64_json': undefined,
-                },
-                sizes: [
-                    { width: 1024, height: 1024 },
-                    { width: 1536, height: 1024 },
-                    { width: 1024, height: 1536 },
-                ],
-                n: { min: 1, max: 10 },
-            },
-            'dall-e-2': {
-                style: {
-                    'vivid': undefined,
-                    'natural': undefined,
-                },
-                background: {
-                    'transparent': undefined,
-                    'opaque': undefined,
-                    'auto': undefined,
-                },
-                quality: {
-                    'low': 'standard',
-                    'medium': 'standard',
-                    'high': 'standard',
-                },
-                responseFormat: {
-                    'url': 'url',
-                    'b64_json': 'b64_json',
-                },
-                sizes: [
-                    { width: 256, height: 256 },
-                    { width: 512, height: 512 },
-                    { width: 1024, height: 1024 },
-                ],
-                n: { min: 1, max: 10 },
-            },
-            'dall-e-3': {
-                style: {
-                    'vivid': 'vivid',
-                    'natural': 'natural',
-                },
-                background: {
-                    'transparent': undefined,
-                    'opaque': undefined,
-                    'auto': undefined,
-                },
-                quality: {
-                    'low': 'standard',
-                    'medium': 'hd',
-                    'high': 'hd',
-                },
-                responseFormat: {
-                    'url': 'url',
-                    'b64_json': 'b64_json',
-                },
-                sizes: [
-                    { width: 1024, height: 1024 },
-                    { width: 1792, height: 1024 },
-                    { width: 1024, height: 1792 },
-                ],
-                n: { min: 1, max: 1 },
-            },
-            'unknown': {
-                style: {
-                    'vivid': undefined,
-                    'natural': undefined,
-                },
-                background: {
-                    'transparent': undefined,
-                    'opaque': undefined,
-                    'auto': undefined,
-                },
-                quality: {
-                    'low': undefined,
-                    'medium': undefined,
-                    'high': undefined,
-                },
-                responseFormat: {
-                    'url': undefined,
-                    'b64_json': undefined,
-                },
-                sizes: [],
-                n: { min: 1, max: 1 },
-            },
-        };
-        const sizesAvailable = modelParameters[modelId].sizes;
-        let size = undefined;
-        if (request.size && sizesAvailable.length > 0) {
-            const [widthStr, heightStr] = request.size.split('x');
-            const width = parseInt(widthStr, 10);
-            const height = parseInt(heightStr, 10);
-            const closest = sizesAvailable
-                .map(d => ({
-                ...d,
-                ratioDiff: Math.abs(d.width / d.height - width / height),
-                scale: Math.min(d.width / width, d.height / height)
-            }))
-                .sort((a, b) => a.ratioDiff - b.ratioDiff || b.scale - a.scale)[0];
-            size = `${closest.width}x${closest.height}`;
-        }
-        const params = {
-            model,
-            prompt: request.prompt,
-            n: request.n ? Math.max(modelParameters[modelId].n.min, Math.min(modelParameters[modelId].n.max, request.n)) : undefined,
-            size,
-            quality: request.quality ? modelParameters[modelId].quality[request.quality] : undefined,
-            style: request.style ? modelParameters[modelId].style[request.style] : undefined,
-            background: request.background ? modelParameters[modelId].background[request.background] : undefined,
-            response_format: request.responseFormat ? modelParameters[modelId].responseFormat[request.responseFormat] : undefined,
-        };
-        return params;
+    rejectedSchema(request, error) {
+        return schemaRejection(request, error);
     }
     /**
-     * Generate images.
-     *
-     * @param request Image generation request parameters
-     * @param ctx Context object (not used)
-     * @param config Optional configuration override
-     * @returns Generated image URLs or base64 data
-     * @throws {ProviderError} If generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * Send a chat call. A request that overflows the context window ends as
+     * `length` rather than failing, so the prompt loop can trim and retry. A
+     * rejected schema becomes a SchemaRejectedError.
      */
-    generateImage = async (request, ctx, config) => {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'generate image', effectiveConfig.defaultModels?.imageGenerate || 'gpt-image-1');
-        const baseParams = this.getGenerateParameters(request, model.id);
-        const params = {
-            ...baseParams,
-            user: request.userIdentifier,
-            ...request.extra,
-            stream: false,
-        };
-        // Apply provider-specific customizations
-        this.augmentImageGenerateRequest?.(params, request, effectiveConfig);
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.imageGenerate?.beforeRequest?.(request, params, ctx);
-        const client = this.createClient(effectiveConfig);
-        let response;
+    async sendChat(op, run, request, params, call) {
         try {
-            response = await retry(async (signal) => {
-                return await client.images.generate(params, { signal });
-            });
+            return { result: await this.send(op, run, request, params, call) };
         }
         catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during image generation', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.imageGenerate?.onError?.(request, params, e, ctx);
+            if (!(e instanceof ContextWindowError)) {
+                const badRequest = e instanceof Error && 'status' in e && (e.status === 400 || e.status === 422);
+                throw (badRequest && this.rejectedSchema(request, e)) || e;
             }
-            throw e;
+            const overflow = { content: '', toolCalls: [], finishReason: 'length', model: run.model, usage: { text: { input: e.contextWindow } } };
+            return { overflow: await this.finish(op, run, request, params, overflow) };
         }
-        const result = {
-            images: (response.data || []).map((img) => ({
-                url: img.url || undefined,
-                b64_json: img.b64_json || undefined,
-                revisedPrompt: img.revised_prompt || undefined,
-            })),
-            model,
-            usage: response.usage ? convertOpenAIUsage(response.usage) : undefined,
-        };
-        // Call post-request hook with params
-        await effectiveConfig.hooks?.imageGenerate?.afterRequest?.(request, params, result, ctx);
-        return result;
-    };
+    }
     /**
-     * Generate images with streaming progress updates.
-     *
-     * Note: OpenAI's API doesn't natively support streaming image generation,
-     * so this implementation polls for progress or returns the result immediately.
-     *
-     * @param request Image generation request parameters
-     * @param ctx Context object (not used)
-     * @param config Optional configuration override
-     * @returns Async generator yielding progress chunks
-     * @throws {ProviderError} If generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * Relay streamed chunks, then report the assembled response to the after
+     * hook (even when the stream fails part way) and return it.
      */
-    generateImageStream = async function* (request, ctx, config) {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry, signal } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'generate image stream', effectiveConfig.defaultModels?.imageGenerate || 'gpt-image-1');
-        const baseParams = this.getGenerateParameters(request, model.id);
-        const imageStreams = Math.max(1, Math.min(3, request.streamCount ?? 2));
-        const params = {
-            ...baseParams,
-            user: request.userIdentifier,
-            partial_images: imageStreams,
-            ...request.extra,
-            stream: true,
-        };
-        this.augmentImageGenerateRequest?.(params, request, effectiveConfig);
-        const client = this.createClient(effectiveConfig);
+    async *relay(op, run, request, params, chunks) {
+        const received = [];
         let response;
         try {
-            response = await retry(async (signal) => {
-                return await client.images.generate(params, { signal });
-            });
-        }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during image generation', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.imageGenerate?.onError?.(request, params, e, ctx);
+            for await (const chunk of chunks) {
+                if (run.signal?.aborted) {
+                    throw new Error('Request aborted');
+                }
+                received.push(chunk);
+                yield chunk;
             }
-            throw e;
         }
-        // Yield completion with results
-        let imageCount = 0;
-        for await (const img of response) {
-            if (signal?.aborted) {
-                throw new Error('Request aborted');
-            }
-            const progress = (imageCount + 1) / (imageStreams + 1);
-            yield {
-                progress,
-                done: img.type === 'image_generation.completed',
-                image: {
-                    b64_json: img.b64_json || undefined,
-                },
-            };
-            imageCount++;
+        finally {
+            response = getResponseFromChunks(received, run.model);
+            await this.finish(op, run, request, params, response);
         }
-    };
+        return response;
+    }
+    // ============================================================================
+    // Chat
+    // ============================================================================
     /**
-     * Get image generation parameters based on model and request.
+     * Whether a chat request goes to the Responses API: always or never when
+     * configured, otherwise when the model is Responses-only or the request
+     * uses something only Responses offers.
      *
-     * @param request - Image generation request
-     * @param model - Model ID
-     * @returns
+     * @param request - The request
+     * @param modelId - The model it targets
+     * @param config - Provider configuration
+     * @param model - The full model, whose registry entry says whether it is
+     *   Responses-only; the model id decides otherwise
      */
-    getEditParameters(request, model) {
-        const modelId = model.includes('gpt-image-')
-            ? 'gpt-image'
-            : model.includes('dall-e-2')
-                ? 'dall-e-2'
-                : model.includes('dall-e-3')
-                    ? 'dall-e-3'
-                    : 'unknown';
-        const modelParameters = {
-            'gpt-image': {
-                responseFormat: {
-                    'url': undefined,
-                    'b64_json': undefined,
-                },
-                sizes: [
-                    { width: 1024, height: 1024 },
-                    { width: 1536, height: 1024 },
-                    { width: 1024, height: 1536 },
-                ],
-                n: { min: 1, max: 10 },
-            },
-            'dall-e-2': {
-                responseFormat: {
-                    'url': 'url',
-                    'b64_json': 'b64_json',
-                },
-                sizes: [
-                    { width: 256, height: 256 },
-                    { width: 512, height: 512 },
-                    { width: 1024, height: 1024 },
-                ],
-                n: { min: 1, max: 10 },
-            },
-            'dall-e-3': {
-                responseFormat: {
-                    'url': 'url',
-                    'b64_json': 'b64_json',
-                },
-                sizes: [
-                    { width: 1024, height: 1024 },
-                    { width: 1792, height: 1024 },
-                    { width: 1024, height: 1792 },
-                ],
-                n: { min: 1, max: 1 },
-            },
-            'unknown': {
-                responseFormat: {
-                    'url': undefined,
-                    'b64_json': undefined,
-                },
-                sizes: [],
-                n: { min: 1, max: 1 },
-            },
-        };
-        const sizesAvailable = modelParameters[modelId].sizes;
-        let size = undefined;
-        if (request.size && sizesAvailable.length > 0) {
-            const [widthStr, heightStr] = request.size.split('x');
-            const width = parseInt(widthStr, 10);
-            const height = parseInt(heightStr, 10);
-            const closest = sizesAvailable
-                .map(d => ({
-                ...d,
-                ratioDiff: Math.abs(d.width / d.height - width / height),
-                scale: Math.min(d.width / width, d.height / height)
-            }))
-                .sort((a, b) => a.ratioDiff - b.ratioDiff || b.scale - a.scale)[0];
-            size = `${closest.width}x${closest.height}`;
+    usesResponses(request, modelId, config, model) {
+        const api = config.api ?? 'auto';
+        if (api !== 'auto') {
+            return api === 'responses';
         }
-        const params = {
-            model,
-            prompt: request.prompt,
-            n: request.n ? Math.max(modelParameters[modelId].n.min, Math.min(modelParameters[modelId].n.max, request.n)) : undefined,
-            size,
-            response_format: request.responseFormat ? modelParameters[modelId].responseFormat[request.responseFormat] : undefined,
-        };
-        return params;
+        const responsesOnly = model?.metadata?.responsesOnly ?? isResponsesOnly(modelId);
+        const { effort, mode, summary, context } = request.reason ?? {};
+        const responsesTools = request.tools?.some(tool => tool.format || tool.defer || tool.async);
+        // Only Responses carries reasoning across tool calls, and newer models
+        // reject function tools with reasoning on Chat Completions
+        const reasonsWithTools = !!request.tools?.length && !!effort && effort !== 'none';
+        return responsesOnly === true || !!request.hostedTools?.length || !!responsesTools || reasonsWithTools || !!(mode || summary || context);
     }
     /**
-     * Edit images using DALL-E models.
+     * Chat Completions parameters for a request, before the stream flag.
      *
-     * Supports image editing with text prompts and optional masks.
+     * @param request - The request
+     * @param run - The resolved call
+     * @param streaming - Whether the response will stream (audio output
+     *   streams only as PCM)
+     */
+    async buildChatParams(request, run, streaming) {
+        const budget = this.schemaBudget(run);
+        const tools = this.convertTools(request, budget);
+        const audio = request.modalities?.includes('audio') ? request.audio : undefined;
+        const audioFormat = outputAudioFormat(request, streaming);
+        const store = run.config.store ?? false;
+        return {
+            model: run.model.id,
+            messages: await this.convertMessages(request, run.config),
+            temperature: request.temperature,
+            top_p: request.topP,
+            max_completion_tokens: request.maxTokens,
+            frequency_penalty: request.frequencyPenalty,
+            presence_penalty: request.presencePenalty,
+            logit_bias: request.logitBias,
+            logprobs: request.logProbabilities,
+            seed: request.seed,
+            stop: request.stop,
+            tools,
+            tool_choice: tools?.length ? this.convertToolChoice(request) : undefined,
+            // Parallel calls are the default; reasoning models such as o3 reject the parameter itself
+            parallel_tool_calls: tools?.length && request.toolsOneAtATime ? false : undefined,
+            response_format: this.convertResponseFormat(request, budget),
+            reasoning_effort: request.reason?.effort && clampReasoningEffort(request.reason.effort, run.modelInfo?.reasoningEfforts),
+            verbosity: request.verbosity,
+            service_tier: request.serviceTier,
+            // Chat Completions only takes metadata on stored completions
+            metadata: store ? request.metadata : undefined,
+            modalities: audio ? ['text', 'audio'] : undefined,
+            audio: audio && audioFormat && { voice: audio.voice, format: toChatAudioFormat(audioFormat) },
+            moderation: request.moderate ? { model: MODERATION_MODEL } : undefined,
+            prompt_cache_key: request.cacheKey,
+            safety_identifier: request.userKey,
+            store,
+            ...request.extra,
+        };
+    }
+    /**
+     * Responses API parameters for a request, before the stream flag.
+     * Reasoning comes back encrypted unless responses are stored, so later
+     * turns can replay it.
      *
-     * @param request Image edit request parameters
-     * @param ctx Context object (not used)
-     * @param config Optional configuration override
-     * @returns Edited image URLs or base64 data
-     * @throws {ProviderError} If editing fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * @param request - The request
+     * @param run - The resolved call
      */
-    editImage = async (request, ctx, config) => {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'edit image', effectiveConfig.defaultModels?.imageEdit || 'gpt-image-1');
-        const image = await toFile(request.image);
-        const mask = request.mask ? await toFile(request.mask) : undefined;
-        const baseParams = this.getEditParameters(request, model.id);
-        const params = {
-            ...baseParams,
-            image,
-            mask,
-            user: request.userIdentifier,
+    async buildResponsesParams(request, run) {
+        const budget = this.schemaBudget(run);
+        const store = run.config.store ?? false;
+        const format = this.convertResponseFormat(request, budget);
+        const functions = this.convertTools(request, budget) ?? [];
+        const definitions = request.tools ?? [];
+        // Deferred tools load through hosted tool search
+        const search = definitions.some(tool => tool.defer) ? [{ type: 'tool_search' }] : [];
+        const tools = [
+            ...definitions.map((tool, i) => {
+                const shared = { name: tool.name, description: tool.description, defer_loading: tool.defer, async: tool.async };
+                return tool.format
+                    ? { type: 'custom', ...shared, format: tool.format }
+                    : { type: 'function', ...shared, parameters: functions[i].function.parameters ?? null, strict: functions[i].function.strict ?? false };
+            }),
+            ...search,
+            ...(request.hostedTools ?? []).map(tool => toHostedTool(tool, this.name)),
+        ];
+        const kind = (name) => definitions.find(tool => tool.name === name)?.format ? 'custom' : 'function';
+        const choice = request.toolChoice;
+        const reason = request.reason;
+        return {
+            model: run.model.id,
+            input: await this.convertResponsesInput(request, run.config),
+            tools: tools.length ? tools : undefined,
+            tool_choice: !tools.length ? undefined
+                : typeof choice !== 'object' ? choice
+                    : 'tool' in choice ? { type: kind(choice.tool), name: choice.tool }
+                        : { type: 'allowed_tools', mode: choice.required ? 'required' : 'auto', tools: choice.allowed.map(name => ({ type: kind(name), name })) },
+            parallel_tool_calls: tools.length ? !request.toolsOneAtATime : undefined,
+            text: {
+                // The Responses API treats an unflagged json_schema as strict, so a non-strict one says so
+                format: format?.type === 'json_schema'
+                    ? { type: 'json_schema', ...format.json_schema, schema: format.json_schema.schema ?? {}, strict: format.json_schema.strict ?? false }
+                    : format,
+                verbosity: request.verbosity,
+            },
+            reasoning: reason && {
+                effort: reason.effort && clampReasoningEffort(reason.effort, run.modelInfo?.reasoningEfforts),
+                summary: reason.summary,
+                mode: reason.mode,
+                context: reason.context,
+            },
+            include: store ? undefined : ['reasoning.encrypted_content'],
+            max_output_tokens: request.maxTokens,
+            temperature: request.temperature,
+            top_p: request.topP,
+            metadata: request.metadata,
+            service_tier: request.serviceTier,
+            moderation: request.moderate ? { model: MODERATION_MODEL } : undefined,
+            prompt_cache_key: request.cacheKey,
+            safety_identifier: request.userKey,
+            store,
             ...request.extra,
-            stream: false,
         };
-        // Apply provider-specific customizations
-        this.augmentImageGenerateRequest?.(params, request, effectiveConfig);
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.imageEdit?.beforeRequest?.(request, params, ctx);
-        const client = this.createClient(effectiveConfig);
-        let response;
-        try {
-            response = await retry(async (signal) => {
-                return await client.images.edit(params, { signal });
-            });
+    }
+    /**
+     * Map a Chat Completions result to a @aeye response.
+     */
+    chatResponse(completion, run, audioFormat) {
+        const { message, finish_reason } = completion.choices[0];
+        const toolCalls = message.tool_calls?.flatMap((tc) => tc.type === 'function'
+            ? [{ id: tc.id, name: tc.function.name, arguments: tc.function.arguments }]
+            : []);
+        const citations = message.annotations?.map(note => toCitation(note.url_citation));
+        return {
+            content: message.content || '',
+            toolCalls,
+            finishReason: toolCalls?.length ? 'tool_calls' : finish_reason === 'function_call' /* deprecated */ ? 'stop' : finish_reason,
+            refusal: message.refusal ?? (finish_reason === 'content_filter' ? message.content ?? undefined : undefined),
+            citations: citations?.length ? citations : undefined,
+            audio: message.audio ? { id: message.audio.id, data: message.audio.data, transcript: message.audio.transcript, format: audioFormat } : undefined,
+            moderation: completion.moderation ? toModeration(completion.moderation) : undefined,
+            serviceTier: toServiceTier(completion.service_tier),
+            model: run.model,
+            usage: completion.usage ? chatUsage(completion.usage) : undefined,
+        };
+    }
+    /**
+     * Turn a Chat Completions stream into chunks.
+     *
+     * Tool calls are finalized only on positive evidence they're done: a
+     * finish reason on the chunk (the whole response is done), or a higher
+     * tool-call index (tool calls arrive in index order). Providers interleave
+     * usage-only and keep-alive chunks, so "not updated this chunk" is not
+     * evidence. Anything unfinished when the stream completes is finalized
+     * then; a stream that fails leaves its calls unfinished.
+     */
+    async *chatChunks(stream, request, config) {
+        const toolCalls = new Map();
+        let maxIndexSeen = -1;
+        const audioFormat = outputAudioFormat(request, true);
+        // A tool call's own finished chunk, also naming it if it never was
+        const finished = (toolCall) => {
+            const named = toolCall.named;
+            toolCall.finished = toolCall.named = true;
+            return named ? { toolCall } : { toolCall, toolCallNamed: toolCall, toolCallArguments: toolCall };
+        };
+        for await (const raw of stream) {
+            const choice = raw?.choices[0];
+            const delta = choice?.delta;
+            const finish = choice?.finish_reason;
+            // OpenAI streams `finish_reason: null` on every intermediate chunk
+            const chunk = {
+                content: delta?.content || undefined,
+                finishReason: finish === 'function_call' /* deprecated */ ? 'stop' : finish ?? undefined,
+                refusal: delta?.refusal ?? undefined,
+                audio: delta?.audio && { id: delta.audio.id, data: delta.audio.data, transcript: delta.audio.transcript, format: audioFormat },
+                moderation: raw.moderation ? toModeration(raw.moderation) : undefined,
+                serviceTier: toServiceTier(raw.service_tier),
+                usage: raw.usage ? chatUsage(raw.usage) : undefined,
+            };
+            for (const tc of delta?.tool_calls ?? []) {
+                const toolCall = toolCalls.get(tc.index) ?? { id: '', name: '', arguments: '', named: false, finished: false, index: tc.index };
+                toolCalls.set(tc.index, toolCall);
+                toolCall.id = tc.id || toolCall.id;
+                toolCall.name = tc.function?.name || toolCall.name;
+                toolCall.arguments += tc.function?.arguments ?? '';
+                maxIndexSeen = Math.max(maxIndexSeen, tc.index);
+                if (toolCall.arguments) {
+                    if (toolCall.named) {
+                        chunk.toolCallArguments = toolCall;
+                    }
+                    else {
+                        chunk.toolCallNamed = toolCall;
+                        toolCall.named = true;
+                    }
+                }
+            }
+            this.augmentChatChunk(raw, chunk, config);
+            yield chunk;
+            for (const toolCall of toolCalls.values()) {
+                if (!toolCall.finished && (chunk.finishReason !== undefined || toolCall.index < maxIndexSeen)) {
+                    yield finished(toolCall);
+                }
+            }
         }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during image editing', details?.contextWindow, e);
+        for (const toolCall of toolCalls.values()) {
+            if (!toolCall.finished) {
+                yield finished(toolCall);
             }
-            else {
-                await effectiveConfig.hooks?.imageEdit?.onError?.(request, params, e, ctx);
+        }
+    }
+    /**
+     * Run a chat request through Chat Completions.
+     */
+    async complete(request, run) {
+        const params = { ...await this.buildChatParams(request, run, false), stream: false };
+        this.augmentChatRequest(params, request, run.config);
+        const sent = await this.sendChat('chat', run, request, params, async (signal) => {
+            const completion = await run.client.chat.completions.create(params, { signal, headers: this.chatHeaders(params) });
+            if (!completion.choices?.[0]) {
+                throw new ProviderError(this.name, 'No choices in response');
             }
-            throw e;
+            return completion;
+        });
+        if ('overflow' in sent) {
+            return sent.overflow;
         }
-        const result = {
-            images: (response.data || []).map((img) => ({
-                url: img.url || undefined,
-                b64_json: img.b64_json || undefined,
-                revisedPrompt: img.revised_prompt || undefined,
-            })),
-            model,
-            usage: response.usage ? convertOpenAIUsage(response.usage) : undefined,
-        };
-        // Call post-request hook with params
-        await effectiveConfig.hooks?.imageEdit?.afterRequest?.(request, params, result, ctx);
-        return result;
-    };
+        const response = this.chatResponse(sent.result, run, outputAudioFormat(request, false));
+        this.augmentChatResponse(sent.result, response, run.config);
+        return this.finish('chat', run, request, params, response);
+    }
     /**
-     * Edit images with streaming progress updates.
-     *
-     * Note: OpenAI's API doesn't natively support streaming image editing,
-     * so this implementation returns the result with progress indicators.
-     *
-     * @param request Image edit request parameters
-     * @param ctx Context object (not used)
-     * @param config Optional configuration override
-     * @returns Async generator yielding progress chunks
-     * @throws {ProviderError} If editing fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * Stream a chat request through Chat Completions.
      */
-    editImageStream = async function* (request, ctx, config) {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry, signal } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'edit image stream', effectiveConfig.defaultModels?.imageEdit || 'gpt-image-1');
-        const image = await toFile(request.image);
-        const mask = request.mask ? await toFile(request.mask) : undefined;
-        const imageStreams = Math.max(1, Math.min(3, request.streamCount ?? 2));
-        const baseParams = this.getEditParameters(request, model.id);
+    async *completeStream(request, run) {
         const params = {
-            ...baseParams,
-            image,
-            mask,
-            user: request.userIdentifier,
-            partial_images: imageStreams,
-            ...request.extra,
+            ...await this.buildChatParams(request, run, true),
             stream: true,
+            stream_options: { include_usage: true },
         };
-        this.augmentImageEditRequest?.(params, request, effectiveConfig);
-        const client = this.createClient(effectiveConfig);
-        let response;
-        try {
-            response = await retry(async (signal) => {
-                return await client.images.edit(params, { signal });
-            });
+        this.augmentChatRequest(params, request, run.config);
+        const sent = await this.sendChat('chat', run, request, params, (signal) => run.client.chat.completions.create(params, { signal, headers: this.chatHeaders(params) }));
+        if ('overflow' in sent) {
+            return sent.overflow;
         }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during image editing', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.imageEdit?.onError?.(request, params, e, ctx);
-            }
-            throw e;
+        return yield* this.relay('chat', run, request, params, this.chatChunks(sent.result, request, run.config));
+    }
+    /**
+     * Run a chat request through the Responses API.
+     */
+    async respond(request, run) {
+        const params = { ...await this.buildResponsesParams(request, run), stream: false };
+        const sent = await this.sendChat('responses', run, request, params, (signal) => run.client.responses.create(params, { signal }));
+        if ('overflow' in sent) {
+            return sent.overflow;
+        }
+        const chunks = [...sent.result.output.map(item => outputItemChunk(item, false, this.name)), responseEndChunk(sent.result)];
+        return this.finish('responses', run, request, params, getResponseFromChunks(chunks, run.model));
+    }
+    /**
+     * Stream a chat request through the Responses API.
+     */
+    async *respondStream(request, run) {
+        const params = { ...await this.buildResponsesParams(request, run), stream: true };
+        const sent = await this.sendChat('responses', run, request, params, (signal) => run.client.responses.create(params, { signal }));
+        if ('overflow' in sent) {
+            return sent.overflow;
         }
-        // Yield completion with results
-        let imageCount = 0;
-        for await (const img of response) {
-            if (signal?.aborted) {
+        return yield* this.relay('responses', run, request, params, responseChunks(sent.result, this.name));
+    }
+    /**
+     * Create an executor for chat requests.
+     *
+     * @param config Optional configuration override
+     * @returns Executor function for chat
+     * @throws {ProviderError} If request fails
+     */
+    createExecutor(config) {
+        return async (request, ctx, metadata, signal) => {
+            const run = this.prepare('chat', request, ctx, metadata, config, signal, 'chat');
+            const sent = deliverSchema(request);
+            return this.usesResponses(sent, run.model.id, run.config, run.modelInfo)
+                ? this.respond(sent, run)
+                : this.complete(sent, run);
+        };
+    }
+    /**
+     * Create a streamer for streaming chat requests.
+     *
+     * @param config Optional configuration override
+     * @returns Streamer async generator function
+     * @throws {ProviderError} If request fails
+     */
+    createStreamer(config) {
+        const provider = this;
+        return async function* (request, ctx, metadata, signal) {
+            const run = provider.prepare('streaming chat', request, ctx, metadata, config, signal, 'chat');
+            const sent = deliverSchema(request);
+            return yield* provider.usesResponses(sent, run.model.id, run.config, run.modelInfo)
+                ? provider.respondStream(sent, run)
+                : provider.completeStream(sent, run);
+        };
+    }
+    // ============================================================================
+    // Images
+    // ============================================================================
+    /**
+     * Relay image generation or edit progress, then report the final images
+     * to the after hook.
+     */
+    async *imageProgress(op, run, request, params, events, partials) {
+        const images = [];
+        let received = 0;
+        for await (const event of events) {
+            if (run.signal?.aborted) {
                 throw new Error('Request aborted');
             }
-            const progress = (imageCount + 1) / (imageStreams + 1);
+            const image = { b64_json: event.b64_json };
+            const done = event.type === 'image_generation.completed' || event.type === 'image_edit.completed';
+            if (done) {
+                images.push(image);
+            }
             yield {
-                progress,
-                done: img.type === 'image_edit.completed',
-                image: {
-                    b64_json: img.b64_json || undefined,
-                },
-                model,
+                progress: ++received / ((partials + 1) * (request.n ?? 1)),
+                done,
+                image,
+                model: run.model,
+                usage: done ? imageUsage(event, 1) : undefined,
             };
-            imageCount++;
         }
-    };
+        await this.finish(op, run, request, params, { images, model: run.model });
+    }
     /**
-     * Transcribe audio to text using Whisper models.
-     *
-     * Supports multiple audio formats and optional timestamps.
+     * Generate images.
      *
-     * @param request Transcription request parameters
-     * @param ctx Context object (not used)
+     * @param request Image generation request parameters
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Transcription text and optional metadata
-     * @throws {ProviderError} If transcription fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * @returns Generated images
+     * @throws {ProviderError} If generation fails
      */
-    transcribe = async (request, ctx, config) => {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry, signal } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'transcribe', effectiveConfig.defaultModels?.transcription || 'whisper-1');
-        const file = await toFile(request.audio);
+    generateImage = async (request, ctx, config) => {
+        const run = this.prepare('generate image', request, ctx, undefined, config, undefined, 'imageGenerate');
         const params = {
-            model: model.id,
-            file,
-            language: request.language,
-            prompt: request.prompt,
-            temperature: request.temperature,
-            response_format: request.responseFormat,
-            timestamp_granularities: request.timestampGranularities,
+            ...imageParams(request, run.model.id, run.modelInfo),
+            moderation: request.moderation,
             ...request.extra,
             stream: false,
         };
-        // Apply provider-specific customizations
-        this.augmentTranscriptionRequest?.(params, request, effectiveConfig);
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.transcribe?.beforeRequest?.(request, params, ctx);
-        const client = this.createClient(effectiveConfig);
-        let response;
-        try {
-            response = await retry(async (signal) => {
-                return await client.audio.transcriptions.create(params, { signal });
-            });
-        }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during image editing', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.transcribe?.onError?.(request, params, e, ctx);
-            }
-            throw e;
-        }
-        const result = {
-            text: response.text,
-            model,
-            usage: response.usage?.type === 'tokens' ? convertOpenAIUsage(response.usage) :
-                response.usage?.seconds ? { audio: { seconds: response.usage.seconds } } : undefined,
+        this.augmentImageGenerateRequest?.(params, request, run.config);
+        const result = await this.send('imageGenerate', run, request, params, (signal) => run.client.images.generate(params, { signal }));
+        const images = (result.data ?? []).map(toGeneratedImage);
+        return this.finish('imageGenerate', run, request, params, { images, model: run.model, usage: imageUsage(result, images.length) });
+    };
+    /**
+     * Generate images with streaming partial images.
+     *
+     * @param request Image generation request parameters
+     * @param ctx Context object
+     * @param config Optional configuration override
+     * @returns Async generator yielding progress chunks
+     * @throws {ProviderError} If generation fails
+     */
+    generateImageStream = async function* (request, ctx, config) {
+        const run = this.prepare('generate image stream', request, ctx, undefined, config, undefined, 'imageGenerate');
+        const partials = partialImages(request);
+        const params = {
+            ...imageParams(request, run.model.id, run.modelInfo),
+            moderation: request.moderation,
+            partial_images: partials,
+            ...request.extra,
+            stream: true,
         };
-        // Call post-request hook with params
-        await effectiveConfig.hooks?.transcribe?.afterRequest?.(request, params, result, ctx);
-        return result;
+        this.augmentImageGenerateRequest?.(params, request, run.config);
+        const events = await this.send('imageGenerate', run, request, params, (signal) => run.client.images.generate(params, { signal }));
+        yield* this.imageProgress('imageGenerate', run, request, params, events, partials);
     };
     /**
-     * Transcribe audio with streaming progress updates.
+     * Image edit parameters shared by the streaming and non-streaming paths.
+     */
+    async editParams(request, run) {
+        return {
+            ...imageParams(request, run.model.id, run.modelInfo),
+            image: await Promise.all([request.image, ...request.references ?? []].map((image) => toFile(image))),
+            mask: request.mask ? await toFile(request.mask) : undefined,
+            input_fidelity: request.inputFidelity,
+            ...request.extra,
+        };
+    }
+    /**
+     * Edit or combine images with a text prompt and an optional mask.
      *
-     * Note: OpenAI's API doesn't natively support streaming transcription,
-     * so this implementation returns the result with progress indicators.
+     * @param request Image edit request parameters
+     * @param ctx Context object
+     * @param config Optional configuration override
+     * @returns Edited images
+     * @throws {ProviderError} If editing fails
+     */
+    editImage = async (request, ctx, config) => {
+        const run = this.prepare('edit image', request, ctx, undefined, config, undefined, 'imageEdit');
+        const params = { ...await this.editParams(request, run), stream: false };
+        this.augmentImageEditRequest?.(params, request, run.config);
+        const result = await this.send('imageEdit', run, request, params, (signal) => run.client.images.edit(params, { signal }));
+        const images = (result.data ?? []).map(toGeneratedImage);
+        return this.finish('imageEdit', run, request, params, { images, model: run.model, usage: imageUsage(result, images.length) });
+    };
+    /**
+     * Edit images with streaming partial images.
      *
-     * @param request Transcription request parameters
-     * @param ctx Context object (not used)
+     * @param request Image edit request parameters
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Async generator yielding transcription chunks
-     * @throws {ProviderError} If transcription fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * @returns Async generator yielding progress chunks
+     * @throws {ProviderError} If editing fails
      */
-    transcribeStream = async function* (request, ctx, config) {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry, signal } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'transcribe stream', effectiveConfig.defaultModels?.transcription || 'whisper-1');
-        const file = await toFile(request.audio);
-        const params = {
-            model: model.id,
-            file,
+    editImageStream = async function* (request, ctx, config) {
+        const run = this.prepare('edit image stream', request, ctx, undefined, config, undefined, 'imageEdit');
+        const partials = partialImages(request);
+        const params = { ...await this.editParams(request, run), partial_images: partials, stream: true };
+        this.augmentImageEditRequest?.(params, request, run.config);
+        const events = await this.send('imageEdit', run, request, params, (signal) => run.client.images.edit(params, { signal }));
+        yield* this.imageProgress('imageEdit', run, request, params, events, partials);
+    };
+    // ============================================================================
+    // Audio
+    // ============================================================================
+    /**
+     * Transcription parameters shared by the streaming and non-streaming
+     * paths. Diarization needs chunking, and known speakers go as data URLs.
+     */
+    async transcriptionParams(request, run) {
+        const speakers = request.knownSpeakers;
+        return {
+            model: run.model.id,
+            file: await toFile(request.audio),
             language: request.language,
             prompt: request.prompt,
             temperature: request.temperature,
             response_format: request.responseFormat,
             timestamp_granularities: request.timestampGranularities,
+            chunking_strategy: request.responseFormat === 'diarized_json' ? 'auto' : undefined,
+            known_speaker_names: speakers?.map((speaker) => speaker.name),
+            known_speaker_references: speakers && await Promise.all(speakers.map((speaker) => toURL(speaker.audio))),
             ...request.extra,
-            stream: true,
         };
-        this.augmentTranscriptionRequest?.(params, request, effectiveConfig);
-        await effectiveConfig.hooks?.transcribe?.beforeRequest?.(request, params, ctx);
-        const client = this.createClient(effectiveConfig);
-        let response;
-        try {
-            response = await retry(async (signal) => {
-                return await client.audio.transcriptions.create(params, { signal });
+    }
+    /**
+     * Transcribe audio to text, with timed and speaker-labeled segments when
+     * the response format provides them.
+     *
+     * @param request Transcription request parameters
+     * @param ctx Context object
+     * @param config Optional configuration override
+     * @returns Transcription text and segments
+     * @throws {ProviderError} If transcription fails
+     */
+    transcribe = async (request, ctx, config) => {
+        const run = this.prepare('transcribe', request, ctx, undefined, config, undefined, 'transcription');
+        const params = { ...await this.transcriptionParams(request, run), stream: false };
+        this.augmentTranscriptionRequest?.(params, request, run.config);
+        // Text, SRT, and VTT formats come back as a bare string
+        const result = await this.send('transcribe', run, request, params, (signal) => run.client.audio.transcriptions.create(params, { signal }));
+        return this.finish('transcribe', run, request, params, typeof result === 'string'
+            ? { text: result, model: run.model }
+            : {
+                text: result.text,
+                segments: 'segments' in result ? result.segments?.map(toSegment) : undefined,
+                model: run.model,
+                usage: result.usage && transcriptionUsage(result.usage),
             });
-        }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during transcription', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.transcribe?.onError?.(request, params, e, ctx);
-            }
-            throw e;
-        }
-        for await (const chunk of response) {
-            if (signal?.aborted) {
+    };
+    /**
+     * Transcribe audio with streaming text and segments.
+     *
+     * @param request Transcription request parameters
+     * @param ctx Context object
+     * @param config Optional configuration override
+     * @returns Async generator yielding transcription chunks
+     * @throws {ProviderError} If transcription fails
+     */
+    transcribeStream = async function* (request, ctx, config) {
+        const run = this.prepare('transcribe stream', request, ctx, undefined, config, undefined, 'transcription');
+        const params = { ...await this.transcriptionParams(request, run), stream: true };
+        this.augmentTranscriptionRequest?.(params, request, run.config);
+        const events = await this.send('transcribe', run, request, params, (signal) => run.client.audio.transcriptions.create(params, { signal }));
+        for await (const event of events) {
+            if (run.signal?.aborted) {
                 throw new Error('Request aborted');
             }
-            switch (chunk.type) {
+            switch (event.type) {
                 case 'transcript.text.delta':
-                    yield {
-                        delta: chunk.delta,
-                    };
+                    yield { delta: event.delta };
                     break;
                 case 'transcript.text.segment':
-                    yield {
-                        segment: {
-                            start: chunk.start,
-                            end: chunk.end,
-                            speaker: chunk.speaker,
-                            text: chunk.text,
-                            id: chunk.id,
-                        },
-                    };
+                    yield { segment: toSegment(event) };
                     break;
                 case 'transcript.text.done':
-                    yield {
-                        text: chunk.text,
-                        usage: chunk.usage ? convertOpenAIUsage(chunk.usage) : undefined,
-                        model,
-                    };
+                    yield { text: event.text, usage: event.usage && transcriptionUsage(event.usage), model: run.model };
                     break;
             }
         }
     };
     /**
-     * Generate speech from text using TTS models.
-     *
-     * Supports multiple voices and audio formats.
+     * Generate speech from text.
      *
      * @param request Speech synthesis request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Audio buffer and content type
+     * @returns Audio stream and its format
      * @throws {ProviderError} If speech generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     speech = async (request, ctx, config) => {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry, signal } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'speech', effectiveConfig.defaultModels?.speech || 'tts-1');
-        const { text: input, instructions, speed } = request;
-        const voiceDefault = 'alloy';
-        const voiceValid = ['alloy', 'ash', 'ballad', 'coral', 'echo', 'sage', 'shimmer', 'verse', 'marin', 'cedar'];
-        const voiceRequest = request.voice || voiceDefault;
-        const voice = voiceValid.includes(voiceRequest) ? voiceRequest : voiceDefault;
-        const responseFormat = request.responseFormat || 'opus';
+        const run = this.prepare('speech', request, ctx, undefined, config, undefined, 'speech');
         const params = {
-            model: model.id,
-            input,
-            instructions,
-            voice,
-            speed,
-            response_format: responseFormat,
+            model: run.model.id,
+            input: request.text,
+            instructions: request.instructions,
+            voice: request.voice ?? 'alloy',
+            speed: request.speed,
+            response_format: request.responseFormat ?? 'opus',
             ...request.extra,
         };
-        // Apply provider-specific customizations
-        this.augmentSpeechRequest?.(params, request, effectiveConfig);
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.speech?.beforeRequest?.(request, params, ctx);
-        const client = this.createClient(effectiveConfig);
-        let response;
-        try {
-            response = await retry(async (signal) => {
-                return await client.audio.speech.create(params, { signal });
-            });
+        this.augmentSpeechRequest?.(params, request, run.config);
+        const result = await this.send('speech', run, request, params, (signal) => run.client.audio.speech.create(params, { signal }));
+        if (!result.body) {
+            throw new ProviderError(this.name, 'Speech response had no audio');
         }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during speech generation', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.speech?.onError?.(request, params, e, ctx);
-            }
-            throw e;
-        }
-        const result = {
-            model,
-            audio: response.body,
-            responseFormat,
-        };
-        // Call post-request hook with params
-        await effectiveConfig.hooks?.speech?.afterRequest?.(request, params, result, ctx);
-        return result;
+        return this.finish('speech', run, request, params, { model: run.model, audio: result.body, responseFormat: params.response_format });
     };
     /**
      * Generate text embeddings for semantic search and similarity.
      *
-     * Supports text-embedding-3-small, text-embedding-3-large, and ada-002 models.
-     *
      * @param request Embedding request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
      * @returns Array of embeddings with usage information
      * @throws {ProviderError} If embedding generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     embed = async (request, ctx, config) => {
-        const effectiveConfig = { ...this.config, ...config };
-        const { model, retry } = this.getRequestData(request, undefined, ctx, effectiveConfig, 'embed', effectiveConfig.defaultModels?.embedding || 'text-embedding-3-small');
+        const run = this.prepare('embed', request, ctx, undefined, config, undefined, 'embedding');
         const params = {
-            model: model.id,
+            model: run.model.id,
             input: request.texts,
             dimensions: request.dimensions,
             encoding_format: request.encodingFormat,
             user: request.userIdentifier,
             ...request.extra,
         };
-        // Apply provider-specific customizations
-        this.augmentEmbeddingRequest?.(params, request, effectiveConfig);
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.embed?.beforeRequest?.(request, params, ctx);
-        const client = this.createClient(effectiveConfig);
-        let response;
-        try {
-            response = await retry(async (signal) => {
-                return await client.embeddings.create(params, { signal });
-            });
-        }
-        catch (e) {
-            if (isContextWindowError(e)) {
-                const details = parseContextWindowError(e);
-                throw new ContextWindowError(this.name, 'Context window exceeded during embedding generation', details?.contextWindow, e);
-            }
-            else {
-                await effectiveConfig.hooks?.embed?.onError?.(request, params, e, ctx);
-            }
-            throw e;
-        }
-        const result = {
-            embeddings: response.data.map((item) => ({
-                embedding: item.embedding,
-                index: item.index,
-            })),
-            model,
-            usage: response.usage
-                ? {
-                    embeddings: {
-                        count: response.data.length,
-                        tokens: response.usage.prompt_tokens
-                    }
-                }
-                : undefined,
-        };
-        // Call post-request hook with params
-        await effectiveConfig.hooks?.embed?.afterRequest?.(request, params, result, ctx);
-        return result;
+        this.augmentEmbeddingRequest?.(params, request, run.config);
+        const result = await this.send('embed', run, request, params, (signal) => run.client.embeddings.create(params, { signal }));
+        return this.finish('embed', run, request, params, {
+            embeddings: result.data.map(({ embedding, index }) => ({ embedding, index })),
+            model: run.model,
+            usage: { embeddings: { count: result.data.length, tokens: result.usage.prompt_tokens } },
+        });
     };
+    // ============================================================================
+    // Decisions
+    // ============================================================================
     /**
-     * Analyze images using vision-capable models.
+     * Typed answers about an input. A conversation goes in as Responses input.
      *
-     * This method converts the image analysis request into a chat request
-     * with image content and calls the chat API internally.
-     *
-     * @param request Image analysis request parameters
-     * @param ctx Context object (not used)
+     * @param request Decision request parameters
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Analysis response with text content
-     * @throws {ProviderError} If analysis fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * @returns Answers by question name
      */
-    analyzeImage = async (request, ctx, config) => {
-        const effectiveConfig = { ...this.config, ...config };
-        // Convert ImageAnalyzeRequest to chat Request
-        const chatRequest = {
-            messages: [
-                {
-                    role: 'user',
-                    content: [
-                        { type: 'text', content: request.prompt },
-                        ...request.images.map((image) => ({
-                            type: 'image',
-                            content: image,
-                        })),
-                    ],
-                },
-            ],
-            temperature: request.temperature,
-            maxTokens: request.maxTokens,
-        };
-        // Construct the params that would be sent to OpenAI
-        const { model } = this.getRequestData(chatRequest, undefined, ctx, effectiveConfig, 'analyze image', effectiveConfig.defaultModels?.imageAnalyze || 'gpt-4-vision-preview');
-        const messages = await this.convertMessages(chatRequest, effectiveConfig);
+    decide = async (request, ctx, config) => {
+        const run = this.prepare('decide', request, ctx, undefined, config, undefined, 'decision');
         const params = {
-            model: model.id,
-            messages,
-            temperature: chatRequest.temperature,
-            max_completion_tokens: chatRequest.maxTokens,
+            model: run.model.id,
+            input: typeof request.input === 'string' ? request.input : await this.convertResponsesInput({ messages: request.input }, run.config),
+            questions: Object.entries(request.questions).map(([name, question]) => toDecisionQuestion(name, question)),
+            ...request.extra,
         };
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.imageAnalyze?.beforeRequest?.(request, params, ctx);
-        const executor = this.createExecutor(effectiveConfig);
-        let response;
-        try {
-            // Use the chat executor to analyze the images (this will also call chat hooks)
-            response = await executor(chatRequest, ctx, {}, undefined);
-            // Call post-request hook with params
-            await effectiveConfig.hooks?.imageAnalyze?.afterRequest?.(request, params, response, ctx);
-        }
-        catch (e) {
-            await effectiveConfig.hooks?.imageAnalyze?.onError?.(request, params, e, ctx);
-            throw e;
-        }
-        return response;
+        const result = await this.send('decide', run, request, params, (signal) => run.client.post('/decisions', { body: params, signal }));
+        return this.finish('decide', run, request, params, {
+            answers: Object.fromEntries(result.answers.map(answer => [answer.name, toDecisionAnswer(answer)])),
+            model: run.model,
+            usage: responsesUsage(result.usage),
+        });
     };
+    // ============================================================================
+    // Batch
+    // ============================================================================
     /**
-     * Analyze images with streaming response.
+     * Run chat requests as one batch on one model. Each request becomes the
+     * same call a direct request would make, through Responses when any of
+     * them needs it.
      *
-     * This method converts the image analysis request into a chat request
-     * with image content and calls the streaming chat API internally.
+     * @param requests Chat requests, whose results come back in this order
+     * @param ctx Context object
+     * @param config Optional configuration override
+     * @returns The submitted batch
+     */
+    submitBatch = async (requests, ctx, config) => {
+        const [first] = requests;
+        if (!first) {
+            throw new ProviderError(this.name, 'A batch needs at least one request');
+        }
+        const run = this.prepare('submit batch', first, ctx, undefined, config, undefined, 'chat');
+        const responses = requests.some(request => this.usesResponses(request, run.model.id, run.config, run.modelInfo));
+        const lines = await Promise.all(requests.map(async (request, index) => {
+            if (responses) {
+                return { custom_id: String(index), body: await this.buildResponsesParams(request, run) };
+            }
+            const params = await this.buildChatParams(request, run, false);
+            this.augmentChatRequest(params, request, run.config);
+            return { custom_id: String(index), body: params };
+        }));
+        return this.createBatch({ endpoint: responses ? '/v1/responses' : '/v1/chat/completions', model: run.model.id, lines }, run);
+    };
+    /**
+     * A batch as it stands now, with its results once it completes.
      *
-     * @param request Image analysis request parameters
-     * @param ctx Context object (not used)
+     * @param job The batch from submitBatch
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Async generator yielding response chunks
-     * @throws {ProviderError} If analysis fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
-    analyzeImageStream = async function* (request, ctx, config) {
-        const effectiveConfig = { ...this.config, ...config };
-        // Convert ImageAnalyzeRequest to chat Request
-        const chatRequest = {
-            messages: [
-                {
+    getBatch = (job, ctx, config) => this.retrieveBatch(job, this.prepare('get batch', { model: job.model }, ctx, undefined, config, undefined, 'chat'));
+    /**
+     * Start a batch: OpenAI takes the requests as an uploaded JSONL file.
+     *
+     * @param batch The requests
+     * @param run The resolved call
+     */
+    async createBatch(batch, run) {
+        const jsonl = batch.lines.map(line => JSON.stringify({ ...line, method: 'POST', url: batch.endpoint })).join('\n');
+        const file = await toFile(new TextEncoder().encode(jsonl), 'application/jsonl', 'batch.jsonl');
+        const input = await run.retry((signal) => run.client.files.create({ file, purpose: 'batch' }, { signal }));
+        const created = await run.retry((signal) => run.client.batches.create({ input_file_id: input.id, endpoint: batch.endpoint, completion_window: '24h' }, { signal }));
+        return this.batchJob(created, run);
+    }
+    /**
+     * Read a batch: OpenAI writes results, and failed requests, to files.
+     *
+     * @param job The batch
+     * @param run The resolved call
+     */
+    async retrieveBatch(job, run) {
+        const batch = await run.retry((signal) => run.client.batches.retrieve(job.id, { signal }));
+        if (batch.status !== 'completed') {
+            return this.batchJob(batch, run);
+        }
+        const files = [batch.output_file_id, batch.error_file_id].filter((id) => !!id);
+        const lines = await Promise.all(files.map(async (id) => {
+            const content = await run.retry(async (signal) => (await run.client.files.content(id, { signal })).text());
+            return content.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+        }));
+        return { ...this.batchJob(batch, run), results: this.batchResults(lines.flat(), batch.request_counts?.total ?? 0, run) };
+    }
+    /**
+     * A batch as @aeye reports it.
+     */
+    batchJob(batch, run) {
+        return {
+            id: batch.id,
+            provider: this.name,
+            model: run.model.id,
+            status: batch.status,
+            counts: batch.request_counts,
+            error: batch.errors?.data?.[0]?.message,
+        };
+    }
+    /**
+     * Results in request order, each mapped as its direct call would be.
+     *
+     * @param lines The results, in any order
+     * @param total How many requests the batch had
+     * @param run The resolved call
+     */
+    batchResults(lines, total, run) {
+        const results = Array.from({ length: Math.max(total, lines.length) }, () => ({ error: 'No result' }));
+        for (const line of lines) {
+            const body = line.response?.body;
+            results[Number(line.custom_id)] = body && 'object' in body && !line.error
+                ? { response: this.batchResponse(body, run) }
+                : { error: line.error?.message ?? (body && !('object' in body) ? body.error.message : `Request failed with status ${line.response?.status_code}`) };
+        }
+        return results;
+    }
+    /**
+     * One batch result body as a @aeye response.
+     */
+    batchResponse(body, run) {
+        if (body.object === 'response') {
+            return getResponseFromChunks([...body.output.map(item => outputItemChunk(item, false, this.name)), responseEndChunk(body)], run.model);
+        }
+        const response = this.chatResponse(body, run);
+        this.augmentChatResponse(body, response, run.config);
+        return response;
+    }
+    // ============================================================================
+    // Image Analysis
+    // ============================================================================
+    /**
+     * An image analysis request as a chat request, and the metadata naming
+     * the configured analysis model as the fallback.
+     */
+    analysisChat(request, config) {
+        const chat = {
+            model: request.model,
+            messages: [{
                     role: 'user',
                     content: [
                         { type: 'text', content: request.prompt },
-                        ...request.images.map((image) => ({
-                            type: 'image',
-                            content: image,
-                        })),
+                        ...request.images.map((image) => ({ type: 'image', content: image })),
                     ],
-                },
-            ],
+                }],
             temperature: request.temperature,
             maxTokens: request.maxTokens,
         };
-        // Construct the params that would be sent to OpenAI
-        const { model } = this.getRequestData(chatRequest, undefined, ctx, effectiveConfig, 'analyze image stream', effectiveConfig.defaultModels?.imageAnalyze || 'gpt-4-vision-preview');
-        const messages = await this.convertMessages(chatRequest, effectiveConfig);
-        const params = {
-            model: model.id,
-            messages,
-            temperature: chatRequest.temperature,
-            max_completion_tokens: chatRequest.maxTokens,
-            stream: true,
-        };
-        // Call pre-request hook with params
-        await effectiveConfig.hooks?.imageAnalyze?.beforeRequest?.(request, params, ctx);
-        const streamer = this.createStreamer(effectiveConfig);
-        try {
-            // Use the chat streamer to analyze the images (this will also call chat hooks)
-            const stream = streamer(chatRequest, ctx, { model: request.model }, undefined);
-            // Track accumulated response for post-hook
-            let accumulatedContent = '';
-            let finalUsage = undefined;
-            let finishReason = undefined;
-            const toolCalls = [];
-            try {
-                for await (const chunk of stream) {
-                    if (chunk.content) {
-                        accumulatedContent += chunk.content;
-                    }
-                    if (chunk.usage) {
-                        finalUsage = chunk.usage;
-                    }
-                    if (chunk.finishReason) {
-                        finishReason = chunk.finishReason;
-                    }
-                    if (chunk.toolCall) {
-                        toolCalls.push(chunk.toolCall);
-                    }
-                    yield chunk;
-                }
-            }
-            finally {
-                // Call post-request hook with params
-                const finalResponse = {
-                    content: accumulatedContent,
-                    toolCalls,
-                    finishReason: toolCalls.length ? 'tool_calls' : finishReason || 'stop',
-                    model,
-                    usage: finalUsage,
-                };
-                await effectiveConfig.hooks?.imageAnalyze?.afterRequest?.(request, params, finalResponse, ctx);
-            }
-        }
-        catch (e) {
-            await effectiveConfig.hooks?.imageAnalyze?.onError?.(request, params, e, ctx);
-            throw e;
-        }
+        const model = config?.defaultModels?.imageAnalyze ?? this.config.defaultModels?.imageAnalyze ?? this.defaults.imageAnalyze;
+        return [chat, { model }];
+    }
+    /**
+     * Analyze images with a vision model. Runs as a chat request, reported
+     * through the chat hooks.
+     */
+    analyzeImage = (request, ctx, config) => {
+        const [chat, metadata] = this.analysisChat(request, config);
+        return this.createExecutor(config)(chat, ctx, metadata);
+    };
+    /**
+     * Analyze images with a vision model, streaming the answer. Runs as a
+     * chat request, reported through the chat hooks.
+     */
+    analyzeImageStream = (request, ctx, config) => {
+        const [chat, metadata] = this.analysisChat(request, config);
+        return this.createStreamer(config)(chat, ctx, metadata);
     };
 }
+/**
+ * The encoding of audio a chat request asks for: as requested, or the
+ * default for how it is delivered (audio streams only as PCM).
+ */
+function outputAudioFormat(request, streaming) {
+    return request.modalities?.includes('audio') ? request.audio?.format ?? (streaming ? 'pcm' : 'mp3') : undefined;
+}
+/**
+ * A generated image as returned by the Images API.
+ */
+function toGeneratedImage(image) {
+    return { url: image.url, b64_json: image.b64_json, revisedPrompt: image.revised_prompt };
+}
+/**
+ * A transcription segment from a verbose or diarized transcription, or a
+ * streamed segment event.
+ */
+function toSegment(segment) {
+    return { id: String(segment.id), start: segment.start, end: segment.end, text: segment.text, speaker: segment.speaker };
+}
 //# sourceMappingURL=openai.js.map