@vellumai/assistant 0.8.5 → 0.8.7

package/src/api/README.md

@@ -1,5 +1,129 @@
 # @vellumai/assistant-api
 
-Public API surface for consumers of the assistant API (web client, gateway,
-evals, future external clients). This directory is the **source of truth** for
+Public API surface for consumers of the assistant runtime — web client, gateway,
+evals, future external clients. This directory is the **source of truth** for
 the wire contracts the assistant exposes: schemas, types, and pure helpers.
+
+Internal assistant code imports the files in this directory via relative paths
+(e.g. `../../api/events/open-url.js`). External consumers import the
+materialized npm-style package `@vellumai/assistant-api`, regenerated into
+`apps/web/node_modules/` by `apps/web/scripts/postinstall.ts`.
+
+## Architecture
+
+A single discriminated-union schema, `AssistantEventSchema`, covers every event
+type whose wire contract is canonical. The web parser (`event-parser.ts`) tries
+this schema first; events not yet covered fall through to a hand-rolled legacy
+switch. The migration goal is to drain the switch — each event moved here
+shrinks the legacy surface and makes wire-shape drift a compile error.
+
+`AssistantEvent` (re-exported alongside the schema) is `z.infer<typeof
+AssistantEventSchema>`. Consumers reference this single type rather than
+re-listing the individual member types: as new events migrate in, they appear
+in `AssistantEvent` automatically.
+
+## Migration recipe
+
+Each batch follows the same shape. Group cohesive event families (lifecycle,
+streaming, document-comment, ui-surface, etc.) rather than migrating events
+one at a time — the per-batch overhead is the same regardless of count.
+
+### 1. Add the canonical schema
+
+One file per event under `./events/`. Schemas use Zod's default strip
+mode — unknown fields are silently discarded during parsing so the
+server can add transport-level metadata (e.g. `seq`) without breaking
+client validation.
+
+```ts
+// assistant/src/api/events/my-event.ts
+import { z } from "zod";
+
+export const MyEventSchema = z.object({
+  type: z.literal("my_event"),
+  conversationId: z.string(),
+  // …
+});
+
+export type MyEvent = z.infer<typeof MyEventSchema>;
+```
+
+Add the type/schema re-export pair to `./index.ts`, alphabetically, and append
+the schema to the `AssistantEventSchema` discriminated union. No other changes
+to the canonical package are needed — `AssistantEvent` picks the new member
+up automatically.
+
+### 2. Adopt the canonical type in daemon code
+
+In `assistant/src/daemon/message-types/<domain>.ts`, delete the local
+`interface MyEvent { … }` declaration and import the canonical `MyEvent`
+type from `../../api/events/my-event.js`. The domain-level
+`_<Domain>ServerMessages` union alias (consumed by `message-protocol.ts`)
+keeps its existing shape — it just references the canonical types now.
+
+**Do not add `export type MyEventLocalName = MyEvent` alias bridges in the
+daemon message-types files.** They shadow the canonical name and create a
+second name for the same thing — exactly the drift this directory exists to
+prevent. Reference the canonical `*Event` name directly inside the
+`_<Domain>ServerMessages` aggregator union, and have downstream daemon
+consumers import the canonical type from `../../api/events/<name>.js` at the
+use site. The only thing that should live in `message-types/<domain>.ts` for
+a migrated event is the import and the union membership.
+
+### 3. Cut over web consumers
+
+`apps/web/src/domains/chat/api/event-types.ts` no longer needs to list the
+migrated event in its `AssistantEvent` union — `APIAssistantEvent` covers it.
+Drop the per-event member, leaving the union to peel off legacy entries one
+at a time as each event migrates.
+
+Local handler modules (e.g. `document-comment-events.ts`) keep their handler
+functions but import the wire types directly from `@vellumai/assistant-api`.
+Do **not** re-export the canonical types from intermediate modules — consumers
+import them straight from the canonical package.
+
+### 4. Delete the legacy parser cases
+
+Remove the matching `case "my_event":` blocks from
+`apps/web/src/domains/chat/api/event-parser.ts`. Any per-event helper
+(`parseFooBase`, etc.) goes with them.
+
+### 5. Tests
+
+Add parser tests for each migrated event covering:
+
+- happy path with all fields
+- minimal required only
+- missing required field → `UnknownEvent`
+- unknown extra field is silently stripped, event still parses
+
+For happy-path tests, inline the discriminator literal in both the input and
+the expected object. `const data = { type: "my_event", … }` widens
+`data.type` to `string`, breaking the discriminated-union match when the
+result is compared with `toEqual(data)`.
+
+Handler-level tests in the consuming domain modules typically need no change
+— the canonical types are wire-compatible with the previous local interfaces.
+
+### 6. Local greenlight gate
+
+Run before push, in order:
+
+```bash
+# In apps/web — regenerate the @vellumai/assistant-api bundle
+bun run scripts/postinstall.ts
+
+# Type-check both packages
+( cd assistant && bunx tsc --noEmit )
+( cd apps/web && bunx tsc --noEmit )
+
+# Targeted tests
+( cd apps/web && bun test src/domains/chat/api/event-parser.test.ts )
+
+# Lint + format the touched files
+bunx eslint <files>
+bunx prettier --write <files>
+```
+
+`format:check` is a distinct CI gate from `lint`; format the touched files
+before push.

