@kaana.ai/contracts 8.7.0 → 8.8.0

package/dist/internal/request.d.ts

@@ -56,6 +56,7 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"image">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -71,6 +72,7 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
                 high: "high";
                 auto: "auto";
             }>>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"audio">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -92,6 +94,7 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
                 data: z.ZodString;
             }, z.core.$strict>], "kind">;
             filename: z.ZodOptional<z.ZodString>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;
@@ -244,6 +247,7 @@ export declare const inferenceRequestSchema: z.ZodObject<{
             content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"text">;
                 text: z.ZodString;
+                cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>, z.ZodObject<{
                 type: z.ZodLiteral<"image">;
                 source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -259,6 +263,7 @@ export declare const inferenceRequestSchema: z.ZodObject<{
                     high: "high";
                     auto: "auto";
                 }>>;
+                cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>, z.ZodObject<{
                 type: z.ZodLiteral<"audio">;
                 source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -280,6 +285,7 @@ export declare const inferenceRequestSchema: z.ZodObject<{
                     data: z.ZodString;
                 }, z.core.$strict>], "kind">;
                 filename: z.ZodOptional<z.ZodString>;
+                cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>, z.ZodObject<{
                 type: z.ZodLiteral<"refusal">;
                 text: z.ZodString;
@@ -355,6 +361,7 @@ export declare const inferenceRequestSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodOptional<z.ZodBoolean>;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         auto: "auto";

package/dist/public/chatCompletions.d.ts

@@ -31,6 +31,7 @@ export declare const chatCompletionMessageSchema: z.ZodObject<{
     content: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodString;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"image">;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -46,6 +47,7 @@ export declare const chatCompletionMessageSchema: z.ZodObject<{
             high: "high";
             auto: "auto";
         }>>;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"audio">;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -67,6 +69,7 @@ export declare const chatCompletionMessageSchema: z.ZodObject<{
             data: z.ZodString;
         }, z.core.$strict>], "kind">;
         filename: z.ZodOptional<z.ZodString>;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"refusal">;
         text: z.ZodString;
@@ -107,6 +110,7 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
         content: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"image">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -122,6 +126,7 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
                 high: "high";
                 auto: "auto";
             }>>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"audio">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -143,6 +148,7 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
                 data: z.ZodString;
             }, z.core.$strict>], "kind">;
             filename: z.ZodOptional<z.ZodString>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;

package/dist/public/messages.d.ts

@@ -65,6 +65,7 @@ export declare const inferenceContentSourceSchema: z.ZodDiscriminatedUnion<[z.Zo
 export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
+    cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"image">;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -80,6 +81,7 @@ export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodO
         high: "high";
         auto: "auto";
     }>>;
+    cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"audio">;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -101,6 +103,7 @@ export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodO
         data: z.ZodString;
     }, z.core.$strict>], "kind">;
     filename: z.ZodOptional<z.ZodString>;
+    cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"refusal">;
     text: z.ZodString;
@@ -202,6 +205,7 @@ export declare const inferenceMessageSchema: z.ZodObject<{
     content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodString;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"image">;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -217,6 +221,7 @@ export declare const inferenceMessageSchema: z.ZodObject<{
             high: "high";
             auto: "auto";
         }>>;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"audio">;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -238,6 +243,7 @@ export declare const inferenceMessageSchema: z.ZodObject<{
             data: z.ZodString;
         }, z.core.$strict>], "kind">;
         filename: z.ZodOptional<z.ZodString>;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"refusal">;
         text: z.ZodString;
@@ -275,6 +281,7 @@ export declare const toolDefinitionSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     strict: z.ZodOptional<z.ZodBoolean>;
+    cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /** Whether, and which, tool the model must call. */
 export declare const toolChoiceSchema: z.ZodUnion<readonly [z.ZodEnum<{

package/dist/public/messages.js

@@ -30,6 +30,22 @@ export const inferenceContentSourceSchema = z.discriminatedUnion('kind', [
     })
         .strict(),
 ]);
