@zhivex-ai/openai 0.16.2 → 0.17.0

package/dist/index.js

@@ -1,17 +1,90 @@
+import { withManualRedirect } from "./manual-redirect.js";
 import { createOpenAIDecisionModel } from "./decision.js";
 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;
@@ -58,13 +131,53 @@ const assertOpenAIToolPathInsideRoot = async (rootDir, targetPath, label) => {
         return targetPath;
     }
     const path = await import("node:path");
+    const fs = await import("node:fs/promises");
     const root = path.resolve(rootDir);
-    const target = path.resolve(root, targetPath);
-    const relative = path.relative(root, target);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    const lexical = path.resolve(root, targetPath);
+    const lexicalRelative = path.relative(root, lexical);
+    const escapes = (relative) => path.isAbsolute(relative) || relative.split(path.sep).includes("..");
+    if (escapes(lexicalRelative)) {
         throw new Error(`OpenAI ${label} path escapes rootDir.`);
     }
-    return target;
+    let rootReal;
+    try {
+        const rootStat = await fs.lstat(root);
+        if (rootStat.isSymbolicLink()) {
+            throw new Error(`OpenAI ${label} path escapes rootDir.`);
+        }
+        rootReal = await fs.realpath(root);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("escapes rootDir"))
+            throw error;
+        throw new Error(`OpenAI ${label} rootDir is not an accessible directory.`);
+    }
+    const missing = [];
+    let current = lexical;
+    let resolvedExisting = rootReal;
+    while (true) {
+        try {
+            resolvedExisting = await fs.realpath(current);
+            break;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT")
+                throw new Error(`OpenAI ${label} path escapes rootDir.`);
+            const parent = path.dirname(current);
+            if (parent === current)
+                throw new Error(`OpenAI ${label} path escapes rootDir.`);
+            missing.push(path.basename(current));
+            current = parent;
+        }
+    }
+    const resolved = missing.length === 0 ? resolvedExisting : path.resolve(resolvedExisting, ...missing.reverse());
+    const relative = path.relative(rootReal, resolved);
+    if (escapes(relative) ||
+        (resolved !== rootReal && !resolved.startsWith(`${rootReal}${path.sep}`))) {
+        throw new Error(`OpenAI ${label} path escapes rootDir.`);
+    }
+    return resolved;
 };
 const resolveOpenAILanguageRequestOptions = (providerOptions, apiKey) => {
     const bodyOptions = { ...(providerOptions ?? {}) };
@@ -141,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;
@@ -149,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) => {
@@ -160,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" ||
@@ -210,7 +331,7 @@ const mapContentParts = (message) => {
             });
         }
         else if (isOpenAIPromptCacheBreakpointPart(part)) {
-            markLastContentBlockForPromptCaching(content);
+            markLastContentBlockForPromptCaching(content, part.data);
         }
     }
     return content;
@@ -317,7 +438,7 @@ const mapTools = (input) => input
                 function: {
                     name: tool.name,
                     description: tool.description,
-                    parameters: toJSONSchema(tool.schema)
+                    parameters: toolInputSchema(tool.schema)
                 }
             };
         }
@@ -344,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)
             };
         }
@@ -757,7 +878,7 @@ const toResponsesInput = (messages, format, history = messages) => {
                     break;
                 case "provider-data":
                     if (isOpenAIPromptCacheBreakpointPart(part)) {
-                        markLastContentBlockForPromptCaching(content);
+                        markLastContentBlockForPromptCaching(content, part.data);
                     }
                     break;
             }
@@ -925,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)
@@ -1528,17 +1703,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)
@@ -1617,13 +1793,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
@@ -1681,6 +1858,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
@@ -1703,13 +1881,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,
@@ -1800,7 +1979,8 @@ export const createOpenAI = (options = {}) => {
             allowUnsafe: options.allowUnsafeEndpoints
         }).toString()
         : undefined;
-    const fetcher = options.fetch ?? globalThis.fetch;
+    const rawFetch = options.fetch ?? globalThis.fetch;
+    const fetcher = withManualRedirect(rawFetch);
     const responseLimits = resolveOpenAIResponseLimits(options.responseLimits);
     return createProviderAdapter({
         name: "openai",
@@ -1827,7 +2007,7 @@ export const createOpenAI = (options = {}) => {
             return isOpenAILiveModel(modelId) ? new OpenAILiveModel(modelId, baseURL, (providerOptions) => resolveOpenAIRealtimeHeaders(apiKey, providerOptions), options.realtimeConnectionFactory ?? openWebSocketConnection, realtimeURL, options.allowUnsafeEndpoints) : new OpenAIRealtimeModel(modelId, apiKey, baseURL, fetcher, options.realtimeConnectionFactory, realtimeURL, browserTokenURL, options.allowUnsafeEndpoints);
         },
         groundedLanguageModel: (modelId) => new OpenAIGroundedLanguageModel(modelId, apiKey, baseURL, fetcher),
-        rawFetch: fetcher,
+        rawFetch,
         agents: new OpenAIAgentsClient(baseURL, apiKey, fetcher, options.allowUnsafeEndpoints)
     });
 };
@@ -1907,9 +2087,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",
@@ -2011,7 +2192,8 @@ export const openAIShellTool = (config = {}) => ({
 });
 const applyOpenAIPatchOperation = async (operation, config) => {
     if (config.rootDir) {
-        await assertOpenAIToolPathInsideRoot(config.rootDir, operation.path, "apply_patch");
+        const safePath = await assertOpenAIToolPathInsideRoot(config.rootDir, operation.path, "apply_patch");
+        return config.applyOperation({ ...operation, path: safePath });
     }
     return config.applyOperation(operation);
 };