@vellumai/assistant 0.8.5 → 0.8.7

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

@@ -0,0 +1,28 @@
+/**
+ * `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(),
+});
+
+export type OpenUrlEvent = z.infer<typeof OpenUrlEventSchema>;

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

@@ -0,0 +1,67 @@
+/**
+ * `question_request` SSE event.
+ *
+ * Server → client prompt asking the user one or a small batch (≤5) of
+ * clarifying questions during a turn. Emitted by the question
+ * prompter when the LLM calls `ask_question` (or its batched
+ * equivalent).
+ *
+ * Resolved by a paired `interaction_resolved` event (`kind:
+ * "question"`, `state: "answered" | "cancelled" | "superseded"`) once
+ * the user submits answers, the daemon times out, or a newer user
+ * message supersedes the pending request.
+ *
+ * Wire-compat:
+ *
+ *  - `questions[]` is the canonical batched shape new clients should
+ *    consume. The whole batch is one card lifecycle on the client:
+ *    one render, one state machine, one response submission. `id` on
+ *    each entry is daemon-assigned (`q1`, `q2`, …) so the client has
+ *    a stable handle to post the user's answer against.
+ *
+ *  - The flat `question` / `description` / `options` /
+ *    `freeTextPlaceholder` fields mirror `questions[0]` for older
+ *    clients that key off the flat shape. Daemon callers that don't
+ *    supply a batch get a one-element `questions` array synthesized
+ *    from the flat fields, so both shapes are populated on every
+ *    broadcast. Once all clients consume `questions[]`, the flat
+ *    fields can be dropped (separate cleanup).
+ *
+ * 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 QuestionOptionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+});
+
+export type QuestionOption = z.infer<typeof QuestionOptionSchema>;
+
+export const QuestionEntrySchema = z.object({
+  id: z.string(),
+  question: z.string(),
+  description: z.string().optional(),
+  options: z.array(QuestionOptionSchema),
+  freeTextPlaceholder: z.string().optional(),
+});
+
+export type QuestionEntry = z.infer<typeof QuestionEntrySchema>;
+
+export const QuestionRequestEventSchema = z.object({
+  type: z.literal("question_request"),
+  requestId: z.string(),
+  questions: z.array(QuestionEntrySchema),
+  question: z.string(),
+  description: z.string().optional(),
+  options: z.array(QuestionOptionSchema),
+  freeTextPlaceholder: z.string().optional(),
+  conversationId: z.string().optional(),
+  toolUseId: z.string().optional(),
+});
+
+export type QuestionRequestEvent = z.infer<typeof QuestionRequestEventSchema>;

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

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

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

@@ -0,0 +1,42 @@
+/**
+ * `secret_request` SSE event.
+ *
+ * Server → client prompt asking the user to supply a credential value
+ * (API key, password, etc.). Emitted by the credential prompter when
+ * a tool call needs a missing secret and the daemon delegates
+ * collection to the active client.
+ *
+ * Resolved by a paired `interaction_resolved` event (`kind: "secret"`,
+ * `state: "answered" | "cancelled"`) once the client posts the secret
+ * back via the credential-store route or cancels.
+ *
+ * `service`, `field`, and `label` are required because the prompter
+ * always supplies them — they identify which credential the daemon is
+ * asking for and how to label the input. Optional fields are scope
+ * hints (`allowedTools`, `allowedDomains`), display affordances
+ * (`description`, `placeholder`), and the `allowOneTimeSend` override
+ * used by clients that support a "send without saving" path.
+ *
+ * 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 SecretRequestEventSchema = z.object({
+  type: z.literal("secret_request"),
+  requestId: z.string(),
+  service: z.string(),
+  field: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  placeholder: z.string().optional(),
+  conversationId: z.string().optional(),
+  purpose: z.string().optional(),
+  allowedTools: z.array(z.string()).optional(),
+  allowedDomains: z.array(z.string()).optional(),
+  allowOneTimeSend: z.boolean().optional(),
+});
+
+export type SecretRequestEvent = z.infer<typeof SecretRequestEventSchema>;

package/src/api/events/subagent-event.ts

@@ -0,0 +1,79 @@
+/**
+ * `subagent_event` SSE event.
+ *
+ * Server → client envelope wrapping any inner `ServerMessage`
+ * emitted by a subagent's conversation. The daemon's subagent
+ * manager rebroadcasts the subagent's own stream through the
+ * parent conversation's `sendToClient`, tagged with the subagent's
+ * id and the parent's `conversationId`. Clients use this envelope
+ * to route inner events to the appropriate inline subagent surface.
+ *
+ * The inner `event` is opaque on the wire — it is itself a fully
+ * structured `ServerMessage` (any member of the canonical event
+ * union) and re-validating it here would duplicate work and
+ * tightly couple subagent canonicalization to every other event
+ * schema. Clients re-parse `event` through the same event parser
+ * they use for top-level stream events. The canonical contract
+ * requires only that `event.type` exists.
+ *
+ * `conversationId` IS present on this event — unlike `spawned` /
+ * `status_changed`, the daemon explicitly stamps it with the
+ * parent conversation id at the envelope layer
+ * (`subagent/manager.ts: wrappedSendToClient`).
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+/**
+ * Inner event payload wrapped by `subagent_event`. Modeled as a
+ * passthrough envelope keyed on `type` plus a curated set of
+ * convenience fields that client surfaces (timeline, status badge,
+ * inline cards) read directly without re-parsing the inner event
+ * through the top-level event parser.
+ *
+ * The full canonical shape of any inner event is whatever the
+ * top-level `AssistantEventSchema` says it is for that `type`;
+ * extra fields pass through untouched. The fields below are not
+ * required by the wire contract — they are hints for downstream
+ * clients to avoid drilling into discriminated unions for common
+ * read paths.
+ */
+export const SubagentInnerEventSchema = z
+  .object({
+    type: z.string(),
+    content: z.string().optional(),
+    /** `assistant_text_delta` events carry text in `text`, not `content`. */
+    text: z.string().optional(),
+    /** `tool_result` events carry output in `result`, not `content`. */
+    result: z.string().optional(),
+    /** `tool_use_start` events carry a JSON object with tool arguments. */
+    input: z.record(z.string(), z.unknown()).optional(),
+    toolName: z.string().optional(),
+    isError: z.boolean().optional(),
+    /**
+     * Tool-use block ID for client-side correlation. Present on
+     * `tool_use_start` and `tool_result` envelopes; used to pair a
+     * result with its originating call when a subagent emits parallel
+     * calls to the same tool (e.g. two `bash` calls) which `toolName`
+     * alone cannot disambiguate.
+     */
+    toolUseId: z.string().optional(),
+  })
+  .passthrough();
+
+export type SubagentInnerEvent = z.infer<typeof SubagentInnerEventSchema>;
+
+export const SubagentEventEventSchema = z
+  .object({
+    type: z.literal("subagent_event"),
+    conversationId: z.string(),
+    subagentId: z.string(),
+    event: SubagentInnerEventSchema,
+  })
+  .strict();
+
+export type SubagentEventEvent = z.infer<typeof SubagentEventEventSchema>;

