@kaana.ai/contracts 8.4.0 → 8.6.0

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export * from './public/images.js';
 export * from './public/messages.js';
 export * from './public/money.js';
 export * from './public/policy.js';
+export * from './public/providerPreferences.js';
 export * from './public/realtime.js';
 export * from './public/responses.js';
 export * from './public/streamEvents.js';

package/dist/index.js

@@ -24,6 +24,7 @@ export * from './public/images.js';
 export * from './public/messages.js';
 export * from './public/money.js';
 export * from './public/policy.js';
+export * from './public/providerPreferences.js';
 export * from './public/realtime.js';
 export * from './public/responses.js';
 export * from './public/streamEvents.js';

package/dist/internal/catalogue.d.ts

@@ -314,10 +314,10 @@ export declare const routingProfileSchema: z.ZodObject<{
     displayName: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     optimiseFor: z.ZodEnum<{
-        quality: "quality";
-        price: "price";
         latency: "latency";
         throughput: "throughput";
+        quality: "quality";
+        price: "price";
         balanced: "balanced";
     }>;
     candidates: z.ZodArray<z.ZodObject<{

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

@@ -2,9 +2,10 @@
  * `POST /v1/chat/completions` — the OpenAI-compatible surface.
  *
  * It speaks the flat OpenAI request and response shapes so an unmodified OpenAI
- * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key, and
- * it gains NO Kaana-specific request field: a capability with no OpenAI
- * representation lives on `/v1/responses`. `.strict()` everywhere: a stock SDK
+ * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key. Its
+ * one extension is `provider`, the OpenRouter-style routing preference (ADR
+ * 0008); every other capability with no OpenAI representation lives on
+ * `/v1/responses`. `.strict()` everywhere: a stock SDK
  * sending a parameter Kaana does not implement is told so rather than having it
  * silently dropped.
  *
@@ -69,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>;
@@ -141,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>;
@@ -214,6 +223,34 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>>;
     user: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodObject<{
+        order: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allow_fallbacks: z.ZodOptional<z.ZodBoolean>;
+        require_parameters: z.ZodOptional<z.ZodBoolean>;
+        quantizations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            unknown: "unknown";
+            int4: "int4";
+            int8: "int8";
+            fp4: "fp4";
+            mxfp4: "mxfp4";
+            nvfp4: "nvfp4";
+            fp6: "fp6";
+            fp8: "fp8";
+            mxfp8: "mxfp8";
+            fp16: "fp16";
+            bf16: "bf16";
+            fp32: "fp32";
+        }>>>;
+        sort: z.ZodOptional<z.ZodEnum<{
+            latency: "latency";
+            throughput: "throughput";
+        }>>;
+        preferred_max_latency: z.ZodOptional<z.ZodNumber>;
+        preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    prompt_cache_key: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** OpenAI's usage block, with the audio members only when audio tokens were metered. */
 export declare const chatCompletionUsageSchema: z.ZodObject<{

package/dist/public/chatCompletions.js

@@ -2,9 +2,10 @@
  * `POST /v1/chat/completions` — the OpenAI-compatible surface.
  *
  * It speaks the flat OpenAI request and response shapes so an unmodified OpenAI
- * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key, and
- * it gains NO Kaana-specific request field: a capability with no OpenAI
- * representation lives on `/v1/responses`. `.strict()` everywhere: a stock SDK
+ * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key. Its
+ * one extension is `provider`, the OpenRouter-style routing preference (ADR
+ * 0008); every other capability with no OpenAI representation lives on
+ * `/v1/responses`. `.strict()` everywhere: a stock SDK
  * sending a parameter Kaana does not implement is told so rather than having it
  * silently dropped.
  *
@@ -18,6 +19,7 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { reasoningEffortSchema } from './catalogue.js';
 import { publicErrorCodeSchema } from './errors.js';
 import { inferenceContentPartSchema } from './messages.js';
+import { promptCacheKeySchema, providerPreferencesSchema } from './providerPreferences.js';
 import { modelTargetSchema } from './responses.js';
 /** `stop` in the OpenAI dialect: one sequence or a list of them. */
 const openAiStopSchema = z.union([
@@ -139,6 +141,10 @@ export const chatCompletionsRequestSchema = z
      * only. `X-Oxy-User-Id` wins when both are present.
      */
     user: z.string().check(minUtf16Length(1)).check(maxUtf16Length(64)).optional(),
+    /** Routing preferences that can only narrow what the grant admits (ADR 0008). */
+    provider: providerPreferencesSchema.optional(),
+    /** OpenAI's field: keeps requests sharing a prompt prefix on one deployment. */
+    prompt_cache_key: promptCacheKeySchema.optional(),
 })
     .strict()
     .superRefine((request, ctx) => {

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<{