@veruna/api-contracts 20.0.0 → 20.1.0

package/build/v1/message/schemas/stream-events.schema.d.ts

@@ -1,6 +1,10 @@
+import { GenerationStatus } from './generation-status.enum';
 import { z } from 'zod';
 import { GenerationStepType } from './generation-step-type.enum';
 import { StreamEventType } from './stream-event-type.enum';
+/**
+ * Step start event - a generation step started
+ */
 export declare const StreamStepStartEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -28,6 +32,15 @@ export declare const StreamStepStartEventSchema: z.ZodObject<{
         argsPreview: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
+/**
+ * Step chunk event - chunk from any step (text, reasoning, prompt generation).
+ *
+ * For text-producing steps (TEXT_GENERATION, REASONING, etc.) `chunk`
+ * carries the delta text and `metadata` is omitted. For CODE_EXECUTION
+ * steps the `metadata` discriminated union describes what the chunk
+ * represents (args streaming, bash line, create_file preview, etc.) and
+ * the frontend branches rendering on `metadata.kind`.
+ */
 export declare const StreamStepChunkEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -91,6 +104,9 @@ export declare const StreamStepChunkEventSchema: z.ZodObject<{
         }, z.core.$strip>], "type">;
     }, z.core.$strip>], "kind">>;
 }, z.core.$strip>;
+/**
+ * Step error event - a generation step failed
+ */
 export declare const StreamStepErrorEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -103,6 +119,9 @@ export declare const StreamStepErrorEventSchema: z.ZodObject<{
     errorCode: z.ZodString;
     errorMessage: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * Step done event - a generation step completed (NOT the whole stream)
+ */
 export declare const StreamStepDoneEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -120,6 +139,11 @@ export declare const StreamStepDoneEventSchema: z.ZodObject<{
         imageUrls: z.ZodArray<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{}, z.core.$strip>]>>;
 }, z.core.$strip>;
