@kaana.ai/contracts 8.15.0 → 8.17.0

package/dist/internal/catalogue.d.ts

@@ -98,7 +98,14 @@ export declare const catalogueModelSchema: z.ZodObject<{
                 conversation: "conversation";
                 transcription: "transcription";
                 translation: "translation";
+                live: "live";
             }>>;
+            defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                conversation: "conversation";
+                transcription: "transcription";
+                translation: "translation";
+                live: "live";
+            }>>>;
             inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
             audioFormats: z.ZodOptional<z.ZodObject<{
                 input: z.ZodArray<z.ZodEnum<{
@@ -428,7 +435,14 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
                 conversation: "conversation";
                 transcription: "transcription";
                 translation: "translation";
+                live: "live";
             }>>;
+            defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                conversation: "conversation";
+                transcription: "transcription";
+                translation: "translation";
+                live: "live";
+            }>>>;
             inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
             audioFormats: z.ZodOptional<z.ZodObject<{
                 input: z.ZodArray<z.ZodEnum<{
@@ -704,7 +718,14 @@ export declare const declaredModelSchema: z.ZodObject<{
                 conversation: "conversation";
                 transcription: "transcription";
                 translation: "translation";
+                live: "live";
             }>>;
+            defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                conversation: "conversation";
+                transcription: "transcription";
+                translation: "translation";
+                live: "live";
+            }>>>;
             inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
             audioFormats: z.ZodOptional<z.ZodObject<{
                 input: z.ZodArray<z.ZodEnum<{
@@ -943,7 +964,14 @@ export declare const declaredCatalogueSchema: z.ZodObject<{
                     conversation: "conversation";
                     transcription: "transcription";
                     translation: "translation";
+                    live: "live";
                 }>>;
+                defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                    conversation: "conversation";
+                    transcription: "transcription";
+                    translation: "translation";
+                    live: "live";
+                }>>>;
                 inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
                 audioFormats: z.ZodOptional<z.ZodObject<{
                     input: z.ZodArray<z.ZodEnum<{

package/dist/internal/catalogue.js

@@ -417,4 +417,27 @@ export const declaredCatalogueSchema = z
     schemaVersion: z.literal(1),
     models: z.array(declaredModelSchema),
 })
-    .strict();
+    .strict()
+    .superRefine((catalogue, ctx) => {
+    // A kind has one default (contract set 8.16.0, Kaana ADR 0012): a client
+    // opens the default line of a kind, so two active defaults would leave the
+    // choice to whichever the client read first.
+    const defaults = new Map();
+    for (const [index, model] of catalogue.models.entries()) {
+        if (model.deprecation.status !== 'active')
+            continue;
+        for (const kind of model.capabilities.realtime?.defaultKinds ?? []) {
+            const first = defaults.get(kind);
+            if (first !== undefined) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['models', index, 'capabilities', 'realtime', 'defaultKinds'],
+                    message: `models[${first}] is already the default ${kind} line: at most one active line is the default of a kind`,
+                });
+            }
+            else {
+                defaults.set(kind, index);
+            }
+        }
+    }
+});

package/dist/internal/grant.d.ts

