@veruna/api-contracts 19.1.0 → 20.1.0

package/build/v1/message/schemas/step-metadata.schema.js

@@ -4,28 +4,69 @@ exports.StepDoneMetadataSchema = exports.StepDoneMetadataByType = exports.Upload
 const zod_1 = require("zod");
 const sandbox_primitive_type_enum_1 = require("../../tool/sandbox/sandbox-primitive-type.enum");
 const generation_step_type_enum_1 = require("./generation-step-type.enum");
+// ============================================================================
+// Step-Start metadata — typed per step type
+// ============================================================================
+/**
+ * WEB_SEARCH step-start metadata: the queries being searched.
+ */
 exports.WebSearchStepStartMetadataSchema = zod_1.z.object({
     queries: zod_1.z.array(zod_1.z.string()),
 });
+/**
+ * CONVERSATION_SEARCH step-start metadata: the query being searched across the
+ * user's past chats. Emitted at step start so the UI can show "searching for X"
+ * live, before results land (mirrors WEB_SEARCH).
+ */
 exports.ConversationSearchStepStartMetadataSchema = zod_1.z.object({
     query: zod_1.z.string(),
 });
+/**
+ * IMAGE_EDIT step-start metadata: source image info.
+ */
 exports.ImageEditStepStartMetadataSchema = zod_1.z.object({
     sourceResolution: zod_1.z.string(),
     sourceImageCount: zod_1.z.number().int().nonnegative(),
 });
+/**
+ * VIDEO_ANALYSIS step-start metadata: the video being analysed.
+ */
 exports.VideoAnalysisStepStartMetadataSchema = zod_1.z.object({
     videoUrl: zod_1.z.string().url(),
 });
+/**
+ * CODE_EXECUTION step-start metadata: sandbox primitive discriminator.
+ *
+ * Emitted BEFORE the tool runs, while the LLM is still streaming tool_call
+ * arguments. `primitiveType` tells the UI which sandbox primitive to render
+ * (bash | create_file | str_replace | view). The UI correlates chunks and
+ * final content with this step via `stepId` on the stream event itself.
+ */
 exports.CodeExecutionStepStartMetadataSchema = zod_1.z.object({
     primitiveType: zod_1.z.enum(sandbox_primitive_type_enum_1.SandboxPrimitiveType),
 });
+/**
+ * CONNECTOR_TOOL step-start metadata: which connector tool is being invoked.
+ * Emitted at step start so the UI can render a live "calling <tool>" card
+ * before the upstream MCP call returns.
+ *
+ * `toolName` is the provider-local tool name (e.g. `ydisk_list`), NOT the
+ * `mcp_<slug>__<name>` wire function name. `connectionUuid` lets the FE resolve
+ * the owning connection (title/icon) by id. `providerKey` is the first-party
+ * provider key, or null for a custom MCP connection. The unique `toolName` +
+ * `connectionUuid` pair keeps this arm unambiguous within the plain union.
+ */
 exports.ConnectorToolStepStartMetadataSchema = zod_1.z.object({
     toolName: zod_1.z.string(),
     connectionUuid: zod_1.z.string(),
     providerKey: zod_1.z.string().nullable(),
     argsPreview: zod_1.z.string().optional(),
 });