package/src/api/events/subagent-spawned.ts

@@ -0,0 +1,40 @@
+/**
+ * `subagent_spawned` SSE event.
+ *
+ * Server → client notification that a new subagent has been spawned
+ * by the parent conversation. Carries identity (`subagentId`),
+ * scoping (`parentConversationId`), human-readable display fields
+ * (`label`, `objective`), and optional spawn-context (`isFork`,
+ * `parentToolUseId` for tool-use anchoring).
+ *
+ * NOTE: no `conversationId` field. Subagent lifecycle events route
+ * to the parent conversation's SSE stream via the parent's
+ * `sendToClient` closure (`parentSendToClient`), not via the
+ * conversation-scoped seq stamping path. The parent conversation is
+ * identified explicitly by `parentConversationId`.
+ *
+ * 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 SubagentSpawnedEventSchema = z
+  .object({
+    type: z.literal("subagent_spawned"),
+    subagentId: z.string(),
+    parentConversationId: z.string(),
+    label: z.string(),
+    objective: z.string(),
+    isFork: z.boolean().optional(),
+    /**
+     * Tool-use id of the `skill_execute` call that spawned this subagent.
+     * Lets the client anchor the inline subagent card to the exact spawn
+     * tool call, independent of the (reconcile-volatile) parent message id.
+     */
+    parentToolUseId: z.string().optional(),
+  })
+  .strict();
+
+export type SubagentSpawnedEvent = z.infer<typeof SubagentSpawnedEventSchema>;

