@vellumai/assistant 0.8.5 → 0.8.6

package/src/api/README.md

@@ -1,5 +1,127 @@
 # @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/`. Each schema is `.strict()` so unknown
+fields surface as `UnknownEvent` rather than silently passing through.
+
+```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 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.
+
+### 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`
+- strict mode rejects an unknown extra field → `UnknownEvent`
+
+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.
+
+## 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/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/events/assistant-outbound-attachment.ts

@@ -0,0 +1,51 @@
+/**
+ * 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(),
+  })
+  .strict();
+
+export type AssistantOutboundAttachment = z.infer<
+  typeof AssistantOutboundAttachmentSchema
+>;

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

@@ -0,0 +1,32 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type AssistantTextDeltaEvent = z.infer<
+  typeof AssistantTextDeltaEventSchema
+>;

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

@@ -0,0 +1,33 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type AssistantTurnStartEvent = z.infer<
+  typeof AssistantTurnStartEventSchema
+>;

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

@@ -0,0 +1,48 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export const DocumentCommentCreatedEventSchema = z
+  .object({
+    type: z.literal("document_comment_created"),
+    conversationId: z.string(),
+    surfaceId: z.string(),
+    comment: DocumentCommentSchema,
+  })
+  .strict();
+
+export type DocumentCommentCreatedEvent = z.infer<
+  typeof DocumentCommentCreatedEventSchema
+>;

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

@@ -0,0 +1,24 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type DocumentCommentDeletedEvent = z.infer<
+  typeof DocumentCommentDeletedEventSchema
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type DocumentCommentReopenedEvent = z.infer<
+  typeof DocumentCommentReopenedEventSchema
+>;

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

@@ -0,0 +1,27 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type DocumentCommentResolvedEvent = z.infer<
+  typeof DocumentCommentResolvedEventSchema
+>;

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

@@ -0,0 +1,24 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type GenerationCancelledEvent = z.infer<
+  typeof GenerationCancelledEventSchema
+>;

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

@@ -0,0 +1,41 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type GenerationHandoffEvent = z.infer<
+  typeof GenerationHandoffEventSchema
+>;

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

@@ -0,0 +1,42 @@
+/**
+ * `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(),
+  })
+  .strict();
+
+export type MessageCompleteEvent = z.infer<typeof MessageCompleteEventSchema>;

package/src/api/events/open-url.ts

@@ -0,0 +1,30 @@
+/**
+ * `open_url` SSE event.
+ *
+ * Sent by the assistant when it wants the client to open a URL — OAuth
+ * authorization popups, system-settings deep links, and browser hand-offs
+ * from tool execution. The web client routes the URL through same-origin
+ * detection, an OAuth popup, or `window.open`, depending on the URL shape.
+ *
+ * Canonical wire-contract source. Assistant code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ *
+ * `conversationId` is optional: emit sites with a conversation context
+ * (OAuth orchestrator, conversation-scoped tools) should set it on the
+ * inner message; CLI signal-file broadcasts and other global flows omit
+ * it. The parser never grafts the envelope-level routing key onto the
+ * typed event — the schema is the contract.
+ */
+
+import { z } from "zod";
+
+export const OpenUrlEventSchema = z
+  .object({
+    type: z.literal("open_url"),
+    url: z.string().min(1),
+    title: z.string().optional(),
+    conversationId: z.string().optional(),
+  })
+  .strict();
+
+export type OpenUrlEvent = z.infer<typeof OpenUrlEventSchema>;

package/src/{events → api/events}/relationship-state-updated.ts

@@ -13,13 +13,13 @@
 
 import { z } from "zod";
 
-export const RelationshipStateUpdatedSchema = z
+export const RelationshipStateUpdatedEventSchema = z
   .object({
     type: z.literal("relationship_state_updated"),
     updatedAt: z.string(),
   })
   .strict();
 
-export type RelationshipStateUpdated = z.infer<
-  typeof RelationshipStateUpdatedSchema
+export type RelationshipStateUpdatedEvent = z.infer<
+  typeof RelationshipStateUpdatedEventSchema
 >;

package/src/api/events/tool-use-start.ts

@@ -0,0 +1,32 @@
+/**
+ * `tool_use_start` SSE event.
+ *
+ * Emitted by the daemon's agent loop when a tool invocation begins —
+ * carries the tool name, the structured input the model produced, and
+ * correlation ids for the conversation, the message, and the tool_use
+ * block itself.
+ *
+ * `messageId` is the database row id of the assistant message that owns
+ * this tool_use block; absent on streams produced by older daemons that
+ * pre-date the anchor protocol. Same semantics as
+ * `AssistantTextDeltaEvent.messageId`.
+ *
+ * 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 ToolUseStartEventSchema = z
+  .object({
+    type: z.literal("tool_use_start"),
+    toolName: z.string(),
+    input: z.record(z.string(), z.unknown()),
+    toolUseId: z.string().optional(),
+    messageId: z.string().optional(),
+    conversationId: z.string().optional(),
+  })
+  .strict();
+
+export type ToolUseStartEvent = z.infer<typeof ToolUseStartEventSchema>;