@kaana.ai/contracts 8.6.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/anthropicMessages.d.ts

@@ -11,12 +11,6 @@
  *
  * ## What is refused, and why
  *
- *  - **`cache_control`, anywhere** (on a block, a tool, `system` or the
- *    request). Kaana's usage units have no unit for a cache WRITE (see the
- *    Anthropic adapter's usage meter): a cache write is billed at a premium
- *    over input, so honouring the marker while folding the write into
- *    `input_tokens` would report less than the request cost. The marker is
- *    refused, by name and path, instead of being dropped.
  *  - **`thinking.display`** and every other `thinking` member this file does
  *    not name.
  *  - **Server tools** (`web_search`, `bash`, `text_editor`, …), `mcp_servers`,
@@ -25,6 +19,26 @@
  *  - **An image `url` source**: nothing fetches an image URL (ADR 0007); a
  *    `base64` source is carried inline under the image rules.
  *
+ * ## `cache_control`: accepted and IGNORED
+ *
+ * Claude Code puts a `cache_control` marker on every request, so refusing it
+ * made the endpoint unusable by its main client. The marker is accepted wherever
+ * the dialect puts it (the request, `system`, a tool, a content block) and is
+ * NOT honoured: Kaana forwards no cache hint, so no cache write happens and the
+ * usage it reports stays exactly what the request cost. The only effect is the
+ * one the caller asked for and does not get: no prompt-cache discount on a write
+ * (reads that a provider caches on its own are still metered as
+ * `cache_read_input_tokens`). A request whose marker was ignored is answered
+ * with `Kaana-Ignored-Parameters: cache_control`. Honouring it needs a priced
+ * cache-write unit (`cache_write_input_tokens`, contract 8.4.0) that nothing
+ * emits yet.
+ *
+ * The same holds for three more members Claude Code sends: `context_management`,
+ * `thinking.display` and `tools[].defer_loading`. Each is a hint or a beta that
+ * changes how a provider trims, shows or loads, never what a request means or
+ * costs; each present one is named in `Kaana-Ignored-Parameters`. Any other
+ * member this file does not name is still refused.
+ *
  * ## Reasoning (contract set 8.6.0, ADR 0009 decision 2)
  *
  * `thinking: {type: 'enabled', budget_tokens}` is the contract's
@@ -67,14 +81,17 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
     max_tokens: z.ZodNumber;
     messages: z.ZodArray<z.ZodObject<{
         role: z.ZodEnum<{
+            system: "system";
             user: "user";
             assistant: "assistant";
         }>;
         content: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
+            cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"image">;
+            cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"base64">;
                 media_type: z.ZodString;
@@ -88,14 +105,17 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
             id: z.ZodString;
             name: z.ZodString;
             input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"tool_result">;
             tool_use_id: z.ZodString;
             content: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
                 type: z.ZodLiteral<"text">;
                 text: z.ZodString;
+                cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, z.core.$strict>, z.ZodObject<{
                 type: z.ZodLiteral<"image">;
+                cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 source: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     type: z.ZodLiteral<"base64">;
                     media_type: z.ZodString;
@@ -106,6 +126,7 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
                 }, z.core.$strict>], "type">;
             }, z.core.$strict>]>>]>>;
             is_error: z.ZodOptional<z.ZodBoolean>;
+            cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"thinking">;
             thinking: z.ZodString;
@@ -118,7 +139,9 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
     system: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodString;
+        cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strict>>]>>;
+    cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     temperature: z.ZodOptional<z.ZodNumber>;
     top_p: z.ZodOptional<z.ZodNumber>;
     top_k: z.ZodOptional<z.ZodNumber>;
@@ -130,6 +153,8 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodOptional<z.ZodBoolean>;
+        cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        defer_loading: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
     tool_choice: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"auto">;
@@ -145,10 +170,13 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
         type: z.ZodLiteral<"disabled">;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"adaptive">;
+        display: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"enabled">;
         budget_tokens: z.ZodNumber;
