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

package/src/runtime/routes/conversation-routes.ts

@@ -10,6 +10,7 @@ import {
   createAssistantMessage,
   createUserMessage,
 } from "../../agent/message-types.js";
+import { ConversationMessageSchema } from "../../api/responses/conversation-message.js";
 import {
   CHANNEL_IDS,
   INTERFACE_IDS,
@@ -18,6 +19,7 @@ import {
   parseInterfaceId,
   supportsHostProxy,
 } from "../../channels/types.js";
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getConfig } from "../../config/loader.js";
 import {
@@ -26,6 +28,7 @@ import {
 } from "../../conversations/message-consolidation.js";
 import { createApprovalConversationGenerator } from "../../daemon/approval-generators.js";
 import type { Conversation } from "../../daemon/conversation.js";
+import { persistQueuedMessageBody } from "../../daemon/conversation-messaging.js";
 import {
   buildModelInfoEvent,
   formatCleanResult,
@@ -40,10 +43,15 @@ import { getOrCreateConversation as getOrCreateConversationInstance } from "../.
 import { canonicalizeTimeZone } from "../../daemon/date-context.js";
 import {
   buildScanFirstMessage,
+  buildSelfIntroMessage,
   getCannedFirstGreeting,
   isWakeUpGreeting,
 } from "../../daemon/first-greeting.js";
-import { renderHistoryContent } from "../../daemon/handlers/shared.js";
+import {
+  collectAttachmentRefs,
+  type HistoryAttachmentRef,
+  renderHistoryContent,
+} from "../../daemon/handlers/shared.js";
 import { HostAppControlProxy } from "../../daemon/host-app-control-proxy.js";
 import { HostCuProxy } from "../../daemon/host-cu-proxy.js";
 import {
@@ -75,6 +83,7 @@ import {
 } from "../../memory/canonical-guardian-store.js";
 import {
   addMessage,
+  extractImageSourcePaths,
   getConversation,
   getMessages,
   getMessagesPaginated,
@@ -82,8 +91,6 @@ import {
   type MessageRow,
   provenanceFromTrustContext,
   setConversationInferenceProfile,
-  setConversationOriginChannelIfUnset,
-  setConversationOriginInterfaceIfUnset,
 } from "../../memory/conversation-crud.js";
 import {
   getConversationByKey,
@@ -103,10 +110,15 @@ import type { Provider } from "../../providers/types.js";
 import { checkIngressForSecrets } from "../../security/secret-ingress.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { getLogger } from "../../util/logger.js";
-import { getWorkspacePromptPath } from "../../util/platform.js";
+import {
+  getWorkspaceDir,
+  getWorkspacePromptPath,
+} from "../../util/platform.js";
 import { silentlyWithLog } from "../../util/silently.js";
 import { assistantEventHub, broadcastMessage } from "../assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
+import { getPersistedSeq } from "../assistant-stream-state.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { routeGuardianReply } from "../guardian-reply-router.js";
 import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
 import type {
@@ -131,6 +143,10 @@ import {
   NotFoundError,
   RouteError,
 } from "./errors.js";
+import {
+  collectPendingConfirmations,
+  enrichToolCallsWithConfirmation,
+} from "./tool-call-confirmation-enrichment.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
 
@@ -140,6 +156,128 @@ const log = getLogger("conversation-routes");
 const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/g;
 const ATTACHMENT_ENTRY_RE = /^attachment:(\d+)$/;
 
+/** Rewrites a rendered `contentOrder` to reflect attachment alignment. */
+type ContentOrderRewrite = (contentOrder: string[]) => string[];
+
+interface AlignedAttachments {
+  /** Hydrated rows, reordered to match the inline file-block order. */
+  attachments: RuntimeAttachmentMetadata[];
+  /**
+   * Resolves a content-walk attachment ref index to its hydrated DB row,
+   * mirroring the inline placement `rewriteContentOrder` encodes. Refs with no
+   * inline placement (unmatched ids, count mismatch, no DB rows) are absent, so
+   * `renderHistoryContent` emits no `attachment` block for them — the row still
+   * ships via the flat `attachments` array.
+   */
+  refIndexToAttachment: Map<number, RuntimeAttachmentMetadata>;
+  rewriteContentOrder: ContentOrderRewrite;
+}
+
+/**
+ * Align DB-hydrated attachment rows with the file-block refs `renderHistoryContent`
+ * captured. When a file block was persisted with `_attachmentId` (user-message
+ * uploads) we join on that id to position the chip inline; DB rows without a
+ * matching ref go to the tail as orphan chips, and unmatched refs drop their
+ * `attachment:N` entry. Assistant-authored file blocks carry no `_attachmentId`,
+ * so when no ids match we fall back to positional alignment if the ref and row
+ * counts agree; otherwise we strip the markers and let chips fall to the tail.
+ */
+function alignAttachments(
+  attachmentRefs: HistoryAttachmentRef[],
+  attachments: RuntimeAttachmentMetadata[],
+): AlignedAttachments {
+  const refIndexToAttachment = new Map<number, RuntimeAttachmentMetadata>();
+  const identity: ContentOrderRewrite = (contentOrder) => contentOrder;
+  const stripAttachmentEntries: ContentOrderRewrite = (contentOrder) =>
+    contentOrder.filter((entry) => !ATTACHMENT_ENTRY_RE.test(entry));
+
+  if (attachmentRefs.length === 0) {
+    return { attachments, refIndexToAttachment, rewriteContentOrder: identity };
+  }
+  if (attachments.length === 0) {
+    // Refs were captured but no DB rows came back — drop the contentOrder
+    // entries to avoid out-of-bounds renders.
+    return {
+      attachments,
+      refIndexToAttachment,
+      rewriteContentOrder: stripAttachmentEntries,
+    };
+  }
+
+  const byId = new Map<string, number>();
+  attachments.forEach((att, idx) => {
+    if (att.id) byId.set(att.id, idx);
+  });
+  const consumed = new Set<number>();
+  const orderedRowIdx: Array<number | null> = attachmentRefs.map((ref) => {
+    if (!ref.attachmentId) return null;
+    const idx = byId.get(ref.attachmentId);
+    if (idx === undefined || consumed.has(idx)) return null;
+    consumed.add(idx);
+    return idx;
+  });
+  const matchedRows = orderedRowIdx.filter(
+    (idx): idx is number => idx !== null,
+  );
+
+  if (matchedRows.length > 0) {
+    const orphanRows: number[] = [];
+    for (let i = 0; i < attachments.length; i++) {
+      if (!consumed.has(i)) orphanRows.push(i);
+    }
+    const reordered = [
+      ...matchedRows.map((i) => attachments[i]),
+      ...orphanRows.map((i) => attachments[i]),
+    ];
+    const refToNewIdx = new Map<number, number>();
+    let nextIdx = 0;
+    orderedRowIdx.forEach((rowIdx, refIdx) => {
+      if (rowIdx !== null) {
+        refToNewIdx.set(refIdx, nextIdx);
+        refIndexToAttachment.set(refIdx, reordered[nextIdx]);
+        nextIdx++;
+      }
+    });
+    const rewriteContentOrder: ContentOrderRewrite = (contentOrder) =>
+      contentOrder
+        .map((entry) => {
+          const match = entry.match(ATTACHMENT_ENTRY_RE);
+          if (!match) return entry;
+          const remapped = refToNewIdx.get(Number(match[1]));
+          return remapped !== undefined ? `attachment:${remapped}` : undefined;
+        })
+        .filter((e): e is string => e !== undefined);
+    return {
+      attachments: reordered,
+      refIndexToAttachment,
+      rewriteContentOrder,
+    };
+  }
+
+  if (attachmentRefs.length !== attachments.length) {
+    // No ref carried an attachmentId we could match and the counts disagree, so
+    // positional mapping can't be trusted — strip any attachment:N entries so
+    // the client doesn't position attachments inline against a misaligned array
+    // (they fall to the tail instead).
+    return {
+      attachments,
+      refIndexToAttachment,
+      rewriteContentOrder: stripAttachmentEntries,
+    };
+  }
+
+  // No ref matched an id but the counts agree (the assistant-authored case):
+  // the Nth marker maps to the Nth row positionally, so the original
+  // contentOrder is left untouched.
+  attachmentRefs.forEach((_ref, refIdx) => {
+    refIndexToAttachment.set(refIdx, attachments[refIdx]);
+  });
+  return { attachments, refIndexToAttachment, rewriteContentOrder: identity };
+}
+
+/** Feature flag gating the self-intro first message (see first-greeting.ts). */
+const SELF_INTRO_GREETING_FLAG = "self-intro-greeting" as const;
+
 const SUGGESTION_CACHE_MAX = 100;
 const VALID_RISK_THRESHOLDS = ["none", "low", "medium", "high"] as const;
 type RiskThreshold = (typeof VALID_RISK_THRESHOLDS)[number];
@@ -395,23 +533,10 @@ async function tryConsumeCanonicalGuardianReply(params: {
   // is not re-processed as a new user turn.
   let messageId: string | undefined;
   try {
-    const guardianImageSourcePaths: Record<string, string> = {};
-    for (let i = 0; i < attachments.length; i++) {
-      const a = attachments[i];
-      if (a.filePath && a.mimeType.toLowerCase().startsWith("image/")) {
-        guardianImageSourcePaths[`${i}:${a.filename}`] = a.filePath;
-      }
-    }
-    const channelMeta = {
-      userMessageChannel: sourceChannel,
-      assistantMessageChannel: sourceChannel,
-      userMessageInterface: sourceInterface,
-      assistantMessageInterface: sourceInterface,
-      provenanceTrustClass: "guardian" as const,
-      ...(Object.keys(guardianImageSourcePaths).length > 0
-        ? { imageSourcePaths: guardianImageSourcePaths }
-        : {}),
-    };
+    const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+      provenanceOverride: { provenanceTrustClass: "guardian" },
+      attachments,
+    });
 
     const cleanUserMessage = createUserMessage(content, attachments);
     const llmUserMessage = enrichMessageWithSourcePaths(
@@ -422,7 +547,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
       conversationId,
       "user",
       JSON.stringify(cleanUserMessage.content),
-      channelMeta,
+      { metadata: channelMeta },
     );
     messageId = persistedUser.id;
 
@@ -436,7 +561,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
       conversationId,
       "assistant",
       JSON.stringify(assistantMessage.content),
-      channelMeta,
+      { metadata: channelMeta },
     );
 
     // Avoid mutating in-memory history / emitting stream deltas while a run is active.
@@ -516,6 +641,7 @@ export function handleListMessages({
         hasMore: false,
         oldestTimestamp: null,
         oldestMessageId: null,
+        seq: null,
       };
     }
     return { messages: [] };
@@ -538,6 +664,10 @@ export function handleListMessages({
 
   let rawMessages: MessageRow[];
   let hasMore = false;
+  // Resume cursor surfaced when the paginated scan stops on its row cap with a
+  // (possibly empty) page — lets us still emit an oldest cursor so the client
+  // can request the next window instead of stalling.
+  let scanResumeCursor: { createdAt: number; id: string } | undefined;
 
   // Drop messages flagged as hidden in metadata (e.g. internal scaffolding
   // like retrospective instructions). The LLM-side history loader
@@ -550,7 +680,14 @@ export function handleListMessages({
   // assistant message has tool_use blocks but its matching user tool_result
   // is left visible, the result will render as a standalone orphan because
   // `mergeToolResultsIntoAssistantMessages` has nothing to merge it into.
-  const visibleFilter = (m: MessageRow) => !isHiddenMessage(m.metadata);
+  //
+  // Only renderable roles reach this UI-facing transcript. `system` rows (a
+  // permitted `MessageRole`, e.g. skill-authored context) are agent-context
+  // scaffolding, never a displayed turn, so they are dropped here at the
+  // source rather than narrowed away per-client.
+  const visibleFilter = (m: MessageRow) =>
+    !isHiddenMessage(m.metadata) &&
+    (m.role === "user" || m.role === "assistant");
 
   if (isPaginated) {
     const result = getMessagesPaginated(
@@ -561,6 +698,7 @@ export function handleListMessages({
     );
     rawMessages = result.messages;
     hasMore = result.hasMore;
+    scanResumeCursor = result.nextCursor;
   } else {
     rawMessages = getMessages(resolvedConversationId).filter(visibleFilter);
   }
@@ -583,7 +721,10 @@ export function handleListMessages({
     mergeConsecutiveAssistantMessages(mergedMessages);
   const assistantSlackDisplayName = getAssistantName()?.trim() || undefined;
 
-  // Parse content blocks and extract text + tool calls
+  // Parse each row's stored content and per-message metadata. Rendering is
+  // deferred to the serializer pass below so it runs after attachment
+  // alignment, letting renderHistoryContent inline `attachment` blocks during
+  // its single content walk.
   const parsed = consolidatedMessages.map((msg) => {
     let content: unknown;
     try {
@@ -591,7 +732,6 @@ export function handleListMessages({
     } catch {
       content = msg.content;
     }
-    const rendered = renderHistoryContent(content);
 
     // Extract sentAt from metadata for display timestamps. When a message
     // was queued or its persistence was delayed (long assistant generation),
@@ -639,94 +779,51 @@ export function handleListMessages({
       },
     );
 
-    // Strip <no_response/> markers from assistant messages so web/API
-    // clients never see the raw sentinel. Only assistant messages produce
-    // this marker; user messages are left untouched.
-    if (msg.role === "assistant") {
-      const originalSegments = rendered.textSegments;
-      const keepIndices: number[] = [];
-      const filteredSegments: string[] = [];
-      for (let i = 0; i < originalSegments.length; i++) {
-        const cleaned = originalSegments[i]
-          .replace(NO_RESPONSE_INLINE_RE, "")
-          .trim();
-        if (cleaned.length > 0) {
-          keepIndices.push(i);
-          filteredSegments.push(cleaned);
-        }
-      }
-      // Remap contentOrder text:N indices to account for removed segments
-      const indexMap = new Map<number, number>();
-      keepIndices.forEach((oldIdx, newIdx) => indexMap.set(oldIdx, newIdx));
-      const filteredContentOrder = rendered.contentOrder
-        .map((entry) => {
-          const m = entry.match(/^text:(\d+)$/);
-          if (!m) return entry;
-          const newIdx = indexMap.get(Number(m[1]));
-          return newIdx !== undefined ? `text:${newIdx}` : undefined;
-        })
-        .filter((e): e is string => e !== undefined);
-
-      return {
-        role: msg.role,
-        text: rendered.text.replace(NO_RESPONSE_INLINE_RE, "").trim(),
-        timestamp: msg.createdAt,
-        sentAt,
-        toolCalls: rendered.toolCalls,
-        toolCallsBeforeText: rendered.toolCallsBeforeText,
-        textSegments: filteredSegments,
-        contentOrder: filteredContentOrder,
-        surfaces: rendered.surfaces,
-        attachmentRefs: rendered.attachments,
-        slackMessage,
-        ...(rendered.thinkingSegments.length > 0
-          ? { thinkingSegments: rendered.thinkingSegments }
-          : {}),
-        id: msg.id,
-        subagentNotification,
-      };
-    }
+    // `visibleFilter` has already dropped every non-renderable role, so the
+    // only values reaching here are `user` and `assistant`; narrow the raw DB
+    // `string` to the wire union.
+    const role: "user" | "assistant" =
+      msg.role === "assistant" ? "assistant" : "user";
 
     return {
-      role: msg.role,
-      text: rendered.text,
-      timestamp: msg.createdAt,
-      sentAt,
-      toolCalls: rendered.toolCalls,
-      toolCallsBeforeText: rendered.toolCallsBeforeText,
-      textSegments: rendered.textSegments,
-      contentOrder: rendered.contentOrder,
-      surfaces: rendered.surfaces,
-      attachmentRefs: rendered.attachments,
-      slackMessage,
-      ...(rendered.thinkingSegments.length > 0
-        ? { thinkingSegments: rendered.thinkingSegments }
-        : {}),
       id: msg.id,
+      role,
+      content,
+      createdAt: msg.createdAt,
+      sentAt,
       subagentNotification,
+      slackMessage,
     };
   });
 
+  // Confirmation context layered onto rendered tool calls at render time: the
+  // derived scope ladder for scope-aware tools, and any in-flight prompt read
+  // from the pending-interactions registry. Both are computed once per request
+  // and applied per message below.
+  const workspaceDir = getWorkspaceDir();
+  const pendingConfirmations = collectPendingConfirmations(
+    resolvedConversationId,
+  );
+
   const messages: RuntimeMessagePayload[] = parsed.map((m) => {
+    const mergedMessageIds = m.id ? (mergedIdMap.get(m.id) ?? []) : [];
+
+    // Hydrate the row's attachments from the DB. A metadata-only query avoids
+    // loading large base64 blobs for non-image attachments (documents, audio);
+    // full data is fetched only for images so the client can generate
+    // thumbnails for inline display on history restore. Merged messages
+    // (consecutive assistant merge) are queried too so their attachments
+    // aren't lost before DB compaction relinks them.
     let msgAttachments: RuntimeAttachmentMetadata[] = [];
     if (m.id) {
-      // Use metadata-only query first to avoid loading large base64
-      // blobs for non-image attachments (documents, audio). Then
-      // selectively fetch full data only for images so the client can
-      // generate thumbnails for inline display on history restore.
-      // Also query attachments for any messages that were merged into
-      // this one (consecutive assistant merge), so their attachments
-      // aren't lost before DB compaction relinks them.
-      const idsToQuery = [m.id, ...(mergedIdMap.get(m.id) ?? [])];
+      const idsToQuery = [m.id, ...mergedMessageIds];
       const linked = idsToQuery.flatMap((id) =>
         getAttachmentMetadataForMessage(id),
       );
       if (linked.length > 0) {
         msgAttachments = linked.map((a) => {
           if (a.mimeType.startsWith("image/")) {
-            const full = getAttachmentById(a.id, {
-              hydrateFileData: true,
-            });
+            const full = getAttachmentById(a.id, { hydrateFileData: true });
             return {
               id: a.id,
               filename: a.originalFilename,
@@ -753,100 +850,101 @@ export function handleListMessages({
       }
     }
 
-    // Align msgAttachments order with the file-block order captured by
-    // renderHistoryContent. When a file block was persisted with
-    // `_attachmentId`, we can join on that id to position the chip inline
-    // (the `attachment:N` entries in contentOrder index into msgAttachments).
-    // DB rows without a matching ref go to the tail as orphan chips;
-    // unmatched refs drop their contentOrder entry and trigger a remap.
-    let alignedContentOrder = m.contentOrder;
-    if (
-      m.attachmentRefs.length > 0 &&
-      msgAttachments.length > 0 &&
-      m.contentOrder.length > 0
-    ) {
-      const byId = new Map<string, number>();
-      msgAttachments.forEach((att, idx) => {
-        if (att.id) byId.set(att.id, idx);
-      });
-      const consumed = new Set<number>();
-      const orderedRowIdx: Array<number | null> = m.attachmentRefs.map(
-        (ref) => {
-          if (!ref.attachmentId) return null;
-          const idx = byId.get(ref.attachmentId);
-          if (idx === undefined || consumed.has(idx)) return null;
-          consumed.add(idx);
-          return idx;
-        },
-      );
-      const matchedRows = orderedRowIdx.filter(
-        (idx): idx is number => idx !== null,
-      );
-      if (matchedRows.length > 0) {
-        const orphanRows: number[] = [];
-        for (let i = 0; i < msgAttachments.length; i++) {
-          if (!consumed.has(i)) orphanRows.push(i);
+    // Align the hydrated rows with the file-block refs, then render. Rendering
+    // after alignment lets renderHistoryContent inline each `attachment` block
+    // during its single content walk, so `contentBlocks` comes back ready to
+    // ship with no post-processing. The aligned reorder/rewrite keeps the
+    // legacy `attachments` array and `contentOrder` positions consistent.
+    const attachmentRefs = collectAttachmentRefs(m.content);
+    const aligned = alignAttachments(attachmentRefs, msgAttachments);
+    msgAttachments = aligned.attachments;
+    const attachmentBlocks = attachmentRefs.map(
+      (_ref, refIdx) => aligned.refIndexToAttachment.get(refIdx) ?? null,
+    );
+    const rendered = renderHistoryContent(
+      m.content,
+      attachmentBlocks,
+      m.id ?? undefined,
+    );
+
+    const toolCalls = enrichToolCallsWithConfirmation(rendered.toolCalls, {
+      workspaceDir,
+      pendingConfirmations,
+    });
+
+    // Strip <no_response/> markers from assistant messages so web/API clients
+    // never see the raw sentinel. Only assistant messages produce it; user
+    // messages are untouched. The filter is applied consistently to the flat
+    // text, the segments, the contentOrder text refs, and the text blocks of
+    // contentBlocks.
+    let text = rendered.text;
+    let textSegments = rendered.textSegments;
+    let contentOrder = rendered.contentOrder;
+    let contentBlocks = rendered.contentBlocks;
+    if (m.role === "assistant") {
+      const keepIndices: number[] = [];
+      const filteredSegments: string[] = [];
+      for (let i = 0; i < rendered.textSegments.length; i++) {
+        const cleaned = rendered.textSegments[i]
+          .replace(NO_RESPONSE_INLINE_RE, "")
+          .trim();
+        if (cleaned.length > 0) {
+          keepIndices.push(i);
+          filteredSegments.push(cleaned);
         }
-        msgAttachments = [
-          ...matchedRows.map((i) => msgAttachments[i]),
-          ...orphanRows.map((i) => msgAttachments[i]),
-        ];
-        const refToNewIdx = new Map<number, number>();
-        let nextIdx = 0;
-        orderedRowIdx.forEach((rowIdx, refIdx) => {
-          if (rowIdx !== null) {
-            refToNewIdx.set(refIdx, nextIdx);
-            nextIdx++;
-          }
-        });
-        alignedContentOrder = m.contentOrder
-          .map((entry) => {
-            const match = entry.match(ATTACHMENT_ENTRY_RE);
-            if (!match) return entry;
-            const remapped = refToNewIdx.get(Number(match[1]));
-            return remapped !== undefined
-              ? `attachment:${remapped}`
-              : undefined;
-          })
-          .filter((e): e is string => e !== undefined);
-      } else {
-        // No refs carried an attachmentId we could match — strip any
-        // attachment:N entries so the client doesn't try to position
-        // attachments inline against a misaligned array.
-        alignedContentOrder = m.contentOrder.filter(
-          (entry) => !ATTACHMENT_ENTRY_RE.test(entry),
-        );
       }
-    } else if (m.attachmentRefs.length > 0 && msgAttachments.length === 0) {
-      // Refs were captured but no DB rows came back — drop the
-      // contentOrder entries to avoid out-of-bounds renders.
-      alignedContentOrder = m.contentOrder.filter(
-        (entry) => !ATTACHMENT_ENTRY_RE.test(entry),
-      );
+      const indexMap = new Map<number, number>();
+      keepIndices.forEach((oldIdx, newIdx) => indexMap.set(oldIdx, newIdx));
+      contentOrder = rendered.contentOrder
+        .map((entry) => {
+          const tm = entry.match(/^text:(\d+)$/);
+          if (!tm) return entry;
+          const newIdx = indexMap.get(Number(tm[1]));
+          return newIdx !== undefined ? `text:${newIdx}` : undefined;
+        })
+        .filter((e): e is string => e !== undefined);
+      textSegments = filteredSegments;
+      text = rendered.text.replace(NO_RESPONSE_INLINE_RE, "").trim();
+      contentBlocks = rendered.contentBlocks
+        .map((block) =>
+          block.type === "text"
+            ? {
+                type: "text" as const,
+                text: block.text.replace(NO_RESPONSE_INLINE_RE, "").trim(),
+              }
+            : block,
+        )
+        .filter((block) => block.type !== "text" || block.text.length > 0);
     }
 
-    // Use sentAt (actual event time) for the display timestamp when
-    // available, falling back to createdAt (persistence time).
-    // Note: clients use this display timestamp as their pagination cursor
-    // after memory-pressure trimming, while server-side pagination filters
-    // on createdAt. The mismatch is benign — it may return slightly extra
-    // data on a page boundary but never loses messages.
-    const displayTimestamp = m.sentAt ?? m.timestamp;
+    const alignedContentOrder = aligned.rewriteContentOrder(contentOrder);
+
+    // Use sentAt (actual event time) for the display timestamp when available,
+    // falling back to createdAt (persistence time). Clients use this display
+    // timestamp as their pagination cursor after memory-pressure trimming,
+    // while server-side pagination filters on createdAt. The mismatch is
+    // benign — it may return slightly extra data on a page boundary but never
+    // loses messages.
+    const displayTimestamp = m.sentAt ?? m.createdAt;
     return {
       id: m.id ?? "",
+      ...(mergedMessageIds.length > 0 ? { mergedMessageIds } : {}),
       role: m.role,
-      content: m.text,
+      // Flat plain-text body the legacy Swift client reads directly; see the
+      // `content` field on ConversationMessageSchema for why this must stay.
+      content: text,
       timestamp: new Date(displayTimestamp).toISOString(),
       attachments: msgAttachments,
-      ...(m.toolCalls.length > 0 ? { toolCalls: m.toolCalls } : {}),
-      ...(m.surfaces.length > 0 ? { surfaces: m.surfaces } : {}),
-      ...(m.textSegments.length > 0 ? { textSegments: m.textSegments } : {}),
-      ...(m.thinkingSegments?.length
-        ? { thinkingSegments: m.thinkingSegments }
+      ...(toolCalls.length > 0 ? { toolCalls } : {}),
+      ...(rendered.surfaces.length > 0 ? { surfaces: rendered.surfaces } : {}),
+      ...(textSegments.length > 0 ? { textSegments } : {}),
+      ...(rendered.thinkingSegments.length > 0
+        ? { thinkingSegments: rendered.thinkingSegments }
         : {}),
       ...(alignedContentOrder.length > 0
         ? { contentOrder: alignedContentOrder }
         : {}),
+      ...(contentBlocks.length > 0 ? { contentBlocks } : {}),
       ...(m.subagentNotification
         ? { subagentNotification: m.subagentNotification }
         : {}),
@@ -854,11 +952,24 @@ export function handleListMessages({
     };
   });
 
+  // Snapshot↔stream alignment token: the `seq` of the last event whose
+  // content is durably persisted for this conversation in the current
+  // daemon process. Returned on every resolved-conversation response so a
+  // client can apply only stream events with a higher `seq`. Null when
+  // nothing has been persisted in-process (cold/aged-out/post-restart).
+  const persistedSeq = getPersistedSeq(resolvedConversationId);
+
   if (isPaginated) {
+    // Prefer the page's oldest visible row (the documented cursor semantic).
+    // When a scan-cap-truncated page comes back empty there's no visible row
+    // to anchor on, so fall back to the resume cursor so the client still gets
+    // a `(timestamp, id)` to continue paginating from instead of stalling.
     const oldestTimestamp =
-      rawMessages.length > 0 ? rawMessages[0].createdAt : undefined;
+      rawMessages.length > 0
+        ? rawMessages[0].createdAt
+        : scanResumeCursor?.createdAt;
     const oldestMessageId =
-      rawMessages.length > 0 ? rawMessages[0].id : undefined;
+      rawMessages.length > 0 ? rawMessages[0].id : scanResumeCursor?.id;
     // `page=latest` always emits both metadata fields so the web client has
     // a stable contract; emit `null` when the conversation is empty.
     // The existing `beforeTimestamp` branch keeps its conditional shape to
@@ -869,6 +980,7 @@ export function handleListMessages({
         hasMore,
         oldestTimestamp: oldestTimestamp ?? null,
         oldestMessageId: oldestMessageId ?? null,
+        seq: persistedSeq,
       };
     }
 
@@ -877,10 +989,11 @@ export function handleListMessages({
       hasMore,
       ...(oldestTimestamp != null ? { oldestTimestamp } : {}),
       ...(oldestMessageId != null ? { oldestMessageId } : {}),
+      seq: persistedSeq,
     };
   }
 
-  return { messages };
+  return { messages, seq: persistedSeq };
 }
 
 /**
@@ -1002,13 +1115,15 @@ export async function handleSendMessage(
       cohort?: string;
       websiteUrl?: string;
       contentSourceUrl?: string;
+      bootstrapTemplate?: string;
+      initialMessage?: string;
+      skills?: string[];
     };
   };
 
   const actorPrincipalId = headers?.["x-vellum-actor-principal-id"];
   const principalType = headers?.["x-vellum-principal-type"];
-  const originClientId =
-    headers?.["x-vellum-client-id"]?.trim() || undefined;
+  const originClientId = headers?.["x-vellum-client-id"]?.trim() || undefined;
 
   const { conversationKey, content, attachmentIds } = body;
   const inboundConversationId =
@@ -1149,10 +1264,13 @@ export async function handleSendMessage(
   // assistant-minted internal id) when the client supplies it — clients
   // must obtain this id from a prior daemon response, so a missing row
   // is a 404. Otherwise fall through to the external-key path: the
-  // client-supplied `conversationKey` (used by non-vellum channels and
-  // the web idempotency flow) or, when neither is provided, a stable
-  // default keyed on sourceChannel + sourceInterface so repeated calls
-  // from the same channel/interface share a single thread.
+  // client-supplied `conversationKey` (external-key lookup; materializes
+  // on first use) or, when neither is provided, a channel-dependent
+  // default. The vellum channel mints a fresh conversation on every
+  // empty-handed send so first-message-of-a-new-chat surfaces with a
+  // server-minted id; other channels (phone, slack, …) share a stable
+  // `default:<channel>:<interface>` thread so repeated calls from the
+  // same channel/interface stay co-located.
   let mapping: {
     conversationId: string;
     conversationType: string;
@@ -1174,7 +1292,9 @@ export async function handleSendMessage(
     const resolvedConversationKey =
       conversationKey && conversationKey.length > 0
         ? conversationKey
-        : `default:${sourceChannel}:${sourceInterface}`;
+        : sourceChannel === "vellum"
+          ? crypto.randomUUID()
+          : `default:${sourceChannel}:${sourceInterface}`;
     mapping = getOrCreateConversation(resolvedConversationKey, {
       conversationType: "standard",
     });
@@ -1318,10 +1438,20 @@ export async function handleSendMessage(
   }
 
   const isInteractive = isInteractiveInterface(sourceInterface);
+  // Use the JWT-verified requester principal — not guardianPrincipalId,
+  // which is the workspace owner and would let a trusted contact's web
+  // turn match against the guardian's macOS client.
+  const sourceActorPrincipalId = actorPrincipalId ?? undefined;
   // Bash/File/Transfer singletons are globally available via isAvailable() —
   // no per-conversation gating needed. CU is per-conversation (owns step
   // count, AX tree history, loop detection).
-  if (shouldAttachHostProxyForCapability("host_cu", sourceInterface)) {
+  if (
+    shouldAttachHostProxyForCapability(
+      "host_cu",
+      sourceInterface,
+      sourceActorPrincipalId,
+    )
+  ) {
     if (!conversation.isProcessing() || !conversation.hostCuProxy) {
       conversation.setHostCuProxy(new HostCuProxy());
     }
@@ -1334,7 +1464,13 @@ export async function handleSendMessage(
   // lives in the skill-projection layer (which reads the `feature-flag:
   // app-control` declaration in SKILL.md frontmatter), so an attached proxy
   // is harmless when the flag resolves to off.
-  if (shouldAttachHostProxyForCapability("host_app_control", sourceInterface)) {
+  if (
+    shouldAttachHostProxyForCapability(
+      "host_app_control",
+      sourceInterface,
+      sourceActorPrincipalId,
+    )
+  ) {
     if (!conversation.isProcessing() || !conversation.hostAppControlProxy) {
       conversation.setHostAppControlProxy(
         new HostAppControlProxy(mapping.conversationId),
@@ -1347,7 +1483,11 @@ export async function handleSendMessage(
   // this message will be queued and preactivation is deferred to dequeue
   // time in drainQueueImpl to avoid mutating in-flight turn state.
   if (!conversation.isProcessing()) {
-    preactivateHostProxySkills(conversation, sourceInterface);
+    preactivateHostProxySkills(
+      conversation,
+      sourceInterface,
+      sourceActorPrincipalId,
+    );
   }
   // Wire sendToClient to the SSE hub so all subsystems can reach the HTTP client.
   // hasNoClient must remain `!isInteractive` so downstream tool gating
@@ -1380,6 +1520,16 @@ export async function handleSendMessage(
     conversation.getMessages().length,
   );
   const isScanPath = !!scanUrl && isWakeUp;
+  // Self-intro path: when we know a name, send a natural introduction on the
+  // user's behalf instead of the canned greeting, so the assistant generates a
+  // real first response. Gated behind the `self-intro-greeting` flag (default
+  // off); `undefined` (flag off or no names) falls back to the canned path.
+  const selfIntroGreetingEnabled =
+    isWakeUp &&
+    isAssistantFeatureFlagEnabled(SELF_INTRO_GREETING_FLAG, getConfig());
+  const selfIntro = selfIntroGreetingEnabled
+    ? buildSelfIntroMessage(body.onboarding ?? undefined)
+    : undefined;
 
   let effectiveContent: string | undefined;
   if (isScanPath) {
@@ -1388,55 +1538,46 @@ export async function handleSendMessage(
       : ("content-source" as const);
     effectiveContent = buildScanFirstMessage(scanUrl, scanVariant);
     // Fall through to normal inference path below
-  } else if (isWakeUp && body.onboarding?.cohort === "content-automation") {
-    effectiveContent = "I want to write articles that rank better in GEO";
-    // Fall through to normal inference path — the bootstrap template
-    // and geo-writing skill handle this message.
+  } else if (selfIntroGreetingEnabled && body.onboarding?.initialMessage) {
+    effectiveContent = body.onboarding.initialMessage;
+  } else if (isWakeUp && selfIntro) {
+    // Rewrite to the self-introduction and fall through to real inference
+    // (mirrors the scan path above).
+    effectiveContent = selfIntro;
   } else if (isWakeUp) {
     const cannedGreeting = getCannedFirstGreeting(body.onboarding ?? undefined);
 
-    conversation.processing = true;
+    conversation.setProcessing(true);
     let cleanupDeferred = false;
     try {
-      const provenance = provenanceFromTrustContext(conversation.trustContext);
-      const channelMeta = {
-        ...provenance,
+      const rawContent = content ?? "";
+      const attachments = hasAttachments
+        ? smDeps.resolveAttachments(attachmentIds)
+        : [];
+      const greetingMeta = {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
       };
-
-      const rawContent = content ?? "";
-      const attachments = hasAttachments
-        ? smDeps.resolveAttachments(attachmentIds)
-        : [];
-      const userMsg = createUserMessage(rawContent, attachments);
-      const persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(userMsg.content),
-        channelMeta,
-      );
-      conversation.getMessages().push(userMsg);
-
-      setConversationOriginChannelIfUnset(
-        mapping.conversationId,
-        sourceChannel,
-      );
-      setConversationOriginInterfaceIfUnset(
-        mapping.conversationId,
-        sourceInterface,
-      );
+      const persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: greetingMeta,
+      });
 
       const conversationId = mapping.conversationId;
+      const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+        trustContext: conversation.trustContext,
+      });
 
       const assistantMsg = createAssistantMessage(cannedGreeting);
       const persistedAssistant = await addMessage(
         mapping.conversationId,
         "assistant",
         JSON.stringify(assistantMsg.content),
-        channelMeta,
+        { metadata: channelMeta },
       );
       conversation.getMessages().push(assistantMsg);
 
@@ -1482,7 +1623,7 @@ export async function handleSendMessage(
           persistedAssistant.id,
         );
         publishConversationMessagesChanged(conversationId, originClientId);
-        conversation.processing = false;
+        conversation.setProcessing(false);
         silentlyWithLog(
           conversation.drainQueue(),
           "canned-greeting queue drain",
@@ -1498,8 +1639,8 @@ export async function handleSendMessage(
       cleanupDeferred = true;
       return response;
     } finally {
-      if (!cleanupDeferred && conversation.processing) {
-        conversation.processing = false;
+      if (!cleanupDeferred && conversation.isProcessing()) {
+        conversation.setProcessing(false);
         silentlyWithLog(conversation.drainQueue(), "error-path queue drain");
       }
     }
@@ -1580,25 +1721,22 @@ export async function handleSendMessage(
   if (conversation.isProcessing()) {
     // Queue the message so it's processed when the current turn completes
     const requestId = crypto.randomUUID();
-    const enqueueResult = conversation.enqueueMessage(
-      contentAfterScan,
+    const enqueueResult = conversation.enqueueMessage({
+      content: contentAfterScan,
       attachments,
-      broadcastMessage,
+      onEvent: broadcastMessage,
       requestId,
-      undefined, // activeSurfaceId
-      undefined, // currentPage
-      {
+      metadata: {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
         ...(body.automated === true ? { automated: true } : {}),
       },
-      { isInteractive },
-      undefined, // displayContent
+      isInteractive,
       transport,
       clientMessageId,
-    );
+    });
     if (enqueueResult.rejected) {
       return new RouteResponse(
         JSON.stringify({ accepted: false, error: "queue_full" }),
@@ -1715,56 +1853,43 @@ export async function handleSendMessage(
   const slashResult = await resolveSlash(rawContent, slashContext);
 
   if (slashResult.kind === "unknown") {
-    conversation.processing = true;
+    conversation.setProcessing(true);
     let cleanupDeferred = false;
     try {
-      const provenance = provenanceFromTrustContext(conversation.trustContext);
-      const imageSourcePaths: Record<string, string> = {};
-      for (let i = 0; i < attachments.length; i++) {
-        const a = attachments[i];
-        if (a.filePath && a.mimeType.toLowerCase().startsWith("image/")) {
-          imageSourcePaths[`${i}:${a.filename}`] = a.filePath;
-        }
-      }
-      const channelMeta = {
-        ...provenance,
+      const slashMeta = {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
         ...(body.automated === true ? { automated: true } : {}),
-        ...(Object.keys(imageSourcePaths).length > 0
-          ? { imageSourcePaths }
-          : {}),
       };
-      const cleanMsg = createUserMessage(rawContent, attachments);
-      const llmMsg = enrichMessageWithSourcePaths(cleanMsg, attachments);
-      const persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(cleanMsg.content),
-        channelMeta,
-      );
-      conversation.getMessages().push(llmMsg);
+      const persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: slashMeta,
+        clientMessageId,
+      });
+      if (persisted.deduplicated) {
+        return {
+          accepted: true,
+          messageId: persisted.id,
+          conversationId: mapping.conversationId,
+        };
+      }
 
+      const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+        trustContext: conversation.trustContext,
+      });
       const assistantMsg = createAssistantMessage(slashResult.message);
       const persistedAssistant = await addMessage(
         mapping.conversationId,
         "assistant",
         JSON.stringify(assistantMsg.content),
-        channelMeta,
+        { metadata: channelMeta },
       );
       conversation.getMessages().push(assistantMsg);
 
-      setConversationOriginChannelIfUnset(
-        mapping.conversationId,
-        sourceChannel,
-      );
-      setConversationOriginInterfaceIfUnset(
-        mapping.conversationId,
-        sourceInterface,
-      );
-
       // Snapshot model info now so the deferred callback cannot observe
       // a config change from a concurrent request.
       const modelInfoEvent = isModelSlashCommand(rawContent)
@@ -1809,7 +1934,7 @@ export async function handleSendMessage(
           persistedAssistant.id,
         );
         publishConversationMessagesChanged(conversationId, originClientId);
-        conversation.processing = false;
+        conversation.setProcessing(false);
         silentlyWithLog(conversation.drainQueue(), "slash-command queue drain");
       }, 0);
 
@@ -1818,43 +1943,52 @@ export async function handleSendMessage(
     } finally {
       // No-op for the slash-command early-return path (handled inside
       // setTimeout above), but still needed for error paths.
-      if (!cleanupDeferred && conversation.processing) {
-        conversation.processing = false;
+      if (!cleanupDeferred && conversation.isProcessing()) {
+        conversation.setProcessing(false);
         silentlyWithLog(conversation.drainQueue(), "error-path queue drain");
       }
     }
   }
 
   if (slashResult.kind === "compact") {
-    conversation.processing = true;
-    const provenance = provenanceFromTrustContext(conversation.trustContext);
-    const channelMeta = {
-      ...provenance,
+    conversation.setProcessing(true);
+    const slashMeta = {
       userMessageChannel: sourceChannel,
       assistantMessageChannel: sourceChannel,
       userMessageInterface: sourceInterface,
       assistantMessageInterface: sourceInterface,
     };
-    const cleanMsg = createUserMessage(rawContent, attachments);
-    let persisted: Awaited<ReturnType<typeof addMessage>>;
+    let persisted: Awaited<ReturnType<typeof persistQueuedMessageBody>>;
     try {
-      persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(cleanMsg.content),
-        channelMeta,
-      );
+      persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: slashMeta,
+        clientMessageId,
+      });
     } catch (err) {
       // The fire-and-forget compaction below owns clearing `processing`, but a
       // throw from this initial persist never reaches it — reset here so the
       // conversation isn't stranded in queued mode.
-      conversation.processing = false;
+      conversation.setProcessing(false);
       silentlyWithLog(conversation.drainQueue(), "compact-command queue drain");
       throw err;
     }
-    conversation.getMessages().push(cleanMsg);
+    if (persisted.deduplicated) {
+      conversation.setProcessing(false);
+      silentlyWithLog(conversation.drainQueue(), "compact-dedup queue drain");
+      return {
+        accepted: true,
+        messageId: persisted.id,
+        conversationId: mapping.conversationId,
+      };
+    }
 
     const conversationId = mapping.conversationId;
+    const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+      trustContext: conversation.trustContext,
+    });
 
     // Fire-and-forget: return 202 immediately, run compaction async.
     // forceCompact() makes an LLM call that can exceed the client's
@@ -1870,14 +2004,8 @@ export async function handleSendMessage(
           clientMessageId,
         });
         publishConversationMessagesChanged(conversationId, originClientId);
-        conversation.emitActivityState(
-          "thinking",
-          "context_compacting",
-          "assistant_turn",
-        );
-        const result = await conversation.forceCompact({
-          targetInputTokensOverride: slashResult.targetInputTokensOverride,
-        });
+        conversation.emitActivityState("thinking", "context_compacting");
+        const result = await conversation.forceCompact();
         const responseText = formatCompactResult(result);
 
         const assistantMsg = createAssistantMessage(responseText);
@@ -1885,7 +2013,7 @@ export async function handleSendMessage(
           conversationId,
           "assistant",
           JSON.stringify(assistantMsg.content),
-          channelMeta,
+          { metadata: channelMeta },
         );
         assistantMessagePersisted = true;
         conversation.getMessages().push(assistantMsg);
@@ -1914,7 +2042,7 @@ export async function handleSendMessage(
           retryable: true,
         });
       } finally {
-        conversation.processing = false;
+        conversation.setProcessing(false);
         silentlyWithLog(
           conversation.drainQueue(),
           "compact-command queue drain",
@@ -1930,30 +2058,37 @@ export async function handleSendMessage(
   }
 
   if (slashResult.kind === "clean") {
-    conversation.processing = true;
+    conversation.setProcessing(true);
     const conversationId = mapping.conversationId;
     // Outer try/finally guarantees the processing flag is cleared (and the
     // queue drained) on every failure path — including a throw from the
     // initial user-message persist below, which would otherwise leave the
     // conversation stuck in queued mode indefinitely.
     try {
-      const provenance = provenanceFromTrustContext(conversation.trustContext);
-      const channelMeta = {
-        ...provenance,
+      const slashMeta = {
         userMessageChannel: sourceChannel,
         assistantMessageChannel: sourceChannel,
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
       };
-      const cleanMsg = createUserMessage(rawContent, attachments);
-      const persisted = await addMessage(
-        mapping.conversationId,
-        "user",
-        JSON.stringify(cleanMsg.content),
-        channelMeta,
-      );
-      conversation.getMessages().push(cleanMsg);
+      const persisted = await persistQueuedMessageBody(conversation, {
+        content: rawContent,
+        attachments,
+        requestId: crypto.randomUUID(),
+        metadata: slashMeta,
+        clientMessageId,
+      });
+      if (persisted.deduplicated) {
+        return {
+          accepted: true,
+          messageId: persisted.id,
+          conversationId,
+        };
+      }
 
+      const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
+        trustContext: conversation.trustContext,
+      });
       let assistantMessagePersisted = false;
       try {
         broadcastMessage({
@@ -1973,7 +2108,7 @@ export async function handleSendMessage(
           conversationId,
           "assistant",
           JSON.stringify(assistantMsg.content),
-          channelMeta,
+          { metadata: channelMeta },
         );
         assistantMessagePersisted = true;
         conversation.getMessages().push(assistantMsg);
@@ -2009,7 +2144,7 @@ export async function handleSendMessage(
         conversationId,
       };
     } finally {
-      conversation.processing = false;
+      conversation.setProcessing(false);
       silentlyWithLog(conversation.drainQueue(), "clean-command queue drain");
     }
   }
@@ -2017,16 +2152,22 @@ export async function handleSendMessage(
   const resolvedContent = slashResult.content;
 
   const requestId = crypto.randomUUID();
-  let messageId: string;
-  try {
-    messageId = await conversation.persistUserMessage(
-      resolvedContent,
-      attachments,
-      requestId,
-      body.automated === true ? { automated: true } : undefined,
-    );
-  } catch (err) {
-    throw err;
+  const persistResult = await conversation.persistUserMessage({
+    content: resolvedContent,
+    attachments,
+    requestId,
+    metadata: body.automated === true ? { automated: true } : undefined,
+    clientMessageId,
+  });
+
+  const messageId = persistResult.id;
+
+  if (persistResult.deduplicated) {
+    return {
+      accepted: true,
+      messageId,
+      conversationId: mapping.conversationId,
+    };
   }
 
   broadcastMessage({
@@ -2041,7 +2182,8 @@ export async function handleSendMessage(
 
   // Fire-and-forget the agent loop; events flow to the hub via broadcastMessage.
   conversation
-    .runAgentLoop(resolvedContent, messageId, broadcastMessage, {
+    .runAgentLoop(resolvedContent, messageId, {
+      onEvent: broadcastMessage,
       isInteractive,
       isUserMessage: true,
     })
@@ -2088,8 +2230,8 @@ async function generateLlmSuggestion(
     "",
     "CRITICAL — write from the USER'S perspective only, NEVER from the assistant's:",
     "- The suggestion is what the USER will type into the chat input",
-    "- Use first-person \"I\" only if the user has used it in their prior messages",
-    "- NEVER start with phrases like \"I can help\", \"Here's what\", \"Let me\", \"I'd suggest\" — those are assistant-voice",
+    '- Use first-person "I" only if the user has used it in their prior messages',
+    '- NEVER start with phrases like "I can help", "Here\'s what", "Let me", "I\'d suggest" — those are assistant-voice',
     "- Think: if you were the user reading the assistant's reply, what question or follow-up would you ask next?",
     "",
     "Output only the reply text inside the requested tags — no preamble, no commentary.",
@@ -2119,9 +2261,10 @@ async function generateLlmSuggestion(
   // tokens here would be wasteful.
   const response = await provider.sendMessage(
     [{ role: "user", content: [{ type: "text", text: userPrompt }] }],
-    [], // no tools
-    systemPrompt,
     {
+      tools: [],
+      // no tools
+      systemPrompt,
       config: {
         callSite: "replySuggestion",
         max_tokens: 60,
@@ -2342,6 +2485,47 @@ function handleSearchConversations({
   return { query, results };
 }
 
+// ---------------------------------------------------------------------------
+// Metadata helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Assemble the standard channel metadata object for message persistence.
+ *
+ * Combines provenance (trust context), channel/interface routing, and
+ * optional per-message fields (automated flag, image source paths) into the
+ * Record that `addMessage` stores in the `metadata` column.
+ */
+function buildChannelMetadata(
+  sourceChannel: string,
+  sourceInterface: string,
+  opts?: {
+    trustContext?: Parameters<typeof provenanceFromTrustContext>[0];
+    provenanceOverride?: Record<string, unknown>;
+    automated?: boolean;
+    attachments?: ReadonlyArray<{
+      filename: string;
+      mimeType: string;
+      filePath?: string;
+    }>;
+  },
+): Record<string, unknown> {
+  const provenance =
+    opts?.provenanceOverride ?? provenanceFromTrustContext(opts?.trustContext);
+  const imageSourcePaths = opts?.attachments
+    ? extractImageSourcePaths(opts.attachments)
+    : undefined;
+  return {
+    ...provenance,
+    userMessageChannel: sourceChannel,
+    assistantMessageChannel: sourceChannel,
+    userMessageInterface: sourceInterface,
+    assistantMessageInterface: sourceInterface,
+    ...(opts?.automated ? { automated: true } : {}),
+    ...(imageSourcePaths ? { imageSourcePaths } : {}),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Module-level state
 // ---------------------------------------------------------------------------
@@ -2372,12 +2556,54 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "messages_get",
     endpoint: "messages",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List messages",
     description:
       "Return messages for a conversation, including attachments and interface file metadata.",
     tags: ["messages"],
+    queryParams: [
+      {
+        name: "conversationId",
+        type: "string",
+        required: false,
+        description:
+          "Conversation UUID. One of conversationId or conversationKey is required.",
+      },
+      {
+        name: "conversationKey",
+        type: "string",
+        required: false,
+        description:
+          "Channel/external conversation key. One of conversationId or conversationKey is required.",
+      },
+      {
+        name: "page",
+        type: "string",
+        required: false,
+        description:
+          "When set to 'latest', returns the most recent page of messages with pagination metadata.",
+      },
+      {
+        name: "beforeTimestamp",
+        type: "integer",
+        required: false,
+        description:
+          "Return messages older than this timestamp (ms since epoch). Used for paging older history.",
+      },
+      {
+        name: "limit",
+        type: "integer",
+        required: false,
+        description: "Maximum number of messages to return.",
+      },
+    ],
     responseBody: z.object({
-      messages: z.array(z.unknown()).describe("Array of message objects"),
+      messages: z
+        .array(ConversationMessageSchema)
+        .describe("Array of message objects"),
       hasMore: z
         .boolean()
         .optional()
@@ -2394,6 +2620,13 @@ export const ROUTES: RouteDefinition[] = [
         .nullable()
         .optional()
         .describe("ID of the oldest message in this page"),
+      seq: z
+        .number()
+        .nullable()
+        .optional()
+        .describe(
+          "Global SSE `seq` of the last event whose content is durably persisted for this conversation in the current daemon process. A client can align this snapshot with the `/events` stream by applying only events with `seq` greater than this value. Null when no events have been persisted in this process (cold conversation, after a daemon restart, or when the conversation has aged out of the in-memory map) — clients should cold-start in that case. Absent on older daemons that predate this field.",
+        ),
     }),
     handler: (args) => handleListMessages(args),
   },
@@ -2401,23 +2634,70 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "messages_post",
     endpoint: "messages",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Send a message",
     description:
       "Send a user message to a conversation and trigger the assistant response.",
     tags: ["messages"],
     responseStatus: "202",
     requestBody: z.object({
-      conversationKey: z.string().optional(),
+      conversationId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe(
+          "Internal conversation id (0.8.6+ strict lookup). Omit both id and key to mint a new conversation server-side.",
+        ),
+      conversationKey: z.string().nullable().optional(),
       content: z.string().describe("Message text content"),
       attachments: z
         .array(z.unknown())
-        .describe("Optional file attachments")
+        .describe("Optional inline file attachments")
+        .optional(),
+      attachmentIds: z
+        .array(z.string())
+        .describe("Ids of previously uploaded attachments to attach")
         .optional(),
+      sourceChannel: z
+        .string()
+        .describe('Originating channel id (e.g. "vellum")'),
+      interface: z
+        .string()
+        .describe('Originating interface id (e.g. "vellum")'),
       conversationType: z.string().optional(),
       slashCommand: z.string().optional(),
       clientTimezone: z.string().optional(),
       inferenceProfile: z.string().nullable().optional(),
       riskThreshold: z.enum(VALID_RISK_THRESHOLDS).optional(),
+      onboarding: z
+        .object({
+          tools: z.array(z.string()),
+          tasks: z.array(z.string()),
+          tone: z.string(),
+          userName: z.string().optional(),
+          assistantName: z.string().optional(),
+          googleConnected: z.boolean().optional(),
+          googleScopes: z.array(z.string()).optional(),
+          priorAssistants: z.array(z.string()).optional(),
+          cohort: z.string().optional(),
+          websiteUrl: z.string().optional(),
+          contentSourceUrl: z.string().optional(),
+          bootstrapTemplate: z.string().optional(),
+          initialMessage: z.string().optional(),
+          skills: z.array(z.string()).optional(),
+        })
+        .describe("PreChat onboarding context, sent on the first message only")
+        .optional(),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+      conversationId: z.string().optional(),
+      messageId: z.string().optional(),
+      queued: z.boolean().optional(),
+      requestId: z.string().optional(),
     }),
     handler: async (args) =>
       handleSendMessage(args, {
@@ -2433,6 +2713,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "search_get",
     endpoint: "search",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Search conversations",
     description: "Full-text search across all conversations.",
     tags: ["conversations"],
@@ -2446,6 +2730,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "suggestion_get",
     endpoint: "suggestion",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get reply suggestion",
     description:
       "Return an LLM-generated follow-up suggestion for the most recent assistant message.",