+/**
+ * Billing estimate event — initial hold opened before stream start.
+ * Sized at `model.price + Σ explicit option deltas`. Tools called
+ * during the run top up via STEP_BILLED on the fly.
+ */
 export declare const StreamBillingEstimateEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -128,6 +152,12 @@ export declare const StreamBillingEstimateEventSchema: z.ZodObject<{
     holdId: z.ZodString;
     estimatedTokens: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * Per-step billing event — emitted after each billable step settles.
+ * `stepTokens` is the cost of this single step (after markup), and
+ * `heldTokens` is the cumulative hold size including this step (initial
+ * estimate + Σ top-ups so far). For non-billable steps no event is sent.
+ */
 export declare const StreamStepBilledEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -140,22 +170,51 @@ export declare const StreamStepBilledEventSchema: z.ZodObject<{
     requestedTokens: z.ZodOptional<z.ZodNumber>;
     discountTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * Done event - stream completed successfully.
+ *
+ * `chargedTokens` is the final amount billed to the user — set after
+ * finalize() completes (via the outbox sync fast-path). Optional
+ * because the worker may finalize asynchronously after the stream's
+ * terminal event has already been delivered; clients that need the
+ * exact charge should fall back to GET /messages/:id when absent.
+ */
 export declare const StreamDoneEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof import("./message-error-category.enum").MessageErrorCategory>>>;
+    errorActions: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof import("./message-error-action.enum").MessageErrorAction>>>;
     type: z.ZodLiteral<StreamEventType.DONE>;
     chargedTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * Why the stream was cancelled. Surfaced in the CANCELLED event so the UI
+ * can render an explanation distinct from "user pressed stop" — in
+ * particular, INSUFFICIENT_FUNDS pairs with a BUDGET_PROMO step in the
+ * persisted message and a topup / register CTA banner.
+ */
 export declare enum StreamCancellationReason {
+    /** User invoked the stop button. */
     USER = "USER",
+    /** A heavy step couldn't be funded (StreamBudgetPolicy CUTOFF mode). */
     INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
+    /** Internal failure (db drop, runtime crash). */
     SYSTEM = "SYSTEM"
 }
+/**
+ * Cancelled event - stream cancelled by user OR by the runtime.
+ *
+ * `chargedTokens` reflects the partial settlement — only the steps that
+ * completed before cancel are charged. Additional fields explain *why*
+ * the stream stopped so the UI can render an actionable banner.
+ */
 export declare const StreamCancelledEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof import("./message-error-category.enum").MessageErrorCategory>>>;
+    errorActions: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof import("./message-error-action.enum").MessageErrorAction>>>;
     type: z.ZodLiteral<StreamEventType.CANCELLED>;
     chargedTokens: z.ZodOptional<z.ZodNumber>;
     reason: z.ZodOptional<z.ZodEnum<typeof StreamCancellationReason>>;
@@ -163,13 +222,24 @@ export declare const StreamCancelledEventSchema: z.ZodObject<{
     requiredTokens: z.ZodOptional<z.ZodNumber>;
     shortfallTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * Error event - error occurred during streaming.
+ * No details are exposed to frontend for security reasons; the
+ * partial charge for steps that succeeded before the failure is
+ * surfaced via `chargedTokens` when available.
+ */
 export declare const StreamErrorEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof import("./message-error-category.enum").MessageErrorCategory>>>;
+    errorActions: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof import("./message-error-action.enum").MessageErrorAction>>>;
     type: z.ZodLiteral<StreamEventType.ERROR>;
     chargedTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * Image event - AI generated image (base64)
+ */
 export declare const StreamImageEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -179,12 +249,18 @@ export declare const StreamImageEventSchema: z.ZodObject<{
     imageMimeType: z.ZodString;
     imageIndex: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * Image generation error event - image generation failed (content filter, etc.)
+ */
 export declare const StreamImageGenerationErrorEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
     type: z.ZodLiteral<StreamEventType.IMAGE_GENERATION_ERROR>;
 }, z.core.$strip>;
+/**
+ * Citations event - web search sources
+ */
 export declare const StreamCitationsEventSchema: z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
@@ -198,11 +274,32 @@ export declare const StreamCitationsEventSchema: z.ZodObject<{
         endIndex: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * Heartbeat event - keep-alive signal to prevent connection timeout
+ * Sent every 15 seconds during streaming
+ */
 export declare const StreamHeartbeatEventSchema: z.ZodObject<{
     type: z.ZodLiteral<StreamEventType.HEARTBEAT>;
     timestamp: z.ZodString;
 }, z.core.$strip>;
+/** Transient routing status before the first text or reasoning output. */
+export declare const StreamGenerationStatusEventSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    chatId: z.ZodString;
+    messageId: z.ZodString;
+    type: z.ZodLiteral<StreamEventType.GENERATION_STATUS>;
+    status: z.ZodEnum<typeof GenerationStatus>;
+    modelId: z.ZodString;
+}, z.core.$strip>;
+/** Discriminated union of all stream events; narrow by `type`. */
 export declare const StreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodNumber;
+    chatId: z.ZodString;
+    messageId: z.ZodString;
+    type: z.ZodLiteral<StreamEventType.GENERATION_STATUS>;
+    status: z.ZodEnum<typeof GenerationStatus>;
+    modelId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
@@ -367,12 +464,16 @@ export declare const StreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof import("./message-error-category.enum").MessageErrorCategory>>>;
+    errorActions: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof import("./message-error-action.enum").MessageErrorAction>>>;
     type: z.ZodLiteral<StreamEventType.DONE>;
     chargedTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof import("./message-error-category.enum").MessageErrorCategory>>>;
+    errorActions: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof import("./message-error-action.enum").MessageErrorAction>>>;
     type: z.ZodLiteral<StreamEventType.CANCELLED>;
     chargedTokens: z.ZodOptional<z.ZodNumber>;
     reason: z.ZodOptional<z.ZodEnum<typeof StreamCancellationReason>>;
@@ -383,6 +484,8 @@ export declare const StreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodNumber;
     chatId: z.ZodString;
     messageId: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof import("./message-error-category.enum").MessageErrorCategory>>>;
+    errorActions: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof import("./message-error-action.enum").MessageErrorAction>>>;
     type: z.ZodLiteral<StreamEventType.ERROR>;
     chargedTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>], "type">;

package/build/v1/message/schemas/stream-events.schema.js

@@ -1,106 +1,279 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StreamEventSchema = exports.StreamHeartbeatEventSchema = exports.StreamCitationsEventSchema = exports.StreamImageGenerationErrorEventSchema = exports.StreamImageEventSchema = exports.StreamErrorEventSchema = exports.StreamCancelledEventSchema = exports.StreamCancellationReason = exports.StreamDoneEventSchema = exports.StreamStepBilledEventSchema = exports.StreamBillingEstimateEventSchema = exports.StreamStepDoneEventSchema = exports.StreamStepErrorEventSchema = exports.StreamStepChunkEventSchema = exports.StreamStepStartEventSchema = void 0;
+exports.StreamEventSchema = exports.StreamGenerationStatusEventSchema = exports.StreamHeartbeatEventSchema = exports.StreamCitationsEventSchema = exports.StreamImageGenerationErrorEventSchema = exports.StreamImageEventSchema = exports.StreamErrorEventSchema = exports.StreamCancelledEventSchema = exports.StreamCancellationReason = exports.StreamDoneEventSchema = exports.StreamStepBilledEventSchema = exports.StreamBillingEstimateEventSchema = exports.StreamStepDoneEventSchema = exports.StreamStepErrorEventSchema = exports.StreamStepChunkEventSchema = exports.StreamStepStartEventSchema = void 0;
+const error_meta_schema_1 = require("./error-meta.schema");
+const generation_status_enum_1 = require("./generation-status.enum");
 const zod_1 = require("zod");
 const generation_step_type_enum_1 = require("./generation-step-type.enum");
 const stream_event_type_enum_1 = require("./stream-event-type.enum");
 const citation_schema_1 = require("./citation.schema");
 const step_metadata_schema_1 = require("./step-metadata.schema");
 const step_chunk_metadata_schema_1 = require("./step-chunk-metadata.schema");
+// ============================================================================
+// Base Event Schema
+// ============================================================================
 const BaseStreamEventSchema = zod_1.z.object({
+    /** Sequential event ID (starts from 1) */
     id: zod_1.z.number().int().positive(),
+    /** Chat UUID */
     chatId: zod_1.z.string().uuid(),
+    /** AI Message UUID */
     messageId: zod_1.z.string().uuid(),
 });
+// ============================================================================
+// Specific Event Schemas
+// ============================================================================
+/**
+ * Step start event - a generation step started
+ */
 exports.StreamStepStartEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.STEP_START),
+    /** Which step type started */
     stepType: zod_1.z.enum(generation_step_type_enum_1.GenerationStepType),
+    /** Unique step execution ID (UUID) */
     stepId: zod_1.z.string().uuid(),
+    /** Step index in pipeline (0-based) */
     stepIndex: zod_1.z.number().int().nonnegative(),
+    /**
+     * AiModel UUID that produced this step's output. Populated for
+     * step types in `MODEL_ATTRIBUTED_STEP_TYPES` (TEXT_GENERATION,
+     * REASONING, WEB_SEARCH, IMAGE_GENERATION, IMAGE_EDIT,
+     * VIDEO_ANALYSIS); `null` for
+     * tool / IO / utility-LLM steps that aren't user-attributed and
+     * for replayed events that pre-date this field. Frontend uses
+     * this to render which model generated each section of a message.
+     */
     modelUuid: zod_1.z.string().uuid().nullable().default(null),
+    /** Typed metadata per step type (queries for web_search, sourceResolution for image_edit, etc.) */
     metadata: step_metadata_schema_1.StepStartMetadataSchema,
 });
