@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.2

package/dist/providers/openai-provider.js

@@ -1,7 +1,40 @@
+import { context, trace } from "@opentelemetry/api";
+import { tracedProviderLoop, tracedToolCall, beginProviderRound, providerRoundContext, tracedProviderLlm } from "./loop-tracing.js";
 import OpenAI, { toFile } from "openai";
-import { createLogger } from "@nodetool-ai/config";
-import { BaseProvider } from "./base-provider.js";
+import { createLogger, importHidden } from "@nodetool-ai/config";
+import { BaseProvider, budgetStopItem, resolveTurnBudget, splitToolResultImages } from "./base-provider.js";
+import { openAIContextExceeded } from "./context-exceeded.js";
+import { hashSystemPrompt } from "./provider-session.js";
+import { sniffAudioMime } from "./audio-mime.js";
+/** Extension for each mime `sniffAudioMime` can return; anything else is mp3. */
+const AUDIO_MIME_EXT = {
+    "audio/wav": "wav",
+    "audio/ogg": "ogg",
+    "audio/flac": "flac",
+    "audio/mpeg": "mp3"
+};
+import { extractResponsesImages, extractResponsesText, extractResponsesToolCalls, messagesToResponsesInput, responseToolChoice, responseTools, responseUsage, streamResponsesEvents } from "./responses-api.js";
+import { PROVIDER_IDS, isCallable, isNumber, isRecord, isString } from "@nodetool-ai/protocol";
+import { isProviderMessageEvent, isProviderSessionUpdate, IMAGE_GENERATION_TOOL_NAME, PROVIDER_STOP_ABORTED, WEB_SEARCH_TOOL_NAME } from "./types.js";
+async function loadSharp() {
+    const mod = await importHidden("sharp");
+    if (!mod)
+        throw new Error("sharp requires Node");
+    return "default" in mod ? mod.default : mod;
+}
 const log = createLogger("nodetool.runtime.providers.openai");
