@kaana.ai/contracts 8.2.0 → 8.4.0

package/dist/public/anthropicMessages.js

@@ -0,0 +1,274 @@
+/**
+ * `POST /v1/messages` — the Anthropic-Messages-compatible surface.
+ *
+ * It speaks the flat Anthropic request, response and stream shapes so an
+ * unmodified Anthropic SDK or Claude Code works with
+ * `ANTHROPIC_BASE_URL=https://kaana.ai` and an `oxy_sk_…` key (sent as
+ * `x-api-key` or as `Authorization: Bearer`). Like `/v1/chat/completions` it
+ * gains NO Kaana-specific request field, and it is `.strict()` everywhere: a
+ * stock SDK sending a parameter Kaana does not implement is told so rather than
+ * having it silently dropped.
+ *
+ * ## 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.
+ *  - **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.
+ *
+ * `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
+ * `end_turn`.
+ *
+ * `metadata.user_id` is accepted and neither forwarded nor stored: it is an
+ * end-user identifier, and Kaana persists none.
+ *
+ * `usage` is derived from the measured units: `input_tokens`, `output_tokens`
+ * (reasoning included, as Anthropic counts it) and, only when the route
+ * measured it, `cache_read_input_tokens`. There is no `cache_creation_*`.
+ */
+import { z } from 'zod';
+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();
+const imageBlockSchema = z
+    .object({
+    type: z.literal('image'),
+    source: z.discriminatedUnion('type', [
+        z
+            .object({
+            type: z.literal('base64'),
+            media_type: nonEmpty(255),
+            data: z.string().check(minUtf16Length(1)),
+        })
+            .strict(),
+        /** Parses so the refusal can name it; Kaana fetches no image URL. */
+        z.object({ type: z.literal('url'), url: nonEmpty(4096) }).strict(),
+    ]),
+})
+    .strict();
+const toolUseBlockSchema = z
+    .object({
+    type: z.literal('tool_use'),
+    id: nonEmpty(128),
+    name: nonEmpty(128),
+    input: z.record(z.string(), z.unknown()),
+})
+    .strict();
+const toolResultBlockSchema = z
+    .object({
+    type: z.literal('tool_result'),
+    tool_use_id: nonEmpty(128),
+    content: z
+        .union([z.string(), z.array(z.union([textBlockSchema, imageBlockSchema]))])
+        .optional(),
+    /**
+     * Accepted. The contract's tool message has no error flag, so the result's
+     * own content is what the model reads; the flag is not forwarded.
+     */
+    is_error: z.boolean().optional(),
+})
+    .strict();
+const messageSchema = z
+    .object({
+    role: z.enum(['user', 'assistant']),
+    content: z.union([
+        z.string(),
+        z
+            .array(z.union([textBlockSchema, imageBlockSchema, toolUseBlockSchema, toolResultBlockSchema]))
+            .min(1),
+    ]),
+})
+    .strict()
+    .superRefine((message, ctx) => {
+    if (typeof message.content === 'string')
+        return;
+    for (const [index, block] of message.content.entries()) {
+        const allowed = message.role === 'assistant'
+            ? block.type === 'text' || block.type === 'tool_use'
+            : block.type !== 'tool_use';
+        if (!allowed) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['content', index, 'type'],
+                message: `a ${message.role} message does not carry a ${block.type} block`,
+            });
+        }
+    }
+});
+const toolSchema = z
+    .object({
+    type: z.literal('custom').optional(),
+    name: nonEmpty(128),
+    description: z.string().check(maxUtf16Length(32768)).optional(),
+    input_schema: z.record(z.string(), z.unknown()),
+    strict: z.boolean().optional(),
+})
+    .strict();
+const toolChoiceSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('auto') }).strict(),
+    z.object({ type: z.literal('any') }).strict(),
+    z.object({ type: z.literal('none') }).strict(),
+    z.object({ type: z.literal('tool'), name: nonEmpty(128) }).strict(),
+]);
+export const anthropicMessagesRequestSchema = z
+    .object({
+    /** A model reference (`publisher/model[@revision]`) or a power level. */
+    model: modelTargetSchema,
+    /** Required, as Anthropic requires it. */
+    max_tokens: z.number().int().positive().safe(),
+    messages: z.array(messageSchema).min(1),
+    system: z.union([z.string(), z.array(textBlockSchema)]).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(),
+    stop_sequences: z.array(nonEmpty(256)).max(8).optional(),
+    stream: z.boolean().optional(),
+    tools: z.array(toolSchema).max(128).optional(),
+    tool_choice: toolChoiceSchema.optional(),
+    /** Only "off" is accepted: see the file comment. */
+    thinking: z
+        .object({ type: z.literal('disabled') })
+        .strict()
+        .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. */
+    metadata: z
+        .object({ user_id: z.string().check(maxUtf16Length(512)).nullable().optional() })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((request, ctx) => {
+    if (request.tool_choice !== undefined && (request.tools ?? []).length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['tool_choice'],
+            message: 'a tool choice requires at least one tool definition',
+        });
+    }
+});
+const usageSchema = z
+    .object({
+    input_tokens: z.number().int().nonnegative(),
+    output_tokens: z.number().int().nonnegative(),
+    /** Present only when the route measured a cache read. */
+    cache_read_input_tokens: z.number().int().nonnegative().optional(),
+})
+    .strict();
+const stopReasonSchema = z.enum(['end_turn', 'max_tokens', 'tool_use', 'refusal']);
+const outputBlockSchema = z.discriminatedUnion('type', [
+    textBlockSchema,
+    toolUseBlockSchema.extend({ input: z.record(z.string(), z.unknown()) }),
+]);
+const messageBodySchema = z.object({
+    id: nonEmpty(256),
+    type: z.literal('message'),
+    role: z.literal('assistant'),
+    /** The revision that served the request. */
+    model: nonEmpty(256),
+});
+/** The non-streaming body. The request id rides in `Kaana-Request-Id` and `Request-Id`. */
+export const anthropicMessageSchema = messageBodySchema
+    .extend({
+    content: z.array(outputBlockSchema),
+    stop_reason: stopReasonSchema,
+    stop_sequence: z.literal(null),
+    usage: usageSchema,
+})
+    .strict();
+/** The error body, and the data of a stream's `event: error` frame. */
+export const anthropicErrorSchema = z
+    .object({
+    type: z.literal('error'),
+    error: z
+        .object({
+        type: z.enum([
+            'invalid_request_error',
+            'authentication_error',
+            'billing_error',
+            'permission_error',
+            'not_found_error',
+            'request_too_large',
+            'rate_limit_error',
+            'timeout_error',
+            'overloaded_error',
+            'api_error',
+        ]),
+        message: nonEmpty(4096),
+    })
+        .strict(),
+    request_id: nonEmpty(256).optional(),
+})
+    .strict();
+/**
+ * One frame of a streamed message: `event: <type>` and this as its data. The
+ * input tokens are known only when the route reports usage, so `message_start`
+ * carries zeros and the final `message_delta` the measured totals. A stream that
+ * fails after its first frame ends with an `error` frame and no `message_stop`.
+ */
+export const anthropicStreamEventSchema = z.discriminatedUnion('type', [
+    z
+        .object({
+        type: z.literal('message_start'),
+        message: messageBodySchema
+            .extend({
+            content: z.array(outputBlockSchema).length(0),
+            stop_reason: z.literal(null),
+            stop_sequence: z.literal(null),
+            usage: usageSchema,
+        })
+            .strict(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal('content_block_start'),
+        index: z.number().int().nonnegative(),
+        content_block: z.discriminatedUnion('type', [
+            z.object({ type: z.literal('text'), text: z.literal('') }).strict(),
+            toolUseBlockSchema.extend({ input: z.object({}).strict() }),
+        ]),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal('content_block_delta'),
+        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('input_json_delta'), partial_json: z.string() }).strict(),
+        ]),
+    })
+        .strict(),
+    z
+        .object({ type: z.literal('content_block_stop'), index: z.number().int().nonnegative() })
+        .strict(),
+    z
+        .object({
+        type: z.literal('message_delta'),
+        delta: z.object({ stop_reason: stopReasonSchema, stop_sequence: z.literal(null) }).strict(),
+        usage: usageSchema,
+    })
+        .strict(),
+    z.object({ type: z.literal('message_stop') }).strict(),
+    z.object({ type: z.literal('ping') }).strict(),
+    anthropicErrorSchema,
+]);

