@kaana.ai/contracts 8.5.0 → 8.6.0

package/dist/internal/request.d.ts

@@ -95,6 +95,10 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"reasoning">;
+            text: z.ZodOptional<z.ZodString>;
+            opaque: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], "type">>;
         name: z.ZodOptional<z.ZodString>;
         toolCallId: z.ZodOptional<z.ZodString>;
@@ -279,6 +283,10 @@ export declare const inferenceRequestSchema: z.ZodObject<{
             }, z.core.$strict>, z.ZodObject<{
                 type: z.ZodLiteral<"refusal">;
                 text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                type: z.ZodLiteral<"reasoning">;
+                text: z.ZodOptional<z.ZodString>;
+                opaque: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>], "type">>;
             name: z.ZodOptional<z.ZodString>;
             toolCallId: z.ZodOptional<z.ZodString>;
@@ -307,11 +315,13 @@ export declare const inferenceRequestSchema: z.ZodObject<{
         stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
     reasoning: z.ZodOptional<z.ZodObject<{
-        effort: z.ZodEnum<{
+        effort: z.ZodOptional<z.ZodEnum<{
             low: "low";
             medium: "medium";
             high: "high";
-        }>;
+        }>>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        exclude: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     speech: z.ZodOptional<z.ZodObject<{
         voice: z.ZodString;

package/dist/internal/streamEvents.d.ts

@@ -253,6 +253,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
         output_audio_transcript: "output_audio_transcript";
     }>;
     text: z.ZodString;
+    opaque: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     type: z.ZodLiteral<"audio">;

package/dist/public/anthropicMessages.d.ts

@@ -17,18 +17,30 @@
  *    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` other than `{ type: 'disabled' }`.** The contract's reasoning
- *    control is an effort (`low`, `medium`, `high`), not a token budget, and a
- *    thinking block has no part in a message: reasoning is private and is never
- *    returned. Reasoning effort is asked with `output_config.effort`, which
- *    maps one to one. A `thinking` or `redacted_thinking` block in a message is
- *    refused for the same reason.
+ *  - **`thinking.display`** and every other `thinking` member this file does
+ *    not name.
  *  - **Server tools** (`web_search`, `bash`, `text_editor`, …), `mcp_servers`,
  *    `container`, `service_tier`, `disable_parallel_tool_use`, `document`
  *    blocks and any other member this file does not name.
  *  - **An image `url` source**: nothing fetches an image URL (ADR 0007); a
  *    `base64` source is carried inline under the image rules.
  *
+ * ## Reasoning (contract set 8.6.0, ADR 0009 decision 2)
+ *
+ * `thinking: {type: 'enabled', budget_tokens}` is the contract's
+ * `reasoning.maxTokens` and `thinking: {type: 'adaptive'}` opts in to reasoning
+ * with the route's own sizing; `output_config.effort` is `reasoning.effort`, and
+ * a budget beside an effort is refused (the contract treats them as
+ * alternatives). A route that cannot take a budget refuses it by name.
+ *
+ * An answer carries `thinking` blocks before its text and tool calls, and an
+ * assistant message sent back carries them again, UNMODIFIED, ahead of its
+ * `tool_use` blocks. The block's `signature` is the contract's opaque
+ * continuation token (the sealed string a `reasoning` part carries), which is
+ * why a stock Anthropic SDK continues a tool turn without knowing anything
+ * else: it returns what it received. `redacted_thinking` is accepted on the way
+ * in (its `data` is the same token) and never produced.
+ *
  * `stop_reason: 'stop_sequence'` is never produced: the finish reason Kaana
  * measures does not say WHICH stop sequence ended the turn, and `stop_sequence`
  * would then have to name one. A turn that ended on a stop sequence reports
@@ -94,6 +106,13 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
                 }, z.core.$strict>], "type">;
             }, z.core.$strict>]>>]>>;
             is_error: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"thinking">;
+            thinking: z.ZodString;
+            signature: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"redacted_thinking">;
+            data: z.ZodString;
         }, z.core.$strict>]>>]>;
     }, z.core.$strict>>;
     system: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodObject<{
@@ -122,9 +141,14 @@ export declare const anthropicMessagesRequestSchema: z.ZodObject<{
         type: z.ZodLiteral<"tool">;
         name: z.ZodString;
     }, z.core.$strict>], "type">>;
-    thinking: z.ZodOptional<z.ZodObject<{
+    thinking: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"disabled">;
-    }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"adaptive">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"enabled">;
+        budget_tokens: z.ZodNumber;
+    }, z.core.$strict>], "type">>;
     output_config: z.ZodOptional<z.ZodObject<{
         effort: z.ZodOptional<z.ZodEnum<{
             low: "low";
@@ -143,6 +167,10 @@ export declare const anthropicMessageSchema: z.ZodObject<{
     role: z.ZodLiteral<"assistant">;
     model: z.ZodString;
     content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"thinking">;
+        thinking: z.ZodString;
+        signature: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
@@ -198,6 +226,10 @@ export declare const anthropicStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
         role: z.ZodLiteral<"assistant">;
         model: z.ZodString;
         content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"thinking">;
+            thinking: z.ZodString;
+            signature: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
@@ -218,6 +250,10 @@ export declare const anthropicStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
     type: z.ZodLiteral<"content_block_start">;
     index: z.ZodNumber;
     content_block: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"thinking">;
+        thinking: z.ZodLiteral<"">;
+        signature: z.ZodLiteral<"">;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodLiteral<"">;
     }, z.core.$strict>, z.ZodObject<{
@@ -232,6 +268,12 @@ export declare const anthropicStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
     delta: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"text_delta">;
         text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"thinking_delta">;
+        thinking: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"signature_delta">;
+        signature: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"input_json_delta">;
         partial_json: z.ZodString;

package/dist/public/anthropicMessages.js

@@ -17,18 +17,30 @@
  *    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` other than `{ type: 'disabled' }`.** The contract's reasoning
- *    control is an effort (`low`, `medium`, `high`), not a token budget, and a
- *    thinking block has no part in a message: reasoning is private and is never
- *    returned. Reasoning effort is asked with `output_config.effort`, which
- *    maps one to one. A `thinking` or `redacted_thinking` block in a message is
- *    refused for the same reason.
+ *  - **`thinking.display`** and every other `thinking` member this file does
+ *    not name.
  *  - **Server tools** (`web_search`, `bash`, `text_editor`, …), `mcp_servers`,
  *    `container`, `service_tier`, `disable_parallel_tool_use`, `document`
  *    blocks and any other member this file does not name.
  *  - **An image `url` source**: nothing fetches an image URL (ADR 0007); a
  *    `base64` source is carried inline under the image rules.
  *
+ * ## Reasoning (contract set 8.6.0, ADR 0009 decision 2)
+ *
+ * `thinking: {type: 'enabled', budget_tokens}` is the contract's
+ * `reasoning.maxTokens` and `thinking: {type: 'adaptive'}` opts in to reasoning
+ * with the route's own sizing; `output_config.effort` is `reasoning.effort`, and
+ * a budget beside an effort is refused (the contract treats them as
+ * alternatives). A route that cannot take a budget refuses it by name.
+ *
+ * An answer carries `thinking` blocks before its text and tool calls, and an
+ * assistant message sent back carries them again, UNMODIFIED, ahead of its
+ * `tool_use` blocks. The block's `signature` is the contract's opaque
+ * continuation token (the sealed string a `reasoning` part carries), which is
+ * why a stock Anthropic SDK continues a tool turn without knowing anything
+ * else: it returns what it received. `redacted_thinking` is accepted on the way
+ * in (its `data` is the same token) and never produced.
+ *
  * `stop_reason: 'stop_sequence'` is never produced: the finish reason Kaana
  * measures does not say WHICH stop sequence ended the turn, and `stop_sequence`
  * would then have to name one. A turn that ended on a stop sequence reports
@@ -63,6 +75,21 @@ const imageBlockSchema = z
     ]),
 })
     .strict();
