@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

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

package/src/api/events/disk-pressure-status-changed.ts

@@ -0,0 +1,61 @@
+/**
+ * `disk_pressure_status_changed` SSE event.
+ *
+ * Global broadcast pushed when the daemon's disk-pressure snapshot
+ * changes. Mirrors the REST `GET /disk-pressure` status shape so the
+ * client's monitor can apply stream updates and polled fetches through
+ * the same code path. Carries no `conversationId` — it is workspace-wide.
+ *
+ * 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 DiskPressureStateSchema = z.enum([
+  "disabled",
+  "ok",
+  "warning",
+  "critical",
+  "unknown",
+]);
+
+export type DiskPressureState = z.infer<typeof DiskPressureStateSchema>;
+
+export const DiskPressureBlockedCapabilitySchema = z.enum([
+  "agent-turns",
+  "background-work",
+  "remote-ingress",
+]);
+
+export type DiskPressureBlockedCapability = z.infer<
+  typeof DiskPressureBlockedCapabilitySchema
+>;
+
+export const DiskPressureStatusSchema = z.object({
+  enabled: z.boolean(),
+  state: DiskPressureStateSchema,
+  locked: z.boolean(),
+  acknowledged: z.boolean(),
+  overrideActive: z.boolean(),
+  effectivelyLocked: z.boolean(),
+  lockId: z.string().nullable(),
+  usagePercent: z.number().nullable(),
+  thresholdPercent: z.number(),
+  path: z.string().nullable(),
+  lastCheckedAt: z.string().nullable(),
+  blockedCapabilities: z.array(DiskPressureBlockedCapabilitySchema),
+  error: z.string().nullable(),
+});
+
+export type DiskPressureStatus = z.infer<typeof DiskPressureStatusSchema>;
+
+export const DiskPressureStatusChangedEventSchema = z.object({
+  type: z.literal("disk_pressure_status_changed"),
+  status: DiskPressureStatusSchema,
+});
+
+export type DiskPressureStatusChangedEvent = z.infer<
+  typeof DiskPressureStatusChangedEventSchema
+>;

package/src/api/events/document-comment-created.ts

@@ -0,0 +1,44 @@
+/**
+ * `document_comment_created` SSE event.
+ *
+ * Emitted when a new comment is added to a document surface — either
+ * authored by the user or by the assistant during a tool run. Carries
+ * the full comment payload so the client can render it without a
+ * separate fetch. Subsequent lifecycle transitions (resolve / reopen /
+ * delete) reference the comment by id only.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+const DocumentCommentSchema = z.object({
+  id: z.string(),
+  surfaceId: z.string(),
+  /** Author label — typically `"user"` or `"assistant"`. Wire is permissive `string`; clients narrow at the boundary. */
+  author: z.string(),
+  content: z.string(),
+  /** Character offsets into the rendered document text when the comment is anchored to a selection. */
+  anchorStart: z.number().optional(),
+  anchorEnd: z.number().optional(),
+  /** The selected text the comment was anchored to, for resilience to document edits. */
+  anchorText: z.string().optional(),
+  /** Set when the comment is a reply in a thread. */
+  parentCommentId: z.string().optional(),
+  /** Lifecycle state — `"open"` or `"resolved"`. Wire is permissive `string`; clients narrow at the boundary. */
+  status: z.string(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+export const DocumentCommentCreatedEventSchema = z.object({
+  type: z.literal("document_comment_created"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  comment: DocumentCommentSchema,
+});
+
+export type DocumentCommentCreatedEvent = z.infer<
+  typeof DocumentCommentCreatedEventSchema
+>;

package/src/api/events/document-comment-deleted.ts

@@ -0,0 +1,22 @@
+/**
+ * `document_comment_deleted` SSE event.
+ *
+ * Emitted when a document comment is removed. The client drops the
+ * comment from local state.
+ *
+ * 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 DocumentCommentDeletedEventSchema = z.object({
+  type: z.literal("document_comment_deleted"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  commentId: z.string(),
+});
+
+export type DocumentCommentDeletedEvent = z.infer<
+  typeof DocumentCommentDeletedEventSchema
+>;

package/src/api/events/document-comment-reopened.ts

@@ -0,0 +1,23 @@
+/**
+ * `document_comment_reopened` SSE event.
+ *
+ * Emitted when a previously-resolved document comment is reopened.
+ * The client clears the comment's resolved state and transitions it
+ * back to `"open"`.
+ *
+ * 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 DocumentCommentReopenedEventSchema = z.object({
+  type: z.literal("document_comment_reopened"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  commentId: z.string(),
+});
+
+export type DocumentCommentReopenedEvent = z.infer<
+  typeof DocumentCommentReopenedEventSchema
+>;

package/src/api/events/document-comment-resolved.ts

@@ -0,0 +1,25 @@
+/**
+ * `document_comment_resolved` SSE event.
+ *
+ * Emitted when an existing document comment is marked resolved. The
+ * client transitions the comment's status to `"resolved"` and stamps
+ * `resolvedBy` from the wire value.
+ *
+ * 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 DocumentCommentResolvedEventSchema = z.object({
+  type: z.literal("document_comment_resolved"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  commentId: z.string(),
+  /** User or actor label that resolved the comment. */
+  resolvedBy: z.string(),
+});
+
+export type DocumentCommentResolvedEvent = z.infer<
+  typeof DocumentCommentResolvedEventSchema
+>;

