@builder.io/ai-utils 0.81.3 → 0.82.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.81.3",
+  "version": "0.82.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/codegen/investigation-context.d.ts

@@ -18,5 +18,5 @@ export interface BuildInvestigationSystemPromptInput {
     event: InvestigationEvent;
     completionJson: InvestigationCompletionJSON | undefined;
 }
-export declare function buildInvestigationSystemPrompt({ event, completionJson }: BuildInvestigationSystemPromptInput): string;
+export declare function buildInvestigationSystemPrompt({ event, completionJson, }: BuildInvestigationSystemPromptInput): string;
 export declare const SUGGESTED_QUESTIONS: readonly string[];

package/src/codegen.d.ts

@@ -2890,6 +2890,8 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
     systemReminderPrompt: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type CodeGenInputOptions = z.infer<typeof CodeGenInputOptionsSchema> & {
+    /** @internal Derived from BuilderEditorState.components for editor AI. */
+    _allowedComponentNames?: string[];
     /**
      * Optional factory function to wrap the MCP client with custom behavior
      * Used by Editor AI to add permission checks for model operations
@@ -3950,6 +3952,13 @@ export interface MCPAuthRequiredServer {
     authorizationUrl: string;
     scopes: string[];
     isReauth: boolean;
+    /**
+     * Server opted in to the LLM-driven `__authenticate` flow via its Firestore
+     * `useAuthenticateTool` field. Servers opted in this way (or, org-wide, via
+     * the `codegen-tool-mcp-authenticate` LD flag) get a synthetic auth tool
+     * instead of a blocking `mcp-auth-required` event.
+     */
+    useAuthenticateTool?: boolean;
 }
 export interface GenerateCodeEventMCPAuthRequired {
     type: "mcp-auth-required";

package/src/completion.d.ts

@@ -99,7 +99,8 @@ export interface BuilderEditorState {
      */
     content?: BuilderContent;
     /**
-     * Builder custom components.
+     * Components available in the Builder editor, including built-ins.
+     * When present, editor AI restricts generated content to this list.
      */
     components?: Component[];
     /**

package/src/editor-ai.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const EDITOR_AI_READ_DEFAULT_LIMIT = 250;
+export declare const EDITOR_AI_READ_MAX_LIMIT = 1500;
+export declare const EditorAiReadRequestSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    activeLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EditorAiReadRequest = z.infer<typeof EditorAiReadRequestSchema>;
+export declare const EditorAiReadResponseSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    totalLines: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    activeLocale: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type EditorAiReadResponse = z.infer<typeof EditorAiReadResponseSchema>;
+export declare const EditorAiEditRequestSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    old_str: z.ZodString;
+    new_str: z.ZodString;
+    activeLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EditorAiEditRequest = z.infer<typeof EditorAiEditRequestSchema>;
+export declare const EditorAiEditResponseSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    patch: z.ZodString;
+    modifiedBuilderContent: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type EditorAiEditResponse = z.infer<typeof EditorAiEditResponseSchema>;
+export declare const EditorAiWriteRequestSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    content: z.ZodString;
+    activeLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EditorAiWriteRequest = z.infer<typeof EditorAiWriteRequestSchema>;
+export declare const EditorAiWriteResponseSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    modifiedBuilderContent: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type EditorAiWriteResponse = z.infer<typeof EditorAiWriteResponseSchema>;
+export type EditorAiErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "NO_MATCH" | "VALIDATION_FAILED" | "INTERNAL";
+export declare const EditorAiErrorBodySchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EditorAiErrorBody = z.infer<typeof EditorAiErrorBodySchema>;

package/src/editor-ai.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+// Request/response contracts for the stateless /editor/read|edit|write
+// endpoints. Shared so the Builder CMS MCP server reuses the same shapes.
+export const EDITOR_AI_READ_DEFAULT_LIMIT = 250;
+export const EDITOR_AI_READ_MAX_LIMIT = 1500;
+export const EditorAiReadRequestSchema = z
+    .object({
+    contentId: z.string().min(1),
+    offset: z.number().int().min(0).optional(),
+    limit: z.number().int().min(1).max(EDITOR_AI_READ_MAX_LIMIT).optional(),
+    // Locale to operate on; defaults to "Default" when omitted.
+    activeLocale: z.string().min(1).optional(),
+})
+    .meta({ title: "EditorAiReadRequest" });
+export const EditorAiReadResponseSchema = z
+    .object({
+    contentId: z.string(),
+    totalLines: z.number().int(),
+    offset: z.number().int(),
+    limit: z.number().int(),
+    activeLocale: z.string(),
+    content: z.string(),
+})
+    .meta({ title: "EditorAiReadResponse" });
+export const EditorAiEditRequestSchema = z
+    .object({
+    contentId: z.string().min(1),
+    old_str: z
+        .string()
+        .min(1)
+        .refine((s) => s.trim().length > 0, {
+        message: "old_str must not be only whitespace",
+    }),
+    new_str: z.string(),
+    // Locale to operate on; defaults to "Default" when omitted.
+    activeLocale: z.string().min(1).optional(),
+})
+    .meta({ title: "EditorAiEditRequest" });
+export const EditorAiEditResponseSchema = z
+    .object({
+    contentId: z.string(),
+    patch: z.string(),
+    modifiedBuilderContent: z.record(z.string(), z.unknown()),
+})
+    .meta({ title: "EditorAiEditResponse" });
+export const EditorAiWriteRequestSchema = z
+    .object({
+    contentId: z.string().min(1),
+    content: z.string().min(1),
+    // Locale to operate on; defaults to "Default" when omitted.
+    activeLocale: z.string().min(1).optional(),
+})
+    .meta({ title: "EditorAiWriteRequest" });
+export const EditorAiWriteResponseSchema = z
+    .object({
+    contentId: z.string(),
+    modifiedBuilderContent: z.record(z.string(), z.unknown()),
+})
+    .meta({ title: "EditorAiWriteResponse" });
+export const EditorAiErrorBodySchema = z
+    .object({
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        hint: z.string().optional(),
+        details: z.record(z.string(), z.unknown()).optional(),
+    }),
+})
+    .meta({ title: "EditorAiErrorBody" });

package/src/editor-ai.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/editor-ai.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { EditorAiEditRequestSchema } from "./editor-ai.js";
+describe("EditorAiEditRequestSchema", () => {
+    it("accepts an old_str with real content (whitespace preserved)", () => {
+        const parsed = EditorAiEditRequestSchema.parse({
+            contentId: "c1",
+            old_str: '      <Text text="hi" />',
+            new_str: '      <Text text="bye" />',
+        });
+        // Value is not trimmed — exact indentation is preserved for matching.
+        expect(parsed.old_str).toBe('      <Text text="hi" />');
+    });
+    it("rejects an empty old_str", () => {
+        const result = EditorAiEditRequestSchema.safeParse({
+            contentId: "c1",
+            old_str: "",
+            new_str: "x",
+        });
+        expect(result.success).toBe(false);
+    });
+    it("rejects a whitespace-only old_str", () => {
+        const result = EditorAiEditRequestSchema.safeParse({
+            contentId: "c1",
+            old_str: "   \n\t",
+            new_str: "x",
+        });
+        expect(result.success).toBe(false);
+    });
+    it("allows an empty new_str (delete)", () => {
+        const result = EditorAiEditRequestSchema.safeParse({
+            contentId: "c1",
+            old_str: '<Text text="hi" />',
+            new_str: "",
+        });
+        expect(result.success).toBe(true);
+    });
+});

package/src/index.d.ts

@@ -19,4 +19,6 @@ export * from "./connectivity/types.js";
 export * from "./connectivity/classify.js";
 export * from "./single-tenancy.js";
 export * from "./design-systems.js";
+export * from "./editor-ai.js";
+export * from "./realtime.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/index.js

@@ -19,4 +19,6 @@ export * from "./connectivity/types.js";
 export * from "./connectivity/classify.js";
 export * from "./single-tenancy.js";
 export * from "./design-systems.js";
+export * from "./editor-ai.js";
+export * from "./realtime.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/messages.d.ts

@@ -93,6 +93,14 @@ export interface MCPServerURLDefinition {
     serverId: string;
     disabled: boolean;
     clientName?: string;
+    /**
+     * Per-server opt-in to the LLM-driven `mcp__<name>__authenticate` flow,
+     * independent of the `codegen-tool-mcp-authenticate` LD flag. Set on the
+     * Firestore `mcpServers` doc to roll the tool out to one server at a time;
+     * the LD flag remains the org-wide switch. Either being true opts the
+     * server in, so the flag can still turn it on everywhere at once.
+     */
+    useAuthenticateTool?: boolean;
 }
 export interface MCPServerToolConfiguration {
     allowed_tools?: Array<string> | null;
@@ -119,6 +127,13 @@ export interface MCPServerDoc<TCreateDate = unknown, TLegacyTokenExpiresAt = nev
     disabled?: boolean;
     clientName: string | undefined;
     tool_configuration?: MCPServerToolConfiguration | null;
+    /**
+     * Opt this server in to the LLM-driven `mcp__<name>__authenticate` tool
+     * instead of the blocking `mcp-auth-required` event, without turning on the
+     * org-wide `codegen-tool-mcp-authenticate` LD flag. Lets a single MCP server
+     * ship on the tool path ahead of the rest.
+     */
+    useAuthenticateTool?: boolean;
     oauthMetadata?: MCPServerOAuthMetadata | null;
     authorizationToken?: string;
     refreshToken?: string | null;

package/src/projects.d.ts

@@ -909,12 +909,6 @@ export interface Project {
     deletedAt?: InMigrationDateNullable;
     /** User ID of whoever deleted the project. */
     deletedBy?: string;
-    /**
-     * When true, branches are stored in the standalone `branches` collection
-     * instead of embedded in project.branches field.
-     * Defaults to false for backwards compatibility with existing projects.
-     */
-    useBranchesCollection?: boolean;
     /** When true, the project is in code-only mode */
     codeOnlyMode?: boolean;
     /**
@@ -1075,8 +1069,6 @@ export interface CreateProjectOptions {
     autoApplySetup?: boolean;
     templateId?: string;
     useInternalHost?: boolean;
-    /** Store branches in the standalone `branches` collection vs embedded in the project doc. */
-    useBranchesCollection?: boolean;
     /** @internal Read-only source repo cloned to bootstrap the project. Carried through to Firestore. */
     templateRepoUrl?: string;
     /** @internal First-class hosting config copied from the template. Carried through to Firestore. */
@@ -1728,7 +1720,6 @@ export declare const CloneProjectOptionsSchema: z.ZodObject<{
     }>;
     userEmail: z.ZodOptional<z.ZodString>;
     useKube: z.ZodDefault<z.ZodBoolean>;
-    useBranchesCollection: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type CloneProjectOptions = z.infer<typeof CloneProjectOptionsSchema>;
 export declare const DuplicateBranchOptionsSchema: z.ZodObject<{

package/src/projects.js

@@ -640,13 +640,6 @@ export const CloneProjectOptionsSchema = z.object({
     useKube: z.boolean().default(false).meta({
         description: "Whether to provision on cloud-v2 (Kubernetes). Defaults to false.",
     }),
-    useBranchesCollection: z
-        .boolean()
-        .default(false)
-        .meta({
-        description: "Whether the new project stores branches in the standalone `branches` " +
-            "collection rather than embedded in the project doc. Defaults to false.",
-    }),
 });
 export const DuplicateBranchOptionsSchema = z.object({
     projectId: z.string().min(1).meta({

package/src/proxy.d.ts

@@ -20,7 +20,7 @@ export interface ProxyConfig {
  *
  * `proxyDestination` is always passed through unchanged.
  */
-export declare function getProxyConfig({ devServerUrl, proxyOrigin, proxyDefaultOrigin, proxyDestination }: ProxyConfig): {
+export declare function getProxyConfig({ devServerUrl, proxyOrigin, proxyDefaultOrigin, proxyDestination, }: ProxyConfig): {
     proxyOrigin: string | undefined;
     proxyDefaultOrigin: string | undefined;
     proxyDestination: string | undefined;

package/src/realtime.d.ts

@@ -0,0 +1,232 @@
+import { z } from "zod";
+export declare const BUILDER_REALTIME_MODEL: "gpt-realtime-2.1";
+export declare const BUILDER_REALTIME_MAX_SDP_LENGTH = 256000;
+export declare const BUILDER_REALTIME_MAX_SESSION_BYTES = 64000;
+export declare const OpenAIRealtimeFunctionToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type OpenAIRealtimeFunctionTool = z.infer<typeof OpenAIRealtimeFunctionToolSchema>;
+export declare const OpenAIRealtimeMcpToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"mcp">;
+    server_label: z.ZodString;
+    server_url: z.ZodOptional<z.ZodURL>;
+    server_description: z.ZodOptional<z.ZodString>;
+    authorization: z.ZodOptional<z.ZodString>;
+    allowed_tools: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    require_approval: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        always: "always";
+        never: "never";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+}, z.core.$strip>;
+export type OpenAIRealtimeMcpTool = z.infer<typeof OpenAIRealtimeMcpToolSchema>;
+export declare const OpenAIRealtimeToolSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"mcp">;
+    server_label: z.ZodString;
+    server_url: z.ZodOptional<z.ZodURL>;
+    server_description: z.ZodOptional<z.ZodString>;
+    authorization: z.ZodOptional<z.ZodString>;
+    allowed_tools: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    require_approval: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        always: "always";
+        never: "never";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+}, z.core.$strip>], "type">;
+export type OpenAIRealtimeTool = z.infer<typeof OpenAIRealtimeToolSchema>;
+/**
+ * The subset of OpenAI's Realtime session configuration accepted by Builder
+ * Connect. Zod objects intentionally strip unknown keys before this config is
+ * forwarded to OpenAI.
+ */
+export declare const OpenAIRealtimeSessionConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"realtime">;
+    model: z.ZodLiteral<"gpt-realtime-2.1">;
+    output_modalities: z.ZodTuple<[z.ZodLiteral<"audio">], null>;
+    instructions: z.ZodOptional<z.ZodString>;
+    audio: z.ZodOptional<z.ZodObject<{
+        input: z.ZodOptional<z.ZodObject<{
+            format: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+            noise_reduction: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                type: z.ZodEnum<{
+                    far_field: "far_field";
+                    near_field: "near_field";
+                }>;
+            }, z.core.$strip>>>;
+            transcription: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                model: z.ZodLiteral<"gpt-4o-mini-transcribe">;
+                language: z.ZodOptional<z.ZodString>;
+                prompt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            turn_detection: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                type: z.ZodEnum<{
+                    semantic_vad: "semantic_vad";
+                    server_vad: "server_vad";
+                }>;
+                threshold: z.ZodOptional<z.ZodNumber>;
+                prefix_padding_ms: z.ZodOptional<z.ZodNumber>;
+                silence_duration_ms: z.ZodOptional<z.ZodNumber>;
+                idle_timeout_ms: z.ZodOptional<z.ZodNumber>;
+                eagerness: z.ZodOptional<z.ZodEnum<{
+                    auto: "auto";
+                    high: "high";
+                    low: "low";
+                    medium: "medium";
+                }>>;
+                create_response: z.ZodOptional<z.ZodBoolean>;
+                interrupt_response: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        output: z.ZodOptional<z.ZodObject<{
+            format: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+            voice: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strip>]>>;
+            speed: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        strict: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"mcp">;
+        server_label: z.ZodString;
+        server_url: z.ZodOptional<z.ZodURL>;
+        server_description: z.ZodOptional<z.ZodString>;
+        authorization: z.ZodOptional<z.ZodString>;
+        allowed_tools: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        require_approval: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            always: "always";
+            never: "never";
+        }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    }, z.core.$strip>], "type">>>;
+    tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+        required: "required";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"mcp">;
+        server_label: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    max_output_tokens: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"inf">, z.ZodNumber]>>;
+    prompt: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    tracing: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
+    truncation: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        disabled: "disabled";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type OpenAIRealtimeSessionConfig = z.infer<typeof OpenAIRealtimeSessionConfigSchema>;
+export declare const BuilderRealtimeSessionRequestSchema: z.ZodObject<{
+    sdp: z.ZodString;
+    session: z.ZodObject<{
+        type: z.ZodLiteral<"realtime">;
+        model: z.ZodLiteral<"gpt-realtime-2.1">;
+        output_modalities: z.ZodTuple<[z.ZodLiteral<"audio">], null>;
+        instructions: z.ZodOptional<z.ZodString>;
+        audio: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodObject<{
+                format: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+                noise_reduction: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        far_field: "far_field";
+                        near_field: "near_field";
+                    }>;
+                }, z.core.$strip>>>;
+                transcription: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                    model: z.ZodLiteral<"gpt-4o-mini-transcribe">;
+                    language: z.ZodOptional<z.ZodString>;
+                    prompt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                turn_detection: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        semantic_vad: "semantic_vad";
+                        server_vad: "server_vad";
+                    }>;
+                    threshold: z.ZodOptional<z.ZodNumber>;
+                    prefix_padding_ms: z.ZodOptional<z.ZodNumber>;
+                    silence_duration_ms: z.ZodOptional<z.ZodNumber>;
+                    idle_timeout_ms: z.ZodOptional<z.ZodNumber>;
+                    eagerness: z.ZodOptional<z.ZodEnum<{
+                        auto: "auto";
+                        high: "high";
+                        low: "low";
+                        medium: "medium";
+                    }>>;
+                    create_response: z.ZodOptional<z.ZodBoolean>;
+                    interrupt_response: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            output: z.ZodOptional<z.ZodObject<{
+                format: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+                voice: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    id: z.ZodString;
+                }, z.core.$strip>]>>;
+                speed: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"function">;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            strict: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"mcp">;
+            server_label: z.ZodString;
+            server_url: z.ZodOptional<z.ZodURL>;
+            server_description: z.ZodOptional<z.ZodString>;
+            authorization: z.ZodOptional<z.ZodString>;
+            allowed_tools: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+            require_approval: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                always: "always";
+                never: "never";
+            }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        }, z.core.$strip>], "type">>>;
+        tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            auto: "auto";
+            none: "none";
+            required: "required";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"function">;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"mcp">;
+            server_label: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        max_output_tokens: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"inf">, z.ZodNumber]>>;
+        prompt: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        tracing: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
+        truncation: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            auto: "auto";
+            disabled: "disabled";
+        }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type BuilderRealtimeSessionRequest = z.infer<typeof BuilderRealtimeSessionRequestSchema>;

