@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/oauth/connection.ts

@@ -5,8 +5,9 @@ export interface OAuthConnectionRequest {
   headers?: Record<string, string>;
   /**
    * A string is forwarded to the provider verbatim under the caller's own
-   * `Content-Type` (multipart, XML, form-encoded). Anything else is
-   * JSON-serialized and sent as `application/json`.
+   * `Content-Type` (multipart, XML, form-encoded). A Buffer or Uint8Array
+   * is forwarded as raw bytes. Anything else is JSON-serialized and sent
+   * as `application/json`.
    */
   body?: unknown;
   /**

package/src/oauth/platform-connection.test.ts

@@ -102,6 +102,41 @@ describe("PlatformOAuthConnection", () => {
     expect(result.body).toEqual(upstreamBody);
   });
 
+  test("encodes a Buffer request body as base64 in the proxy envelope", async () => {
+    const binary = Buffer.from([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe, 0x00,
+    ]);
+
+    const client = makeMockClient(
+      mock(async (_url: string | URL | Request, init?: RequestInit) => {
+        const parsed = JSON.parse(init?.body as string);
+        expect(parsed.request.body).toBe(binary.toString("base64"));
+        expect(parsed.request.body_encoding).toBe("base64");
+        expect(parsed.request.headers["Content-Type"]).toBe("application/pdf");
+
+        return new Response(
+          JSON.stringify({
+            status: 200,
+            headers: { "content-type": "application/json" },
+            body: { id: "file-123" },
+          }),
+          { status: 200 },
+        );
+      }) as unknown as typeof globalThis.fetch,
+    );
+
+    const conn = new PlatformOAuthConnection({
+      ...DEFAULT_OPTIONS,
+      client,
+    });
+    await conn.request({
+      method: "POST",
+      path: "/upload/drive/v3/files",
+      headers: { "Content-Type": "application/pdf" },
+      body: binary,
+    });
+  });
+
   test("decodes base64 binary proxy bodies into a Buffer", async () => {
     const binary = Buffer.from([
       0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe, 0x00,

package/src/oauth/platform-connection.ts

@@ -7,6 +7,7 @@ import type {
   OAuthConnectionRequest,
   OAuthConnectionResponse,
 } from "./connection.js";
+import { isBinaryOAuthBody } from "./connection.js";
 
 const log = getLogger("platform-oauth-connection");
 const MAX_RETRIES = 3;
@@ -84,20 +85,24 @@ export class PlatformOAuthConnection implements OAuthConnection {
 
     // The envelope carries the caller's headers and body side by side. A
     // string body is placed in the envelope as a string, so the proxy forwards
-    // those bytes verbatim under the caller's Content-Type; an object body
-    // travels as JSON and the proxy serializes it.
-    const body: Record<string, unknown> = {
-      request: {
-        method: req.method,
-        path: req.path,
-        query: req.query ?? {},
-        headers: req.headers ?? {},
-        body: req.body ?? null,
-        ...((req.baseUrl ?? this.baseUrl)
-          ? { base_url: req.baseUrl ?? this.baseUrl }
-          : {}),
-      },
+    // those bytes verbatim under the caller's Content-Type. A Buffer is
+    // base64-encoded so binary uploads survive JSON. An object body travels
+    // as JSON and the proxy serializes it.
+    const request: Record<string, unknown> = {
+      method: req.method,
+      path: req.path,
+      query: req.query ?? {},
+      headers: req.headers ?? {},
+      body: req.body ?? null,
+      ...((req.baseUrl ?? this.baseUrl)
+        ? { base_url: req.baseUrl ?? this.baseUrl }
+        : {}),
     };
+    if (isBinaryOAuthBody(req.body)) {
+      request.body = Buffer.from(req.body).toString("base64");
+      request.body_encoding = "base64";
+    }
+    const body: Record<string, unknown> = { request };
 
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       const response = await this.client.fetch(proxyPath, {

package/src/oauth/scope-utils.ts

@@ -24,6 +24,54 @@ export function scopeDifference(
   );
 }
 
+/**
+ * Split a scope list the way the provider writes it.
+ *
+ * Providers (GitHub, Slack) may return comma-separated scopes regardless of
+ * the separator used to join outbound authorize URLs, so the default tolerates
+ * both spaces and commas. A provider that explicitly configures a non-default
+ * separator (Linear uses ",") is honored, keeping configured scopes
+ * round-tripping symmetrically.
+ *
+ * The one parser for both directions: token responses and authorize
+ * parameters. Two copies would let a provider-format fix land on one and not
+ * the other.
+ */
+export function parseScopeList(
+  raw: string,
+  scopeSeparator: string = " ",
+): string[] {
+  const splitPattern = scopeSeparator === " " ? /[ ,]/ : scopeSeparator;
+  return raw
+    .split(splitPattern)
+    .map((scope) => scope.trim())
+    .filter(Boolean);
+}
+
+/**
+ * The scopes the stored access token is expected to carry.
+ *
+ * A provider that asks for user scopes alongside bot scopes issues two grants
+ * from one authorization. `exchangeCodeForTokens` stores the `authed_user`
+ * token in that case and records that token's own grant as `grantedScopes`, so
+ * coverage has to be measured against the request that produced the stored
+ * token: `user_scope` where the provider sends one, the `scope` parameter
+ * otherwise. Measuring a user grant against the bot request reports scopes the
+ * authorization could never place on that token.
+ */
+export function expectedScopesForStoredToken(
+  defaultScopes: string[],
+  authorizeParams: Record<string, string> | undefined,
+  scopeSeparator?: string,
+): string[] {
+  const userScope = authorizeParams?.user_scope;
+  if (typeof userScope !== "string") {
+    return defaultScopes;
+  }
+  const parsed = parseScopeList(userScope, scopeSeparator);
+  return parsed.length > 0 ? parsed : defaultScopes;
+}
+
 const GMAIL_FULL_ACCESS_SCOPE = "https://mail.google.com/";
 const GMAIL_READONLY_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";
 

package/src/oauth/seed-providers.ts

@@ -183,6 +183,14 @@ export const PROVIDER_SEED_DATA: Record<
     clientIdPlaceholder: null,
     logoUrl:
       "https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/slack/default.svg",
+    // Sent as the bot `scope` parameter, while this flow persists the
+    // `authed_user` token and stores `authed_user.scope` as `grantedScopes`.
+    // Credential health compares this list against that grant, so a scope
+    // listed here that `user_scope` does not also request reports as
+    // `missing_scopes`, a hard failure that disables the provider's tools.
+    // The wider bot set belongs to Socket Mode installs, which verify the live
+    // `x-oauth-scopes` header against SLACK_REQUIRED_BOT_SCOPES in
+    // channel-readiness-service.ts.
     defaultScopes: [
       "channels:join",
       "channels:read",
@@ -200,6 +208,10 @@ export const PROVIDER_SEED_DATA: Record<
       "reactions:write",
     ],
     availableScopes: "https://api.slack.com/scopes",
+    // Carries write scopes because the persisted `authed_user` token is the
+    // only credential this flow stores, so it acts as the installer for every
+    // call including `chat.postMessage`. The manifest's user list is read-only
+    // instead, since a Socket Mode install keeps a bot token beside it.
     authorizeParams: {
       user_scope:
         "channels:read,channels:history,groups:read,groups:history,im:read,im:history,im:write,mpim:read,mpim:history,users:read,chat:write,search:read,reactions:write",

package/src/outbound-proxy/certs.ts

@@ -49,6 +49,7 @@ export async function ensureLocalCA(dataDir: string): Promise<void> {
   const keyProc = Bun.spawn(["openssl", "genrsa", "-out", keyPath, "2048"], {
     stdout: "pipe",
     stderr: "pipe",
+    windowsHide: true,
   });
   const keyExit = await keyProc.exited;
   if (keyExit !== 0) {
@@ -76,7 +77,7 @@ export async function ensureLocalCA(dataDir: string): Promise<void> {
       "-addext",
       "keyUsage=critical,keyCertSign,cRLSign",
     ],
-    { stdout: "pipe", stderr: "pipe" },
+    { stdout: "pipe", stderr: "pipe", windowsHide: true },
   );
   const certExit = await certProc.exited;
   if (certExit !== 0) {
@@ -144,7 +145,7 @@ export async function issueLeafCert(
   // Generate leaf key
   const keyProc = Bun.spawn(
     ["openssl", "genrsa", "-out", leafKeyPath, "2048"],
-    { stdout: "pipe", stderr: "pipe" },
+    { stdout: "pipe", stderr: "pipe", windowsHide: true },
   );
   const keyExit = await keyProc.exited;
   if (keyExit !== 0) {
@@ -166,7 +167,7 @@ export async function issueLeafCert(
       "-subj",
       `/CN=${hostname}`,
     ],
-    { stdout: "pipe", stderr: "pipe" },
+    { stdout: "pipe", stderr: "pipe", windowsHide: true },
   );
   const csrExit = await csrProc.exited;
   if (csrExit !== 0) {
@@ -198,7 +199,7 @@ export async function issueLeafCert(
       "-extfile",
       extPath,
     ],
-    { stdout: "pipe", stderr: "pipe" },
+    { stdout: "pipe", stderr: "pipe", windowsHide: true },
   );
   const signExit = await signProc.exited;
   if (signExit !== 0) {

package/src/permissions/question-guardian-request.test.ts

@@ -21,7 +21,7 @@ const bridgeMock = mock((_params: Record<string, unknown>) =>
   Promise.resolve({ bridged: true as const, signalId: "req-1" }),
 );
 const withdrawCardsMock = mock((_params: Record<string, unknown>) =>
-  Promise.resolve(),
+  Promise.resolve({ complete: true }),
 );
 
 let trustContext: TrustContext | undefined;
@@ -37,7 +37,13 @@ mock.module("../daemon/conversation-registry.js", () => ({
         })
       : undefined,
 }));
+// Spread the actual module so transitive importers of names this
+// factory does not stub keep resolving (a partial factory breaks at
+// import time when the graph gains a new named import).
+const actualGatewayGuardianRequests =
+  await import("../channels/gateway-guardian-requests.js");
 mock.module("../channels/gateway-guardian-requests.js", () => ({
+  ...actualGatewayGuardianRequests,
   createGuardianRequest: (params: Record<string, unknown>) =>
     createGuardianRequestMock(params),
   expireGuardianRequest: (id: string) => expireGuardianRequestMock(id),

package/src/persistence/attachments-store.ts

@@ -273,36 +273,52 @@ function materializeAttachmentIntoConversation(
   const resolvedName = resolveUniqueFilename(attachDir, row.originalFilename);
   const targetPath = join(attachDir, resolvedName);
 
-  let sourcePath = row.sourcePath;
-  if (row.dataBase64) {
-    writeFileSync(targetPath, Buffer.from(row.dataBase64, "base64"));
-  } else {
-    const readablePath = [row.filePath, row.sourcePath].find(
-      (path): path is string => !!path && existsSync(path),
-    );
-    if (!readablePath) {
-      return;
-    }
-
-    if (!sourcePath && readablePath !== row.filePath) {
-      sourcePath = readablePath;
-    } else if (
-      !sourcePath &&
-      readablePath === row.filePath &&
-      dirname(readablePath) !== attachDir
-    ) {
-      sourcePath = readablePath;
-    }
-
-    copyFileSync(readablePath, targetPath);
-  }
-
   // Remember the old file path before updating the DB row, so we can
   // clean up the staging copy (e.g. in data/attachments/) after the
   // canonical path moves to the conversation directory.
   const previousFilePath = row.filePath;
 
-  persistAttachmentFilePath(row.id, targetPath, sourcePath);
+  let sourcePath = row.sourcePath;
+  try {
+    if (row.dataBase64) {
+      writeFileSync(targetPath, Buffer.from(row.dataBase64, "base64"));
+    } else {
+      const readablePath = [row.filePath, row.sourcePath].find(
+        (path): path is string => !!path && existsSync(path),
+      );
+      if (!readablePath) {
+        return;
+      }
+
+      if (!sourcePath && readablePath !== row.filePath) {
+        sourcePath = readablePath;
+      } else if (
+        !sourcePath &&
+        readablePath === row.filePath &&
+        dirname(readablePath) !== attachDir
+      ) {
+        sourcePath = readablePath;
+      }
+
+      copyFileSync(readablePath, targetPath);
+    }
+
+    persistAttachmentFilePath(row.id, targetPath, sourcePath);
+  } catch (err) {
+    // Only the copy this call was making. `resolveUniqueFilename` picked a name
+    // nothing occupied, so whatever sits at `targetPath` now is this attempt's
+    // own work. The row's `filePath` is deliberately left alone: until the
+    // update above lands it can still name the file the bytes came FROM, and
+    // for a fresh clone that file belongs to another conversation.
+    if (existsSync(targetPath)) {
+      try {
+        unlinkSync(targetPath);
+      } catch {
+        /* leave the copy rather than fail the failure */
+      }
+    }
+    throw err;
+  }
 
   // Remove the old staging file now that the canonical copy lives in
   // the conversation directory.  Only delete files that live in the
@@ -344,18 +360,58 @@ function scopeAttachmentToConversation(
   }
 
   const linkedConversationIds = listLinkedConversationIds(attachmentId);
-  if (linkedConversationIds.some((id) => id !== conversationId)) {
+  const cloned = linkedConversationIds.some((id) => id !== conversationId);
+  if (cloned) {
     row = cloneAttachmentRow(row);
   }
 
-  materializeAttachmentIntoConversation(
-    row,
-    conversationId,
-    conversationCreatedAt,
-  );
+  try {
+    materializeAttachmentIntoConversation(
+      row,
+      conversationId,
+      conversationCreatedAt,
+    );
+  } catch (err) {
+    if (cloned) {
+      discardFailedCloneRow(row.id);
+    }
+    throw err;
+  }
   return row.id;
 }
 
+/**
+ * Drop the row a failed clone left behind, touching no file at all.
+ *
+ * A clone is inserted carrying the SOURCE row's `filePath`, and only a
+ * successful materialization repoints it at a copy of its own. At the moment
+ * materialization fails the row can therefore still name the original's file,
+ * and deleting that would take the source conversation's data with it. This is
+ * the hazard the staging-dir guard in
+ * {@link materializeAttachmentIntoConversation} exists for, applied to the
+ * other end of the same window.
+ *
+ * The file this attempt was creating is cleaned up by materialization itself,
+ * which is the only code that knows the path it chose.
+ *
+ * Best effort. Rethrowing the original failure matters more than the row, and
+ * the caller converts that failure into an inline fallback either way.
+ */
+function discardFailedCloneRow(clonedId: string): void {
+  try {
+    rawRun(
+      "attachments:discardFailedCloneRow",
+      `DELETE FROM attachments WHERE id = ?`,
+      clonedId,
+    );
+  } catch (err) {
+    getLogger("attachments-store").warn(
+      { err, attachmentId: clonedId },
+      "Could not discard the row left by a failed attachment clone",
+    );
+  }
+}
+
 /**
  * Scope a pre-uploaded attachment into a conversation WITHOUT linking it to a
  * message, returning the scoped row's metadata. Mirrors {@link createInlineAttachment}
@@ -1164,6 +1220,32 @@ export function getAttachmentsByIds(
   return results;
 }
 
+/**
+ * Hydrate attachment ids into the shape a persisted user message stores:
+ * base64 data plus the on-disk source path where one is known. Ids with no
+ * attachment row are dropped, so a caller that needs to know an id was bad
+ * compares the returned length against what it asked for.
+ */
+export function resolveAttachmentsForPersist(attachmentIds: string[]): Array<{
+  id: string;
+  filename: string;
+  mimeType: string;
+  data: string;
+  filePath?: string;
+}> {
+  const resolved = getAttachmentsByIds(attachmentIds, {
+    hydrateFileData: true,
+  });
+  const sourcePaths = getSourcePathsForAttachments(attachmentIds);
+  return resolved.map((a) => ({
+    id: a.id,
+    filename: a.originalFilename,
+    mimeType: a.mimeType,
+    data: a.dataBase64,
+    ...(sourcePaths.has(a.id) ? { filePath: sourcePaths.get(a.id) } : {}),
+  }));
+}
+
 export function linkAttachmentToMessage(
   messageId: string,
   attachmentId: string,
@@ -1332,6 +1414,16 @@ export function deleteOrphanAttachments(candidateIds: string[]): number {
 
   // Clean up on-disk files only after the DB rows have been removed
   for (const filePath of orphanFilePaths) {
+    // A path is not private to one row. A clone carries the source's
+    // `filePath` until materialization repoints it, and an attachment already
+    // sitting in the destination's directory is scoped without being copied at
+    // all, so a surviving row can still name this file. Unlinking it then
+    // destroys another conversation's data, which is what the staging-dir
+    // guard in `materializeAttachmentIntoConversation` avoids at the other end
+    // of the same window.
+    if (attachmentFilePathStillReferenced(filePath)) {
+      continue;
+    }
     try {
       unlinkSync(filePath);
     } catch {
@@ -1341,3 +1433,14 @@ export function deleteOrphanAttachments(candidateIds: string[]): number {
 
   return deletedCount;
 }
+
+/** True while any surviving attachment row still names this file. */
+function attachmentFilePathStillReferenced(filePath: string): boolean {
+  return (
+    rawGet<{ id: string }>(
+      "attachments:filePathStillReferenced",
+      `SELECT id FROM attachments WHERE file_path = ? LIMIT 1`,
+      filePath,
+    ) !== null
+  );
+}

package/src/persistence/conversation-crud.ts

@@ -91,8 +91,12 @@ import {
   type ConversationCreateType,
   type ConversationOrigin,
   isHiddenMessageMetadata,
+  isNoResponseMetadata,
+  isReactionMessageMetadata,
   isSystemCardMetadata,
   PINNED_GROUP_ID,
+  SIGHT_FRAME_ATTACHMENT_IDS_KEY,
+  sightFrameAttachmentIdsFromMetadata,
   UNGROUPED_GROUP_ID,
 } from "./conversation-types.js";
 import { runAsyncSqlite } from "./db-async-query.js";
@@ -458,7 +462,10 @@ export {
  * alongside the schema that carries them.
  */
 export {
+  isNoResponseMetadata,
   isSystemCardMetadata,
+  NO_RESPONSE_MESSAGE_KIND,
+  REACTION_MESSAGE_KIND,
   SYSTEM_CARD_MESSAGE_KIND,
 } from "./conversation-types.js";
 
@@ -485,7 +492,7 @@ export function isProviderErrorMetadata(
 
 /**
  * True when an assistant row is a standalone display turn: a system card or
- * a provider-error notice. Standalone rows never merge with adjacent
+ * a provider-error notice, or a deliberate-silence marker. Standalone rows never merge with adjacent
  * assistant rows, and turn grouping closes on them, so display merging and
  * the turn resolver agree on boundaries. Takes the raw persisted `metadata`
  * JSON string; malformed JSON and non-assistant roles are never standalone.
@@ -499,7 +506,12 @@ export function isStandaloneAssistantMessage(
   }
   try {
     const parsed = JSON.parse(metadata) as Record<string, unknown>;
-    return isSystemCardMetadata(parsed) || isProviderErrorMetadata(parsed);
+    return (
+      isSystemCardMetadata(parsed) ||
+      isProviderErrorMetadata(parsed) ||
+      isNoResponseMetadata(parsed) ||
+      isReactionMessageMetadata(parsed)
+    );
   } catch {
     return false;
   }
@@ -1675,6 +1687,8 @@ function populateForkContentsInProcess(args: PopulateForkContentsArgs): void {
     });
   }
 
+  widenForkSightFrameTags(messagesToCopy, forkedMessageIds, attachmentIdMap);
+
   // Set lastMessageAt to the max createdAt of copied messages so the
   // forked conversation sorts correctly by message recency.
   const lastCopiedMessage = messagesToCopy.at(-1);
@@ -1718,6 +1732,75 @@ function populateForkContentsInProcess(args: PopulateForkContentsArgs): void {
   }
 }
 
+/**
+ * Extend the copied rows' camera-frame tags to name the fork's cloned
+ * attachment ids alongside the source ids they were written with.
+ *
+ * A fork leaves its rows describing their attachments two different ways:
+ * `messages.content` is copied byte for byte and still names the SOURCE
+ * attachment ids, while `message_attachments` is re-linked to freshly CLONED
+ * rows under new ids. Readers split along that seam. Camera-frame retention
+ * matches the tag against the ids in the content blocks (source ids), and the
+ * compactor builds its image manifest from the links (cloned ids) and stamps
+ * those onto the frames it rebuilds. A tag naming only one vocabulary goes
+ * blind on the other, so it names both.
+ *
+ * Widening rather than remapping is deliberate: replacing the source ids would
+ * fix the compactor's frames by breaking every frame the fork holds directly,
+ * which is the common case. Extra ids are inert, since an id no block carries
+ * simply never matches.
+ *
+ * Runs after the attachment loop because that loop is what produces the id map.
+ * Only rows that actually carry a tag are rewritten, so an ordinary fork does
+ * no extra writes.
+ */
+function widenForkSightFrameTags(
+  messagesToCopy: MessageRow[],
+  forkedMessageIds: Map<string, string>,
+  attachmentIdMap: Map<string, string>,
+): void {
+  if (attachmentIdMap.size === 0) {
+    return;
+  }
+  const db = getDb();
+  for (const message of messagesToCopy) {
+    const forkedMessageId = forkedMessageIds.get(message.id);
+    if (!forkedMessageId) {
+      continue;
+    }
+    const sourceMetadata = parseMessageMetadata(message.metadata);
+    const sourceIds = sightFrameAttachmentIdsFromMetadata(sourceMetadata);
+    if (sourceIds.length === 0) {
+      continue;
+    }
+    const widened = new Set(sourceIds);
+    for (const sourceId of sourceIds) {
+      const clonedId = attachmentIdMap.get(sourceId);
+      if (clonedId) {
+        widened.add(clonedId);
+      }
+    }
+    if (widened.size === sourceIds.length) {
+      continue;
+    }
+    const forkedRow = db
+      .select({ metadata: messages.metadata })
+      .from(messages)
+      .where(eq(messages.id, forkedMessageId))
+      .get();
+    const forkedMetadata = parseMessageMetadata(forkedRow?.metadata ?? null);
+    db.update(messages)
+      .set({
+        metadata: JSON.stringify({
+          ...(forkedMetadata ?? {}),
+          [SIGHT_FRAME_ATTACHMENT_IDS_KEY]: [...widened],
+        }),
+      })
+      .where(eq(messages.id, forkedMessageId))
+      .run();
+  }
+}
+
 /**
  * How many leading rows of the inherited window sit behind the source's
  * compaction boundary, counted in `getMessages` load order (`createdAt`
@@ -2494,6 +2577,41 @@ export function selectProviderMetaCandidateMetadata(
   return out;
 }
 
+/**
+ * Every attachment the conversation's rows tagged as an ambient camera frame,
+ * mapped to the `createdAt` of the row that carried it.
+ *
+ * Like the Slack prefilter above, the `LIKE` is an indexable narrowing only:
+ * each candidate row is parsed and validated before an id is taken, so a row
+ * that merely mentions the key contributes nothing. Any row state qualifies
+ * because the tag is written with the insert, and the lineage filter is what
+ * lets a fork see the frames it inherited.
+ */
+export function selectSightFrameCaptureTimes(
+  conversationId: string,
+): Map<string, number> {
+  const db = getDb();
+  const rows = db
+    .select({ metadata: messages.metadata, createdAt: messages.createdAt })
+    .from(messages)
+    .where(
+      and(
+        lineageFilter(conversationId),
+        like(messages.metadata, `%"${SIGHT_FRAME_ATTACHMENT_IDS_KEY}"%`),
+      ),
+    )
+    .orderBy(asc(messages.createdAt))
+    .all();
+  const captureTimes = new Map<string, number>();
+  for (const row of rows) {
+    const metadata = parseMessageMetadata(row.metadata);
+    for (const id of sightFrameAttachmentIdsFromMetadata(metadata)) {
+      captureTimes.set(id, row.createdAt);
+    }
+  }
+  return captureTimes;
+}
+
 /**
  * Count messages in a conversation that were created strictly after the
  * `afterMessageId` reference message. If `afterMessageId` is `null` or empty,
@@ -4082,8 +4200,18 @@ export function relinkAttachments(
  *
  * Returns segment IDs so the caller can clean up the corresponding
  * Qdrant vector entries.
+ *
+ * `retainAttachmentIds` exempts attachments from the orphan cleanup below, for
+ * a caller rolling a message back rather than deleting it: the attachment
+ * returns to the uploaded-but-unlinked state it was in before the row existed,
+ * which is a live state (that is where every attachment sits between upload and
+ * send), not a leak. Callers deleting a message for good pass nothing and the
+ * attachments it alone referenced are collected.
  */
-export function deleteMessageById(messageId: string): DeletedMemoryIds {
+export function deleteMessageById(
+  messageId: string,
+  options?: { retainAttachmentIds?: readonly string[] },
+): DeletedMemoryIds {
   const db = getDb();
   const result: DeletedMemoryIds = {
     segmentIds: [],
@@ -4145,7 +4273,12 @@ export function deleteMessageById(messageId: string): DeletedMemoryIds {
     ...purgeMessageSegments([messageId], "deleteMessageById:post-delete"),
   );
 
-  deleteOrphanAttachments(candidateAttachmentIds);
+  const retainAttachmentIds = options?.retainAttachmentIds;
+  deleteOrphanAttachments(
+    retainAttachmentIds && retainAttachmentIds.length > 0
+      ? candidateAttachmentIds.filter((id) => !retainAttachmentIds.includes(id))
+      : candidateAttachmentIds,
+  );
 
   // Remove the deleted message's point from the lexical index. Enqueued only
   // when the row actually existed (`msgRow` set), after the transaction and