package/src/api/events/document-editor-update.ts

@@ -0,0 +1,27 @@
+/**
+ * `document_editor_update` SSE event.
+ *
+ * Emitted by the document tool to push new markdown into the client's
+ * built-in rich-text editor for an open document surface. Used in place
+ * of `document_editor_show` when the surface is already open, so the
+ * client replaces content in place instead of reopening (which would
+ * clobber unsaved edits).
+ *
+ * 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 DocumentEditorUpdateEventSchema = z.object({
+  type: z.literal("document_editor_update"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  markdown: z.string(),
+  mode: z.string(),
+});
+
+export type DocumentEditorUpdateEvent = z.infer<
+  typeof DocumentEditorUpdateEventSchema
+>;

package/src/api/events/error.ts

@@ -0,0 +1,32 @@
+/**
+ * `error` SSE event.
+ *
+ * Terminal error for an assistant turn — emitted when generation fails
+ * before a `message_complete`. Carries a human-readable `message` plus
+ * optional machine-readable classification (`code`, `errorCategory`)
+ * the client uses to pick contextual recovery UI, and `requestId` /
+ * `conversationId` correlation ids.
+ *
+ * `message` is required: the daemon's emit sites always populate it.
+ * `category` is a coarse contextual hint (e.g. `secret_blocked` →
+ * "Send Anyway"); `errorCategory` is the finer machine-readable
+ * classification used by billing/credit recovery banners.
+ *
+ * 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 ErrorEventSchema = z.object({
+  type: z.literal("error"),
+  message: z.string(),
+  code: z.string().optional(),
+  category: z.string().optional(),
+  errorCategory: z.string().optional(),
+  requestId: z.string().optional(),
+  conversationId: z.string().optional(),
+});
+
+export type ErrorEvent = z.infer<typeof ErrorEventSchema>;

package/src/api/events/generation-cancelled.ts

@@ -0,0 +1,22 @@
+/**
+ * `generation_cancelled` SSE event.
+ *
+ * Emitted when an assistant turn is cancelled before completion —
+ * user-initiated abort, queue-drain interruption, or daemon-side
+ * lifecycle exit. Terminal event for the turn: no further deltas or
+ * `message_complete` follow.
+ *
+ * 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 GenerationCancelledEventSchema = z.object({
+  type: z.literal("generation_cancelled"),
+  conversationId: z.string().optional(),
+});
+
+export type GenerationCancelledEvent = z.infer<
+  typeof GenerationCancelledEventSchema
+>;

package/src/api/events/generation-handoff.ts

@@ -0,0 +1,39 @@
+/**
+ * `generation_handoff` SSE event.
+ *
+ * Emitted when an assistant turn finishes and the daemon's agent loop
+ * yields control to the next queued user message in the same
+ * conversation. Functionally similar to `message_complete` — same
+ * attachment payload, same `messageId` semantics — but tells the
+ * client that another turn is about to begin without an intervening
+ * idle state, so the UI can keep the activity indicator on.
+ *
+ * `queuedCount` is the depth of the conversation's pending-message
+ * queue at handoff time (not including the just-finished turn). Used
+ * by the client to size queued-message UI affordances.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import { AssistantOutboundAttachmentSchema } from "./assistant-outbound-attachment.js";
+
+export const GenerationHandoffEventSchema = z.object({
+  type: z.literal("generation_handoff"),
+  conversationId: z.string().optional(),
+  /** Daemon request id of the just-finished turn — correlates with
+   *  the request id surfaced by the inbound user message. */
+  requestId: z.string().optional(),
+  /** Depth of the pending-message queue at handoff time. */
+  queuedCount: z.number(),
+  /** Database row id of the just-finished assistant turn. */
+  messageId: z.string().optional(),
+  attachments: z.array(AssistantOutboundAttachmentSchema).optional(),
+  attachmentWarnings: z.array(z.string()).optional(),
+});
+
+export type GenerationHandoffEvent = z.infer<
+  typeof GenerationHandoffEventSchema
+>;

