@zhivex-ai/openai 0.16.3 → 0.18.0

package/dist/index.js

@@ -4,15 +4,87 @@ import { computerInputSchema, computerScreenshotSchema } from "./computer.js";
 export { openAIComputerTool, OpenAIComputerExecutionError } from "./computer.js";
 import { jsonHeaders, parseJson, RESERVED_REQUEST_HEADERS } from "./http.js";
 import { OpenAIRealtimeModel, openAIRealtimeMcpMetadataKey, resolveOpenAIRealtimeHeaders } from "./realtime.js";
-export { openAIRealtimeMcpMetadataKey } from "./realtime.js";
+export { OpenAIRealtimeModel, openAIRealtimeMcpMetadataKey } from "./realtime.js";
 import { OpenAIEmbeddingModel, OpenAITranscriptionModel, OpenAISpeechModel, toUint8Array } from "./resource-models.js";
+export { OpenAISpeechModel } from "./resource-models.js";
 import { OpenAIAgentsClient } from "./agents.js";
 export { OpenAIAgentsClient } from "./agents.js";
 import { toJSONSchema, z } from "zod";
 import { OpenAILiveModel, isOpenAILiveModel } from "./live.js";
+export { OpenAILiveModel } from "./live.js";
 import { createOpenAIImageGenerationModel, normalizeOpenAIImageGenerationCall, normalizeOpenAIImageGenerationPartialImage } from "./image-generation.js";
 import { groundedCapabilities, supportsOpenAIModernResponses, assertOpenAIModelRequestSupported, resolveOpenAIModelProfile, modelCapabilities } from "./capabilities.js";
-import { imageInputToDataUrl, ConfigurationError, ProviderHTTPError, ProviderResponseTooLargeError, ProviderToolCallError, assertTrustedEndpoint, resolveAudioResponseLimits, openWebSocketConnection, hostedTool, providerDataPart, UnsupportedFeatureError, createProviderAdapter, isCallableToolDefinition, isHostedToolDefinition, normalizeFinishReason, streamSSE, streamChatCompletions, toolResultPayload, withRetry, withResponseRetry, withTimeoutSignal } from "@zhivex-ai/core/provider";
+import { imageInputToDataUrl, ConfigurationError, ProviderHTTPError, ProviderResponseTooLargeError, ProviderToolCallError, ValidationError, assertTrustedEndpoint, resolveAudioResponseLimits, openWebSocketConnection, hostedTool, providerDataPart, UnsupportedFeatureError, createProviderAdapter, isCallableToolDefinition, isHostedToolDefinition, normalizeFinishReason, streamSSE, streamChatCompletions, toolResultPayload, withRetry, withResponseRetry, withTimeoutSignal } from "@zhivex-ai/core/provider";
+const TOOL_INPUT_JSON_SCHEMA = Symbol.for("@zhivex-ai/core/json-schema");
+/** Zod inputs stay on toJSONSchema so this package still loads against the oldest core in its peer range. */
+const toolInputSchema = (schema) => {
+    if (schema !== null && typeof schema === "object" && schema[TOOL_INPUT_JSON_SCHEMA] === true) {
+        return { ...schema.jsonSchema };
+    }
+    return toJSONSchema(schema);
+};
+const openAISamplingWarnings = new Set();
+const warnOpenAISampling = (option, detail) => {
+    const key = `openai:${option}:${detail}`;
+    if (openAISamplingWarnings.has(key))
+        return;
+    openAISamplingWarnings.add(key);
+    console.warn(`Provider "openai" does not support ${option}. ${detail} The option was ignored.`);
+};
+const openAIChatCacheTtlWarnings = new Set();
+const warnOpenAIChatPromptCacheTtl = () => {
+    const key = 'openai:prompt_cache_options.ttl:12h:chat';
+    if (openAIChatCacheTtlWarnings.has(key))
+        return;
+    openAIChatCacheTtlWarnings.add(key);
+    console.warn('Provider "openai" does not support prompt_cache_options.ttl "12h" on Chat Completions. The option was ignored.');
+};
+/** Chat Completions support for a 12-hour cache TTL is unconfirmed, so that value is ignored. */
+const openAIChatBodyOptions = (options) => {
+    const cache = options.prompt_cache_options;
+    if (cache?.ttl !== "12h")
+        return options;
+    warnOpenAIChatPromptCacheTtl();
+    const rest = { ...cache };
+    delete rest.ttl;
+    const next = { ...options };
+    if (Object.keys(rest).length === 0)
+        delete next.prompt_cache_options;
+    else
+        next.prompt_cache_options = rest;
+    return next;
+};
+/** Model profiles that already reject sampling. `topP` still throws in assertOpenAIModelRequestSupported. */
+const openAISamplingRejected = (modelId, input, bodyOptions) => {
+    const profile = resolveOpenAIModelProfile(modelId);
+    if (profile.sampling === "allowed")
+        return null;
+    const effort = input.reasoning?.effort ?? bodyOptions.reasoning?.effort ?? bodyOptions.reasoning_effort;
+    return profile.sampling === "unsupported" || effort !== "none" ? profile.label : null;
+};
+const openAIChatSampling = (modelId, input, bodyOptions) => {
+    const rejected = openAISamplingRejected(modelId, input, bodyOptions);
+    if (rejected) {
+        if (input.seed !== undefined)
+            warnOpenAISampling("seed", `${rejected} does not support seed.`);
+        if (input.stopSequences !== undefined) {
+            warnOpenAISampling("stopSequences", `${rejected} does not support stop sequences.`);
+        }
+    }
+    return {
+        ...(input.topP !== undefined ? { top_p: input.topP } : {}),
+        ...(!rejected && input.seed !== undefined ? { seed: input.seed } : {}),
+        ...(!rejected && input.stopSequences !== undefined ? { stop: [...input.stopSequences] } : {})
+    };
+};
+const openAIResponsesSampling = (input) => {
+    if (input.seed !== undefined)
+        warnOpenAISampling("seed", "The Responses API does not accept seed.");
+    if (input.stopSequences !== undefined) {
+        warnOpenAISampling("stopSequences", "The Responses API does not accept stop sequences.");
+    }
+    return input.topP !== undefined ? { top_p: input.topP } : {};
+};
 const MIB = 1024 * 1024;
 const DEFAULT_HOSTED_IMAGE_EVENT_BYTES = 32 * MIB;
 const DEFAULT_HOSTED_IMAGE_TOTAL_BYTES = 128 * MIB;
