@kaana.ai/contracts 8.15.0 → 8.17.0

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.17.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,26 @@ 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.
+ */
+/**
+ * Contract set 8.17.0 publishes `CATALOGUE_ADDITIONS`: the catalogue values a
+ * reader on an earlier set refuses, each with the set that introduced it, and
+ * makes the request's `Kaana-Contract-Version` the set `GET /v1/models` is
+ * rendered in. No shape, field or member changes, and every 8.16.0 message
+ * parses the same; MINOR because Kaana now answers a caller by the set it
+ * states, which is what keeps a value added to the catalogue from refusing a
+ * deployed reader's whole list.
+ */
 /** 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. */
@@ -272,8 +292,9 @@ export const KAANA_REQUEST_ID_HEADER = 'Kaana-Request-Id';
 /**
  * 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. Every set since 4.0.0 parses the
- * catalogue Kaana serves.
+ * later), the set the client parses. `GET /v1/models` is rendered in the set
+ * a request states, without any value of {@link CATALOGUE_ADDITIONS} that set
+ * lacks; a request that states none receives none of them.
  */
 export const KAANA_CONTRACT_VERSION_HEADER = 'Kaana-Contract-Version';
 /**

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.15.0",
+    "version": "8.17.0",
     "description": "Kaana inference API. Generated from @kaana.ai/contracts; the Zod source is the authority. Accounts, applications, oxy_sk_ keys, limits and billing are managed in Oxy Console: https://console.oxy.so"
   },
   "servers": [
@@ -5203,6 +5203,13 @@
               "$ref": "#/components/schemas/RealtimeSessionKind"
             }
           },
+          "defaultKinds": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RealtimeSessionKind"
+            }
+          },
           "inputAudioTranscription": {
             "type": "boolean"
           },
@@ -5734,6 +5741,15 @@
           },
           {
             "$ref": "#/components/schemas/RealtimeSessionCloseCommand"
+          },
+          {
+            "$ref": "#/components/schemas/RealtimeDelegationReplyCommand"
+          },
+          {
+            "$ref": "#/components/schemas/RealtimeDelegationContextCommand"
+          },
+          {
+            "$ref": "#/components/schemas/RealtimeDelegationCancelCommand"
           }
         ]
       },
@@ -5959,6 +5975,214 @@
           }
         ]
       },
+      "RealtimeDelegationAcknowledgement": {
+        "type": "string",
+        "enum": [
+          "auto",
+          "none"
+        ]
+      },
+      "RealtimeDelegationCancelCommand": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "delegation.cancel"
+          },
+          "delegationId": {
+            "$ref": "#/components/schemas/RealtimeDelegationId"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "commandId",
+          "type",
+          "delegationId"
+        ]
+      },
+      "RealtimeDelegationConfig": {
+        "type": "object",
+        "properties": {
+          "acknowledgement": {
+            "$ref": "#/components/schemas/RealtimeDelegationAcknowledgement"
+          }
+        },
+        "required": [
+          "acknowledgement"
+        ],
+        "additionalProperties": false
+      },
+      "RealtimeDelegationContextCommand": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "delegation.context"
+          },
+          "delegationId": {
+            "$ref": "#/components/schemas/RealtimeDelegationId"
+          },
+          "text": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8192
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "commandId",
+          "type",
+          "delegationId",
+          "text"
+        ]
+      },
+      "RealtimeDelegationId": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128
+      },
+      "RealtimeDelegationReplyCommand": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "delegation.reply"
+          },
+          "delegationId": {
+            "$ref": "#/components/schemas/RealtimeDelegationId"
+          },
+          "text": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8192
+          },
+          "verbatim": {
+            "maxItems": 32,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            }
+          },
+          "final": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "commandId",
+          "type",
+          "delegationId",
+          "text",
+          "final"
+        ]
+      },
+      "RealtimeDelegationRequestedEvent": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "sequence": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "delegation.requested"
+          },
+          "delegationId": {
+            "$ref": "#/components/schemas/RealtimeDelegationId"
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "sequence",
+          "type",
+          "delegationId",
+          "text"
+        ]
+      },
+      "RealtimeDelegationSupersededEvent": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "sequence": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "delegation.superseded"
+          },
+          "delegationId": {
+            "$ref": "#/components/schemas/RealtimeDelegationId"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "sequence",
+          "type",
+          "delegationId"
+        ]
+      },
       "RealtimeInputAudioAppendCommand": {
         "type": "object",
         "properties": {
@@ -6681,6 +6905,12 @@
           {
             "$ref": "#/components/schemas/RealtimeToolCallEvent"
           },
+          {
+            "$ref": "#/components/schemas/RealtimeDelegationRequestedEvent"
+          },
+          {
+            "$ref": "#/components/schemas/RealtimeDelegationSupersededEvent"
+          },
           {
             "$ref": "#/components/schemas/RealtimePublicResponseDoneEvent"
           },
@@ -7019,6 +7249,9 @@
             "type": "integer",
             "exclusiveMinimum": 0,
             "maximum": 9007199254740991
+          },
+          "delegation": {
+            "$ref": "#/components/schemas/RealtimeDelegationConfig"
           }
         },
         "required": [
@@ -7071,7 +7304,8 @@
         "enum": [
           "conversation",
           "transcription",
-          "translation"
+          "translation",
+          "live"
         ]
       },
       "RealtimeSessionLimits": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaana.ai/contracts",
-  "version": "8.15.0",
+  "version": "8.17.0",
   "description": "Kaana inference contract: the Zod schemas of the public API at https://kaana.ai/v1 and, under /internal, of the Oxy-Kaana grant, settlement and signed lane.",
   "type": "module",
   "sideEffects": false,