+/**
+ * Registry of step-start metadata schemas by step type. Only specific step
+ * types carry metadata; others have `undefined`. Used by stream validators
+ * to pick the right schema given a step type at runtime.
+ */
 exports.StepStartMetadataByType = {
     [generation_step_type_enum_1.GenerationStepType.WEB_SEARCH]: exports.WebSearchStepStartMetadataSchema,
     [generation_step_type_enum_1.GenerationStepType.CONVERSATION_SEARCH]: exports.ConversationSearchStepStartMetadataSchema,
@@ -34,6 +75,10 @@ exports.StepStartMetadataByType = {
     [generation_step_type_enum_1.GenerationStepType.CODE_EXECUTION]: exports.CodeExecutionStepStartMetadataSchema,
     [generation_step_type_enum_1.GenerationStepType.CONNECTOR_TOOL]: exports.ConnectorToolStepStartMetadataSchema,
 };
+/**
+ * Union schema for all possible step-start metadata shapes. Used in
+ * stream-events schema for the metadata field.
+ */
 exports.StepStartMetadataSchema = zod_1.z
     .union([
     exports.WebSearchStepStartMetadataSchema,
@@ -44,13 +89,26 @@ exports.StepStartMetadataSchema = zod_1.z
     exports.ConnectorToolStepStartMetadataSchema,
 ])
     .optional();
+// ============================================================================
+// Step-Done metadata — typed per step type
+// ============================================================================
+/**
+ * UPLOAD step-done metadata: URLs of uploaded images.
+ */
 exports.UploadStepDoneMetadataSchema = zod_1.z.union([
     zod_1.z.object({ imageUrl: zod_1.z.string().url() }),
     zod_1.z.object({ imageUrls: zod_1.z.array(zod_1.z.string().url()) }),
     zod_1.z.object({}),
 ]);
+/**
+ * Registry of step-done metadata schemas by step type. Currently only
+ * UPLOAD carries metadata; others have `undefined`.
+ */
 exports.StepDoneMetadataByType = {
     [generation_step_type_enum_1.GenerationStepType.UPLOAD]: exports.UploadStepDoneMetadataSchema,
 };
+/**
+ * Union schema for all possible step-done metadata shapes.
+ */
 exports.StepDoneMetadataSchema = exports.UploadStepDoneMetadataSchema.optional();
 //# sourceMappingURL=step-metadata.schema.js.map

package/build/v1/message/schemas/step-metadata.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"step-metadata.schema.js","sourceRoot":"","sources":["../../../../v1/message/schemas/step-metadata.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,gGAAsF;AACtF,2EAAiE;AASpD,QAAA,gCAAgC,GAAG,OAAC,CAAC,MAAM,CAAC;IACrD,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAC;AAOU,QAAA,yCAAyC,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9D,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAKU,QAAA,gCAAgC,GAAG,OAAC,CAAC,MAAM,CAAC;IACrD,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC5B,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACnD,CAAC,CAAC;AAKU,QAAA,oCAAoC,GAAG,OAAC,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC7B,CAAC,CAAC;AAUU,QAAA,oCAAoC,GAAG,OAAC,CAAC,MAAM,CAAC;IACzD,aAAa,EAAE,OAAC,CAAC,IAAI,CAAC,kDAAoB,CAAC;CAC9C,CAAC,CAAC;AAaU,QAAA,oCAAoC,GAAG,OAAC,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IACpB,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE;IAC1B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAOU,QAAA,uBAAuB,GAEhC;IACA,CAAC,8CAAkB,CAAC,UAAU,CAAC,EAAE,wCAAgC;IACjE,CAAC,8CAAkB,CAAC,mBAAmB,CAAC,EAAE,iDAAyC;IACnF,CAAC,8CAAkB,CAAC,UAAU,CAAC,EAAE,wCAAgC;IACjE,CAAC,8CAAkB,CAAC,cAAc,CAAC,EAAE,4CAAoC;IACzE,CAAC,8CAAkB,CAAC,cAAc,CAAC,EAAE,4CAAoC;IACzE,CAAC,8CAAkB,CAAC,cAAc,CAAC,EAAE,4CAAoC;CAC5E,CAAC;AAMW,QAAA,uBAAuB,GAAG,OAAC;KACnC,KAAK,CAAC;IACH,wCAAgC;IAChC,iDAAyC;IACzC,wCAAgC;IAChC,4CAAoC;IACpC,4CAAoC;IACpC,4CAAoC;CACvC,CAAC;KACD,QAAQ,EAAE,CAAC;AASH,QAAA,4BAA4B,GAAG,OAAC,CAAC,KAAK,CAAC;IAChD,OAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;IACxC,OAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;IAClD,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC;CACf,CAAC,CAAC;AAMU,QAAA,sBAAsB,GAE/B;IACA,CAAC,8CAAkB,CAAC,MAAM,CAAC,EAAE,oCAA4B;CAC5D,CAAC;AAKW,QAAA,sBAAsB,GAAG,oCAA4B,CAAC,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"step-metadata.schema.js","sourceRoot":"","sources":["../../../../v1/message/schemas/step-metadata.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,gGAAsF;AACtF,2EAAiE;AAEjE,+EAA+E;AAC/E,4CAA4C;AAC5C,+EAA+E;AAE/E;;GAEG;AACU,QAAA,gCAAgC,GAAG,OAAC,CAAC,MAAM,CAAC;IACrD,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,yCAAyC,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9D,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,gCAAgC,GAAG,OAAC,CAAC,MAAM,CAAC;IACrD,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC5B,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACnD,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,oCAAoC,GAAG,OAAC,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC7B,CAAC,CAAC;AAEH;;;;;;;GAOG;AACU,QAAA,oCAAoC,GAAG,OAAC,CAAC,MAAM,CAAC;IACzD,aAAa,EAAE,OAAC,CAAC,IAAI,CAAC,kDAAoB,CAAC;CAC9C,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACU,QAAA,oCAAoC,GAAG,OAAC,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IACpB,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE;IAC1B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,uBAAuB,GAEhC;IACA,CAAC,8CAAkB,CAAC,UAAU,CAAC,EAAE,wCAAgC;IACjE,CAAC,8CAAkB,CAAC,mBAAmB,CAAC,EAAE,iDAAyC;IACnF,CAAC,8CAAkB,CAAC,UAAU,CAAC,EAAE,wCAAgC;IACjE,CAAC,8CAAkB,CAAC,cAAc,CAAC,EAAE,4CAAoC;IACzE,CAAC,8CAAkB,CAAC,cAAc,CAAC,EAAE,4CAAoC;IACzE,CAAC,8CAAkB,CAAC,cAAc,CAAC,EAAE,4CAAoC;CAC5E,CAAC;AAEF;;;GAGG;AACU,QAAA,uBAAuB,GAAG,OAAC;KACnC,KAAK,CAAC;IACH,wCAAgC;IAChC,iDAAyC;IACzC,wCAAgC;IAChC,4CAAoC;IACpC,4CAAoC;IACpC,4CAAoC;CACvC,CAAC;KACD,QAAQ,EAAE,CAAC;AAEhB,+EAA+E;AAC/E,2CAA2C;AAC3C,+EAA+E;AAE/E;;GAEG;AACU,QAAA,4BAA4B,GAAG,OAAC,CAAC,KAAK,CAAC;IAChD,OAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;IACxC,OAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;IAClD,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC;CACf,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,sBAAsB,GAE/B;IACA,CAAC,8CAAkB,CAAC,MAAM,CAAC,EAAE,oCAA4B;CAC5D,CAAC;AAEF;;GAEG;AACU,QAAA,sBAAsB,GAAG,oCAA4B,CAAC,QAAQ,EAAE,CAAC"}

package/build/v1/message/schemas/stream-event-type.enum.d.ts

@@ -1,15 +1,44 @@
+/**
+ * Stream Event Types for message streaming (NDJSON format)
+ */
 export declare enum StreamEventType {
+    /** Transient routing status before visible model output. */
+    GENERATION_STATUS = "GENERATION_STATUS",
+    /** Generation step started */
     STEP_START = "STEP_START",
+    /** Chunk from any step (text, reasoning, prompt generation) */
     STEP_CHUNK = "STEP_CHUNK",
+    /** Generation step failed (terminal error for the step) */
     STEP_ERROR = "STEP_ERROR",
+    /** Generation step completed (NOT the whole stream) */
     STEP_DONE = "STEP_DONE",
+    /** Image generated by AI */
     IMAGE = "IMAGE",
+    /** Image generation failed (content filter, etc.) */
     IMAGE_GENERATION_ERROR = "IMAGE_GENERATION_ERROR",
+    /** Web search citations/sources */
     CITATIONS = "CITATIONS",
+    /** Keep-alive heartbeat (sent every 15 seconds) */
     HEARTBEAT = "HEARTBEAT",
+    /**
+     * Initial billing hold opened (BEFORE the stream's first token).
+     * Carries the hold id and estimated lock amount so the frontend can
+     * show "X tokens locked" immediately. Reflects the lower-bound
+     * estimate (model.price + Σ explicit option deltas); runtime tools
+     * top up the hold mid-stream and surface via STEP_BILLED.
+     */
     BILLING_ESTIMATE = "BILLING_ESTIMATE",
+    /**
+     * Per-step billing settled. Emitted after each billable step's
+     * settleStep call, carrying the step's individual cost and the
+     * cumulative held amount (initial estimate + Σ top-ups). Lets the
+     * UI show real-time spend climbing during the stream.
+     */
     STEP_BILLED = "STEP_BILLED",
+    /** Stream completed successfully */
     DONE = "DONE",
+    /** Stream cancelled by user */
     CANCELLED = "CANCELLED",
+    /** Error occurred during streaming */
     ERROR = "ERROR"
 }

package/build/v1/message/schemas/stream-event-type.enum.js

@@ -1,20 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamEventType = void 0;
+/**
+ * Stream Event Types for message streaming (NDJSON format)
+ */
 var StreamEventType;
 (function (StreamEventType) {
+    /** Transient routing status before visible model output. */
+    StreamEventType["GENERATION_STATUS"] = "GENERATION_STATUS";
+    /** Generation step started */
     StreamEventType["STEP_START"] = "STEP_START";
+    /** Chunk from any step (text, reasoning, prompt generation) */
     StreamEventType["STEP_CHUNK"] = "STEP_CHUNK";
+    /** Generation step failed (terminal error for the step) */
     StreamEventType["STEP_ERROR"] = "STEP_ERROR";
+    /** Generation step completed (NOT the whole stream) */
     StreamEventType["STEP_DONE"] = "STEP_DONE";
+    /** Image generated by AI */
     StreamEventType["IMAGE"] = "IMAGE";
+    /** Image generation failed (content filter, etc.) */
     StreamEventType["IMAGE_GENERATION_ERROR"] = "IMAGE_GENERATION_ERROR";
+    /** Web search citations/sources */
     StreamEventType["CITATIONS"] = "CITATIONS";
+    /** Keep-alive heartbeat (sent every 15 seconds) */
     StreamEventType["HEARTBEAT"] = "HEARTBEAT";
+    /**
+     * Initial billing hold opened (BEFORE the stream's first token).
+     * Carries the hold id and estimated lock amount so the frontend can
+     * show "X tokens locked" immediately. Reflects the lower-bound
+     * estimate (model.price + Σ explicit option deltas); runtime tools
+     * top up the hold mid-stream and surface via STEP_BILLED.
+     */
     StreamEventType["BILLING_ESTIMATE"] = "BILLING_ESTIMATE";
+    /**
+     * Per-step billing settled. Emitted after each billable step's
+     * settleStep call, carrying the step's individual cost and the
+     * cumulative held amount (initial estimate + Σ top-ups). Lets the
+     * UI show real-time spend climbing during the stream.
+     */
     StreamEventType["STEP_BILLED"] = "STEP_BILLED";
+    /** Stream completed successfully */
     StreamEventType["DONE"] = "DONE";
+    /** Stream cancelled by user */
     StreamEventType["CANCELLED"] = "CANCELLED";
+    /** Error occurred during streaming */
     StreamEventType["ERROR"] = "ERROR";
 })(StreamEventType || (exports.StreamEventType = StreamEventType = {}));
 //# sourceMappingURL=stream-event-type.enum.js.map

package/build/v1/message/schemas/stream-event-type.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-event-type.enum.js","sourceRoot":"","sources":["../../../../v1/message/schemas/stream-event-type.enum.ts"],"names":[],"mappings":";;;AAGA,IAAY,eAsCX;AAtCD,WAAY,eAAe;IAEvB,4CAAyB,CAAA;IAEzB,4CAAyB,CAAA;IAEzB,4CAAyB,CAAA;IAEzB,0CAAuB,CAAA;IAEvB,kCAAe,CAAA;IAEf,oEAAiD,CAAA;IAEjD,0CAAuB,CAAA;IAEvB,0CAAuB,CAAA;IAQvB,wDAAqC,CAAA;IAOrC,8CAA2B,CAAA;IAE3B,gCAAa,CAAA;IAEb,0CAAuB,CAAA;IAEvB,kCAAe,CAAA;AACnB,CAAC,EAtCW,eAAe,+BAAf,eAAe,QAsC1B"}
+{"version":3,"file":"stream-event-type.enum.js","sourceRoot":"","sources":["../../../../v1/message/schemas/stream-event-type.enum.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,IAAY,eAwCX;AAxCD,WAAY,eAAe;IACvB,4DAA4D;IAC5D,0DAAuC,CAAA;IACvC,8BAA8B;IAC9B,4CAAyB,CAAA;IACzB,+DAA+D;IAC/D,4CAAyB,CAAA;IACzB,2DAA2D;IAC3D,4CAAyB,CAAA;IACzB,uDAAuD;IACvD,0CAAuB,CAAA;IACvB,4BAA4B;IAC5B,kCAAe,CAAA;IACf,qDAAqD;IACrD,oEAAiD,CAAA;IACjD,mCAAmC;IACnC,0CAAuB,CAAA;IACvB,mDAAmD;IACnD,0CAAuB,CAAA;IACvB;;;;;;OAMG;IACH,wDAAqC,CAAA;IACrC;;;;;OAKG;IACH,8CAA2B,CAAA;IAC3B,oCAAoC;IACpC,gCAAa,CAAA;IACb,+BAA+B;IAC/B,0CAAuB,CAAA;IACvB,sCAAsC;IACtC,kCAAe,CAAA;AACnB,CAAC,EAxCW,eAAe,+BAAf,eAAe,QAwC1B"}

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">;