package/src/api/events/home-feed-updated.ts

@@ -0,0 +1,26 @@
+/**
+ * `home_feed_updated` SSE event.
+ *
+ * Emitted after a successful write to the home feed journal — clients
+ * invalidate their cached feed view and refetch. Skipped when the
+ * underlying write fails.
+ *
+ * Global event (no `conversationId`): the home feed 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 HomeFeedUpdatedEventSchema = z.object({
+  type: z.literal("home_feed_updated"),
+  /** ISO-8601 timestamp of when the feed was written. */
+  updatedAt: z.string(),
+  /** Count of items with `status === "new"` after this write. */
+  newItemCount: z.number(),
+});
+
+export type HomeFeedUpdatedEvent = z.infer<typeof HomeFeedUpdatedEventSchema>;

package/src/api/events/identity-changed.ts

@@ -0,0 +1,32 @@
+/**
+ * `identity_changed` SSE event.
+ *
+ * Broadcast when `IDENTITY.md` changes on disk. Clients refresh their cached
+ * identity view; the fields here are the new authoritative identity, so a
+ * client could apply them directly without a follow-up GET.
+ *
+ * Global event (no `conversationId`): identity 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 IdentityChangedEventSchema = z.object({
+  type: z.literal("identity_changed"),
+  /** Updated assistant name. */
+  name: z.string(),
+  /** Updated role / job description. */
+  role: z.string(),
+  /** Updated personality description. */
+  personality: z.string(),
+  /** Updated emoji glyph. */
+  emoji: z.string(),
+  /** Updated home / origin description. */
+  home: z.string(),
+});
+
+export type IdentityChangedEvent = z.infer<typeof IdentityChangedEventSchema>;

package/src/api/events/interaction-resolved.ts

