@kaana.ai/contracts 8.7.0 → 8.9.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

@@ -23,6 +23,33 @@ export declare const modelTargetSchema: z.ZodUnion<readonly [z.ZodString, z.ZodE
     pro: "pro";
     ultra: "ultra";
 }>]>;
+/**
+ * The response format of `POST /v1/responses`: the signed request's format
+ * (`responseFormatSchema`) and, on the two JSON formats, `repair` (contract set
+ * 8.9.0, Kaana ADR 0009 decision 5).
+ *
+ * `repair: true` asks Kaana to repair nearly valid JSON in the final text of a
+ * non-streaming answer that ended with `stop`: a surrounding code fence, prose
+ * around the value, trailing commas, closers a normal stop forgot. It never
+ * changes text that already parses, never repairs an answer cut by the token
+ * limit (`length`) or ended by a filter, a refusal or a tool call, and checks
+ * nothing against `schema` (Kaana carries no validator). A repaired answer is
+ * marked by the response header `Kaana-Repaired: true`, never by a body
+ * member. It is refused on `text` and with `stream: true`, and it is not part of
+ * the signed request: no provider and no Oxy sees it. Default off.
+ */
+export declare const responsesResponseFormatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"json_object">;
+    repair: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"json_schema">;
+    name: z.ZodString;
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    strict: z.ZodBoolean;
+    repair: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "type">;
 /**
  * The request. `model` may be absent: the application's routing policy in Oxy
  * Console may name a default target, and the request is refused only when it
@@ -53,6 +80,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 +96,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 +118,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 +150,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";
@@ -133,11 +164,13 @@ export declare const responsesRequestSchema: z.ZodObject<{
         type: z.ZodLiteral<"text">;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"json_object">;
+        repair: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"json_schema">;
         name: z.ZodString;
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodBoolean;
+        repair: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>], "type">>;
     reasoning: z.ZodOptional<z.ZodObject<{
         effort: z.ZodOptional<z.ZodEnum<{
@@ -207,6 +240,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 +256,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 +278,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;
@@ -287,6 +323,7 @@ export declare const responseSchema: z.ZodObject<{
     }, z.core.$strict>;
     latencyMs: z.ZodNumber;
 }, z.core.$strict>;
+export type ResponsesResponseFormat = z.infer<typeof responsesResponseFormatSchema>;
 export type ModelTarget = z.infer<typeof modelTargetSchema>;
 export type ResponsesRequest = z.infer<typeof responsesRequestSchema>;
 export type Response = z.infer<typeof responseSchema>;

package/dist/public/responses.js

@@ -11,7 +11,7 @@ import { z } from 'zod';
 import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { powerLevelSchema } from './catalogue.js';
 import { generationIdSchema, modelReferenceSchema, requestIdSchema } from './identifiers.js';
-import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, responseFormatSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
+import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
 import { usageQuantitySchema } from './money.js';
 import { routingPolicyReferenceSchema } from './policy.js';
 import { promptCacheKeySchema, providerPreferencesSchema } from './providerPreferences.js';
@@ -23,6 +23,34 @@ import { inferenceFinishReasonSchema } from './streamEvents.js';
  * the string alone).
  */
 export const modelTargetSchema = z.union([modelReferenceSchema, powerLevelSchema]);
