@kaana.ai/contracts 8.0.1 → 8.2.0

package/dist/internal/catalogue.d.ts

@@ -562,6 +562,26 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         ultra: "ultra";
     }>>;
 }, z.core.$strip>;
+/**
+ * What a model line's image input costs at most, as the line's own documented
+ * rule states it (contract set 8.2.0, Kaana ADR 0007). Internal: Oxy reads it
+ * from the declared catalogue to bound the input of a request carrying images;
+ * `GET /v1/models` does not serve it.
+ *
+ * `maxInputTokensPerImage` is the most input tokens the line's provider bills
+ * for ONE image the contract admits (`checkImageInput`), at any `detail` the
+ * contract offers, from the publisher's documented resize and tokenization
+ * rule. Images are billed as input tokens at the line's `input_tokens` price;
+ * this figure only sizes a hold and qualifies a route, the settlement is the
+ * provider's own count.
+ *
+ * ABSENT means undeclared, even on a model whose `inputModalities` lists
+ * `image`: nobody has stated what one image costs on it, so no request carrying
+ * an image is authorized on it.
+ */
+export declare const declaredImageInputSchema: z.ZodObject<{
+    maxInputTokensPerImage: z.ZodNumber;
+}, z.core.$strict>;
 /**
  * One model as Kaana DECLARES it in `configs/public-catalogue.json` (Kaana ADR
  * 0002, amendment 2026-10-15): the public `modelSchema` without the three
@@ -791,6 +811,9 @@ export declare const declaredModelSchema: z.ZodObject<{
         platform_internal: "platform_internal";
         public: "public";
     }>;
+    imageInput: z.ZodOptional<z.ZodObject<{
+        maxInputTokensPerImage: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * The declared catalogue: identity, publisher, licence, provenance, data
@@ -1019,9 +1042,13 @@ export declare const declaredCatalogueSchema: z.ZodObject<{
             platform_internal: "platform_internal";
             public: "public";
         }>;
+        imageInput: z.ZodOptional<z.ZodObject<{
+            maxInputTokensPerImage: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type DeclaredModel = z.infer<typeof declaredModelSchema>;
+export type DeclaredImageInput = z.infer<typeof declaredImageInputSchema>;
 export type DeclaredCatalogue = z.infer<typeof declaredCatalogueSchema>;
 export type AvailabilityScope = z.infer<typeof availabilityScopeSchema>;
 export type CommercialPermission = z.infer<typeof commercialPermissionSchema>;

package/dist/internal/catalogue.js

@@ -354,6 +354,28 @@ export const modelCatalogueEntrySchema = z.object({
      */
     powerClass: modelPowerClassSchema.optional(),
 });
+/**
+ * What a model line's image input costs at most, as the line's own documented
+ * rule states it (contract set 8.2.0, Kaana ADR 0007). Internal: Oxy reads it
+ * from the declared catalogue to bound the input of a request carrying images;
+ * `GET /v1/models` does not serve it.
+ *
+ * `maxInputTokensPerImage` is the most input tokens the line's provider bills
+ * for ONE image the contract admits (`checkImageInput`), at any `detail` the
+ * contract offers, from the publisher's documented resize and tokenization
+ * rule. Images are billed as input tokens at the line's `input_tokens` price;
+ * this figure only sizes a hold and qualifies a route, the settlement is the
+ * provider's own count.
+ *
+ * ABSENT means undeclared, even on a model whose `inputModalities` lists
+ * `image`: nobody has stated what one image costs on it, so no request carrying
+ * an image is authorized on it.
+ */
+export const declaredImageInputSchema = z
+    .object({
+    maxInputTokensPerImage: z.number().int().positive().safe(),
+})
+    .strict();
 /**
  * One model as Kaana DECLARES it in `configs/public-catalogue.json` (Kaana ADR
  * 0002, amendment 2026-10-15): the public `modelSchema` without the three
@@ -368,8 +390,20 @@ export const modelCatalogueEntrySchema = z.object({
  */
 export const declaredModelSchema = modelSchema
     .omit({ schemaVersion: true, currentRevision: true, availableRevisions: true })
