@vellumai/assistant 0.8.6 → 0.8.7

package/src/api/README.md

@@ -30,20 +30,20 @@ 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/`. Each schema is `.strict()` so unknown
-fields surface as `UnknownEvent` rather than silently passing through.
+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(),
-    // …
-  })
-  .strict();
+export const MyEventSchema = z.object({
+  type: z.literal("my_event"),
+  conversationId: z.string(),
+  // …
+});
 
 export type MyEvent = z.infer<typeof MyEventSchema>;
 ```
@@ -61,6 +61,15 @@ 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
@@ -86,7 +95,7 @@ Add parser tests for each migrated event covering:
 - happy path with all fields
 - minimal required only
 - missing required field → `UnknownEvent`
-- strict mode rejects an unknown extra 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
@@ -118,10 +127,3 @@ bunx prettier --write <files>
 
 `format:check` is a distinct CI gate from `lint`; format the touched files
 before push.
-
-## Status
-
-The remaining legacy parser cases are tracked in the **Solve Chat SSE**
-workstream (record `282e972a` in `workspace/data/apps/workstream-command-center/records/`).
-Each batch lands as its own PR under the `API Events Canonical Schemas`
-stream.

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

@@ -18,33 +18,31 @@
 
 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(),
-  })
-  .strict();
+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

@@ -18,14 +18,12 @@
 
 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(),
-  })
-  .strict();
+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

@@ -20,13 +20,11 @@
 
 import { z } from "zod";
 
-export const AssistantTurnStartEventSchema = z
-  .object({
-    type: z.literal("assistant_turn_start"),
-    messageId: z.string(),
-    conversationId: z.string().optional(),
-  })
-  .strict();
+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
+>;

package/src/api/events/conversation-list-invalidated.ts

@@ -0,0 +1,38 @@
+/**
+ * `conversation_list_invalidated` SSE event.
+ *
+ * Tells clients their sidebar conversation list is stale and should be
+ * refetched. `reason` categorizes the underlying cause so clients can
+ * pick narrower refresh strategies if they choose.
+ *
+ * Global event (no `conversationId`): the conversation list 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 ConversationListInvalidatedReasonSchema = z.enum([
+  "created",
+  "renamed",
+  "deleted",
+  "reordered",
+  "seen_changed",
+]);
+
+export type ConversationListInvalidatedReason = z.infer<
+  typeof ConversationListInvalidatedReasonSchema
+>;
+
+export const ConversationListInvalidatedEventSchema = z.object({
+  type: z.literal("conversation_list_invalidated"),
+  /** Categorical cause of invalidation. */
+  reason: ConversationListInvalidatedReasonSchema,
+});
+
+export type ConversationListInvalidatedEvent = z.infer<
+  typeof ConversationListInvalidatedEventSchema
+>;

package/src/api/events/conversation-title-updated.ts

@@ -0,0 +1,24 @@
+/**
+ * `conversation_title_updated` SSE event.
+ *
+ * Emitted when a conversation's title changes — typically right after
+ * the auto-titling LLM pass completes, or on explicit rename. Clients
+ * update sidebar entries in-place rather than refetching the full list.
+ *
+ * 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 ConversationTitleUpdatedEventSchema = z.object({
+  type: z.literal("conversation_title_updated"),
+  /** Conversation whose title changed. */
+  conversationId: z.string(),
+  /** New title. */
+  title: z.string(),
+});
+
+export type ConversationTitleUpdatedEvent = z.infer<
+  typeof ConversationTitleUpdatedEventSchema
+>;