package/src/api/constants/call-sites.ts

@@ -0,0 +1,27 @@
+/**
+ * Logical call-site identifiers stamped onto every `llm_request_log` row
+ * (column `call_site` — migration 264). The inspector branches on this
+ * value alone to distinguish real LLM calls (`mainAgent`,
+ * `compactionAgent`, …) from synthetic agent-error-message rows.
+ *
+ * The constants below are the wire contract; both backend (when writing
+ * a row) and frontend (when rendering one) must reference the same
+ * literal. Add new call sites here as new emit sites appear.
+ */
+
+/**
+ * Marks a synthetic assistant error-message row — one the agent loop
+ * emitted because something went wrong (budget yield, out of funds, …)
+ * with no underlying LLM call. All such events cause the loop to exit,
+ * so a single generic bucket plus the existing `agent_loop_exit_reason`
+ * column is enough to discriminate which kind of error fired
+ * (`budget_yield_unrecovered`, future out-of-funds, etc.).
+ *
+ * Intentionally *not* a member of the backend's `LLMCallSite` enum:
+ * that enum binds config lookup, not the shape of the `call_site`
+ * column. Compaction-route filters that match
+ * `call_site = 'compactionAgent'` already treat this value as a
+ * non-compaction call, which is the desired floor-lookup behavior.
+ */
+export const CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE =
+  "syntheticAgentErrorMessage";

package/src/api/constants/tool-execution.ts

@@ -0,0 +1,21 @@
+/**
+ * Default cap (in seconds) on how long a single tool invocation may run
+ * before the assistant aborts it with a synthetic error result. This is
+ * the canonical default for the `timeouts.toolExecutionTimeoutSec` config
+ * field and the fallback used by `executeWithTimeout` when the config
+ * value is missing or invalid.
+ *
+ * Exposed on the API surface so frontend consumers — chiefly
+ * `sanitizeDisplayMessages` in the web client — can recognise tool
+ * calls whose live tracking outlives any plausible server-side
+ * execution and mark them as failed instead of spinning forever. The
+ * canonical case is an assistant restart mid-tool: the daemon never
+ * delivers the `tool_result` SSE, the client retains
+ * `status: "running"`, and the bubble would otherwise stall the UI
+ * across the restart boundary.
+ *
+ * Treat this as the wire contract for the default. Callers that need a
+ * different ceiling should still read the deployed config — this
+ * constant is only authoritative when the config doesn't override it.
+ */
+export const DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC = 120;

package/src/api/events/assistant-activity-state.ts