-    .extend({ audience: z.enum(['public', 'platform_internal']) })
-    .strict();
+    .extend({
+    audience: z.enum(['public', 'platform_internal']),
+    imageInput: declaredImageInputSchema.optional(),
+})
+    .strict()
+    .superRefine((model, ctx) => {
+    if (model.imageInput !== undefined && !model.capabilities.inputModalities.includes('image')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['imageInput'],
+            message: 'a model that bounds its image input takes image input',
+        });
+    }
+});
 /**
  * The declared catalogue: identity, publisher, licence, provenance, data
  * policy, capabilities, voices and the LIST PRICE per unit of every model

package/dist/internal/grant.d.ts

@@ -74,6 +74,7 @@ export declare const grantRequestFactsSchema: z.ZodObject<{
     audioInputMilliseconds: z.ZodOptional<z.ZodNumber>;
     embeddingInputs: z.ZodOptional<z.ZodNumber>;
     images: z.ZodOptional<z.ZodNumber>;
+    inputImages: z.ZodOptional<z.ZodNumber>;
     declaredTools: z.ZodNumber;
     stream: z.ZodBoolean;
     realtimeSessionKind: z.ZodOptional<z.ZodEnum<{
@@ -125,6 +126,7 @@ export declare const inferenceAuthorizationRequestSchema: z.ZodObject<{
         audioInputMilliseconds: z.ZodOptional<z.ZodNumber>;
         embeddingInputs: z.ZodOptional<z.ZodNumber>;
         images: z.ZodOptional<z.ZodNumber>;
+        inputImages: z.ZodOptional<z.ZodNumber>;
         declaredTools: z.ZodNumber;
         stream: z.ZodBoolean;
         realtimeSessionKind: z.ZodOptional<z.ZodEnum<{
@@ -204,6 +206,7 @@ export declare const authorizationRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
         audioInputMilliseconds: z.ZodOptional<z.ZodNumber>;
         embeddingInputs: z.ZodOptional<z.ZodNumber>;
         images: z.ZodOptional<z.ZodNumber>;
+        inputImages: z.ZodOptional<z.ZodNumber>;
         declaredTools: z.ZodNumber;
         stream: z.ZodBoolean;
         realtimeSessionKind: z.ZodOptional<z.ZodEnum<{

package/dist/internal/grant.js

@@ -22,7 +22,7 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { powerLevelSchema, realtimeSessionKindSchema } from '../public/catalogue.js';
 import { generationRecordSchema } from '../public/generations.js';
 import { delegatedUserIdSchema, generationIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, inferenceRegionSchema, inferenceTimestampSchema, modelIdSchema, modelRevisionLabelSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, } from '../public/identifiers.js';
-import { requestLabelsSchema } from '../public/messages.js';
+import { MAX_INPUT_IMAGES, requestLabelsSchema } from '../public/messages.js';
 import { moneySchema } from '../public/money.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceScopeSchema } from './attribution.js';
@@ -107,6 +107,13 @@ export const grantRequestFactsSchema = z
     /** Embeddings: how many inputs. Images: how many images. */
     embeddingInputs: z.number().int().positive().max(2048).optional(),
     images: z.number().int().positive().max(10).optional(),
+    /**
+     * Completions: how many image parts the input carries (contract set 8.2.0,
+     * Kaana ADR 0007), present exactly when it carries one. Their bytes are not
+     * in `estimatedInputTokens`: Oxy bounds each image by the line's declared
+     * `imageInput.maxInputTokensPerImage` and admits only lines that declare it.
+     */
+    inputImages: z.number().int().positive().max(MAX_INPUT_IMAGES).optional(),
     /** How many tools the request declares; their definitions stay in Kaana. */
     declaredTools: z.number().int().nonnegative().max(128),
     stream: z.boolean(),