+/**
+ * Step chunk event - chunk from any step (text, reasoning, prompt generation).
+ *
+ * For text-producing steps (TEXT_GENERATION, REASONING, etc.) `chunk`
+ * carries the delta text and `metadata` is omitted. For CODE_EXECUTION
+ * steps the `metadata` discriminated union describes what the chunk
+ * represents (args streaming, bash line, create_file preview, etc.) and
+ * the frontend branches rendering on `metadata.kind`.
+ */
 exports.StreamStepChunkEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.STEP_CHUNK),
+    /** Which step type this chunk belongs to */
     stepType: zod_1.z.enum(generation_step_type_enum_1.GenerationStepType),
+    /** Unique step execution ID (UUID) */
     stepId: zod_1.z.string().uuid(),
+    /** Chunk content */
     chunk: zod_1.z.string(),
+    /**
+     * AiModel UUID that produced this step. Mirrors the value emitted on
+     * `STEP_START` for the same `stepId` — duplicated on every chunk so
+     * the FE can attribute the chunk to a model without maintaining a
+     * stepId→modelUuid map. `null` for non-attributed step types.
+     * See `MODEL_ATTRIBUTED_STEP_TYPES`.
+     */
     modelUuid: zod_1.z.string().uuid().nullable().default(null),
+    /** Typed per-kind metadata for CODE_EXECUTION chunks; omitted otherwise. */
     metadata: step_chunk_metadata_schema_1.StepChunkMetadataSchema.optional(),
 });