+/**
+ * An assistant's reasoning. `thinking` is the readable text (empty when the
+ * model returned none); `signature` is the continuation token to return
+ * unmodified, empty only for a block that cannot be continued.
+ */
+const thinkingBlockSchema = z
+    .object({
+    type: z.literal('thinking'),
+    thinking: z.string(),
+    signature: z.string(),
+})
+    .strict();
+const redactedThinkingBlockSchema = z
+    .object({ type: z.literal('redacted_thinking'), data: nonEmpty(1_000_000) })
+    .strict();
 const toolUseBlockSchema = z
     .object({
     type: z.literal('tool_use'),
@@ -91,7 +118,14 @@ const messageSchema = z
     content: z.union([
         z.string(),
         z
-            .array(z.union([textBlockSchema, imageBlockSchema, toolUseBlockSchema, toolResultBlockSchema]))
+            .array(z.union([
+            textBlockSchema,
+            imageBlockSchema,
+            toolUseBlockSchema,
+            toolResultBlockSchema,
+            thinkingBlockSchema,
+            redactedThinkingBlockSchema,
+        ]))
             .min(1),
     ]),
 })
@@ -100,9 +134,10 @@ const messageSchema = z
     if (typeof message.content === 'string')
         return;
     for (const [index, block] of message.content.entries()) {
+        const reasoning = block.type === 'thinking' || block.type === 'redacted_thinking';
         const allowed = message.role === 'assistant'
-            ? block.type === 'text' || block.type === 'tool_use'
-            : block.type !== 'tool_use';
+            ? block.type === 'text' || block.type === 'tool_use' || reasoning
+            : block.type !== 'tool_use' && !reasoning;
         if (!allowed) {
             ctx.addIssue({
                 code: 'custom',
@@ -142,10 +177,22 @@ export const anthropicMessagesRequestSchema = z
     stream: z.boolean().optional(),
     tools: z.array(toolSchema).max(128).optional(),
     tool_choice: toolChoiceSchema.optional(),
-    /** Only "off" is accepted: see the file comment. */
+    /**
+     * `disabled` asks for nothing; `adaptive` opts in to reasoning (the
+     * contract's `reasoning: {}`); `enabled` sets a token budget
+     * (`reasoning.maxTokens`). See the file comment.
+     */
     thinking: z
-        .object({ type: z.literal('disabled') })
-        .strict()
+        .discriminatedUnion('type', [
+        z.object({ type: z.literal('disabled') }).strict(),
+        z.object({ type: z.literal('adaptive') }).strict(),
+        z
+            .object({
+            type: z.literal('enabled'),
+            budget_tokens: z.number().int().positive().safe(),
+        })
+            .strict(),
+    ])
         .optional(),
     /** `effort` is the contract's reasoning effort; no other member is carried. */
     output_config: z.object({ effort: reasoningEffortSchema.optional() }).strict().optional(),
@@ -175,6 +222,7 @@ const usageSchema = z
     .strict();
 const stopReasonSchema = z.enum(['end_turn', 'max_tokens', 'tool_use', 'refusal']);
 const outputBlockSchema = z.discriminatedUnion('type', [
+    thinkingBlockSchema,
     textBlockSchema,
     toolUseBlockSchema.extend({ input: z.record(z.string(), z.unknown()) }),
 ]);
@@ -243,6 +291,13 @@ export const anthropicStreamEventSchema = z.discriminatedUnion('type', [
         type: z.literal('content_block_start'),
         index: z.number().int().nonnegative(),
         content_block: z.discriminatedUnion('type', [
+            z
+                .object({
+                type: z.literal('thinking'),
+                thinking: z.literal(''),
+                signature: z.literal(''),
+            })
+                .strict(),
             z.object({ type: z.literal('text'), text: z.literal('') }).strict(),
             toolUseBlockSchema.extend({ input: z.object({}).strict() }),
         ]),
@@ -254,6 +309,8 @@ export const anthropicStreamEventSchema = z.discriminatedUnion('type', [
         index: z.number().int().nonnegative(),
         delta: z.discriminatedUnion('type', [
             z.object({ type: z.literal('text_delta'), text: z.string() }).strict(),
+            z.object({ type: z.literal('thinking_delta'), thinking: z.string() }).strict(),
+            z.object({ type: z.literal('signature_delta'), signature: z.string() }).strict(),
             z.object({ type: z.literal('input_json_delta'), partial_json: z.string() }).strict(),
         ]),
     })

package/dist/public/chatCompletions.d.ts

@@ -70,6 +70,10 @@ export declare const chatCompletionMessageSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"refusal">;
         text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"reasoning">;
+        text: z.ZodOptional<z.ZodString>;
+        opaque: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "type">>]>>>;
     name: z.ZodOptional<z.ZodString>;
     tool_call_id: z.ZodOptional<z.ZodString>;
@@ -142,6 +146,10 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"reasoning">;
+            text: z.ZodOptional<z.ZodString>;
+            opaque: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], "type">>]>>>;
         name: z.ZodOptional<z.ZodString>;
         tool_call_id: z.ZodOptional<z.ZodString>;

package/dist/public/messages.d.ts

@@ -23,34 +23,44 @@ export declare const inferenceContentSourceSchema: z.ZodDiscriminatedUnion<[z.Zo
 /**
  * One part of a message's content. A message is always a list of parts.
  *
- * ## `refusal` is a member and `reasoning` is not, and the asymmetry is the point
+ * ## `refusal` and `reasoning` are members, and neither is ever answer text
  *
  * A model that DECLINES says why, and those words are meant for the customer:
  * they are the difference between "rephrase this" and "stop asking". Before this
  * member existed there was nowhere in an {@link InferenceMessage} to put them, so
- * a non-streaming fold kept `finishReason: 'refusal'` and dropped the sentence —
- * the customer learned they were refused and not why, while a streaming caller of
- * the same request got the whole explanation on the `refusal` delta channel.
+ * a non-streaming fold kept `finishReason: 'refusal'` and dropped the sentence.
+ * The part is a MEMBER rather than a field because a refusal need not have text:
+ * an Anthropic `stop_reason: "refusal"` maps to the finish reason and separates
+ * no words from the answer, while an OpenAI-compatible `refusal` does.
  *
- * Reasoning is the opposite case and stays absent. It is the model's private
- * working, and a `text` part is where somebody would put it — which renders
- * private reasoning to the customer AS the answer, the product bug the delta
- * channels exist to prevent. An opaque per-block reasoning blob crossing this
- * boundary needs a home nobody has chosen yet, and inventing one here would
- * choose it by accident.
+ * ## `reasoning` (contract set 8.6.0, Kaana ADR 0009 decision 2)
  *
- * Both public dialects can carry a refusal, which is what separates the two
- * cases at the boundary as well as in principle: `refusal` is OpenAI's OWN field
- * in both of its shapes (`delta.refusal` streaming, `message.refusal`
- * non-streaming), while reasoning has no OpenAI field at all — the
- * `reasoning_content`/`reasoning` spellings an OpenAI-compatible provider emits
- * are provider extensions. So carrying the refusal costs no dialect its
- * standard-client parseability, and carrying reasoning would.
+ * Reasoning was deliberately absent until the owner chose its home, because an
+ * opaque per-block reasoning blob had none. The cost of that absence was
+ * correctness: a thinking model that calls a tool cannot be continued unless the
+ * assistant's reasoning blocks, with their signatures, come back to the provider
+ * unmodified and in order, and a customer who only ever received reasoning TEXT
+ * on the `reasoning` delta channel had nothing to send back.
  *
- * The part is a MEMBER rather than a field because a refusal need not have text:
- * an Anthropic `stop_reason: "refusal"` maps to the finish reason and separates
- * no words from the answer, while an OpenAI-compatible `refusal` does. A required
- * field would force the first provider to invent a sentence.
+ * The part is `{type: 'reasoning', text?, opaque?}`:
+ *
+ * - `text` is what a person may read. It is a display value and is never
+ *   forwarded to a provider on its own.
+ * - `opaque` is a continuation token the customer MUST return UNMODIFIED, in the
+ *   position it arrived. Its content is Kaana's to define and the customer's to
+ *   treat as a sealed string: it is provider-neutral on the surface and carries
+ *   whatever the serving provider needs to continue. Sealing is NOT
+ *   cryptographic: a forged or edited token is no more than a request the
+ *   provider refuses, so nothing may rely on it for trust.
+ * - at least one of the two is present.
+ *
+ * A reasoning part is the assistant's alone, exactly as a refusal is. It is
+ * never a `text` part, so no renderer can present private reasoning as the
+ * answer, and the delta channels keep reasoning apart for the same reason.
+ *
+ * What a route does with a token it cannot read (it was issued by another
+ * provider family, after a failover or a model switch) is drop it, never fail:
+ * the continuation is lost, the conversation is not.
  */
 export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;
@@ -94,6 +104,10 @@ export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodO
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"refusal">;
     text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"reasoning">;
+    text: z.ZodOptional<z.ZodString>;
+    opaque: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "type">;
 /**
  * The image formats a request may carry. Every provider that serves image input
@@ -227,6 +241,10 @@ export declare const inferenceMessageSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"refusal">;
         text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"reasoning">;
+        text: z.ZodOptional<z.ZodString>;
+        opaque: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "type">>;
     name: z.ZodOptional<z.ZodString>;
     toolCallId: z.ZodOptional<z.ZodString>;
@@ -280,17 +298,30 @@ export declare const responseFormatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
 }, z.core.$strict>], "type">;
 /**
  * The caller's reasoning control. Strict, like every leaf: a provider-specific
- * knob (`budget_tokens`, `summary`) is refused rather than silently dropped.
+ * knob (`summary`) is refused rather than silently dropped.
  *
- * Oxy forwards it only after checking the resolved model advertises the effort
- * in its catalogue `reasoningEfforts`; Kaana translates it per provider.
+ * - `effort` is how much to reason, in the catalogue's words. Oxy forwards it
+ *   only after checking the resolved model advertises it in `reasoningEfforts`.
+ * - `maxTokens` is a thinking BUDGET in tokens. It is the other way to size
+ *   reasoning, so it excludes `effort`. A route that cannot take a budget
+ *   refuses it with `invalid_request` naming `reasoning.maxTokens`.
+ * - `exclude: true` means the model may still reason, and be billed for it, but
+ *   no reasoning is returned: no `reasoning` delta, no reasoning part, no opaque
+ *   token. A caller that excludes reasoning cannot continue it.
+ *
+ * Carrying `reasoning` at all, even as `{}`, opts in to receiving reasoning
+ * continuation tokens (the `opaque` field of a `reasoning` delta); a request
+ * without it never receives one, which is what keeps older readers of the
+ * stream unaffected.
  */
 export declare const inferenceReasoningSchema: z.ZodObject<{
-    effort: z.ZodEnum<{
+    effort: z.ZodOptional<z.ZodEnum<{
         low: "low";
         medium: "medium";
         high: "high";
-    }>;
+    }>>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    exclude: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /** Parameters for text-to-speech, preserved in the signed request. */
 export declare const inferenceSpeechParametersSchema: z.ZodObject<{

package/dist/public/messages.js

@@ -33,34 +33,44 @@ export const inferenceContentSourceSchema = z.discriminatedUnion('kind', [
 /**
  * One part of a message's content. A message is always a list of parts.
  *
- * ## `refusal` is a member and `reasoning` is not, and the asymmetry is the point
+ * ## `refusal` and `reasoning` are members, and neither is ever answer text
  *
  * A model that DECLINES says why, and those words are meant for the customer:
  * they are the difference between "rephrase this" and "stop asking". Before this
  * member existed there was nowhere in an {@link InferenceMessage} to put them, so
- * a non-streaming fold kept `finishReason: 'refusal'` and dropped the sentence —
- * the customer learned they were refused and not why, while a streaming caller of
- * the same request got the whole explanation on the `refusal` delta channel.
+ * a non-streaming fold kept `finishReason: 'refusal'` and dropped the sentence.
+ * The part is a MEMBER rather than a field because a refusal need not have text:
+ * an Anthropic `stop_reason: "refusal"` maps to the finish reason and separates
+ * no words from the answer, while an OpenAI-compatible `refusal` does.
  *
- * Reasoning is the opposite case and stays absent. It is the model's private
- * working, and a `text` part is where somebody would put it — which renders
- * private reasoning to the customer AS the answer, the product bug the delta
- * channels exist to prevent. An opaque per-block reasoning blob crossing this
- * boundary needs a home nobody has chosen yet, and inventing one here would
- * choose it by accident.
+ * ## `reasoning` (contract set 8.6.0, Kaana ADR 0009 decision 2)
  *
- * Both public dialects can carry a refusal, which is what separates the two
- * cases at the boundary as well as in principle: `refusal` is OpenAI's OWN field
- * in both of its shapes (`delta.refusal` streaming, `message.refusal`
- * non-streaming), while reasoning has no OpenAI field at all — the
- * `reasoning_content`/`reasoning` spellings an OpenAI-compatible provider emits
- * are provider extensions. So carrying the refusal costs no dialect its
- * standard-client parseability, and carrying reasoning would.
+ * Reasoning was deliberately absent until the owner chose its home, because an
+ * opaque per-block reasoning blob had none. The cost of that absence was
+ * correctness: a thinking model that calls a tool cannot be continued unless the
+ * assistant's reasoning blocks, with their signatures, come back to the provider
+ * unmodified and in order, and a customer who only ever received reasoning TEXT
+ * on the `reasoning` delta channel had nothing to send back.
  *
- * The part is a MEMBER rather than a field because a refusal need not have text:
- * an Anthropic `stop_reason: "refusal"` maps to the finish reason and separates
- * no words from the answer, while an OpenAI-compatible `refusal` does. A required
- * field would force the first provider to invent a sentence.
+ * The part is `{type: 'reasoning', text?, opaque?}`:
+ *
+ * - `text` is what a person may read. It is a display value and is never
+ *   forwarded to a provider on its own.
+ * - `opaque` is a continuation token the customer MUST return UNMODIFIED, in the
+ *   position it arrived. Its content is Kaana's to define and the customer's to
+ *   treat as a sealed string: it is provider-neutral on the surface and carries
+ *   whatever the serving provider needs to continue. Sealing is NOT
+ *   cryptographic: a forged or edited token is no more than a request the
+ *   provider refuses, so nothing may rely on it for trust.
+ * - at least one of the two is present.
+ *
+ * A reasoning part is the assistant's alone, exactly as a refusal is. It is
+ * never a `text` part, so no renderer can present private reasoning as the
+ * answer, and the delta channels keep reasoning apart for the same reason.
+ *
+ * What a route does with a token it cannot read (it was issued by another
+ * provider family, after a failover or a model switch) is drop it, never fail:
+ * the continuation is lost, the conversation is not.
  */
 export const inferenceContentPartSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('text'), text: z.string() }).strict(),
@@ -85,6 +95,20 @@ export const inferenceContentPartSchema = z.discriminatedUnion('type', [
      * renderer can present a refusal as the answer that was asked for.
      */
     z.object({ type: z.literal('refusal'), text: z.string() }).strict(),
+    /**
+     * The assistant's reasoning, readable and/or as an opaque continuation token
+     * to return unmodified. See the member note above.
+     */
+    z
+        .object({
+        type: z.literal('reasoning'),
+        text: z.string().optional(),
+        opaque: z.string().check(minUtf16Length(1)).optional(),
+    })
+        .strict()
+        .refine((part) => part.text !== undefined || part.opaque !== undefined, {
+        message: 'a reasoning part carries text, an opaque token, or both',
+    }),
 ]);
 /* -------------------------------------------------------------------------- */
 /*  Image input (contract set 8.2.0, Kaana ADR 0007)                           */
@@ -257,15 +281,15 @@ export const inferenceMessageSchema = z
         });
     }
     // Same rule as `toolCalls`, for the same reason: only the assistant can
-    // decline, so a refusal on any other role is a part every provider would
-    // silently ignore — and one a renderer might not.
+    // decline or reason, so either part on any other role is one every provider
+    // would silently ignore — and one a renderer might not.
     if (message.role !== 'assistant') {
         for (const [index, part] of message.content.entries()) {
-            if (part.type === 'refusal') {
+            if (part.type === 'refusal' || part.type === 'reasoning') {
                 ctx.addIssue({
                     code: 'custom',
                     path: ['content', index, 'type'],
-                    message: 'only an assistant message carries a refusal',
+                    message: `only an assistant message carries a ${part.type}`,
                 });
             }
         }
@@ -327,12 +351,33 @@ export const responseFormatSchema = z.discriminatedUnion('type', [
 ]);
 /**
  * The caller's reasoning control. Strict, like every leaf: a provider-specific
- * knob (`budget_tokens`, `summary`) is refused rather than silently dropped.
+ * knob (`summary`) is refused rather than silently dropped.
+ *
+ * - `effort` is how much to reason, in the catalogue's words. Oxy forwards it
+ *   only after checking the resolved model advertises it in `reasoningEfforts`.
+ * - `maxTokens` is a thinking BUDGET in tokens. It is the other way to size
+ *   reasoning, so it excludes `effort`. A route that cannot take a budget
+ *   refuses it with `invalid_request` naming `reasoning.maxTokens`.
+ * - `exclude: true` means the model may still reason, and be billed for it, but
+ *   no reasoning is returned: no `reasoning` delta, no reasoning part, no opaque
+ *   token. A caller that excludes reasoning cannot continue it.
  *
- * Oxy forwards it only after checking the resolved model advertises the effort
- * in its catalogue `reasoningEfforts`; Kaana translates it per provider.
+ * Carrying `reasoning` at all, even as `{}`, opts in to receiving reasoning
+ * continuation tokens (the `opaque` field of a `reasoning` delta); a request
+ * without it never receives one, which is what keeps older readers of the
+ * stream unaffected.
  */
-export const inferenceReasoningSchema = z.object({ effort: reasoningEffortSchema }).strict();
+export const inferenceReasoningSchema = z
+    .object({
+    effort: reasoningEffortSchema.optional(),
+    maxTokens: z.number().int().min(1).max(2_147_483_647).optional(),
+    exclude: z.boolean().optional(),
+})
+    .strict()
+    .refine((reasoning) => reasoning.effort === undefined || reasoning.maxTokens === undefined, {
+    message: 'reasoning takes an effort or a maxTokens budget, not both',
+    path: ['maxTokens'],
+});
 /** Parameters for text-to-speech, preserved in the signed request. */
 export const inferenceSpeechParametersSchema = z
     .object({

package/dist/public/responses.d.ts

@@ -92,6 +92,10 @@ export declare const responsesRequestSchema: z.ZodObject<{
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"reasoning">;
+            text: z.ZodOptional<z.ZodString>;
+            opaque: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], "type">>;
         name: z.ZodOptional<z.ZodString>;
         toolCallId: z.ZodOptional<z.ZodString>;
@@ -136,11 +140,13 @@ export declare const responsesRequestSchema: z.ZodObject<{
         strict: z.ZodBoolean;
     }, z.core.$strict>], "type">>;
     reasoning: z.ZodOptional<z.ZodObject<{
-        effort: z.ZodEnum<{
+        effort: z.ZodOptional<z.ZodEnum<{
             low: "low";
             medium: "medium";
             high: "high";
-        }>;
+        }>>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        exclude: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     clientRequestId: z.ZodOptional<z.ZodString>;
@@ -240,6 +246,10 @@ export declare const responseSchema: z.ZodObject<{
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"refusal">;
             text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"reasoning">;
+            text: z.ZodOptional<z.ZodString>;
+            opaque: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>], "type">>;
         name: z.ZodOptional<z.ZodString>;
         toolCallId: z.ZodOptional<z.ZodString>;

package/dist/public/streamEvents.d.ts

@@ -25,6 +25,7 @@ export declare const inferenceStreamDeltaEventSchema: z.ZodObject<{
         output_audio_transcript: "output_audio_transcript";
     }>;
     text: z.ZodString;
+    opaque: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** The encodings an audio output may carry. */
 export declare const inferenceAudioMediaTypeSchema: z.ZodEnum<{
@@ -238,6 +239,7 @@ export declare const responseStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         output_audio_transcript: "output_audio_transcript";
     }>;
     text: z.ZodString;
+    opaque: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     type: z.ZodLiteral<"audio">;

package/dist/public/streamEvents.js

@@ -32,6 +32,14 @@ export const inferenceStreamDeltaEventSchema = z.object({
      */
     channel: z.enum(['output_text', 'reasoning', 'refusal', 'output_audio_transcript']),
     text: z.string(),
+    /**
+     * Contract set 8.6.0. On the `reasoning` channel only: the continuation token
+     * of one finished reasoning block, which the customer returns UNMODIFIED as the
+     * `opaque` of a `reasoning` content part, in the order the blocks arrived.
+     * Emitted once per block, after the block's text deltas (with empty `text`),
+     * and only to a request that carried `reasoning` and did not `exclude` it.
+     */
+    opaque: z.string().check(minUtf16Length(1)).optional(),
 });
 /** The encodings an audio output may carry. */
 export const inferenceAudioMediaTypeSchema = z.enum([

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.5.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.6.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:
@@ -214,6 +214,15 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.5.0";
  * `promptCacheKey`) on `POST /v1/chat/completions` and `POST /v1/responses`
  * (Kaana ADR 0008). The preference only narrows what the grant admits. Nothing
  * in 8.4.0 changes and the signed grant and envelope are untouched.
+ *
+ * Contract set 8.6.0 is additive: reasoning continuity (Kaana ADR 0009 decision
+ * 2). `reasoning` takes `maxTokens` and `exclude` beside `effort` (all optional;
+ * `effort` and `maxTokens` are exclusive), a message's content gains the
+ * assistant-only `reasoning` part (`text?`, `opaque?`), and a `reasoning` delta
+ * may carry `opaque`. Every 8.5.0 message parses the same; the delta's `opaque`
+ * 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.
  */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";

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.5.0';
+export const INFERENCE_CONTRACT_VERSION = '8.6.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:
@@ -214,6 +214,15 @@ export const INFERENCE_CONTRACT_VERSION = '8.5.0';
  * `promptCacheKey`) on `POST /v1/chat/completions` and `POST /v1/responses`
  * (Kaana ADR 0008). The preference only narrows what the grant admits. Nothing
  * in 8.4.0 changes and the signed grant and envelope are untouched.
+ *
+ * Contract set 8.6.0 is additive: reasoning continuity (Kaana ADR 0009 decision
+ * 2). `reasoning` takes `maxTokens` and `exclude` beside `effort` (all optional;
+ * `effort` and `maxTokens` are exclusive), a message's content gains the
+ * assistant-only `reasoning` part (`text?`, `opaque?`), and a `reasoning` delta
+ * may carry `opaque`. Every 8.5.0 message parses the same; the delta's `opaque`
+ * 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.
  */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.5.0",
+    "version": "8.6.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": [
@@ -1282,6 +1282,27 @@
             "type": "array",
             "items": {
               "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "thinking"
+                    },
+                    "thinking": {
+                      "type": "string"
+                    },
+                    "signature": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "thinking",
+                    "signature"
+                  ],
+                  "additionalProperties": false
+                },
                 {
                   "type": "object",
                   "properties": {
@@ -1644,6 +1665,46 @@
                               "tool_use_id"
                             ],
                             "additionalProperties": false
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "const": "thinking"
+                              },
+                              "thinking": {
+                                "type": "string"
+                              },
+                              "signature": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "thinking",
+                              "signature"
+                            ],
+                            "additionalProperties": false
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "const": "redacted_thinking"
+                              },
+                              "data": {
+                                "type": "string",
+                                "minLength": 1,
+                                "maxLength": 1000000
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "data"
+                            ],
+                            "additionalProperties": false
                           }
                         ]
                       }
@@ -1812,17 +1873,53 @@
             ]
           },
           "thinking": {
-            "type": "object",
-            "properties": {
-              "type": {
-                "type": "string",
-                "const": "disabled"
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "const": "disabled"
+                  }
+                },
+                "required": [
+                  "type"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "const": "adaptive"
+                  }
+                },
+                "required": [
+                  "type"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "const": "enabled"
+                  },
+                  "budget_tokens": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "type",
+                  "budget_tokens"
+                ],
+                "additionalProperties": false
               }