package/dist/internal/realtime.d.ts

@@ -108,6 +108,7 @@ export declare const realtimeSessionRequestSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -248,6 +249,7 @@ export declare const realtimeSessionCreatedEventSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -505,6 +507,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -581,6 +584,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -827,6 +831,16 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     requestId: z.ZodString;
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"transcript.interim">;
+    source: z.ZodLiteral<"input_audio">;
+    itemId: z.ZodString;
+    contentIndex: z.ZodNumber;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"text.delta">;
     responseId: z.ZodString;

package/dist/internal/realtime.js

@@ -11,7 +11,7 @@ import { inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from
 import { usageQuantitySchema, usageSourceSchema } from '../public/money.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceFinishReasonSchema } from '../public/streamEvents.js';
-import { MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandAcceptedEventSchema, realtimeCommandIdSchema, realtimeConfigIssues, realtimeInputAudioClearedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeItemAddedEventSchema, realtimeItemDeletedEventSchema, realtimeItemDoneEventSchema, realtimeItemTruncatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeResponseCreatedEventSchema, realtimeResponseIdSchema, realtimeResponseStatusSchema, realtimeSessionCloseReasonSchema, realtimeSessionConfigSchema, realtimeSessionLimitsSchema, realtimeSessionResumedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, } from '../public/realtime.js';
+import { MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandAcceptedEventSchema, realtimeCommandIdSchema, realtimeConfigIssues, realtimeInputAudioClearedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeItemAddedEventSchema, realtimeItemDeletedEventSchema, realtimeItemDoneEventSchema, realtimeItemTruncatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeResponseCreatedEventSchema, realtimeResponseIdSchema, realtimeResponseStatusSchema, realtimeSessionCloseReasonSchema, realtimeSessionConfigSchema, realtimeSessionLimitsSchema, realtimeSessionResumedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, realtimeTranscriptInterimEventSchema, } from '../public/realtime.js';
 import { inferenceAttributionSchema } from './attribution.js';
 import { inferenceErrorSchema } from './errors.js';
 import { deploymentIdSchema, inferenceProviderSlugSchema } from './identifiers.js';
@@ -165,6 +165,7 @@ export const realtimeServerEventSchema = z
     realtimeOutputAudioDoneEventSchema,
     realtimeTranscriptDeltaEventSchema,
     realtimeTranscriptDoneEventSchema,
+    realtimeTranscriptInterimEventSchema,
     realtimeTextDeltaEventSchema,
     realtimeToolCallEventSchema,
     realtimeResponseDoneEventSchema,

package/dist/public/messages.d.ts

@@ -95,6 +95,61 @@ export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodO
     type: z.ZodLiteral<"refusal">;
     text: z.ZodString;
 }, z.core.$strict>], "type">;
