@oxy.so/contracts 4.2.0 → 4.4.0

package/dist/cjs/inference/realtime.js

@@ -0,0 +1,826 @@
+"use strict";
+/**
+ * Realtime sessions — the one inference family that is not a request.
+ *
+ * Everything else in this contract is one-shot: an envelope goes in, a stream of
+ * events comes out, one terminal event ends it. A realtime session (OpenAI's
+ * Realtime and Live families, and any provider like them) is a long-lived,
+ * two-way conversation over a WebSocket: the client keeps appending audio,
+ * editing the conversation and asking for responses, and the server keeps
+ * answering, detecting speech, transcribing and being interrupted, for up to an
+ * hour. Forcing that through {@link inferenceRequestSchema} would make the
+ * request envelope mean two things, so it is its own family: a signed session
+ * request, a closed set of client COMMANDS and a closed set of server EVENTS.
+ *
+ * ## Identity, metering and settlement
+ *
+ * A session IS one request for attribution, metering and settlement:
+ * `attribution.requestId` names it, every command and event carries that
+ * `requestId`, and the session settles exactly once, through one
+ * `normalizedUsageReportSchema` for that request id, delivered by the transport
+ * after `session.closed` exactly as a one-shot stream delivers its report.
+ * `response.done` and `session.closed` carry units as MEASUREMENT EVIDENCE, the
+ * same standing `inferenceStreamUsageEventSchema` has: settleable units, never a
+ * settleable record. No upstream cost appears anywhere in this module.
+ *
+ * ## Routing
+ *
+ * A session names a model, never a routing profile, and is never substituted:
+ * every authorized route is `same_model`. The data plane may try the routes in
+ * order until one OPENS; once `session.created` has been sent the deployment is
+ * fixed for the session's life. There is no mid-session failover, because the
+ * conversation state lives upstream and a second provider does not have it.
+ *
+ * ## Framing
+ *
+ * Every WebSocket frame is ONE JSON text message: a command from the client, an
+ * event from the server. Binary frames are refused. Audio travels only as
+ * padded base64 inside `input_audio.append`, an `input_audio` content part or
+ * `output_audio.delta`, each bounded by {@link MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH}
+ * characters (48 KiB of audio, about one second of 24 kHz PCM16), and a
+ * session's total audio in each direction is bounded by its signed
+ * `limits`. Audio is never a text delta: a transcript is `transcript.delta`,
+ * spoken audio is `output_audio.delta`, and neither is `text.delta`.
+ *
+ * ## Commands are at-most-once
+ *
+ * Every command carries a client-chosen `commandId`, unique within the session,
+ * and the server answers each with `command.accepted` BEFORE applying it. So:
+ *
+ *  - A command whose acknowledgement arrived was applied, once.
+ *  - A command sent again with a `commandId` the server has already accepted is
+ *    NOT applied again: the server answers `command.accepted` with
+ *    `duplicate: true`. A client may therefore retry a command it is unsure of by
+ *    resending the SAME `commandId`, and only that way.
+ *  - A command whose write was AMBIGUOUS — the connection dropped before its
+ *    acknowledgement — is never replayed automatically by any hop. Resending it
+ *    under a NEW `commandId` is a new command, and appending the same audio twice
+ *    is exactly the double-metered input this rule exists to prevent.
+ *  - The data plane never replays a command upstream. If ITS upstream connection
+ *    drops, the upstream conversation is gone with it and the session ends with
+ *    `session.closed` (`upstream_closed` or `upstream_error`).
+ *
+ * ## Reconnect
+ *
+ * A dropped client connection does not end the session at once. For
+ * `resumeWindowMs` (declared by `session.created`, at most
+ * {@link MAX_REALTIME_RESUME_WINDOW_MS}) the client may open a new connection
+ * whose FIRST frame is a signed `session.resume` naming the last server
+ * `sequence` it processed. The server then replays every event after it, in
+ * order, emits `session.resumed`, and continues. Events are numbered from 0 by a
+ * single monotonic `sequence` per session, so a replayed event is recognisable
+ * as a duplicate rather than as new output. Past the window, or when the named
+ * sequence is no longer buffered, the resume is refused and the session closes
+ * (`resume_expired`): nothing is guessed. Commands are not part of the replay —
+ * see above.
+ *
+ * ## Authentication
+ *
+ * The session request and a `session.resume` are the first frame of their
+ * connection and are signed with the same edge signature the one-shot envelope
+ * carries, over that frame's exact bytes; the signature headers ride on the
+ * WebSocket upgrade. Every later frame is covered by the connection that
+ * signature opened.
+ *
+ * Decided in: OxyHQ/Kaana#90.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.realtimeTranscriptDoneEventSchema = exports.realtimeTranscriptDeltaEventSchema = exports.realtimeTranscriptSourceSchema = exports.realtimeOutputAudioDoneEventSchema = exports.realtimeOutputAudioDeltaEventSchema = exports.realtimeResponseCreatedEventSchema = exports.realtimeInputAudioClearedEventSchema = exports.realtimeInputAudioCommittedEventSchema = exports.realtimeSpeechStoppedEventSchema = exports.realtimeSpeechStartedEventSchema = exports.realtimeItemTruncatedEventSchema = exports.realtimeItemDeletedEventSchema = exports.realtimeItemDoneEventSchema = exports.realtimeItemAddedEventSchema = exports.realtimeCommandAcceptedEventSchema = exports.realtimeSessionResumedEventSchema = exports.realtimeSessionUpdatedEventSchema = exports.realtimeSessionCreatedEventSchema = exports.realtimeClientCommandSchema = exports.realtimeSessionCloseCommandSchema = exports.realtimeSessionResumeCommandSchema = exports.realtimeResponseCancelCommandSchema = exports.realtimeResponseCreateCommandSchema = exports.realtimeInputAudioClearCommandSchema = exports.realtimeInputAudioCommitCommandSchema = exports.realtimeInputAudioAppendCommandSchema = exports.realtimeItemTruncateCommandSchema = exports.realtimeItemDeleteCommandSchema = exports.realtimeItemCreateCommandSchema = exports.realtimeSessionUpdateCommandSchema = exports.realtimeResponseParametersSchema = exports.realtimeConversationItemSchema = exports.realtimeContentPartSchema = exports.realtimeSessionRequestSchema = exports.realtimeClientMetadataSchema = exports.realtimeSessionLimitsSchema = exports.realtimeSessionConfigUpdateSchema = exports.realtimeSessionConfigSchema = exports.realtimeTranslationSchema = exports.realtimeInputTranscriptionSchema = exports.realtimeTurnDetectionSchema = exports.realtimeOutputModalitySchema = exports.realtimeAudioFormatSchema = exports.realtimeResponseIdSchema = exports.realtimeItemIdSchema = exports.realtimeCommandIdSchema = exports.MAX_REALTIME_RESUME_WINDOW_MS = exports.MAX_REALTIME_SESSION_AUDIO_BYTES = exports.MAX_REALTIME_SESSION_DURATION_MS = exports.MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH = void 0;
+exports.realtimeServerEventSchema = exports.realtimeSessionClosedEventSchema = exports.realtimeSessionCloseReasonSchema = exports.realtimeErrorEventSchema = exports.realtimeResponseDoneEventSchema = exports.realtimeResponseStatusSchema = exports.realtimeToolCallEventSchema = exports.realtimeTextDeltaEventSchema = void 0;
+const zod_1 = require("zod");
+const attribution_1 = require("./attribution");
+const catalogue_1 = require("./catalogue");
+const errors_1 = require("./errors");
+const identifiers_1 = require("./identifiers");
+const money_1 = require("./money");
+const request_1 = require("./request");
+const routingPolicy_1 = require("./routingPolicy");
+const streamEvents_1 = require("./streamEvents");
+/* -------------------------------------------------------------------------- */
+/*  Bounds                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * The most base64 characters one audio frame may carry: 49 152 bytes of audio,
+ * about one second of 24 kHz mono PCM16. Bounded so no frame is large enough to
+ * stall a connection, and so a byte cap can be enforced as audio arrives rather
+ * than after it has been buffered.
+ */
+exports.MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH = 65536;
+/** The longest a session may be signed for: one hour. */
+exports.MAX_REALTIME_SESSION_DURATION_MS = 3600000;
+/**
+ * The most audio a session may be signed for in EACH direction: one hour of
+ * 24 kHz mono PCM16 (48 000 bytes per second), the densest format a session
+ * carries.
+ */
+exports.MAX_REALTIME_SESSION_AUDIO_BYTES = 172800000;
+/** The longest a dropped connection may be resumed after: one minute. */
+exports.MAX_REALTIME_RESUME_WINDOW_MS = 60000;
+/* -------------------------------------------------------------------------- */
+/*  Vocabulary                                                                */
+/* -------------------------------------------------------------------------- */
+/** A client-chosen command identity, unique within one session. */
+exports.realtimeCommandIdSchema = zod_1.z.string().min(1).max(128);
+/** A conversation item's identity within one session. */
+exports.realtimeItemIdSchema = zod_1.z.string().min(1).max(128);
+/** A response's identity within one session. */
+exports.realtimeResponseIdSchema = zod_1.z.string().min(1).max(128);
+/**
+ * The audio encodings a session carries, in both directions. Named by what they
+ * ARE (sample format, rate) because a realtime stream has no container to say so.
+ */
+exports.realtimeAudioFormatSchema = zod_1.z.enum([
+    "pcm16_24khz",
+    "g711_ulaw",
+    "g711_alaw",
+]);
+/** What a session's responses produce. */
+exports.realtimeOutputModalitySchema = zod_1.z.enum(["text", "audio"]);
+const audioFrameSchema = zod_1.z
+    .string()
+    .min(4)
+    .max(exports.MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH)
+    .regex(identifiers_1.PADDED_BASE64_PATTERN);
+const sequenceSchema = zod_1.z.number().int().nonnegative().safe();
+const milliseconds = zod_1.z.number().int().nonnegative().safe();
+/* -------------------------------------------------------------------------- */
+/*  Session configuration                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * How the end of a user's turn is detected.
+ *
+ * `none` means the client commits input audio itself. The two VAD forms name
+ * `createResponse` and `interruptResponse` explicitly rather than defaulting
+ * them: whether the model answers on its own, and whether new speech cuts it
+ * off, are the two behaviours a caller most needs to have chosen, and a default
+ * would choose them silently — and differently per provider.
+ */
+exports.realtimeTurnDetectionSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("none") }).strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("server_vad"),
+        threshold: zod_1.z.number().min(0).max(1).optional(),
+        prefixPaddingMs: zod_1.z.number().int().min(0).max(5000).optional(),
+        silenceDurationMs: zod_1.z.number().int().min(0).max(10000).optional(),
+        createResponse: zod_1.z.boolean(),
+        interruptResponse: zod_1.z.boolean(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("semantic_vad"),
+        eagerness: zod_1.z.enum(["low", "medium", "high", "auto"]),
+        createResponse: zod_1.z.boolean(),
+        interruptResponse: zod_1.z.boolean(),
+    })
+        .strict(),
+]);
+/**
+ * Transcription of the caller's input audio. Presence enables it; the
+ * transcription model is the deployment's own, declared where the deployment
+ * is, never chosen by a string here.
+ */
+exports.realtimeInputTranscriptionSchema = zod_1.z
+    .object({
+    /** A BCP 47 tag, when the caller knows the language. */
+    language: zod_1.z.string().min(2).max(35).optional(),
+    prompt: zod_1.z.string().max(4096).optional(),
+})
+    .strict();
+/** The target of a `translation` session. */
+exports.realtimeTranslationSchema = zod_1.z
+    .object({
+    /** A BCP 47 tag. */
+    targetLanguage: zod_1.z.string().min(2).max(35),
+})
+    .strict();
+/**
+ * A session's full configuration, as signed at open and as echoed back by
+ * `session.created` and `session.updated`.
+ *
+ * `inputAudioFormat` and `turnDetection` are required because every session
+ * kind consumes audio and has to know when a turn ends; nothing else is,
+ * because each kind needs a different subset — see the refinement on
+ * {@link realtimeSessionRequestSchema}.
+ */
+exports.realtimeSessionConfigSchema = zod_1.z
+    .object({
+    instructions: zod_1.z.string().max(32768).optional(),
+    outputModalities: zod_1.z.array(exports.realtimeOutputModalitySchema).min(1).max(2).optional(),
+    voice: zod_1.z.string().min(1).max(64).optional(),
+    inputAudioFormat: exports.realtimeAudioFormatSchema,
+    outputAudioFormat: exports.realtimeAudioFormatSchema.optional(),
+    turnDetection: exports.realtimeTurnDetectionSchema,
+    inputAudioTranscription: exports.realtimeInputTranscriptionSchema.optional(),
+    translation: exports.realtimeTranslationSchema.optional(),
+    tools: zod_1.z.array(request_1.toolDefinitionSchema).max(128).optional(),
+    toolChoice: request_1.toolChoiceSchema.optional(),
+    temperature: zod_1.z.number().min(0).max(2).optional(),
+    /** Per response, not per session: the session's ceiling is `limits`. */
+    maxOutputTokens: zod_1.z.number().int().positive().safe().optional(),
+})
+    .strict();
+/**
+ * What `session.update` may change mid-session.
+ *
+ * The session's kind, its audio formats and its voice are fixed at open —
+ * providers refuse to change a voice once it has spoken, and a format change
+ * mid-stream would make every buffered frame ambiguous — so they are not fields
+ * here, and the strict parse refuses them rather than ignoring them.
+ */
+exports.realtimeSessionConfigUpdateSchema = zod_1.z
+    .object({
+    instructions: zod_1.z.string().max(32768).optional(),
+    outputModalities: zod_1.z.array(exports.realtimeOutputModalitySchema).min(1).max(2).optional(),
+    turnDetection: exports.realtimeTurnDetectionSchema.optional(),
+    inputAudioTranscription: exports.realtimeInputTranscriptionSchema.optional(),
+    tools: zod_1.z.array(request_1.toolDefinitionSchema).max(128).optional(),
+    toolChoice: request_1.toolChoiceSchema.optional(),
+    temperature: zod_1.z.number().min(0).max(2).optional(),
+    maxOutputTokens: zod_1.z.number().int().positive().safe().optional(),
+})
+    .strict()
+    .superRefine((update, ctx) => {
+    if (Object.keys(update).length === 0) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "a session update changes at least one field",
+        });
+    }
+});
+/**
+ * The ceilings Oxy signed the session for. The data plane enforces each one and
+ * closes the session (`limit_exceeded`, `max_duration`, `idle_timeout`) rather
+ * than exceeding it: these bound what the session can cost, which is what Oxy's
+ * spend reservation was sized against.
+ */
+exports.realtimeSessionLimitsSchema = zod_1.z
+    .object({
+    maxDurationMs: zod_1.z.number().int().min(1000).max(exports.MAX_REALTIME_SESSION_DURATION_MS),
+    idleTimeoutMs: zod_1.z.number().int().min(1000).max(exports.MAX_REALTIME_SESSION_DURATION_MS),
+    maxInputAudioBytes: zod_1.z.number().int().positive().max(exports.MAX_REALTIME_SESSION_AUDIO_BYTES),
+    maxOutputAudioBytes: zod_1.z.number().int().positive().max(exports.MAX_REALTIME_SESSION_AUDIO_BYTES),
+    maxResponses: zod_1.z.number().int().positive().max(10000),
+})
+    .strict();
+/**
+ * What the edge records about the session CALL. Strict for the reason
+ * `clientRequestMetadataSchema` is: this object is where an IP would be added.
+ */
+exports.realtimeClientMetadataSchema = zod_1.z
+    .object({
+    /** The public path, e.g. `/v1/realtime`. */
+    endpoint: zod_1.z.string().min(1).max(256),
+    clientSessionId: zod_1.z.string().min(1).max(128).optional(),
+    receivedAt: identifiers_1.inferenceTimestampSchema,
+    labels: zod_1.z.record(zod_1.z.string().max(256)).optional(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  The session request                                                       */
+/* -------------------------------------------------------------------------- */
+const modelLineOf = (reference) => {
+    const at = reference.indexOf("@");
+    return at === -1 ? reference : reference.slice(0, at);
+};
+/**
+ * The signed request that opens a session: the first frame of its connection.
+ */
+exports.realtimeSessionRequestSchema = zod_1.z
+    .object({
+    schemaVersion: zod_1.z.literal(1),
+    attribution: attribution_1.inferenceAttributionSchema,
+    /** The model the caller named, pinned or not. Never a routing profile. */
+    modelReference: identifiers_1.modelReferenceSchema,
+    kind: catalogue_1.realtimeSessionKindSchema,
+    transport: catalogue_1.realtimeSessionTransportSchema,
+    config: exports.realtimeSessionConfigSchema,
+    limits: exports.realtimeSessionLimitsSchema,
+    client: exports.realtimeClientMetadataSchema,
+    routingPolicy: routingPolicy_1.routingPolicyReferenceSchema,
+    /** In preference order, tried only until one opens. All `same_model`. */
+    authorizedRoutes: zod_1.z.array(routingPolicy_1.authorizedRouteSchema).min(1),
+})
+    .superRefine((request, ctx) => {
+    const { config } = request;
+    const issue = (path, message) => ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path, message });
+    if (request.limits.idleTimeoutMs > request.limits.maxDurationMs) {
+        issue(["limits", "idleTimeoutMs"], "an idle timeout cannot outlast the session");
+    }
+    const producesAudio = config.outputModalities?.includes("audio") === true;
+    const hasTools = config.tools !== undefined && config.tools.length > 0;
+    switch (request.kind) {
+        case "conversation":
+            if (config.outputModalities === undefined) {
+                issue(["config", "outputModalities"], "a conversation names what its responses produce");
+            }
+            if (producesAudio && (config.voice === undefined || config.outputAudioFormat === undefined)) {
+                issue(["config"], "spoken responses need a voice and an output audio format");
+            }
+            if (config.translation !== undefined) {
+                issue(["config", "translation"], "only a translation session translates");
+            }
+            break;
+        case "transcription":
+            if (config.inputAudioTranscription === undefined) {
+                issue(["config", "inputAudioTranscription"], "a transcription session transcribes its input");
+            }
+            for (const field of ["outputModalities", "voice", "outputAudioFormat", "translation", "tools", "toolChoice", "maxOutputTokens"]) {
+                if (config[field] !== undefined) {
+                    issue(["config", field], "a transcription session never responds");
+                }
+            }
+            if (config.turnDetection.type !== "none" && (config.turnDetection.createResponse || config.turnDetection.interruptResponse)) {
+                issue(["config", "turnDetection"], "a transcription session has no response to create or interrupt");
+            }
+            break;
+        case "translation":
+            if (config.translation === undefined || config.outputAudioFormat === undefined) {
+                issue(["config"], "a translation session names its target language and output audio format");
+            }
+            if (config.tools !== undefined || config.toolChoice !== undefined) {
+                issue(["config", "tools"], "a translation session calls no tools");
+            }
+            break;
+    }
+    if (config.toolChoice !== undefined && !hasTools) {
+        issue(["config", "toolChoice"], "a tool choice requires at least one tool definition");
+    }
+    if (config.tools !== undefined) {
+        const names = config.tools.map((tool) => tool.name);
+        if (new Set(names).size !== names.length) {
+            issue(["config", "tools"], "tool names must be unique within one session");
+        }
+    }
+    if (config.outputModalities !== undefined && new Set(config.outputModalities).size !== config.outputModalities.length) {
+        issue(["config", "outputModalities"], "each output modality is named at most once");
+    }
+    // A session is never substituted: the conversation it holds belongs to one
+    // model, so every route serves the line the caller named, and a pinned
+    // request is served on exactly the revision it pinned.
+    const line = modelLineOf(request.modelReference);
+    const pinned = request.modelReference.includes("@");
+    for (const [index, route] of request.authorizedRoutes.entries()) {
+        if (route.substitution !== "same_model" || modelLineOf(route.modelReference) !== line) {
+            issue(["authorizedRoutes", index], "every route of a session serves the model it named");
+        }
+        if (pinned && route.modelReference !== request.modelReference) {
+            issue(["authorizedRoutes", index, "modelReference"], "a pinned session is served on exactly the revision it pinned");
+        }
+    }
+    const deployments = request.authorizedRoutes.map((route) => route.deploymentId);
+    if (new Set(deployments).size !== deployments.length) {
+        issue(["authorizedRoutes"], "each deployment appears at most once in the authorized route list");
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  Conversation items                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * One part of a conversation message.
+ *
+ * `input_audio` carries its audio inline (one bounded frame); `output_audio`
+ * never does — spoken output arrives as `output_audio.delta` events, and an
+ * item echoing it carries only the format and, once known, the transcript.
+ */
+exports.realtimeContentPartSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("input_text"), text: zod_1.z.string().max(1048576) }).strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("input_audio"),
+        format: exports.realtimeAudioFormatSchema,
+        data: audioFrameSchema.optional(),
+        transcript: zod_1.z.string().optional(),
+    })
+        .strict(),
+    zod_1.z.object({ type: zod_1.z.literal("output_text"), text: zod_1.z.string() }).strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("output_audio"),
+        format: exports.realtimeAudioFormatSchema,
+        transcript: zod_1.z.string().optional(),
+    })
+        .strict(),
+]);
+const INPUT_PARTS = new Set(["input_text", "input_audio"]);
+/**
+ * One item of the conversation a session holds.
+ *
+ * `itemId` is optional on an item a client CREATES (the server assigns one) and
+ * is always stated by the server on the events that carry an item.
+ */
+exports.realtimeConversationItemSchema = zod_1.z
+    .discriminatedUnion("type", [
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("message"),
+        itemId: exports.realtimeItemIdSchema.optional(),
+        role: zod_1.z.enum(["system", "user", "assistant"]),
+        content: zod_1.z.array(exports.realtimeContentPartSchema).min(1).max(64),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("function_call"),
+        itemId: exports.realtimeItemIdSchema.optional(),
+        callId: zod_1.z.string().min(1).max(128),
+        name: zod_1.z.string().min(1).max(128),
+        arguments: zod_1.z.string(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal("function_call_output"),
+        itemId: exports.realtimeItemIdSchema.optional(),
+        callId: zod_1.z.string().min(1).max(128),
+        output: zod_1.z.string().max(1048576),
+    })
+        .strict(),
+])
+    .superRefine((item, ctx) => {
+    if (item.type !== "message")
+        return;
+    for (const [index, part] of item.content.entries()) {
+        const isInput = INPUT_PARTS.has(part.type);
+        // A user or system turn is input; an assistant turn is output. A part on
+        // the wrong side is one every provider would silently ignore.
+        if (item.role === "assistant" ? isInput : !isInput) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ["content", index, "type"],
+                message: `a ${item.role} message cannot carry ${part.type}`,
+            });
+        }
+        if (item.role === "system" && part.type !== "input_text") {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ["content", index, "type"],
+                message: "a system message is text",
+            });
+        }
+    }
+});
+/** Per-response overrides for `response.create`. Absent fields keep the session's. */
+exports.realtimeResponseParametersSchema = zod_1.z
+    .object({
+    instructions: zod_1.z.string().max(32768).optional(),
+    outputModalities: zod_1.z.array(exports.realtimeOutputModalitySchema).min(1).max(2).optional(),
+    maxOutputTokens: zod_1.z.number().int().positive().safe().optional(),
+    toolChoice: request_1.toolChoiceSchema.optional(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Client commands                                                           */
+/* -------------------------------------------------------------------------- */
+const commandBase = {
+    /** See `version.ts`: each command is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    commandId: exports.realtimeCommandIdSchema,
+};
+exports.realtimeSessionUpdateCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("session.update"),
+    config: exports.realtimeSessionConfigUpdateSchema,
+});
+exports.realtimeItemCreateCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("conversation.item.create"),
+    /** Insert after this item; absent appends. */
+    previousItemId: exports.realtimeItemIdSchema.optional(),
+    item: exports.realtimeConversationItemSchema,
+});
+exports.realtimeItemDeleteCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("conversation.item.delete"),
+    itemId: exports.realtimeItemIdSchema,
+});
+/**
+ * Cut an assistant's audio item at the point the listener actually heard, after
+ * an interruption, so the conversation the model remembers is the one that was
+ * spoken rather than the one that was generated.
+ */
+exports.realtimeItemTruncateCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("conversation.item.truncate"),
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+    audioEndMs: milliseconds,
+});
+exports.realtimeInputAudioAppendCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("input_audio.append"),
+    /** One bounded frame in the session's `inputAudioFormat`. */
+    data: audioFrameSchema,
+});
+exports.realtimeInputAudioCommitCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("input_audio.commit"),
+});
+exports.realtimeInputAudioClearCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("input_audio.clear"),
+});
+exports.realtimeResponseCreateCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("response.create"),
+    response: exports.realtimeResponseParametersSchema.optional(),
+});
+exports.realtimeResponseCancelCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("response.cancel"),
+    /** Absent cancels the response in progress, if any. */
+    responseId: exports.realtimeResponseIdSchema.optional(),
+});
+/**
+ * The first frame of a reconnection: replay every event after `afterSequence`.
+ * `-1` asks for every buffered event from the start.
+ */
+exports.realtimeSessionResumeCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("session.resume"),
+    afterSequence: zod_1.z.number().int().min(-1).safe(),
+});
+exports.realtimeSessionCloseCommandSchema = zod_1.z.object({
+    ...commandBase,
+    type: zod_1.z.literal("session.close"),
+});
+/** Every command a client can send. */
+exports.realtimeClientCommandSchema = zod_1.z.discriminatedUnion("type", [
+    exports.realtimeSessionUpdateCommandSchema,
+    exports.realtimeItemCreateCommandSchema,
+    exports.realtimeItemDeleteCommandSchema,
+    exports.realtimeItemTruncateCommandSchema,
+    exports.realtimeInputAudioAppendCommandSchema,
+    exports.realtimeInputAudioCommitCommandSchema,
+    exports.realtimeInputAudioClearCommandSchema,
+    exports.realtimeResponseCreateCommandSchema,
+    exports.realtimeResponseCancelCommandSchema,
+    exports.realtimeSessionResumeCommandSchema,
+    exports.realtimeSessionCloseCommandSchema,
+]);
+/* -------------------------------------------------------------------------- */
+/*  Server events                                                             */
+/* -------------------------------------------------------------------------- */
+const eventBase = {
+    /** See `version.ts`: each event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    /** One monotonic sequence per session, from 0; what makes a replay detectable. */
+    sequence: sequenceSchema,
+    /** The command this event answers, when it answers one. */
+    commandId: exports.realtimeCommandIdSchema.optional(),
+};
+/**
+ * The session opened. Names the revision-pinned model, the serving provider and
+ * the exact deployment — fixed for the rest of the session — and the effective
+ * configuration and limits. `deploymentId` is for settlement: like the usage
+ * event's, it is not rendered to the customer.
+ */
+exports.realtimeSessionCreatedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("session.created"),
+    resolvedModelReference: identifiers_1.modelReferenceSchema,
+    servingProvider: identifiers_1.inferenceProviderSlugSchema,
+    deploymentId: identifiers_1.deploymentIdSchema,
+    kind: catalogue_1.realtimeSessionKindSchema,
+    config: exports.realtimeSessionConfigSchema,
+    limits: exports.realtimeSessionLimitsSchema,
+    resumeWindowMs: zod_1.z.number().int().nonnegative().max(exports.MAX_REALTIME_RESUME_WINDOW_MS),
+    startedAt: identifiers_1.inferenceTimestampSchema,
+    expiresAt: identifiers_1.inferenceTimestampSchema,
+});
+exports.realtimeSessionUpdatedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("session.updated"),
+    config: exports.realtimeSessionConfigSchema,
+});
+exports.realtimeSessionResumedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("session.resumed"),
+    afterSequence: zod_1.z.number().int().min(-1).safe(),
+});
+/** Sent before a command is applied. `duplicate` means it was not applied again. */
+exports.realtimeCommandAcceptedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("command.accepted"),
+    commandId: exports.realtimeCommandIdSchema,
+    duplicate: zod_1.z.boolean(),
+});
+exports.realtimeItemAddedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("conversation.item.added"),
+    itemId: exports.realtimeItemIdSchema,
+    previousItemId: exports.realtimeItemIdSchema.optional(),
+    item: exports.realtimeConversationItemSchema,
+});
+exports.realtimeItemDoneEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("conversation.item.done"),
+    itemId: exports.realtimeItemIdSchema,
+    item: exports.realtimeConversationItemSchema,
+});
+exports.realtimeItemDeletedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("conversation.item.deleted"),
+    itemId: exports.realtimeItemIdSchema,
+});
+exports.realtimeItemTruncatedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("conversation.item.truncated"),
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+    audioEndMs: milliseconds,
+});
+/**
+ * Voice activity began. With `interruptResponse`, a response in progress is
+ * cancelled by it: this event is the interruption, and the client should stop
+ * playback and truncate what was not heard.
+ */
+exports.realtimeSpeechStartedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("input_audio.speech_started"),
+    itemId: exports.realtimeItemIdSchema,
+    audioStartMs: milliseconds,
+});
+exports.realtimeSpeechStoppedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("input_audio.speech_stopped"),
+    itemId: exports.realtimeItemIdSchema,
+    audioEndMs: milliseconds,
+});
+exports.realtimeInputAudioCommittedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("input_audio.committed"),
+    itemId: exports.realtimeItemIdSchema,
+    previousItemId: exports.realtimeItemIdSchema.optional(),
+});
+exports.realtimeInputAudioClearedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("input_audio.cleared"),
+});
+exports.realtimeResponseCreatedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("response.created"),
+    responseId: exports.realtimeResponseIdSchema,
+});
+/** One bounded frame of spoken output, in the session's `outputAudioFormat`. */
+exports.realtimeOutputAudioDeltaEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("output_audio.delta"),
+    responseId: exports.realtimeResponseIdSchema,
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+    format: exports.realtimeAudioFormatSchema,
+    data: audioFrameSchema,
+});
+exports.realtimeOutputAudioDoneEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("output_audio.done"),
+    responseId: exports.realtimeResponseIdSchema,
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+});
+/**
+ * Which audio a transcript describes: the caller's (`input_audio`) or the
+ * model's own speech (`output_audio`). Neither is answer text.
+ */
+exports.realtimeTranscriptSourceSchema = zod_1.z.enum(["input_audio", "output_audio"]);
+exports.realtimeTranscriptDeltaEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("transcript.delta"),
+    source: exports.realtimeTranscriptSourceSchema,
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+    /** Present for `output_audio`: the response whose speech this is. */
+    responseId: exports.realtimeResponseIdSchema.optional(),
+    text: zod_1.z.string(),
+});
+exports.realtimeTranscriptDoneEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("transcript.done"),
+    source: exports.realtimeTranscriptSourceSchema,
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+    responseId: exports.realtimeResponseIdSchema.optional(),
+    transcript: zod_1.z.string(),
+});
+/** Written output of a response (`outputModalities` including `text`). */
+exports.realtimeTextDeltaEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("text.delta"),
+    responseId: exports.realtimeResponseIdSchema,
+    itemId: exports.realtimeItemIdSchema,
+    contentIndex: zod_1.z.number().int().nonnegative().safe(),
+    text: zod_1.z.string(),
+});
+/** A tool call being streamed; same accumulation rules as the one-shot event. */
+exports.realtimeToolCallEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("tool_call"),
+    responseId: exports.realtimeResponseIdSchema,
+    itemId: exports.realtimeItemIdSchema,
+    toolCallId: zod_1.z.string().min(1).max(128),
+    name: zod_1.z.string().min(1).max(128).optional(),
+    argumentsDelta: zod_1.z.string().optional(),
+    complete: zod_1.z.boolean(),
+});
+/** How a response ended. */
+exports.realtimeResponseStatusSchema = zod_1.z.enum([
+    "completed",
+    "cancelled",
+    "incomplete",
+    "failed",
+]);
+/**
+ * A response ended, with the units it consumed — measurement evidence, as on
+ * the one-shot usage event. A cancelled or failed response still consumed what
+ * it consumed, so its units are reported too.
+ */
+exports.realtimeResponseDoneEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("response.done"),
+    responseId: exports.realtimeResponseIdSchema,
+    status: exports.realtimeResponseStatusSchema,
+    finishReason: streamEvents_1.inferenceFinishReasonSchema.optional(),
+    deploymentId: identifiers_1.deploymentIdSchema,
+    units: zod_1.z.array(money_1.usageQuantitySchema),
+    usageSource: money_1.usageSourceSchema,
+});
+/**
+ * An error. `fatal: false` refuses one command and the session continues;
+ * `fatal: true` is followed by `session.closed` and nothing else.
+ */
+exports.realtimeErrorEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("error"),
+    fatal: zod_1.z.boolean(),
+    error: errors_1.inferenceErrorSchema,
+});
+/** Why a session ended. */
+exports.realtimeSessionCloseReasonSchema = zod_1.z.enum([
+    "client_closed",
+    "max_duration",
+    "idle_timeout",
+    "limit_exceeded",
+    "resume_expired",
+    "upstream_closed",
+    "upstream_error",
+    "no_route_available",
+    "server_shutdown",
+]);
+/**
+ * The terminal event. Carries the session's total units; `deploymentId` is
+ * absent only when no route ever opened, in which case nothing was consumed.
+ */
+exports.realtimeSessionClosedEventSchema = zod_1.z.object({
+    ...eventBase,
+    type: zod_1.z.literal("session.closed"),
+    reason: exports.realtimeSessionCloseReasonSchema,
+    deploymentId: identifiers_1.deploymentIdSchema.optional(),
+    units: zod_1.z.array(money_1.usageQuantitySchema),
+    usageSource: money_1.usageSourceSchema,
+    closedAt: identifiers_1.inferenceTimestampSchema,
+});
+/** Every event a session can emit. */
+exports.realtimeServerEventSchema = zod_1.z
+    .discriminatedUnion("type", [
+    exports.realtimeSessionCreatedEventSchema,
+    exports.realtimeSessionUpdatedEventSchema,
+    exports.realtimeSessionResumedEventSchema,
+    exports.realtimeCommandAcceptedEventSchema,
+    exports.realtimeItemAddedEventSchema,
+    exports.realtimeItemDoneEventSchema,
+    exports.realtimeItemDeletedEventSchema,
+    exports.realtimeItemTruncatedEventSchema,
+    exports.realtimeSpeechStartedEventSchema,
+    exports.realtimeSpeechStoppedEventSchema,
+    exports.realtimeInputAudioCommittedEventSchema,
+    exports.realtimeInputAudioClearedEventSchema,
+    exports.realtimeResponseCreatedEventSchema,
+    exports.realtimeOutputAudioDeltaEventSchema,
+    exports.realtimeOutputAudioDoneEventSchema,
+    exports.realtimeTranscriptDeltaEventSchema,
+    exports.realtimeTranscriptDoneEventSchema,
+    exports.realtimeTextDeltaEventSchema,
+    exports.realtimeToolCallEventSchema,
+    exports.realtimeResponseDoneEventSchema,
+    exports.realtimeErrorEventSchema,
+    exports.realtimeSessionClosedEventSchema,
+])
+    .superRefine((event, ctx) => {
+    // Each unit is reported once, as a total — the rule every usage record in
+    // this contract holds. Checked on the union because a discriminated union's
+    // options must stay plain objects.
+    if (event.type !== "response.done" && event.type !== "session.closed")
+        return;
+    const units = event.units.map((quantity) => quantity.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ["units"],
+            message: "each unit is reported at most once",
+        });
+    }
+});