@@ -182,6 +254,14 @@ const isOpenAIPromptCacheBreakpointPart = (part) => part.type === "provider-data
     part.data !== null &&
     typeof part.data === "object" &&
     part.data.type === "prompt_cache_breakpoint";
+const explicitPromptCacheBreakpoint = (breakpoint) => {
+    const record = breakpoint;
+    const ttl = record.ttl;
+    if (ttl !== undefined && ttl !== "30m" && ttl !== "12h") {
+        throw new ValidationError('OpenAI prompt cache breakpoint ttl must be "30m" or "12h".');
+    }
+    return ttl === "30m" || ttl === "12h" ? { mode: "explicit", ttl } : { mode: "explicit" };
+};
 const promptCacheBreakpointForContentPart = (part) => {
     const metadata = part
         .providerMetadata;
@@ -190,7 +270,7 @@ const promptCacheBreakpointForContentPart = (part) => {
         : metadata;
     const breakpoint = openAIMetadata?.prompt_cache_breakpoint;
     return breakpoint && typeof breakpoint === "object" && !Array.isArray(breakpoint)
-        ? { prompt_cache_breakpoint: { mode: "explicit" } }
+        ? { prompt_cache_breakpoint: explicitPromptCacheBreakpoint(breakpoint) }
         : {};
 };
 const imageDetailForPart = (part) => {
@@ -201,12 +281,12 @@ const imageDetailForPart = (part) => {
             : undefined);
     return detail === "auto" || detail === "low" || detail === "high" || detail === "original" ? detail : undefined;
 };
-const markLastContentBlockForPromptCaching = (content) => {
+const markLastContentBlockForPromptCaching = (content, breakpoint) => {
     const last = content.at(-1);
     if (!last) {
         throw new ConfigurationError("OpenAI prompt cache breakpoints must follow a cacheable content part.");
     }
-    last.prompt_cache_breakpoint = { mode: "explicit" };
+    last.prompt_cache_breakpoint = explicitPromptCacheBreakpoint(breakpoint);
 };
 const mapContentParts = (message) => {
     const hasRichContent = message.parts.some((part) => part.type === "image" ||
@@ -251,7 +331,7 @@ const mapContentParts = (message) => {
             });
         }
         else if (isOpenAIPromptCacheBreakpointPart(part)) {
-            markLastContentBlockForPromptCaching(content);
+            markLastContentBlockForPromptCaching(content, part.data);
         }
     }
     return content;
@@ -358,7 +438,7 @@ const mapTools = (input) => input
                 function: {
                     name: tool.name,
                     description: tool.description,
-                    parameters: toJSONSchema(tool.schema)
+                    parameters: toolInputSchema(tool.schema)
                 }
             };
         }