+/**
+ * The image formats a request may carry. Every provider that serves image input
+ * on a Kaana route reads these four: Anthropic (`image/jpeg`, `image/png`,
+ * `image/gif`, `image/webp`) and OpenAI (PNG, JPEG, WEBP, non-animated GIF).
+ */
+export declare const INPUT_IMAGE_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+/**
+ * The most image parts one request may carry, across every message. Above 20
+ * images Anthropic applies a stricter per-image dimension limit to EVERY image
+ * of the request, so 20 is the most a request can carry and keep one rule per
+ * image on every route.
+ */
+export declare const MAX_INPUT_IMAGES = 20;
+/**
+ * The most decoded bytes one image may carry: 3,750,000, whose base64 is
+ * 5,000,000 characters, the smallest per-image limit a provider serving these
+ * routes documents (Anthropic on Amazon Bedrock: 5 MB base64-encoded).
+ */
+export declare const MAX_INPUT_IMAGE_BYTES = 3750000;
+/** Why one image part cannot be carried, before anything is held. Never the image itself. */
+export interface ImageInputIssue {
+    /** The message, as its index in the request's message list. */
+    readonly messageIndex: number;
+    /** The part, as its index in that message's content; absent for the request-wide count. */
+    readonly partIndex?: number;
+    /** The field at fault, relative to the part. */
+    readonly field: 'role' | 'source' | 'source.mediaType' | 'source.data' | 'count';
+    readonly message: string;
+}
+/**
+ * Check the image parts of a conversation against the contract's image rules
+ * (Kaana ADR 0007). Kaana refuses a request with `invalid_request` and the first
+ * issue BEFORE it asks Oxy for a grant; Oxy applies the same rules on its own
+ * edge; a client may run it first.
+ *
+ *  - an image is `inline`: no component fetches an image URL, and a `url`
+ *    source is never forwarded to a provider to fetch either;
+ *  - its media type is one of {@link INPUT_IMAGE_MEDIA_TYPES};
+ *  - its data is canonical base64 of at most {@link MAX_INPUT_IMAGE_BYTES} bytes;
+ *  - it rides on a `user` or `tool` message;
+ *  - the request carries at most {@link MAX_INPUT_IMAGES} of them.
+ *
+ * Returns the number of image parts and every issue, in message order. An issue
+ * names where and why, never the bytes: an image is payload and is never echoed
+ * into an error, a log line or a record.
+ */
+export declare function checkImageInput(messages: readonly InferenceMessage[]): {
+    readonly images: number;
+    readonly issues: ImageInputIssue[];
+};
+/**
+ * The decoded length of canonical base64 (RFC 4648 section 4, padded, no line
+ * breaks), or `undefined` when the text is not that. Counted, never decoded.
+ */
+export declare function base64DecodedLength(data: string): number | undefined;
 /**
  * A tool call an assistant made, in the normalized form.
  *

package/dist/public/messages.js

@@ -86,6 +86,113 @@ export const inferenceContentPartSchema = z.discriminatedUnion('type', [
      */
     z.object({ type: z.literal('refusal'), text: z.string() }).strict(),
 ]);