package/src/realtime.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+export const BUILDER_REALTIME_MODEL = "gpt-realtime-2.1";
+export const BUILDER_REALTIME_MAX_SDP_LENGTH = 256000;
+export const BUILDER_REALTIME_MAX_SESSION_BYTES = 64000;
+const utf8ByteLength = (value) => new TextEncoder().encode(value).length;
+const boundedRecord = (maxBytes, message) => z.record(z.string(), z.unknown()).refine((value) => {
+    try {
+        return utf8ByteLength(JSON.stringify(value)) <= maxBytes;
+    }
+    catch (_a) {
+        return false;
+    }
+}, { message });
+const RealtimeAudioFormatSchema = z.union([
+    z.string().min(1).max(128),
+    boundedRecord(2048, "Audio format configuration is too large"),
+]);
+const RealtimeInputAudioSchema = z.object({
+    format: RealtimeAudioFormatSchema.optional(),
+    noise_reduction: z
+        .object({
+        type: z.enum(["near_field", "far_field"]),
+    })
+        .nullable()
+        .optional(),
+    transcription: z
+        .object({
+        model: z.literal("gpt-4o-mini-transcribe"),
+        language: z.string().min(1).max(32).optional(),
+        prompt: z.string().max(4096).optional(),
+    })
+        .nullable()
+        .optional(),
+    turn_detection: z
+        .object({
+        type: z.enum(["server_vad", "semantic_vad"]),
+        threshold: z.number().min(0).max(1).optional(),
+        prefix_padding_ms: z.number().int().min(0).max(10000).optional(),
+        silence_duration_ms: z.number().int().min(0).max(60000).optional(),
+        idle_timeout_ms: z.number().int().min(0).max(3600000).optional(),
+        eagerness: z.enum(["low", "medium", "high", "auto"]).optional(),
+        create_response: z.boolean().optional(),
+        interrupt_response: z.boolean().optional(),
+    })
+        .nullable()
+        .optional(),
+});
+const RealtimeOutputAudioSchema = z.object({
+    format: RealtimeAudioFormatSchema.optional(),
+    voice: z
+        .union([
+        z.string().min(1).max(128),
+        z.object({ id: z.string().min(1).max(256) }),
+    ])
+        .optional(),
+    speed: z.number().positive().max(4).optional(),
+});
+export const OpenAIRealtimeFunctionToolSchema = z.object({
+    type: z.literal("function"),
+    name: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-zA-Z0-9_-]+$/),
+    description: z.string().max(4096).optional(),
+    parameters: boundedRecord(32000, "Realtime tool parameter schema is too large").optional(),
+    strict: z.boolean().optional(),
+});
+export const OpenAIRealtimeMcpToolSchema = z.object({
+    type: z.literal("mcp"),
+    server_label: z.string().min(1).max(128),
+    server_url: z.url().max(2048).optional(),
+    server_description: z.string().max(4096).optional(),
+    authorization: z.string().min(1).max(8192).optional(),
+    allowed_tools: z
+        .union([
+        z.array(z.string().min(1).max(128)).max(64),
+        boundedRecord(8000, "MCP allowed-tools configuration is too large"),
+    ])
+        .optional(),
+    require_approval: z
+        .union([
+        z.enum(["always", "never"]),
+        boundedRecord(8000, "MCP approval configuration is too large"),
+    ])
+        .optional(),
+});
+export const OpenAIRealtimeToolSchema = z.discriminatedUnion("type", [
+    OpenAIRealtimeFunctionToolSchema,
+    OpenAIRealtimeMcpToolSchema,
+]);
+const OpenAIRealtimeToolChoiceSchema = z.union([
+    z.enum(["auto", "none", "required"]),
+    z.object({
+        type: z.literal("function"),
+        name: z.string().min(1).max(64),
+    }),
+    z.object({
+        type: z.literal("mcp"),
+        server_label: z.string().min(1).max(128),
+        name: z.string().min(1).max(128).optional(),
+    }),
+]);
+/**
+ * The subset of OpenAI's Realtime session configuration accepted by Builder
+ * Connect. Zod objects intentionally strip unknown keys before this config is
+ * forwarded to OpenAI.
+ */
+export const OpenAIRealtimeSessionConfigSchema = z
+    .object({
+    type: z.literal("realtime"),
+    model: z.literal(BUILDER_REALTIME_MODEL),
+    output_modalities: z.tuple([z.literal("audio")]),
+    instructions: z.string().max(32000).optional(),
+    audio: z
+        .object({
+        input: RealtimeInputAudioSchema.optional(),
+        output: RealtimeOutputAudioSchema.optional(),
+    })
+        .optional(),
+    tools: z.array(OpenAIRealtimeToolSchema).max(32).optional(),
+    tool_choice: OpenAIRealtimeToolChoiceSchema.optional(),
+    max_output_tokens: z
+        .union([z.literal("inf"), z.number().int().min(1).max(4096)])
+        .optional(),
+    prompt: z
+        .object({
+        id: z.string().min(1).max(256),
+        version: z.string().min(1).max(128).optional(),
+        variables: boundedRecord(16000, "Realtime prompt variables are too large").optional(),
+    })
+        .nullable()
+        .optional(),
+    tracing: z
+        .union([
+        z.literal("auto"),
+        boundedRecord(8000, "Realtime tracing configuration is too large"),
+    ])
+        .nullable()
+        .optional(),
+    truncation: z
+        .union([
+        z.enum(["auto", "disabled"]),
+        boundedRecord(2048, "Realtime truncation configuration is too large"),
+    ])
+        .optional(),
+    include: z.array(z.string().min(1).max(256)).max(16).optional(),
+})
+    .refine((session) => utf8ByteLength(JSON.stringify(session)) <=
+    BUILDER_REALTIME_MAX_SESSION_BYTES, { message: "Realtime session configuration is too large" });
+export const BuilderRealtimeSessionRequestSchema = z.object({
+    sdp: z
+        .string()
+        .min(1)
+        .max(BUILDER_REALTIME_MAX_SDP_LENGTH)
+        .refine((sdp) => sdp.trim().length > 0, { message: "SDP cannot be blank" }),
+    session: OpenAIRealtimeSessionConfigSchema,
+});