package/dist/public/audio.d.ts

@@ -85,6 +85,7 @@ export declare const speechAudioDoneEventSchema: z.ZodObject<{
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;
@@ -168,6 +169,7 @@ export declare const speechStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;
@@ -313,6 +315,7 @@ export declare const transcriptionSchema: z.ZodObject<{
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;

package/dist/public/catalogue.d.ts

@@ -157,6 +157,11 @@ export declare const modelRealtimeCapabilitiesSchema: z.ZodObject<{
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/**
+ * The boolean capabilities that may be listed as unreported (contract set
+ * 8.4.0): the five whose `false` has so far meant both "no" and "not recorded".
+ */
+export declare const UNREPORTED_CAPABILITY_KEYS: readonly ["tools", "parallelToolCalls", "structuredOutput", "jsonMode", "promptCaching"];
 /**
  * What a model can do, in the terms a caller has to decide against before
  * sending a request: can it call tools, does it accept images, will it honour a
@@ -226,6 +231,13 @@ export declare const modelCapabilitiesSchema: z.ZodObject<{
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    unreported: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        tools: "tools";
+        parallelToolCalls: "parallelToolCalls";
+        structuredOutput: "structuredOutput";
+        jsonMode: "jsonMode";
+        promptCaching: "promptCaching";
+    }>>>;
 }, z.core.$strict>;
 /**
  * License terms, including the two questions that decide whether Oxy may serve
@@ -483,6 +495,13 @@ export declare const modelSchema: z.ZodObject<{
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
+        unreported: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            tools: "tools";
+            parallelToolCalls: "parallelToolCalls";
+            structuredOutput: "structuredOutput";
+            jsonMode: "jsonMode";
+            promptCaching: "promptCaching";
+        }>>>;
     }, z.core.$strict>;
     audio: z.ZodOptional<z.ZodObject<{
         voices: z.ZodArray<z.ZodObject<{
@@ -573,6 +592,7 @@ export declare const modelSchema: z.ZodObject<{
                 audio_output_tokens: "audio_output_tokens";
                 session_milliseconds: "session_milliseconds";
                 input_transcription_milliseconds: "input_transcription_milliseconds";
+                cache_write_input_tokens: "cache_write_input_tokens";
             }>;
             amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
             per: z.ZodNumber;
@@ -702,6 +722,13 @@ export declare const modelListSchema: z.ZodObject<{
                     }>>;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
+            unreported: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                tools: "tools";
+                parallelToolCalls: "parallelToolCalls";
+                structuredOutput: "structuredOutput";
+                jsonMode: "jsonMode";
+                promptCaching: "promptCaching";
+            }>>>;
         }, z.core.$strict>;
         audio: z.ZodOptional<z.ZodObject<{
             voices: z.ZodArray<z.ZodObject<{
@@ -792,6 +819,7 @@ export declare const modelListSchema: z.ZodObject<{
                     audio_output_tokens: "audio_output_tokens";
                     session_milliseconds: "session_milliseconds";
                     input_transcription_milliseconds: "input_transcription_milliseconds";
+                    cache_write_input_tokens: "cache_write_input_tokens";
                 }>;
                 amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
                 per: z.ZodNumber;

package/dist/public/catalogue.js

@@ -127,6 +127,17 @@ export const modelRealtimeCapabilitiesSchema = z
         .optional(),
 })
     .strict();
+/**
+ * The boolean capabilities that may be listed as unreported (contract set
+ * 8.4.0): the five whose `false` has so far meant both "no" and "not recorded".
+ */
+export const UNREPORTED_CAPABILITY_KEYS = [
+    'tools',
+    'parallelToolCalls',
+    'structuredOutput',
+    'jsonMode',
+    'promptCaching',
+];
 /**
  * What a model can do, in the terms a caller has to decide against before
  * sending a request: can it call tools, does it accept images, will it honour a
@@ -168,9 +179,38 @@ export const modelCapabilitiesSchema = z
     apiFormats: z.array(inferenceApiFormatSchema).min(1).optional(),
     /** Realtime sessions this model holds; absent means none. Contract set 3.2.0. */
     realtime: modelRealtimeCapabilitiesSchema.optional(),
+    /**
+     * The boolean capabilities whose value is NOT evidence: nobody recorded an
+     * answer, so `false` there means "not stated as true", not "known absent".
+     * Added in contract set 8.4.0 so the five required booleans keep their
+     * shape for every deployed reader while a producer can still say which of
+     * them it never established. A listed key is always `false`. ABSENT means
+     * undeclared (a catalogue from an older producer): every boolean is read
+     * as it was before this field existed.
+     */
+    unreported: z.array(z.enum(UNREPORTED_CAPABILITY_KEYS)).optional(),
 })
     .strict()
     .superRefine((capabilities, ctx) => {
+    const unreported = capabilities.unreported;
+    if (unreported !== undefined) {
+        if (new Set(unreported).size !== unreported.length) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['unreported'],
+                message: 'each unreported capability is listed at most once',
+            });
+        }
+        for (const [index, key] of unreported.entries()) {
+            if (capabilities[key]) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['unreported', index],
+                    message: `${key} is true, so it is reported: an unreported capability is false`,
+                });
+            }
+        }
+    }
     const formats = capabilities.apiFormats;
     if (formats !== undefined && new Set(formats).size !== formats.length) {
         ctx.addIssue({

package/dist/public/chatCompletions.d.ts

@@ -21,9 +21,9 @@ import { z } from 'zod';
  */
 export declare const chatCompletionMessageSchema: z.ZodObject<{
     role: z.ZodEnum<{
-        user: "user";
         system: "system";
         developer: "developer";
+        user: "user";
         assistant: "assistant";
         tool: "tool";
     }>;
@@ -93,9 +93,9 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
     }>]>;
     messages: z.ZodArray<z.ZodObject<{
         role: z.ZodEnum<{
-            user: "user";
             system: "system";
             developer: "developer";
+            user: "user";
             assistant: "assistant";
             tool: "tool";
         }>;

package/dist/public/decisions.d.ts

@@ -145,6 +145,7 @@ export declare const decisionSuccessSchema: z.ZodObject<{
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;

package/dist/public/generations.d.ts

@@ -57,6 +57,7 @@ export declare const chargedGenerationRecordSchema: z.ZodObject<{
                 audio_output_tokens: "audio_output_tokens";
                 session_milliseconds: "session_milliseconds";
                 input_transcription_milliseconds: "input_transcription_milliseconds";
+                cache_write_input_tokens: "cache_write_input_tokens";
             }>;
             amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
             per: z.ZodNumber;
@@ -106,6 +107,7 @@ export declare const chargedGenerationRecordSchema: z.ZodObject<{
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;
@@ -174,6 +176,7 @@ export declare const meteredGenerationRecordSchema: z.ZodObject<{
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;
@@ -206,6 +209,7 @@ export declare const generationRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
                 audio_output_tokens: "audio_output_tokens";
                 session_milliseconds: "session_milliseconds";
                 input_transcription_milliseconds: "input_transcription_milliseconds";
+                cache_write_input_tokens: "cache_write_input_tokens";
             }>;
             amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
             per: z.ZodNumber;
@@ -255,6 +259,7 @@ export declare const generationRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;
@@ -317,6 +322,7 @@ export declare const generationRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         quantity: z.ZodNumber;
     }, z.core.$strict>>;

package/dist/public/messages.d.ts

@@ -163,9 +163,9 @@ export declare const inferenceToolCallSchema: z.ZodObject<{
     arguments: z.ZodString;
 }, z.core.$strict>;
 export declare const inferenceMessageRoleSchema: z.ZodEnum<{
-    user: "user";
     system: "system";
     developer: "developer";
+    user: "user";
     assistant: "assistant";
     tool: "tool";
 }>;
@@ -179,9 +179,9 @@ export declare const inferenceMessageRoleSchema: z.ZodEnum<{
  */
 export declare const inferenceMessageSchema: z.ZodObject<{
     role: z.ZodEnum<{
-        user: "user";
         system: "system";
         developer: "developer";
+        user: "user";
         assistant: "assistant";
         tool: "tool";
     }>;

package/dist/public/messages.js

@@ -296,7 +296,7 @@ export const toolDefinitionSchema = z
     .object({
     type: z.literal('function'),
     name: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
-    description: z.string().check(maxUtf16Length(2000)).optional(),
+    description: z.string().check(maxUtf16Length(32768)).optional(),
     parameters: z.record(z.string(), z.unknown()),
     /** Ask the provider to enforce the schema, where it supports enforcement. */
     strict: z.boolean().optional(),

package/dist/public/money.d.ts

@@ -142,12 +142,22 @@ export declare const moneySchema: z.ZodObject<{
  * (`routes/inferenceEdge.ts` renders `prompt_tokens` as
  * `input_tokens + cached_input_tokens`).
  *
+ * **`cache_write_input_tokens` is the first-request premium** (added in contract
+ * set 8.4.0): input tokens written to a prompt cache on THIS request, which a
+ * provider bills above the base input rate (Anthropic's 5-minute write is 1.25x
+ * input). It is a sibling under the partition rule, never inside `input_tokens`
+ * or `cached_input_tokens`: a cache read and a cache write of the same token
+ * cannot both happen, so the three never count one token twice. It covers the
+ * provider's DEFAULT time-to-live only; a longer TTL is a different price and
+ * is not expressible by this unit, so a route that cannot price it refuses it.
+ * Declared before anything emits it: Oxy must accept the unit first.
+ *
  * Time is carried in integer MILLISECONDS rather than seconds so that no unit
  * quantity is ever fractional: a 12.5-second transcription is `12500`, exactly,
  * and the "units are integers" rule holds for every modality instead of holding
  * for tokens and being quietly broken by audio.
  */
-export declare const USAGE_UNITS: readonly ["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings", "audio_input_tokens", "cached_audio_input_tokens", "audio_output_tokens", "session_milliseconds", "input_transcription_milliseconds"];
+export declare const USAGE_UNITS: readonly ["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings", "audio_input_tokens", "cached_audio_input_tokens", "audio_output_tokens", "session_milliseconds", "input_transcription_milliseconds", "cache_write_input_tokens"];
 export declare const usageUnitSchema: z.ZodEnum<{
     input_tokens: "input_tokens";
     cached_input_tokens: "cached_input_tokens";
@@ -165,6 +175,7 @@ export declare const usageUnitSchema: z.ZodEnum<{
     audio_output_tokens: "audio_output_tokens";
     session_milliseconds: "session_milliseconds";
     input_transcription_milliseconds: "input_transcription_milliseconds";
+    cache_write_input_tokens: "cache_write_input_tokens";
 }>;
 /**
  * A metered quantity of ONE unit. Never money — a quantity carries no price and
@@ -188,6 +199,7 @@ export declare const usageQuantitySchema: z.ZodObject<{
         audio_output_tokens: "audio_output_tokens";
         session_milliseconds: "session_milliseconds";
         input_transcription_milliseconds: "input_transcription_milliseconds";
+        cache_write_input_tokens: "cache_write_input_tokens";
     }>;
     quantity: z.ZodNumber;
 }, z.core.$strict>;
@@ -231,6 +243,7 @@ export declare const unitPriceSchema: z.ZodObject<{
         audio_output_tokens: "audio_output_tokens";
         session_milliseconds: "session_milliseconds";
         input_transcription_milliseconds: "input_transcription_milliseconds";
+        cache_write_input_tokens: "cache_write_input_tokens";
     }>;
     amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
     per: z.ZodNumber;
@@ -265,6 +278,7 @@ export declare const priceSnapshotSchema: z.ZodObject<{
             audio_output_tokens: "audio_output_tokens";
             session_milliseconds: "session_milliseconds";
             input_transcription_milliseconds: "input_transcription_milliseconds";
+            cache_write_input_tokens: "cache_write_input_tokens";
         }>;
         amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
         per: z.ZodNumber;
@@ -294,6 +308,7 @@ export declare const usageSchema: z.ZodArray<z.ZodObject<{
         audio_output_tokens: "audio_output_tokens";
         session_milliseconds: "session_milliseconds";
         input_transcription_milliseconds: "input_transcription_milliseconds";
+        cache_write_input_tokens: "cache_write_input_tokens";
     }>;
     quantity: z.ZodNumber;
 }, z.core.$strict>>;

package/dist/public/money.js

@@ -150,6 +150,16 @@ export const moneySchema = z
  * (`routes/inferenceEdge.ts` renders `prompt_tokens` as
  * `input_tokens + cached_input_tokens`).
  *
+ * **`cache_write_input_tokens` is the first-request premium** (added in contract
+ * set 8.4.0): input tokens written to a prompt cache on THIS request, which a
+ * provider bills above the base input rate (Anthropic's 5-minute write is 1.25x
+ * input). It is a sibling under the partition rule, never inside `input_tokens`
+ * or `cached_input_tokens`: a cache read and a cache write of the same token
+ * cannot both happen, so the three never count one token twice. It covers the
+ * provider's DEFAULT time-to-live only; a longer TTL is a different price and
+ * is not expressible by this unit, so a route that cannot price it refuses it.
+ * Declared before anything emits it: Oxy must accept the unit first.
+ *
  * Time is carried in integer MILLISECONDS rather than seconds so that no unit
  * quantity is ever fractional: a 12.5-second transcription is `12500`, exactly,
  * and the "units are integers" rule holds for every modality instead of holding
@@ -172,6 +182,7 @@ export const USAGE_UNITS = [
     'audio_output_tokens',
     'session_milliseconds',
     'input_transcription_milliseconds',
+    'cache_write_input_tokens',
 ];
 export const usageUnitSchema = z.enum(USAGE_UNITS);
 /**