@@ -0,0 +1,75 @@
+/**
+ * `assistant_activity_state` SSE event.
+ *
+ * Server-side assistant activity lifecycle, used by clients to place
+ * the thinking indicator. `activityVersion` is monotonically increasing
+ * per conversation; clients must ignore events with a version older
+ * than their current known version.
+ *
+ * `phase`, `anchor`, and `reason` are strict enums because the daemon
+ * emits a fixed, known set and clients switch on them. `requestId`
+ * marks the active user request when available; `statusText` is a
+ * human-readable description of what the assistant is doing.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const AssistantActivityPhaseSchema = z.enum([
+  "idle",
+  "thinking",
+  "streaming",
+  "tool_running",
+  "awaiting_confirmation",
+]);
+
+export type AssistantActivityPhase = z.infer<
+  typeof AssistantActivityPhaseSchema
+>;
+
+export const AssistantActivityAnchorSchema = z.enum([
+  "assistant_turn",
+  "user_turn",
+  "global",
+]);
+
+export type AssistantActivityAnchor = z.infer<
+  typeof AssistantActivityAnchorSchema
+>;
+
+export const AssistantActivityReasonSchema = z.enum([
+  "message_dequeued",
+  "thinking_delta",
+  "first_text_delta",
+  "tool_use_start",
+  "preview_start",
+  "tool_result_received",
+  "confirmation_requested",
+  "confirmation_resolved",
+  "context_compacting",
+  "message_complete",
+  "generation_cancelled",
+  "error_terminal",
+]);
+
+export type AssistantActivityReason = z.infer<
+  typeof AssistantActivityReasonSchema
+>;
+
+export const AssistantActivityStateEventSchema = z.object({
+  type: z.literal("assistant_activity_state"),
+  conversationId: z.string(),
+  activityVersion: z.number(),
+  phase: AssistantActivityPhaseSchema,
+  anchor: AssistantActivityAnchorSchema,
+  reason: AssistantActivityReasonSchema,
+  requestId: z.string().optional(),
+  statusText: z.string().optional(),
+});
+
+export type AssistantActivityStateEvent = z.infer<
+  typeof AssistantActivityStateEventSchema
+>;

package/src/api/events/assistant-outbound-attachment.ts

@@ -0,0 +1,49 @@
+/**
+ * Outbound assistant attachment — the wire shape attached to
+ * `message_complete` and `generation_handoff` SSE events when the
+ * assistant turn produced files (sandbox writes, host transfers, tool
+ * blocks that returned binary content).
+ *
+ * Shape is the daemon's emit-time projection of `UserMessageAttachment`
+ * (see `assistant/src/daemon/message-types/shared.ts`): only the fields
+ * built in `conversation-attachments.ts::buildEmittedAttachments` plus
+ * fields the daemon explicitly emits to clients (`filePath` for
+ * recordings, per #9744) make it onto the wire. Daemon-internal fields
+ * not intended for clients (`extractedText`) stay on the daemon side
+ * and do not appear here.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const AssistantOutboundAttachmentSchema = z.object({
+  /** Storage id assigned by the daemon's attachment store; absent on
+   *  in-memory drafts not backed by a stored row. */
+  id: z.string().optional(),
+  filename: z.string(),
+  mimeType: z.string(),
+  /** Base64-encoded file bytes. May be empty when `fileBacked` is
+   *  true and the client should hydrate via the /content endpoint. */
+  data: z.string(),
+  sourceType: z.enum(["sandbox_file", "host_file", "tool_block"]).optional(),
+  /** Original file size in bytes. Present when `data` was omitted to
+   *  keep payloads small. */
+  sizeBytes: z.number().optional(),
+  /** Base64-encoded JPEG thumbnail. Generated server-side for video
+   *  attachments. */
+  thumbnailData: z.string().optional(),
+  /** True when the attachment is stored on disk and clients should
+   *  hydrate via the /content endpoint instead of relying on `data`. */
+  fileBacked: z.boolean().optional(),
+  /** Local on-disk path for file-backed attachments. Used by the
+   *  macOS client to play recordings and render thumbnails directly
+   *  from the local file (see #9744 — eliminates the HTTP fetch +
+   *  ffmpeg dep for video). Web clients ignore this field. */
+  filePath: z.string().optional(),
+});
+
+export type AssistantOutboundAttachment = z.infer<
+  typeof AssistantOutboundAttachmentSchema
+>;

package/src/api/events/assistant-text-delta.ts