@@ -385,7 +465,7 @@ const mapResponsesTools = (input) => input
                 type: "function",
                 name: tool.name,
                 description: tool.description,
-                parameters: toJSONSchema(tool.schema),
+                parameters: toolInputSchema(tool.schema),
                 ...openAIResponsesFunctionConfig(tool)
             };
         }
@@ -798,7 +878,7 @@ const toResponsesInput = (messages, format, history = messages) => {
                     break;
                 case "provider-data":
                     if (isOpenAIPromptCacheBreakpointPart(part)) {
-                        markLastContentBlockForPromptCaching(content);
+                        markLastContentBlockForPromptCaching(content, part.data);
                     }
                     break;
             }
@@ -966,36 +1046,90 @@ const attachTerminalUsage = (error, raw) => new ProviderToolCallError({
     cause: error.cause,
     usage: mapResponsesUsage(raw)
 });
-const mapResponsesUsage = (usage) => usage
-    ? {
+const mapOpenAICacheWriteTokensDetails = (details) => {
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return undefined;
+    const record = details;
+    const read = (key) => typeof record[key] === "number" ? record[key] : undefined;
+    const ttl30mTokens = read("ttl_30m_tokens");
+    const ttl12hTokens = read("ttl_12h_tokens");
+    if (ttl30mTokens === undefined && ttl12hTokens === undefined)
+        return undefined;
+    return {
+        ...(ttl30mTokens !== undefined ? { ttl30mTokens } : {}),
+        ...(ttl12hTokens !== undefined ? { ttl12hTokens } : {})
+    };
+};
+const mapResponsesUsage = (usage) => {
+    if (!usage)
+        return undefined;
+    const cacheWriteTokensDetails = mapOpenAICacheWriteTokensDetails(usage.input_tokens_details?.cache_write_tokens_details);
+    return {
         inputTokens: usage.input_tokens,
         cachedInputTokens: usage.input_tokens_details?.cached_tokens,
         cacheWriteTokens: usage.input_tokens_details?.cache_write_tokens,
+        ...(cacheWriteTokensDetails ? { cacheWriteTokensDetails } : {}),
         outputTokens: usage.output_tokens,
         reasoningTokens: usage.output_tokens_details?.reasoning_tokens,
         totalTokens: usage.total_tokens
-    }
-    : undefined;
-const mapChatUsage = (usage) => usage
-    ? {
+    };
+};
+const mapChatUsage = (usage) => {
+    if (!usage)
+        return undefined;
+    const cacheWriteTokensDetails = mapOpenAICacheWriteTokensDetails(usage.prompt_tokens_details?.cache_write_tokens_details);
+    return {
         inputTokens: usage.prompt_tokens,
         cachedInputTokens: usage.prompt_tokens_details?.cached_tokens,
         cacheWriteTokens: usage.prompt_tokens_details?.cache_write_tokens,
+        ...(cacheWriteTokensDetails ? { cacheWriteTokensDetails } : {}),
         outputTokens: usage.completion_tokens,
         reasoningTokens: usage.completion_tokens_details?.reasoning_tokens,
         totalTokens: usage.total_tokens
-    }
-    : undefined;
+    };
+};
+const openAIUsageCounters = (usage) => [
+    usage.inputTokens,
+    usage.outputTokens,
+    usage.totalTokens,
+    usage.cachedInputTokens,
+    usage.cacheWriteTokens,
+    usage.reasoningTokens,
+    usage.cacheWriteTokensDetails?.ttl30mTokens,
+    usage.cacheWriteTokensDetails?.ttl12hTokens
+];
+const openAIUsageCounterInvalid = (usage) => openAIUsageCounters(usage ?? {}).some((value) => value !== undefined && (!Number.isSafeInteger(value) || value < 0));
 const addTokenUsage = (left, right) => {
     if (!left)
         return right;
     if (!right)
         return left;
     const sum = (a, b) => a === undefined || b === undefined ? undefined : a + b;
+    const consistentDetails = (writes, details) => {
+        if (!details)
+            return (writes ?? 0) === 0;
+        return writes !== undefined && (details.ttl30mTokens ?? 0) + (details.ttl12hTokens ?? 0) === writes;
+    };
+    const cacheWriteTokensDetails = consistentDetails(left.cacheWriteTokens, left.cacheWriteTokensDetails) &&
+        consistentDetails(right.cacheWriteTokens, right.cacheWriteTokensDetails) &&
+        (left.cacheWriteTokensDetails || right.cacheWriteTokensDetails)
+        ? {
+            ...(left.cacheWriteTokensDetails?.ttl30mTokens !== undefined || right.cacheWriteTokensDetails?.ttl30mTokens !== undefined
+                ? { ttl30mTokens: (left.cacheWriteTokensDetails?.ttl30mTokens ?? 0) + (right.cacheWriteTokensDetails?.ttl30mTokens ?? 0) }
+                : {}),
+            ...(left.cacheWriteTokensDetails?.ttl12hTokens !== undefined || right.cacheWriteTokensDetails?.ttl12hTokens !== undefined
+                ? { ttl12hTokens: (left.cacheWriteTokensDetails?.ttl12hTokens ?? 0) + (right.cacheWriteTokensDetails?.ttl12hTokens ?? 0) }
+                : {})
+        }
+        : undefined;
     return {
         inputTokens: sum(left.inputTokens, right.inputTokens),
         cachedInputTokens: sum(left.cachedInputTokens, right.cachedInputTokens),
         cacheWriteTokens: sum(left.cacheWriteTokens, right.cacheWriteTokens),
+        ...(cacheWriteTokensDetails &&
+            (cacheWriteTokensDetails.ttl30mTokens !== undefined || cacheWriteTokensDetails.ttl12hTokens !== undefined)
+            ? { cacheWriteTokensDetails }
+            : {}),
         outputTokens: sum(left.outputTokens, right.outputTokens),
         reasoningTokens: sum(left.reasoningTokens, right.reasoningTokens),
         totalTokens: sum(left.totalTokens, right.totalTokens)
@@ -1493,6 +1627,17 @@ class OpenAILanguageModel {
         if (!this.capabilities.vision && input.messages.some(message => message.parts.some(part => part.type === "image"))) {
             throw new UnsupportedFeatureError(`OpenAI model "${this.modelId}" has no declared vision support.`);
         }
+        if (!this.capabilities.audioInput && input.messages.some(message => message.parts.some(part => part.type === "audio"))) {
+            throw new UnsupportedFeatureError(`OpenAI model "${this.modelId}" has no declared audio input support.`);
+        }
+        // No OpenAI language model advertises video input unless inputMediaTypes says so.
+        const acceptsVideo = this.capabilities.inputMediaTypes?.some((type) => {
+            const normalized = type.toLowerCase();
+            return normalized === "*/*" || normalized === "video/*" || normalized.startsWith("video/");
+        }) === true;
+        if (!acceptsVideo && input.messages.some(message => message.parts.some(part => part.type === "file" && part.mediaType.toLowerCase().startsWith("video/")))) {
+            throw new UnsupportedFeatureError(`OpenAI model "${this.modelId}" has no declared video input support.`);
+        }
         const rawFormat = options.bodyOptions.response_format;
         const rawText = options.bodyOptions.text;
         const formatTypes = [rawFormat?.type, rawText?.format?.type];
@@ -1569,17 +1714,18 @@ class OpenAILanguageModel {
                         ...(input.toolChoice ? { tool_choice: mapResponsesToolChoice(input.toolChoice) } : {}),
                         text: mapResponsesStructuredOutput(input) ?? responseBodyOptions.text,
                         temperature: input.temperature,
+                        ...openAIResponsesSampling(input),
                         max_output_tokens: ptc ? remainingOutputTokens : input.maxTokens,
                         ...mapResponsesReasoning(input, responseBodyOptions.reasoning)
                     })
                 }), { ...input, abortSignal: signal, ...(ptc ? { maxRetries: 0 } : {}) }, "OpenAI");
                 const json = await parseJson(response);
                 const reportedUsage = mapResponsesUsage(json.usage);