+/**
+ * Step error event - a generation step failed
+ */
 exports.StreamStepErrorEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.STEP_ERROR),
+    /** Which step type failed */
     stepType: zod_1.z.enum(generation_step_type_enum_1.GenerationStepType),
+    /** Unique step execution ID (UUID) */
     stepId: zod_1.z.string().uuid(),
+    /** Step index in pipeline (0-based) */
     stepIndex: zod_1.z.number().int().nonnegative(),
+    /**
+     * AiModel UUID that owned this step (mirrors `STEP_START.modelUuid`).
+     * `null` for non-attributed step types — see `MODEL_ATTRIBUTED_STEP_TYPES`.
+     */
     modelUuid: zod_1.z.string().uuid().nullable().default(null),
+    /** Step error code */
     errorCode: zod_1.z.string().min(1),
+    /** Optional step error message */
     errorMessage: zod_1.z.string().optional(),
 });
+/**
+ * Step done event - a generation step completed (NOT the whole stream)
+ */
 exports.StreamStepDoneEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.STEP_DONE),
+    /** Which step type completed */
     stepType: zod_1.z.enum(generation_step_type_enum_1.GenerationStepType),
+    /** Unique step execution ID (UUID) */
     stepId: zod_1.z.string().uuid(),
+    /** Step index in pipeline (0-based) */
     stepIndex: zod_1.z.number().int().nonnegative(),
+    /**
+     * AiModel UUID that produced this step (mirrors `STEP_START.modelUuid`).
+     * `null` for non-attributed step types — see `MODEL_ATTRIBUTED_STEP_TYPES`.
+     */
     modelUuid: zod_1.z.string().uuid().nullable().default(null),
+    /** Full content of the completed step (text steps) */
     fullContent: zod_1.z.string().optional(),
+    /** Structured content for non-text steps (code_execution, web_search, etc.) */
     structuredContent: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    /** Typed metadata per step type (imageUrl/imageUrls for upload step) */
     metadata: step_metadata_schema_1.StepDoneMetadataSchema,
 });
+/**
+ * Billing estimate event — initial hold opened before stream start.
+ * Sized at `model.price + Σ explicit option deltas`. Tools called
+ * during the run top up via STEP_BILLED on the fly.
+ */
 exports.StreamBillingEstimateEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.BILLING_ESTIMATE),
+    /** Hold UUID — same id used in transactions and DB. */
     holdId: zod_1.z.string().uuid(),
+    /** Estimated amount locked at the start of the stream. */
     estimatedTokens: zod_1.z.number().int().nonnegative(),
 });
+/**
+ * Per-step billing event — emitted after each billable step settles.
+ * `stepTokens` is the cost of this single step (after markup), and
+ * `heldTokens` is the cumulative hold size including this step (initial
+ * estimate + Σ top-ups so far). For non-billable steps no event is sent.
+ */
 exports.StreamStepBilledEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.STEP_BILLED),
+    /** Hold UUID — same id used in transactions and DB. */
     holdId: zod_1.z.string().uuid(),
+    /** Step UUID this charge belongs to. */
     stepId: zod_1.z.string().uuid(),
+    /** Cost of this single step (already in user-facing tokens). */
     stepTokens: zod_1.z.number().int().nonnegative(),
+    /** Cumulative hold size after this step (initial + top-ups). */
     heldTokens: zod_1.z.number().int().nonnegative(),
+    /**
+     * What the step would have cost if balance were unlimited. Equal to
+     * `stepTokens` (or omitted) for ordinary settlements; greater than
+     * `stepTokens` when the wallet ran out and the StreamBudgetPolicy
+     * applied a discount on this step. UI can render a "💚 covered N
+     * tokens" badge inline when `discountTokens > 0`.
+     */
     requestedTokens: zod_1.z.number().int().nonnegative().optional(),