@@ -0,0 +1,30 @@
+/**
+ * `assistant_text_delta` SSE event.
+ *
+ * Streaming text chunk emitted by the daemon as the model produces
+ * assistant output. Multiple deltas accumulate into a single assistant
+ * message; the matching `message_complete` event marks the turn done.
+ *
+ * `messageId` is the database row id of the assistant message this
+ * delta belongs to — stamped from the pre-allocated turn anchor (see
+ * `reserveMessage` / `AssistantTurnStartEvent`). Absent on streams
+ * produced by older daemons that pre-date the anchor protocol, or on
+ * synthetic deltas (canned greetings, slash-command echoes, live-voice
+ * transcript injections) that don't bind to a row.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const AssistantTextDeltaEventSchema = z.object({
+  type: z.literal("assistant_text_delta"),
+  text: z.string(),
+  messageId: z.string().optional(),
+  conversationId: z.string().optional(),
+});
+
+export type AssistantTextDeltaEvent = z.infer<
+  typeof AssistantTextDeltaEventSchema
+>;

package/src/api/events/assistant-turn-start.ts

@@ -0,0 +1,31 @@
+/**
+ * `assistant_turn_start` SSE event.
+ *
+ * Marks the start of an assistant turn — emitted once by the daemon
+ * *before* any `assistant_text_delta`, `tool_use_start`, or
+ * `assistant_thinking_delta` event for that turn. The `messageId` is the
+ * pre-allocated database row id (see `reserveMessage` in
+ * `assistant/src/memory/conversation-crud.ts`) that subsequent streaming
+ * events stamp on their `messageId` field. Clients use this id to
+ * anchor a UI bubble at turn-start instead of waiting for
+ * `message_complete`.
+ *
+ * Types-only addition at introduction — no daemon emit sites yet. The
+ * agent loop will adopt pre-allocation in a follow-up.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const AssistantTurnStartEventSchema = z.object({
+  type: z.literal("assistant_turn_start"),
+  messageId: z.string(),
+  conversationId: z.string().optional(),
+});
+
+export type AssistantTurnStartEvent = z.infer<
+  typeof AssistantTurnStartEventSchema
+>;

package/src/api/events/avatar-updated.ts

@@ -0,0 +1,24 @@
+/**
+ * `avatar_updated` SSE event.
+ *
+ * Emitted after the avatar image has been regenerated and saved to disk.
+ * Clients bust their avatar cache; the `avatarPath` is the absolute path
+ * to the new image file, available to clients that read it directly.
+ *
+ * Global event (no `conversationId`): the avatar is per-user, not
+ * per-conversation, and the daemon fans this out across every active
+ * client of the user.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const AvatarUpdatedEventSchema = z.object({
+  type: z.literal("avatar_updated"),
+  /** Absolute path to the updated avatar image file. */
+  avatarPath: z.string(),
+});
+
+export type AvatarUpdatedEvent = z.infer<typeof AvatarUpdatedEventSchema>;

package/src/api/events/compaction-circuit-closed.ts

@@ -0,0 +1,26 @@
+/**
+ * `compaction_circuit_closed` SSE event.
+ *
+ * Emitted when the per-conversation auto-compaction circuit breaker
+ * transitions from open → closed because a successful compaction reset
+ * `ctx.compactionCircuitOpenUntil`. Clients clear the "auto-compaction
+ * paused" banner so it dismisses immediately instead of lingering until
+ * the original `openUntil` deadline.
+ *
+ * Only fires on the open → closed transition — successful compactions
+ * while the breaker was already closed would be noise.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const CompactionCircuitClosedEventSchema = z.object({
+  type: z.literal("compaction_circuit_closed"),
+  conversationId: z.string(),
+});
+
+export type CompactionCircuitClosedEvent = z.infer<
+  typeof CompactionCircuitClosedEventSchema
+>;

package/src/api/events/compaction-circuit-open.ts

@@ -0,0 +1,28 @@
+/**
+ * `compaction_circuit_open` SSE event.
+ *
+ * Emitted when the per-conversation auto-compaction circuit breaker trips
+ * (3 consecutive failures). The Swift / web client surfaces a banner
+ * indicating auto-compaction is paused until `openUntil` (ms epoch).
+ *
+ * `reason` is narrowed to the only string the daemon emits today
+ * (`"3_consecutive_failures"`). Strict by design — any future trip
+ * reason must be added here and on the daemon side together.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const CompactionCircuitOpenEventSchema = z.object({
+  type: z.literal("compaction_circuit_open"),
+  conversationId: z.string(),
+  reason: z.literal("3_consecutive_failures"),
+  /** Timestamp (ms since epoch) when the breaker will allow auto-compaction again. */
+  openUntil: z.number(),
+});
+
+export type CompactionCircuitOpenEvent = z.infer<
+  typeof CompactionCircuitOpenEventSchema
+>;