package/src/realtime.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/realtime.spec.js

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { BUILDER_REALTIME_MAX_SDP_LENGTH, BuilderRealtimeSessionRequestSchema, OpenAIRealtimeSessionConfigSchema, } from "./realtime.js";
+const validSession = {
+    type: "realtime",
+    model: "gpt-realtime-2.1",
+    output_modalities: ["audio"],
+    instructions: "Help the user operate their Builder app.",
+};
+describe("BuilderRealtimeSessionRequestSchema", () => {
+    it("accepts a bounded audio session with tools", () => {
+        var _a;
+        const result = BuilderRealtimeSessionRequestSchema.parse({
+            sdp: "v=0\r\no=- 1 1 IN IP4 127.0.0.1",
+            session: {
+                ...validSession,
+                audio: {
+                    input: {
+                        turn_detection: {
+                            type: "semantic_vad",
+                            eagerness: "auto",
+                            create_response: true,
+                            interrupt_response: true,
+                        },
+                    },
+                    output: { voice: "marin" },
+                },
+                tools: [
+                    {
+                        type: "function",
+                        name: "navigate",
+                        description: "Navigate within the app",
+                        parameters: {
+                            type: "object",
+                            properties: { path: { type: "string" } },
+                            required: ["path"],
+                        },
+                    },
+                ],
+            },
+        });
+        expect(result.session.model).toBe("gpt-realtime-2.1");
+        expect((_a = result.session.tools) === null || _a === void 0 ? void 0 : _a[0]).toMatchObject({
+            type: "function",
+            name: "navigate",
+        });
+    });
+    it("strips unknown request, session, and known nested config keys", () => {
+        const sdp = " v=0\r\n";
+        const result = BuilderRealtimeSessionRequestSchema.parse({
+            sdp,
+            ignoredRequestValue: "secret",
+            session: {
+                ...validSession,
+                ignoredSessionValue: "secret",
+                audio: {
+                    output: {
+                        voice: "marin",
+                        ignoredAudioValue: "secret",
+                    },
+                },
+            },
+        });
+        expect(result).toEqual({
+            sdp,
+            session: {
+                ...validSession,
+                audio: { output: { voice: "marin" } },
+            },
+        });
+    });
+    it.each([
+        [{ ...validSession, type: "transcription" }],
+        [{ ...validSession, model: "gpt-realtime" }],
+        [{ ...validSession, output_modalities: ["text"] }],
+        [{ ...validSession, output_modalities: ["audio", "text"] }],
+        [{ ...validSession, output_modalities: [] }],
+    ])("rejects unsupported sessions", (session) => {
+        expect(BuilderRealtimeSessionRequestSchema.safeParse({ sdp: "v=0", session })
+            .success).toBe(false);
+    });
+    it("rejects transcription models that do not match the metered rate", () => {
+        expect(OpenAIRealtimeSessionConfigSchema.safeParse({
+            ...validSession,
+            audio: {
+                input: { transcription: { model: "gpt-4o-transcribe" } },
+            },
+        }).success).toBe(false);
+    });
+    it("rejects empty and oversized SDP offers", () => {
+        expect(BuilderRealtimeSessionRequestSchema.safeParse({
+            sdp: "   ",
+            session: validSession,
+        }).success).toBe(false);
+        expect(BuilderRealtimeSessionRequestSchema.safeParse({
+            sdp: "x".repeat(BUILDER_REALTIME_MAX_SDP_LENGTH + 1),
+            session: validSession,
+        }).success).toBe(false);
+    });
+    it("bounds instructions, tool count, and tool parameter schemas", () => {
+        expect(OpenAIRealtimeSessionConfigSchema.safeParse({
+            ...validSession,
+            instructions: "x".repeat(32001),
+        }).success).toBe(false);
+        expect(OpenAIRealtimeSessionConfigSchema.safeParse({
+            ...validSession,
+            tools: Array.from({ length: 33 }, (_, index) => ({
+                type: "function",
+                name: `tool_${index}`,
+            })),
+        }).success).toBe(false);
+        expect(OpenAIRealtimeSessionConfigSchema.safeParse({
+            ...validSession,
+            tools: [
+                {
+                    type: "function",
+                    name: "large_tool",
+                    parameters: { description: "x".repeat(32001) },
+                },
+            ],
+        }).success).toBe(false);
+    });
+});