package/src/api/events/subagent-status-changed.ts

@@ -0,0 +1,65 @@
+/**
+ * `subagent_status_changed` SSE event.
+ *
+ * Server → client notification that a subagent's status has
+ * transitioned. Carries `subagentId`, the new `status`, an optional
+ * `error` message (typically present when transitioning into
+ * `failed`), and an optional rolling `usage` snapshot.
+ *
+ * NOTE: no `conversationId` field. Like `subagent_spawned`, status
+ * transitions route to the parent conversation's SSE stream via
+ * `parentSendToClient` closure, not via conversation-scoped seq
+ * stamping. The subagent is identified by `subagentId`; clients
+ * already know the parent association from the prior `spawned` event.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+/**
+ * Subagent lifecycle status. Mirrors `SubagentStatus` in
+ * `assistant/src/subagent/types.ts`. `aborted` is a terminal state
+ * reached via explicit `subagent_abort` request.
+ */
+export const SubagentStatusSchema = z.enum([
+  "pending",
+  "running",
+  "awaiting_input",
+  "completed",
+  "failed",
+  "aborted",
+]);
+
+export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
+
+/**
+ * Rolling usage snapshot for a subagent. Field names mirror the
+ * daemon's `UsageStats` interface (`shared.ts`) — in particular,
+ * `estimatedCost` is the canonical wire field, not `totalCost`.
+ */
+export const SubagentUsageStatsSchema = z
+  .object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    estimatedCost: z.number(),
+  })
+  .strict();
+
+export type SubagentUsageStats = z.infer<typeof SubagentUsageStatsSchema>;
+
+export const SubagentStatusChangedEventSchema = z
+  .object({
+    type: z.literal("subagent_status_changed"),
+    subagentId: z.string(),
+    status: SubagentStatusSchema,
+    error: z.string().optional(),
+    usage: SubagentUsageStatsSchema.optional(),
+  })
+  .strict();
+
+export type SubagentStatusChangedEvent = z.infer<
+  typeof SubagentStatusChangedEventSchema
+>;

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

