@kaana.ai/contracts 4.4.0 → 5.0.0

package/dist/public/realtime.d.ts

@@ -4,7 +4,9 @@
  * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/realtime.ts`) by Kaana ADR 0002.
  */
 import { z } from 'zod';
-import { type ModelAudioCapabilities, type ModelCapabilities, realtimeSessionKindSchema } from './catalogue.js';
+import { realtimeOutputModalitySchema } from './audioFormats.js';
+import { type ModelAudioCapabilities, type ModelCapabilities, type RealtimeParameters, realtimeSessionKindSchema } from './catalogue.js';
+import { toolChoiceSchema } from './messages.js';
 /**
  * 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
@@ -28,11 +30,6 @@ export declare const realtimeCommandIdSchema: z.ZodString;
 export declare const realtimeItemIdSchema: z.ZodString;
 /** A response's identity within one session. */
 export declare const realtimeResponseIdSchema: z.ZodString;
-/** What a session's responses produce. */
-export declare const realtimeOutputModalitySchema: z.ZodEnum<{
-    text: "text";
-    audio: "audio";
-}>;
 /**
  * How the end of a user's turn is detected.
  *
@@ -85,6 +82,16 @@ export declare const realtimeInputTranscriptionSchema: z.ZodObject<{
 export declare const realtimeTranslationSchema: z.ZodObject<{
     targetLanguage: z.ZodString;
 }, z.core.$strict>;
+/**
+ * A function tool a session may call: the chat tool without `strict`, which no
+ * realtime provider's session schema has (contract set 5.0.0).
+ */
+export declare const realtimeToolDefinitionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    name: z.ZodString;
+    parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 /**
  * A session's full configuration, as signed at open and as echoed back by
  * `session.created` and `session.updated`.
@@ -141,19 +148,17 @@ export declare const realtimeSessionConfigSchema: z.ZodObject<{
     tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"function">;
         name: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
         parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        strict: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
         none: "none";
+        auto: "auto";
         required: "required";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;
         name: z.ZodString;
     }, z.core.$strict>]>>;
-    temperature: z.ZodOptional<z.ZodNumber>;
     maxOutputTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /**
@@ -197,19 +202,17 @@ export declare const realtimeSessionConfigUpdateSchema: z.ZodObject<{
     tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"function">;
         name: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
         parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        strict: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
         none: "none";
+        auto: "auto";
         required: "required";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;
         name: z.ZodString;
     }, z.core.$strict>]>>;
-    temperature: z.ZodOptional<z.ZodNumber>;
     maxOutputTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /**
@@ -315,8 +318,8 @@ export declare const realtimeResponseParametersSchema: z.ZodObject<{
     }>>>;
     maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
         none: "none";
+        auto: "auto";
         required: "required";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;
@@ -358,19 +361,17 @@ export declare const realtimeSessionUpdateCommandSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;
@@ -478,8 +479,8 @@ export declare const realtimeResponseCreateCommandSchema: z.ZodObject<{
         }>>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -550,19 +551,17 @@ export declare const realtimeClientCommandSchema: z.ZodDiscriminatedUnion<[z.Zod
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;
@@ -658,8 +657,8 @@ export declare const realtimeClientCommandSchema: z.ZodDiscriminatedUnion<[z.Zod
         }>>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -736,19 +735,17 @@ export declare const realtimeSessionUpdatedEventSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;
@@ -1065,15 +1062,9 @@ export interface RealtimeConfigIssue {
  * apply the same ones, and a session a client may open is one Kaana may run.
  */
 export declare function realtimeConfigIssues(kind: z.infer<typeof realtimeSessionKindSchema>, config: z.infer<typeof realtimeSessionConfigSchema>): RealtimeConfigIssue[];
-/**
- * The most text `conversation.item.create` commands a session may be opened
- * for: the bound a duration-priced route's hold is sized from.
- */
-export declare const MAX_REALTIME_TEXT_ITEMS = 10000;
 /**
  * The customer's partial limits request: every signed limit, each filled from
- * Kaana's defaults when omitted, plus `maxTextItems`, the most billable text
- * items the session may send (absent, it defaults to `maxResponses`).
+ * Kaana's defaults when omitted, never above them.
  */
 export declare const realtimeOpenLimitsSchema: z.ZodObject<{
     maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -1081,8 +1072,13 @@ export declare const realtimeOpenLimitsSchema: z.ZodObject<{
     maxInputAudioBytes: z.ZodOptional<z.ZodNumber>;
     maxOutputAudioBytes: z.ZodOptional<z.ZodNumber>;
     maxResponses: z.ZodOptional<z.ZodNumber>;
-    maxTextItems: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
+/**
+ * The largest first frame of `GET /v1/realtime`: a `session.open` with its
+ * instructions and up to 128 tool definitions (contract set 5.0.0). A larger
+ * frame closes the connection before it is read.
+ */
+export declare const MAX_REALTIME_OPEN_FRAME_BYTES: number;
 /**
  * The first frame a client sends on `GET /v1/realtime?model=…` to OPEN a
  * session (a reconnection instead sends `session.resume`). One grant covers the
@@ -1147,19 +1143,17 @@ export declare const realtimeSessionOpenSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     limits: z.ZodOptional<z.ZodObject<{
@@ -1168,7 +1162,6 @@ export declare const realtimeSessionOpenSchema: z.ZodObject<{
         maxInputAudioBytes: z.ZodOptional<z.ZodNumber>;
         maxOutputAudioBytes: z.ZodOptional<z.ZodNumber>;
         maxResponses: z.ZodOptional<z.ZodNumber>;
-        maxTextItems: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     clientSessionId: z.ZodOptional<z.ZodString>;
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -1199,6 +1192,28 @@ export declare function checkRealtimeSessionOpen(open: z.infer<typeof realtimeSe
     readonly capabilities: ModelCapabilities;
     readonly audio?: ModelAudioCapabilities;
 }): RealtimeOpenIssue[];
+/**
+ * The part of a session configuration, of a `session.update` or of a
+ * `response.create` that a model's {@link RealtimeParameters} govern.
+ */
+export interface RealtimeGovernedFields {
+    readonly outputModalities?: readonly RealtimeOutputModality[];
+    readonly turnDetection?: RealtimeTurnDetection;
+    readonly inputAudioTranscription?: {
+        readonly prompt?: string;
+    };
+    readonly toolChoice?: z.infer<typeof toolChoiceSchema>;
+    readonly maxOutputTokens?: number;
+}
+/**
+ * Every field that `parameters` do not serve, each with the `param` Kaana's
+ * refusal names (`prefix` is `config` for an open or a `session.update`,
+ * `response` for a `response.create`), in the order Kaana checks them. It is
+ * exactly Kaana's own check (Go's `RealtimeParameters.Issues`, held to the
+ * same vectors), so a client that builds its session from a model's
+ * parameters, or filters models with this, is never refused for one.
+ */
+export declare function realtimeParameterIssues(prefix: 'config' | 'response', fields: RealtimeGovernedFields, parameters: RealtimeParameters): RealtimeOpenIssue[];
 /**
  * The session opened: the revision-pinned model, fixed for the rest of the
  * session, and the effective configuration and limits. The signed lane's
@@ -1260,19 +1275,17 @@ export declare const realtimePublicSessionCreatedEventSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
@@ -1499,19 +1512,17 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
@@ -1577,19 +1588,17 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
             parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-            strict: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            auto: "auto";
             none: "none";
+            auto: "auto";
             required: "required";
         }>, z.ZodObject<{
             type: z.ZodLiteral<"function">;
             name: z.ZodString;
         }, z.core.$strict>]>>;
-        temperature: z.ZodOptional<z.ZodNumber>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;

package/dist/public/realtime.js

@@ -4,7 +4,7 @@
  * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/realtime.ts`) by Kaana ADR 0002.
  */
 import { z } from 'zod';
