@kaana.ai/contracts 8.8.0 → 8.9.0

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
@@ -137,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<{
@@ -294,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.8.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.8.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.8.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.8.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.8.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": [
@@ -8026,7 +8026,7 @@
             "$ref": "#/components/schemas/ToolChoice"
           },
           "responseFormat": {
-            "$ref": "#/components/schemas/ResponseFormat"
+            "$ref": "#/components/schemas/ResponsesResponseFormat"
           },
           "reasoning": {
             "$ref": "#/components/schemas/InferenceReasoning"
@@ -8051,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": {

package/package.json

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