@vellumai/assistant 0.8.3 → 0.8.5

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

@@ -1,14 +1,7 @@
 /**
  * Route handlers for conversation messages and suggestions.
  */
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 
 import { z } from "zod";
 
@@ -27,10 +20,15 @@ import {
 } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getConfig } from "../../config/loader.js";
+import {
+  mergeConsecutiveAssistantMessages,
+  mergeToolResultsIntoAssistantMessages,
+} from "../../conversations/message-consolidation.js";
 import { createApprovalConversationGenerator } from "../../daemon/approval-generators.js";
 import type { Conversation } from "../../daemon/conversation.js";
 import {
   buildModelInfoEvent,
+  formatCleanResult,
   formatCompactResult,
   isModelSlashCommand,
 } from "../../daemon/conversation-process.js";
@@ -41,6 +39,7 @@ import {
 import { getOrCreateConversation as getOrCreateConversationInstance } from "../../daemon/conversation-store.js";
 import { canonicalizeTimeZone } from "../../daemon/date-context.js";
 import {
+  buildScanFirstMessage,
   getCannedFirstGreeting,
   isWakeUpGreeting,
 } from "../../daemon/first-greeting.js";
@@ -51,6 +50,7 @@ import {
   preactivateHostProxySkills,
   shouldAttachHostProxyForCapability,
 } from "../../daemon/host-proxy-preactivation.js";
+import { getAssistantName } from "../../daemon/identity-helpers.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import type {
   HostProxyTransportMetadata,
@@ -75,7 +75,7 @@ import {
 } from "../../memory/canonical-guardian-store.js";
 import {
   addMessage,
-  getLastAssistantTimestampBefore,
+  getConversation,
   getMessages,
   getMessagesPaginated,
   hasMessages,
@@ -103,10 +103,7 @@ 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 {
-  getInterfacesDir,
-  getWorkspacePromptPath,
-} from "../../util/platform.js";
+import { 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";
@@ -128,7 +125,12 @@ import {
   resolveTrustContext,
   withSourceChannel,
 } from "../trust-context-resolver.js";
-import { BadRequestError, InternalError, RouteError } from "./errors.js";
+import {
+  BadRequestError,
+  InternalError,
+  NotFoundError,
+  RouteError,
+} from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
 
@@ -136,6 +138,7 @@ const log = getLogger("conversation-routes");
 
 /** Matches the `<no_response/>` sentinel used by channel delivery suppression. */
 const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/g;
+const ATTACHMENT_ENTRY_RE = /^attachment:(\d+)$/;
 
 const SUGGESTION_CACHE_MAX = 100;
 const VALID_RISK_THRESHOLDS = ["none", "low", "medium", "high"] as const;
@@ -148,31 +151,95 @@ function isValidRiskThreshold(value: unknown): value is RiskThreshold {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Temporary fix — remove when #31994 lands
+// ---------------------------------------------------------------------------
+//
+// The canned-response paths in this file (canned greeting, inline approval
+// reply, slash command, /compact, /clean) bypass the agent loop and so don't
+// pick up the per-turn anchor id allocated in conversation-agent-loop.ts.
+// Their `message_complete` events therefore went out without `messageId`,
+// and the macOS client filter at ChatActionHandler.swift:507 dropped those
+// events when they raced past the 50 ms streaming-buffer flush — leaving
+// `isSending` stuck for the full 60 s watchdog window.
+//
+// Centralized so the patch surface is one helper + N one-line callers rather
+// than N duplicated literals. When #31994 lands and stamps these sites with
+// `state.assistantTurnId` directly, grep for `emitCannedMessageComplete` to
+// find every call site and inline-then-delete.
+function emitCannedMessageComplete(
+  send: (msg: ServerMessage) => void,
+  conversationId: string,
+  persistedAssistantId: string,
+): void {
+  send({
+    type: "message_complete",
+    conversationId,
+    messageId: persistedAssistantId,
+  });
+}
+
+/**
+ * True when a message's persisted metadata explicitly flags it as hidden.
+ * Used to suppress internal scaffolding messages from UI history while
+ * leaving them in the LLM-side context.
+ */
+function isHiddenMessage(metadata: string | null): boolean {
+  if (!metadata) return false;
+  try {
+    const meta = JSON.parse(metadata) as { hidden?: unknown };
+    return meta?.hidden === true;
+  } catch {
+    return false;
+  }
+}
+
 function buildSlackHistoryMessage(
   slackMeta: SlackMessageMetadata | null,
+  opts?: { role?: string; assistantDisplayName?: string },
 ): RuntimeMessagePayload["slackMessage"] | undefined {
   if (!slackMeta) return undefined;
 
   const slackConfig = getConfig().slack;
+  const replyThreadTs =
+    slackMeta.threadTs && slackMeta.threadTs !== slackMeta.channelTs
+      ? slackMeta.threadTs
+      : undefined;
   const messageLink = buildSlackMessageDeepLinks({
     teamId: slackConfig?.teamId,
     teamUrl: slackConfig?.teamUrl,
     channelId: slackMeta.channelId,
     messageTs: slackMeta.channelTs,
+    ...(replyThreadTs ? { threadTs: replyThreadTs } : {}),
   });
-  const threadLink = slackMeta.threadTs
+  const threadLink = replyThreadTs
     ? buildSlackMessageDeepLinks({
         teamId: slackConfig?.teamId,
         teamUrl: slackConfig?.teamUrl,
         channelId: slackMeta.channelId,
-        messageTs: slackMeta.threadTs,
+        messageTs: replyThreadTs,
       })
     : undefined;
+  const assistantDisplayName =
+    opts?.role === "assistant" ? opts.assistantDisplayName : undefined;
+  const senderDisplayName =
+    slackMeta.displayName?.trim() || assistantDisplayName;
 
   return {
     channelId: slackMeta.channelId,
+    ...(slackMeta.channelName ? { channelName: slackMeta.channelName } : {}),
     channelTs: slackMeta.channelTs,
     ...(slackMeta.threadTs ? { threadTs: slackMeta.threadTs } : {}),
+    ...(senderDisplayName || slackMeta.actorExternalUserId
+      ? {
+          sender: {
+            ...(senderDisplayName ? { displayName: senderDisplayName } : {}),
+            ...(slackMeta.actorExternalUserId
+              ? { externalUserId: slackMeta.actorExternalUserId }
+              : {}),
+          },
+        }
+      : {}),
     ...(messageLink ? { messageLink } : {}),
     ...(threadLink ? { threadLink } : {}),
   };
@@ -253,6 +320,8 @@ async function tryConsumeCanonicalGuardianReply(params: {
   verifiedActorExternalUserId?: string;
   /** Verified actor principal ID for principal-based authorization. */
   verifiedActorPrincipalId?: string;
+  /** Originating client identifier for sync_changed self-echo suppression. */
+  originClientId?: string;
 }): Promise<{ consumed: boolean; messageId?: string }> {
   const {
     conversationId,
@@ -265,6 +334,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
     approvalConversationGenerator,
     verifiedActorExternalUserId,
     verifiedActorPrincipalId,
+    originClientId,
   } = params;
   const trimmedContent = content.trim();
 
@@ -362,7 +432,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
         ? "Decision applied."
         : "Request already resolved.");
     const assistantMessage = createAssistantMessage(replyText);
-    await addMessage(
+    const persistedAssistant = await addMessage(
       conversationId,
       "assistant",
       JSON.stringify(assistantMessage.content),
@@ -377,9 +447,9 @@ async function tryConsumeCanonicalGuardianReply(params: {
         text: replyText,
         conversationId: conversationId,
       });
-      onEvent({ type: "message_complete", conversationId: conversationId });
+      emitCannedMessageComplete(onEvent, conversationId, persistedAssistant.id);
     }
-    publishConversationMessagesChanged(conversationId);
+    publishConversationMessagesChanged(conversationId, originClientId);
   } catch (err) {
     log.warn(
       { err, conversationId },
@@ -390,32 +460,9 @@ async function tryConsumeCanonicalGuardianReply(params: {
   return { consumed: true, messageId };
 }
 
-function getInterfaceFilesWithMtimes(
-  interfacesDir: string | null,
-): Array<{ path: string; mtimeMs: number }> {
-  if (!interfacesDir || !existsSync(interfacesDir)) return [];
-  const results: Array<{ path: string; mtimeMs: number }> = [];
-  const scan = (dir: string): void => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const fullPath = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        scan(fullPath);
-      } else {
-        results.push({
-          path: relative(interfacesDir, fullPath),
-          mtimeMs: statSync(fullPath).mtimeMs,
-        });
-      }
-    }
-  };
-  scan(interfacesDir);
-  return results;
-}
-
-export function handleListMessages(
-  { queryParams }: RouteHandlerArgs,
-  interfacesDir: string | null,
-): Record<string, unknown> {
+export function handleListMessages({
+  queryParams,
+}: RouteHandlerArgs): Record<string, unknown> {
   const conversationId = queryParams?.conversationId;
   const conversationKey = queryParams?.conversationKey;
 
@@ -423,8 +470,20 @@ export function handleListMessages(
   if (conversationId) {
     resolvedConversationId = conversationId;
   } else if (conversationKey) {
+    // Dual lookup, key-first: prefer the `conversation_keys` table — the
+    // canonical channel/external → internal-id mapping — so legacy or
+    // externally-sourced keys keep their explicit mapping precedence and
+    // never collide with an unrelated `conversations.id`. Fall back to a
+    // direct id lookup only when no mapping exists, which covers
+    // background/scheduled conversations bootstrapped without a
+    // `conversation_keys` row (web clients use the conversation list's
+    // `id` as `conversationKey` for those).
     const mapping = getConversationByKey(conversationKey);
-    resolvedConversationId = mapping?.conversationId;
+    if (mapping) {
+      resolvedConversationId = mapping.conversationId;
+    } else if (getConversation(conversationKey)) {
+      resolvedConversationId = conversationKey;
+    }
   } else {
     throw new BadRequestError(
       "conversationKey or conversationId query parameter is required",
@@ -480,16 +539,30 @@ export function handleListMessages(
   let rawMessages: MessageRow[];
   let hasMore = false;
 
+  // Drop messages flagged as hidden in metadata (e.g. internal scaffolding
+  // like retrospective instructions). The LLM-side history loader
+  // (`getMessages` in memory/conversation-crud.ts) intentionally does not
+  // filter — hidden messages remain in agent context but are suppressed from
+  // the UI list. Filtering is pushed into the paginated query so `hasMore`
+  // and the cursor reflect visible rows; otherwise a fully-hidden page would
+  // return `hasMore: true` with no cursor and stall the web client.
+  // Hidden tool_use/tool_result pairs must be hidden together — if a hidden
+  // 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);
+
   if (isPaginated) {
     const result = getMessagesPaginated(
       resolvedConversationId,
       limit,
       beforeTimestamp,
+      visibleFilter,
     );
     rawMessages = result.messages;
     hasMore = result.hasMore;
   } else {
-    rawMessages = getMessages(resolvedConversationId);
+    rawMessages = getMessages(resolvedConversationId).filter(visibleFilter);
   }
 
   // During streaming, tool_use (assistant) and tool_result (user) events are
@@ -508,6 +581,7 @@ export function handleListMessages(
   // (consecutive tool refs grouped together).
   const { messages: consolidatedMessages, mergedIdMap } =
     mergeConsecutiveAssistantMessages(mergedMessages);
+  const assistantSlackDisplayName = getAssistantName()?.trim() || undefined;
 
   // Parse content blocks and extract text + tool calls
   const parsed = consolidatedMessages.map((msg) => {
@@ -559,6 +633,10 @@ export function handleListMessages(
     }
     const slackMessage = buildSlackHistoryMessage(
       readSlackMetadataFromMessageMetadata(msg.metadata),
+      {
+        role: msg.role,
+        assistantDisplayName: assistantSlackDisplayName,
+      },
     );
 
     // Strip <no_response/> markers from assistant messages so web/API
@@ -599,6 +677,7 @@ export function handleListMessages(
         textSegments: filteredSegments,
         contentOrder: filteredContentOrder,
         surfaces: rendered.surfaces,
+        attachmentRefs: rendered.attachments,
         slackMessage,
         ...(rendered.thinkingSegments.length > 0
           ? { thinkingSegments: rendered.thinkingSegments }
@@ -618,6 +697,7 @@ export function handleListMessages(
       textSegments: rendered.textSegments,
       contentOrder: rendered.contentOrder,
       surfaces: rendered.surfaces,
+      attachmentRefs: rendered.attachments,
       slackMessage,
       ...(rendered.thinkingSegments.length > 0
         ? { thinkingSegments: rendered.thinkingSegments }
@@ -627,15 +707,6 @@ export function handleListMessages(
     };
   });
 
-  const interfaceFiles = getInterfaceFilesWithMtimes(interfacesDir);
-
-  let prevAssistantTimestamp = 0;
-  if (isPaginated && rawMessages.length > 0) {
-    prevAssistantTimestamp = getLastAssistantTimestampBefore(
-      resolvedConversationId!,
-      rawMessages[0].createdAt,
-    );
-  }
   const messages: RuntimeMessagePayload[] = parsed.map((m) => {
     let msgAttachments: RuntimeAttachmentMetadata[] = [];
     if (m.id) {
@@ -682,19 +753,76 @@ export function handleListMessages(
       }
     }
 
-    let interfaces: string[] | undefined;
-    if (m.role === "assistant") {
-      const msgTimestamp = new Date(m.timestamp).getTime();
-      const dirtied = interfaceFiles
-        .filter(
-          (f) =>
-            f.mtimeMs > prevAssistantTimestamp && f.mtimeMs <= msgTimestamp,
-        )
-        .map((f) => f.path);
-      if (dirtied.length > 0) {
-        interfaces = dirtied;
+    // 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);
+        }
+        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),
+        );
       }
-      prevAssistantTimestamp = msgTimestamp;
+    } 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),
+      );
     }
 
     // Use sentAt (actual event time) for the display timestamp when
@@ -704,26 +832,21 @@ export function handleListMessages(
     // 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 mergedMessageIds = mergedIdMap.get(m.id) ?? [];
-    const daemonMessageId =
-      m.role === "assistant"
-        ? (mergedMessageIds[mergedMessageIds.length - 1] ?? m.id)
-        : undefined;
     return {
       id: m.id ?? "",
-      ...(daemonMessageId ? { daemonMessageId } : {}),
       role: m.role,
       content: m.text,
       timestamp: new Date(displayTimestamp).toISOString(),
       attachments: msgAttachments,
       ...(m.toolCalls.length > 0 ? { toolCalls: m.toolCalls } : {}),
-      ...(interfaces ? { interfaces } : {}),
       ...(m.surfaces.length > 0 ? { surfaces: m.surfaces } : {}),
       ...(m.textSegments.length > 0 ? { textSegments: m.textSegments } : {}),
       ...(m.thinkingSegments?.length
         ? { thinkingSegments: m.thinkingSegments }
         : {}),
-      ...(m.contentOrder.length > 0 ? { contentOrder: m.contentOrder } : {}),
+      ...(alignedContentOrder.length > 0
+        ? { contentOrder: alignedContentOrder }
+        : {}),
       ...(m.subagentNotification
         ? { subagentNotification: m.subagentNotification }
         : {}),
@@ -760,305 +883,6 @@ export function handleListMessages(
   return { messages };
 }
 
-// ── Tool-result merging ─────────────────────────────────────────────
-
-function isToolResultType(type: string): boolean {
-  return type === "tool_result" || type === "web_search_tool_result";
-}
-
-function isSystemNoticeText(block: Record<string, unknown>): boolean {
-  if (block.type !== "text") return false;
-  const text = typeof block.text === "string" ? block.text : "";
-  return (
-    text.startsWith("<system_notice>") && text.endsWith("</system_notice>")
-  );
-}
-
-/**
- * Merge tool_result blocks from user messages into the preceding assistant
- * message's content array. This lets renderHistoryContent's pendingToolUses
- * map pair tool_use and tool_result blocks, preventing "unknown" tool names.
- *
- * User messages that consist entirely of tool_result blocks (and optional
- * system_notice text) are removed from the output. Mixed messages (tool_result
- * + real user text) keep only the non-tool-result blocks.
- */
-function mergeToolResultsIntoAssistantMessages(
-  messages: MessageRow[],
-): MessageRow[] {
-  // Index of the most recent assistant message in the output array.
-  let lastAssistantIdx = -1;
-  // Parsed content caches — lazily populated per assistant message.
-  const parsedAssistantContent = new Map<number, unknown[]>();
-
-  const result: MessageRow[] = [];
-
-  for (const msg of messages) {
-    if (msg.role === "assistant") {
-      lastAssistantIdx = result.length;
-      result.push(msg);
-      continue;
-    }
-
-    // Only process user messages — other roles pass through.
-    if (msg.role !== "user") {
-      result.push(msg);
-      continue;
-    }
-
-    let blocks: unknown[];
-    try {
-      const parsed = JSON.parse(msg.content);
-      if (!Array.isArray(parsed)) {
-        result.push(msg);
-        continue;
-      }
-      blocks = parsed;
-    } catch {
-      result.push(msg);
-      continue;
-    }
-
-    // Separate tool-result blocks from real user content.
-    const toolResultBlocks: unknown[] = [];
-    const otherBlocks: unknown[] = [];
-    for (const block of blocks) {
-      if (
-        typeof block === "object" &&
-        block !== null &&
-        typeof (block as Record<string, unknown>).type === "string"
-      ) {
-        const rec = block as Record<string, unknown>;
-        if (isToolResultType(rec.type as string)) {
-          toolResultBlocks.push(block);
-        } else if (isSystemNoticeText(rec)) {
-          // System notices don't count as user content — drop them when
-          // the message is otherwise tool-result-only.
-          otherBlocks.push(block);
-        } else {
-          otherBlocks.push(block);
-        }
-      } else {
-        otherBlocks.push(block);
-      }
-    }
-
-    // No tool results → pass through unchanged. System notices are only
-    // injected alongside tool results in the agent loop, so a pure user
-    // message (no tool_result blocks) should never be filtered — even if
-    // the user's text happens to look like a system_notice tag.
-    if (toolResultBlocks.length === 0) {
-      result.push(msg);
-      continue;
-    }
-
-    // Append tool_result blocks to the preceding assistant message's content.
-    if (lastAssistantIdx >= 0) {
-      const assistant = result[lastAssistantIdx];
-      let assistantContent = parsedAssistantContent.get(lastAssistantIdx);
-      if (!assistantContent) {
-        try {
-          const parsed = JSON.parse(assistant.content);
-          assistantContent = Array.isArray(parsed) ? parsed : [parsed];
-        } catch {
-          assistantContent = [];
-        }
-        parsedAssistantContent.set(lastAssistantIdx, assistantContent);
-      }
-      assistantContent.push(...toolResultBlocks);
-    } else {
-      // No preceding assistant message (pagination boundary) — keep the
-      // original message as-is to avoid permanent data loss. The preceding
-      // assistant tool_use lives in the previous page; dropping the result
-      // here would be unrecoverable.
-      // Still strip system notices so internal prompt text isn't exposed.
-      const filteredBlocks = blocks.filter(
-        (b) =>
-          !(
-            typeof b === "object" &&
-            b !== null &&
-            isSystemNoticeText(b as Record<string, unknown>)
-          ),
-      );
-      result.push({
-        ...msg,
-        content:
-          filteredBlocks.length === blocks.length
-            ? msg.content
-            : JSON.stringify(filteredBlocks),
-      });
-      continue;
-    }
-
-    // If the user message had only tool_result (+ system_notice) blocks,
-    // suppress it entirely. Otherwise keep the non-tool-result content.
-    const realUserContent = otherBlocks.filter(
-      (b) =>
-        !(
-          typeof b === "object" &&
-          b !== null &&
-          isSystemNoticeText(b as Record<string, unknown>)
-        ),
-    );
-    if (realUserContent.length > 0) {
-      result.push({ ...msg, content: JSON.stringify(otherBlocks) });
-    }
-    // else: tool-result-only → suppressed (results already merged above)
-  }
-
-  // Write back any modified assistant message content.
-  for (const [idx, content] of parsedAssistantContent) {
-    result[idx] = { ...result[idx], content: JSON.stringify(content) };
-  }
-
-  return result;
-}
-
-// ── Consecutive assistant message merging ────────────────────────────
-
-/** Parse a message's JSON content into an array of content blocks. */
-function parseContentBlocks(content: string): unknown[] {
-  try {
-    const parsed = JSON.parse(content);
-    return Array.isArray(parsed) ? parsed : [parsed];
-  } catch (err) {
-    log.warn(
-      { err },
-      "Failed to parse content blocks during assistant message merge",
-    );
-    return [];
-  }
-}
-
-/**
- * Append content blocks from a donor message onto a target block array.
- * Parses the donor's JSON content and pushes each block into `target`.
- */
-function appendContentBlocks(target: unknown[], donorContent: string): void {
-  try {
-    const parsed = JSON.parse(donorContent);
-    if (Array.isArray(parsed)) {
-      target.push(...parsed);
-    } else {
-      target.push(parsed);
-    }
-  } catch (err) {
-    log.warn(
-      { err },
-      "Failed to parse donor content blocks during assistant message merge",
-    );
-  }
-}
-
-/**
- * Promote metadata fields from a donor message to the surviving message
- * when the survivor lacks them. Currently promotes `subagentNotification`.
- * Returns a new MessageRow if promotion occurred, otherwise the original.
- */
-function promoteMetadata(survivor: MessageRow, donor: MessageRow): MessageRow {
-  if (donor.metadata && survivor.metadata) {
-    try {
-      const survivorMeta = JSON.parse(survivor.metadata);
-      const donorMeta = JSON.parse(donor.metadata);
-      if (
-        !survivorMeta.subagentNotification &&
-        donorMeta.subagentNotification
-      ) {
-        survivorMeta.subagentNotification = donorMeta.subagentNotification;
-        return { ...survivor, metadata: JSON.stringify(survivorMeta) };
-      }
-    } catch (err) {
-      log.warn(
-        { err },
-        "Failed to parse metadata during assistant message merge",
-      );
-    }
-  } else if (donor.metadata && !survivor.metadata) {
-    return { ...survivor, metadata: donor.metadata };
-  }
-  return survivor;
-}
-
-/**
- * Merge consecutive assistant messages into a single message at query time.
- *
- * During streaming, all assistant turns within one agent loop accumulate on
- * a single client-side ChatMessage. In the DB, each API turn is stored as a
- * separate assistant row (consolidation is deferred to compaction for
- * prefix-cache stability). This produces N separate assistant messages that
- * the client renders as N individual bubbles — each showing "Completed 1
- * step" instead of one grouped "Completed N steps" accordion.
- *
- * This function concatenates the content block arrays of consecutive
- * assistant messages (no intervening user messages after tool-result
- * merging) into the first message of each run. The merged messages are
- * removed from the output. This is query-time only — the DB is not
- * modified.
- *
- * The first message in each run keeps its id, createdAt, and metadata so
- * that attachment lookups, display timestamps, and subagent notifications
- * continue to work. Metadata from later messages in the run (e.g.
- * subagentNotification) is preserved by promoting it to the surviving
- * message when the surviving message has no metadata of its own for that
- * field.
- */
-function mergeConsecutiveAssistantMessages(messages: MessageRow[]): {
-  messages: MessageRow[];
-  /** Maps each surviving message ID → all original message IDs merged into it. */
-  mergedIdMap: Map<string, string[]>;
-} {
-  const result: MessageRow[] = [];
-  // Key = index in `result`, value = accumulated content blocks.
-  const pendingMerges = new Map<number, unknown[]>();
-  // Key = index in `result`, value = IDs of messages merged into the target.
-  const mergedIds = new Map<number, string[]>();
-
-  for (const msg of messages) {
-    const lastIdx = result.length - 1;
-    const isConsecutiveAssistant =
-      msg.role === "assistant" &&
-      lastIdx >= 0 &&
-      result[lastIdx].role === "assistant";
-
-    if (!isConsecutiveAssistant) {
-      result.push(msg);
-      continue;
-    }
-
-    // Track the donor message ID.
-    let ids = mergedIds.get(lastIdx);
-    if (!ids) {
-      ids = [];
-      mergedIds.set(lastIdx, ids);
-    }
-    ids.push(msg.id);
-
-    // Lazily parse the target's content on first merge.
-    let targetContent = pendingMerges.get(lastIdx);
-    if (!targetContent) {
-      targetContent = parseContentBlocks(result[lastIdx].content);
-      pendingMerges.set(lastIdx, targetContent);
-    }
-
-    appendContentBlocks(targetContent, msg.content);
-    result[lastIdx] = promoteMetadata(result[lastIdx], msg);
-  }
-
-  // Write back merged content for any messages that were targets.
-  for (const [idx, content] of pendingMerges) {
-    result[idx] = { ...result[idx], content: JSON.stringify(content) };
-  }
-
-  // Build the merged ID map keyed by surviving message ID.
-  const mergedIdMap = new Map<string, string[]>();
-  for (const [idx, ids] of mergedIds) {
-    mergedIdMap.set(result[idx].id, ids);
-  }
-
-  return { messages: result, mergedIdMap };
-}
-
-/**
 /**
  * Persist the pre-chat onboarding payload to disk.
  *
@@ -1092,6 +916,10 @@ export function persistOnboardingArtifacts(onboarding: {
   tone: string;
   userName?: string;
   assistantName?: string;
+  priorAssistants?: string[];
+  cohort?: string;
+  websiteUrl?: string;
+  contentSourceUrl?: string;
 }): void {
   writeOnboardingSidecar(onboarding);
 
@@ -1147,6 +975,7 @@ export async function handleSendMessage(
 ): Promise<unknown> {
   const body = (rawBody ?? {}) as {
     conversationKey?: string;
+    conversationId?: string;
     content?: string;
     attachmentIds?: string[];
     sourceChannel?: string;
@@ -1169,13 +998,23 @@ export async function handleSendMessage(
       assistantName?: string;
       googleConnected?: boolean;
       googleScopes?: string[];
+      priorAssistants?: string[];
+      cohort?: string;
+      websiteUrl?: string;
+      contentSourceUrl?: 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 { conversationKey, content, attachmentIds } = body;
+  const inboundConversationId =
+    typeof body.conversationId === "string" && body.conversationId.length > 0
+      ? body.conversationId
+      : undefined;
   const clientMessageId =
     typeof body.clientMessageId === "string" ? body.clientMessageId : undefined;
   const requestedInferenceProfile =
@@ -1243,12 +1082,6 @@ export async function handleSendMessage(
       ? (canonicalizeTimeZone(body.clientTimezone) ?? undefined)
       : undefined;
 
-  // When conversationKey is omitted, derive a stable default from
-  // sourceChannel + sourceInterface so that repeated calls from the same
-  // channel/interface pair share a single conversation thread.
-  const resolvedConversationKey =
-    conversationKey ?? `default:${sourceChannel}:${sourceInterface}`;
-
   // Reject non-string content values (numbers, objects, etc.)
   if (content != null && typeof content !== "string") {
     throw new BadRequestError("content must be a string");
@@ -1312,9 +1145,40 @@ export async function handleSendMessage(
   // timer so the next heartbeat is a full interval after this interaction.
   HeartbeatService.getInstance()?.resetTimer();
 
-  const mapping = getOrCreateConversation(resolvedConversationKey, {
-    conversationType: "standard",
-  });
+  // Resolve the target conversation. Fetch by `conversationId` (the
+  // 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.
+  let mapping: {
+    conversationId: string;
+    conversationType: string;
+    created: boolean;
+  };
+  if (inboundConversationId !== undefined) {
+    const existing = getConversation(inboundConversationId);
+    if (!existing) {
+      throw new NotFoundError(
+        `Conversation ${inboundConversationId} not found`,
+      );
+    }
+    mapping = {
+      conversationId: existing.id,
+      conversationType: existing.conversationType,
+      created: false,
+    };
+  } else {
+    const resolvedConversationKey =
+      conversationKey && conversationKey.length > 0
+        ? conversationKey
+        : `default:${sourceChannel}:${sourceInterface}`;
+    mapping = getOrCreateConversation(resolvedConversationKey, {
+      conversationType: "standard",
+    });
+  }
 
   if (requestedRiskThreshold !== undefined) {
     const result = await ipcCall("set_conversation_threshold", {
@@ -1348,6 +1212,7 @@ export async function handleSendMessage(
       publishConversationListAndMetadataChanged(
         "created",
         mapping.conversationId,
+        originClientId,
       );
     }
   }
@@ -1500,12 +1365,34 @@ export async function handleSendMessage(
     );
   }
 
-  // ── Canned first-greeting fast path ──
-  // On a completely fresh workspace, skip LLM inference for the macOS
-  // wake-up greeting and return a pre-written response. When onboarding
-  // context is present the greeting is personalized using the selections;
-  // otherwise a generic greeting is served. Both paths are instant.
-  if (isWakeUpGreeting(trimmedContent, conversation.getMessages().length)) {
+  // ── URL scan path: rewrite first message for scan onboarding ──
+  // When onboarding provides a websiteUrl or contentSourceUrl and the
+  // first message is the macOS wake-up greeting, bypass the canned
+  // greeting and rewrite the user message to a scan instruction so real
+  // LLM inference runs against the URL.
+  const sanitizeUrl = (u?: string) =>
+    u?.trim().replace(/[\r\n\t]/g, "") || undefined;
+  const websiteUrl = sanitizeUrl(body.onboarding?.websiteUrl);
+  const contentSourceUrl = sanitizeUrl(body.onboarding?.contentSourceUrl);
+  const scanUrl = websiteUrl || contentSourceUrl;
+  const isWakeUp = isWakeUpGreeting(
+    trimmedContent,
+    conversation.getMessages().length,
+  );
+  const isScanPath = !!scanUrl && isWakeUp;
+
+  let effectiveContent: string | undefined;
+  if (isScanPath) {
+    const scanVariant = websiteUrl
+      ? ("website" as const)
+      : ("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 (isWakeUp) {
     const cannedGreeting = getCannedFirstGreeting(body.onboarding ?? undefined);
 
     conversation.processing = true;
@@ -1545,7 +1432,7 @@ export async function handleSendMessage(
       const conversationId = mapping.conversationId;
 
       const assistantMsg = createAssistantMessage(cannedGreeting);
-      await addMessage(
+      const persistedAssistant = await addMessage(
         mapping.conversationId,
         "assistant",
         JSON.stringify(assistantMsg.content),
@@ -1569,6 +1456,7 @@ export async function handleSendMessage(
             tone: body.onboarding!.tone,
             googleConnected: body.onboarding!.googleConnected,
             googleScopes: body.onboarding!.googleScopes,
+            priorAssistants: body.onboarding!.priorAssistants,
           });
         } catch (err) {
           log.warn({ err }, "Failed to record onboarding telemetry event");
@@ -1588,8 +1476,12 @@ export async function handleSendMessage(
           text: cannedGreeting,
           conversationId,
         });
-        broadcastMessage({ type: "message_complete", conversationId });
-        publishConversationMessagesChanged(conversationId);
+        emitCannedMessageComplete(
+          broadcastMessage,
+          conversationId,
+          persistedAssistant.id,
+        );
+        publishConversationMessagesChanged(conversationId, originClientId);
         conversation.processing = false;
         silentlyWithLog(
           conversation.drainQueue(),
@@ -1623,12 +1515,18 @@ export async function handleSendMessage(
         tone: body.onboarding!.tone,
         googleConnected: body.onboarding!.googleConnected,
         googleScopes: body.onboarding!.googleScopes,
+        priorAssistants: body.onboarding!.priorAssistants,
       });
     } catch (err) {
       log.warn({ err }, "Failed to record onboarding telemetry event");
     }
   }
 
+  // When the scan path rewrote the first message, prefer the rewritten
+  // content for all downstream consumers (guardian reply, enqueue, agent
+  // loop) so they see the scan instruction rather than the wake-up greeting.
+  const contentAfterScan = effectiveContent ?? content ?? "";
+
   const attachments = hasAttachments
     ? smDeps.resolveAttachments(attachmentIds)
     : [];
@@ -1648,7 +1546,7 @@ export async function handleSendMessage(
       conversationId: mapping.conversationId,
       sourceChannel,
       sourceInterface,
-      content: content ?? "",
+      content: contentAfterScan,
       attachments,
       conversation,
       onEvent: broadcastMessage,
@@ -1661,6 +1559,7 @@ export async function handleSendMessage(
           : deps.approvalConversationGenerator,
       verifiedActorExternalUserId,
       verifiedActorPrincipalId,
+      originClientId,
     });
     if (inlineReplyResult.consumed) {
       return {
@@ -1682,7 +1581,7 @@ export async function handleSendMessage(
     // Queue the message so it's processed when the current turn completes
     const requestId = crypto.randomUUID();
     const enqueueResult = conversation.enqueueMessage(
-      content ?? "",
+      contentAfterScan,
       attachments,
       broadcastMessage,
       requestId,
@@ -1754,6 +1653,7 @@ export async function handleSendMessage(
       accepted: true,
       queued: true,
       conversationId: mapping.conversationId,
+      requestId,
     };
   }
 
@@ -1801,7 +1701,9 @@ export async function handleSendMessage(
   await conversation.ensureActorScopedHistory();
 
   // Resolve slash commands before persisting or running the agent loop.
-  const rawContent = content ?? "";
+  // `contentAfterScan` already carries the scan-rewritten content when
+  // applicable; reuse it here for consistency.
+  const rawContent = contentAfterScan;
   const slashContext = buildSlashContextForContent(rawContent, {
     conversationId: mapping.conversationId,
     messageCount: conversation.getMessages().length,
@@ -1846,7 +1748,7 @@ export async function handleSendMessage(
       conversation.getMessages().push(llmMsg);
 
       const assistantMsg = createAssistantMessage(slashResult.message);
-      await addMessage(
+      const persistedAssistant = await addMessage(
         mapping.conversationId,
         "assistant",
         JSON.stringify(assistantMsg.content),
@@ -1901,11 +1803,12 @@ export async function handleSendMessage(
           text: message,
           conversationId,
         });
-        broadcastMessage({
-          type: "message_complete",
-          conversationId: conversationId,
-        });
-        publishConversationMessagesChanged(conversationId);
+        emitCannedMessageComplete(
+          broadcastMessage,
+          conversationId,
+          persistedAssistant.id,
+        );
+        publishConversationMessagesChanged(conversationId, originClientId);
         conversation.processing = false;
         silentlyWithLog(conversation.drainQueue(), "slash-command queue drain");
       }, 0);
@@ -1933,12 +1836,22 @@ export async function handleSendMessage(
       assistantMessageInterface: sourceInterface,
     };
     const cleanMsg = createUserMessage(rawContent, attachments);
-    const persisted = await addMessage(
-      mapping.conversationId,
-      "user",
-      JSON.stringify(cleanMsg.content),
-      channelMeta,
-    );
+    let persisted: Awaited<ReturnType<typeof addMessage>>;
+    try {
+      persisted = await addMessage(
+        mapping.conversationId,
+        "user",
+        JSON.stringify(cleanMsg.content),
+        channelMeta,
+      );
+    } 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;
+      silentlyWithLog(conversation.drainQueue(), "compact-command queue drain");
+      throw err;
+    }
     conversation.getMessages().push(cleanMsg);
 
     const conversationId = mapping.conversationId;
@@ -1956,7 +1869,7 @@ export async function handleSendMessage(
           messageId: persisted.id,
           clientMessageId,
         });
-        publishConversationMessagesChanged(conversationId);
+        publishConversationMessagesChanged(conversationId, originClientId);
         conversation.emitActivityState(
           "thinking",
           "context_compacting",
@@ -1968,7 +1881,7 @@ export async function handleSendMessage(
         const responseText = formatCompactResult(result);
 
         const assistantMsg = createAssistantMessage(responseText);
-        await addMessage(
+        const persistedAssistant = await addMessage(
           conversationId,
           "assistant",
           JSON.stringify(assistantMsg.content),
@@ -1982,11 +1895,15 @@ export async function handleSendMessage(
           text: responseText,
           conversationId,
         });
-        broadcastMessage({ type: "message_complete", conversationId });
-        publishConversationMessagesChanged(conversationId);
+        emitCannedMessageComplete(
+          broadcastMessage,
+          conversationId,
+          persistedAssistant.id,
+        );
+        publishConversationMessagesChanged(conversationId, originClientId);
       } catch (err) {
         if (assistantMessagePersisted) {
-          publishConversationMessagesChanged(conversationId);
+          publishConversationMessagesChanged(conversationId, originClientId);
         }
         log.error({ err, conversationId }, "Compact command failed");
         broadcastMessage({
@@ -2012,6 +1929,91 @@ export async function handleSendMessage(
     };
   }
 
+  if (slashResult.kind === "clean") {
+    conversation.processing = 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,
+        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);
+
+      let assistantMessagePersisted = false;
+      try {
+        broadcastMessage({
+          type: "user_message_echo",
+          text: rawContent,
+          conversationId,
+          messageId: persisted.id,
+          clientMessageId,
+        });
+        publishConversationMessagesChanged(conversationId, originClientId);
+
+        const result = await conversation.forceClean();
+        const responseText = formatCleanResult(result);
+
+        const assistantMsg = createAssistantMessage(responseText);
+        const persistedAssistant = await addMessage(
+          conversationId,
+          "assistant",
+          JSON.stringify(assistantMsg.content),
+          channelMeta,
+        );
+        assistantMessagePersisted = true;
+        conversation.getMessages().push(assistantMsg);
+
+        broadcastMessage({
+          type: "assistant_text_delta",
+          text: responseText,
+          conversationId,
+        });
+        emitCannedMessageComplete(
+          broadcastMessage,
+          conversationId,
+          persistedAssistant.id,
+        );
+        publishConversationMessagesChanged(conversationId, originClientId);
+      } catch (err) {
+        if (assistantMessagePersisted) {
+          publishConversationMessagesChanged(conversationId, originClientId);
+        }
+        log.error({ err, conversationId }, "Clean command failed");
+        broadcastMessage({
+          type: "conversation_error",
+          conversationId,
+          code: "UNKNOWN",
+          userMessage: `Clean failed: ${err instanceof Error ? err.message : String(err)}`,
+          retryable: true,
+        });
+      }
+
+      return {
+        accepted: true,
+        messageId: persisted.id,
+        conversationId,
+      };
+    } finally {
+      conversation.processing = false;
+      silentlyWithLog(conversation.drainQueue(), "clean-command queue drain");
+    }
+  }
+
   const resolvedContent = slashResult.content;
 
   const requestId = crypto.randomUUID();
@@ -2035,7 +2037,7 @@ export async function handleSendMessage(
     requestId,
     clientMessageId,
   });
-  publishConversationMessagesChanged(mapping.conversationId);
+  publishConversationMessagesChanged(mapping.conversationId, originClientId);
 
   // Fire-and-forget the agent loop; events flow to the hub via broadcastMessage.
   conversation
@@ -2080,14 +2082,25 @@ async function generateLlmSuggestion(
         ? escapeXmlContent(priorUserText)
         : priorUserText;
 
-  const systemPrompt =
-    "You generate short, casual reply suggestions a user might type next in a chat. Match the tone and register of the preceding conversation. Output only the reply text inside the requested tags — no preamble, no commentary.";
+  const systemPrompt = [
+    "You generate short, casual reply suggestions a user might type next in a chat.",
+    "Match the tone and register of the preceding conversation.",
+    "",
+    "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",
+    "- 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.",
+  ].join("\n");
 
   const userPrompt =
     `Here is the end of a conversation:\n\n` +
     `<user_message>${truncatedUser ?? "(no prior user message)"}</user_message>\n` +
     `<assistant_message>${truncatedAssistant}</assistant_message>\n\n` +
-    `Write the user's next reply, focusing on the LAST question or call-to-action in the assistant message. Keep it short (under 15 words), casual, and in the user's voice. Respond in this exact format:\n\n` +
+    `Write the USER'S next reply — what the user would type. Focus on the LAST question or call-to-action in the assistant message. Keep it short (under 15 words), casual, and in the user's voice. ` +
+    `The reply must read as something typed BY the user, not something the assistant would say. Respond in this exact format:\n\n` +
     `<reply>YOUR_REPLY_HERE</reply>`;
 
   // Single user message only — no assistant-role prefill. Anthropic
@@ -2163,14 +2176,27 @@ export async function handleGetSuggestion(
   };
 
   const conversationKey = queryParams?.conversationKey;
-  if (!conversationKey) {
-    throw new BadRequestError("conversationKey query parameter is required");
+  const conversationId = queryParams?.conversationId;
+  if (!conversationKey && !conversationId) {
+    throw new BadRequestError(
+      "conversationKey or conversationId query parameter is required",
+    );
   }
 
-  const mapping = getConversationByKey(conversationKey);
-  if (!mapping) return noSuggestion;
+  let resolvedConversationId: string | undefined;
+  if (conversationId) {
+    resolvedConversationId = conversationId;
+  } else if (conversationKey) {
+    const mapping = getConversationByKey(conversationKey);
+    if (mapping) {
+      resolvedConversationId = mapping.conversationId;
+    } else if (getConversation(conversationKey)) {
+      resolvedConversationId = conversationKey;
+    }
+  }
+  if (!resolvedConversationId) return noSuggestion;
 
-  const rawMessages = getMessages(mapping.conversationId);
+  const rawMessages = getMessages(resolvedConversationId);
   if (rawMessages.length === 0) return noSuggestion;
 
   // Staleness check: compare requested messageId against the latest
@@ -2369,7 +2395,7 @@ export const ROUTES: RouteDefinition[] = [
         .optional()
         .describe("ID of the oldest message in this page"),
     }),
-    handler: (args) => handleListMessages(args, getInterfacesDir()),
+    handler: (args) => handleListMessages(args),
   },
   {
     operationId: "messages_post",
@@ -2424,10 +2450,31 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Return an LLM-generated follow-up suggestion for the most recent assistant message.",
     tags: ["messages"],
+    queryParams: [
+      {
+        name: "conversationId",
+        type: "string",
+        description:
+          "Conversation ID to fetch a suggestion for. Either this or conversationKey is required.",
+      },
+      {
+        name: "conversationKey",
+        type: "string",
+        description:
+          "Legacy conversation key. Either this or conversationId is required.",
+      },
+      {
+        name: "messageId",
+        type: "string",
+        description:
+          "Optional. Latest assistant message ID the client has seen — used to detect staleness.",
+      },
+    ],
     responseBody: z.object({
-      suggestion: z.string(),
-      messageId: z.string(),
+      suggestion: z.string().nullable(),
+      messageId: z.string().nullable(),
       source: z.string(),
+      stale: z.boolean().optional(),
     }),
     handler: async (args) =>
       handleGetSuggestion(args, {