@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/persistence/attachments-store.ts

@@ -17,7 +17,7 @@ import {
 } from "node:fs";
 import { basename, dirname, extname, join } from "node:path";
 
-import { eq } from "drizzle-orm";
+import { and, eq, inArray } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import {
@@ -31,7 +31,7 @@ import { getWorkspaceDir } from "../util/platform.js";
 import { getConversationAttachmentsDirPath } from "./conversation-directories.js";
 import { getDb } from "./db-connection.js";
 import { rawAll, rawGet, rawRun } from "./raw-query.js";
-import { attachments, messageAttachments } from "./schema.js";
+import { attachments, messageAttachments, messages } from "./schema.js";
 
 export interface StoredAttachment {
   id: string;
@@ -206,16 +206,23 @@ function insertMessageAttachmentLink(
   attachmentId: string,
   position: number,
 ): void {
-  const db = getDb();
-  db.insert(messageAttachments)
-    .values({
-      id: uuid(),
-      messageId,
-      attachmentId,
-      position,
-      createdAt: Date.now(),
-    })
-    .run();
+  rawRun(
+    "attachments:insertMessageAttachmentLink",
+    `INSERT INTO message_attachments
+       (id, message_id, attachment_id, position, created_at)
+     SELECT ?, ?, ?, ?, ?
+     WHERE NOT EXISTS (
+       SELECT 1 FROM message_attachments
+       WHERE message_id = ? AND attachment_id = ?
+     )`,
+    uuid(),
+    messageId,
+    attachmentId,
+    position,
+    Date.now(),
+    messageId,
+    attachmentId,
+  );
 }
 
 function persistAttachmentFilePath(
@@ -1256,6 +1263,20 @@ export function linkAttachmentToMessage(
     throw new Error(`Message not found: ${messageId}`);
   }
 
+  const existing = getDb()
+    .select({ attachmentId: messageAttachments.attachmentId })
+    .from(messageAttachments)
+    .where(
+      and(
+        eq(messageAttachments.messageId, messageId),
+        eq(messageAttachments.attachmentId, attachmentId),
+      ),
+    )
+    .get();
+  if (existing) {
+    return existing.attachmentId;
+  }
+
   const scopedAttachmentId = scopeAttachmentToConversation(
     attachmentId,
     ctx.conversationId,
@@ -1301,41 +1322,60 @@ export function getAttachmentsForMessage(
 export function getAttachmentMetadataForMessage(
   messageId: string,
 ): StoredAttachment[] {
-  const db = getDb();
-  const links = db
-    .select({ attachmentId: messageAttachments.attachmentId })
-    .from(messageAttachments)
-    .where(eq(messageAttachments.messageId, messageId))
-    .orderBy(messageAttachments.position)
-    .all();
+  return getAttachmentMetadataForMessages([messageId]).map(
+    (row) => row.attachment,
+  );
+}
 
-  if (links.length === 0) {
-    return [];
-  }
+export interface MessageAttachmentMetadata {
+  messageId: string;
+  messageMetadata: string | null;
+  attachment: StoredAttachment;
+}
 
-  const results: StoredAttachment[] = [];
-  for (const link of links) {
-    if (!link.attachmentId) {
-      continue;
-    }
-    const row = db
-      .select({
-        id: attachments.id,
-        originalFilename: attachments.originalFilename,
-        mimeType: attachments.mimeType,
-        sizeBytes: attachments.sizeBytes,
-        kind: attachments.kind,
-        thumbnailBase64: attachments.thumbnailBase64,
-        createdAt: attachments.createdAt,
-      })
-      .from(attachments)
-      .where(eq(attachments.id, link.attachmentId))
-      .get();
-    if (row) {
-      results.push(row);
-    }
+/**
+ * Return linked attachment metadata together with the metadata of each source
+ * message. Rows follow the requested message order, then link position.
+ */
+export function getAttachmentMetadataForMessages(
+  messageIds: string[],
+): MessageAttachmentMetadata[] {
+  if (messageIds.length === 0) {
+    return [];
   }
-  return results;
+  const db = getDb();
+  const rows = db
+    .select({
+      messageId: messageAttachments.messageId,
+      messageMetadata: messages.metadata,
+      position: messageAttachments.position,
+      id: attachments.id,
+      originalFilename: attachments.originalFilename,
+      mimeType: attachments.mimeType,
+      sizeBytes: attachments.sizeBytes,
+      kind: attachments.kind,
+      thumbnailBase64: attachments.thumbnailBase64,
+      createdAt: attachments.createdAt,
+    })
+    .from(messageAttachments)
+    .innerJoin(messages, eq(messages.id, messageAttachments.messageId))
+    .innerJoin(attachments, eq(attachments.id, messageAttachments.attachmentId))
+    .where(inArray(messageAttachments.messageId, messageIds))
+    .all();
+  const messageOrder = new Map(messageIds.map((id, index) => [id, index]));
+  rows.sort((a, b) => {
+    const messageDelta =
+      (messageOrder.get(a.messageId) ?? 0) -
+      (messageOrder.get(b.messageId) ?? 0);
+    return messageDelta !== 0 ? messageDelta : a.position - b.position;
+  });
+  return rows.map(
+    ({ messageId, messageMetadata, position: _position, ...a }) => ({
+      messageId,
+      messageMetadata,
+      attachment: a,
+    }),
+  );
 }
 
 /**

package/src/persistence/conversation-crud.ts

@@ -94,6 +94,8 @@ import {
 import { deleteConversationRowsInBatches } from "./conversation-row-batch-delete.js";
 import {
   BACKGROUND_CONVERSATION_TYPES,
+  COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY,
+  computerUseScreenshotAttachmentIdsFromMetadata,
   type ConversationCreateType,
   type ConversationOrigin,
   isHiddenMessageMetadata,
@@ -413,6 +415,9 @@ export const messageMetadataSchema = z
      * channel/interface fields cannot stand in for it.
      */
     voiceSessionTurn: z.boolean().optional(),
+    [COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY]: z
+      .array(z.string())
+      .optional(),
     /**
      * Discriminates daemon-authored rows from ordinary turns.
      * `"system_card"` marks pre-composed status cards (the /compact, /clean,
@@ -1849,7 +1854,25 @@ function populateForkContentsInProcess(args: PopulateForkContentsArgs): void {
     });
   }
 
-  widenForkSightFrameTags(messagesToCopy, forkedMessageIds, attachmentIdMap);
+  remapForkWorkspaceAttachmentRefs(
+    messagesToCopy,
+    forkedMessageIds,
+    attachmentIdMap,
+  );
+  widenForkAttachmentIdTags(
+    messagesToCopy,
+    forkedMessageIds,
+    attachmentIdMap,
+    SIGHT_FRAME_ATTACHMENT_IDS_KEY,
+    sightFrameAttachmentIdsFromMetadata,
+  );
+  widenForkAttachmentIdTags(
+    messagesToCopy,
+    forkedMessageIds,
+    attachmentIdMap,
+    COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY,
+    computerUseScreenshotAttachmentIdsFromMetadata,
+  );
 
   // Set lastMessageAt to the max createdAt of copied messages so the
   // forked conversation sorts correctly by message recency.
@@ -1895,31 +1918,99 @@ 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.
+ * Remap copied workspace references to the fork-scoped attachment ids created
+ * by the relink loop.
  *
- * 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.
+ * The same source attachment can be linked to several copied messages. The
+ * shared map keeps every copied reference and message link on one cloned row,
+ * while references to attachments outside the copied window stay unchanged.
+ */
+function remapForkWorkspaceAttachmentRefs(
+  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 remappedContent = remapWorkspaceAttachmentRefs(
+      message.content,
+      attachmentIdMap,
+    );
+    if (remappedContent === message.content) {
+      continue;
+    }
+
+    db.update(messages)
+      .set({ content: JSON.stringify(remappedContent) })
+      .where(eq(messages.id, forkedMessageId))
+      .run();
+  }
+}
+
+function remapWorkspaceAttachmentRefs(
+  value: unknown,
+  attachmentIdMap: ReadonlyMap<string, string>,
+): unknown {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const remapped = value.map((entry) => {
+      const next = remapWorkspaceAttachmentRefs(entry, attachmentIdMap);
+      changed ||= next !== entry;
+      return next;
+    });
+    return changed ? remapped : value;
+  }
+
+  if (value == null || typeof value !== "object") {
+    return value;
+  }
+
+  const record = value as Record<string, unknown>;
+  let changed = false;
+  const remapped: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    let next = remapWorkspaceAttachmentRefs(entry, attachmentIdMap);
+    if (
+      key === "attachmentId" &&
+      record.type === "workspace_ref" &&
+      typeof entry === "string"
+    ) {
+      next = attachmentIdMap.get(entry) ?? entry;
+    }
+    changed ||= next !== entry;
+    remapped[key] = next;
+  }
+  return changed ? remapped : value;
+}
+
+/**
+ * Extend a copied row's attachment-id metadata to name cloned ids alongside
+ * the source ids it was written with.
  *
- * 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.
+ * Copied message content uses the fork-scoped ids, while metadata begins as a
+ * copy of the source row. Naming both ids preserves compatibility with readers
+ * of either vocabulary. Extra ids are inert because an id no block or linked
+ * attachment 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(
+function widenForkAttachmentIdTags(
   messagesToCopy: MessageRow[],
   forkedMessageIds: Map<string, string>,
   attachmentIdMap: Map<string, string>,
+  metadataKey: string,
+  readIds: (metadata: Record<string, unknown> | null | undefined) => string[],
 ): void {
   if (attachmentIdMap.size === 0) {
     return;
@@ -1931,7 +2022,7 @@ function widenForkSightFrameTags(
       continue;
     }
     const sourceMetadata = parseMessageMetadata(message.metadata);
-    const sourceIds = sightFrameAttachmentIdsFromMetadata(sourceMetadata);
+    const sourceIds = readIds(sourceMetadata);
     if (sourceIds.length === 0) {
       continue;
     }
@@ -1955,7 +2046,7 @@ function widenForkSightFrameTags(
       .set({
         metadata: JSON.stringify({
           ...(forkedMetadata ?? {}),
-          [SIGHT_FRAME_ATTACHMENT_IDS_KEY]: [...widened],
+          [metadataKey]: [...widened],
         }),
       })
       .where(eq(messages.id, forkedMessageId))
@@ -2806,8 +2897,8 @@ export interface ConversationAttachmentListing {
  * Driven from `messages` so the lineage predicate rides
  * `idx_messages_conversation_created_at`. An attachment linked to more than
  * one row is listed once, on the newest row that carries it. Tool-result rows
- * are left out: the transcript never shows them, and the assistant row carries
- * the promoted copy of every image a tool produced.
+ * are left out: reply-linked output belongs in Files, while tool-result-only
+ * media stays available through tool history.
  *
  * The lineage-wide select still reads every linked row: an exact `total` and
  * the metadata-derived flags are only known after the role and visibility

package/src/persistence/conversation-plugin-facade.ts

@@ -1,3 +1,4 @@
+import type { ToolDefinition } from "../providers/types.js";
 import type {
   AddMessageOptions,
   ConversationRow,
@@ -5,6 +6,7 @@ import type {
   MessageRow,
 } from "./conversation-crud.js";
 import type { ArchiveStatusFilter } from "./conversation-queries.js";
+import type { ConversationToolSurface } from "./conversation-tool-surface.js";
 import type { ConversationType } from "./conversation-types.js";
 
 /**
@@ -52,6 +54,34 @@ export async function getMessages(
   return fn(conversationId);
 }
 
+/**
+ * What the conversation's most recent live turn sent to the provider that a
+ * replaying fork reproduces verbatim (its tool definitions and the
+ * delegation-section state of its system prompt), or `null` when none has
+ * been recorded.
+ */
+export async function getRecordedConversationToolSurface(
+  conversationId: string,
+): Promise<ConversationToolSurface | null> {
+  const { getConversationToolSurface: fn } =
+    await import("./conversation-tool-surface.js");
+  return fn(conversationId);
+}
+
+/**
+ * The tool definitions the conversation's most recent live turn sent to the
+ * provider, or `null` when none has been recorded. A projection of
+ * {@link getRecordedConversationToolSurface}: a fork replaying the source's
+ * request needs the whole record, whose delegation-section state the system
+ * prompt tier of the provider cache prefix depends on.
+ */
+export async function getConversationToolSurface(
+  conversationId: string,
+): Promise<ToolDefinition[] | null> {
+  const surface = await getRecordedConversationToolSurface(conversationId);
+  return surface?.tools ?? null;
+}
+
 /** Whether the conversation currently has a turn in flight. */
 export async function isConversationProcessing(id: string): Promise<boolean> {
   const { isConversationProcessing: fn } =

package/src/persistence/conversation-tool-surface.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+
+import { eq, sql } from "drizzle-orm";
+
+import type { ToolDefinition } from "../providers/types.js";
+import { getDb } from "./db-connection.js";
+import { conversationToolSurfaces } from "./schema/index.js";
+
+/**
+ * Per-conversation record of what the most recent live turn sent to the
+ * provider that a fork wake cannot re-derive (`conversation_tool_surfaces`).
+ *
+ * The provider prompt cache is a byte-exact prefix match over
+ * `tools -> system -> messages`, so a background wake that forks a
+ * conversation can only reuse the source's cached prefix by sending the SAME
+ * tools array under the SAME system prompt. Re-deriving either on the fork
+ * cannot guarantee that: the fork may run in another process (a different
+ * tool registry), with no connected clients (different host-tool gates),
+ * under a presence the persisted message stamps do not encode, or under a
+ * wake scope that cannot spawn subagents where the source could (the system
+ * prompt's delegation section). Recording the resolved values and replaying
+ * them verbatim can.
+ */
+
+/** What a live turn sent that a replaying fork reproduces verbatim. */
+export interface ConversationToolSurface {
+  /** The tool definitions the turn sent, exactly as resolved. */
+  tools: ToolDefinition[];
+  /**
+   * Whether the turn's system prompt rendered the parallel-delegation
+   * section (`01-parallel-tasks`), which the prompt derives from the same
+   * resolved tool surface plus the turn's channel. `null` when unknown: the
+   * turn ran on a system-prompt override, or the row predates the column.
+   */
+  delegateIndependentTasks: boolean | null;
+}
+
+/** Content hash of the serialized surface. */
+export function hashConversationToolSurface(
+  surface: ConversationToolSurface,
+): string {
+  return hashSurface(
+    JSON.stringify(surface.tools),
+    surface.delegateIndependentTasks,
+  );
+}
+
+function hashSurface(
+  toolsJson: string,
+  delegateIndependentTasks: boolean | null,
+): string {
+  const marker =
+    delegateIndependentTasks === null
+      ? ""
+      : delegateIndependentTasks
+        ? "1"
+        : "0";
+  return createHash("sha256")
+    .update(toolsJson)
+    .update("\n")
+    .update(marker)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * Persist `surface` as the conversation's current wire surface and return
+ * its hash. `knownHash` is the hash the caller last recorded for this
+ * conversation (undefined when it has recorded nothing this process
+ * lifetime): a matching hash skips the statement outright. Otherwise the
+ * upsert only rewrites a row whose stored hash differs, so a conversation
+ * reloaded from disk never rewrites an unchanged surface either.
+ */
+export function recordConversationToolSurface(
+  conversationId: string,
+  surface: ConversationToolSurface,
+  knownHash?: string,
+): string {
+  const toolsJson = JSON.stringify(surface.tools);
+  const { delegateIndependentTasks } = surface;
+  const toolsHash = hashSurface(toolsJson, delegateIndependentTasks);
+  if (knownHash === toolsHash) {
+    return toolsHash;
+  }
+  const updatedAt = Date.now();
+  getDb()
+    .insert(conversationToolSurfaces)
+    .values({
+      conversationId,
+      toolsJson,
+      toolsHash,
+      delegateIndependentTasks,
+      updatedAt,
+    })
+    .onConflictDoUpdate({
+      target: conversationToolSurfaces.conversationId,
+      set: { toolsJson, toolsHash, delegateIndependentTasks, updatedAt },
+      setWhere: sql`${conversationToolSurfaces.toolsHash} <> excluded.tools_hash`,
+    })
+    .run();
+  return toolsHash;
+}
+
+/**
+ * The surface the conversation's most recent live turn sent, or `null` when
+ * no turn has recorded one (or the stored JSON is unreadable).
+ */
+export function getConversationToolSurface(
+  conversationId: string,
+): ConversationToolSurface | null {
+  const row = getDb()
+    .select({
+      toolsJson: conversationToolSurfaces.toolsJson,
+      delegateIndependentTasks:
+        conversationToolSurfaces.delegateIndependentTasks,
+    })
+    .from(conversationToolSurfaces)
+    .where(eq(conversationToolSurfaces.conversationId, conversationId))
+    .get();
+  if (!row) {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(row.toolsJson);
+    if (!Array.isArray(parsed)) {
+      return null;
+    }
+    return {
+      tools: parsed as ToolDefinition[],
+      delegateIndependentTasks: row.delegateIndependentTasks ?? null,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/persistence/conversation-types.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY,
+  computerUseScreenshotAttachmentIdsFromMetadata,
+} from "./conversation-types.js";
+
+describe("computerUseScreenshotAttachmentIdsFromMetadata", () => {
+  test("returns valid nonempty attachment ids", () => {
+    expect(
+      computerUseScreenshotAttachmentIdsFromMetadata({
+        [COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY]: [
+          "attachment-1",
+          "",
+          42,
+          "attachment-2",
+        ],
+      }),
+    ).toEqual(["attachment-1", "attachment-2"]);
+  });
+
+  test("treats absent and malformed metadata as legacy", () => {
+    expect(computerUseScreenshotAttachmentIdsFromMetadata(undefined)).toEqual(
+      [],
+    );
+    expect(
+      computerUseScreenshotAttachmentIdsFromMetadata({
+        [COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY]: "attachment-1",
+      }),
+    ).toEqual([]);
+  });
+});

package/src/persistence/conversation-types.ts

@@ -82,7 +82,10 @@ export function isBackgroundConversationType(
  * columns into one label.
  */
 export type ConversationKind =
-  "user" | "background" | "background_memory_consolidation" | "scheduled";
+  | "user"
+  | "background"
+  | "background_memory_consolidation"
+  | "scheduled";
 
 /**
  * Single classifier shared by the LLM-context routes and the notification
@@ -270,6 +273,10 @@ export function isVoiceSessionUserMessage(
  */
 export const SIGHT_FRAME_ATTACHMENT_IDS_KEY = "sightFrameAttachmentIds";
 
+/** Metadata key naming computer-use screenshots automatically linked to a reply. */
+export const COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY =
+  "computerUseScreenshotAttachmentIds";
+
 /**
  * The row's attachments that arrived as ambient camera frames, by attachment
  * id. A user attachment carries no metadata of its own, so the marking lives on
@@ -291,6 +298,23 @@ export function sightFrameAttachmentIdsFromMetadata(
   );
 }
 
+/**
+ * Attachment ids whose placement on this row was automatic computer-use
+ * screenshot promotion. Malformed and legacy metadata conservatively yields
+ * no marked attachments.
+ */
+export function computerUseScreenshotAttachmentIdsFromMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+): string[] {
+  const ids = metadata?.[COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY];
+  if (!Array.isArray(ids)) {
+    return [];
+  }
+  return ids.filter(
+    (id): id is string => typeof id === "string" && id.length > 0,
+  );
+}
+
 /**
  * True when a stored `messages.metadata` column belongs to a standalone
  * ambient camera keep: a row the call's own gate sampled, which no one spoke.
@@ -360,9 +384,7 @@ export function isDesktopOriginatedUserMessage(
     return false;
   }
   const clientOs = parseClientOs((client as Record<string, unknown>).os);
-  return (
-    clientOs === "macos" || clientOs === "windows" || clientOs === "linux"
-  );
+  return clientOs === "macos" || clientOs === "windows" || clientOs === "linux";
 }
 
 /**