-                if (ptc && (!reportedUsage || ![reportedUsage.inputTokens, reportedUsage.outputTokens, reportedUsage.totalTokens].every(value => typeof value === "number" && Number.isSafeInteger(value) && value >= 0) || reportedUsage.totalTokens < reportedUsage.inputTokens + reportedUsage.outputTokens || Object.values(reportedUsage).some(value => value !== undefined && (!Number.isSafeInteger(value) || value < 0)))) {
+                if (ptc && (!reportedUsage || ![reportedUsage.inputTokens, reportedUsage.outputTokens, reportedUsage.totalTokens].every(value => typeof value === "number" && Number.isSafeInteger(value) && value >= 0) || reportedUsage.totalTokens < reportedUsage.inputTokens + reportedUsage.outputTokens || openAIUsageCounterInvalid(reportedUsage))) {
                     throw failure("OPENAI_PTC_USAGE_UNKNOWN");
                 }
                 const nextUsage = addTokenUsage(accumulatedUsage, reportedUsage);
-                if (ptc && Object.values(nextUsage ?? {}).some(value => value !== undefined && !Number.isSafeInteger(value)))
+                if (ptc && openAIUsageCounterInvalid(nextUsage))
                     throw failure("OPENAI_PTC_USAGE_UNKNOWN");
                 accumulatedUsage = nextUsage;
                 if (ptc)
@@ -1658,13 +1804,14 @@ class OpenAILanguageModel {
                 headers: options.headers,
                 signal,
                 body: JSON.stringify({
-                    ...options.bodyOptions,
+                    ...openAIChatBodyOptions(options.bodyOptions),
                     model: this.modelId,
                     messages: mapMessages(input.messages, input.toolResultFormat),
                     tools: mapTools(input.tools),
                     ...(input.toolChoice ? { tool_choice: mapToolChoice(input.toolChoice) } : {}),
                     response_format: mapStructuredOutput(input) ?? options.bodyOptions.response_format,
                     temperature: input.temperature,
+                    ...openAIChatSampling(this.modelId, input, options.bodyOptions),
                     ...(input.reasoning ? {} : { max_tokens: input.maxTokens }),
                     ...mapChatReasoning(input),
                     stream: false
@@ -1722,6 +1869,7 @@ class OpenAILanguageModel {
                     ...(input.toolChoice ? { tool_choice: mapResponsesToolChoice(input.toolChoice) } : {}),
                     text: mapResponsesStructuredOutput(input) ?? responseBodyOptions.text,
                     temperature: input.temperature,
+                    ...openAIResponsesSampling(input),
                     max_output_tokens: input.maxTokens,
                     ...mapResponsesReasoning(input, responseBodyOptions.reasoning),
                     stream: true
@@ -1744,13 +1892,14 @@ class OpenAILanguageModel {
             headers: options.headers,
             signal,
             body: JSON.stringify({
-                ...options.bodyOptions,
+                ...openAIChatBodyOptions(options.bodyOptions),
                 model: this.modelId,
                 messages: mapMessages(input.messages, input.toolResultFormat),
                 tools: mapTools(input.tools),
                 ...(input.toolChoice ? { tool_choice: mapToolChoice(input.toolChoice) } : {}),
                 response_format: mapStructuredOutput(input) ?? options.bodyOptions.response_format,
                 temperature: input.temperature,
+                ...openAIChatSampling(this.modelId, input, options.bodyOptions),
                 ...(input.reasoning ? {} : { max_tokens: input.maxTokens }),
                 ...mapChatReasoning(input),
                 stream: true,
@@ -1846,6 +1995,7 @@ export const createOpenAI = (options = {}) => {
     const responseLimits = resolveOpenAIResponseLimits(options.responseLimits);
     return createProviderAdapter({
         name: "openai",
+        decisionModel: (modelId = "gpt-6-luna") => createOpenAIDecisionModel(modelId, { apiKey, baseURL, fetch: fetcher, allowUnsafeEndpoints: options.allowUnsafeEndpoints }),
         experimentalDecisionModel: (modelId = "gpt-6-luna") => createOpenAIDecisionModel(modelId, { apiKey, baseURL, fetch: fetcher, allowUnsafeEndpoints: options.allowUnsafeEndpoints }),
         languageModel: (modelId) => {
             if (modelId.startsWith("gpt-live-"))
@@ -1949,9 +2099,10 @@ export const openAIRealtimeMcpApprovalResult = (response) => ({
         }
     }
 });
-export const openAIPromptCacheBreakpoint = () => providerDataPart("openai", {
+export const openAIPromptCacheBreakpoint = (breakpoint) => providerDataPart("openai", {
     type: "prompt_cache_breakpoint",
-    mode: "explicit"
+    mode: "explicit",
+    ...(breakpoint?.ttl ? { ttl: breakpoint.ttl } : {})
 });
 export const openAIComputerUseTool = (config) => hostedTool({
     name: "computer",