@vellumai/assistant 0.8.1 → 0.8.3

package/src/home/feed-types.ts

@@ -38,6 +38,14 @@ export type FeedItemStatus = "new" | "seen" | "acted_on" | "dismissed";
 /** Visual urgency treatment — controls badge color independently of sort priority. */
 export type FeedItemUrgency = "low" | "medium" | "high" | "critical";
 
+/** Broad category for grouping and filtering feed items. */
+export type FeedItemCategory =
+  | "security"
+  | "scheduling"
+  | "background"
+  | "email"
+  | "system";
+
 /**
  * A single action button attached to a feed item.
  *
@@ -81,7 +89,13 @@ export interface FeedItem {
   type: FeedItemType;
   /** Integer in [0, 100]; higher values sort earlier. */
   priority: number;
-  title: string;
+  /**
+   * Optional short header. Omit when the source did not supply one — the
+   * notification pipeline never manufactures a title from rendered copy
+   * (LLM-echoed bodies stutter against `summary`). Clients fall back to
+   * `summary` when rendering a row.
+   */
+  title?: string;
   summary: string;
   /** Event time (ISO-8601). */
   timestamp: string;
@@ -96,6 +110,14 @@ export interface FeedItem {
   conversationId?: string;
   /** Server-driven detail panel descriptor; when present, the client opens this panel kind. */
   detailPanel?: FeedItemDetailPanel;
+  /** Broad category for grouping and filtering feed items. */
+  category?: FeedItemCategory;
+  /** True when this item represents an assistant-initiated share or a high-importance system event. Used by clients to split inbox vs activity surfaces. */
+  noteworthy?: boolean;
+  /** True when the assistant herself emitted this item (e.g. via the `notifications send` skill). Drives clients to swap the row's leading icon for the persona avatar; system-generated items keep the category icon. */
+  fromAssistant?: boolean;
+  /** Arbitrary structured data the detail panel or other consumers can use. */
+  metadata?: Record<string, unknown>;
   /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
   createdAt: string;
 }
@@ -164,6 +186,14 @@ const feedItemDetailPanelSchema = z.object({
   kind: feedItemDetailPanelKindSchema,
 });
 
