@kaana.ai/contracts 8.15.0 → 8.16.0

package/dist/public/realtime.d.ts

@@ -30,10 +30,26 @@ export declare const MAX_REALTIME_RESUME_WINDOW_MS = 60000;
  * reads it here, never copies it.
  */
 export declare const MAX_REALTIME_ITEM_TEXT_CHARS = 1048576;
+/**
+ * The most characters (UTF-16 code units) the text of one `delegation.reply` or
+ * `delegation.context` may hold (contract set 8.16.0). A client streams a long
+ * answer as several replies, sentence by sentence; Kaana splits each to its
+ * provider's own bound.
+ */
+export declare const MAX_REALTIME_DELEGATION_TEXT_CHARS = 8192;
+/** The most verbatim spans one `delegation.reply` may mark (contract set 8.16.0). */
+export declare const MAX_REALTIME_VERBATIM_SPANS = 32;
+/** The most characters (UTF-16 code units) one verbatim span may hold (contract set 8.16.0). */
+export declare const MAX_REALTIME_VERBATIM_SPAN_CHARS = 256;
 /** A client-chosen command identity, unique within one session. */
 export declare const realtimeCommandIdSchema: z.ZodString;
 /** A conversation item's identity within one session. */
 export declare const realtimeItemIdSchema: z.ZodString;
+/**
+ * A delegation's identity within one session: one turn a `live` session handed
+ * to its caller (contract set 8.16.0).
+ */
+export declare const realtimeDelegationIdSchema: z.ZodString;
 /** A response's identity within one session. */
 export declare const realtimeResponseIdSchema: z.ZodString;
 /**
@@ -85,6 +101,10 @@ export declare const realtimeTurnDetectionSchema: z.ZodDiscriminatedUnion<[z.Zod
  * session: where the provider bills the transcription
  * apart from the session model, as `input_transcription_milliseconds` (see
  * `USAGE_UNITS`); where the session's own price includes it, as nothing more.
+ *
+ * A `live` session relays the caller's words whether or not it is set, because
+ * its delegation needs them; there it takes `language` only (contract set
+ * 8.16.0).
  */
 export declare const realtimeInputTranscriptionSchema: z.ZodObject<{
     language: z.ZodOptional<z.ZodString>;
@@ -95,6 +115,25 @@ export declare const realtimeInputTranscriptionSchema: z.ZodObject<{
 export declare const realtimeTranslationSchema: z.ZodObject<{
     targetLanguage: z.ZodString;
 }, z.core.$strict>;
+/**
+ * Whether the voice of a `live` session acknowledges a turn it handed over:
+ * `auto` lets it say a short "one moment" while the caller's backend works;
+ * `none` keeps it silent until the first reply.
+ */
+export declare const realtimeDelegationAcknowledgementSchema: z.ZodEnum<{
+    auto: "auto";
+    none: "none";
+}>;
+/**
+ * How a `live` session hands its turns to its caller (contract set 8.16.0,
+ * Kaana ADR 0012). Required for `live` and refused for every other kind.
+ */
+export declare const realtimeDelegationConfigSchema: z.ZodObject<{
+    acknowledgement: z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+    }>;
+}, 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).
@@ -174,6 +213,12 @@ export declare const realtimeSessionConfigSchema: z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strict>]>>;
     maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    delegation: z.ZodOptional<z.ZodObject<{
+        acknowledgement: z.ZodEnum<{
+            auto: "auto";
+            none: "none";
+        }>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * What `session.update` may change mid-session.
@@ -531,7 +576,50 @@ export declare const realtimeSessionCloseCommandSchema: z.ZodObject<{
     requestId: z.ZodString;
     commandId: z.ZodString;
 }, z.core.$strip>;
-/** Every command a client can send. */
+/**
+ * Speak this part of a delegated turn's answer (contract set 8.16.0). A client
+ * streams its answer sentence by sentence and marks the last part `final`;
+ * after it, nothing more is spoken for the delegation. Each `verbatim` span is
+ * a part of `text` the voice says exactly as written: numbers, addresses,
+ * names, codes. A reply to a delegation that is unknown, superseded, cancelled
+ * or already final is refused (`invalid_request`, param `delegationId`).
+ */
+export declare const realtimeDelegationReplyCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"delegation.reply">;
+    delegationId: z.ZodString;
+    text: z.ZodString;
+    verbatim: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    final: z.ZodBoolean;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    commandId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Silent context the voice may use while a delegated turn is answered, for
+ * example "still checking your calendar" (contract set 8.16.0). Never spoken
+ * as written.
+ */
+export declare const realtimeDelegationContextCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"delegation.context">;
+    delegationId: z.ZodString;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    commandId: z.ZodString;
+}, z.core.$strip>;
+/** The client dropped a delegated turn: nothing more is spoken for it (contract set 8.16.0). */
+export declare const realtimeDelegationCancelCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"delegation.cancel">;
+    delegationId: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    commandId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Every command a client can send. The three `delegation.*` commands are a
+ * `live` session's; `session.update`, `input_audio.commit` and
+ * `input_audio.clear` are refused on one (`invalid_request`, param `type`).
+ */
 export declare const realtimeClientCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"session.update">;
     config: z.ZodObject<{
@@ -702,6 +790,28 @@ export declare const realtimeClientCommandSchema: z.ZodDiscriminatedUnion<[z.Zod
     schemaVersion: z.ZodLiteral<1>;
     requestId: z.ZodString;
     commandId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"delegation.reply">;
+    delegationId: z.ZodString;
+    text: z.ZodString;
+    verbatim: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    final: z.ZodBoolean;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    commandId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"delegation.context">;
+    delegationId: z.ZodString;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    commandId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"delegation.cancel">;
+    delegationId: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    commandId: z.ZodString;
 }, z.core.$strip>], "type">;
 export declare const realtimeSessionUpdatedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"session.updated">;