@@ -0,0 +1,29 @@
+/**
+ * `sync_changed` SSE event.
+ *
+ * The generic multi-client cache-invalidation contract. The daemon
+ * broadcasts it after a persisted-state write succeeds; `tags` name
+ * which cached resources are now stale (not their new values) so each
+ * client refetches the affected endpoints. This is a global broadcast —
+ * it carries no `conversationId`.
+ *
+ * `originClientId` is the opaque identifier of the client whose mutation
+ * triggered the emission, when known. Consumers may use it to suppress
+ * self-echoes (the originating tab already applied the change
+ * optimistically). It is absent for daemon-internal emissions (agent
+ * loop, FS watcher, schedules).
+ *
+ * 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 SyncChangedEventSchema = z.object({
+  type: z.literal("sync_changed"),
+  tags: z.array(z.string().min(1)).min(1),
+  originClientId: z.string().min(1).optional(),
+});
+
+export type SyncChangedEvent = z.infer<typeof SyncChangedEventSchema>;

package/src/api/events/tool-result.ts

@@ -0,0 +1,129 @@
+/**
+ * `tool_result` SSE event.
+ *
+ * Emitted by the daemon's agent loop when a tool invocation finishes —
+ * carries the textual result, optional risk metadata for trust-rule
+ * evaluation, and correlation ids for the conversation, the message,
+ * and the tool_use block.
+ *
+ * The three risk-option arrays are distinct contracts:
+ *  - `riskAllowlistOptions` — Minimatch-glob save-path patterns; what
+ *    the rule editor's "Apply to" radio group persists as a trust
+ *    rule's `pattern`. Mirrors `ConfirmationRequestEvent.allowlistOptions`.
+ *  - `riskScopeOptions` — display-only ladder whose `pattern` is
+ *    regex-flavored and NOT a valid trust rule pattern; clients must
+ *    not feed it into the save path. Shape differs from the canonical
+ *    `ScopeOption` (`{ pattern, label }` vs `{ label, scope }`), so it
+ *    has its own schema here.
+ *  - `riskDirectoryScopeOptions` — directory scope ladder for the rule
+ *    editor modal.
+ *
+ * `activityMetadata` is structured live activity for rich client
+ * rendering (web_search / web_fetch); clients that key off `result`
+ * continue to work unchanged.
+ *
+ * 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 {
+  AllowlistOptionSchema,
+  ConfirmationDiffSchema,
+  DirectoryScopeOptionSchema,
+} from "./confirmation-request.js";
+
+export const RiskScopeOptionSchema = z.object({
+  pattern: z.string(),
+  label: z.string(),
+});
+
+export type RiskScopeOption = z.infer<typeof RiskScopeOptionSchema>;
+
+export const WebSearchProviderIdSchema = z.enum([
+  "anthropic-native",
+  "brave",
+  "perplexity",
+  "tavily",
+]);
+
+export type WebSearchProviderId = z.infer<typeof WebSearchProviderIdSchema>;
+
+export const WebSearchResultItemSchema = z.object({
+  rank: z.number(),
+  title: z.string(),
+  url: z.string(),
+  domain: z.string(),
+  faviconUrl: z.string().optional(),
+  snippet: z.string().optional(),
+  age: z.string().optional(),
+  score: z.number().optional(),
+});
+
+export type WebSearchResultItem = z.infer<typeof WebSearchResultItemSchema>;
+
+export const WebSearchMetadataSchema = z.object({
+  query: z.string(),
+  provider: WebSearchProviderIdSchema,
+  resultCount: z.number(),
+  durationMs: z.number(),
+  results: z.array(WebSearchResultItemSchema),
+  errorMessage: z.string().optional(),
+});
+
+export type WebSearchMetadata = z.infer<typeof WebSearchMetadataSchema>;
+
+export const WebFetchMetadataSchema = z.object({
+  url: z.string(),
+  finalUrl: z.string(),
+  status: z.number(),
+  contentType: z.string().optional(),
+  byteCount: z.number(),
+  charCount: z.number(),
+  truncated: z.boolean(),
+  title: z.string().optional(),
+  domain: z.string(),
+  faviconUrl: z.string().optional(),
+  redirectCount: z.number(),
+  durationMs: z.number(),
+  errorMessage: z.string().optional(),
+  mayRequireJavaScript: z.boolean().optional(),
+});
+
+export type WebFetchMetadata = z.infer<typeof WebFetchMetadataSchema>;
+
+export const ToolActivityMetadataSchema = z.object({
+  webSearch: WebSearchMetadataSchema.optional(),
+  webFetch: WebFetchMetadataSchema.optional(),
+});
+
+export type ToolActivityMetadata = z.infer<typeof ToolActivityMetadataSchema>;
+
+export const ToolResultEventSchema = z.object({
+  type: z.literal("tool_result"),
+  toolName: z.string(),
+  result: z.string(),
+  isError: z.boolean().optional(),
+  diff: ConfirmationDiffSchema.optional(),
+  status: z.string().optional(),
+  conversationId: z.string().optional(),
+  imageData: z.string().optional(),
+  imageDataList: z.array(z.string()).optional(),
+  toolUseId: z.string().optional(),
+  messageId: z.string().optional(),
+  riskLevel: z.string().optional(),
+  riskReason: z.string().optional(),
+  matchedTrustRuleId: z.string().optional(),
+  isContainerized: z.boolean().optional(),
+  riskScopeOptions: z.array(RiskScopeOptionSchema).optional(),
+  riskAllowlistOptions: z.array(AllowlistOptionSchema).optional(),
+  riskDirectoryScopeOptions: z.array(DirectoryScopeOptionSchema).optional(),
+  approvalMode: z.string().optional(),
+  approvalReason: z.string().optional(),
+  riskThreshold: z.string().optional(),
+  activityMetadata: ToolActivityMetadataSchema.optional(),
+});
+
+export type ToolResultEvent = z.infer<typeof ToolResultEventSchema>;

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

@@ -0,0 +1,30 @@
+/**
+ * `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(),
+});
+
+export type ToolUseStartEvent = z.infer<typeof ToolUseStartEventSchema>;

package/src/api/events/turn-profile-auto-routed.ts

@@ -0,0 +1,28 @@
+/**
+ * `turn_profile_auto_routed` SSE event.
+ *
+ * Emitted when the query-complexity auto-router selects a non-default
+ * inference profile for the current turn. Clients render a subtle
+ * inline notification (e.g. "Using Quality for this response"). Only
+ * fires when the router picks a profile — not when the user explicitly
+ * pinned one.
+ *
+ * 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 TurnProfileAutoRoutedEventSchema = z.object({
+  type: z.literal("turn_profile_auto_routed"),
+  conversationId: z.string(),
+  /** Profile key (e.g. "quality-optimized"). */
+  profile: z.string(),
+  /** Human-readable label (e.g. "Quality"). */
+  profileLabel: z.string(),
+});
+
+export type TurnProfileAutoRoutedEvent = z.infer<
+  typeof TurnProfileAutoRoutedEventSchema
+>;