+        display: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "type">>;
+    context_management: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     output_config: z.ZodOptional<z.ZodObject<{
         effort: z.ZodOptional<z.ZodEnum<{
             low: "low";
@@ -173,10 +201,12 @@ export declare const anthropicMessageSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodString;
+        cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"tool_use">;
         id: z.ZodString;
         name: z.ZodString;
+        cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strict>], "type">>;
     stop_reason: z.ZodEnum<{
@@ -232,10 +262,12 @@ export declare const anthropicStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
+            cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"tool_use">;
             id: z.ZodString;
             name: z.ZodString;
+            cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         }, z.core.$strict>], "type">>;
         stop_reason: z.ZodLiteral<null>;
@@ -260,6 +292,7 @@ export declare const anthropicStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
         type: z.ZodLiteral<"tool_use">;
         id: z.ZodString;
         name: z.ZodString;
+        cache_control: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         input: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>], "type">;
 }, z.core.$strict>, z.ZodObject<{

package/dist/public/anthropicMessages.js

@@ -11,12 +11,6 @@
  *
  * ## What is refused, and why
  *
- *  - **`cache_control`, anywhere** (on a block, a tool, `system` or the
- *    request). Kaana's usage units have no unit for a cache WRITE (see the
- *    Anthropic adapter's usage meter): a cache write is billed at a premium
- *    over input, so honouring the marker while folding the write into
- *    `input_tokens` would report less than the request cost. The marker is
- *    refused, by name and path, instead of being dropped.
  *  - **`thinking.display`** and every other `thinking` member this file does
  *    not name.
  *  - **Server tools** (`web_search`, `bash`, `text_editor`, …), `mcp_servers`,
@@ -25,6 +19,26 @@
  *  - **An image `url` source**: nothing fetches an image URL (ADR 0007); a
  *    `base64` source is carried inline under the image rules.
  *
+ * ## `cache_control`: accepted and IGNORED
+ *
+ * Claude Code puts a `cache_control` marker on every request, so refusing it
+ * made the endpoint unusable by its main client. The marker is accepted wherever
+ * the dialect puts it (the request, `system`, a tool, a content block) and is
+ * NOT honoured: Kaana forwards no cache hint, so no cache write happens and the
+ * usage it reports stays exactly what the request cost. The only effect is the
+ * one the caller asked for and does not get: no prompt-cache discount on a write
+ * (reads that a provider caches on its own are still metered as
+ * `cache_read_input_tokens`). A request whose marker was ignored is answered
+ * with `Kaana-Ignored-Parameters: cache_control`. Honouring it needs a priced
+ * cache-write unit (`cache_write_input_tokens`, contract 8.4.0) that nothing
+ * emits yet.
+ *
+ * The same holds for three more members Claude Code sends: `context_management`,
+ * `thinking.display` and `tools[].defer_loading`. Each is a hint or a beta that
+ * changes how a provider trims, shows or loads, never what a request means or
+ * costs; each present one is named in `Kaana-Ignored-Parameters`. Any other
+ * member this file does not name is still refused.
+ *
  * ## Reasoning (contract set 8.6.0, ADR 0009 decision 2)
  *
  * `thinking: {type: 'enabled', budget_tokens}` is the contract's
@@ -58,10 +72,21 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { reasoningEffortSchema } from './catalogue.js';
 import { modelTargetSchema } from './responses.js';
 const nonEmpty = (max) => z.string().check(minUtf16Length(1)).check(maxUtf16Length(max));
-const textBlockSchema = z.object({ type: z.literal('text'), text: z.string() }).strict();
+/** Accepted and ignored, whatever members it carries (`type`, `ttl`, `scope`): see "`cache_control`" in the file comment. */
+const cacheControlSchema = z.record(z.string(), z.unknown());
+/** Accepted and ignored: how much reasoning text a client wants shown. */
+const thinkingDisplaySchema = z.string();
+const textBlockSchema = z
+    .object({
+    type: z.literal('text'),
+    text: z.string(),
+    cache_control: cacheControlSchema.optional(),
+})
+    .strict();
 const imageBlockSchema = z
     .object({
     type: z.literal('image'),
+    cache_control: cacheControlSchema.optional(),
     source: z.discriminatedUnion('type', [
         z
             .object({
@@ -96,6 +121,7 @@ const toolUseBlockSchema = z
     id: nonEmpty(128),
     name: nonEmpty(128),
     input: z.record(z.string(), z.unknown()),
+    cache_control: cacheControlSchema.optional(),
 })
     .strict();
 const toolResultBlockSchema = z
@@ -110,11 +136,13 @@ const toolResultBlockSchema = z
      * own content is what the model reads; the flag is not forwarded.
      */
     is_error: z.boolean().optional(),
+    cache_control: cacheControlSchema.optional(),
 })
     .strict();
 const messageSchema = z
     .object({
-    role: z.enum(['user', 'assistant']),
+    /** `system` is a mid-conversation instruction Claude Code sends: text blocks only. */
+    role: z.enum(['user', 'assistant', 'system']),
     content: z.union([
         z.string(),
         z
@@ -137,7 +165,9 @@ const messageSchema = z
         const reasoning = block.type === 'thinking' || block.type === 'redacted_thinking';
         const allowed = message.role === 'assistant'
             ? block.type === 'text' || block.type === 'tool_use' || reasoning
-            : block.type !== 'tool_use' && !reasoning;
+            : message.role === 'system'
+                ? block.type === 'text'
+                : block.type !== 'tool_use' && !reasoning;
         if (!allowed) {
             ctx.addIssue({
                 code: 'custom',
@@ -154,6 +184,9 @@ const toolSchema = z
     description: z.string().check(maxUtf16Length(32768)).optional(),
     input_schema: z.record(z.string(), z.unknown()),
     strict: z.boolean().optional(),
+    cache_control: cacheControlSchema.optional(),
+    /** Accepted and ignored: Kaana loads every tool it is sent. */
+    defer_loading: z.boolean().optional(),
 })
     .strict();
 const toolChoiceSchema = z.discriminatedUnion('type', [
@@ -170,6 +203,7 @@ export const anthropicMessagesRequestSchema = z
     max_tokens: z.number().int().positive().safe(),
     messages: z.array(messageSchema).min(1),
     system: z.union([z.string(), z.array(textBlockSchema)]).optional(),
+    cache_control: cacheControlSchema.optional(),
     temperature: z.number().min(0).max(1).optional(),
     top_p: z.number().min(0).max(1).optional(),
     top_k: z.number().int().positive().safe().optional(),
@@ -185,15 +219,20 @@ export const anthropicMessagesRequestSchema = z
     thinking: z
         .discriminatedUnion('type', [
         z.object({ type: z.literal('disabled') }).strict(),
-        z.object({ type: z.literal('adaptive') }).strict(),
+        z
+            .object({ type: z.literal('adaptive'), display: thinkingDisplaySchema.optional() })
+            .strict(),
         z
             .object({
             type: z.literal('enabled'),
             budget_tokens: z.number().int().positive().safe(),
+            display: thinkingDisplaySchema.optional(),
         })
             .strict(),
     ])
         .optional(),
+    /** Accepted and ignored (an Anthropic beta Claude Code sends). */
+    context_management: z.record(z.string(), z.unknown()).optional(),
     /** `effort` is the contract's reasoning effort; no other member is carried. */
     output_config: z.object({ effort: reasoningEffortSchema.optional() }).strict().optional(),
     /** Accepted and not forwarded or stored. */

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.6.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.6.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.6.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": [
@@ -1312,6 +1312,13 @@
                     },
                     "text": {
                       "type": "string"
+                    },
+                    "cache_control": {
+                      "type": "object",
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "additionalProperties": {}
                     }
                   },
                   "required": [
@@ -1343,6 +1350,13 @@
                         "type": "string"
                       },
                       "additionalProperties": {}
+                    },
+                    "cache_control": {
+                      "type": "object",
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "additionalProperties": {}
                     }
                   },
                   "required": [
@@ -1428,7 +1442,8 @@
                   "type": "string",
                   "enum": [
                     "user",
-                    "assistant"
+                    "assistant",
+                    "system"
                   ]
                 },
                 "content": {
@@ -1450,6 +1465,13 @@
                               },
                               "text": {
                                 "type": "string"
+                              },
+                              "cache_control": {
+                                "type": "object",
+                                "propertyNames": {
+                                  "type": "string"
+                                },
+                                "additionalProperties": {}
                               }
                             },
                             "required": [
@@ -1465,6 +1487,13 @@
                                 "type": "string",
                                 "const": "image"
                               },
+                              "cache_control": {
+                                "type": "object",
+                                "propertyNames": {
+                                  "type": "string"
+                                },
+                                "additionalProperties": {}
+                              },
                               "source": {
                                 "oneOf": [
                                   {
@@ -1542,6 +1571,13 @@
                                   "type": "string"
                                 },
                                 "additionalProperties": {}
+                              },
+                              "cache_control": {
+                                "type": "object",
+                                "propertyNames": {
+                                  "type": "string"
+                                },
+                                "additionalProperties": {}
                               }
                             },
                             "required": [
@@ -1582,6 +1618,13 @@
                                             },
                                             "text": {
                                               "type": "string"
+                                            },
+                                            "cache_control": {
+                                              "type": "object",
+                                              "propertyNames": {
+                                                "type": "string"
+                                              },
+                                              "additionalProperties": {}
                                             }
                                           },
                                           "required": [
@@ -1597,6 +1640,13 @@
                                               "type": "string",
                                               "const": "image"
                                             },
+                                            "cache_control": {
+                                              "type": "object",
+                                              "propertyNames": {
+                                                "type": "string"
+                                              },
+                                              "additionalProperties": {}
+                                            },
                                             "source": {
                                               "oneOf": [
                                                 {
@@ -1658,6 +1708,13 @@
                               },
                               "is_error": {
                                 "type": "boolean"
+                              },
+                              "cache_control": {
+                                "type": "object",
+                                "propertyNames": {
+                                  "type": "string"
+                                },
+                                "additionalProperties": {}
                               }
                             },
                             "required": [
@@ -1735,6 +1792,13 @@
                     },
                     "text": {
                       "type": "string"
+                    },
+                    "cache_control": {
+                      "type": "object",
+                      "propertyNames": {
+                        "type": "string"
+                      },
+                      "additionalProperties": {}
                     }
                   },
                   "required": [
@@ -1746,6 +1810,13 @@
               }
             ]
           },
+          "cache_control": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          },
           "temperature": {
             "type": "number",
             "minimum": 0,
@@ -1801,6 +1872,16 @@
                 },
                 "strict": {
                   "type": "boolean"
+                },
+                "cache_control": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {}
+                },
+                "defer_loading": {
+                  "type": "boolean"
                 }
               },
               "required": [
@@ -1893,6 +1974,9 @@
                   "type": {
                     "type": "string",
                     "const": "adaptive"
+                  },
+                  "display": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -1911,6 +1995,9 @@
                     "type": "integer",
                     "exclusiveMinimum": 0,
                     "maximum": 9007199254740991
+                  },
+                  "display": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -1921,6 +2008,13 @@
               }
             ]
           },