-import { realtimeAudioFormatSchema } from './audioFormats.js';
+import { realtimeAudioFormatSchema, realtimeOutputModalitySchema } from './audioFormats.js';
 import { realtimeSessionKindSchema, realtimeSessionTransportSchema, } from './catalogue.js';
 import { inferenceTimestampSchema, modelReferenceSchema, PADDED_BASE64_PATTERN, requestIdSchema, } from './identifiers.js';
 import { publicErrorSchema } from './errors.js';
@@ -34,8 +34,6 @@ export const realtimeCommandIdSchema = z.string().min(1).max(128);
 export const realtimeItemIdSchema = z.string().min(1).max(128);
 /** A response's identity within one session. */
 export const realtimeResponseIdSchema = z.string().min(1).max(128);
-/** What a session's responses produce. */
-export const realtimeOutputModalitySchema = z.enum(['text', 'audio']);
 const audioFrameSchema = z
     .string()
     .min(4)
@@ -102,6 +100,11 @@ export const realtimeTranslationSchema = z
     targetLanguage: z.string().min(2).max(35),
 })
     .strict();
+/**
+ * A function tool a session may call: the chat tool without `strict`, which no
+ * realtime provider's session schema has (contract set 5.0.0).
+ */
+export const realtimeToolDefinitionSchema = toolDefinitionSchema.omit({ strict: true });
 /**
  * A session's full configuration, as signed at open and as echoed back by
  * `session.created` and `session.updated`.
@@ -121,9 +124,8 @@ export const realtimeSessionConfigSchema = z
     turnDetection: realtimeTurnDetectionSchema,
     inputAudioTranscription: realtimeInputTranscriptionSchema.optional(),
     translation: realtimeTranslationSchema.optional(),
-    tools: z.array(toolDefinitionSchema).max(128).optional(),
+    tools: z.array(realtimeToolDefinitionSchema).max(128).optional(),
     toolChoice: toolChoiceSchema.optional(),
-    temperature: z.number().min(0).max(2).optional(),
     /** Per response, not per session: the session's ceiling is `limits`. */
     maxOutputTokens: z.number().int().positive().safe().optional(),
 })