+/* -------------------------------------------------------------------------- */
+/*  Image input (contract set 8.2.0, Kaana ADR 0007)                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * The image formats a request may carry. Every provider that serves image input
+ * on a Kaana route reads these four: Anthropic (`image/jpeg`, `image/png`,
+ * `image/gif`, `image/webp`) and OpenAI (PNG, JPEG, WEBP, non-animated GIF).
+ */
+export const INPUT_IMAGE_MEDIA_TYPES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+];
+/**
+ * The most image parts one request may carry, across every message. Above 20
+ * images Anthropic applies a stricter per-image dimension limit to EVERY image
+ * of the request, so 20 is the most a request can carry and keep one rule per
+ * image on every route.
+ */
+export const MAX_INPUT_IMAGES = 20;
+/**
+ * The most decoded bytes one image may carry: 3,750,000, whose base64 is
+ * 5,000,000 characters, the smallest per-image limit a provider serving these
+ * routes documents (Anthropic on Amazon Bedrock: 5 MB base64-encoded).
+ */
+export const MAX_INPUT_IMAGE_BYTES = 3_750_000;
+/**
+ * Check the image parts of a conversation against the contract's image rules
+ * (Kaana ADR 0007). Kaana refuses a request with `invalid_request` and the first
+ * issue BEFORE it asks Oxy for a grant; Oxy applies the same rules on its own
+ * edge; a client may run it first.
+ *
+ *  - an image is `inline`: no component fetches an image URL, and a `url`
+ *    source is never forwarded to a provider to fetch either;
+ *  - its media type is one of {@link INPUT_IMAGE_MEDIA_TYPES};
+ *  - its data is canonical base64 of at most {@link MAX_INPUT_IMAGE_BYTES} bytes;
+ *  - it rides on a `user` or `tool` message;
+ *  - the request carries at most {@link MAX_INPUT_IMAGES} of them.
+ *
+ * Returns the number of image parts and every issue, in message order. An issue
+ * names where and why, never the bytes: an image is payload and is never echoed
+ * into an error, a log line or a record.
+ */
+export function checkImageInput(messages) {
+    const issues = [];
+    let images = 0;
+    for (const [messageIndex, message] of messages.entries()) {
+        for (const [partIndex, part] of message.content.entries()) {
+            if (part.type !== 'image')
+                continue;
+            images += 1;
+            const at = { messageIndex, partIndex };
+            if (message.role !== 'user' && message.role !== 'tool') {
+                issues.push({ ...at, field: 'role', message: 'an image rides on a user or tool message' });
+            }
+            const source = part.source;
+            if (source.kind !== 'inline') {
+                issues.push({
+                    ...at,
+                    field: 'source',
+                    message: 'an image is sent inline as base64; no image URL is fetched',
+                });
+                continue;
+            }
+            if (!INPUT_IMAGE_MEDIA_TYPES.includes(source.mediaType)) {
+                issues.push({
+                    ...at,
+                    field: 'source.mediaType',
+                    message: `an image is one of ${INPUT_IMAGE_MEDIA_TYPES.join(', ')}`,
+                });
+            }
+            const bytes = base64DecodedLength(source.data);
+            if (bytes === undefined) {
+                issues.push({ ...at, field: 'source.data', message: 'image data is canonical base64' });
+            }
+            else if (bytes > MAX_INPUT_IMAGE_BYTES) {
+                issues.push({
+                    ...at,
+                    field: 'source.data',
+                    message: `an image is at most ${MAX_INPUT_IMAGE_BYTES} bytes`,
+                });
+            }
+        }
+    }
+    if (images > MAX_INPUT_IMAGES) {
+        issues.push({
+            messageIndex: messages.length - 1,
+            field: 'count',
+            message: `a request carries at most ${MAX_INPUT_IMAGES} images`,
+        });
+    }
+    return { images, issues };
+}
+const BASE64_BODY = /^[A-Za-z0-9+/]*$/;
+/**
+ * The decoded length of canonical base64 (RFC 4648 section 4, padded, no line
+ * breaks), or `undefined` when the text is not that. Counted, never decoded.
+ */
+export function base64DecodedLength(data) {
+    if (data.length === 0 || data.length % 4 !== 0)
+        return undefined;
+    const padding = data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0;
+    if (!BASE64_BODY.test(data.slice(0, data.length - padding)))
+        return undefined;
+    return (data.length / 4) * 3 - padding;
+}
 /**
  * A tool call an assistant made, in the normalized form.
  *

package/dist/public/realtime.d.ts

@@ -89,6 +89,7 @@ export declare const realtimeTurnDetectionSchema: z.ZodDiscriminatedUnion<[z.Zod
 export declare const realtimeInputTranscriptionSchema: z.ZodObject<{
     language: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
+    interimResults: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /** The target of a `translation` session. */
 export declare const realtimeTranslationSchema: z.ZodObject<{
@@ -153,6 +154,7 @@ export declare const realtimeSessionConfigSchema: z.ZodObject<{
     inputAudioTranscription: z.ZodOptional<z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;
+        interimResults: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     translation: z.ZodOptional<z.ZodObject<{
         targetLanguage: z.ZodString;
@@ -210,6 +212,7 @@ export declare const realtimeSessionConfigUpdateSchema: z.ZodObject<{
     inputAudioTranscription: z.ZodOptional<z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;
+        interimResults: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"function">;
@@ -369,6 +372,7 @@ export declare const realtimeSessionUpdateCommandSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -559,6 +563,7 @@ export declare const realtimeClientCommandSchema: z.ZodDiscriminatedUnion<[z.Zod
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -740,6 +745,7 @@ export declare const realtimeSessionUpdatedEventSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1017,6 +1023,24 @@ export declare const realtimeTranscriptDoneEventSchema: z.ZodObject<{
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The provisional text of an input item not yet final (contract set 8.1.0,
+ * Kaana ADR 0006): sent only to a `transcription` session that asked for
+ * `interimResults`. Each one REPLACES the item's previous interim text; it is
+ * display state, never settled and never part of the item's transcript, and
+ * the item's next `transcript.delta` or its `transcript.done` supersedes it.
+ */
+export declare const realtimeTranscriptInterimEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"transcript.interim">;
+    source: z.ZodLiteral<"input_audio">;
+    itemId: z.ZodString;
+    contentIndex: z.ZodNumber;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /** Written output of a response (`outputModalities` including `text`). */
 export declare const realtimeTextDeltaEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"text.delta">;
@@ -1158,6 +1182,7 @@ export declare const realtimeSessionOpenSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1268,6 +1293,7 @@ export declare const realtimePublicSessionCreatedEventSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1505,6 +1531,7 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1581,6 +1608,7 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1827,6 +1855,16 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
     requestId: z.ZodString;
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"transcript.interim">;
+    source: z.ZodLiteral<"input_audio">;
+    itemId: z.ZodString;
+    contentIndex: z.ZodNumber;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"text.delta">;
     responseId: z.ZodString;

package/dist/public/realtime.js

@@ -116,6 +116,12 @@ export const realtimeInputTranscriptionSchema = z
     language: z.string().check(minUtf16Length(2)).check(maxUtf16Length(35)).optional(),
     /** A hint — vocabulary or context — used where the model takes one. */
     prompt: z.string().check(maxUtf16Length(4_096)).optional(),
+    /**
+     * Send `transcript.interim`: the model's provisional text of the current
+     * item, about every half second, before any of it is final (contract set
+     * 8.1.0, Kaana ADR 0006). Only a `transcription` session sends it.
+     */
+    interimResults: z.boolean().optional(),
 })
     .strict();
 /** The target of a `translation` session. */
@@ -506,6 +512,21 @@ export const realtimeTranscriptDoneEventSchema = z.object({
     responseId: realtimeResponseIdSchema.optional(),
     transcript: z.string(),
 });
+/**
+ * The provisional text of an input item not yet final (contract set 8.1.0,
+ * Kaana ADR 0006): sent only to a `transcription` session that asked for
+ * `interimResults`. Each one REPLACES the item's previous interim text; it is
+ * display state, never settled and never part of the item's transcript, and
+ * the item's next `transcript.delta` or its `transcript.done` supersedes it.
+ */
+export const realtimeTranscriptInterimEventSchema = z.object({
+    ...eventBase,
+    type: z.literal('transcript.interim'),
+    source: z.literal('input_audio'),
+    itemId: realtimeItemIdSchema,
+    contentIndex: z.number().int().nonnegative().safe(),
+    text: z.string(),
+});
 /** Written output of a response (`outputModalities` including `text`). */
 export const realtimeTextDeltaEventSchema = z.object({
     ...eventBase,
@@ -599,6 +620,9 @@ export function realtimeConfigIssues(kind, config) {
             }
             break;
     }
+    if (kind !== 'transcription' && config.inputAudioTranscription?.interimResults === true) {
+        found(['inputAudioTranscription', 'interimResults'], 'only a transcription session sends interim text');
+    }
     if (config.toolChoice !== undefined && !hasTools) {
         found(['toolChoice'], 'a tool choice requires at least one tool definition');
     }
@@ -805,6 +829,7 @@ export const realtimePublicServerEventSchema = z
     realtimeOutputAudioDoneEventSchema,
     realtimeTranscriptDeltaEventSchema,
     realtimeTranscriptDoneEventSchema,
+    realtimeTranscriptInterimEventSchema,
     realtimeTextDeltaEventSchema,
     realtimeToolCallEventSchema,
     realtimePublicResponseDoneEventSchema,

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.0.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.2.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:
@@ -181,6 +181,20 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.0.0";
  * envelopes v3 and v4 (`scopedExecutionSchema`, `privateAutoExecutionSchema`
  * and every shape under them) and a deployment's `scopedExecution`. A grant
  * or a request that parsed under 6.0.0 without them still parses the same.
+ *
+ * Contract set 8.1.0 (Kaana ADR 0006) is additive: a `transcription`
+ * session's `inputAudioTranscription.interimResults`, and the
+ * `transcript.interim` event it asks for, the provisional text of an input
+ * item that the item's deltas and its `transcript.done` supersede. Any other
+ * kind asking for interim text is refused. Nothing in 8.0.0 changes.
+ *
+ * Contract set 8.2.0 (Kaana ADR 0007) is additive: image input. The rules an
+ * image part answers to (`checkImageInput`, `INPUT_IMAGE_MEDIA_TYPES`,
+ * `MAX_INPUT_IMAGES`, `MAX_INPUT_IMAGE_BYTES`), the internal declared model's
+ * `imageInput` (the most input tokens one image costs on the line) and the
+ * grant fact `inputImages`. Every 8.1.0 message parses the same; a consumer on
+ * 8.1.0 or earlier refuses a declared catalogue or an authorization carrying
+ * what is new, so Oxy reads them before Kaana publishes them.
  */
 /** 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.0.0';
+export const INFERENCE_CONTRACT_VERSION = '8.2.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:
@@ -181,6 +181,20 @@ export const INFERENCE_CONTRACT_VERSION = '8.0.0';
  * envelopes v3 and v4 (`scopedExecutionSchema`, `privateAutoExecutionSchema`
  * and every shape under them) and a deployment's `scopedExecution`. A grant
  * or a request that parsed under 6.0.0 without them still parses the same.
+ *
+ * Contract set 8.1.0 (Kaana ADR 0006) is additive: a `transcription`
+ * session's `inputAudioTranscription.interimResults`, and the
+ * `transcript.interim` event it asks for, the provisional text of an input
+ * item that the item's deltas and its `transcript.done` supersede. Any other
+ * kind asking for interim text is refused. Nothing in 8.0.0 changes.
+ *
+ * Contract set 8.2.0 (Kaana ADR 0007) is additive: image input. The rules an
+ * image part answers to (`checkImageInput`, `INPUT_IMAGE_MEDIA_TYPES`,
+ * `MAX_INPUT_IMAGES`, `MAX_INPUT_IMAGE_BYTES`), the internal declared model's
+ * `imageInput` (the most input tokens one image costs on the line) and the
+ * grant fact `inputImages`. Every 8.1.0 message parses the same; a consumer on
+ * 8.1.0 or earlier refuses a declared catalogue or an authorization carrying
+ * what is new, so Oxy reads them before Kaana publishes them.
  */
 /** 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.0.0",
+    "version": "8.2.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": [
@@ -4470,6 +4470,9 @@
           "prompt": {
             "type": "string",
             "maxLength": 4096
+          },
+          "interimResults": {
+            "type": "boolean"
           }
         },
         "additionalProperties": false
@@ -5020,6 +5023,9 @@
           {
             "$ref": "#/components/schemas/RealtimeTranscriptDoneEvent"
           },
+          {
+            "$ref": "#/components/schemas/RealtimeTranscriptInterimEvent"
+          },
           {
             "$ref": "#/components/schemas/RealtimeTextDeltaEvent"
           },
@@ -5945,6 +5951,55 @@
           "transcript"
         ]
       },
+      "RealtimeTranscriptInterimEvent": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "sequence": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "transcript.interim"
+          },
+          "source": {
+            "type": "string",
+            "const": "input_audio"
+          },
+          "itemId": {
+            "$ref": "#/components/schemas/RealtimeItemId"
+          },
+          "contentIndex": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "sequence",
+          "type",
+          "source",
+          "itemId",
+          "contentIndex",
+          "text"
+        ]
+      },
       "RealtimeTranscriptSource": {
         "type": "string",
         "enum": [

package/package.json

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