@vellumai/assistant 0.8.5 → 0.8.7

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

@@ -0,0 +1,67 @@
+/**
+ * `ui_surface_show` SSE event.
+ *
+ * Server → client request to render an ephemeral UI surface (card,
+ * form, list, table, confirmation, dynamic_page, file_upload,
+ * document_preview, task_preferences) inside the chat view. The
+ * concrete `data` shape depends on `surfaceType` and is owned by the
+ * surface-data subsystem in `daemon/message-types/surfaces.ts`; the
+ * canonical schema treats `data` as opaque on the wire so this file
+ * doesn't have to mirror eight nested-payload schemas.
+ *
+ * Lifecycle: a surface progresses `show` → (zero or more `update`s) →
+ * (`dismiss` for cancellation OR `complete` with a `summary` /
+ * `submittedData` payload). `surfaceId` is the shared correlation key
+ * across all four lifecycle events.
+ *
+ * `actions` is the array of clickable choices rendered alongside the
+ * surface. Each action's `style` is a strict 3-variant enum because
+ * the daemon-side `SurfaceAction.style` is the same enum — the wire
+ * contract is stricter than the legacy parser, which accepted any
+ * string.
+ *
+ * `persistent` defaults to false. When true, clicking an action does
+ * not dismiss the surface — the client keeps it visible and only
+ * marks the clicked action as spent (used for launcher / menu
+ * cards). The legacy web `UISurfaceShowEvent` interface was missing
+ * this field entirely — adding it via the canonical schema fixes a
+ * silent wire-shape drift.
+ *
+ * `toolCallId` is the id of the tool call that produced the surface
+ * (the `ui_show` proxy tool). The client uses it to gate display-only
+ * app previews on whether that tool call's result has arrived, rather
+ * than on whole-turn streaming state. Optional: surfaces emitted
+ * outside a tool call (or by older daemons) omit it, and the client
+ * treats a missing link as already complete.
+ *
+ * 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 SurfaceActionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  style: z.enum(["primary", "secondary", "destructive"]).optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type SurfaceAction = z.infer<typeof SurfaceActionSchema>;
+
+export const UISurfaceShowEventSchema = z.object({
+  type: z.literal("ui_surface_show"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  surfaceType: z.string(),
+  title: z.string().optional(),
+  data: z.record(z.string(), z.unknown()),
+  actions: z.array(SurfaceActionSchema).optional(),
+  display: z.enum(["inline", "panel"]).optional(),
+  messageId: z.string().optional(),
+  persistent: z.boolean().optional(),
+  toolCallId: z.string().optional(),
+});
+
+export type UISurfaceShowEvent = z.infer<typeof UISurfaceShowEventSchema>;

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

@@ -0,0 +1,26 @@
+/**
+ * `ui_surface_update` SSE event.
+ *
+ * Server → client incremental update to a previously-shown surface.
+ * Identified by the `surfaceId` returned in the original
+ * `ui_surface_show`. The client merges `data` into the rendered
+ * surface's state. `data` is opaque at the wire level for the same
+ * reason as `ui_surface_show.data` — the concrete shape depends on
+ * the surface's 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 UISurfaceUpdateEventSchema = z.object({
+  type: z.literal("ui_surface_update"),
+  conversationId: z.string(),
+  surfaceId: z.string(),
+  data: z.record(z.string(), z.unknown()),
+});
+
+export type UISurfaceUpdateEvent = z.infer<typeof UISurfaceUpdateEventSchema>;

package/src/api/events/usage-update.ts

@@ -0,0 +1,34 @@
+/**
+ * `usage_update` SSE event.
+ *
+ * Emitted after each LLM call with per-call token counts plus the
+ * conversation's running totals and estimated cost. Clients use it for
+ * live-updating usage metrics and the context-window indicator. A
+ * UI-only hint — it does not persist to the DB or affect billing.
+ *
+ * The per-call and total token counts, `estimatedCost`, and `model`
+ * are always supplied by the daemon, so they are required. The
+ * context-window fields are present only when the turn has a known
+ * context window.
+ *
+ * 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 UsageUpdateEventSchema = z.object({
+  type: z.literal("usage_update"),
+  conversationId: z.string(),
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  estimatedCost: z.number(),
+  model: z.string(),
+  contextWindowTokens: z.number().optional(),
+  contextWindowMaxTokens: z.number().optional(),
+});
+
+export type UsageUpdateEvent = z.infer<typeof UsageUpdateEventSchema>;

package/src/api/events/user-message-echo.ts

@@ -0,0 +1,35 @@
+/**
+ * `user_message_echo` SSE event.
+ *
+ * Emitted when a user message is persisted to a conversation — direct
+ * sends, slash/canned/compaction turns, and synthetic surface-action
+ * prompts. Carries the user's outbound `text` so clients that did not
+ * originate the send (passive viewers, other devices) can render the
+ * user turn, and so the originating client can dedupe its optimistic
+ * row against `messageId`/`clientMessageId`.
+ *
+ * `messageId` is absent for synthetic echoes where no distinct user row
+ * is persisted (e.g. surface-action prompts). `clientMessageId` is the
+ * client-generated correlation nonce from the HTTP POST body, echoed
+ * back so the originating client can dedupe even if the echo beats the
+ * 202 response. `requestId` correlates with `message_queued` /
+ * `message_dequeued` for the same 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 UserMessageEchoEventSchema = z
+  .object({
+    type: z.literal("user_message_echo"),
+    text: z.string(),
+    conversationId: z.string().optional(),
+    messageId: z.string().optional(),
+    requestId: z.string().optional(),
+    clientMessageId: z.string().optional(),
+  })
+  .strict();
+
+export type UserMessageEchoEvent = z.infer<typeof UserMessageEchoEventSchema>;

package/src/api/index.ts

@@ -1,4 +1,483 @@
+import { z } from "zod";
+
+import { AssistantActivityStateEventSchema } from "./events/assistant-activity-state.js";
+import { AssistantTextDeltaEventSchema } from "./events/assistant-text-delta.js";
+import { AssistantTurnStartEventSchema } from "./events/assistant-turn-start.js";
+import { AvatarUpdatedEventSchema } from "./events/avatar-updated.js";
+import { CompactionCircuitClosedEventSchema } from "./events/compaction-circuit-closed.js";
+import { CompactionCircuitOpenEventSchema } from "./events/compaction-circuit-open.js";
+import { ConfirmationRequestEventSchema } from "./events/confirmation-request.js";
+import { ContactRequestEventSchema } from "./events/contact-request.js";
+import { ConversationErrorEventSchema } from "./events/conversation-error.js";
+import { ConversationListInvalidatedEventSchema } from "./events/conversation-list-invalidated.js";
+import { ConversationTitleUpdatedEventSchema } from "./events/conversation-title-updated.js";
+import { DiskPressureStatusChangedEventSchema } from "./events/disk-pressure-status-changed.js";
+import { DocumentCommentCreatedEventSchema } from "./events/document-comment-created.js";
+import { DocumentCommentDeletedEventSchema } from "./events/document-comment-deleted.js";
+import { DocumentCommentReopenedEventSchema } from "./events/document-comment-reopened.js";
+import { DocumentCommentResolvedEventSchema } from "./events/document-comment-resolved.js";
+import { DocumentEditorUpdateEventSchema } from "./events/document-editor-update.js";
+import { ErrorEventSchema } from "./events/error.js";
+import { GenerationCancelledEventSchema } from "./events/generation-cancelled.js";
+import { GenerationHandoffEventSchema } from "./events/generation-handoff.js";
+import { HomeFeedUpdatedEventSchema } from "./events/home-feed-updated.js";
+import { IdentityChangedEventSchema } from "./events/identity-changed.js";
+import { InteractionResolvedEventSchema } from "./events/interaction-resolved.js";
+import { MessageCompleteEventSchema } from "./events/message-complete.js";
+import { MessageDequeuedEventSchema } from "./events/message-dequeued.js";
+import { MessageQueuedEventSchema } from "./events/message-queued.js";
+import { MessageQueuedDeletedEventSchema } from "./events/message-queued-deleted.js";
+import { MessageRequestCompleteEventSchema } from "./events/message-request-complete.js";
+import { NavigateSettingsEventSchema } from "./events/navigate-settings.js";
+import { NotificationIntentEventSchema } from "./events/notification-intent.js";
+import { OpenUrlEventSchema } from "./events/open-url.js";
+import { QuestionRequestEventSchema } from "./events/question-request.js";
+import { RelationshipStateUpdatedEventSchema } from "./events/relationship-state-updated.js";
+import { SecretRequestEventSchema } from "./events/secret-request.js";
+import { SubagentEventEventSchema } from "./events/subagent-event.js";
+import { SubagentSpawnedEventSchema } from "./events/subagent-spawned.js";
+import { SubagentStatusChangedEventSchema } from "./events/subagent-status-changed.js";
+import { SyncChangedEventSchema } from "./events/sync-changed.js";
+import { ToolResultEventSchema } from "./events/tool-result.js";
+import { ToolUseStartEventSchema } from "./events/tool-use-start.js";
+import { TurnProfileAutoRoutedEventSchema } from "./events/turn-profile-auto-routed.js";
+import { UISurfaceCompleteEventSchema } from "./events/ui-surface-complete.js";
+import { UISurfaceDismissEventSchema } from "./events/ui-surface-dismiss.js";
+import { UISurfaceShowEventSchema } from "./events/ui-surface-show.js";
+import { UISurfaceUpdateEventSchema } from "./events/ui-surface-update.js";
+import { UsageUpdateEventSchema } from "./events/usage-update.js";
+import { UserMessageEchoEventSchema } from "./events/user-message-echo.js";
+
+export { CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE } from "./constants/call-sites.js";
+export { DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC } from "./constants/tool-execution.js";
 export {
-  type RelationshipStateUpdated,
-  RelationshipStateUpdatedSchema,
-} from "../events/relationship-state-updated.js";
+  type AssistantActivityAnchor,
+  AssistantActivityAnchorSchema,
+  type AssistantActivityPhase,
+  AssistantActivityPhaseSchema,
+  type AssistantActivityReason,
+  AssistantActivityReasonSchema,
+  type AssistantActivityStateEvent,
+  AssistantActivityStateEventSchema,
+} from "./events/assistant-activity-state.js";
+export {
+  type AssistantOutboundAttachment,
+  AssistantOutboundAttachmentSchema,
+} from "./events/assistant-outbound-attachment.js";
+export {
+  type AssistantTextDeltaEvent,
+  AssistantTextDeltaEventSchema,
+} from "./events/assistant-text-delta.js";
+export {
+  type AssistantTurnStartEvent,
+  AssistantTurnStartEventSchema,
+} from "./events/assistant-turn-start.js";
+export {
+  type AvatarUpdatedEvent,
+  AvatarUpdatedEventSchema,
+} from "./events/avatar-updated.js";
+export {
+  type CompactionCircuitClosedEvent,
+  CompactionCircuitClosedEventSchema,
+} from "./events/compaction-circuit-closed.js";
+export {
+  type CompactionCircuitOpenEvent,
+  CompactionCircuitOpenEventSchema,
+} from "./events/compaction-circuit-open.js";
+export {
+  type ACPOption,
+  type ACPOptionKind,
+  ACPOptionKindSchema,
+  ACPOptionSchema,
+  type AllowlistOption,
+  AllowlistOptionSchema,
+  type ConfirmationDiff,
+  ConfirmationDiffSchema,
+  type ConfirmationExecutionTarget,
+  ConfirmationExecutionTargetSchema,
+  type ConfirmationRequestEvent,
+  ConfirmationRequestEventSchema,
+  type DirectoryScopeOption,
+  DirectoryScopeOptionSchema,
+  type ScopeOption,
+  ScopeOptionSchema,
+} from "./events/confirmation-request.js";
+export {
+  type ContactRequestEvent,
+  ContactRequestEventSchema,
+} from "./events/contact-request.js";
+export {
+  type ConversationErrorCode,
+  ConversationErrorCodeSchema,
+  type ConversationErrorEvent,
+  ConversationErrorEventSchema,
+} from "./events/conversation-error.js";
+export {
+  type ConversationListInvalidatedEvent,
+  ConversationListInvalidatedEventSchema,
+  type ConversationListInvalidatedReason,
+  ConversationListInvalidatedReasonSchema,
+} from "./events/conversation-list-invalidated.js";
+export {
+  type ConversationTitleUpdatedEvent,
+  ConversationTitleUpdatedEventSchema,
+} from "./events/conversation-title-updated.js";
+export {
+  type DiskPressureBlockedCapability,
+  DiskPressureBlockedCapabilitySchema,
+  type DiskPressureState,
+  DiskPressureStateSchema,
+  type DiskPressureStatus,
+  type DiskPressureStatusChangedEvent,
+  DiskPressureStatusChangedEventSchema,
+  DiskPressureStatusSchema,
+} from "./events/disk-pressure-status-changed.js";
+export {
+  type DocumentCommentCreatedEvent,
+  DocumentCommentCreatedEventSchema,
+} from "./events/document-comment-created.js";
+export {
+  type DocumentCommentDeletedEvent,
+  DocumentCommentDeletedEventSchema,
+} from "./events/document-comment-deleted.js";
+export {
+  type DocumentCommentReopenedEvent,
+  DocumentCommentReopenedEventSchema,
+} from "./events/document-comment-reopened.js";
+export {
+  type DocumentCommentResolvedEvent,
+  DocumentCommentResolvedEventSchema,
+} from "./events/document-comment-resolved.js";
+export {
+  type DocumentEditorUpdateEvent,
+  DocumentEditorUpdateEventSchema,
+} from "./events/document-editor-update.js";
+export { type ErrorEvent, ErrorEventSchema } from "./events/error.js";
+export {
+  type GenerationCancelledEvent,
+  GenerationCancelledEventSchema,
+} from "./events/generation-cancelled.js";
+export {
+  type GenerationHandoffEvent,
+  GenerationHandoffEventSchema,
+} from "./events/generation-handoff.js";
+export {
+  type HomeFeedUpdatedEvent,
+  HomeFeedUpdatedEventSchema,
+} from "./events/home-feed-updated.js";
+export {
+  type IdentityChangedEvent,
+  IdentityChangedEventSchema,
+} from "./events/identity-changed.js";
+export {
+  type InteractionResolutionState,
+  InteractionResolutionStateSchema,
+  type InteractionResolvedEvent,
+  InteractionResolvedEventSchema,
+} from "./events/interaction-resolved.js";
+export {
+  type MessageCompleteEvent,
+  MessageCompleteEventSchema,
+} from "./events/message-complete.js";
+export {
+  type MessageDequeuedEvent,
+  MessageDequeuedEventSchema,
+} from "./events/message-dequeued.js";
+export {
+  type MessageQueuedEvent,
+  MessageQueuedEventSchema,
+} from "./events/message-queued.js";
+export {
+  type MessageQueuedDeletedEvent,
+  MessageQueuedDeletedEventSchema,
+} from "./events/message-queued-deleted.js";
+export {
+  type MessageRequestCompleteEvent,
+  MessageRequestCompleteEventSchema,
+} from "./events/message-request-complete.js";
+export {
+  type NavigateSettingsEvent,
+  NavigateSettingsEventSchema,
+} from "./events/navigate-settings.js";
+export {
+  type NotificationIntentEvent,
+  NotificationIntentEventSchema,
+} from "./events/notification-intent.js";
+export { type OpenUrlEvent, OpenUrlEventSchema } from "./events/open-url.js";
+export {
+  type QuestionEntry,
+  QuestionEntrySchema,
+  type QuestionOption,
+  QuestionOptionSchema,
+  type QuestionRequestEvent,
+  QuestionRequestEventSchema,
+} from "./events/question-request.js";
+export {
+  type RelationshipStateUpdatedEvent,
+  RelationshipStateUpdatedEventSchema,
+} from "./events/relationship-state-updated.js";
+export {
+  type SecretRequestEvent,
+  SecretRequestEventSchema,
+} from "./events/secret-request.js";
+export {
+  type SubagentEventEvent,
+  SubagentEventEventSchema,
+  type SubagentInnerEvent,
+  SubagentInnerEventSchema,
+} from "./events/subagent-event.js";
+export {
+  type SubagentSpawnedEvent,
+  SubagentSpawnedEventSchema,
+} from "./events/subagent-spawned.js";
+export {
+  type SubagentStatus,
+  type SubagentStatusChangedEvent,
+  SubagentStatusChangedEventSchema,
+  SubagentStatusSchema,
+  type SubagentUsageStats,
+  SubagentUsageStatsSchema,
+} from "./events/subagent-status-changed.js";
+export {
+  type SyncChangedEvent,
+  SyncChangedEventSchema,
+} from "./events/sync-changed.js";
+export {
+  type RiskScopeOption,
+  RiskScopeOptionSchema,
+  type ToolActivityMetadata,
+  ToolActivityMetadataSchema,
+  type ToolResultEvent,
+  ToolResultEventSchema,
+  type WebFetchMetadata,
+  WebFetchMetadataSchema,
+  type WebSearchMetadata,
+  WebSearchMetadataSchema,
+  type WebSearchProviderId,
+  WebSearchProviderIdSchema,
+  type WebSearchResultItem,
+  WebSearchResultItemSchema,
+} from "./events/tool-result.js";
+export {
+  type ToolUseStartEvent,
+  ToolUseStartEventSchema,
+} from "./events/tool-use-start.js";
+export {
+  type TurnProfileAutoRoutedEvent,
+  TurnProfileAutoRoutedEventSchema,
+} from "./events/turn-profile-auto-routed.js";
+export {
+  type UISurfaceCompleteEvent,
+  UISurfaceCompleteEventSchema,
+} from "./events/ui-surface-complete.js";
+export {
+  type UISurfaceDismissEvent,
+  UISurfaceDismissEventSchema,
+} from "./events/ui-surface-dismiss.js";
+export {
+  type SurfaceAction,
+  SurfaceActionSchema,
+  type UISurfaceShowEvent,
+  UISurfaceShowEventSchema,
+} from "./events/ui-surface-show.js";
+export {
+  type UISurfaceUpdateEvent,
+  UISurfaceUpdateEventSchema,
+} from "./events/ui-surface-update.js";
+export {
+  type UsageUpdateEvent,
+  UsageUpdateEventSchema,
+} from "./events/usage-update.js";
+export {
+  type UserMessageEchoEvent,
+  UserMessageEchoEventSchema,
+} from "./events/user-message-echo.js";
+export {
+  type DictationContext,
+  DictationContextSchema,
+  type DictationRequest,
+  DictationRequestSchema,
+} from "./requests/dictation.js";
+export {
+  type DiskPressureStatusResponse,
+  DiskPressureStatusResponseSchema,
+} from "./responses/disk-pressure-status.js";
+export {
+  type Capability,
+  CapabilitySchema,
+  type CapabilityTier,
+  type ContextBanner,
+  ContextBannerSchema,
+  type Fact,
+  type FactCategory,
+  type FactConfidence,
+  FactSchema,
+  type FactSource,
+  type FeedAction,
+  FeedActionSchema,
+  type FeedItem,
+  type FeedItemCategory,
+  FeedItemCategorySchema,
+  type FeedItemDetailPanel,
+  type FeedItemDetailPanelKind,
+  FeedItemDetailPanelKindSchema,
+  FeedItemDetailPanelSchema,
+  FeedItemSchema,
+  type FeedItemStatus,
+  FeedItemStatusSchema,
+  type FeedItemType,
+  FeedItemTypeSchema,
+  type FeedItemUrgency,
+  FeedItemUrgencySchema,
+  type HomeFeedResponse,
+  HomeFeedResponseSchema,
+  type RelationshipState,
+  RelationshipStateSchema,
+  type RelationshipTier,
+  type SuggestedPrompt,
+  SuggestedPromptSchema,
+  type SuggestedPromptSource,
+  SuggestedPromptSourceSchema,
+} from "./responses/home.js";
+export {
+  type LlmContextResponse,
+  LlmContextResponseSchema,
+} from "./responses/llm-context-response.js";
+export {
+  type LLMCallSummary,
+  LLMCallSummarySchema,
+  type LLMContextSection,
+  LLMContextSectionSchema,
+  type LLMRequestLogEntry,
+  LLMRequestLogEntrySchema,
+} from "./responses/llm-request-log-entry.js";
+export {
+  type MemoryCandidate,
+  MemoryCandidateSchema,
+  type MemoryDegradation,
+  MemoryDegradationSchema,
+  type MemoryRecallLog,
+  MemoryRecallLogSchema,
+} from "./responses/memory-recall-log.js";
+export {
+  type MemoryV2ActivationLog,
+  MemoryV2ActivationLogSchema,
+  type MemoryV2ConceptRow,
+  MemoryV2ConceptRowSchema,
+  type MemoryV2ConfigSnapshot,
+  MemoryV2ConfigSnapshotSchema,
+} from "./responses/memory-v2-activation-log.js";
+export {
+  type MemoryV3SelectionLog,
+  MemoryV3SelectionLogSchema,
+  type MemoryV3SelectionRow,
+  MemoryV3SelectionRowSchema,
+} from "./responses/memory-v3-selection-log.js";
+export {
+  type SubagentDetailEvent,
+  SubagentDetailEventSchema,
+  type SubagentDetailResponse,
+  SubagentDetailResponseSchema,
+} from "./responses/subagent-detail.js";
+
+/**
+ * Canonical SSE event schema for the assistant runtime.
+ *
+ * Discriminated union over the `type` field. Each member is the
+ * canonical wire-contract schema for a single event type, defined
+ * alongside the daemon code that emits it. Consumers (web client,
+ * gateway, evals) parse incoming events with this single schema
+ * rather than maintaining their own dispatch table.
+ *
+ * Add new events by exporting their schema from `./events/` and
+ * appending them to the union below. See `./README.md` for the full
+ * migration recipe.
+ */
+export const AssistantEventSchema = z.discriminatedUnion("type", [
+  AssistantActivityStateEventSchema,
+  AssistantTextDeltaEventSchema,
+  AssistantTurnStartEventSchema,
+  AvatarUpdatedEventSchema,
+  CompactionCircuitClosedEventSchema,
+  CompactionCircuitOpenEventSchema,
+  ConfirmationRequestEventSchema,
+  ContactRequestEventSchema,
+  ConversationErrorEventSchema,
+  ConversationListInvalidatedEventSchema,
+  ConversationTitleUpdatedEventSchema,
+  DiskPressureStatusChangedEventSchema,
+  DocumentCommentCreatedEventSchema,
+  DocumentCommentDeletedEventSchema,
+  DocumentCommentReopenedEventSchema,
+  DocumentCommentResolvedEventSchema,
+  DocumentEditorUpdateEventSchema,
+  ErrorEventSchema,
+  GenerationCancelledEventSchema,
+  GenerationHandoffEventSchema,
+  HomeFeedUpdatedEventSchema,
+  IdentityChangedEventSchema,
+  InteractionResolvedEventSchema,
+  MessageCompleteEventSchema,
+  MessageDequeuedEventSchema,
+  MessageQueuedEventSchema,
+  MessageQueuedDeletedEventSchema,
+  MessageRequestCompleteEventSchema,
+  NavigateSettingsEventSchema,
+  NotificationIntentEventSchema,
+  OpenUrlEventSchema,
+  QuestionRequestEventSchema,
+  RelationshipStateUpdatedEventSchema,
+  SecretRequestEventSchema,
+  SubagentEventEventSchema,
+  SubagentSpawnedEventSchema,
+  SubagentStatusChangedEventSchema,
+  SyncChangedEventSchema,
+  ToolResultEventSchema,
+  ToolUseStartEventSchema,
+  TurnProfileAutoRoutedEventSchema,
+  UISurfaceCompleteEventSchema,
+  UISurfaceDismissEventSchema,
+  UISurfaceShowEventSchema,
+  UISurfaceUpdateEventSchema,
+  UsageUpdateEventSchema,
+  UserMessageEchoEventSchema,
+]);
+
+/**
+ * Inferred TypeScript union for every event currently covered by
+ * `AssistantEventSchema`. Consumers should reference this single type
+ * rather than re-listing the individual member types — as each new
+ * event migrates into the schema, it appears here automatically.
+ */
+export type AssistantEvent = z.infer<typeof AssistantEventSchema>;
+
+/**
+ * SSE wire envelope wrapping every outbound event from the daemon.
+ *
+ * Transport-level metadata (`id`, `seq`, `emittedAt`, `conversationId`)
+ * surrounds the semantic event payload in `message`.
+ */
+export const AssistantEventEnvelopeSchema = z.object({
+  id: z.string(),
+  conversationId: z.string().optional(),
+  seq: z.number().int().optional(),
+  /**
+   * Subscriber-filtered sequence number. Monotonic per conversation per
+   * SSE subscriber, counting only events the subscriber is eligible to
+   * receive (i.e. after capability/client/interface targeting is applied).
+   * Gap-free by construction — clients should prefer `clientSeq` over
+   * `seq` for gap detection to avoid false positives caused by targeted
+   * events (host_bash, host_cu, etc.) that increment the global `seq`
+   * but are filtered out for non-matching subscribers.
+   *
+   * Absent on older daemons that predate this field; clients fall back
+   * to `seq` when `clientSeq` is not present.
+   */
+  clientSeq: z.number().int().optional(),
+  emittedAt: z.string(),
+  message: AssistantEventSchema,
+});
+
+export type AssistantEventEnvelope = z.infer<
+  typeof AssistantEventEnvelopeSchema
+>;