+          "context_management": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          },
           "output_config": {
             "type": "object",
             "properties": {
@@ -2021,6 +2115,13 @@
                             },
                             "text": {
                               "type": "string"
+                            },
+                            "cache_control": {
+                              "type": "object",
+                              "propertyNames": {
+                                "type": "string"
+                              },
+                              "additionalProperties": {}
                             }
                           },
                           "required": [
@@ -2052,6 +2153,13 @@
                                 "type": "string"
                               },
                               "additionalProperties": {}
+                            },
+                            "cache_control": {
+                              "type": "object",
+                              "propertyNames": {
+                                "type": "string"
+                              },
+                              "additionalProperties": {}
                             }
                           },
                           "required": [
@@ -2194,6 +2302,13 @@
                         "type": "object",
                         "properties": {},
                         "additionalProperties": false
+                      },
+                      "cache_control": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {}
                       }
                     },
                     "required": [
@@ -3964,6 +4079,9 @@
               },
               "text": {
                 "type": "string"
+              },
+              "cacheBreakpoint": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -3989,6 +4107,9 @@
                   "low",
                   "high"
                 ]
+              },
+              "cacheBreakpoint": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -4027,6 +4148,9 @@
               "filename": {
                 "type": "string",
                 "maxLength": 255
+              },
+              "cacheBreakpoint": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -8193,6 +8317,9 @@
           },
           "strict": {
             "type": "boolean"
+          },
+          "cacheBreakpoint": {
+            "type": "boolean"
           }
         },
         "required": [

package/package.json

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