+/**
+ * A prompt-cache breakpoint (contract set 8.8.0): the prompt up to and including
+ * the part, system message or tool that carries it is to be cached by a provider
+ * that can express it. `true` is Anthropic's `cache_control: {type: "ephemeral"}`
+ * with the default 5-minute lifetime and nothing else: there is no lifetime
+ * field, because the one cache-write unit cannot price a longer one.
+ *
+ * It is a hint with no effect on the answer. A route that cannot express it
+ * ignores it and still succeeds; Kaana's executor sends it only to a route whose
+ * granted price version prices `cache_write_input_tokens`, so a cache write is
+ * never provoked that the customer is not charged for at its own rate. A provider
+ * that allows fewer breakpoints than are marked receives the earliest ones in
+ * prompt order (tools, then system, then messages). `false` is the same as absent.
+ * Only a part whose type a provider caches (`text`, `image`, `file`) carries it.
+ */
+const cacheBreakpointSchema = z.boolean().optional();
 /**
  * One part of a message's content. A message is always a list of parts.
  *
@@ -73,13 +89,20 @@ export const inferenceContentSourceSchema = z.discriminatedUnion('kind', [
  * the continuation is lost, the conversation is not.
  */
 export const inferenceContentPartSchema = z.discriminatedUnion('type', [
-    z.object({ type: z.literal('text'), text: z.string() }).strict(),
+    z
+        .object({
+        type: z.literal('text'),
+        text: z.string(),
+        cacheBreakpoint: cacheBreakpointSchema,
+    })
+        .strict(),
     z
         .object({
         type: z.literal('image'),
         source: inferenceContentSourceSchema,
         /** Provider-independent hint; providers that ignore it are unaffected. */
         detail: z.enum(['auto', 'low', 'high']).optional(),
+        cacheBreakpoint: cacheBreakpointSchema,
     })
         .strict(),
     z.object({ type: z.literal('audio'), source: inferenceContentSourceSchema }).strict(),
@@ -88,6 +111,7 @@ export const inferenceContentPartSchema = z.discriminatedUnion('type', [
         type: z.literal('file'),
         source: inferenceContentSourceSchema,
         filename: z.string().check(maxUtf16Length(255)).optional(),
+        cacheBreakpoint: cacheBreakpointSchema,
     })
         .strict(),
     /**
@@ -324,6 +348,8 @@ export const toolDefinitionSchema = z
     parameters: z.record(z.string(), z.unknown()),
     /** Ask the provider to enforce the schema, where it supports enforcement. */
     strict: z.boolean().optional(),
+    /** A prompt-cache breakpoint after this tool ({@link cacheBreakpointSchema}). */
+    cacheBreakpoint: cacheBreakpointSchema,
 })
     .strict();
 /** Whether, and which, tool the model must call. */

package/dist/public/realtime.js

@@ -135,7 +135,10 @@ export const realtimeTranslationSchema = z
  * 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 });
+export const realtimeToolDefinitionSchema = toolDefinitionSchema.omit({
+    strict: true,
+    cacheBreakpoint: true,
+});
 /**
  * A session's full configuration, as signed at open and as echoed back by
  * `session.created` and `session.updated`.

package/dist/public/responses.d.ts

@@ -53,6 +53,7 @@ export declare const responsesRequestSchema: z.ZodObject<{
         content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"image">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -68,6 +69,7 @@ export declare const responsesRequestSchema: z.ZodObject<{
                 high: "high";
                 auto: "auto";
             }>>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"audio">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -89,6 +91,7 @@ export declare const responsesRequestSchema: z.ZodObject<{
                 data: z.ZodString;
             }, z.core.$strict>], "kind">;
             filename: z.ZodOptional<z.ZodString>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;
@@ -120,6 +123,7 @@ export declare const responsesRequestSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodOptional<z.ZodBoolean>;
+        cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
     toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         auto: "auto";
@@ -207,6 +211,7 @@ export declare const responseSchema: z.ZodObject<{
         content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"image">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -222,6 +227,7 @@ export declare const responseSchema: z.ZodObject<{
                 high: "high";
                 auto: "auto";
             }>>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"audio">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -243,6 +249,7 @@ export declare const responseSchema: z.ZodObject<{
                 data: z.ZodString;
             }, z.core.$strict>], "kind">;
             filename: z.ZodOptional<z.ZodString>;
+            cacheBreakpoint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;

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.7.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.8.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:

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.7.0';
+export const INFERENCE_CONTRACT_VERSION = '8.8.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:

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.7.0",
+    "version": "8.8.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": [
@@ -4079,6 +4079,9 @@
               },
               "text": {
                 "type": "string"
+              },
+              "cacheBreakpoint": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -4104,6 +4107,9 @@
                   "low",
                   "high"
                 ]
+              },
+              "cacheBreakpoint": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -4142,6 +4148,9 @@
               "filename": {
                 "type": "string",
                 "maxLength": 255
+              },
+              "cacheBreakpoint": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -8308,6 +8317,9 @@
           },
           "strict": {
             "type": "boolean"
+          },
+          "cacheBreakpoint": {
+            "type": "boolean"
           }
         },
         "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaana.ai/contracts",
-  "version": "8.7.0",
+  "version": "8.8.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,