+/**
+ * The response format of `POST /v1/responses`: the signed request's format
+ * (`responseFormatSchema`) and, on the two JSON formats, `repair` (contract set
+ * 8.9.0, Kaana ADR 0009 decision 5).
+ *
+ * `repair: true` asks Kaana to repair nearly valid JSON in the final text of a
+ * non-streaming answer that ended with `stop`: a surrounding code fence, prose
+ * around the value, trailing commas, closers a normal stop forgot. It never
+ * changes text that already parses, never repairs an answer cut by the token
+ * limit (`length`) or ended by a filter, a refusal or a tool call, and checks
+ * nothing against `schema` (Kaana carries no validator). A repaired answer is
+ * marked by the response header `Kaana-Repaired: true`, never by a body
+ * member. It is refused on `text` and with `stream: true`, and it is not part of
+ * the signed request: no provider and no Oxy sees it. Default off.
+ */
+export const responsesResponseFormatSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('text') }).strict(),
+    z.object({ type: z.literal('json_object'), repair: z.boolean().optional() }).strict(),
+    z
+        .object({
+        type: z.literal('json_schema'),
+        name: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
+        schema: z.record(z.string(), z.unknown()),
+        strict: z.boolean(),
+        repair: z.boolean().optional(),
+    })
+        .strict(),
+]);
 /** The message-or-text input `/v1/responses` accepts. */
 const responsesInputSchema = z.union([
     z.string().check(minUtf16Length(1)),
@@ -55,7 +83,7 @@ export const responsesRequestSchema = z
         .optional(),
     tools: z.array(toolDefinitionSchema).max(128).optional(),
     toolChoice: toolChoiceSchema.optional(),
-    responseFormat: responseFormatSchema.optional(),
+    responseFormat: responsesResponseFormatSchema.optional(),
     /** Refused when the resolved model does not advertise the effort. */
     reasoning: inferenceReasoningSchema.optional(),
     labels: requestLabelsSchema.optional(),
@@ -68,6 +96,16 @@ export const responsesRequestSchema = z
 })
     .strict()
     .superRefine((request, ctx) => {
+    if (request.responseFormat !== undefined &&
+        'repair' in request.responseFormat &&
+        request.responseFormat.repair === true &&
+        request.stream === true) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['responseFormat', 'repair'],
+            message: 'repair works on a whole answer and cannot be used with stream: true',
+        });
+    }
     if (request.toolChoice !== undefined && (request.tools ?? []).length === 0) {
         ctx.addIssue({
             code: 'custom',

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.9.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:
@@ -223,6 +223,13 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.7.0";
  * is emitted only to a request that carried `reasoning`. A consumer on 8.5.0 or
  * earlier (Oxy's legacy signed lane) refuses a message or request that carries
  * what is new, so Oxy reads it before a customer sends it.
+ *
+ * Contract set 8.9.0 is additive: the optional `repair` member of
+ * `POST /v1/responses`'s `responseFormat` (`responsesResponseFormatSchema`, Kaana
+ * ADR 0009 decision 5) and the response header `Kaana-Repaired`. It is a public
+ * request member only: the signed grant and envelope are unchanged, and a
+ * response carries no new body member, so every older reader parses what 8.9.0
+ * serves.
  */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";
@@ -254,6 +261,12 @@ export declare const KAANA_USAGE_HEADER = "Kaana-Usage";
  */
 export declare const KAANA_ROUTING_POLICY_ID_HEADER = "Kaana-Routing-Policy-Id";
 export declare const KAANA_ROUTING_POLICY_VERSION_HEADER = "Kaana-Routing-Policy-Version";
+/**
+ * The response header Kaana sets to `true` when it changed the model's JSON
+ * text because the request asked for `responseFormat.repair` (contract set
+ * 8.9.0). Absent otherwise.
+ */
+export declare const KAANA_REPAIRED_HEADER = "Kaana-Repaired";
 /** The request header that names the end user a service token acts for. */
 export declare const KAANA_ON_BEHALF_OF_HEADER = "X-Oxy-User-Id";
 /** The request header that makes a request idempotent. */

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.9.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:
@@ -223,6 +223,13 @@ export const INFERENCE_CONTRACT_VERSION = '8.7.0';
  * is emitted only to a request that carried `reasoning`. A consumer on 8.5.0 or
  * earlier (Oxy's legacy signed lane) refuses a message or request that carries
  * what is new, so Oxy reads it before a customer sends it.
+ *
+ * Contract set 8.9.0 is additive: the optional `repair` member of
+ * `POST /v1/responses`'s `responseFormat` (`responsesResponseFormatSchema`, Kaana
+ * ADR 0009 decision 5) and the response header `Kaana-Repaired`. It is a public
+ * request member only: the signed grant and envelope are unchanged, and a
+ * response carries no new body member, so every older reader parses what 8.9.0
+ * serves.
  */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';
@@ -254,6 +261,12 @@ export const KAANA_USAGE_HEADER = 'Kaana-Usage';
  */
 export const KAANA_ROUTING_POLICY_ID_HEADER = 'Kaana-Routing-Policy-Id';
 export const KAANA_ROUTING_POLICY_VERSION_HEADER = 'Kaana-Routing-Policy-Version';
+/**
+ * The response header Kaana sets to `true` when it changed the model's JSON
+ * text because the request asked for `responseFormat.repair` (contract set
+ * 8.9.0). Absent otherwise.
+ */
+export const KAANA_REPAIRED_HEADER = 'Kaana-Repaired';
 /** The request header that names the end user a service token acts for. */
 export const KAANA_ON_BEHALF_OF_HEADER = 'X-Oxy-User-Id';
 /** The request header that makes a request idempotent. */

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.7.0",
+    "version": "8.9.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": [
@@ -8017,7 +8026,7 @@
             "$ref": "#/components/schemas/ToolChoice"
           },
           "responseFormat": {
-            "$ref": "#/components/schemas/ResponseFormat"
+            "$ref": "#/components/schemas/ResponsesResponseFormat"
           },
           "reasoning": {
             "$ref": "#/components/schemas/InferenceReasoning"
@@ -8042,6 +8051,73 @@
         ],
         "additionalProperties": false
       },
+      "ResponsesResponseFormat": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "text"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "json_object"
+              },
+              "repair": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "json_schema"
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "schema": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
+              },
+              "strict": {
+                "type": "boolean"
+              },
+              "repair": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "type",
+              "name",
+              "schema",
+              "strict"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      },
       "RoutingPolicyReference": {
         "type": "object",
         "properties": {
@@ -8308,6 +8384,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.9.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,