+const feedItemCategorySchema = z.enum([
+  "security",
+  "scheduling",
+  "background",
+  "email",
+  "system",
+]);
+
 /**
  * Schema for a single `FeedItem`.
  *
@@ -178,7 +208,7 @@ export const feedItemSchema = z.object({
   id: z.string(),
   type: feedItemTypeSchema,
   priority: z.number().int().min(0).max(100),
-  title: z.string(),
+  title: z.string().optional(),
   summary: z.string(),
   timestamp: z.string(),
   status: feedItemStatusSchema.default("new"),
@@ -187,6 +217,10 @@ export const feedItemSchema = z.object({
   urgency: feedItemUrgencySchema.optional(),
   conversationId: z.string().optional(),
   detailPanel: feedItemDetailPanelSchema.optional(),
+  category: feedItemCategorySchema.optional(),
+  noteworthy: z.boolean().optional(),
+  fromAssistant: z.boolean().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
   createdAt: z.string(),
 });
 

package/src/home/post-connect-feed.ts

@@ -44,6 +44,7 @@ export async function emitPostConnectNudge(service: string): Promise<void> {
       "I can triage your inbox, summarize new emails, or draft replies to important threads.",
     timestamp: now.toISOString(),
     status: "new",
+    category: "email",
     expiresAt,
     createdAt: now.toISOString(),
     actions: [

package/src/index.ts

@@ -1,5 +1,22 @@
 #!/usr/bin/env bun
 
+import { red } from "./cli/lib/cli-colors.js";
+import {
+  detectUnknownCommand,
+  formatUnknownCommandMessage,
+} from "./cli/lib/unknown-command.js";
 import { buildCliProgram } from "./cli/program.js";
 
-(await buildCliProgram()).parse();
+const program = await buildCliProgram();
+
+// Commander processes `--help` before any action or hook fires, so
+// `assistant <unknown> --help` would dump the root help instead of flagging
+// the typo. Pre-scan argv so the unknown-command error wins over the help
+// short-circuit. See cli/lib/unknown-command.ts.
+const unknown = detectUnknownCommand(program, process.argv.slice(2));
+if (unknown) {
+  process.stderr.write(`${red(formatUnknownCommandMessage(unknown))}\n`);
+  process.exit(1);
+}
+
+program.parse();

package/src/ipc/cli-client.ts

@@ -135,19 +135,26 @@ export async function cliIpcCall<T = unknown>(
 
     const reqId = crypto.randomUUID();
 
-    opts?.signal?.addEventListener("abort", () => {
-      finish({ ok: false, error: "Request aborted" });
-    }, { once: true });
+    opts?.signal?.addEventListener(
+      "abort",
+      () => {
+        finish({ ok: false, error: "Request aborted" });
+      },
+      { once: true },
+    );
 
     const reader = new IpcFrameReader(
       (envelope) => {
         if (envelope.id !== reqId) return;
         const msg = envelope as IpcResponse;
         if (msg.error) {
-          finish({ ok: false, error: msg.error,
+          finish({
+            ok: false,
+            error: msg.error,
             ...(msg.statusCode != null && { statusCode: msg.statusCode }),
             ...(msg.errorCode != null && { errorCode: msg.errorCode }),
-            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }),
+          });
         } else {
           finish({ ok: true, result: msg.result as T });
         }
@@ -199,7 +206,13 @@ export async function cliIpcCallBinary(
   opts?: { timeoutMs?: number; signal?: AbortSignal },
 ): Promise<
   | { ok: true; headers: Record<string, string>; bytes: Uint8Array }
-  | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown }
+  | {
+      ok: false;
+      error: string;
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    }
 > {
   if (opts?.signal?.aborted) {
     throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
@@ -215,7 +228,13 @@ export async function cliIpcCallBinary(
     const finish = (
       result:
         | { ok: true; headers: Record<string, string>; bytes: Uint8Array }
-        | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown },
+        | {
+            ok: false;
+            error: string;
+            statusCode?: number;
+            errorCode?: string;
+            errorDetails?: unknown;
+          },
     ) => {
       if (settled) return;
       settled = true;
@@ -226,8 +245,14 @@ export async function cliIpcCallBinary(
     };
 
     const connectTimer = setTimeout(() => {
-      log.debug({ method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS }, "CLI IPC binary connect timed out");
-      finish({ ok: false, error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.` });
+      log.debug(
+        { method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS },
+        "CLI IPC binary connect timed out",
+      );
+      finish({
+        ok: false,
+        error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`,
+      });
     }, CONNECT_TIMEOUT_MS);
 
     const socket = new Socket();
@@ -235,7 +260,10 @@ export async function cliIpcCallBinary(
 
     socket.on("error", (err) => {
       const code = (err as NodeJS.ErrnoException).code;
-      log.debug({ err, code, method, socketPath }, "CLI IPC binary socket error");
+      log.debug(
+        { err, code, method, socketPath },
+        "CLI IPC binary socket error",
+      );
       finish({
         ok: false,
         error:
@@ -258,23 +286,37 @@ export async function cliIpcCallBinary(
 
     const reqId = crypto.randomUUID();
 
-    opts?.signal?.addEventListener("abort", () => {
-      finish({ ok: false, error: "Request aborted" });
-    }, { once: true });
+    opts?.signal?.addEventListener(
+      "abort",
+      () => {
+        finish({ ok: false, error: "Request aborted" });
+      },
+      { once: true },
+    );
 
     const reader = new IpcFrameReader(
       (envelope, binary) => {
         if (envelope.id !== reqId) return;
         const msg = envelope as IpcResponse;
         if (msg.error) {
-          finish({ ok: false, error: msg.error,
+          finish({
+            ok: false,
+            error: msg.error,
             ...(msg.statusCode != null && { statusCode: msg.statusCode }),
             ...(msg.errorCode != null && { errorCode: msg.errorCode }),
-            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }),
+          });
         } else if (binary === undefined) {
-          finish({ ok: false, error: "Expected binary frame but received JSON-only response" });
+          finish({
+            ok: false,
+            error: "Expected binary frame but received JSON-only response",
+          });
         } else {
-          finish({ ok: true, headers: (envelope.headers ?? {}) as Record<string, string>, bytes: binary });
+          finish({
+            ok: true,
+            headers: (envelope.headers ?? {}) as Record<string, string>,
+            bytes: binary,
+          });
         }
       },
       (err) => finish({ ok: false, error: err.message }),
@@ -285,7 +327,10 @@ export async function cliIpcCallBinary(
       writeMessage(socket, { id: reqId, method, params });
 
       callTimer = setTimeout(() => {
-        log.debug({ method, socketPath, timeoutMs: callTimeoutMs }, "CLI IPC binary call timed out");
+        log.debug(
+          { method, socketPath, timeoutMs: callTimeoutMs },
+          "CLI IPC binary call timed out",
+        );
         finish({ ok: false, error: "Request timed out" });
       }, callTimeoutMs);
 
@@ -323,24 +368,42 @@ export async function cliIpcCallStream(
   params?: Record<string, unknown>,
   opts?: { firstByteTimeoutMs?: number; signal?: AbortSignal },
 ): Promise<
-  | { ok: true; headers: Record<string, string>; body: ReadableStream<Uint8Array>; abort: () => void }
-  | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown }
+  | {
+      ok: true;
+      headers: Record<string, string>;
+      body: ReadableStream<Uint8Array>;
+      abort: () => void;
+    }
+  | {
+      ok: false;
+      error: string;
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    }
 > {
   if (opts?.signal?.aborted) {
     throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
   }
 
   const socketPath = getAssistantSocketPath();
-  const firstByteTimeoutMs = opts?.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS;
+  const firstByteTimeoutMs =
+    opts?.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS;
 
   return new Promise((resolve) => {
     let settled = false;
     let firstByteTimer: ReturnType<typeof setTimeout> | undefined;
-    let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
-
-    const finishError = (
-      result: { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown },
-    ) => {
+    let streamController:
+      | ReadableStreamDefaultController<Uint8Array>
+      | undefined;
+
+    const finishError = (result: {
+      ok: false;
+      error: string;
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    }) => {
       if (settled) return;
       settled = true;
       clearTimeout(connectTimer);
@@ -366,8 +429,14 @@ export async function cliIpcCallStream(
     };
 
     const connectTimer = setTimeout(() => {
-      log.debug({ method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS }, "CLI IPC stream connect timed out");
-      finishError({ ok: false, error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.` });
+      log.debug(
+        { method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS },
+        "CLI IPC stream connect timed out",
+      );
+      finishError({
+        ok: false,
+        error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`,
+      });
     }, CONNECT_TIMEOUT_MS);
 
     const socket = new Socket();
@@ -375,7 +444,10 @@ export async function cliIpcCallStream(
 
     socket.on("error", (err) => {
       const code = (err as NodeJS.ErrnoException).code;
-      log.debug({ err, code, method, socketPath }, "CLI IPC stream socket error");
+      log.debug(
+        { err, code, method, socketPath },
+        "CLI IPC stream socket error",
+      );
       if (!settled) {
         finishError({
           ok: false,
@@ -399,24 +471,35 @@ export async function cliIpcCallStream(
             : "Connection closed before response",
         });
       } else if (streamController) {
-        streamController.error(new Error("Connection closed before stream ended"));
+        streamController.error(
+          new Error("Connection closed before stream ended"),
+        );
         streamController = undefined;
       }
     });
 
     const reqId = crypto.randomUUID();
 
-    opts?.signal?.addEventListener("abort", () => { abort(); }, { once: true });
+    opts?.signal?.addEventListener(
+      "abort",
+      () => {
+        abort();
+      },
+      { once: true },
+    );
 
     const reader = new IpcFrameReader(
       (envelope) => {
         // Non-streaming envelope with error (e.g. method not found, auth failure)
         if (envelope.id !== reqId) return;
         const msg = envelope as IpcResponse;
-        finishError({ ok: false, error: msg.error ?? "Unexpected non-streaming response",
+        finishError({
+          ok: false,
+          error: msg.error ?? "Unexpected non-streaming response",
           ...(msg.statusCode != null && { statusCode: msg.statusCode }),
           ...(msg.errorCode != null && { errorCode: msg.errorCode }),
-          ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+          ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }),
+        });
       },
       (err) => finishError({ ok: false, error: err.message }),
       {
@@ -437,7 +520,12 @@ export async function cliIpcCallStream(
           });
           settled = true;
           clearTimeout(connectTimer);
-          resolve({ ok: true, headers: (envelope.headers ?? {}) as Record<string, string>, body, abort });
+          resolve({
+            ok: true,
+            headers: (envelope.headers ?? {}) as Record<string, string>,
+            body,
+            abort,
+          });
         },
         onStreamChunk: (chunk) => {
           streamController?.enqueue(chunk);
@@ -455,8 +543,14 @@ export async function cliIpcCallStream(
       writeMessage(socket, { id: reqId, method, params });
 
       firstByteTimer = setTimeout(() => {
-        log.debug({ method, socketPath, timeoutMs: firstByteTimeoutMs }, "CLI IPC stream first-byte timeout");
-        finishError({ ok: false, error: "Stream timed out waiting for first byte" });
+        log.debug(
+          { method, socketPath, timeoutMs: firstByteTimeoutMs },
+          "CLI IPC stream first-byte timeout",
+        );
+        finishError({
+          ok: false,
+          error: "Stream timed out waiting for first byte",
+        });
       }, firstByteTimeoutMs);
 
       socket.on("data", (chunk) => {
@@ -491,13 +585,21 @@ export function exitFromIpcResult(
   _cmd?: unknown,
 ): never {
   process.stderr.write((r.error ?? "Unknown error") + "\n");
-  if (r.statusCode === undefined) {
-    process.exit(10);
-  } else if (r.statusCode >= 500) {
-    process.exit(3);
-  } else if (r.statusCode >= 400) {
-    process.exit(2);
-  } else {
-    process.exit(1);
-  }
+  process.exit(exitCodeFromIpcResult(r));
+}
+
+/**
+ * Map an IPC error result to its CLI process exit code without exiting.
+ *
+ * Use this when callers want to emit a structured response (e.g. a JSON
+ * error envelope in `--json` mode) before terminating with the same status
+ * code that {@link exitFromIpcResult} would produce.
+ *
+ * Exit code matrix matches {@link exitFromIpcResult}.
+ */
+export function exitCodeFromIpcResult(r: { statusCode?: number }): number {
+  if (r.statusCode === undefined) return 10;
+  if (r.statusCode >= 500) return 3;
+  if (r.statusCode >= 400) return 2;
+  return 1;
 }