@@ -82,6 +82,7 @@ export declare const grantRequestFactsSchema: z.ZodObject<{
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>>;
 }, z.core.$strict>;
 /**
@@ -135,6 +136,7 @@ export declare const inferenceAuthorizationRequestSchema: z.ZodObject<{
             conversation: "conversation";
             transcription: "transcription";
             translation: "translation";
+            live: "live";
         }>>;
     }, z.core.$strict>;
     idempotencyKey: z.ZodOptional<z.ZodString>;
@@ -216,6 +218,7 @@ export declare const authorizationRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
             conversation: "conversation";
             transcription: "transcription";
             translation: "translation";
+            live: "live";
         }>>;
     }, z.core.$strict>;
     idempotencyKey: z.ZodOptional<z.ZodString>;

package/dist/internal/realtime.d.ts

@@ -64,6 +64,7 @@ export declare const realtimeSessionRequestSchema: z.ZodObject<{
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>;
     transport: z.ZodEnum<{
         websocket: "websocket";
@@ -128,6 +129,12 @@ export declare const realtimeSessionRequestSchema: 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;
@@ -208,6 +215,7 @@ export declare const realtimeSessionCreatedEventSchema: z.ZodObject<{
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>;
     config: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
@@ -269,6 +277,12 @@ export declare const realtimeSessionCreatedEventSchema: 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;
@@ -468,6 +482,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>;
     config: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
@@ -529,6 +544,12 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
             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;
@@ -606,6 +627,12 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
             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;
@@ -865,6 +892,21 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     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;

package/dist/internal/realtime.js

@@ -11,7 +11,7 @@ import { inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from
 import { usageQuantitySchema, usageSourceSchema } from '../public/money.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceFinishReasonSchema } from '../public/streamEvents.js';
-import { MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandAcceptedEventSchema, realtimeCommandIdSchema, realtimeConfigIssues, realtimeInputAudioClearedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeItemAddedEventSchema, realtimeItemDeletedEventSchema, realtimeItemDoneEventSchema, realtimeItemTruncatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeResponseCreatedEventSchema, realtimeResponseIdSchema, realtimeResponseStatusSchema, realtimeSessionCloseReasonSchema, realtimeSessionConfigSchema, realtimeSessionLimitsSchema, realtimeSessionResumedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, realtimeTranscriptInterimEventSchema, } from '../public/realtime.js';
+import { MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandAcceptedEventSchema, realtimeCommandIdSchema, realtimeConfigIssues, realtimeDelegationRequestedEventSchema, realtimeDelegationSupersededEventSchema, realtimeInputAudioClearedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeItemAddedEventSchema, realtimeItemDeletedEventSchema, realtimeItemDoneEventSchema, realtimeItemTruncatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeResponseCreatedEventSchema, realtimeResponseIdSchema, realtimeResponseStatusSchema, realtimeSessionCloseReasonSchema, realtimeSessionConfigSchema, realtimeSessionLimitsSchema, realtimeSessionResumedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, realtimeTranscriptInterimEventSchema, } from '../public/realtime.js';
 import { inferenceAttributionSchema } from './attribution.js';
 import { inferenceErrorSchema } from './errors.js';
 import { deploymentIdSchema, inferenceProviderSlugSchema } from './identifiers.js';
@@ -168,6 +168,8 @@ export const realtimeServerEventSchema = z
     realtimeTranscriptInterimEventSchema,
     realtimeTextDeltaEventSchema,
     realtimeToolCallEventSchema,
+    realtimeDelegationRequestedEventSchema,
+    realtimeDelegationSupersededEventSchema,
     realtimeResponseDoneEventSchema,
     realtimeErrorEventSchema,
     realtimeSessionClosedEventSchema,

package/dist/public/catalogue.d.ts

@@ -93,19 +93,23 @@ export declare const inferenceApiFormatSchema: z.ZodEnum<{
     batches: "batches";
 }>;
 /**
- * What a realtime session is FOR. The three are different upstream products
- * with different event families and different metering, not options of one:
+ * What a realtime session is FOR. They are different upstream products with
+ * different event families and different metering, not options of one:
  *
  *  - `conversation` — a speech-to-speech (or text) model holding a dialogue,
  *    with responses, tool calls and interruption.
  *  - `transcription` — live speech-to-text; the model never responds, it only
  *    transcribes committed input audio.
  *  - `translation` — live speech-to-speech translation into one target language.
+ *  - `live` — a spoken conversation whose turns the CALLER's backend answers
+ *    (contract set 8.16.0, Kaana ADR 0012): the voice hands each turn over as
+ *    `delegation.requested` and speaks the `delegation.reply` it is given.
  */
 export declare const realtimeSessionKindSchema: z.ZodEnum<{
     conversation: "conversation";
     transcription: "transcription";
     translation: "translation";
+    live: "live";
 }>;
 /**
  * How a realtime session is carried. One member today: a WebSocket, whose every
@@ -133,6 +137,13 @@ export declare const realtimeSessionTransportSchema: z.ZodEnum<{
  * - `audioFormats` — the realtime encodings a session may name as
  *   `config.inputAudioFormat` and `config.outputAudioFormat`. These are not the
  *   media types of `audio.audioFormats`, which describe files.
+ *
+ * `defaultKinds` arrived in contract set 8.16.0 (Kaana ADR 0012): the session
+ * kinds for which this line is Kaana's default, each one of its `sessionKinds`.
+ * A client opens the default line of a kind after reading `GET /v1/models`, so
+ * which provider serves a kind is a catalogue decision and never a client
+ * constant. At most one active line is the default of a kind. Absent means the
+ * line is the default of none.
  */
 export declare const modelRealtimeCapabilitiesSchema: z.ZodObject<{
     transports: z.ZodArray<z.ZodEnum<{
@@ -142,7 +153,14 @@ export declare const modelRealtimeCapabilitiesSchema: z.ZodObject<{
         conversation: "conversation";
         transcription: "transcription";
         translation: "translation";
+        live: "live";
     }>>;
+    defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        conversation: "conversation";
+        transcription: "transcription";
+        translation: "translation";
+        live: "live";
+    }>>>;
     inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
     audioFormats: z.ZodOptional<z.ZodObject<{
         input: z.ZodArray<z.ZodEnum<{
@@ -216,7 +234,14 @@ export declare const modelCapabilitiesSchema: z.ZodObject<{
             conversation: "conversation";
             transcription: "transcription";
             translation: "translation";
+            live: "live";
         }>>;
+        defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            conversation: "conversation";
+            transcription: "transcription";
+            translation: "translation";
+            live: "live";
+        }>>>;
         inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
         audioFormats: z.ZodOptional<z.ZodObject<{
             input: z.ZodArray<z.ZodEnum<{
@@ -480,7 +505,14 @@ export declare const modelSchema: z.ZodObject<{
                 conversation: "conversation";
                 transcription: "transcription";
                 translation: "translation";
+                live: "live";
             }>>;
+            defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                conversation: "conversation";
+                transcription: "transcription";
+                translation: "translation";
+                live: "live";
+            }>>>;
             inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
             audioFormats: z.ZodOptional<z.ZodObject<{
                 input: z.ZodArray<z.ZodEnum<{
@@ -707,7 +739,14 @@ export declare const modelListSchema: z.ZodObject<{
                     conversation: "conversation";
                     transcription: "transcription";
                     translation: "translation";
+                    live: "live";
                 }>>;
+                defaultKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                    conversation: "conversation";
+                    transcription: "transcription";
+                    translation: "translation";
+                    live: "live";
+                }>>>;
                 inputAudioTranscription: z.ZodOptional<z.ZodBoolean>;
                 audioFormats: z.ZodOptional<z.ZodObject<{
                     input: z.ZodArray<z.ZodEnum<{
@@ -872,6 +911,38 @@ export declare const modelListSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strict>;
+/**
+ * One value `GET /v1/models` gained after a contract set (contract set 8.17.0).
+ *
+ * The catalogue's leaves are strict and its enums closed, so a reader refuses
+ * the WHOLE list on the first field or member its own set lacks. Kaana
+ * therefore renders the catalogue in the set the caller states in
+ * `Kaana-Contract-Version` (`@kaana.ai/sdk` 2.0.0 and later send it on every
+ * request): a value listed here reaches only a caller whose set is `since` or
+ * later. A caller that states no set, or one that does not parse, receives
+ * none of them.
+ *
+ * - `path` names a field of a model; a list on the way is crossed, applying the
+ *   rest of the path to each element.
+ * - Without `member`, the field is the addition and is left out.
+ * - With `member`, the value at `path` is an enum and `member` is the addition:
+ *   the list element that holds it is left out (the member itself in a list of
+ *   members; the object carrying it in a list of objects). When that empties
+ *   the list, the field at `emptied` (the nearest optional field holding the
+ *   list) is left out with it.
+ *
+ * Adding a member to an enum the catalogue reaches, or a field to one of its
+ * strict objects, appends an entry here in the same change; the
+ * `@kaana.ai/sdk` compatibility suite compares this list with the published
+ * releases deployed readers run.
+ */
+export interface CatalogueAddition {
+    readonly since: string;
+    readonly path: readonly string[];
+    readonly member?: string;
+    readonly emptied?: readonly string[];
+}
+export declare const CATALOGUE_ADDITIONS: readonly CatalogueAddition[];
 /**
  * One power level as `GET /v1/power-levels` lists it for the calling
  * credential: the level, the class it draws from, the effort it asks for, and

package/dist/public/catalogue.js

@@ -78,16 +78,24 @@ export const inferenceApiFormatSchema = z.enum([
     'batches',
 ]);
 /**
- * What a realtime session is FOR. The three are different upstream products
- * with different event families and different metering, not options of one:
+ * What a realtime session is FOR. They are different upstream products with
+ * different event families and different metering, not options of one:
  *
  *  - `conversation` — a speech-to-speech (or text) model holding a dialogue,
  *    with responses, tool calls and interruption.
  *  - `transcription` — live speech-to-text; the model never responds, it only
  *    transcribes committed input audio.
  *  - `translation` — live speech-to-speech translation into one target language.
+ *  - `live` — a spoken conversation whose turns the CALLER's backend answers
+ *    (contract set 8.16.0, Kaana ADR 0012): the voice hands each turn over as
+ *    `delegation.requested` and speaks the `delegation.reply` it is given.
  */
-export const realtimeSessionKindSchema = z.enum(['conversation', 'transcription', 'translation']);
+export const realtimeSessionKindSchema = z.enum([
+    'conversation',
+    'transcription',
+    'translation',
+    'live',
+]);
 /**
  * How a realtime session is carried. One member today: a WebSocket, whose every
  * frame is one JSON message (see `realtime.ts`). WebRTC and SIP are separate
@@ -112,11 +120,19 @@ export const realtimeSessionTransportSchema = z.enum(['websocket']);
  * - `audioFormats` — the realtime encodings a session may name as
  *   `config.inputAudioFormat` and `config.outputAudioFormat`. These are not the
  *   media types of `audio.audioFormats`, which describe files.
+ *
+ * `defaultKinds` arrived in contract set 8.16.0 (Kaana ADR 0012): the session
+ * kinds for which this line is Kaana's default, each one of its `sessionKinds`.
+ * A client opens the default line of a kind after reading `GET /v1/models`, so
+ * which provider serves a kind is a catalogue decision and never a client
+ * constant. At most one active line is the default of a kind. Absent means the
+ * line is the default of none.
  */
 export const modelRealtimeCapabilitiesSchema = z
     .object({
     transports: z.array(realtimeSessionTransportSchema).min(1),
     sessionKinds: z.array(realtimeSessionKindSchema).min(1),
+    defaultKinds: z.array(realtimeSessionKindSchema).min(1).optional(),
     inputAudioTranscription: z.boolean().optional(),
     audioFormats: z
         .object({
@@ -229,6 +245,25 @@ export const modelCapabilitiesSchema = z
             message: 'each session kind is declared at most once',
         });
     }
+    const defaults = realtime.defaultKinds;
+    if (defaults !== undefined) {
+        if (new Set(defaults).size !== defaults.length) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['realtime', 'defaultKinds'],
+                message: 'each default kind is declared at most once',
+            });
+        }
+        for (const [index, kind] of defaults.entries()) {
+            if (!realtime.sessionKinds.includes(kind)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['realtime', 'defaultKinds', index],
+                    message: `a line is the default only of a kind it holds, and it holds no ${kind} session`,
+                });
+            }
+        }
+    }
     if (new Set(realtime.transports).size !== realtime.transports.length) {
         ctx.addIssue({
             code: 'custom',
@@ -537,6 +572,22 @@ export const modelSchema = z.object({
 });
 /** `GET /v1/models`. */
 export const modelListSchema = z.object({ data: z.array(modelSchema) }).strict();
+export const CATALOGUE_ADDITIONS = [
+    { since: '8.4.0', path: ['capabilities', 'unreported'] },
+    {
+        since: '8.4.0',
+        path: ['pricing', 'unitPrices', 'unit'],
+        member: 'cache_write_input_tokens',
+        emptied: ['pricing'],
+    },
+    {
+        since: '8.16.0',
+        path: ['capabilities', 'realtime', 'sessionKinds'],
+        member: 'live',
+        emptied: ['capabilities', 'realtime'],
+    },
+    { since: '8.16.0', path: ['capabilities', 'realtime', 'defaultKinds'] },
+];
 /**
  * One power level as `GET /v1/power-levels` lists it for the calling
  * credential: the level, the class it draws from, the effort it asks for, and