@@ -765,6 +875,12 @@ export declare const realtimeSessionUpdatedEventSchema: z.ZodObject<{
             name: z.ZodString;
         }, z.core.$strict>]>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        delegation: z.ZodOptional<z.ZodObject<{
+            acknowledgement: z.ZodEnum<{
+                auto: "auto";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;
     requestId: z.ZodString;
@@ -1067,6 +1183,35 @@ export declare const realtimeToolCallEventSchema: z.ZodObject<{
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * A `live` session hands one turn to its caller (contract set 8.16.0). `text`
+ * is the caller's words since the previous delegation, assembled by Kaana from
+ * the input transcript, so no client stitches transcripts. Answer it with
+ * `delegation.reply`; a newer delegation before its `final` reply supersedes
+ * it.
+ */
+export declare const realtimeDelegationRequestedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"delegation.requested">;
+    delegationId: z.ZodString;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The person moved on: a newer delegation opened before this one's `final`
+ * reply (contract set 8.16.0). Its reply is no longer spoken, and a command
+ * naming it is refused.
+ */
+export declare const realtimeDelegationSupersededEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"delegation.superseded">;
+    delegationId: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /** How a response ended. */
 export declare const realtimeResponseStatusSchema: z.ZodEnum<{
     cancelled: "cancelled";
@@ -1098,6 +1243,16 @@ 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[];
+/**
+ * Whether a session of this kind takes a command (contract set 8.16.0, Kaana
+ * ADR 0012): a `live` session takes no `session.update`, `input_audio.commit`
+ * or `input_audio.clear`, because its voice fixes the session at open and
+ * detects the turns, and only a `live` session takes the `delegation.*`
+ * commands. Kaana refuses any other with `invalid_request`, param `type`,
+ * before acknowledging it. Whether the model serves a command it takes is the
+ * model's to answer.
+ */
+export declare function realtimeSessionTakes(kind: z.infer<typeof realtimeSessionKindSchema>, command: z.infer<typeof realtimeClientCommandSchema>['type']): boolean;
 /**
  * The customer's partial limits request: every signed limit, each filled from
  * Kaana's defaults when omitted, never above them.
@@ -1138,6 +1293,7 @@ export declare const realtimeSessionOpenSchema: z.ZodObject<{
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>;
     transport: z.ZodOptional<z.ZodEnum<{
         websocket: "websocket";
@@ -1202,6 +1358,12 @@ export declare const realtimeSessionOpenSchema: z.ZodObject<{
             name: z.ZodString;
         }, z.core.$strict>]>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        delegation: z.ZodOptional<z.ZodObject<{
+            acknowledgement: z.ZodEnum<{
+                auto: "auto";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     limits: z.ZodOptional<z.ZodObject<{
         maxDurationMs: z.ZodOptional<z.ZodNumber>;
@@ -1252,6 +1414,7 @@ export declare const realtimePublicSessionCreatedEventSchema: z.ZodObject<{
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>;
     config: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
@@ -1313,6 +1476,12 @@ export declare const realtimePublicSessionCreatedEventSchema: z.ZodObject<{
             name: z.ZodString;
         }, z.core.$strict>]>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        delegation: z.ZodOptional<z.ZodObject<{
+            acknowledgement: z.ZodEnum<{
+                auto: "auto";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
         maxDurationMs: z.ZodNumber;
@@ -1492,6 +1661,7 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>;
     config: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
@@ -1553,6 +1723,12 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
             name: z.ZodString;
         }, z.core.$strict>]>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        delegation: z.ZodOptional<z.ZodObject<{
+            acknowledgement: z.ZodEnum<{
+                auto: "auto";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     limits: z.ZodObject<{
         maxDurationMs: z.ZodNumber;
@@ -1630,6 +1806,12 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
             name: z.ZodString;
         }, z.core.$strict>]>>;
         maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        delegation: z.ZodOptional<z.ZodObject<{
+            acknowledgement: z.ZodEnum<{
+                auto: "auto";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     schemaVersion: z.ZodLiteral<1>;
     requestId: z.ZodString;
@@ -1889,6 +2071,21 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
     requestId: z.ZodString;
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"delegation.requested">;
+    delegationId: z.ZodString;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"delegation.superseded">;
+    delegationId: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"response.done">;
     responseId: z.ZodString;
@@ -2041,6 +2238,13 @@ export type RealtimeTurnDetection = z.infer<typeof realtimeTurnDetectionSchema>;
 export type RealtimeInputTranscription = z.infer<typeof realtimeInputTranscriptionSchema>;
 export type RealtimeTranslation = z.infer<typeof realtimeTranslationSchema>;
 export type RealtimeSessionConfig = z.infer<typeof realtimeSessionConfigSchema>;
+export type RealtimeDelegationAcknowledgement = z.infer<typeof realtimeDelegationAcknowledgementSchema>;
+export type RealtimeDelegationConfig = z.infer<typeof realtimeDelegationConfigSchema>;
+export type RealtimeDelegationReplyCommand = z.infer<typeof realtimeDelegationReplyCommandSchema>;
+export type RealtimeDelegationContextCommand = z.infer<typeof realtimeDelegationContextCommandSchema>;
+export type RealtimeDelegationCancelCommand = z.infer<typeof realtimeDelegationCancelCommandSchema>;
+export type RealtimeDelegationRequestedEvent = z.infer<typeof realtimeDelegationRequestedEventSchema>;
+export type RealtimeDelegationSupersededEvent = z.infer<typeof realtimeDelegationSupersededEventSchema>;
 export type RealtimeSessionConfigUpdate = z.infer<typeof realtimeSessionConfigUpdateSchema>;
 export type RealtimeSessionLimits = z.infer<typeof realtimeSessionLimitsSchema>;
 export type RealtimeContentPart = z.infer<typeof realtimeContentPartSchema>;

package/dist/public/realtime.js

@@ -36,6 +36,17 @@ export const MAX_REALTIME_RESUME_WINDOW_MS = 60_000;
  * reads it here, never copies it.
  */
 export const MAX_REALTIME_ITEM_TEXT_CHARS = 1_048_576;
+/**
+ * The most characters (UTF-16 code units) the text of one `delegation.reply` or
+ * `delegation.context` may hold (contract set 8.16.0). A client streams a long
+ * answer as several replies, sentence by sentence; Kaana splits each to its
+ * provider's own bound.
+ */
+export const MAX_REALTIME_DELEGATION_TEXT_CHARS = 8_192;
+/** The most verbatim spans one `delegation.reply` may mark (contract set 8.16.0). */
+export const MAX_REALTIME_VERBATIM_SPANS = 32;
+/** The most characters (UTF-16 code units) one verbatim span may hold (contract set 8.16.0). */
+export const MAX_REALTIME_VERBATIM_SPAN_CHARS = 256;
 /** A client-chosen command identity, unique within one session. */
 export const realtimeCommandIdSchema = z
     .string()
@@ -43,6 +54,14 @@ export const realtimeCommandIdSchema = z
     .check(maxUtf16Length(128));
 /** A conversation item's identity within one session. */
 export const realtimeItemIdSchema = z.string().check(minUtf16Length(1)).check(maxUtf16Length(128));
+/**
+ * A delegation's identity within one session: one turn a `live` session handed
+ * to its caller (contract set 8.16.0).
+ */
+export const realtimeDelegationIdSchema = z
+    .string()
+    .check(minUtf16Length(1))
+    .check(maxUtf16Length(128));
 /** A response's identity within one session. */
 export const realtimeResponseIdSchema = z
     .string()
@@ -105,6 +124,10 @@ export const realtimeTurnDetectionSchema = z.discriminatedUnion('type', [
  * session: where the provider bills the transcription
  * apart from the session model, as `input_transcription_milliseconds` (see
  * `USAGE_UNITS`); where the session's own price includes it, as nothing more.
+ *
+ * A `live` session relays the caller's words whether or not it is set, because
+ * its delegation needs them; there it takes `language` only (contract set
+ * 8.16.0).
  */
 export const realtimeInputTranscriptionSchema = z
     .object({
@@ -131,6 +154,21 @@ export const realtimeTranslationSchema = z
     targetLanguage: z.string().check(minUtf16Length(2)).check(maxUtf16Length(35)),
 })
     .strict();
+/**
+ * Whether the voice of a `live` session acknowledges a turn it handed over:
+ * `auto` lets it say a short "one moment" while the caller's backend works;
+ * `none` keeps it silent until the first reply.
+ */
+export const realtimeDelegationAcknowledgementSchema = z.enum(['auto', 'none']);
+/**
+ * How a `live` session hands its turns to its caller (contract set 8.16.0,
+ * Kaana ADR 0012). Required for `live` and refused for every other kind.
+ */
+export const realtimeDelegationConfigSchema = z
+    .object({
+    acknowledgement: realtimeDelegationAcknowledgementSchema,
+})
+    .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).
@@ -162,6 +200,8 @@ export const realtimeSessionConfigSchema = z
     toolChoice: toolChoiceSchema.optional(),
     /** Per response, not per session: the session's ceiling is `limits`. */
     maxOutputTokens: z.number().int().positive().safe().optional(),
+    /** A `live` session's delegation; fixed at open (contract set 8.16.0). */
+    delegation: realtimeDelegationConfigSchema.optional(),
 })
     .strict();
 /**
@@ -184,6 +224,8 @@ export const realtimeSessionConfigUpdateSchema = z
 })
     .strict()
     .superRefine((update, ctx) => {
+    // A `live` session takes no update at all: its voice fixes everything at
+    // open, and Kaana refuses the command (`invalid_request`, param `type`).
     if (Object.keys(update).length === 0) {
         ctx.addIssue({
             code: 'custom',
@@ -377,8 +419,53 @@ export const realtimeSessionCloseCommandSchema = z.object({
     ...commandBase,
     type: z.literal('session.close'),
 });
-/** Every command a client can send. */
-export const realtimeClientCommandSchema = z.discriminatedUnion('type', [
+const delegationTextSchema = z
+    .string()
+    .check(minUtf16Length(1))
+    .check(maxUtf16Length(MAX_REALTIME_DELEGATION_TEXT_CHARS));
+/**
+ * Speak this part of a delegated turn's answer (contract set 8.16.0). A client
+ * streams its answer sentence by sentence and marks the last part `final`;
+ * after it, nothing more is spoken for the delegation. Each `verbatim` span is
+ * a part of `text` the voice says exactly as written: numbers, addresses,
+ * names, codes. A reply to a delegation that is unknown, superseded, cancelled
+ * or already final is refused (`invalid_request`, param `delegationId`).
+ */
+export const realtimeDelegationReplyCommandSchema = z.object({
+    ...commandBase,
+    type: z.literal('delegation.reply'),
+    delegationId: realtimeDelegationIdSchema,
+    text: delegationTextSchema,
+    verbatim: z
+        .array(z.string().check(minUtf16Length(1)).check(maxUtf16Length(MAX_REALTIME_VERBATIM_SPAN_CHARS)))
+        .max(MAX_REALTIME_VERBATIM_SPANS)
+        .optional(),
+    final: z.boolean(),
+});
+/**
+ * Silent context the voice may use while a delegated turn is answered, for
+ * example "still checking your calendar" (contract set 8.16.0). Never spoken
+ * as written.
+ */
+export const realtimeDelegationContextCommandSchema = z.object({
+    ...commandBase,
+    type: z.literal('delegation.context'),
+    delegationId: realtimeDelegationIdSchema,
+    text: delegationTextSchema,
+});
+/** The client dropped a delegated turn: nothing more is spoken for it (contract set 8.16.0). */
+export const realtimeDelegationCancelCommandSchema = z.object({
+    ...commandBase,
+    type: z.literal('delegation.cancel'),
+    delegationId: realtimeDelegationIdSchema,
+});
+/**
+ * Every command a client can send. The three `delegation.*` commands are a
+ * `live` session's; `session.update`, `input_audio.commit` and
+ * `input_audio.clear` are refused on one (`invalid_request`, param `type`).
+ */
+export const realtimeClientCommandSchema = z
+    .discriminatedUnion('type', [
     realtimeSessionUpdateCommandSchema,
     realtimeItemCreateCommandSchema,
     realtimeItemDeleteCommandSchema,
@@ -390,7 +477,25 @@ export const realtimeClientCommandSchema = z.discriminatedUnion('type', [
     realtimeResponseCancelCommandSchema,
     realtimeSessionResumeCommandSchema,
     realtimeSessionCloseCommandSchema,
-]);
+    realtimeDelegationReplyCommandSchema,
+    realtimeDelegationContextCommandSchema,
+    realtimeDelegationCancelCommandSchema,
+])
+    .superRefine((command, ctx) => {
+    // Checked on the union because a discriminated union's options must stay
+    // plain objects.
+    if (command.type !== 'delegation.reply' || command.verbatim === undefined)
+        return;
+    for (const [index, span] of command.verbatim.entries()) {
+        if (!command.text.includes(span)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['verbatim', index],
+                message: 'a verbatim span is a part of the reply text, exactly as written',
+            });
+        }
+    }
+});
 const eventBase = {
     /** See `version.ts`: each event is a whole message on the wire. */
     schemaVersion: z.literal(1),
@@ -550,6 +655,29 @@ export const realtimeToolCallEventSchema = z.object({
     argumentsDelta: z.string().optional(),
     complete: z.boolean(),
 });
+/**
+ * A `live` session hands one turn to its caller (contract set 8.16.0). `text`
+ * is the caller's words since the previous delegation, assembled by Kaana from
+ * the input transcript, so no client stitches transcripts. Answer it with
+ * `delegation.reply`; a newer delegation before its `final` reply supersedes
+ * it.
+ */
+export const realtimeDelegationRequestedEventSchema = z.object({
+    ...eventBase,
+    type: z.literal('delegation.requested'),
+    delegationId: realtimeDelegationIdSchema,
+    text: z.string(),
+});
+/**
+ * The person moved on: a newer delegation opened before this one's `final`
+ * reply (contract set 8.16.0). Its reply is no longer spoken, and a command
+ * naming it is refused.
+ */
+export const realtimeDelegationSupersededEventSchema = z.object({
+    ...eventBase,
+    type: z.literal('delegation.superseded'),
+    delegationId: realtimeDelegationIdSchema,
+});
 /** How a response ended. */
 export const realtimeResponseStatusSchema = z.enum([
     'completed',
@@ -622,6 +750,39 @@ export function realtimeConfigIssues(kind, config) {
                 found(['tools'], 'a translation session calls no tools');
             }
             break;
+        case 'live':
+            // Kaana ADR 0012 §1: the voice speaks, detects turns and hands each one
+            // over; the caller's backend answers it, with its own tools.
+            if (config.voice === undefined) {
+                found(['voice'], 'a live session speaks in a voice');
+            }
+            if (config.outputAudioFormat !== config.inputAudioFormat) {
+                found(['outputAudioFormat'], 'a live session speaks the audio format it hears');
+            }
+            if (config.turnDetection.type === 'none') {
+                found(['turnDetection'], 'the voice of a live session detects the turns');
+            }
+            if (config.delegation === undefined) {
+                found(['delegation'], 'a live session hands its turns over');
+            }
+            for (const field of [
+                'outputModalities',
+                'tools',
+                'toolChoice',
+                'maxOutputTokens',
+                'translation',
+            ]) {
+                if (config[field] !== undefined) {
+                    found([field], "a live session's answers and their tools are its caller's");
+                }
+            }
+            if (config.inputAudioTranscription?.prompt !== undefined) {
+                found(['inputAudioTranscription', 'prompt'], 'a live session transcribes with no prompt');
+            }
+            break;
+    }
+    if (kind !== 'live' && config.delegation !== undefined) {
+        found(['delegation'], 'only a live session hands its turns over');
     }
     if (kind !== 'transcription' && config.inputAudioTranscription?.interimResults === true) {
         found(['inputAudioTranscription', 'interimResults'], 'only a transcription session sends interim text');
@@ -641,6 +802,25 @@ export function realtimeConfigIssues(kind, config) {
     }
     return issues;
 }
+const REFUSED_BY_LIVE = new Set([
+    'session.update',
+    'input_audio.commit',
+    'input_audio.clear',
+]);
+/**
+ * Whether a session of this kind takes a command (contract set 8.16.0, Kaana
+ * ADR 0012): a `live` session takes no `session.update`, `input_audio.commit`
+ * or `input_audio.clear`, because its voice fixes the session at open and
+ * detects the turns, and only a `live` session takes the `delegation.*`
+ * commands. Kaana refuses any other with `invalid_request`, param `type`,
+ * before acknowledging it. Whether the model serves a command it takes is the
+ * model's to answer.
+ */
+export function realtimeSessionTakes(kind, command) {
+    if (kind === 'live')
+        return !REFUSED_BY_LIVE.has(command);
+    return !command.startsWith('delegation.');
+}
 /* -------------------------------------------------------------------------- */
 /*  Opening a session (`GET /v1/realtime`)                                     */
 /* -------------------------------------------------------------------------- */
@@ -835,6 +1015,8 @@ export const realtimePublicServerEventSchema = z
     realtimeTranscriptInterimEventSchema,
     realtimeTextDeltaEventSchema,
     realtimeToolCallEventSchema,
+    realtimeDelegationRequestedEventSchema,
+    realtimeDelegationSupersededEventSchema,
     realtimePublicResponseDoneEventSchema,
     realtimePublicErrorEventSchema,
     realtimePublicSessionClosedEventSchema,

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 = "8.15.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.16.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:
@@ -265,6 +265,17 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.15.0";
  * `POST /v1/rerank` and emits the `rerank` operation for a model some deployment
  * can serve.
  */
+/**
+ * Contract set 8.16.0 (Kaana ADR 0012) is additive: the realtime session kind
+ * `live`, a spoken conversation whose turns the caller's backend answers. Its
+ * `config.delegation` (`realtimeDelegationConfigSchema`), the commands
+ * `delegation.reply`, `delegation.context` and `delegation.cancel`, the events
+ * `delegation.requested` and `delegation.superseded`, and the catalogue's
+ * `capabilities.realtime.defaultKinds`, with at most one active default line per
+ * kind. Every 8.15.0 message parses the same; a consumer on 8.15.0 refuses a
+ * session, a command, an event or a catalogue carrying what is new, so Oxy reads
+ * them before Kaana serves a `live` line.
+ */
 /** 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. */

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 = '8.15.0';
+export const INFERENCE_CONTRACT_VERSION = '8.16.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:
@@ -265,6 +265,17 @@ export const INFERENCE_CONTRACT_VERSION = '8.15.0';
  * `POST /v1/rerank` and emits the `rerank` operation for a model some deployment
  * can serve.
  */
+/**
+ * Contract set 8.16.0 (Kaana ADR 0012) is additive: the realtime session kind
+ * `live`, a spoken conversation whose turns the caller's backend answers. Its
+ * `config.delegation` (`realtimeDelegationConfigSchema`), the commands
+ * `delegation.reply`, `delegation.context` and `delegation.cancel`, the events
+ * `delegation.requested` and `delegation.superseded`, and the catalogue's
+ * `capabilities.realtime.defaultKinds`, with at most one active default line per
+ * kind. Every 8.15.0 message parses the same; a consumer on 8.15.0 refuses a
+ * session, a command, an event or a catalogue carrying what is new, so Oxy reads
+ * them before Kaana serves a `live` line.
+ */
 /** 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. */