+    /**
+     * Per-step write-off — `requestedTokens - stepTokens`. Always `>= 0`.
+     * Omitted when no overflow occurred.
+     */
     discountTokens: zod_1.z.number().int().nonnegative().optional(),
 });
-exports.StreamDoneEventSchema = BaseStreamEventSchema.extend({
+/**
+ * Done event - stream completed successfully.
+ *
+ * `chargedTokens` is the final amount billed to the user — set after
+ * finalize() completes (via the outbox sync fast-path). Optional
+ * because the worker may finalize asynchronously after the stream's
+ * terminal event has already been delivered; clients that need the
+ * exact charge should fall back to GET /messages/:id when absent.
+ */
+exports.StreamDoneEventSchema = BaseStreamEventSchema.extend(error_meta_schema_1.ErrorMetaSchema.shape).extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.DONE),
     chargedTokens: zod_1.z.number().int().nonnegative().optional(),
 });
+/**
+ * Why the stream was cancelled. Surfaced in the CANCELLED event so the UI
+ * can render an explanation distinct from "user pressed stop" — in
+ * particular, INSUFFICIENT_FUNDS pairs with a BUDGET_PROMO step in the
+ * persisted message and a topup / register CTA banner.
+ */
 var StreamCancellationReason;
 (function (StreamCancellationReason) {
+    /** User invoked the stop button. */
     StreamCancellationReason["USER"] = "USER";
+    /** A heavy step couldn't be funded (StreamBudgetPolicy CUTOFF mode). */
     StreamCancellationReason["INSUFFICIENT_FUNDS"] = "INSUFFICIENT_FUNDS";
+    /** Internal failure (db drop, runtime crash). */
     StreamCancellationReason["SYSTEM"] = "SYSTEM";
 })(StreamCancellationReason || (exports.StreamCancellationReason = StreamCancellationReason = {}));
-exports.StreamCancelledEventSchema = BaseStreamEventSchema.extend({
+/**
+ * Cancelled event - stream cancelled by user OR by the runtime.
+ *
+ * `chargedTokens` reflects the partial settlement — only the steps that
+ * completed before cancel are charged. Additional fields explain *why*
+ * the stream stopped so the UI can render an actionable banner.
+ */
+exports.StreamCancelledEventSchema = BaseStreamEventSchema.extend(error_meta_schema_1.ErrorMetaSchema.shape).extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.CANCELLED),
     chargedTokens: zod_1.z.number().int().nonnegative().optional(),
+    /** Why the stream stopped. Optional for backwards compat with old clients. */
     reason: zod_1.z.enum(StreamCancellationReason).optional(),
+    /**
+     * For INSUFFICIENT_FUNDS — the step type that couldn't be funded
+     * (e.g. IMAGE_GENERATION). Omitted for USER / SYSTEM.
+     */
     failedStepType: zod_1.z.enum(generation_step_type_enum_1.GenerationStepType).optional(),
+    /**
+     * For INSUFFICIENT_FUNDS — tokens the failed step would have needed.
+     * Mirrors the BUDGET_PROMO step's `requiredTokens` for clients that
+     * render the banner from the live event before reload.
+     */
     requiredTokens: zod_1.z.number().int().nonnegative().optional(),
+    /** For INSUFFICIENT_FUNDS — `requiredTokens - available`. */
     shortfallTokens: zod_1.z.number().int().nonnegative().optional(),
 });
-exports.StreamErrorEventSchema = BaseStreamEventSchema.extend({
+/**
+ * Error event - error occurred during streaming.
+ * No details are exposed to frontend for security reasons; the
+ * partial charge for steps that succeeded before the failure is
+ * surfaced via `chargedTokens` when available.
+ */
+exports.StreamErrorEventSchema = BaseStreamEventSchema.extend(error_meta_schema_1.ErrorMetaSchema.shape).extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.ERROR),
     chargedTokens: zod_1.z.number().int().nonnegative().optional(),
 });
+/**
+ * Image event - AI generated image (base64)
+ */
 exports.StreamImageEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.IMAGE),
+    /** Base64 encoded image data */
     imageBase64: zod_1.z.string().min(1),
