@kaana.ai/contracts 8.5.0 → 8.7.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

@@ -11,24 +11,50 @@
  *
  * ## 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` 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.
  *
+ * ## `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
+ * `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
@@ -55,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;
@@ -76,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;
@@ -94,12 +126,22 @@ 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;
+            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<{
         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>;
@@ -111,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">;
@@ -122,9 +166,17 @@ 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">;
+        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";
@@ -143,12 +195,18 @@ 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;
+        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<{
@@ -198,12 +256,18 @@ 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;
+            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>;
@@ -218,12 +282,17 @@ 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<{
         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<{
@@ -232,6 +301,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

@@ -11,24 +11,50 @@
  *
  * ## 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` 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.
  *
+ * ## `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
+ * `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
@@ -46,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({
@@ -63,12 +100,28 @@ 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'),
     id: nonEmpty(128),
     name: nonEmpty(128),
     input: z.record(z.string(), z.unknown()),
+    cache_control: cacheControlSchema.optional(),
 })
     .strict();
 const toolResultBlockSchema = z
@@ -83,15 +136,24 @@ 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
-            .array(z.union([textBlockSchema, imageBlockSchema, toolUseBlockSchema, toolResultBlockSchema]))
+            .array(z.union([
+            textBlockSchema,
+            imageBlockSchema,
+            toolUseBlockSchema,
+            toolResultBlockSchema,
+            thinkingBlockSchema,
+            redactedThinkingBlockSchema,
+        ]))
             .min(1),
     ]),
 })
@@ -100,9 +162,12 @@ 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
+            : message.role === 'system'
+                ? block.type === 'text'
+                : block.type !== 'tool_use' && !reasoning;
         if (!allowed) {
             ctx.addIssue({
                 code: 'custom',
@@ -119,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', [
@@ -135,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(),
@@ -142,11 +211,28 @@ 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'), 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. */
@@ -175,6 +261,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 +330,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 +348,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<{