@@ -0,0 +1,50 @@
+/**
+ * `interaction_resolved` SSE event.
+ *
+ * Broadcast when a pending interaction (confirmation, secret, question,
+ * host-proxy request) transitions to a resolved state. Clients use this
+ * to drop attention / processing indicators without polling.
+ *
+ * `state` is the lifecycle outcome:
+ *  - `approved` / `rejected` — user-facing confirmation outcome
+ *  - `answered` — question / secret responded to
+ *  - `cancelled` — runtime-side termination (timeout, abort, dispose,
+ *    prompter shutdown)
+ *  - `superseded` — invalidated by a newer event (auto-deny on enqueue,
+ *    fresh user message arriving while a confirmation was outstanding).
+ *
+ * `kind` is the interaction category (`"confirmation"`, `"secret"`,
+ * `"question"`, `"host_bash"`, …) — kept loose (`string`) on the wire
+ * because the daemon emits it directly from the pending-interaction
+ * map without enum narrowing. Web-side narrowing happens at the
+ * attention-tracking allowlist boundary.
+ *
+ * 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 InteractionResolutionStateSchema = z.enum([
+  "approved",
+  "rejected",
+  "answered",
+  "cancelled",
+  "superseded",
+]);
+
+export type InteractionResolutionState = z.infer<
+  typeof InteractionResolutionStateSchema
+>;
+
+export const InteractionResolvedEventSchema = z.object({
+  type: z.literal("interaction_resolved"),
+  requestId: z.string(),
+  conversationId: z.string(),
+  state: InteractionResolutionStateSchema,
+  kind: z.string(),
+});
+
+export type InteractionResolvedEvent = z.infer<
+  typeof InteractionResolvedEventSchema
+>;

package/src/api/events/message-complete.ts

@@ -0,0 +1,40 @@
+/**
+ * `message_complete` SSE event.
+ *
+ * Marks the end of an assistant turn — emitted once per turn after the
+ * final `assistant_text_delta` (or as the sole turn event for canned
+ * one-shot messages, recording-handler echoes, slash-command outputs,
+ * and aux notifier injections that don't stream text). Clients gate
+ * task-completion side effects on this event.
+ *
+ * `messageId` is the database row id of the completed assistant turn;
+ * shared with the `assistant_text_delta` chunks that streamed it. May
+ * be absent on synthetic completions that don't bind to a persisted
+ * row.
+ *
+ * `source` distinguishes a real main-turn completion from auxiliary
+ * notifier injections (call transcripts, call summaries, watch
+ * notifier outputs). Clients gate the task-complete sound and similar
+ * side effects on `source !== "aux"`. Absent is treated as `"main"`
+ * for backwards compatibility.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import { AssistantOutboundAttachmentSchema } from "./assistant-outbound-attachment.js";
+
+export const MessageCompleteEventSchema = z.object({
+  type: z.literal("message_complete"),
+  messageId: z.string().optional(),
+  conversationId: z.string().optional(),
+  source: z.enum(["main", "aux"]).optional(),
+  attachments: z.array(AssistantOutboundAttachmentSchema).optional(),
+  /** Soft warnings produced while resolving attachments (e.g. format
+   *  conversions, size truncations). Display-only — not blocking. */
+  attachmentWarnings: z.array(z.string()).optional(),
+});
+
+export type MessageCompleteEvent = z.infer<typeof MessageCompleteEventSchema>;

package/src/api/events/message-dequeued.ts

@@ -0,0 +1,21 @@
+/**
+ * `message_dequeued` SSE event.
+ *
+ * Emitted when a previously-queued user message is removed from the
+ * per-conversation request queue because the runtime is about to start
+ * a turn for it. Pairs with the prior `message_queued` for the same
+ * `requestId`. Clients clear the pending indicator.
+ *
+ * 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 MessageDequeuedEventSchema = z.object({
+  type: z.literal("message_dequeued"),
+  conversationId: z.string(),
+  requestId: z.string(),
+});
+
+export type MessageDequeuedEvent = z.infer<typeof MessageDequeuedEventSchema>;

package/src/api/events/message-queued-deleted.ts

@@ -0,0 +1,23 @@
+/**
+ * `message_queued_deleted` SSE event.
+ *
+ * Emitted when a queued user message is discarded before it ever runs
+ * (e.g. the user cancels it from the queue UI). Clients drop the
+ * pending indicator for `requestId`. Distinct from `message_dequeued`,
+ * which signals normal promotion into a running turn.
+ *
+ * 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 MessageQueuedDeletedEventSchema = z.object({
+  type: z.literal("message_queued_deleted"),
+  conversationId: z.string(),
+  requestId: z.string(),
+});
+
+export type MessageQueuedDeletedEvent = z.infer<
+  typeof MessageQueuedDeletedEventSchema
+>;

package/src/api/events/message-queued.ts

@@ -0,0 +1,22 @@
+/**
+ * `message_queued` SSE event.
+ *
+ * Emitted when a user message is accepted while an assistant turn is
+ * still streaming, and the runtime holds it in the per-conversation
+ * request queue rather than starting a new turn. Clients render a
+ * pending indicator and use `position` to order multiple queued items.
+ *
+ * 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 MessageQueuedEventSchema = z.object({
+  type: z.literal("message_queued"),
+  conversationId: z.string(),
+  requestId: z.string(),
+  position: z.number(),
+});
+
+export type MessageQueuedEvent = z.infer<typeof MessageQueuedEventSchema>;