@@ -142,9 +144,8 @@ export const realtimeSessionConfigUpdateSchema = z
     outputModalities: z.array(realtimeOutputModalitySchema).min(1).max(2).optional(),
     turnDetection: realtimeTurnDetectionSchema.optional(),
     inputAudioTranscription: realtimeInputTranscriptionSchema.optional(),
-    tools: z.array(toolDefinitionSchema).max(128).optional(),
+    tools: z.array(realtimeToolDefinitionSchema).max(128).optional(),
     toolChoice: toolChoiceSchema.optional(),
-    temperature: z.number().min(0).max(2).optional(),
     maxOutputTokens: z.number().int().positive().safe().optional(),
 })
     .strict()
@@ -587,21 +588,16 @@ export function realtimeConfigIssues(kind, config) {
 /*  Opening a session (`GET /v1/realtime`)                                     */
 /* -------------------------------------------------------------------------- */
 /**
- * The most text `conversation.item.create` commands a session may be opened
- * for: the bound a duration-priced route's hold is sized from.
+ * The customer's partial limits request: every signed limit, each filled from
+ * Kaana's defaults when omitted, never above them.
  */
-export const MAX_REALTIME_TEXT_ITEMS = 10_000;
+export const realtimeOpenLimitsSchema = realtimeSessionLimitsSchema.partial().strict();
 /**
- * The customer's partial limits request: every signed limit, each filled from
- * Kaana's defaults when omitted, plus `maxTextItems`, the most billable text
- * items the session may send (absent, it defaults to `maxResponses`).
+ * The largest first frame of `GET /v1/realtime`: a `session.open` with its
+ * instructions and up to 128 tool definitions (contract set 5.0.0). A larger
+ * frame closes the connection before it is read.
  */
-export const realtimeOpenLimitsSchema = realtimeSessionLimitsSchema
-    .partial()
-    .extend({
-    maxTextItems: z.number().int().nonnegative().max(MAX_REALTIME_TEXT_ITEMS).optional(),
-})
-    .strict();
+export const MAX_REALTIME_OPEN_FRAME_BYTES = 1024 * 1024;
 /**
  * The first frame a client sends on `GET /v1/realtime?model=…` to OPEN a
  * session (a reconnection instead sends `session.resume`). One grant covers the
@@ -702,9 +698,79 @@ export function checkRealtimeSessionOpen(open, model) {
         !audio.languages.includes(transcription.language)) {
         issues.push({
             param: 'config.inputAudioTranscription.language',
-            message: `this model does not declare the language ${transcription.language}`,
+            message: `this model does not declare the language ${transcription.language}` +
+                (audio.detectsLanguage === true ? '; omit it to let the model detect the language' : ''),
         });
     }
+    if (realtime.parameters !== undefined) {
+        issues.push(...realtimeParameterIssues('config', config, realtime.parameters));
+    }
+    return issues;
+}
+function toolChoiceKind(choice) {
+    return typeof choice === 'string' ? choice : 'function';
+}
+function sameModalities(a, b) {
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+ * Every field that `parameters` do not serve, each with the `param` Kaana's
+ * refusal names (`prefix` is `config` for an open or a `session.update`,
+ * `response` for a `response.create`), in the order Kaana checks them. It is
+ * exactly Kaana's own check (Go's `RealtimeParameters.Issues`, held to the
+ * same vectors), so a client that builds its session from a model's
+ * parameters, or filters models with this, is never refused for one.
+ */
+export function realtimeParameterIssues(prefix, fields, parameters) {
+    const issues = [];
+    const issue = (param, message) => issues.push({ param: `${prefix}.${param}`, message });
+    if (fields.outputModalities !== undefined &&
+        !parameters.outputModalities.some((set) => sameModalities(set, fields.outputModalities ?? []))) {
+        issue('outputModalities', `this model produces ${parameters.outputModalities.map((set) => `[${set.join(' ')}]`).join(' or ')} in one response`);
+    }
+    const detection = fields.turnDetection;
+    if (detection !== undefined) {
+        const served = parameters.turnDetection.find((candidate) => candidate.type === detection.type);
+        if (served === undefined) {
+            issue('turnDetection', `this model has no ${detection.type} turn detection`);
+        }
+        else {
+            if (served.fixedResponses && detection.type !== 'none') {
+                if (!detection.createResponse) {
+                    issue('turnDetection.createResponse', `this model's ${detection.type} always answers the turn it detected; createResponse must be true`);
+                }
+                if (!detection.interruptResponse) {
+                    issue('turnDetection.interruptResponse', `this model's ${detection.type} lets the caller's speech interrupt an answer; interruptResponse must be true`);
+                }
+            }
+            if (detection.type === 'server_vad') {
+                const threshold = served.threshold;
+                if (threshold !== undefined &&
+                    detection.threshold !== undefined &&
+                    (detection.threshold < threshold.min || detection.threshold > threshold.max)) {
+                    issue('turnDetection.threshold', `this model's ${detection.type} threshold is ${threshold.min} to ${threshold.max}`);
+                }
+            }
+        }
+    }
+    if (fields.inputAudioTranscription?.prompt !== undefined &&
+        !parameters.inputTranscriptionPrompt) {
+        issue('inputAudioTranscription.prompt', "this model's input transcription takes no prompt");
+    }
+    if (fields.toolChoice !== undefined &&
+        !parameters.toolChoice.includes(toolChoiceKind(fields.toolChoice))) {
+        issue('toolChoice', `this model serves the tool choices ${parameters.toolChoice.join(', ')}`);
+    }
+    if (fields.maxOutputTokens !== undefined) {
+        if (parameters.maxOutputTokens === undefined) {
+            issue('maxOutputTokens', 'this model has no output token cap');
+        }
+        else if (fields.maxOutputTokens > parameters.maxOutputTokens) {
+            issue('maxOutputTokens', `this model caps a response at most at ${parameters.maxOutputTokens} output tokens`);
+        }
+    }
     return issues;
 }
 /* -------------------------------------------------------------------------- */

package/dist/public/responses.d.ts

@@ -118,8 +118,8 @@ export declare const responsesRequestSchema: z.ZodObject<{
         strict: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-        auto: "auto";
         none: "none";
+        auto: "auto";
         required: "required";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;

package/dist/public/version.d.ts

@@ -100,7 +100,7 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export declare const INFERENCE_CONTRACT_VERSION = "4.4.0";
+export declare const INFERENCE_CONTRACT_VERSION = "5.0.0";
 /**
  * Contract set 4.0.0 (Kaana ADR 0002) is the first published as
  * `@kaana.ai/contracts`. MAJOR because the set changed hands and split in two:
@@ -135,12 +135,38 @@ export declare const INFERENCE_CONTRACT_VERSION = "4.4.0";
  * permission, dedicated capacity), and `sameModelFailover` on
  * `grantStepLimitsSchema` (default `true`: what 4.3.0 did). Nothing in 4.3.0
  * changes.
+ *
+ * Contract set 4.5.0 is additive: the signed envelope's optional
+ * `transcription` member (`inferenceTranscriptionParametersSchema`), which
+ * carries a file transcription's `language` to the model instead of the
+ * public API refusing it. Nothing in 4.4.0 changes.
+ *
+ * Contract set 5.0.0 publishes what each voice model ACCEPTS, so a client
+ * builds its request from the catalogue instead of learning the rules from a
+ * refusal. Additive: `capabilities.realtime.parameters` (turn detections and
+ * their bounds, output modality sets, tool choices, the output token cap, the
+ * input transcription prompt, and the units each detection is billed in),
+ * `audio.detectsLanguage` and `audio.transcriptionPrompt`,
+ * `realtimeParameterIssues` and `checkTranscriptionRequest`, the envelope's
+ * `transcription.prompt`, `MAX_REALTIME_OPEN_FRAME_BYTES`. MAJOR because it
+ * REMOVES what no server ever served, each of which Kaana already refused:
+ * the realtime `temperature`, a realtime tool's `strict`
+ * (`realtimeToolDefinitionSchema`), `limits.maxTextItems` and
+ * `MAX_REALTIME_TEXT_ITEMS`, and a transcription's `timestamps`, `segments`
+ * and `words`. A request that parsed under 4.5.0 and that Kaana served
+ * still parses and is served the same.
  */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";
 /** The response header that carries the request id. */
 export declare const KAANA_REQUEST_ID_HEADER = "Kaana-Request-Id";
-/** The response header that carries {@link INFERENCE_CONTRACT_VERSION}. */
+/**
+ * The header that carries {@link INFERENCE_CONTRACT_VERSION}: on every
+ * response, the set Kaana serves; on a request (`@kaana.ai/sdk` 2.0.0 and
+ * later), the set the client parses. The catalogue's leaves are strict, so
+ * Kaana renders `GET /v1/models` in the shape of the client's set: a client
+ * that states none is served the 4.x shape, without what set 5.0.0 added.
+ */
 export declare const KAANA_CONTRACT_VERSION_HEADER = "Kaana-Contract-Version";
 /**
  * The response header that names the revision that actually served a request

package/dist/public/version.js

@@ -100,7 +100,7 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '4.4.0';
+export const INFERENCE_CONTRACT_VERSION = '5.0.0';
 /**
  * Contract set 4.0.0 (Kaana ADR 0002) is the first published as
  * `@kaana.ai/contracts`. MAJOR because the set changed hands and split in two:
@@ -135,12 +135,38 @@ export const INFERENCE_CONTRACT_VERSION = '4.4.0';
  * permission, dedicated capacity), and `sameModelFailover` on
  * `grantStepLimitsSchema` (default `true`: what 4.3.0 did). Nothing in 4.3.0
  * changes.
+ *
+ * Contract set 4.5.0 is additive: the signed envelope's optional
+ * `transcription` member (`inferenceTranscriptionParametersSchema`), which
+ * carries a file transcription's `language` to the model instead of the
+ * public API refusing it. Nothing in 4.4.0 changes.
+ *
+ * Contract set 5.0.0 publishes what each voice model ACCEPTS, so a client
+ * builds its request from the catalogue instead of learning the rules from a
+ * refusal. Additive: `capabilities.realtime.parameters` (turn detections and
+ * their bounds, output modality sets, tool choices, the output token cap, the
+ * input transcription prompt, and the units each detection is billed in),
+ * `audio.detectsLanguage` and `audio.transcriptionPrompt`,
+ * `realtimeParameterIssues` and `checkTranscriptionRequest`, the envelope's
+ * `transcription.prompt`, `MAX_REALTIME_OPEN_FRAME_BYTES`. MAJOR because it
+ * REMOVES what no server ever served, each of which Kaana already refused:
+ * the realtime `temperature`, a realtime tool's `strict`
+ * (`realtimeToolDefinitionSchema`), `limits.maxTextItems` and
+ * `MAX_REALTIME_TEXT_ITEMS`, and a transcription's `timestamps`, `segments`
+ * and `words`. A request that parsed under 4.5.0 and that Kaana served
+ * still parses and is served the same.
  */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';
 /** The response header that carries the request id. */
 export const KAANA_REQUEST_ID_HEADER = 'Kaana-Request-Id';
-/** The response header that carries {@link INFERENCE_CONTRACT_VERSION}. */
+/**
+ * The header that carries {@link INFERENCE_CONTRACT_VERSION}: on every
+ * response, the set Kaana serves; on a request (`@kaana.ai/sdk` 2.0.0 and
+ * later), the set the client parses. The catalogue's leaves are strict, so
+ * Kaana renders `GET /v1/models` in the shape of the client's set: a client
+ * that states none is served the 4.x shape, without what set 5.0.0 added.
+ */
 export const KAANA_CONTRACT_VERSION_HEADER = 'Kaana-Contract-Version';
 /**
  * The response header that names the revision that actually served a request