package/src/live-voice/__tests__/live-voice-stt.test.ts

@@ -229,6 +229,63 @@ describe("LiveVoiceSession STT", () => {
     ]);
   });
 
+  test("retains transcriber handle when stop() throws so close() can clean up", async () => {
+    class ThrowingStopTranscriber extends MockStreamingTranscriber {
+      stopCalls = 0;
+      override stop(): void {
+        this.stopCalls += 1;
+        if (this.stopCalls === 1) {
+          throw new Error("stop failed");
+        }
+      }
+    }
+
+    const transcriber = new ThrowingStopTranscriber();
+    const { frames, session } = createSessionWithTranscriber(transcriber);
+
+    await session.start();
+    await session.handleClientFrame({ type: "ptt_release" });
+
+    expect(transcriber.stopCalls).toBe(1);
+    expect(
+      frames.some(
+        (frame) =>
+          frame.type === "error" &&
+          frame.message.includes(
+            "Live voice transcription could not be stopped",
+          ),
+      ),
+    ).toBe(true);
+
+    await session.close("websocket_close");
+
+    expect(transcriber.stopCalls).toBe(2);
+  });
+
+  test("retains transcriber handle when stop() throws so interrupt() can clean up", async () => {
+    class ThrowingStopTranscriber extends MockStreamingTranscriber {
+      stopCalls = 0;
+      override stop(): void {
+        this.stopCalls += 1;
+        if (this.stopCalls === 1) {
+          throw new Error("stop failed");
+        }
+      }
+    }
+
+    const transcriber = new ThrowingStopTranscriber();
+    const { session } = createSessionWithTranscriber(transcriber);
+
+    await session.start();
+    await session.handleClientFrame({ type: "ptt_release" });
+
+    expect(transcriber.stopCalls).toBe(1);
+
+    await session.handleClientFrame({ type: "interrupt" });
+
+    expect(transcriber.stopCalls).toBe(2);
+  });
+
   test("uses the production streaming transcriber resolver by default", () => {
     const source = readFileSync(
       new URL("../live-voice-session.ts", import.meta.url),

package/src/mcp/client.ts

@@ -14,6 +14,24 @@ const log = getLogger("mcp-client");
 
 const CONNECT_TIMEOUT_MS = 30_000;
 
+// MCP servers occasionally return tools with a missing or non-object
+// `inputSchema` (spec violation, but seen in the wild). Coerce to a valid
+// empty object schema so downstream code that assumes `input_schema: object`
+// (e.g. `injectActivityField`) doesn't crash.
+function normalizeInputSchema(
+  raw: unknown,
+  toolName: string,
+): Record<string, unknown> {
+  if (raw != null && typeof raw === "object" && !Array.isArray(raw)) {
+    return raw as Record<string, unknown>;
+  }
+  log.warn(
+    { toolName, received: typeof raw },
+    "MCP tool returned non-object inputSchema; defaulting to empty object schema",
+  );
+  return { type: "object", properties: {} };
+}
+
 export interface McpToolInfo {
   name: string;
   description: string;
@@ -80,9 +98,7 @@ export class McpClient {
         `mcp:${this.serverId}:tokens`,
       );
       if (cachedTokens) {
-        const callbackTransport = getIsPlatform()
-          ? "gateway"
-          : "loopback";
+        const callbackTransport = getIsPlatform() ? "gateway" : "loopback";
         this.oauthProvider = new McpOAuthProvider(
           this.serverId,
           transportConfig.url,
@@ -164,7 +180,7 @@ export class McpClient {
     return result.tools.map((tool) => ({
       name: tool.name,
       description: tool.description ?? "",
-      inputSchema: tool.inputSchema as Record<string, unknown>,
+      inputSchema: normalizeInputSchema(tool.inputSchema, tool.name),
     }));
   }
 

package/src/media/image-credentials.ts

@@ -8,8 +8,8 @@
  * credentials are unavailable.
  */
 
-import { MANAGED_PROVIDER_META } from "../providers/managed-proxy/constants.js";
-import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { PLATFORM_PROVIDER_META } from "../providers/platform-proxy/constants.js";
+import { resolveManagedProxyContext } from "../providers/platform-proxy/context.js";
 import { getProviderKeyAsync } from "../security/secure-keys.js";
 import type { ImageGenCredentials, ImageGenProvider } from "./types.js";
 
@@ -33,7 +33,7 @@ export async function resolveImageGenCredentials(opts: {
     // Resolve platform URL + assistant API key from a single snapshot so
     // baseUrl and assistantApiKey can't diverge if the credential is cleared
     // between lookups.
-    const meta = MANAGED_PROVIDER_META[provider];
+    const meta = PLATFORM_PROVIDER_META[provider];
     const ctx = await resolveManagedProxyContext();
     if (
       !meta?.managed ||

package/src/memory/__tests__/bookmark-crud.test.ts

@@ -93,17 +93,13 @@ describe("bookmark-crud", () => {
       messageId: "msg-1",
     });
 
-    const first = createBookmark(db, {
-      messageId: "msg-1",
-      conversationId: "conv-1",
-    });
-    const second = createBookmark(db, {
-      messageId: "msg-1",
-      conversationId: "conv-1",
-    });
+    const first = createBookmark(db, { messageId: "msg-1" });
+    const second = createBookmark(db, { messageId: "msg-1" });
 
-    expect(second.id).toBe(first.id);
-    expect(second.createdAt).toBe(first.createdAt);
+    expect(first.inserted).toBe(true);
+    expect(second.inserted).toBe(false);
+    expect(second.bookmark.id).toBe(first.bookmark.id);
+    expect(second.bookmark.createdAt).toBe(first.bookmark.createdAt);
 
     const all = listBookmarks(db);
     expect(all.length).toBe(1);
@@ -119,11 +115,10 @@ describe("bookmark-crud", () => {
       messageRole: "assistant",
     });
 
-    const summary = createBookmark(db, {
-      messageId: "msg-summary",
-      conversationId: "conv-summary",
-    });
+    const result = createBookmark(db, { messageId: "msg-summary" });
 
+    expect(result.inserted).toBe(true);
+    const summary = result.bookmark;
     expect(summary.conversationTitle).toBe("Title goes here");
     expect(summary.messagePreview).toBe("summary body");
     expect(summary.messageRole).toBe("assistant");
@@ -179,14 +174,8 @@ describe("bookmark-crud", () => {
       conversationId: "conv-drop",
       messageId: "msg-drop",
     });
-    createBookmark(db, {
-      messageId: "msg-keep",
-      conversationId: "conv-keep",
-    });
-    createBookmark(db, {
-      messageId: "msg-drop",
-      conversationId: "conv-drop",
-    });
+    createBookmark(db, { messageId: "msg-keep" });
+    createBookmark(db, { messageId: "msg-drop" });
     expect(listBookmarks(db).length).toBe(2);
 
     // Deleting the parent conversation cascades through messages → bookmarks.
@@ -203,7 +192,7 @@ describe("bookmark-crud", () => {
       conversationId: "conv-d",
       messageId: "msg-d",
     });
-    createBookmark(db, { messageId: "msg-d", conversationId: "conv-d" });
+    createBookmark(db, { messageId: "msg-d" });
     expect(listBookmarks(db).length).toBe(1);
 
     expect(deleteBookmarkByMessageId(db, "msg-d")).toBe(true);
@@ -223,9 +212,8 @@ describe("bookmark-crud", () => {
       messageRole: "user",
     });
 
-    const summary = createBookmark(db, {
+    const { bookmark: summary } = createBookmark(db, {
       messageId: "msg-blocks",
-      conversationId: "conv-blocks",
     });
 
     // Without the decode step, this would render as the raw JSON literal
@@ -248,11 +236,29 @@ describe("bookmark-crud", () => {
       messageRole: "assistant",
     });
 
-    const summary = createBookmark(db, {
+    const { bookmark: summary } = createBookmark(db, {
       messageId: "msg-multi",
-      conversationId: "conv-multi",
     });
 
     expect(summary.messagePreview).toBe("first paragraph\nsecond paragraph");
   });
+
+  test("createBookmark derives conversationId from the message row", () => {
+    const { db, raw } = setupDb();
+    seedConversationAndMessage(raw, {
+      conversationId: "conv-real",
+      messageId: "msg-x",
+    });
+
+    const { bookmark: summary } = createBookmark(db, { messageId: "msg-x" });
+    expect(summary.conversationId).toBe("conv-real");
+    expect(listBookmarks(db)[0]?.conversationId).toBe("conv-real");
+  });
+
+  test("createBookmark throws when the message id does not exist", () => {
+    const { db } = setupDb();
+    expect(() => createBookmark(db, { messageId: "ghost" })).toThrow(
+      /Message ghost not found/,
+    );
+  });
 });