openai 6.47.0 → 6.49.0

package/src/helpers/zod.ts

@@ -13,6 +13,7 @@ import {
 import { zodToJsonSchema as _zodToJsonSchema } from '../_vendor/zod-to-json-schema';
 import { AutoParseableResponseTool, makeParseableResponseTool } from '../lib/ResponsesParser';
 import { type ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
+import { type RealtimeFunctionTool } from '../resources/realtime/realtime';
 import { toStrictJsonSchema } from '../lib/transform';
 import { JSONSchema } from '../lib/jsonschema';
 
@@ -37,38 +38,134 @@ type InferZodType<T extends ZodTypeLike> =
   : T extends { _zod: { output: infer Output } } ? Output
   : never;
 
-function zodV3ToJsonSchema(schema: z3.ZodType, options: { name: string }): Record<string, unknown> {
-  return _zodToJsonSchema(schema, {
+type ZodSchemaDefinitions = Record<string, ZodTypeLike>;
+
+type ZodResponseFormatProps = Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'> & {
+  /**
+   * Schemas to extract into the generated JSON Schema definitions.
+   * Use this to reuse large shared schemas instead of inlining them at every occurrence.
+   */
+  schemaDefinitions?: ZodSchemaDefinitions | undefined;
+};
+
+function encodeSchemaDefinitionRefToken(token: string): string {
+  return encodeURIComponent(token.replace(/~/g, '~0').replace(/\//g, '~1'));
+}
+
+function validateSchemaDefinitions(schemaDefinitions: ZodSchemaDefinitions | undefined): void {
+  if (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, '__proto__')) {
+    throw new Error('schemaDefinitions cannot include "__proto__" as a definition name');
+  }
+}
+
+function escapeSchemaDefinitionRefs<T extends object>(
+  schema: T,
+  schemaDefinitions: ZodSchemaDefinitions | undefined,
+): T {
+  const refReplacements = new Map(
+    Object.keys(schemaDefinitions ?? {}).map((name) => [
+      `#/definitions/${name}`,
+      `#/definitions/${encodeSchemaDefinitionRefToken(name)}`,
+    ]),
+  );
+
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') return;
+
+    if (Array.isArray(value)) {
+      for (const child of value) visit(child);
+      return;
+    }
+
+    const record = value as Record<string, unknown>;
+    const ref = record['$ref'];
+    if (typeof ref === 'string') {
+      record['$ref'] = refReplacements.get(ref) ?? ref;
+    }
+
+    for (const child of Object.values(record)) visit(child);
+  };
+
+  visit(schema);
+  return schema;
+}
+
+function getZodV3RootName(name: string, schemaDefinitions: ZodSchemaDefinitions | undefined): string {
+  let rootName = name;
+  while (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, rootName)) {
+    rootName = `${rootName}_root`;
+  }
+  return rootName;
+}
+
+function zodV3ToJsonSchema(
+  schema: z3.ZodType,
+  options: { name: string; schemaDefinitions?: ZodSchemaDefinitions | undefined },
+): Record<string, unknown> {
+  const rootName = getZodV3RootName(options.name, options.schemaDefinitions);
+  const jsonSchema = _zodToJsonSchema(schema, {
     openaiStrictMode: true,
-    name: options.name,
+    name: rootName,
     nameStrategy: 'duplicate-ref',
     $refStrategy: 'extract-to-root',
     nullableStrategy: 'property',
+    ...(options.schemaDefinitions ?
+      { definitions: options.schemaDefinitions as unknown as Record<string, z3.ZodType> }
+    : undefined),
   });
+
+  return escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
 }
 
-function zodV4ToJsonSchema(schema: ZodV4Schema): Record<string, unknown> {
-  return toStrictJsonSchema(
-    z4.toJSONSchema(schema, {
-      target: 'draft-7',
-      override: ({ zodSchema, jsonSchema }) => {
-        const def = zodSchema._zod.def;
-
-        if (def.type === 'union' && 'discriminator' in def && Array.isArray(jsonSchema.oneOf)) {
-          if (jsonSchema.anyOf !== undefined) {
-            throw new Error(
-              'Zod discriminated union generated both `anyOf` and `oneOf`, which cannot be represented in an OpenAI strict schema',
-            );
-          }
-
-          // Discriminator values are mutually exclusive, so anyOf preserves the
-          // union while staying inside the API's supported JSON Schema subset.
-          jsonSchema.anyOf = jsonSchema.oneOf;
-          delete jsonSchema.oneOf;
+function zodV4ToJsonSchema(
+  schema: ZodV4Schema,
+  options: { schemaDefinitions?: ZodSchemaDefinitions | undefined } = {},
+): Record<string, unknown> {
+  const metadata = options.schemaDefinitions ? z4.registry<Record<string, unknown>>() : undefined;
+  for (const [name, definition] of Object.entries(options.schemaDefinitions ?? {})) {
+    metadata?.add(definition as unknown as z4.ZodType, { id: name });
+  }
+
+  const jsonSchema = z4.toJSONSchema(schema, {
+    target: 'draft-7',
+    ...(metadata ? { metadata } : undefined),
+    override: ({ zodSchema, jsonSchema }) => {
+      const def = zodSchema._zod.def;
+
+      if (def.type === 'union' && 'discriminator' in def && Array.isArray(jsonSchema.oneOf)) {
+        if (jsonSchema.anyOf !== undefined) {
+          throw new Error(
+            'Zod discriminated union generated both `anyOf` and `oneOf`, which cannot be represented in an OpenAI strict schema',
+          );
         }
-      },
-    }) as JSONSchema,
-  ) as Record<string, unknown>;
+
+        // Discriminator values are mutually exclusive, so anyOf preserves the
+        // union while staying inside the API's supported JSON Schema subset.
+        jsonSchema.anyOf = jsonSchema.oneOf;
+        delete jsonSchema.oneOf;
+      }
+    },
+  }) as JSONSchema;
+
+  const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+
+  return toStrictJsonSchema(escapedSchema) as Record<string, unknown>;
+}
+
+function zodV3ToNonStrictJsonSchema(schema: z3.ZodType, options: { name: string }): Record<string, unknown> {
+  return _zodToJsonSchema(schema, {
+    name: options.name,
+    nameStrategy: 'duplicate-ref',
+    $refStrategy: 'extract-to-root',
+    pipeStrategy: 'input',
+  });
+}
+
+function zodV4ToNonStrictJsonSchema(schema: ZodV4Schema): Record<string, unknown> {
+  return z4.toJSONSchema(schema, {
+    target: 'draft-7',
+    io: 'input',
+  }) as Record<string, unknown>;
 }
 
 function isZodV4(zodObject: ZodSchema): zodObject is ZodV4Schema {
@@ -129,18 +226,23 @@ function parseZodObject<ZodInput extends ZodTypeLike>(
 export function zodResponseFormat<ZodInput extends ZodTypeLike>(
   zodObject: ZodInput,
   name: string,
-  props?: Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'>,
+  props?: ZodResponseFormatProps,
 ): AutoParseableResponseFormat<InferZodType<ZodInput>> {
   const zodSchema = zodObject as unknown as ZodSchema;
+  const { schemaDefinitions, ...responseFormatProps } = props ?? {};
+  validateSchemaDefinitions(schemaDefinitions);
 
   return makeParseableResponseFormat<InferZodType<ZodInput>>(
     {
       type: 'json_schema',
       json_schema: {
-        ...props,
+        ...responseFormatProps,
         name,
         strict: true,
-        schema: isZodV4(zodSchema) ? zodV4ToJsonSchema(zodSchema) : zodV3ToJsonSchema(zodSchema, { name }),
+        schema:
+          isZodV4(zodSchema) ?
+            zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
+          : zodV3ToJsonSchema(zodSchema, { name, schemaDefinitions }),
       },
     },
     (content) => parseZodObject(zodObject, content),
@@ -177,7 +279,7 @@ export function zodFunction<Parameters extends ZodTypeLike>(options: {
   function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
   description?: string | undefined;
 }): AutoParseableTool<{
-  arguments: Parameters;
+  arguments: InferZodType<Parameters>;
   name: string;
   function: (args: InferZodType<Parameters>) => unknown;
 }> {
@@ -210,7 +312,7 @@ export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
   function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
   description?: string | undefined;
 }): AutoParseableResponseTool<{
-  arguments: Parameters;
+  arguments: InferZodType<Parameters>;
   name: string;
   function: (args: InferZodType<Parameters>) => unknown;
 }> {
@@ -233,3 +335,30 @@ export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
     },
   );
 }
+
+/**
+ * Creates a Realtime API `function` tool definition from the given Zod schema.
+ *
+ * Unlike {@link zodResponsesFunction}, this helper does not add `strict`
+ * because Realtime function tools do not support that field.
+ *
+ * This helper only creates the tool definition. Parse function-call arguments
+ * from Realtime events with the original Zod schema.
+ */
+export function zodRealtimeFunction<Parameters extends ZodTypeLike>(options: {
+  name: string;
+  parameters: Parameters;
+  description?: string | undefined;
+}): RealtimeFunctionTool {
+  const zodSchema = options.parameters as unknown as ZodSchema;
+
+  return {
+    type: 'function',
+    name: options.name,
+    parameters:
+      isZodV4(zodSchema) ?
+        zodV4ToNonStrictJsonSchema(zodSchema)
+      : zodV3ToNonStrictJsonSchema(zodSchema, { name: options.name }),
+    ...(options.description ? { description: options.description } : undefined),
+  };
+}

package/src/internal/headers.ts

@@ -12,6 +12,7 @@ export type HeadersLike =
   | NullableHeaders;
 
 const brand_privateNullableHeaders = /* @__PURE__ */ Symbol('brand.privateNullableHeaders');
+const httpTokenHeaderName = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
 /**
  * @internal
@@ -74,16 +75,19 @@ export const buildHeaders = (newHeaders: HeadersLike[]): NullableHeaders => {
   for (const headers of newHeaders) {
     const seenHeaders = new Set<string>();
     for (const [name, value] of iterateHeaders(headers)) {
+      if (!httpTokenHeaderName.test(name)) {
+        throw new TypeError(`Header name must be a valid HTTP token ["${name}"]`);
+      }
       const lowerName = name.toLowerCase();
       if (!seenHeaders.has(lowerName)) {
-        targetHeaders.delete(name);
+        targetHeaders.delete(lowerName);
         seenHeaders.add(lowerName);
       }
       if (value === null) {
-        targetHeaders.delete(name);
+        targetHeaders.delete(lowerName);
         nullHeaders.add(lowerName);
       } else {
-        targetHeaders.append(name, value);
+        targetHeaders.append(lowerName, value);
         nullHeaders.delete(lowerName);
       }
     }

package/src/lib/AbstractChatCompletionRunner.ts

@@ -5,6 +5,7 @@ import { uuid4 } from '../internal/utils/uuid';
 import { isAutoParsableTool, parseChatCompletion } from '../lib/parser';
 import type {
   ChatCompletion,
+  ChatCompletionAssistantMessageParam,
   ChatCompletionCreateParams,
   ChatCompletionMessage,
   ChatCompletionMessageFunctionToolCall,
@@ -49,6 +50,47 @@ function normalizeToolCallIds(chatCompletion: ChatCompletion): void {
   }
 }
 
+/**
+ * Parsed completions contain response-only and helper-only fields. Keep those
+ * on runner.messages for callers, but only replay valid request fields.
+ */
+function toRequestMessage(message: ChatCompletionMessageParam): ChatCompletionMessageParam {
+  if (!isAssistantMessage(message)) return message;
+
+  const requestMessage: ChatCompletionAssistantMessageParam = { role: 'assistant' };
+
+  if (message.audio != null) requestMessage.audio = { id: message.audio.id };
+  if (message.content !== undefined) requestMessage.content = message.content;
+  if (message.function_call != null) requestMessage.function_call = message.function_call;
+  if (message.name !== undefined) requestMessage.name = message.name;
+  if (message.refusal != null) requestMessage.refusal = message.refusal;
+  if (message.tool_calls !== undefined) {
+    requestMessage.tool_calls = message.tool_calls.map((toolCall) => {
+      if (toolCall.type === 'custom') {
+        return {
+          id: toolCall.id,
+          type: toolCall.type,
+          custom: {
+            input: toolCall.custom.input,
+            name: toolCall.custom.name,
+          },
+        };
+      }
+
+      return {
+        id: toolCall.id,
+        type: toolCall.type,
+        function: {
+          arguments: toolCall.function.arguments,
+          name: toolCall.function.name,
+        },
+      };
+    });
+  }
+
+  return requestMessage;
+}
+
 export interface ChatCompletionRunnerContext {
   messages: ChatCompletionMessageParam[];
   abort(): void;
@@ -413,7 +455,7 @@ export class AbstractChatCompletionRunner<
           ...restParams,
           tool_choice,
           tools,
-          messages: [...this.messages],
+          messages: this.messages.map(toRequestMessage),
         },
         options,
       );

package/src/lib/ChatCompletionStream.ts

@@ -20,6 +20,7 @@ import {
 } from '../lib/parser';
 import { ChatCompletionFunctionTool, ParsedChatCompletion } from '../resources/chat/completions';
 import {
+  type ChatCompletionAudio,
   ChatCompletionTokenLogprob,
   type ChatCompletion,
   type ChatCompletionChunk,
@@ -196,12 +197,14 @@ export class ChatCompletionStream<ParsedT = null>
   implements AsyncIterable<ChatCompletionChunk>
 {
   #params: ChatCompletionCreateParams | null;
+  #audioDoneChoiceIndexes: Set<number>;
   #choiceEventStates: ChoiceEventState[];
   #currentChatCompletionSnapshot: ChatCompletionSnapshot | undefined;
 
   constructor(params: ChatCompletionCreateParams | null) {
     super();
     this.#params = params;
+    this.#audioDoneChoiceIndexes = new Set();
     this.#choiceEventStates = [];
   }
 
@@ -240,6 +243,7 @@ export class ChatCompletionStream<ParsedT = null>
 
   #beginRequest() {
     if (this.ended) return;
+    this.#audioDoneChoiceIndexes = new Set();
     this.#currentChatCompletionSnapshot = undefined;
   }
 
@@ -428,9 +432,11 @@ export class ChatCompletionStream<ParsedT = null>
     if (!snapshot) {
       throw new OpenAIError(`request ended without sending any chunks`);
     }
+    const audioDoneChoiceIndexes = this.#audioDoneChoiceIndexes;
+    this.#audioDoneChoiceIndexes = new Set();
     this.#currentChatCompletionSnapshot = undefined;
     this.#choiceEventStates = [];
-    return finalizeChatCompletion(snapshot, this.#params);
+    return finalizeChatCompletion(snapshot, this.#params, audioDoneChoiceIndexes);
   }
 
   protected override async _createChatCompletion(
@@ -575,15 +581,41 @@ export class ChatCompletionStream<ParsedT = null>
 
       if (!delta) continue; // Shouldn't happen; just in case.
 
-      const { content, refusal, function_call, role, tool_calls, ...rest } = delta;
+      this.#audioDoneChoiceIndexes.delete(index);
+      const { audio, content, refusal, function_call, role, tool_calls, ...rest } = delta as typeof delta & {
+        audio?: Partial<ChatCompletionAudio> | null;
+      };
       assertIsEmpty(rest);
       Object.assign(choice.message, rest);
+      if (
+        audio?.expires_at != null &&
+        audio.id == null &&
+        audio.data == null &&
+        audio.transcript == null &&
+        content == null &&
+        refusal == null &&
+        function_call == null &&
+        role == null &&
+        tool_calls == null &&
+        Object.keys(rest).length === 0
+      ) {
+        this.#audioDoneChoiceIndexes.add(index);
+      }
 
       if (refusal) {
         choice.message.refusal = (choice.message.refusal || '') + refusal;
       }
 
       if (role) choice.message.role = role;
+      if (audio) {
+        const audioSnapshot = (choice.message.audio ??= {});
+        if (audio.id != null) audioSnapshot.id = audio.id;
+        if (audio.data != null) audioSnapshot.data = (audioSnapshot.data ?? '') + audio.data;
+        if (audio.transcript != null) {
+          audioSnapshot.transcript = (audioSnapshot.transcript ?? '') + audio.transcript;
+        }
+        if (audio.expires_at != null) audioSnapshot.expires_at = audio.expires_at;
+      }
       if (function_call) {
         if (!choice.message.function_call) {
           choice.message.function_call = function_call;
@@ -698,6 +730,7 @@ export class ChatCompletionStream<ParsedT = null>
 function finalizeChatCompletion<ParsedT>(
   snapshot: ChatCompletionSnapshot,
   params: ChatCompletionCreateParams | null,
+  audioDoneChoiceIndexes: ReadonlySet<number>,
 ): ParsedChatCompletion<ParsedT> {
   const { id, choices, created, model, system_fingerprint, ...rest } = snapshot;
   const completion: ChatCompletion = {
@@ -705,11 +738,16 @@ function finalizeChatCompletion<ParsedT>(
     id,
     choices: choices.map(
       ({ message, finish_reason, index, logprobs, ...choiceRest }): ChatCompletion.Choice => {
-        if (!finish_reason) {
+        const { content = null, function_call, tool_calls, audio, ...messageRest } = message;
+        // Audio streams can end with an expires_at-only chunk after the
+        // generated audio, without a separate finish_reason.
+        const finishReason =
+          finish_reason ?? (audioDoneChoiceIndexes.has(index) && isCompleteAudio(audio) ? 'stop' : null);
+        if (!finishReason) {
           throw new OpenAIError(`missing finish_reason for choice ${index}`);
         }
 
-        const { content = null, function_call, tool_calls, ...messageRest } = message;
+        const audioResponse = audio ? { audio: audio as ChatCompletionAudio } : {};
         const role = message.role as 'assistant'; // this is what we expect; in theory it could be different which would make our types a slight lie but would be fine.
         if (!role) {
           throw new OpenAIError(`missing role for choice ${index}`);
@@ -728,12 +766,13 @@ function finalizeChatCompletion<ParsedT>(
           return {
             ...choiceRest,
             message: {
+              ...audioResponse,
               content,
               function_call: { arguments: args, name },
               role,
               refusal: message.refusal ?? null,
             },
-            finish_reason,
+            finish_reason: finishReason,
             index,
             logprobs,
           };
@@ -743,10 +782,11 @@ function finalizeChatCompletion<ParsedT>(
           return {
             ...choiceRest,
             index,
-            finish_reason,
+            finish_reason: finishReason,
             logprobs,
             message: {
               ...messageRest,
+              ...audioResponse,
               role,
               content,
               refusal: message.refusal ?? null,
@@ -779,8 +819,8 @@ function finalizeChatCompletion<ParsedT>(
         }
         return {
           ...choiceRest,
-          message: { ...messageRest, content, role, refusal: message.refusal ?? null },
-          finish_reason,
+          message: { ...messageRest, ...audioResponse, content, role, refusal: message.refusal ?? null },
+          finish_reason: finishReason,
           index,
           logprobs,
         };
@@ -795,6 +835,12 @@ function finalizeChatCompletion<ParsedT>(
   return maybeParseChatCompletion(completion, params);
 }
 
+function isCompleteAudio(
+  audio: Partial<ChatCompletionAudio> | null | undefined,
+): audio is ChatCompletionAudio {
+  return audio?.id != null && audio.data != null && audio.transcript != null && audio.expires_at != null;
+}
+
 function str(x: unknown) {
   return JSON.stringify(x);
 }
@@ -875,6 +921,8 @@ export namespace ChatCompletionSnapshot {
        */
       content?: string | null;
 
+      audio?: Partial<ChatCompletionAudio> | null;
+
       refusal?: string | null;
 
       parsed?: unknown | null;

package/src/lib/ResponsesParser.ts

@@ -74,10 +74,7 @@ export function parseResponse<
   const output: Array<ParsedResponseOutputItem<ParsedT>> = response.output.map(
     (item): ParsedResponseOutputItem<ParsedT> => {
       if (item.type === 'function_call') {
-        return {
-          ...item,
-          parsed_arguments: shouldParse ? parseToolCall(params, item) : null,
-        };
+        return shouldParse ? parseToolCall(params, item) : { ...item, parsed_arguments: null };
       }
       if (item.type === 'message') {
         const content: Array<ParsedContent<ParsedT>> = item.content.map((content) => {
@@ -149,7 +146,12 @@ export function hasAutoParseableInput(params: ResponseCreateParamsWithTools): bo
     return true;
   }
 
-  return false;
+  return (
+    Array.isArray(params.tools) &&
+    params.tools.some(
+      (tool) => isAutoParsableTool(tool) || (tool.type === 'function' && tool.strict === true),
+    )
+  );
 }
 
 type ToolOptions = {

package/src/lib/jsonschema.ts

@@ -61,6 +61,7 @@ export type JSONSchemaVersion = string;
  */
 export type JSONSchemaDefinition = JSONSchema | boolean;
 export interface JSONSchema {
+  $schema?: JSONSchemaVersion | undefined;
   $id?: string | undefined;
   $comment?: string | undefined;
 
@@ -86,6 +87,8 @@ export interface JSONSchema {
   maxLength?: number | undefined;
   minLength?: number | undefined;
   pattern?: string | undefined;
+  contentEncoding?: string | undefined;
+  contentMediaType?: string | undefined;
 
   /**
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4