package/src/api/events/confirmation-request.ts

@@ -0,0 +1,114 @@
+/**
+ * `confirmation_request` SSE event.
+ *
+ * Server → client prompt asking the user to approve or deny a tool
+ * invocation that fell outside the auto-approve threshold. Emitted by
+ * the confirmation prompter / risk classifier when a tool call needs
+ * human review.
+ *
+ * Resolved by a paired `interaction_resolved` event (`kind:
+ * "confirmation"`, `state: "approved" | "rejected" | "cancelled" |
+ * "superseded"`) once the user decides, the daemon times out, or a
+ * newer user message supersedes the pending request.
+ *
+ * Required fields are what the prompter always supplies:
+ *  - `toolName`, `input` — what the tool will run with
+ *  - `riskLevel` — risk-classifier output, used for display only
+ *    (kept loose `string` rather than enum — risk grades evolve
+ *    independently of the wire and the client renders them as text)
+ *  - `allowlistOptions`, `scopeOptions` — radio choices the rule
+ *    editor offers when the user picks "always allow"
+ *
+ * `acpToolKind` and `acpOptions` are present only for ACP (Agent
+ * Client Protocol) permission requests forwarded from a sub-agent;
+ * `acpOptions.kind` is a strict 4-variant enum because the agent
+ * protocol mandates exactly those four shapes.
+ *
+ * `executionTarget` distinguishes sandbox vs host execution — a strict
+ * 2-variant enum because the sandbox switch is binary at the daemon
+ * level.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const AllowlistOptionSchema = z.object({
+  label: z.string(),
+  description: z.string(),
+  pattern: z.string(),
+});
+
+export type AllowlistOption = z.infer<typeof AllowlistOptionSchema>;
+
+export const ScopeOptionSchema = z.object({
+  label: z.string(),
+  scope: z.string(),
+});
+
+export type ScopeOption = z.infer<typeof ScopeOptionSchema>;
+
+export const DirectoryScopeOptionSchema = z.object({
+  label: z.string(),
+  scope: z.string(),
+});
+
+export type DirectoryScopeOption = z.infer<typeof DirectoryScopeOptionSchema>;
+
+export const ConfirmationDiffSchema = z.object({
+  filePath: z.string(),
+  oldContent: z.string(),
+  newContent: z.string(),
+  isNewFile: z.boolean(),
+});
+
+export type ConfirmationDiff = z.infer<typeof ConfirmationDiffSchema>;
+
+export const ACPOptionKindSchema = z.enum([
+  "allow_once",
+  "allow_always",
+  "reject_once",
+  "reject_always",
+]);
+
+export type ACPOptionKind = z.infer<typeof ACPOptionKindSchema>;
+
+export const ACPOptionSchema = z.object({
+  optionId: z.string(),
+  name: z.string(),
+  kind: ACPOptionKindSchema,
+});
+
+export type ACPOption = z.infer<typeof ACPOptionSchema>;
+
+export const ConfirmationExecutionTargetSchema = z.enum(["sandbox", "host"]);
+
+export type ConfirmationExecutionTarget = z.infer<
+  typeof ConfirmationExecutionTargetSchema
+>;
+
+export const ConfirmationRequestEventSchema = z.object({
+  type: z.literal("confirmation_request"),
+  requestId: z.string(),
+  toolName: z.string(),
+  input: z.record(z.string(), z.unknown()),
+  riskLevel: z.string(),
+  riskReason: z.string().optional(),
+  isContainerized: z.boolean().optional(),
+  executionTarget: ConfirmationExecutionTargetSchema.optional(),
+  allowlistOptions: z.array(AllowlistOptionSchema),
+  scopeOptions: z.array(ScopeOptionSchema),
+  directoryScopeOptions: z.array(DirectoryScopeOptionSchema).optional(),
+  diff: ConfirmationDiffSchema.optional(),
+  conversationId: z.string().optional(),
+  persistentDecisionsAllowed: z.boolean().optional(),
+  toolUseId: z.string().optional(),
+  acpToolKind: z.string().optional(),
+  acpOptions: z.array(ACPOptionSchema).optional(),
+});
+
+export type ConfirmationRequestEvent = z.infer<
+  typeof ConfirmationRequestEventSchema
+>;

package/src/api/events/contact-request.ts

@@ -0,0 +1,33 @@
+/**
+ * `contact_request` SSE event.
+ *
+ * Server → client prompt asking the user to enter a contact channel
+ * address (phone, email, etc.). Emitted by the `contacts/prompt` IPC
+ * route while a `pendingContactPrompts` entry awaits a reply.
+ *
+ * Resolved by a paired `interaction_resolved` event (`kind:
+ * "contact"`, `state: "answered" | "cancelled"`) once the user
+ * responds or the timeout fires.
+ *
+ * `channel` and `role` are advisory hints, not enforced enums — the
+ * client may render any input it likes and post back a structured
+ * contact payload.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const ContactRequestEventSchema = z.object({
+  type: z.literal("contact_request"),
+  requestId: z.string(),
+  channel: z.string().optional(),
+  placeholder: z.string().optional(),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  role: z.string().optional(),
+});
+
+export type ContactRequestEvent = z.infer<typeof ContactRequestEventSchema>;

package/src/api/events/conversation-error.ts

@@ -0,0 +1,77 @@
+/**
+ * `conversation_error` SSE event.
+ *
+ * Conversation-scoped error broadcast to every client subscribed to
+ * the stream. Unlike the turn-terminal `error` event, this carries a
+ * stable `code` enum and a `retryable` flag so the chat banner can
+ * offer source-aware recovery (e.g. naming the provider connection or
+ * profile that needs fixing).
+ *
+ * `conversationId` is required and carried on the event itself — the
+ * broadcast reaches all subscribers, so without it a breaker trip in
+ * one conversation would paint the error banner on every open chat.
+ *
+ * Canonical wire-contract source. Daemon code imports the type and the
+ * `ConversationErrorCode` enum directly from this file; external
+ * consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+/**
+ * Stable machine-readable classification for conversation-scoped
+ * errors. Drives client recovery UI (retry affordances, billing
+ * banners, connection/profile callouts). `UNKNOWN` is the catch-all
+ * for unclassified failures.
+ */
+export const ConversationErrorCodeSchema = z.enum([
+  "PROVIDER_NETWORK",
+  "PROVIDER_RATE_LIMIT",
+  "MANAGED_USAGE_LIMIT",
+  "PROVIDER_OVERLOADED",
+  "PROVIDER_API",
+  "IMAGE_TOO_LARGE",
+  "PROVIDER_BILLING",
+  "PROVIDER_ORDERING",
+  "PROVIDER_WEB_SEARCH",
+  "PROVIDER_NOT_CONFIGURED",
+  "PROVIDER_INVALID_KEY",
+  "MANAGED_KEY_INVALID",
+  "CONTEXT_TOO_LARGE",
+  "BUDGET_YIELD_UNRECOVERED",
+  "MAX_TOKENS_REACHED",
+  "CONVERSATION_ABORTED",
+  "CONVERSATION_PROCESSING_FAILED",
+  "DISK_SPACE_CRITICAL",
+  "REGENERATE_FAILED",
+  "UNKNOWN",
+]);
+
+export type ConversationErrorCode = z.infer<typeof ConversationErrorCodeSchema>;
+
+export const ConversationErrorEventSchema = z.object({
+  type: z.literal("conversation_error"),
+  conversationId: z.string(),
+  code: ConversationErrorCodeSchema,
+  userMessage: z.string(),
+  retryable: z.boolean(),
+  debugDetails: z.string().optional(),
+  errorCategory: z.string().optional(),
+  /**
+   * Name of the `provider_connections` row in play when the error
+   * occurred. Lets the chat banner point users at the connection to
+   * fix (e.g. an invalid API key). Absent when the error fires before
+   * a connection is resolved.
+   */
+  connectionName: z.string().optional(),
+  /**
+   * Name of the resolved profile (active or per-call override) in
+   * play when the error occurred. Absent when the error fires before
+   * a profile is resolved.
+   */
+  profileName: z.string().optional(),
+});
+
+export type ConversationErrorEvent = z.infer<
+  typeof ConversationErrorEventSchema
+>;