@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -0,0 +1,33 @@
+/**
+ * `assistant_thinking_delta` SSE event.
+ *
+ * Streaming reasoning chunk emitted by the daemon as a reasoning-capable
+ * model produces its chain of thought. Multiple deltas accumulate into a
+ * single assistant message's thinking block, interleaved with
+ * `assistant_text_delta` and tool events in emission order; the matching
+ * `message_complete` event marks the turn done.
+ *
+ * `messageId` is the database row id of the assistant message this
+ * delta belongs to — same semantics as `AssistantTextDeltaEvent.messageId`.
+ * Absent on streams produced by older daemons that pre-date the anchor
+ * protocol.
+ *
+ * Only emitted when thinking streaming is enabled for the turn; turns that
+ * suppress reasoning output produce none.
+ *
+ * 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 AssistantThinkingDeltaEventSchema = z.object({
+  type: z.literal("assistant_thinking_delta"),
+  thinking: z.string(),
+  messageId: z.string().optional(),
+  conversationId: z.string().optional(),
+});
+
+export type AssistantThinkingDeltaEvent = z.infer<
+  typeof AssistantThinkingDeltaEventSchema
+>;

package/src/api/events/tool-output-chunk.ts

@@ -0,0 +1,45 @@
+/**
+ * `tool_output_chunk` SSE event.
+ *
+ * Streamed by the daemon's agent loop while a tool runs, carrying
+ * incremental output (e.g. a bash command's stdout). The `subType` and
+ * `subTool*` fields describe nested sub-tool activity for tools that
+ * themselves orchestrate other tools, so clients can render sub-steps
+ * within the parent tool's output.
+ *
+ * `messageId` is the database row id of the assistant message that owns
+ * the parent 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 ToolOutputChunkSubTypeSchema = z.enum([
+  "tool_start",
+  "tool_complete",
+  "status",
+]);
+
+export type ToolOutputChunkSubType = z.infer<
+  typeof ToolOutputChunkSubTypeSchema
+>;
+
+export const ToolOutputChunkEventSchema = z.object({
+  type: z.literal("tool_output_chunk"),
+  chunk: z.string(),
+  conversationId: z.string().optional(),
+  toolUseId: z.string().optional(),
+  subType: ToolOutputChunkSubTypeSchema.optional(),
+  subToolName: z.string().optional(),
+  subToolInput: z.string().optional(),
+  subToolIsError: z.boolean().optional(),
+  subToolId: z.string().optional(),
+  messageId: z.string().optional(),
+});
+
+export type ToolOutputChunkEvent = z.infer<typeof ToolOutputChunkEventSchema>;

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

@@ -0,0 +1,32 @@
+/**
+ * `tool_use_preview_start` SSE event.
+ *
+ * Emitted by the daemon's agent loop the moment a tool_use block is
+ * recognized in the model stream, before its input has finished
+ * streaming. Clients use it to render a tool affordance optimistically;
+ * the structured input arrives later via `tool_input_delta` and the
+ * invocation proper via `tool_use_start`.
+ *
+ * `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 ToolUsePreviewStartEventSchema = z.object({
+  type: z.literal("tool_use_preview_start"),
+  toolUseId: z.string(),
+  toolName: z.string(),
+  conversationId: z.string().optional(),
+  messageId: z.string().optional(),
+});
+
+export type ToolUsePreviewStartEvent = z.infer<
+  typeof ToolUsePreviewStartEventSchema
+>;

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

@@ -0,0 +1,69 @@
+/**
+ * `trace_event` SSE event.
+ *
+ * Diagnostic timeline event emitted by the daemon's `TraceEmitter` as a
+ * request moves through its lifecycle (received, queued, LLM calls, tool
+ * invocations, completion). Each event carries a monotonic per-conversation
+ * `sequence` so clients can reconstruct order even when timestamps collide,
+ * plus optional structured `attributes` (e.g. token counts, latency, tool
+ * name). The daemon normalizes every attribute value to a primitive, so the
+ * value type is the `string | number | boolean | null` union below.
+ *
+ * `kind` and `status` are strict enums because the daemon emits a fixed,
+ * known set and clients switch on them (icons, metrics, group status).
+ *
+ * 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 TraceEventKindSchema = z.enum([
+  "request_received",
+  "request_queued",
+  "request_dequeued",
+  "llm_call_started",
+  "llm_call_finished",
+  "assistant_message",
+  "tool_started",
+  "tool_permission_requested",
+  "tool_permission_decided",
+  "tool_finished",
+  "tool_failed",
+  "generation_handoff",
+  "message_complete",
+  "generation_cancelled",
+  "request_error",
+  "tool_profiling_summary",
+]);
+
+export type TraceEventKind = z.infer<typeof TraceEventKindSchema>;
+
+export const TraceEventStatusSchema = z.enum([
+  "info",
+  "success",
+  "warning",
+  "error",
+]);
+
+export type TraceEventStatus = z.infer<typeof TraceEventStatusSchema>;
+
+export const TraceEventSchema = z.object({
+  type: z.literal("trace_event"),
+  eventId: z.string(),
+  conversationId: z.string(),
+  requestId: z.string().optional(),
+  timestampMs: z.number(),
+  sequence: z.number(),
+  kind: TraceEventKindSchema,
+  status: TraceEventStatusSchema.optional(),
+  summary: z.string(),
+  attributes: z
+    .record(
+      z.string(),
+      z.union([z.string(), z.number(), z.boolean(), z.null()]),
+    )
+    .optional(),
+});
+
+export type TraceEvent = z.infer<typeof TraceEventSchema>;

package/src/api/index.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import { AssistantActivityStateEventSchema } from "./events/assistant-activity-state.js";
 import { AssistantTextDeltaEventSchema } from "./events/assistant-text-delta.js";
+import { AssistantThinkingDeltaEventSchema } from "./events/assistant-thinking-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";
@@ -38,8 +39,11 @@ 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 { ToolOutputChunkEventSchema } from "./events/tool-output-chunk.js";
 import { ToolResultEventSchema } from "./events/tool-result.js";
+import { ToolUsePreviewStartEventSchema } from "./events/tool-use-preview-start.js";
 import { ToolUseStartEventSchema } from "./events/tool-use-start.js";
+import { TraceEventSchema } from "./events/trace-event.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";
@@ -68,6 +72,10 @@ export {
   type AssistantTextDeltaEvent,
   AssistantTextDeltaEventSchema,
 } from "./events/assistant-text-delta.js";
+export {
+  type AssistantThinkingDeltaEvent,
+  AssistantThinkingDeltaEventSchema,
+} from "./events/assistant-thinking-delta.js";
 export {
   type AssistantTurnStartEvent,
   AssistantTurnStartEventSchema,
@@ -242,6 +250,12 @@ export {
   type SyncChangedEvent,
   SyncChangedEventSchema,
 } from "./events/sync-changed.js";
+export {
+  type ToolOutputChunkEvent,
+  ToolOutputChunkEventSchema,
+  type ToolOutputChunkSubType,
+  ToolOutputChunkSubTypeSchema,
+} from "./events/tool-output-chunk.js";
 export {
   type RiskScopeOption,
   RiskScopeOptionSchema,
@@ -258,10 +272,22 @@ export {
   type WebSearchResultItem,
   WebSearchResultItemSchema,
 } from "./events/tool-result.js";
+export {
+  type ToolUsePreviewStartEvent,
+  ToolUsePreviewStartEventSchema,
+} from "./events/tool-use-preview-start.js";
 export {
   type ToolUseStartEvent,
   ToolUseStartEventSchema,
 } from "./events/tool-use-start.js";
+export {
+  type TraceEvent,
+  type TraceEventKind,
+  TraceEventKindSchema,
+  TraceEventSchema,
+  type TraceEventStatus,
+  TraceEventStatusSchema,
+} from "./events/trace-event.js";
 export {
   type TurnProfileAutoRoutedEvent,
   TurnProfileAutoRoutedEventSchema,
@@ -298,6 +324,24 @@ export {
   type DictationRequest,
   DictationRequestSchema,
 } from "./requests/dictation.js";
+export {
+  type ConversationContentBlock,
+  ConversationContentBlockSchema,
+  type ConversationMessage,
+  type ConversationMessageAttachment,
+  ConversationMessageAttachmentSchema,
+  ConversationMessageSchema,
+  type ConversationMessageSurface,
+  ConversationMessageSurfaceSchema,
+  type ConversationMessageToolCall,
+  ConversationMessageToolCallSchema,
+  type ConversationSlackMessage,
+  ConversationSlackMessageSchema,
+  type ConversationSubagentNotification,
+  ConversationSubagentNotificationSchema,
+  type PendingToolConfirmation,
+  PendingToolConfirmationSchema,
+} from "./responses/conversation-message.js";
 export {
   type DiskPressureStatusResponse,
   DiskPressureStatusResponseSchema,
@@ -396,6 +440,7 @@ export {
 export const AssistantEventSchema = z.discriminatedUnion("type", [
   AssistantActivityStateEventSchema,
   AssistantTextDeltaEventSchema,
+  AssistantThinkingDeltaEventSchema,
   AssistantTurnStartEventSchema,
   AvatarUpdatedEventSchema,
   CompactionCircuitClosedEventSchema,
@@ -432,8 +477,11 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   SubagentSpawnedEventSchema,
   SubagentStatusChangedEventSchema,
   SyncChangedEventSchema,
+  ToolOutputChunkEventSchema,
   ToolResultEventSchema,
+  ToolUsePreviewStartEventSchema,
   ToolUseStartEventSchema,
+  TraceEventSchema,
   TurnProfileAutoRoutedEventSchema,
   UISurfaceCompleteEventSchema,
   UISurfaceDismissEventSchema,
@@ -461,19 +509,6 @@ 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,
 });

package/src/api/responses/conversation-message.ts

@@ -0,0 +1,368 @@
+/**
+ * Wire contract for the conversation history / messages endpoints.
+ *
+ *   - `GET /v1/assistants/:id/messages` → `{ messages: ConversationMessage[] }`
+ *   - `POST /v1/messages` send acks echo an `assistantMessage: ConversationMessage`
+ *
+ * Holds the canonical history-row shape produced by the daemon's
+ * `renderHistoryContent` + conversation-routes serializer and consumed by
+ * every history client (web, CLI, evals). Defining it here — rather than
+ * re-declaring it in the daemon's `http-types.ts` and again in the web's
+ * `chat/api/messages.ts` — means the producer and all consumers derive from
+ * one source and cannot drift.
+ *
+ * The arrays use a positional encoding:
+ *   - `contentOrder` entries are `"<type>:<index>"` strings (e.g. `"text:0"`,
+ *     `"thinking:1"`, `"tool:0"`, `"surface:0"`, `"attachment:0"`). The index
+ *     points into the matching array below.
+ *   - `textSegments`, `thinkingSegments` are plain string arrays.
+ *   - `toolCalls`, `surfaces`, `attachments` are object arrays.
+ *
+ * Canonical wire-contract source. Assistant code imports the types directly
+ * from this file via relative paths; external consumers (web client,
+ * gateway, evals) import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import {
+  AllowlistOptionSchema,
+  DirectoryScopeOptionSchema,
+  ScopeOptionSchema,
+} from "../events/confirmation-request.js";
+import { ToolActivityMetadataSchema } from "../events/tool-result.js";
+
+// ---------------------------------------------------------------------------
+// Attachment metadata
+// ---------------------------------------------------------------------------
+
+/** Structured attachment metadata attached to a history row. */
+export const ConversationMessageAttachmentSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  sizeBytes: z.number(),
+  kind: z.string(),
+  /** Base64-encoded file data. Only populated for images on history reload. */
+  data: z.string().optional(),
+  /** Base64-encoded thumbnail, when one was generated. */
+  thumbnailData: z.string().optional(),
+  /** True when the attachment bytes are backed by a file on disk. */
+  fileBacked: z.boolean().optional(),
+});
+export type ConversationMessageAttachment = z.infer<
+  typeof ConversationMessageAttachmentSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Tool call
+// ---------------------------------------------------------------------------
+
+const RiskScopeOptionSchema = z.object({
+  pattern: z.string(),
+  label: z.string(),
+});
+
+const RiskAllowlistOptionSchema = z.object({
+  label: z.string(),
+  description: z.string(),
+  pattern: z.string(),
+});
+
+const RiskDirectoryScopeOptionSchema = z.object({
+  scope: z.string(),
+  label: z.string(),
+});
+
+/**
+ * In-flight permission prompt awaiting a user decision, mirrored onto a
+ * history tool call so a cold reconnect (or a conversation reopened after the
+ * event-buffer window has elapsed) can restore the inline confirmation card
+ * without replaying the live `confirmation_request` SSE event.
+ *
+ * The daemon stamps this at render time by consulting the in-memory
+ * `pending-interactions` registry (the authoritative store of unresolved
+ * prompts) — it is not persisted to the database, so it appears only while the
+ * prompt is genuinely outstanding and disappears once the interaction
+ * resolves. The shape mirrors the `confirmation_request` event the live path
+ * delivers, so both paths hydrate the same client state.
+ */
+export const PendingToolConfirmationSchema = z.object({
+  requestId: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  toolName: z.string().optional(),
+  riskLevel: z.string().optional(),
+  riskReason: z.string().optional(),
+  input: z.record(z.string(), z.unknown()).optional(),
+  allowlistOptions: z.array(AllowlistOptionSchema).optional(),
+  scopeOptions: z.array(ScopeOptionSchema).optional(),
+  directoryScopeOptions: z.array(DirectoryScopeOptionSchema).optional(),
+  persistentDecisionsAllowed: z.boolean().optional(),
+});
+export type PendingToolConfirmation = z.infer<
+  typeof PendingToolConfirmationSchema
+>;
+
+/**
+ * Closed set of confirmation outcomes recorded for a tool call. The daemon
+ * only ever persists one of these three values (the outcome map is gated to
+ * them in `conversation-agent-loop.ts`), so the wire carries the closed enum
+ * rather than a free string and clients consume it without re-narrowing.
+ */
+export const ConfirmationDecisionSchema = z.enum([
+  "approved",
+  "denied",
+  "timed_out",
+]);
+export type ConfirmationDecision = z.infer<typeof ConfirmationDecisionSchema>;
+
+/**
+ * A single tool call rendered into a history row. Mirrors the object the
+ * daemon's `renderHistoryContent` emits; `contentOrder` references it as
+ * `tool:N` where `N` indexes into `toolCalls`.
+ */
+export const ConversationMessageToolCallSchema = z.object({
+  /** Stable tool-call id: the provider `tool_use` id, or a synthesized positional id. Guaranteed present as of daemon v0.8.8; optional for skew with older daemons. */
+  id: z.string().optional(),
+  name: z.string(),
+  input: z.record(z.string(), z.unknown()),
+  result: z.string().optional(),
+  isError: z.boolean().optional(),
+  /** Base64-encoded image data from tool contentBlocks. @deprecated Use imageDataList. */
+  imageData: z.string().optional(),
+  /** Base64-encoded image data from tool contentBlocks (e.g. browser_screenshot, image generation). */
+  imageDataList: z.array(z.string()).optional(),
+  /** Unix ms when the tool started executing. */
+  startedAt: z.number().optional(),
+  /** Unix ms when the tool completed. */
+  completedAt: z.number().optional(),
+  /**
+   * Confirmation outcome for this tool call, when one was recorded. Closed
+   * enum: the daemon has only ever emitted these three values since the field
+   * was introduced, so every daemon that carries it conforms — no version gate.
+   */
+  confirmationDecision: ConfirmationDecisionSchema.optional(),
+  /** Friendly label for the confirmation (e.g. "Edit File", "Run Command"). */
+  confirmationLabel: z.string().optional(),
+  /** Risk level classification at invocation time ("low" | "medium" | "high" | "unknown"). */
+  riskLevel: z.string().optional(),
+  /** Human-readable reason for the risk classification. */
+  riskReason: z.string().optional(),
+  /** ID of the trust rule that matched this invocation (if any). */
+  matchedTrustRuleId: z.string().optional(),
+  /** @deprecated Use `approvalMode` and `approvalReason` instead. */
+  autoApproved: z.boolean().optional(),
+  /** How the approval decision was reached: prompted, auto, blocked, or unknown (legacy). */
+  approvalMode: z.string().optional(),
+  /** Why the approval decision was reached (stable enum for client display). */
+  approvalReason: z.string().optional(),
+  /** Snapshot of the auto-approve threshold at execution time. */
+  riskThreshold: z.string().optional(),
+  /** Display-only regex ladder for the rule editor (narrowest → broadest). */
+  riskScopeOptions: z.array(RiskScopeOptionSchema).optional(),
+  /** Minimatch save patterns for the rule editor (narrowest → broadest). */
+  riskAllowlistOptions: z.array(RiskAllowlistOptionSchema).optional(),
+  /** Directory scope ladder for the rule editor. */
+  riskDirectoryScopeOptions: z.array(RiskDirectoryScopeOptionSchema).optional(),
+  /**
+   * Structured tool activity (web_search / web_fetch) for rich client cards.
+   * Persisted alongside the tool call so the activity card survives a history
+   * reopen instead of degrading to the plain `result` text. Mirrors the live
+   * `tool_result` event's `activityMetadata`. Guaranteed present for tool calls
+   * that produced activity as of daemon v0.8.8; absent for older history rows.
+   */
+  activityMetadata: ToolActivityMetadataSchema.optional(),
+  /**
+   * Confirmation scope ladder (`{label, scope}`) for scope-aware tools
+   * (file/bash). Derived at render time via the permission checker's pure
+   * `generateScopeOptions(workspaceDir, toolName)`, so it is reconstructed for
+   * completed tool calls on history reopen rather than persisted. Feeds the
+   * rule editor's trust-rule suggestion fallback. Distinct from the
+   * regex-flavored `riskScopeOptions` (`{pattern, label}`). Guaranteed present
+   * for scope-aware tools as of daemon v0.8.8; absent for older history rows.
+   */
+  scopeOptions: z.array(ScopeOptionSchema).optional(),
+  /**
+   * In-flight permission prompt, present only while the tool call is awaiting
+   * a user decision (read from the `pending-interactions` registry at render
+   * time). Lets a cold reconnect restore the inline confirmation card.
+   * Guaranteed present for outstanding prompts as of daemon v0.8.8.
+   */
+  pendingConfirmation: PendingToolConfirmationSchema.optional(),
+});
+export type ConversationMessageToolCall = z.infer<
+  typeof ConversationMessageToolCallSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Surface
+// ---------------------------------------------------------------------------
+
+const SurfaceActionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  style: z.string().optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * A UI surface (widget) embedded in a history row. `contentOrder` references
+ * it as `surface:N` where `N` indexes into `surfaces`.
+ */
+export const ConversationMessageSurfaceSchema = z.object({
+  surfaceId: z.string(),
+  surfaceType: z.string(),
+  title: z.string().optional(),
+  data: z.record(z.string(), z.unknown()),
+  actions: z.array(SurfaceActionSchema).optional(),
+  display: z.string().optional(),
+  persistent: z.boolean().optional(),
+  completed: z.boolean().optional(),
+  completionSummary: z.string().optional(),
+  /** Id of the tool call that produced this surface (the `ui_show` proxy tool). */
+  toolCallId: z.string().optional(),
+});
+export type ConversationMessageSurface = z.infer<
+  typeof ConversationMessageSurfaceSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Subagent notification
+// ---------------------------------------------------------------------------
+
+/** Daemon-injected subagent lifecycle notification attached to a history row. */
+export const ConversationSubagentNotificationSchema = z.object({
+  subagentId: z.string(),
+  label: z.string(),
+  status: z.string(),
+  error: z.string().optional(),
+  conversationId: z.string().optional(),
+  objective: z.string().optional(),
+});
+export type ConversationSubagentNotification = z.infer<
+  typeof ConversationSubagentNotificationSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Slack message envelope
+// ---------------------------------------------------------------------------
+
+const SlackMessageLinkSchema = z.object({
+  appUrl: z.string().optional(),
+  webUrl: z.string().optional(),
+});
+
+/** Slack provenance for a history row that originated from a Slack channel. */
+export const ConversationSlackMessageSchema = z.object({
+  channelId: z.string(),
+  channelName: z.string().optional(),
+  channelTs: z.string(),
+  threadTs: z.string().optional(),
+  sender: z
+    .object({
+      displayName: z.string().optional(),
+      externalUserId: z.string().optional(),
+    })
+    .optional(),
+  messageLink: SlackMessageLinkSchema.optional(),
+  threadLink: SlackMessageLinkSchema.optional(),
+});
+export type ConversationSlackMessage = z.infer<
+  typeof ConversationSlackMessageSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Content block (unified ordered content)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single ordered content block. `contentBlocks` is the unified, display-ready
+ * projection of a message's model-native content — one ordered tagged array so
+ * clients render by mapping a single list instead of cross-referencing the
+ * parallel positional arrays.
+ *
+ * Discriminants and field names mirror the model-loop `ContentBlock` union
+ * (`providers/types.ts`) so logic reads the same whether it runs in a
+ * plugin/hook (raw provider blocks) or on a client (this cleaned wire form).
+ * The wire form differs from the raw provider union in three deliberate ways:
+ *   - `tool_use` carries its paired result (`toolCall.result`): the daemon
+ *     merges the separate `tool_result` block at read time so clients never
+ *     re-pair calls with their results.
+ *   - internal/sensitive provider fields are dropped (risk/approval scratch
+ *     fields, raw base64 image bytes, provider thought signatures, opaque
+ *     server-tool blobs).
+ *   - vellum projections with no provider analog (`surface`, `attachment`)
+ *     reuse the existing history schemas.
+ *
+ * The daemon builds this array directly from the model-native content while
+ * rendering history (`renderHistoryContent`); the serializer never reconstructs
+ * it from the positional arrays, so it stays correct once those are retired.
+ */
+export const ConversationContentBlockSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }),
+  z.object({ type: z.literal("thinking"), thinking: z.string() }),
+  z.object({
+    type: z.literal("tool_use"),
+    toolCall: ConversationMessageToolCallSchema,
+  }),
+  z.object({
+    type: z.literal("surface"),
+    surface: ConversationMessageSurfaceSchema,
+  }),
+  z.object({
+    type: z.literal("attachment"),
+    attachment: ConversationMessageAttachmentSchema,
+  }),
+]);
+export type ConversationContentBlock = z.infer<
+  typeof ConversationContentBlockSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Conversation message (history row)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single consolidated history row as returned by the daemon's messages
+ * endpoint. Consecutive assistant DB rows are merged into one display row;
+ * `mergedMessageIds` records the folded ids.
+ */
+export const ConversationMessageSchema = z.object({
+  id: z.string(),
+  /**
+   * Server message ids folded into this display row when consecutive
+   * assistant messages were consolidated for history rendering.
+   */
+  mergedMessageIds: z.array(z.string()).optional(),
+  role: z.string(),
+  /**
+   * Flat plain-text body (joined text segments). Redundant with
+   * `textSegments`/`contentOrder` for clients that render from the positional
+   * arrays (web, CLI), but the legacy Swift macOS client reads `content`
+   * directly and drops any history row missing it (its
+   * `HistoryReconstructionService` skips rows with empty text). The serializer
+   * always emits it — do not remove without updating that client.
+   */
+  content: z.string().optional(),
+  /** Display timestamp as an ISO-8601 string. */
+  timestamp: z.string(),
+  attachments: z.array(ConversationMessageAttachmentSchema),
+  toolCalls: z.array(ConversationMessageToolCallSchema).optional(),
+  surfaces: z.array(ConversationMessageSurfaceSchema).optional(),
+  textSegments: z.array(z.string()).optional(),
+  thinkingSegments: z.array(z.string()).optional(),
+  /** Positional `"<type>:<index>"` content ordering (e.g. `"text:0"`, `"thinking:1"`). */
+  contentOrder: z.array(z.string()).optional(),
+  /**
+   * Unified ordered content blocks — the display-ready projection of the
+   * row's model-native content. Ships alongside the positional
+   * `contentOrder`/`textSegments`/`thinkingSegments` arrays during the client
+   * migration; a client that consumes `contentBlocks` can ignore the
+   * positional arrays entirely.
+   */
+  contentBlocks: z.array(ConversationContentBlockSchema).optional(),
+  subagentNotification: ConversationSubagentNotificationSchema.optional(),
+  slackMessage: ConversationSlackMessageSchema.optional(),
+});
+export type ConversationMessage = z.infer<typeof ConversationMessageSchema>;