package/src/api/requests/dictation.ts

@@ -0,0 +1,45 @@
+/**
+ * Wire contract for the dictation REST endpoint (`POST /dictation`).
+ *
+ * The body web/macOS sends when asking the daemon to clean up a raw voice
+ * transcript and classify it as dictation vs. action. `context` is its own
+ * named schema/type so consumers (web client) can import `DictationContext`
+ * directly instead of inferring it from the generated client.
+ *
+ * Canonical wire-contract source. Assistant code imports the types/schema
+ * directly from this file via relative paths (the daemon route sources its
+ * `requestBody` from here); external consumers (web client, gateway, evals)
+ * import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+/**
+ * Context describing where dictation was initiated (app, window, cursor
+ * state, selected text). Strip-mode passthrough: clients send the subset
+ * they have — web sends only `cursorInTextField`, macOS sends the full set —
+ * and the daemon tolerates additional fields without rejecting the request.
+ */
+export const DictationContextSchema = z
+  .object({
+    cursorInTextField: z
+      .boolean()
+      .optional()
+      .describe(
+        "Whether the cursor is in an editable text field when dictation started",
+      ),
+  })
+  .passthrough()
+  .describe(
+    "Dictation context (app name, window title, bundle ID, cursor state, selected text)",
+  );
+
+export type DictationContext = z.infer<typeof DictationContextSchema>;
+
+export const DictationRequestSchema = z.object({
+  transcription: z.string().describe("Raw speech transcription"),
+  context: DictationContextSchema,
+  profileId: z.string().describe("Optional dictation profile ID").optional(),
+});
+
+export type DictationRequest = z.infer<typeof DictationRequestSchema>;