package/src/api/events/ui-surface-complete.ts

@@ -0,0 +1,30 @@
+/**
+ * `ui_surface_complete` SSE event.
+ *
+ * Server → client signal that a surface's lifecycle has ended with a
+ * resolution — distinct from `ui_surface_dismiss`, which is used
+ * when the surface is cancelled with no result. Carries a
+ * human-readable `summary` and an optional structured
+ * `submittedData` payload (e.g. the form values the user submitted).
+ *
+ * `submittedData` is opaque on the wire — its shape depends on the
+ * original `surfaceType` and lives in the surface-data subsystem.
+ *
+ * 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 UISurfaceCompleteEventSchema = z.object({
+  type: z.literal("ui_surface_complete"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  summary: z.string(),
+  submittedData: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type UISurfaceCompleteEvent = z.infer<
+  typeof UISurfaceCompleteEventSchema
+>;

package/src/api/events/ui-surface-dismiss.ts

@@ -0,0 +1,22 @@
+/**
+ * `ui_surface_dismiss` SSE event.
+ *
+ * Server → client request to remove a previously-shown surface
+ * without a completion payload. Used when the surface is cancelled,
+ * superseded, or the daemon has determined the user input is no
+ * longer needed. Identified by `surfaceId`.
+ *
+ * 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 UISurfaceDismissEventSchema = z.object({
+  type: z.literal("ui_surface_dismiss"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+});
+
+export type UISurfaceDismissEvent = z.infer<typeof UISurfaceDismissEventSchema>;