-            },
-            "required": [
-              "type"
-            ],
-            "additionalProperties": false
+            ]
           },
           "output_config": {
             "type": "object",
@@ -1894,6 +1991,27 @@
                     "type": "array",
                     "items": {
                       "oneOf": [
+                        {
+                          "type": "object",
+                          "properties": {
+                            "type": {
+                              "type": "string",
+                              "const": "thinking"
+                            },
+                            "thinking": {
+                              "type": "string"
+                            },
+                            "signature": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "type",
+                            "thinking",
+                            "signature"
+                          ],
+                          "additionalProperties": false
+                        },
                         {
                           "type": "object",
                           "properties": {
@@ -2014,6 +2132,29 @@
               },
               "content_block": {
                 "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "thinking"
+                      },
+                      "thinking": {
+                        "type": "string",
+                        "const": ""
+                      },
+                      "signature": {
+                        "type": "string",
+                        "const": ""
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "thinking",
+                      "signature"
+                    ],
+                    "additionalProperties": false
+                  },
                   {
                     "type": "object",
                     "properties": {
@@ -2104,6 +2245,40 @@
                     ],
                     "additionalProperties": false
                   },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "thinking_delta"
+                      },
+                      "thinking": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "thinking"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "signature_delta"
+                      },
+                      "signature": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "signature"
+                    ],
+                    "additionalProperties": false
+                  },
                   {
                     "type": "object",
                     "properties": {
@@ -3876,6 +4051,26 @@
               "text"
             ],
             "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "reasoning"
+              },
+              "text": {
+                "type": "string"
+              },
+              "opaque": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": false
           }
         ]
       },
@@ -4062,11 +4257,16 @@
         "properties": {
           "effort": {
             "$ref": "#/components/schemas/ReasoningEffort"
+          },
+          "maxTokens": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 2147483647
+          },
+          "exclude": {
+            "type": "boolean"
           }
         },
-        "required": [
-          "effort"
-        ],
         "additionalProperties": false
       },
       "InferenceRegion": {
@@ -4193,6 +4393,10 @@
           },
           "text": {
             "type": "string"
+          },
+          "opaque": {
+            "type": "string",
+            "minLength": 1
           }
         },
         "required": [

package/package.json

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