+    /** Image MIME type (image/jpeg, image/png, etc.) */
     imageMimeType: zod_1.z.string().min(1),
+    /** Image index (for multiple images in one message) */
     imageIndex: zod_1.z.number().int().nonnegative(),
 });
+/**
+ * Image generation error event - image generation failed (content filter, etc.)
+ */
 exports.StreamImageGenerationErrorEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.IMAGE_GENERATION_ERROR),
 });
+/**
+ * Citations event - web search sources
+ */
 exports.StreamCitationsEventSchema = BaseStreamEventSchema.extend({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.CITATIONS),
+    /** Array of citations from web search */
     citations: zod_1.z.array(citation_schema_1.CitationSchema),
 });
+/**
+ * Heartbeat event - keep-alive signal to prevent connection timeout
+ * Sent every 15 seconds during streaming
+ */
 exports.StreamHeartbeatEventSchema = zod_1.z.object({
     type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.HEARTBEAT),
+    /** Server timestamp (ISO 8601) */
     timestamp: zod_1.z.string().datetime(),
 });
+// ============================================================================
+// Union Schema
+// ============================================================================
+/** Transient routing status before the first text or reasoning output. */
+exports.StreamGenerationStatusEventSchema = BaseStreamEventSchema.extend({
+    type: zod_1.z.literal(stream_event_type_enum_1.StreamEventType.GENERATION_STATUS),
+    /** May arrive in replay after text. Clients ignore statuses once visible text exists. */
+    status: zod_1.z.enum(generation_status_enum_1.GenerationStatus),
+    /** Model being tried now; SWITCHING_MODEL carries the new candidate model ID. */
+    modelId: zod_1.z.string().uuid(),
+});
+/** Discriminated union of all stream events; narrow by `type`. */
 exports.StreamEventSchema = zod_1.z.discriminatedUnion('type', [
+    exports.StreamGenerationStatusEventSchema,
     exports.StreamStepStartEventSchema,
     exports.StreamStepChunkEventSchema,
     exports.StreamStepErrorEventSchema,

package/build/v1/message/schemas/stream-events.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-events.schema.js","sourceRoot":"","sources":["../../../../v1/message/schemas/stream-events.schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stream-events.schema.js","sourceRoot":"","sources":["../../../../v1/message/schemas/stream-events.schema.ts"],"names":[],"mappings":"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"}

package/build/v1/model-route/model-route.errors.d.ts

@@ -1,10 +1,25 @@
 import { ErrorMetadata } from '../../shared';
 export declare enum ModelRouteErrorCode {
+    PROTECTED_MODEL_LAST_ROUTE = "PROTECTED_MODEL_LAST_ROUTE",
     MODEL_ROUTE_NOT_FOUND = "MODEL_ROUTE_NOT_FOUND",
     DUPLICATE_MODEL_ROUTE = "DUPLICATE_MODEL_ROUTE",
     INVALID_MODEL_ROUTE = "INVALID_MODEL_ROUTE",
+    /**
+     * A numeric `runtimeOverrides.failover.ttfbTimeoutMs` override would
+     * violate the derived timeout hierarchy's pool nesting — e.g. it exceeds
+     * the image pool wall-clock, or it undercuts the KIE waiter floor for a
+     * KIE async-jobs route.
+     */
     INVALID_TTFB_TIMEOUT_OVERRIDE = "INVALID_TTFB_TIMEOUT_OVERRIDE",
+    /** No ModelRouteTool row exists for (route, tool) on lookup/delete. */
     ROUTE_TOOL_NOT_FOUND = "ROUTE_TOOL_NOT_FOUND",
+    /**
+     * A route-tool upsert carries an option id (for a setting the model also
+     * defines) that is not among the model-level `AiModelTool.settingsConfig`
+     * option ids for that setting. The AI-visible schema and the user-charged
+     * price modifiers are keyed by option id at the model level, so a route
+     * introducing an unknown id would silently diverge billing from generation.
+     */
     ROUTE_TOOL_OPTION_MISMATCH = "ROUTE_TOOL_OPTION_MISMATCH"
 }
 export declare const MODEL_ROUTE_ERRORS: Record<ModelRouteErrorCode, ErrorMetadata>;

package/build/v1/model-route/model-route.errors.js

@@ -3,14 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MODEL_ROUTE_ERRORS = exports.ModelRouteErrorCode = void 0;
 var ModelRouteErrorCode;
 (function (ModelRouteErrorCode) {
+    ModelRouteErrorCode["PROTECTED_MODEL_LAST_ROUTE"] = "PROTECTED_MODEL_LAST_ROUTE";
     ModelRouteErrorCode["MODEL_ROUTE_NOT_FOUND"] = "MODEL_ROUTE_NOT_FOUND";
     ModelRouteErrorCode["DUPLICATE_MODEL_ROUTE"] = "DUPLICATE_MODEL_ROUTE";
     ModelRouteErrorCode["INVALID_MODEL_ROUTE"] = "INVALID_MODEL_ROUTE";
+    /**
+     * A numeric `runtimeOverrides.failover.ttfbTimeoutMs` override would
+     * violate the derived timeout hierarchy's pool nesting — e.g. it exceeds
+     * the image pool wall-clock, or it undercuts the KIE waiter floor for a
+     * KIE async-jobs route.
+     */
     ModelRouteErrorCode["INVALID_TTFB_TIMEOUT_OVERRIDE"] = "INVALID_TTFB_TIMEOUT_OVERRIDE";
+    /** No ModelRouteTool row exists for (route, tool) on lookup/delete. */
     ModelRouteErrorCode["ROUTE_TOOL_NOT_FOUND"] = "ROUTE_TOOL_NOT_FOUND";
+    /**
+     * A route-tool upsert carries an option id (for a setting the model also
+     * defines) that is not among the model-level `AiModelTool.settingsConfig`
+     * option ids for that setting. The AI-visible schema and the user-charged
+     * price modifiers are keyed by option id at the model level, so a route
+     * introducing an unknown id would silently diverge billing from generation.
+     */
     ModelRouteErrorCode["ROUTE_TOOL_OPTION_MISMATCH"] = "ROUTE_TOOL_OPTION_MISMATCH";
 })(ModelRouteErrorCode || (exports.ModelRouteErrorCode = ModelRouteErrorCode = {}));
 exports.MODEL_ROUTE_ERRORS = {
+    [ModelRouteErrorCode.PROTECTED_MODEL_LAST_ROUTE]: {
+        code: ModelRouteErrorCode.PROTECTED_MODEL_LAST_ROUTE,
+        statusCode: 409,
+    },
     [ModelRouteErrorCode.MODEL_ROUTE_NOT_FOUND]: {
         code: ModelRouteErrorCode.MODEL_ROUTE_NOT_FOUND,
         statusCode: 404,

package/build/v1/model-route/model-route.errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-route.errors.js","sourceRoot":"","sources":["../../../v1/model-route/model-route.errors.ts"],"names":[],"mappings":";;;AAEA,IAAY,mBAqBX;AArBD,WAAY,mBAAmB;IAC3B,sEAA+C,CAAA;IAC/C,sEAA+C,CAAA;IAC/C,kEAA2C,CAAA;IAO3C,sFAA+D,CAAA;IAE/D,oEAA6C,CAAA;IAQ7C,gFAAyD,CAAA;AAC7D,CAAC,EArBW,mBAAmB,mCAAnB,mBAAmB,QAqB9B;AAEY,QAAA,kBAAkB,GAA+C;IAC1E,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,EAAE;QACzC,IAAI,EAAE,mBAAmB,CAAC,qBAAqB;QAC/C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,EAAE;QACzC,IAAI,EAAE,mBAAmB,CAAC,qBAAqB;QAC/C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,EAAE;QACvC,IAAI,EAAE,mBAAmB,CAAC,mBAAmB;QAC7C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,6BAA6B,CAAC,EAAE;QACjD,IAAI,EAAE,mBAAmB,CAAC,6BAA6B;QACvD,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,EAAE;QACxC,IAAI,EAAE,mBAAmB,CAAC,oBAAoB;QAC9C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,0BAA0B,CAAC,EAAE;QAC9C,IAAI,EAAE,mBAAmB,CAAC,0BAA0B;QACpD,UAAU,EAAE,GAAG;KAClB;CACK,CAAC"}
+{"version":3,"file":"model-route.errors.js","sourceRoot":"","sources":["../../../v1/model-route/model-route.errors.ts"],"names":[],"mappings":";;;AAEA,IAAY,mBAsBX;AAtBD,WAAY,mBAAmB;IAC3B,gFAAyD,CAAA;IACzD,sEAA+C,CAAA;IAC/C,sEAA+C,CAAA;IAC/C,kEAA2C,CAAA;IAC3C;;;;;OAKG;IACH,sFAA+D,CAAA;IAC/D,uEAAuE;IACvE,oEAA6C,CAAA;IAC7C;;;;;;OAMG;IACH,gFAAyD,CAAA;AAC7D,CAAC,EAtBW,mBAAmB,mCAAnB,mBAAmB,QAsB9B;AAEY,QAAA,kBAAkB,GAA+C;IAC1E,CAAC,mBAAmB,CAAC,0BAA0B,CAAC,EAAE;QAC9C,IAAI,EAAE,mBAAmB,CAAC,0BAA0B;QACpD,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,EAAE;QACzC,IAAI,EAAE,mBAAmB,CAAC,qBAAqB;QAC/C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,EAAE;QACzC,IAAI,EAAE,mBAAmB,CAAC,qBAAqB;QAC/C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,EAAE;QACvC,IAAI,EAAE,mBAAmB,CAAC,mBAAmB;QAC7C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,6BAA6B,CAAC,EAAE;QACjD,IAAI,EAAE,mBAAmB,CAAC,6BAA6B;QACvD,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,EAAE;QACxC,IAAI,EAAE,mBAAmB,CAAC,oBAAoB;QAC9C,UAAU,EAAE,GAAG;KAClB;IACD,CAAC,mBAAmB,CAAC,0BAA0B,CAAC,EAAE;QAC9C,IAAI,EAAE,mBAAmB,CAAC,0BAA0B;QACpD,UAAU,EAAE,GAAG;KAClB;CACK,CAAC"}

package/build/v1/model-route/schemas/admin-model-route-sort.enum.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Admin ModelRoute sort fields.
+ * Values map to sortable ModelRoute columns.
+ * Sort direction uses the shared `SortOrder` enum.
+ */
 export declare enum AdminModelRouteSortField {
     PRIORITY = "priority",
     CREATED_AT = "createdAt",

package/build/v1/model-route/schemas/admin-model-route-sort.enum.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdminModelRouteSortField = void 0;
+/**
+ * Admin ModelRoute sort fields.
+ * Values map to sortable ModelRoute columns.
+ * Sort direction uses the shared `SortOrder` enum.
+ */
 var AdminModelRouteSortField;
 (function (AdminModelRouteSortField) {
     AdminModelRouteSortField["PRIORITY"] = "priority";

package/build/v1/model-route/schemas/admin-model-route-sort.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"admin-model-route-sort.enum.js","sourceRoot":"","sources":["../../../../v1/model-route/schemas/admin-model-route-sort.enum.ts"],"names":[],"mappings":";;;AAKA,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAChC,iDAAqB,CAAA;IACrB,oDAAwB,CAAA;IACxB,oDAAwB,CAAA;AAC5B,CAAC,EAJW,wBAAwB,wCAAxB,wBAAwB,QAInC"}
+{"version":3,"file":"admin-model-route-sort.enum.js","sourceRoot":"","sources":["../../../../v1/model-route/schemas/admin-model-route-sort.enum.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAChC,iDAAqB,CAAA;IACrB,oDAAwB,CAAA;IACxB,oDAAwB,CAAA;AAC5B,CAAC,EAJW,wBAAwB,wCAAxB,wBAAwB,QAInC"}

package/build/v1/model-route/schemas/kie-protocol.enum.d.ts

@@ -1,3 +1,7 @@
+/**
+ * KIE async createTask / webhook flow (image/video/audio generation).
+ * JOBS is also the default when runtimeOverrides.kie.protocol is omitted.
+ */
 export declare enum KieProtocol {
     JOBS = "JOBS"
 }

package/build/v1/model-route/schemas/kie-protocol.enum.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KieProtocol = void 0;
+/**
+ * KIE async createTask / webhook flow (image/video/audio generation).
+ * JOBS is also the default when runtimeOverrides.kie.protocol is omitted.
+ */
 var KieProtocol;
 (function (KieProtocol) {
     KieProtocol["JOBS"] = "JOBS";