+import { snapToGptImage2Size } from "./gpt-image-size.js";
+function openAIImageUsage(response, quality) {
+    return {
+        imageCount: response.data?.length ?? 1,
+        imageQuality: quality ?? undefined,
+        inputTokens: response.usage?.input_tokens,
+        outputTokens: response.usage?.output_tokens,
+        inputTextTokens: response.usage?.input_tokens_details?.text_tokens,
+        inputImageTokens: response.usage?.input_tokens_details?.image_tokens,
+        outputImageTokens: response.usage?.output_tokens_details?.image_tokens
+    };
+}
 function asUint8Array(data) {
     if (data instanceof Uint8Array) {
         return data;
@@ -9,7 +42,7 @@ function asUint8Array(data) {
     if (Array.isArray(data) && data.every((v) => Number.isInteger(v))) {
         return new Uint8Array(data);
     }
-    if (typeof data === "string") {
+    if (isString(data)) {
         return Uint8Array.from(Buffer.from(data, "base64"));
     }
     if (data instanceof ArrayBuffer) {
@@ -18,8 +51,8 @@ function asUint8Array(data) {
     throw new Error("Unsupported binary payload format");
 }
 function toInt16Samples(bytes) {
-    const aligned = bytes.length % 2 === 0 ? bytes : bytes.slice(0, bytes.length - 1);
-    return new Int16Array(aligned.buffer, aligned.byteOffset, aligned.byteLength / 2);
+    const copy = Uint8Array.from(bytes);
+    return new Int16Array(copy.buffer);
 }
 function parseDataUri(uri) {
     const idx = uri.indexOf(",");
@@ -43,9 +76,15 @@ function makeDataUri(mime, data) {
     return `data:${mime};base64,${b64}`;
 }
 /**
- * Custom JSON replacer that handles objects with toJSON() methods
- * and other non-serializable types. Mirrors Python's _default_serializer.
+ * OpenAI's Chat Completions `input_audio` block accepts only `"wav"` or `"mp3"`
+ * as its `format` — a bare token, not a mime type. Resolve it from the declared
+ * mime when present, otherwise sniff the leading magic bytes. Anything that
+ * isn't WAV is sent as `"mp3"` (the only other format OpenAI decodes).
  */
+function openAiAudioFormat(mime, bytes) {
+    const resolved = mime && mime !== "application/octet-stream" ? mime : sniffAudioMime(bytes);
+    return /wave?$/i.test(resolved) ? "wav" : "mp3";
+}
 function defaultSerializer(_key, value) {
     if (value === null || value === undefined)
         return value;
@@ -59,11 +98,118 @@ function defaultSerializer(_key, value) {
         return [...value];
     if (typeof value === "object" &&
         "toJSON" in value &&
-        typeof value.toJSON === "function") {
+        isCallable(value.toJSON)) {
+        // SAFETY: `toJSON` is the JSON.stringify protocol hook — it exists on the
+        // value and, by that contract, produces a JSON-representable result.
         return value.toJSON();
     }
     return value;
 }
+const RESPONSE_WEB_SEARCH_TOOL = {
+    type: "web_search"
+};
+const RESPONSE_IMAGE_GENERATION_TOOL = {
+    type: "image_generation"
+};
+const RESPONSE_HOSTED_TOOL_CHOICES = {
+    [WEB_SEARCH_TOOL_NAME]: "web_search",
+    [IMAGE_GENERATION_TOOL_NAME]: "image_generation"
+};
+const SORA_VIDEO_DURATIONS = [4, 8, 12, 16, 20];
+export const OPENAI_FALLBACK_MODELS = [
+    "gpt-6-astra",
+    "gpt-5.6",
+    "gpt-5.6-sol",
+    "gpt-5.6-terra",
+    "gpt-5.6-luna",
+    "gpt-5.5",
+    "gpt-5.5-pro",
+    "gpt-5.4",
+    "gpt-5.4-pro",
+    "gpt-5.4-mini",
+    "gpt-5.4-nano",
+    "gpt-5",
+    "gpt-5-mini",
+    "gpt-5-nano"
+].map((id) => ({
+    id,
+    name: id,
+    provider: PROVIDER_IDS.OPENAI
+}));
+/**
+ * OpenAI language models we support: the gpt-5 family, served through the
+ * Responses API. Everything before gpt-5 (gpt-4o, gpt-4.1, the o-series, …) is
+ * retired. OpenAI-compatible subclasses set their own provider id and never
+ * reach this predicate, so they keep their own model support on Chat Completions.
+ */
+function isOpenAIResponsesModel(model) {
+    const id = model.toLowerCase();
+    // Audio / realtime / transcription variants stay on Chat Completions — the
+    // Responses API doesn't serve the `modalities: ["text","audio"]` path.
+    if (/audio|realtime|transcribe/.test(id))
+        return false;
+    return /^gpt-5(?:[.-]|$)/.test(id);
+}
+/**
+ * Decode a `GET /v1/models` body into the language models it announces.
+ *
+ * Split out of {@link OpenAIProvider.getAvailableLanguageModels} so the live
+ * contract probe and its raw-response fixtures parse a real production
+ * response the same way the provider does. Strict on the envelope: a body
+ * without a `data` array throws, and the caller decides what to fall back to.
+ */
+export function decodeOpenAIModelList(payload, options) {
+    if (!isRecord(payload)) {
+        throw new Error("OpenAI model list is not an object");
+    }
+    const rows = payload.data;
+    if (!Array.isArray(rows)) {
+        throw new Error("OpenAI model list has no `data` array");
+    }
+    return rows
+        .filter(isRecord)
+        .filter((row) => isString(row.id) && row.id.length > 0)
+        .filter((row) => !options.onlyResponsesModels || isOpenAIResponsesModel(row.id))
+        .map((row) => ({
+        id: row.id,
+        name: row.id,
+        provider: options.provider
+    }));
+}
+function responsesSystemPrompt(messages) {
+    return messages
+        .filter((m) => m.role === "system")
+        .map((m) => (isString(m.content) ? m.content : ""))
+        .filter(Boolean)
+        .join("\n\n");
+}
+/**
+ * A native image_generation result surfaced by the stream parser as an image
+ * chunk. Returns the content block to attach to the assistant message, or
+ * null for any other stream item. The multi-megabyte base64 blob must be
+ * absorbed here, never yielded onward as a chunk.
+ */
+function imageContentFromChunk(item) {
+    if (!isRecord(item) ||
+        item.type !== "chunk" ||
+        item.content_type !== "image" ||
+        !isString(item.content)) {
+        return null;
+    }
+    const metadata = isRecord(item.content_metadata) ? item.content_metadata : {};
+    const mimeType = isString(metadata.mimeType)
+        ? metadata.mimeType
+        : "image/png";
+    return { type: "image_url", image: { data: item.content, mimeType } };
+}
+/** Text block (when non-empty) followed by generated-image blocks. */
+function assistantContentWithImages(text, images) {
+    const blocks = [];
+    if (text)
+        blocks.push({ type: "text", text });
+    blocks.push(...images);
+    return blocks;
+}
 export class OpenAIProvider extends BaseProvider {
     static requiredSecrets() {
         return ["OPENAI_API_KEY"];
@@ -73,7 +219,7 @@ export class OpenAIProvider extends BaseProvider {
     _clientFactory;
     _fetch;
     constructor(secrets, options = {}) {
-        super("openai");
+        super(options.providerId ?? "openai");
         const apiKey = secrets.OPENAI_API_KEY;
         if (!apiKey) {
             throw new Error("OPENAI_API_KEY is required");
@@ -93,46 +239,155 @@ export class OpenAIProvider extends BaseProvider {
         }
         return this._client;
     }
+    /**
+     * True when this instance should serve `model` through the Responses API.
+     * Gated on the real `openai` provider so OpenAI-compatible subclasses (which
+     * pass their own provider id) stay on Chat Completions.
+     */
+    usesResponsesApi(model) {
+        return (this.provider === PROVIDER_IDS.OPENAI && isOpenAIResponsesModel(model));
+    }
+    get supportsNativeWebSearch() {
+        return this.provider === PROVIDER_IDS.OPENAI;
+    }
+    get supportsNativeImageGeneration() {
+        return this.provider === PROVIDER_IDS.OPENAI;
+    }
     async hasToolSupport(model) {
+        if (this.usesResponsesApi(model))
+            return true;
         return !(model.startsWith("o1") || model.startsWith("o3"));
     }
+    /**
+     * Whether this instance actually serves OpenAI's own model catalog.
+     *
+     * The media and embedding lists below are hardcoded OpenAI models tagged
+     * `provider: "openai"`. Subclasses inherit OpenAI's *chat dialect*, not its
+     * lineup — a Groq or vLLM instance offering `gpt-image-2` or `whisper-1` is
+     * always wrong, and picking one sends the request to a host that has no such
+     * endpoint. Subclasses that do serve media (Together, MiniMax, GMI, xAI, …)
+     * override these methods with their own catalog; everyone else correctly
+     * reports none.
+     */
+    servesOpenAICatalog() {
+        return this.provider === PROVIDER_IDS.OPENAI;
+    }
+    /**
+     * OpenAI's own media and embedding operations. A subclass serves them only
+     * through {@link servesOpenAICatalog}; one with its own catalog declares its
+     * own list.
+     */
+    declaredCapabilities() {
+        if (!this.servesOpenAICatalog())
+            return [];
+        return [
+            "text_to_image",
+            "image_to_image",
+            "inpainting",
+            "text_to_video",
+            "image_to_video",
+            "text_to_speech",
+            "automatic_speech_recognition",
+            "generate_embedding"
+        ];
+    }
     async getAvailableLanguageModels() {
+        // The `openai` provider only serves the supported (gpt-5+) models; retire
+        // everything older. Subclasses (their own provider id) keep their full list.
+        const isOpenAI = this.provider === PROVIDER_IDS.OPENAI;
         const response = await this._fetch("https://api.openai.com/v1/models", {
             headers: {
                 Authorization: `Bearer ${this.apiKey}`
             }
         });
         if (!response.ok) {
-            return [];
+            return isOpenAI ? OPENAI_FALLBACK_MODELS : [];
         }
-        const payload = (await response.json());
-        const rows = payload.data ?? [];
-        return rows
-            .filter((row) => typeof row.id === "string" && row.id.length > 0)
-            .map((row) => ({
-            id: row.id,
-            name: row.id,
-            provider: "openai"
-        }));
+        let models;
+        try {
+            models = decodeOpenAIModelList(await response.json(), {
+                provider: this.provider,
+                onlyResponsesModels: isOpenAI
+            });
+        }
+        catch {
+            // A body OpenAI's own decoder rejects is the same situation as an
+            // unreachable listing: fall back rather than fail model discovery.
+            return isOpenAI ? OPENAI_FALLBACK_MODELS : [];
+        }
+        if (models.length === 0 && isOpenAI) {
+            return OPENAI_FALLBACK_MODELS;
+        }
+        return models;
     }
     async getAvailableTTSModels() {
+        if (!this.servesOpenAICatalog())
+            return [];
+        const legacyVoices = [
+            "alloy",
+            "ash",
+            "coral",
+            "echo",
+            "fable",
+            "onyx",
+            "nova",
+            "sage",
+            "shimmer"
+        ];
         return [
+            {
+                id: "gpt-4o-mini-tts",
+                name: "GPT-4o Mini TTS (Deprecated)",
+                provider: "openai",
+                voices: [
+                    "alloy",
+                    "ash",
+                    "ballad",
+                    "coral",
+                    "echo",
+                    "fable",
+                    "nova",
+                    "onyx",
+                    "sage",
+                    "shimmer",
+                    "verse",
+                    "marin",
+                    "cedar"
+                ]
+            },
             {
                 id: "tts-1",
                 name: "TTS 1",
                 provider: "openai",
-                voices: ["alloy", "echo", "fable", "onyx", "nova", "shimmer"]
+                voices: legacyVoices
             },
             {
                 id: "tts-1-hd",
                 name: "TTS 1 HD",
                 provider: "openai",
-                voices: ["alloy", "echo", "fable", "onyx", "nova", "shimmer"]
+                voices: legacyVoices
             }
         ];
     }
     async getAvailableASRModels() {
+        if (!this.servesOpenAICatalog())
+            return [];
         return [
+            {
+                id: "gpt-4o-transcribe",
+                name: "GPT-4o Transcribe",
+                provider: "openai"
+            },
+            {
+                id: "gpt-4o-mini-transcribe",
+                name: "GPT-4o Mini Transcribe",
+                provider: "openai"
+            },
+            {
+                id: "gpt-4o-transcribe-diarize",
+                name: "GPT-4o Transcribe Diarize",
+                provider: "openai"
+            },
             {
                 id: "whisper-1",
                 name: "Whisper",
@@ -141,23 +396,45 @@ export class OpenAIProvider extends BaseProvider {
         ];
     }
     async getAvailableVideoModels() {
+        if (!this.servesOpenAICatalog())
+            return [];
         return [
             {
                 id: "sora-2",
                 name: "Sora 2",
                 provider: "openai",
-                supportedTasks: ["text_to_video"]
+                supportedTasks: ["text_to_video", "image_to_video"],
+                durations: [...SORA_VIDEO_DURATIONS],
+                resolutions: ["720p"],
+                aspectRatios: ["16:9", "9:16"]
             },
             {
                 id: "sora-2-pro",
                 name: "Sora 2 Pro",
                 provider: "openai",
-                supportedTasks: ["text_to_video"]
+                supportedTasks: ["text_to_video", "image_to_video"],
+                durations: [...SORA_VIDEO_DURATIONS],
+                resolutions: ["720p", "1024p", "1080p"],
+                aspectRatios: ["16:9", "9:16"]
             }
         ];
     }
     async getAvailableImageModels() {
+        if (!this.servesOpenAICatalog())
+            return [];
         return [
+            {
+                id: "gpt-image-2.5-flare",
+                name: "GPT Image 2.5 Flare",
+                provider: "openai",
+                supportedTasks: ["text_to_image", "image_to_image"]
+            },
+            {
+                id: "gpt-image-2.5-sunburst",
+                name: "GPT Image 2.5 Sunburst",
+                provider: "openai",
+                supportedTasks: ["text_to_image", "image_to_image"]
+            },
             {
                 id: "gpt-image-2",
                 name: "GPT Image 2",
@@ -185,6 +462,8 @@ export class OpenAIProvider extends BaseProvider {
         ];
     }
     async getAvailableEmbeddingModels() {
+        if (!this.servesOpenAICatalog())
+            return [];
         return [
             {
                 id: "text-embedding-3-small",
@@ -206,10 +485,27 @@ export class OpenAIProvider extends BaseProvider {
             }
         ];
     }
-    resolveImageSize(width, height) {
+    /**
+     * gpt-image-2 accepts arbitrary sizes within limits: both edges a multiple of
+     * 16, long edge <= 3840, aspect ratio <= 3:1, and total area between 0.64MP
+     * and 8.3MP. Requested sizes rarely land on that grid (16:9 at 1K is
+     * 1820x1024), so snap to the nearest valid size preserving the aspect ratio
+     * rather than dropping `size` and letting the API default to a square.
+     */
+    static snapToGptImage2Size(width, height) {
+        const size = snapToGptImage2Size(width, height);
+        return size ? `${size[0]}x${size[1]}` : null;
+    }
+    resolveImageSize(width, height, model) {
         if (!width || !height) {
             return null;
         }
+        const usesFlexibleDimensions = model === "gpt-image-2" ||
+            model?.startsWith("gpt-image-2-") === true ||
+            model?.startsWith("gpt-image-2.") === true;
+        if (usesFlexibleDimensions) {
+            return OpenAIProvider.snapToGptImage2Size(width, height);
+        }
         const supported = [
             [1024, 1024],
             [1024, 1536],
@@ -229,16 +525,24 @@ export class OpenAIProvider extends BaseProvider {
             : bestSoFar);
         return `${best[0]}x${best[1]}`;
     }
-    static resolveVideoSize(aspectRatio, resolution) {
+    static resolveVideoSize(aspectRatio, resolution, model) {
         if (!resolution) {
             return null;
         }
-        const supported = [
-            [1280, 720],
-            [1792, 1024],
-            [720, 1280],
-            [1024, 1792]
-        ];
+        const isStandardSora2 = model?.startsWith("sora-2") === true && !model.includes("pro");
+        const supported = isStandardSora2
+            ? [
+                [1280, 720],
+                [720, 1280]
+            ]
+            : [
+                [1280, 720],
+                [1792, 1024],
+                [1920, 1080],
+                [720, 1280],
+                [1024, 1792],
+                [1080, 1920]
+            ];
         const aspect = (aspectRatio ?? "16:9").replaceAll(" ", "");
         const resolutionKey = resolution.toLowerCase();
         const presets = {
@@ -284,16 +588,18 @@ export class OpenAIProvider extends BaseProvider {
         return closest(Math.max(2, Math.round(targetW)), Math.max(2, Math.round(targetH)));
     }
     static secondsFromParams(params) {
+        const durationSeconds = params.durationSeconds;
+        if (durationSeconds != null &&
+            Number.isFinite(durationSeconds) &&
+            durationSeconds > 0) {
+            return SORA_VIDEO_DURATIONS.reduce((duration, candidate) => candidate <= durationSeconds ? candidate : duration, SORA_VIDEO_DURATIONS[0]);
+        }
         const numFrames = params.numFrames;
-        if (!numFrames || numFrames <= 0) {
+        if (!numFrames || !Number.isFinite(numFrames) || numFrames <= 0) {
             return null;
         }
         const estimated = Math.ceil(numFrames / 24);
-        if (estimated < 8)
-            return 4;
-        if (estimated < 12)
-            return 8;
-        return 12;
+        return SORA_VIDEO_DURATIONS.reduce((duration, candidate) => (candidate <= estimated ? candidate : duration), SORA_VIDEO_DURATIONS[0]);
     }
     static snapToValidVideoDimensions(width, height) {
         const supported = [
@@ -369,17 +675,38 @@ export class OpenAIProvider extends BaseProvider {
         }
         if (content.type === "audio") {
             const c = content;
-            const base64 = c.audio.uri
-                ? (await this.uriToBase64(c.audio.uri)).split(",", 2)[1]
-                : Buffer.from(asUint8Array(c.audio.data ?? new Uint8Array())).toString("base64");
+            let bytes;
+            let mime = c.audio.mimeType;
+            if (c.audio.uri) {
+                const parsed = parseDataUri(await this.uriToBase64(c.audio.uri));
+                bytes = parsed.data;
+                mime = mime ?? parsed.mime;
+            }
+            else {
+                bytes = asUint8Array(c.audio.data ?? new Uint8Array());
+            }
             return {
                 type: "input_audio",
                 input_audio: {
-                    format: "mp3",
-                    data: base64
+                    format: openAiAudioFormat(mime, bytes),
+                    data: Buffer.from(bytes).toString("base64")
                 }
             };
         }
+        if (content.type === "video") {
+            // Reached only with the fallback switched off: BaseProvider otherwise
+            // samples the clip into frames before conversion whenever
+            // `supportsVideoInput` is false, and a missing ffmpeg fails there with
+            // its own message. Named for the configured provider, not the wire
+            // format: every
+            // OpenAI-compatible re-host lands here, and reporting "openai" sent a
+            // diagnosis after the wrong provider.
+            throw new Error(`video input is not supported by ${this.provider} — its chat API is ` +
+                `OpenAI-compatible, which has no video content part. Frame sampling ` +
+                `is off (NODETOOL_VIDEO_FRAME_FALLBACK=0); unset it to read the clip ` +
+                `as stills, or use a provider whose chat models read video natively ` +
+                `(gemini).`);
+        }
         const c = content;
         const imageUrl = c.image.uri
             ? await this.uriToBase64(c.image.uri)
@@ -395,7 +722,7 @@ export class OpenAIProvider extends BaseProvider {
                 throw new Error("Tool message requires toolCallId");
             }
             let content = "";
-            if (typeof message.content === "string") {
+            if (isString(message.content)) {
                 content = message.content;
             }
             else if (message.content != null) {
@@ -410,7 +737,7 @@ export class OpenAIProvider extends BaseProvider {
         if (message.role === "system") {
             return {
                 role: "system",
-                content: typeof message.content === "string" ? message.content : ""
+                content: isString(message.content) ? message.content : ""
             };
         }
         if (message.role === "assistant") {
@@ -422,24 +749,30 @@ export class OpenAIProvider extends BaseProvider {
                     arguments: JSON.stringify(tc.args, defaultSerializer)
                 }
             }));
-            if (typeof message.content === "string" || message.content == null) {
-                return {
+            if (isString(message.content) || message.content == null) {
+                const assistant = {
                     role: "assistant",
-                    content: message.content,
-                    ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {})
+                    content: message.content
                 };
+                if (toolCalls.length > 0) {
+                    assistant.tool_calls = toolCalls;
+                }
+                return assistant;
             }
             const parts = await Promise.all(message.content.map((part) => this.messageContentToOpenAIContentPart(part)));
-            return {
+            const assistant = {
                 role: "assistant",
-                content: parts,
-                ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {})
+                content: parts
             };
+            if (toolCalls.length > 0) {
+                assistant.tool_calls = toolCalls;
+            }
+            return assistant;
         }
         if (message.role !== "user") {
             throw new Error(`Unsupported role: ${message.role}`);
         }
-        if (typeof message.content === "string") {
+        if (isString(message.content)) {
             return {
                 role: "user",
                 content: message.content
@@ -468,19 +801,31 @@ export class OpenAIProvider extends BaseProvider {
         });
     }
     convertSystemToUserForOModels(messages, model) {
-        if (!model.startsWith("o")) {
+        // Match ONLY genuine OpenAI reasoning models (o1/o3/o4), not any id that
+        // merely starts with "o". Compat providers use namespaced ids like
+        // "openai/gpt-4o" or "openai/gpt-oss-120b" that begin with "o" but fully
+        // support the system role — mangling their system prompt corrupts every
+        // request. Strip a leading "vendor/" namespace before matching.
+        const bareModel = model.includes("/")
+            ? model.slice(model.lastIndexOf("/") + 1)
+            : model;
+        if (!/^o[134](-|$)/.test(bareModel)) {
             return messages;
         }
         return messages.map((msg) => msg.role === "system"
             ? {
                 ...msg,
                 role: "user",
-                content: `Instructions: ${typeof msg.content === "string" ? msg.content : ""}`
+                content: `Instructions: ${isString(msg.content) ? msg.content : ""}`
             }
             : msg);
     }
     async *generateMessages(args) {
-        const { model, tools = [], maxTokens = 16384, temperature, topP, presencePenalty, frequencyPenalty, audio } = args;
+        if (this.usesResponsesApi(args.model)) {
+            yield* this.generateMessagesResponses(args);
+            return;
+        }
+        const { model, tools = [], maxTokens = 16384, temperature, topP, presencePenalty, frequencyPenalty, audio, toolChoice } = args;
         const messages = this.convertSystemToUserForOModels(args.messages, model);
         const openaiMessages = await Promise.all(messages.map((m) => this.convertMessage(m)));
         const request = {
@@ -505,9 +850,19 @@ export class OpenAIProvider extends BaseProvider {
         }
         if (hasTools) {
             request.tools = this.formatTools(tools);
+            if (toolChoice) {
+                request.tool_choice =
+                    toolChoice === "any"
+                        ? "required"
+                        : { type: "function", function: { name: toolChoice } };
+            }
         }
         log.debug("OpenAI request", { model });
-        const stream = (await this.getClient().chat.completions.create(request));
+        this.recordRequestPayload(request);
+        // SAFETY: the request is assembled field by field as a dictionary, which
+        // the SDK's closed param interface does not overlap; `stream: true` on it
+        // selects the streaming overload.
+        const stream = (await this.getClient().chat.completions.create(request, { signal: args.signal }));
         const deltaToolCalls = new Map();
         try {
             for await (const chunk of stream) {
@@ -555,22 +910,34 @@ export class OpenAIProvider extends BaseProvider {
                     };
                     yield item;
                 }
-                if (choice.finish_reason === "tool_calls") {
+                if (choice.finish_reason && deltaToolCalls.size > 0) {
                     for (const call of deltaToolCalls.values()) {
                         const toolCall = this.buildToolCall(call.id, call.name, call.arguments);
                         yield toolCall;
                     }
                     deltaToolCalls.clear();
                 }
+                // Always emit a terminal `done: true` chunk when the completion
+                // finishes, regardless of reason. "stop" already emits one above; for
+                // every other terminal reason (tool_calls, length, content_filter)
+                // emit one here so consumers get a consistent end-of-stream marker
+                // (matching the Anthropic and Gemini providers).
+                if (choice.finish_reason && choice.finish_reason !== "stop") {
+                    const doneChunk = { type: "chunk", content: "", done: true };
+                    yield doneChunk;
+                }
             }
         }
         finally {
-            if (typeof stream.close === "function") {
+            if (isCallable(stream.close)) {
                 await stream.close();
             }
         }
     }
     async generateMessage(args) {
+        if (this.usesResponsesApi(args.model)) {
+            return this.generateMessageResponses(args);
+        }
         const { model, tools = [], toolChoice, maxTokens = 16384, temperature, topP, presencePenalty, frequencyPenalty } = args;
         const messages = this.convertSystemToUserForOModels(args.messages, model);
         const openaiMessages = await Promise.all(messages.map((m) => this.convertMessage(m)));
@@ -599,7 +966,10 @@ export class OpenAIProvider extends BaseProvider {
             }
         }
         log.debug("OpenAI request", { model });
-        const completion = await this.getClient().chat.completions.create(request);
+        this.recordRequestPayload(request);
+        // SAFETY: as above — a dictionary request against the SDK's closed
+        // non-streaming param interface.
+        const completion = await this.getClient().chat.completions.create(request, { signal: args.signal });
         const choice = completion.choices?.[0];
         if (!choice) {
             throw new Error("OpenAI returned no choices");
@@ -624,6 +994,427 @@ export class OpenAIProvider extends BaseProvider {
             toolCalls
         };
     }
+    // ---------------------------------------------------------------------------
+    // Responses API path (used for OpenAI models matched by isOpenAIResponsesModel)
+    // ---------------------------------------------------------------------------
+    /** Responses uses native equivalents by default, caller dispatch when restricted. */
+    formatResponsesTools(tools, providedToolsOnly = false) {
+        const formatted = [];
+        for (const tool of tools) {
+            if (!providedToolsOnly && tool.name === WEB_SEARCH_TOOL_NAME) {
+                formatted.push(RESPONSE_WEB_SEARCH_TOOL);
+                continue;
+            }
+            if (!providedToolsOnly && tool.name === IMAGE_GENERATION_TOOL_NAME) {
+                formatted.push(RESPONSE_IMAGE_GENERATION_TOOL);
+                continue;
+            }
+            const [functionTool] = responseTools([tool]);
+            if (functionTool)
+                formatted.push(functionTool);
+        }
+        return formatted;
+    }
+    async generateMessageResponses(args) {
+        const request = await this.buildResponsesRequest(args, {
+            input: await messagesToResponsesInput(args.messages, (uri) => this.resolveUri(uri)),
+            stream: false,
+            store: false
+        });
+        const client = this.getClient();
+        this.recordRequestPayload(request);
+        // SAFETY: the SDK's `create` is overloaded over a closed param interface,
+        // while this request is assembled field by field; `stream: false` is set
+        // on it, so the SDK resolves a response object, not an async iterable.
+        const response = (await client.responses.create.call(client.responses, request, {
+            signal: args.signal
+        }));
+        this.trackUsage(args.model, responseUsage(response));
+        const outputText = isString(response.output_text)
+            ? response.output_text
+            : extractResponsesText(response.output);
+        const toolCalls = extractResponsesToolCalls(response.output, this.buildToolCall.bind(this));
+        const images = extractResponsesImages(response.output);
+        const content = images.length > 0
+            ? assistantContentWithImages(outputText, images)
+            : outputText || null;
+        return {
+            role: "assistant",
+            content,
+            toolCalls: toolCalls.length > 0 ? toolCalls : undefined
+        };
+    }
+    async *generateMessagesResponses(args) {
+        const input = await messagesToResponsesInput(args.messages, (uri) => this.resolveUri(uri));
+        const request = await this.buildResponsesRequest(args, {
+            input,
+            stream: true,
+            store: false
+        });
+        // Absorb native image results here too — this non-loop path must uphold
+        // the same invariant as collectModelTurn: the base64 blob never leaks
+        // outward as a chunk. The image rides a trailing assistant message event.
+        const images = [];
+        let assistantText = "";
+        for await (const item of this.streamResponsesRequest(args, request)) {
+            const image = imageContentFromChunk(item);
+            if (image) {
+                images.push(image);
+                continue;
+            }
+            if (isRecord(item) &&
+                item.type === "chunk" &&
+                isString(item.content) &&
+                !item.thinking) {
+                assistantText += item.content;
+            }
+            yield item;
+        }
+        if (images.length > 0) {
+            yield {
+                type: "message",
+                message: {
+                    role: "assistant",
+                    content: assistantContentWithImages(assistantText, images)
+                }
+            };
+        }
+    }
+    async *generateLoop(args) {
+        if (!this.usesResponsesApi(args.model)) {
+            return yield* super.generateLoop(args);
+        }
+        return yield* tracedProviderLoop(this.provider, args.model, () => this.generateResponsesLoop(args));
+    }
+    async *generateResponsesLoop(args) {
+        const maxIterations = args.maxIterations ?? 25;
+        const { executeTool, maxIterations: _omitMaxIterations, sequentialTools, providedToolsOnly, turnBudget: budgetArg, resolveMedia, ...turnArgs } = args;
+        const { runBudget, turnBudget } = resolveTurnBudget(budgetArg);
+        const systemHash = hashSystemPrompt(responsesSystemPrompt(args.messages));
+        const prior = args.providerSession ?? null;
+        const canResume = prior != null &&
+            prior.providerId === this.provider &&
+            prior.model === args.model &&
+            (prior.systemHash == null || prior.systemHash === systemHash) &&
+            args.messages.length > prior.checkpoint;
+        if (canResume && prior) {
+            const firstMessages = args.messages.slice(prior.checkpoint);
+            const firstTurnState = this.createResponsesTurnState(prior.token);
+            try {
+                yield* this.runResponsesLoop({
+                    args: turnArgs,
+                    resolveMedia,
+                    executeTool,
+                    providedToolsOnly,
+                    sequentialTools: sequentialTools === true,
+                    maxIterations,
+                    firstMessages,
+                    firstPreviousResponseId: prior.token,
+                    systemHash,
+                    firstTurnState,
+                    turnBudget,
+                    runBudget
+                });
+                return;
+            }
+            catch (err) {
+                if (firstTurnState.emittedContent) {
+                    throw err;
+                }
+                log.warn("OpenAI Responses resume failed; starting fresh", {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+        }
+        const freshMessages = args.loadFullHistory
+            ? await args.loadFullHistory()
+            : args.messages;
+        yield* this.runResponsesLoop({
+            args: turnArgs,
+            resolveMedia,
+            executeTool,
+            providedToolsOnly,
+            sequentialTools: sequentialTools === true,
+            maxIterations,
+            firstMessages: freshMessages,
+            firstPreviousResponseId: null,
+            systemHash,
+            firstTurnState: this.createResponsesTurnState(null),
+            turnBudget,
+            runBudget
+        });
+    }
+    async buildResponsesRequest(args, config) {
+        const request = {
+            model: args.model,
+            input: config.input,
+            stream: config.stream,
+            store: config.store
+        };
+        if (config.previousResponseId) {
+            request.previous_response_id = config.previousResponseId;
+        }
+        if (args.maxTokens != null)
+            request.max_output_tokens = args.maxTokens;
+        if (args.temperature != null)
+            request.temperature = args.temperature;
+        if (args.topP != null)
+            request.top_p = args.topP;
+        const tools = this.formatResponsesTools(args.tools ?? [], config.providedToolsOnly);
+        if (tools.length > 0) {
+            request.tools = tools;
+            const hostedToolChoice = !config.providedToolsOnly && args.toolChoice
+                ? RESPONSE_HOSTED_TOOL_CHOICES[args.toolChoice]
+                : undefined;
+            request.tool_choice = hostedToolChoice
+                ? { type: hostedToolChoice }
+                : (responseToolChoice(args.toolChoice) ?? "auto");
+        }
+        return request;
+    }
+    async *streamResponsesRequest(args, request, onResponseId) {
+        const client = this.getClient();
+        this.recordRequestPayload(request);
+        // SAFETY: as in `generateMessageResponses` — an overloaded SDK method over
+        // a closed param interface, given a request assembled field by field. The
+        // caller set `stream: true`, so the SDK resolves an async iterable.
+        const stream = (await client.responses.create.call(client.responses, request, {
+            signal: args.signal
+        }));
+        yield* streamResponsesEvents(stream, {
+            model: args.model,
+            buildToolCall: this.buildToolCall.bind(this),
+            onUsage: (model, usage) => {
+                const cost = this.trackUsage(model, usage);
+                const span = trace.getActiveSpan();
+                span?.setAttributes({
+                    "gen_ai.usage.input_tokens": usage.inputTokens ?? 0,
+                    "gen_ai.usage.output_tokens": usage.outputTokens ?? 0,
+                    "gen_ai.usage.total_tokens": (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0),
+                });
+                if (usage.cachedTokens !== undefined) {
+                    span?.setAttribute("gen_ai.usage.cached_input_tokens", usage.cachedTokens);
+                }
+                if (this.unpricedReason === null) {
+                    span?.setAttribute("gen_ai.usage.cost_usd", cost);
+                }
+                return cost;
+            },
+            onResponseId
+        });
+    }
+    createResponsesTurnState(responseId) {
+        return {
+            assistantText: "",
+            images: [],
+            pending: [],
+            responseId,
+            emittedContent: false
+        };
+    }
+    async *runResponsesLoop(config) {
+        const toolMap = new Map((config.args.tools ?? []).map((tool) => [tool.name, tool]));
+        let previousResponseId = config.firstPreviousResponseId;
+        const toInput = async (messages) => messagesToResponsesInput(config.resolveMedia ? await config.resolveMedia(messages) : messages, (uri) => this.resolveUri(uri));
+        let input = await toInput(config.firstMessages);
+        let state = config.firstTurnState;
+        // Responses carries prior turns server-side behind `previousResponseId`,
+        // so `input` holds only the delta. Reserving against the delta would price
+        // a turn as if the conversation restarted; the transcript is tracked here
+        // so the reservation grows with the turn it is admitting.
+        const transcript = [...config.firstMessages];
+        const runBudget = config.runBudget ?? null;
+        for (let iteration = 0; iteration < config.maxIterations; iteration++) {
+            if (config.args.signal?.aborted) {
+                yield PROVIDER_STOP_ABORTED;
+                return;
+            }
+            if (runBudget?.deadline.expired()) {
+                yield budgetStopItem(runBudget);
+                return;
+            }
+            let reservation = null;
+            if (config.turnBudget) {
+                reservation = this._admitTurn(config.turnBudget, config.args.model, transcript);
+                if (reservation === null) {
+                    yield budgetStopItem(runBudget);
+                    return;
+                }
+            }
+            beginProviderRound(this.provider, config.args.model);
+            const costBeforeTurn = config.turnBudget ? this.getTotalCost() : 0;
+            // The reservation covers exactly one turn, so it has to be reconciled
+            // even when that turn throws. Left outstanding, a single provider error
+            // would shrink the run's headroom for good — the budget is run-level and
+            // outlives the decision that hit the error.
+            try {
+                const request = await this.buildResponsesRequest(config.args, {
+                    input,
+                    stream: true,
+                    store: true,
+                    previousResponseId,
+                    providedToolsOnly: config.providedToolsOnly
+                });
+                const llm = context.with(providerRoundContext(), () => tracedProviderLlm(this.provider, config.args.model, transcript, () => this.collectResponsesTurn(config.args, request, config.systemHash, state)));
+                yield* llm;
+            }
+            finally {
+                if (config.turnBudget && reservation) {
+                    config.turnBudget.commit(reservation, this.getTotalCost() - costBeforeTurn);
+                }
+            }
+            previousResponseId = state.responseId;
+            // Native image_generation results ride the assistant message as image
+            // content and don't affect pending-tool semantics.
+            const assistantContent = state.images.length > 0
+                ? assistantContentWithImages(state.assistantText, state.images)
+                : state.assistantText || null;
+            const assistantMsg = {
+                role: "assistant",
+                content: assistantContent,
+                toolCalls: state.pending.length > 0 ? state.pending : null
+            };
+            yield { type: "message", message: assistantMsg };
+            transcript.push(assistantMsg);
+            if (state.pending.length === 0) {
+                return;
+            }
+            if (!previousResponseId) {
+                throw new Error("OpenAI Responses returned tool calls without a response id");
+            }
+            const toolMessages = [];
+            const runTool = async (tc) => {
+                // Per-tool error isolation: a thrown tool must still yield a
+                // tool_result so a parallel Promise.all rejection can't discard sibling
+                // results and leave a dangling tool_use (rejected by the API next turn).
+                try {
+                    const tool = toolMap.get(tc.name);
+                    if (tool?.execute) {
+                        const execute = tool.execute;
+                        return await tracedToolCall(tc, () => execute(tc.args ?? {}, tc.id));
+                    }
+                    if (config.executeTool) {
+                        const execute = config.executeTool;
+                        return await tracedToolCall(tc, () => execute(tc));
+                    }
+                    return `Tool "${tc.name}" is not available`;
+                }
+                catch (err) {
+                    return `Error executing tool "${tc.name}": ${err instanceof Error ? err.message : String(err)}`;
+                }
+            };
+            const emitToolResult = function* (tc, content) {
+                const { toolContent, imageMessage } = splitToolResultImages(content);
+                const toolMsg = {
+                    role: "tool",
+                    toolCallId: tc.id,
+                    content: toolContent
+                };
+                toolMessages.push(toolMsg);
+                transcript.push(toolMsg);
+                yield { type: "message", message: toolMsg };
+                if (imageMessage) {
+                    toolMessages.push(imageMessage);
+                    // It rides the next turn's input, so it is part of what that turn
+                    // is billed for — and therefore part of what its reservation covers.
+                    transcript.push(imageMessage);
+                }
+            };
+            let terminated = false;
+            if (config.sequentialTools) {
+                for (const tc of state.pending) {
+                    // Honor a mid-turn abort (mirrors base-provider generateLoop): a tool
+                    // like finish_step aborts the signal to stop the model running any
+                    // further tools THIS turn. Without this check the Responses loop would
+                    // keep executing pending tools after completion — duplicate
+                    // step_result/StepCompleted events, overwritten memory, and stray
+                    // side-effecting tools after the step is already done.
+                    if (config.args.signal?.aborted)
+                        break;
+                    const content = await runTool(tc);
+                    yield* emitToolResult(tc, content);
+                    const tool = toolMap.get(tc.name);
+                    if (tool?.terminal) {
+                        terminated = true;
+                        break;
+                    }
+                }
+            }
+            else {
+                const results = await Promise.all(state.pending.map(async (tc) => ({
+                    tc,
+                    content: await runTool(tc)
+                })));
+                for (const { tc, content } of results) {
+                    yield* emitToolResult(tc, content);
+                    const tool = toolMap.get(tc.name);
+                    if (tool?.terminal)
+                        terminated = true;
+                }
+            }
+            input = await toInput(toolMessages);
+            if (terminated)
+                return;
+            state = this.createResponsesTurnState(previousResponseId);
+        }
+        yield { type: "chunk", content: "", done: true };
+        yield {
+            type: "stop",
+            reason: "iterations",
+            detail: `stopped after ${config.maxIterations} tool-calling round(s)`
+        };
+    }
+    async *collectResponsesTurn(args, request, systemHash, state) {
+        const sessionUpdates = [];
+        const enqueueSession = (responseId) => {
+            if (state.responseId === responseId)
+                return;
+            state.responseId = responseId;
+            const session = {
+                providerId: this.provider,
+                model: args.model,
+                token: responseId,
+                checkpoint: args.messages.length,
+                systemHash
+            };
+            sessionUpdates.push({ type: "session", session });
+        };
+        const flushSessions = function* () {
+            while (sessionUpdates.length > 0) {
+                const update = sessionUpdates.shift();
+                if (update)
+                    yield update;
+            }
+        };
+        for await (const item of this.streamResponsesRequest(args, request, enqueueSession)) {
+            yield* flushSessions();
+            if (isProviderSessionUpdate(item) || isProviderMessageEvent(item)) {
+                yield item;
+                continue;
+            }
+            if ("id" in item && "name" in item && "args" in item) {
+                state.pending.push(item);
+                state.emittedContent = true;
+                yield item;
+                continue;
+            }
+            if (isRecord(item) && item.type === "chunk") {
+                const image = imageContentFromChunk(item);
+                if (image) {
+                    state.images.push(image);
+                    state.emittedContent = true;
+                    continue;
+                }
+                if (isString(item.content) && !item.thinking) {
+                    state.assistantText += item.content;
+                    if (item.content)
+                        state.emittedContent = true;
+                }
+                yield item;
+            }
+        }
+        yield* flushSessions();
+    }
     async textToImage(params) {
         if (!params.prompt) {
             throw new Error("The input prompt cannot be empty.");
@@ -635,12 +1426,14 @@ export class OpenAIProvider extends BaseProvider {
             model: params.model.id,
             prompt
         };
-        const size = this.resolveImageSize(params.width ?? undefined, params.height ?? undefined);
+        const size = this.resolveImageSize(params.width ?? undefined, params.height ?? undefined, params.model.id);
         if (size)
             request.size = size;
         if (params.quality)
             request.quality = params.quality;
-        const response = (await this.getClient().images.generate(request));
+        // SAFETY: a dictionary request against the SDK's closed image params.
+        const response = (await this.getClient().images.generate(request, { signal: params.signal }));
+        this.trackUsage(params.model.id, openAIImageUsage(response, params.quality));
         const item = response.data?.[0];
         if (!item) {
             throw new Error("OpenAI image generation returned no image data.");
@@ -657,8 +1450,40 @@ export class OpenAIProvider extends BaseProvider {
         }
         throw new Error("OpenAI image generation returned no image data.");
     }
-    async imageToImage(image, params) {
-        if (!image || image.length === 0) {
+    /**
+     * Convert a white-region mask (R=G=B=255, alpha = selection) into the mask
+     * OpenAI's edit endpoint expects, where fully transparent pixels mark the
+     * region to regenerate. Inverts the alpha channel and keeps RGBA shape.
+     */
+    async toOpenAiEditMask(mask) {
+        const sharp = await loadSharp();
+        const { data, info } = await sharp(Buffer.from(mask))
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        for (let i = 3; i < data.length; i += 4) {
+            data[i] = 255 - data[i];
+        }
+        const png = await sharp(data, {
+            raw: { width: info.width, height: info.height, channels: 4 }
+        })
+            .png()
+            .toBuffer();
+        return new Uint8Array(png);
+    }
+    async imageToImage(images, params) {
+        return this.runImageEdit(images, params);
+    }
+    async inpaint(images, params) {
+        return this.runImageEdit(images, params, params.mask);
+    }
+    /**
+     * Shared OpenAI image-edit call for both image-to-image and inpaint. When
+     * `mask` is supplied the masked region is regenerated.
+     */
+    async runImageEdit(images, params, mask) {
+        const sources = images.filter((b) => b && b.length > 0);
+        if (sources.length === 0) {
             throw new Error("image must not be empty.");
         }
         if (!params.prompt) {
@@ -667,19 +1492,32 @@ export class OpenAIProvider extends BaseProvider {
         const prompt = params.negativePrompt
             ? `${params.prompt.trim()}\n\nDo not include: ${params.negativePrompt.trim()}`
             : params.prompt;
+        // gpt-image-* accepts multiple reference images as an array; fall back to a
+        // single file for one input so older edit models keep working.
+        const imageFiles = await Promise.all(sources.map((b, i) => toFile(Buffer.from(b), `image_${i}.png`, { type: "image/png" })));
         const request = {
             model: params.model.id,
-            image: await toFile(Buffer.from(image), "image.png", {
-                type: "image/png"
-            }),
+            image: imageFiles.length === 1 ? imageFiles[0] : imageFiles,
             prompt
         };
-        const size = this.resolveImageSize(params.targetWidth ?? undefined, params.targetHeight ?? undefined);
+        // Inpainting: the edit endpoint marks the region to regenerate with the
+        // mask's *transparent* pixels. Our masks use the opposite convention
+        // (opaque/white alpha = edit region, matching FAL), so invert the alpha
+        // channel before sending.
+        if (mask && mask.length > 0) {
+            const openAiMask = await this.toOpenAiEditMask(mask);
+            request.mask = await toFile(Buffer.from(openAiMask), "mask.png", {
+                type: "image/png"
+            });
+        }
+        const size = this.resolveImageSize(params.targetWidth ?? undefined, params.targetHeight ?? undefined, params.model.id);
         if (size)
             request.size = size;
         if (params.quality)
             request.quality = params.quality;
-        const response = (await this.getClient().images.edit(request));
+        // SAFETY: a dictionary request against the SDK's closed edit params.
+        const response = (await this.getClient().images.edit(request, { signal: params.signal }));
+        this.trackUsage(params.model.id, openAIImageUsage(response, params.quality));
         const item = response.data?.[0];
         if (!item) {
             throw new Error("OpenAI image editing returned no image data.");
@@ -704,29 +1542,58 @@ export class OpenAIProvider extends BaseProvider {
         const speed = Math.max(0.25, Math.min(4.0, args.speed ?? 1.0));
         const speechApi = this.getClient().audio.speech;
         if (speechApi.with_streaming_response?.create) {
-            const response = await speechApi.with_streaming_response.create({
+            const request = {
                 model: args.model,
                 input: args.text,
                 voice,
                 speed,
                 response_format: "pcm"
-            });
+            };
+            if (args.model === "gpt-4o-mini-tts" && (args.language || args.instructions)) {
+                request.instructions = [
+                    args.language ? `Speak in ${args.language}.` : undefined,
+                    args.instructions
+                ]
+                    .filter((value) => value !== undefined)
+                    .join(" ");
+            }
+            const response = await speechApi.with_streaming_response.create(request);
+            // TTS is billed per input character, not per token.
+            this.trackUsage(args.model, { inputCharacters: args.text.length });
+            let carry;
             for await (const chunk of response.iterBytes(4096)) {
-                const bytes = asUint8Array(chunk);
-                yield { samples: toInt16Samples(bytes) };
+                const incoming = asUint8Array(chunk);
+                const bytes = new Uint8Array(incoming.length + (carry == null ? 0 : 1));
+                if (carry != null)
+                    bytes[0] = carry;
+                bytes.set(incoming, carry == null ? 0 : 1);
+                const completeLength = bytes.length - (bytes.length % 2);
+                carry =
+                    completeLength < bytes.length ? bytes[bytes.length - 1] : undefined;
+                if (completeLength > 0) {
+                    yield { samples: toInt16Samples(bytes.subarray(0, completeLength)) };
+                }
             }
             return;
         }
-        const response = await speechApi.create({
+        const request = {
             model: args.model,
             input: args.text,
             voice,
             speed,
             response_format: "pcm"
-        });
-        const bytes = asUint8Array(typeof response.arrayBuffer === "function"
-            ? await response.arrayBuffer()
-            : response);
+        };
+        if (args.model === "gpt-4o-mini-tts" && (args.language || args.instructions)) {
+            request.instructions = [
+                args.language ? `Speak in ${args.language}.` : undefined,
+                args.instructions
+            ]
+                .filter((value) => value !== undefined)
+                .join(" ");
+        }
+        const response = await speechApi.create(request);
+        this.trackUsage(args.model, { inputCharacters: args.text.length });
+        const bytes = asUint8Array(isCallable(response.arrayBuffer) ? await response.arrayBuffer() : response);
         yield { samples: toInt16Samples(bytes) };
     }
     /**
@@ -754,16 +1621,24 @@ export class OpenAIProvider extends BaseProvider {
         const voice = args.voice ?? "alloy";
         const speed = Math.max(0.25, Math.min(4.0, args.speed ?? 1.0));
         const speechApi = this.getClient().audio.speech;
-        const response = await speechApi.create({
+        const request = {
             model: args.model,
             input: args.text,
             voice,
             speed,
             response_format: fmt
-        });
-        const bytes = asUint8Array(typeof response.arrayBuffer === "function"
-            ? await response.arrayBuffer()
-            : response);
+        };
+        if (args.model === "gpt-4o-mini-tts" && (args.language || args.instructions)) {
+            request.instructions = [
+                args.language ? `Speak in ${args.language}.` : undefined,
+                args.instructions
+            ]
+                .filter((value) => value !== undefined)
+                .join(" ");
+        }
+        const response = await speechApi.create(request);
+        this.trackUsage(args.model, { inputCharacters: args.text.length });
+        const bytes = asUint8Array(isCallable(response.arrayBuffer) ? await response.arrayBuffer() : response);
         return { data: bytes, mimeType: formatToMime[fmt] };
     }
     async automaticSpeechRecognition(args) {
@@ -772,25 +1647,53 @@ export class OpenAIProvider extends BaseProvider {
         }
         const temperature = Math.max(0, Math.min(1, args.temperature ?? 0));
         const audioPart = new Uint8Array(args.audio);
+        // Label the upload with what the bytes actually are. Hardcoding audio/mpeg
+        // made OpenAI reject anything that was not MP3 with "400 Audio file might
+        // be corrupted or unsupported" — which is every clip coming through
+        // `nodetool.video.ExtractAudio`, since that writes PCM WAV.
+        const audioMime = sniffAudioMime(audioPart);
+        const audioName = `audio.${AUDIO_MIME_EXT[audioMime] ?? "mp3"}`;
         const fileLike = typeof File !== "undefined"
-            ? new File([audioPart], "audio.mp3", { type: "audio/mpeg" })
-            : Object.assign(new Blob([audioPart], { type: "audio/mpeg" }), {
-                name: "audio.mp3"
+            ? new File([audioPart], audioName, { type: audioMime })
+            : Object.assign(new Blob([audioPart], { type: audioMime }), {
+                name: audioName
             });
+        const isDiarizationModel = args.model.startsWith("gpt-4o-transcribe-diarize");
+        if (args.word_timestamps && args.model !== "whisper-1") {
+            throw new Error("Word timestamps are only supported by whisper-1");
+        }
         const requestParams = {
             file: fileLike,
             model: args.model,
             language: args.language,
-            prompt: args.prompt,
             temperature
         };
+        if (!isDiarizationModel && args.prompt) {
+            requestParams.prompt = args.prompt;
+        }
+        if (isDiarizationModel) {
+            requestParams.response_format = "diarized_json";
+            requestParams.chunking_strategy = "auto";
+        }
         if (args.word_timestamps) {
             requestParams.response_format = "verbose_json";
             requestParams.timestamp_granularities = ["word", "segment"];
         }
         const response = await this.getClient().audio.transcriptions.create(requestParams);
+        // Whisper/transcribe is billed per second of audio. The duration is only
+        // reported on the verbose/diarized formats (and as `usage.seconds` on the
+        // newer transcribe models); skip accounting when it is absent rather than
+        // guessing.
+        const durationSeconds = isNumber(response.duration)
+            ? response.duration
+            : isNumber(response.usage?.seconds)
+                ? response.usage.seconds
+                : undefined;
+        if (durationSeconds !== undefined) {
+            this.trackUsage(args.model, { durationSeconds });
+        }
         const text = String(response.text ?? "");
-        if (!args.word_timestamps) {
+        if (!args.word_timestamps && !isDiarizationModel) {
             return { text };
         }
         const chunks = [];
@@ -820,19 +1723,24 @@ export class OpenAIProvider extends BaseProvider {
         if (!params.prompt) {
             throw new Error("The input prompt cannot be empty.");
         }
-        const size = OpenAIProvider.resolveVideoSize(params.aspectRatio, params.resolution);
+        const size = OpenAIProvider.resolveVideoSize(params.aspectRatio, params.resolution, params.model.id);
         const seconds = OpenAIProvider.secondsFromParams(params) ?? 4;
         const request = {
             model: params.model.id,
             prompt: params.prompt,
-            size: size ?? "1024x1024",
+            size: size ?? "1280x720",
             seconds: String(seconds)
         };
-        const video = await this.getClient().videos.create(request);
+        // SAFETY: a dictionary request against the SDK's closed video params.
+        const video = await this.getClient().videos.create(request, { signal: params.signal });
         if (!video?.id) {
             throw new Error("OpenAI video create response did not contain a video id");
         }
-        const timeoutMs = 10 * 60 * 1000;
+        const timeoutMs = params.timeoutSeconds != null &&
+            Number.isFinite(params.timeoutSeconds) &&
+            params.timeoutSeconds > 0
+            ? params.timeoutSeconds * 1000
+            : 10 * 60 * 1000;
         const intervalMs = 2000;
         const start = Date.now();
         let latest = video;
@@ -840,8 +1748,17 @@ export class OpenAIProvider extends BaseProvider {
             if (Date.now() - start > timeoutMs) {
                 throw new Error("Video generation timed out");
             }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
-            latest = await this.getClient().videos.retrieve(video.id);
+            const remainingMs = timeoutMs - (Date.now() - start);
+            await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remainingMs)));
+            if (Date.now() - start >= timeoutMs) {
+                throw new Error("Video generation timed out");
+            }
+            if (params.signal?.aborted) {
+                throw new Error("Video generation cancelled");
+            }
+            latest = await this.getClient().videos.retrieve(video.id, {
+                signal: params.signal
+            });
         }
         if (latest.status !== "completed") {
             throw new Error(String(latest.error ??
@@ -855,14 +1772,13 @@ export class OpenAIProvider extends BaseProvider {
             throw new Error("The input image cannot be empty.");
         }
         const [width, height] = OpenAIProvider.extractImageDimensions(image);
-        const requestedSize = OpenAIProvider.resolveVideoSize(params.aspectRatio, params.resolution);
+        const requestedSize = OpenAIProvider.resolveVideoSize(params.aspectRatio, params.resolution, params.model.id);
         const size = requestedSize ?? OpenAIProvider.snapToValidVideoDimensions(width, height);
         const seconds = OpenAIProvider.secondsFromParams(params) ?? 4;
         const [targetW, targetH] = size.split("x").map(Number);
-        const sharp = (await import("sharp")).default;
         const resized = width === targetW && height === targetH
             ? image
-            : new Uint8Array(await sharp(image)
+            : new Uint8Array(await (await loadSharp())(image)
                 .resize(targetW, targetH, { fit: "cover", position: "centre" })
                 .png()
                 .toBuffer());
@@ -874,11 +1790,15 @@ export class OpenAIProvider extends BaseProvider {
             }),
             size: size,
             seconds: String(seconds)
-        });
+        }, { signal: params.signal });
         if (!video?.id) {
             throw new Error("OpenAI image-to-video create response did not contain a video id");
         }
-        const timeoutMs = 10 * 60 * 1000;
+        const timeoutMs = params.timeoutSeconds != null &&
+            Number.isFinite(params.timeoutSeconds) &&
+            params.timeoutSeconds > 0
+            ? params.timeoutSeconds * 1000
+            : 10 * 60 * 1000;
         const intervalMs = 2000;
         const start = Date.now();
         let latest = video;
@@ -886,8 +1806,17 @@ export class OpenAIProvider extends BaseProvider {
             if (Date.now() - start > timeoutMs) {
                 throw new Error("Image-to-video generation timed out");
             }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
-            latest = await this.getClient().videos.retrieve(video.id);
+            const remainingMs = timeoutMs - (Date.now() - start);
+            await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remainingMs)));
+            if (Date.now() - start >= timeoutMs) {
+                throw new Error("Image-to-video generation timed out");
+            }
+            if (params.signal?.aborted) {
+                throw new Error("Image-to-video generation cancelled");
+            }
+            latest = await this.getClient().videos.retrieve(video.id, {
+                signal: params.signal
+            });
         }
         if (latest.status !== "completed") {
             throw new Error(String(latest.error ??
@@ -901,13 +1830,16 @@ export class OpenAIProvider extends BaseProvider {
         if (input.length === 0 || input.every((v) => !v)) {
             throw new Error("text must not be empty");
         }
-        const response = await this.getClient().embeddings.create({
-            model: args.model,
-            input,
-            ...(args.dimensions ? { dimensions: args.dimensions } : {})
-        });
+        const request = { model: args.model, input };
+        if (args.dimensions) {
+            request.dimensions = args.dimensions;
+        }
+        const response = await this.getClient().embeddings.create(request);
         return response.data.map((row) => row.embedding);
     }
+    isContextExceededError(error) {
+        return openAIContextExceeded(error) !== null;
+    }
     isContextLengthError(error) {
         const msg = String(error).toLowerCase();
         return msg.includes("context length") || msg.includes("maximum context");