@vellumai/assistant 0.12.2-staging.6 → 0.12.2-staging.7

package/docs/architecture/memory.md

@@ -87,8 +87,17 @@ graph LR
   nesting existed still parse, since an unindented body line that is not itself
   entry-shaped is read as a continuation.
 - **Consolidation** (`substrate/consolidation-job.ts`) is a background
-  agent conversation that files buffer entries into concept pages, rewrites
-  the aggregate views, and trims the buffer. Scheduling
+  agent conversation that files buffer entries into concept pages and
+  rewrites the aggregate views. The agent never writes the buffer: the job
+  snapshots `buffer.md`, hands the run its pass's entries verbatim in the
+  prompt, and after the run removes exactly those entries itself through
+  `buffer-file.ts` (the module that also owns the append path, so the two
+  writers of the buffer share one protocol). Removal happens only when the
+  run's persisted messages hold a page-writing tool call with a non-error
+  result, the same evidence bar the retrospective's cursor advance uses; a
+  run that wrote nothing, failed, or timed out leaves the buffer intact for
+  the next pass. Entries deferred past the per-run cap and entries appended
+  while the run was in flight are therefore never lost. Scheduling
   (`maybeEnqueueGraphMaintenanceJobs` in `jobs-worker.ts`):
   - interval-based (`memory.v2.consolidation_interval_hours`, default 8h),
     skipped below `MIN_BUFFER_LINES_FOR_CONSOLIDATION` (10) **unless** the

package/docs/desktop-browser-cli.md

@@ -18,7 +18,7 @@ flowchart LR
 
 Chrome and its dock launcher share the managed profile and loopback debug port. For Chrome reopened from the dock, the profile singleton lock identifies a candidate PID, validated against the installed executable, profile and loopback debug arguments. Discovery checks `/proc` socket ownership against that browser PID, refuses redirects and validates the returned browser WebSocket endpoint. The connection stays within the container. No CDP endpoint or token is exposed to the renderer.
 
-The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, cancellation, errors and idle expiry release control. Only `tabs close` closes a Chrome tab.
+The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, turn completion, cancellation, errors and idle expiry release control. Turn completion clears the activity indicator immediately and queues browser cleanup before the next automation session; it leaves Chrome and the current page open for the user. Only `tabs close` closes a Chrome tab.
 
 `assistant browser --virtual-desktop screenshot --output /tmp/desktop-page.jpg` captures a color page image through CDP `Page.captureScreenshot`. It excludes the browser toolbar and desktop dock. `snapshot` returns semantic page structure. Agents should use these interfaces and let the manager start the desktop, including when older memory notes describe manual Xvnc, `xdotool` or scratch XWD conversion scripts.
 
@@ -26,8 +26,10 @@ Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs.
 
 CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation.
 
-The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
+The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Turn-triggered cancellation retries cleanup automatically until it succeeds or ownership changes. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
 
 `--use-active-tab` and personal browser targeting are rejected with `--virtual-desktop`. Download waiting is unsupported. Browser operations are bounded to two minutes and share the desktop lease's action budget and idle expiry.
 
 Validation: focused client tests exercise shared snapshot/click behavior, namespace isolation, stale references, target changes, cancellation and uncertain-input cleanup. Lease tests cover browser ownership, cancellation and cleanup independently of native input. The Linux smoke script exercises real Chrome, the CLI and visible pointer feedback.
+
+The desktop header icon pulses in the assistant's avatar accent color while a browser automation lease is active, including between browser commands. It shares the progress indicator's accent and neutral fallback. Reduced-motion clients show a solid accent. Setup status exposes the optional `automationActive` field; `desktop_activity_changed` events refresh it on acquisition and cancellation or release. Installation progress retains its `assistant:self:desktop` sync invalidations. The indicator reads status without starting installation, and reconnects refetch the current lease state.

package/node_modules/@vellumai/environments/src/shell.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "./shell.js";
@@ -38,6 +39,26 @@ describe("buildShellInvocation", () => {
   });
 });
 
+describe("buildShellSpawnFlags", () => {
+  test("creates a POSIX process group and hides Windows consoles", () => {
+    expect(buildShellSpawnFlags("linux")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+    expect(buildShellSpawnFlags("darwin")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+  });
+
+  test("does not detach Windows children that use piped stdio", () => {
+    expect(buildShellSpawnFlags("win32")).toEqual({
+      detached: false,
+      windowsHide: true,
+    });
+  });
+});
+
 describe("path list handling", () => {
   test("uses the platform delimiter", () => {
     expect(pathListDelimiter("win32")).toBe(";");

package/node_modules/@vellumai/environments/src/shell.ts

@@ -5,6 +5,11 @@ export interface ShellInvocation {
   args: string[];
 }
 
+export interface ShellSpawnFlags {
+  detached: boolean;
+  windowsHide: true;
+}
+
 const WINDOWS_UTF8_PREAMBLE =
   "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; " +
   "$OutputEncoding = [System.Text.Encoding]::UTF8; " +
@@ -43,6 +48,25 @@ export function buildShellInvocation(
   return { command: "bash", args: ["-c", "--", command] };
 }
 
+/**
+ * Spawn flags for assistant-owned shell children (sandbox bash, local
+ * host_bash fallback, sanitized CLI bash, skill runners, scheduled scripts).
+ *
+ * POSIX uses a new process group so timeout/abort can SIGKILL the tree via
+ * `-pid`. Windows process trees are torn down with `taskkill /T`, which does
+ * not need a detached process. Combining `DETACHED_PROCESS`,
+ * `CREATE_NO_WINDOW`, and piped stdio on Windows can emit `close` with exit
+ * 0 and empty pipes without running the encoded command.
+ */
+export function buildShellSpawnFlags(
+  hostPlatform: NodeJS.Platform = process.platform,
+): ShellSpawnFlags {
+  return {
+    detached: hostPlatform !== "win32",
+    windowsHide: true,
+  };
+}
+
 export function pathListDelimiter(
   hostPlatform: NodeJS.Platform = process.platform,
 ): string {

package/node_modules/@vellumai/gateway-client/src/inbound-contract.ts

@@ -83,8 +83,14 @@ export const SourceMetadataSchema = z
     clientTimezone: z.string().optional(),
     /** Channel command intent (e.g. Telegram /start). */
     commandIntent: CommandIntentSchema.optional(),
-    /** Slack-specific: whether the bot was @-mentioned. */
-    slackBotMentioned: z.boolean().optional(),
+    /**
+     * Whether the message addresses the assistant by name, an @-mention on
+     * the platforms that have one. Stated by the channel's normalizer only
+     * where it proved the answer; absent means "not established". Read to
+     * decide whether a reply is expected before any text exists, never to
+     * admit or deny: admission is the gate's job, upstream of this.
+     */
+    botMentioned: z.boolean().optional(),
     /**
      * Slack-specific: the `edited.ts` float-string from a `message_changed`
      * event. Used by the daemon to reject out-of-order edit deliveries whose

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.12.2
+  version: 0.12.1
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -5042,7 +5042,7 @@ paths:
                           type: string
                       required:
                         - type
-                    slackBotMentioned:
+                    botMentioned:
                       type: boolean
                     slackEditedTs:
                       type: string
@@ -11941,6 +11941,8 @@ paths:
                       - ready
                       - failed
                       - unsupported
+                  automationActive:
+                    type: boolean
                   stage:
                     type: string
                     enum:
@@ -11971,6 +11973,8 @@ paths:
                       - ready
                       - failed
                       - unsupported
+                  automationActive:
+                    type: boolean
                   stage:
                     type: string
                     enum:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-staging.6",
+  "version": "0.12.2-staging.7",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -34,7 +34,7 @@
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bun run scripts/test.ts",
     "test:bench": "find src -type f -name '*.benchmark.test.ts' -print0 | xargs -0 -P 1 -I {} bun test {}",
     "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh",
-    "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && ([ -f meta/sync-bundled-copies.ts ] && (bun run meta/sync-bundled-copies.ts && bun run assistant/scripts/generate-bundled-plugin-packages.ts) 2>/dev/null || true)"
+    "postinstall": "bun run scripts/postinstall.ts"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.25.0",

package/scripts/postinstall.ts

@@ -0,0 +1,33 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const repoRoot = resolve(import.meta.dir, "../..");
+
+// Repository setup is best-effort, including installs outside a Git checkout.
+function run(command: string, args: string[]): boolean {
+  return (
+    spawnSync(command, args, {
+      cwd: repoRoot,
+      stdio: ["ignore", "inherit", "ignore"],
+      windowsHide: true,
+    }).status === 0
+  );
+}
+
+if (!run("git", ["config", "core.hooksPath"])) {
+  run("git", ["config", "core.hooksPath", ".githooks"]);
+}
+
+const syncScript = join(repoRoot, "meta", "sync-bundled-copies.ts");
+if (existsSync(syncScript) && run(process.execPath, ["run", syncScript])) {
+  run(process.execPath, [
+    "run",
+    join(
+      repoRoot,
+      "assistant",
+      "scripts",
+      "generate-bundled-plugin-packages.ts",
+    ),
+  ]);
+}

package/scripts/smoke-desktop-browser-cli.ts

@@ -42,6 +42,7 @@ const manager = new DesktopSessionManager({
   renderWallpaper: async () => null,
 });
 const control = new DesktopAutomationLease({
+  notify: async () => {},
   enabled: () => true,
   ready: () =>
     !coldInstall || desktopDependencyInstaller.getStatus().state === "ready",

package/src/__tests__/agent-loop.test.ts

@@ -1977,6 +1977,130 @@ describe("AgentLoop", () => {
     expect(calls[0].tools).not.toEqual(dummyTools);
   });
 
+  test("onToolsSent observes the exact tool array of every provider call", async () => {
+    const perCall: ToolDefinition[][] = [
+      [
+        {
+          name: "first",
+          description: "First",
+          input_schema: { type: "object" },
+        },
+      ],
+      [
+        {
+          name: "second",
+          description: "Second",
+          input_schema: { type: "object" },
+        },
+      ],
+    ];
+    let resolveCount = 0;
+    const sent: ToolDefinition[][] = [];
+
+    const { provider, calls } = createMockProvider([
+      toolUseResponse("t1", "first", {}),
+      textResponse("Done"),
+    ]);
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      toolExecutor: async () => ({ content: "result", isError: false }),
+      resolveTools: () => perCall[resolveCount++]!,
+      onToolsSent: (tools) => {
+        sent.push(tools);
+      },
+    });
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    // One observation per provider call, each the array that call sent.
+    expect(sent).toHaveLength(2);
+    expect(calls[0].tools).toEqual(sent[0]);
+    expect(calls[1].tools).toEqual(sent[1]);
+    expect(sent.map((tools) => tools.map((t) => t.name))).toEqual([
+      ["first"],
+      ["second"],
+    ]);
+  });
+
+  test("onToolsSent sees the provider-native web_search tool the loop appends", async () => {
+    const dynamicTools: ToolDefinition[] = [
+      {
+        name: "dynamic_tool",
+        description: "Dynamic",
+        input_schema: { type: "object" },
+      },
+    ];
+    const sent: ToolDefinition[][] = [];
+
+    const { provider, calls } = createMockProvider([textResponse("Hi")]);
+    Object.assign(provider, { supportsNativeWebSearch: true });
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      config: { enableNativeWebSearch: true },
+      resolveTools: () => dynamicTools,
+      onToolsSent: (tools) => {
+        sent.push(tools);
+      },
+    });
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    // The resolver never saw web_search; the observer sees the wire array.
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.map((t) => t.name)).toEqual(["dynamic_tool", "web_search"]);
+    expect(calls[0].tools).toEqual(sent[0]);
+  });
+
+  test("onToolsSent does not fire for a call cancelled before the request leaves", async () => {
+    // A pre-model-call hook runs after tool resolution and before the send;
+    // aborting there is the window Codex flagged: tools resolved, never sent.
+    const controller = new AbortController();
+    registerPlugin({
+      manifest: { name: "abort-before-send", version: "0.0.1" },
+      hooks: {
+        "pre-model-call": async (ctx) => {
+          controller.abort();
+          return ctx;
+        },
+      },
+    });
+    const sent: ToolDefinition[][] = [];
+    const { provider } = createMockProvider([textResponse("never")]);
+    const loop = new AgentLoop({
+      provider: provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      resolveTools: () => dummyTools,
+      onToolsSent: (tools) => {
+        sent.push(tools);
+      },
+    });
+
+    await loop
+      .run({
+        requestId: "test-request",
+        messages: [userMessage],
+        onEvent: () => {},
+        trust: { sourceChannel: "vellum", trustClass: "unknown" },
+        signal: controller.signal,
+      })
+      .catch(() => {});
+
+    expect(sent).toEqual([]);
+  });
+
   // 28. Tool list can change between turns
   test("resolveTools can return different tools on each turn", async () => {
     const toolsPerTurn: ToolDefinition[][] = [

package/src/__tests__/approval-interception-trust-gates.test.ts

@@ -149,6 +149,46 @@ describe("approval interception trust-class gates", () => {
     expect(sessionMock).toHaveBeenCalled();
   });
 
+  test("guardian apr: callback naming no approval action is consumed as a stale button, never routed as text", async () => {
+    _anchorPrincipalId = "guardian-principal-1";
+    const sessionMock = registerPendingInteraction(
+      "req-guardian-retired-1",
+      CONVERSATION_ID,
+      TOOL_NAME,
+      TOOL_INPUT,
+    );
+
+    // The channel normalizers copy callback data into the message content, so
+    // a button press arrives with both set to the same string.
+    const callbackData = "apr:req-guardian-retired-1:approve_always";
+    const result = await handleApprovalInterception({
+      conversationId: CONVERSATION_ID,
+      callbackData,
+      content: callbackData,
+      conversationExternalId: REQUESTER_CHAT,
+      sourceChannel: "telegram",
+      actorExternalId: "guardian-user-1",
+      replyCallbackUrl: "https://gateway.test/deliver",
+      trustCtx: {
+        sourceChannel: "telegram",
+        trustClass: "guardian",
+        requesterExternalUserId: "guardian-user-1",
+        guardianExternalUserId: "guardian-user-1",
+        guardianPrincipalId: "guardian-principal-1",
+      },
+      assistantId: ASSISTANT_ID,
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.type).toBe("stale_ignored");
+    // No decision, and no reply: the text parsers never saw the callback.
+    expect(sessionMock).not.toHaveBeenCalled();
+    expect(deliverSpy).not.toHaveBeenCalled();
+    expect(pendingInteractions.getByConversation(CONVERSATION_ID)).toHaveLength(
+      1,
+    );
+  });
+
   test("guardian apr: callback with a principal NOT matching the anchor is rejected before any decision", async () => {
     _anchorPrincipalId = "the-real-guardian-principal";
     const sessionMock = registerPendingInteraction(

package/src/__tests__/channel-approval.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, test } from "bun:test";
 
-import type { ApprovalAction } from "../runtime/channel-approval-types.js";
 import { parseCallbackData } from "../runtime/routes/channel-route-shared.js";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -19,19 +18,15 @@ describe("parseCallbackData", () => {
     expect(result!.source).toBe("button");
   });
 
-  test.each<[string, string]>([
-    ["apr:req-123:approve_10m", "approve_once"],
-    ["apr:req-123:approve_conversation", "approve_once"],
-    ["apr:req-123:approve_always", "approve_once"],
-  ])(
-    'maps legacy action "%s" to %s (backward compat)',
-    (data, expectedAction) => {
-      const result = parseCallbackData(data);
-      expect(result).not.toBeNull();
-      expect(result!.action).toBe(expectedAction as ApprovalAction);
-      expect(result!.requestId).toBe("req-123");
-    },
-  );
+  // The parser never maps one action id onto another: an id outside the
+  // approval vocabulary is no action, whatever it resembles.
+  test.each([
+    "apr:req-123:approve_10m",
+    "apr:req-123:approve_conversation",
+    "apr:req-123:approve_always",
+  ])('returns null for the unrecognized action id in "%s"', (data) => {
+    expect(parseCallbackData(data)).toBeNull();
+  });
 
   test("every channel's button press attributes as the button modality", () => {
     for (const channel of ["slack", "telegram", "whatsapp", "discord"]) {

package/src/__tests__/conversation-agent-loop.test.ts

@@ -18,6 +18,7 @@ import {
   queueConversationNotice,
   resetConversationNoticesForTests,
 } from "../daemon/conversation-notices.js";
+import { desktopAutomationLease } from "../desktop/desktop-automation-lease.js";
 import { getConversationDirName } from "../persistence/conversation-directories.js";
 import type { UserPromptSubmitContext } from "../plugin-api/types.js";
 import { resetPluginRegistryAndRegisterDefaults } from "../plugins/defaults/index.js";
@@ -1663,6 +1664,30 @@ describe("session-agent-loop", () => {
     });
   });
 
+  test("releases desktop control before a completed turn accepts another message", async () => {
+    const events: AssistantEvent[] = [];
+    const ctx = makeCtx();
+    const release = spyOn(desktopAutomationLease, "releaseForConversation");
+    const setProcessing = ctx.setProcessing.bind(ctx);
+    ctx.setProcessing = (processing) => {
+      if (!processing) {
+        expect(release).toHaveBeenCalledWith(ctx.conversationId);
+      }
+      setProcessing(processing);
+    };
+    try {
+      await runAgentLoopImpl(ctx, "hello", "msg-1", (event) =>
+        events.push(event),
+      );
+      expect(events.some((event) => event.type === "message_complete")).toBe(
+        true,
+      );
+      expect(release).toHaveBeenCalledTimes(1);
+    } finally {
+      release.mockRestore();
+    }
+  });
+
   describe("tool execution errors via agent loop", () => {
     test("error events from agent loop are classified and emitted", async () => {
       const events: AssistantEvent[] = [];

package/src/__tests__/db-conversation-tool-surface.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tests for the per-conversation wire tool-surface record
+ * (`persistence/conversation-tool-surface.ts`): the resolver records the
+ * tools array a live turn sends, fork wakes read it back verbatim, and an
+ * unchanged surface is never rewritten.
+ */
+
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import {
+  getConversationToolSurface,
+  hashConversationToolSurface,
+  recordConversationToolSurface,
+} from "../persistence/conversation-tool-surface.js";
+import { clearStoredDb, setStoredDb } from "../persistence/db-singleton.js";
+import { migrateCreateConversationToolSurfaces } from "../persistence/migrations/378-create-conversation-tool-surfaces.js";
+import * as schema from "../persistence/schema/index.js";
+import type { ToolDefinition } from "../providers/types.js";
+
+let sqlite: Database;
+
+beforeEach(() => {
+  sqlite = new Database(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  sqlite.run(/*sql*/ `CREATE TABLE conversations (id TEXT PRIMARY KEY)`);
+  sqlite.query(`INSERT INTO conversations (id) VALUES (?)`).run("conv-1");
+  const db = drizzle(sqlite, { schema });
+  migrateCreateConversationToolSurfaces(db);
+  setStoredDb("main", db, () => sqlite.close());
+});
+
+afterEach(() => {
+  clearStoredDb("main");
+});
+
+const TOOLS: ToolDefinition[] = [
+  {
+    name: "remember",
+    description: "Save a fact",
+    input_schema: { type: "object", properties: { content: {} } },
+  },
+  { name: "bell_jingle", description: "Ring", input_schema: {} },
+];
+
+function storedRow(): { tools_hash: string; updated_at: number } | null {
+  return sqlite
+    .query(
+      `SELECT tools_hash, updated_at FROM conversation_tool_surfaces WHERE conversation_id = ?`,
+    )
+    .get("conv-1") as { tools_hash: string; updated_at: number } | null;
+}
+
+describe("recordConversationToolSurface", () => {
+  test("stores the array and returns its content hash", () => {
+    const hash = recordConversationToolSurface("conv-1", TOOLS);
+
+    expect(hash).toBe(hashConversationToolSurface(TOOLS));
+    expect(storedRow()?.tools_hash).toBe(hash);
+    expect(getConversationToolSurface("conv-1")).toEqual(TOOLS);
+  });
+
+  test("replays the exact array, including key order and extra fields", () => {
+    const serverTool = {
+      type: "web_search_20250305",
+      name: "web_search",
+      max_uses: 5,
+    } as unknown as ToolDefinition;
+    const tools = [...TOOLS, serverTool];
+
+    recordConversationToolSurface("conv-1", tools);
+
+    expect(JSON.stringify(getConversationToolSurface("conv-1"))).toBe(
+      JSON.stringify(tools),
+    );
+  });
+
+  test("an unchanged surface with a known hash skips the write", () => {
+    const hash = recordConversationToolSurface("conv-1", TOOLS);
+    const before = storedRow()!.updated_at;
+    sqlite
+      .query(
+        `UPDATE conversation_tool_surfaces SET updated_at = ? WHERE conversation_id = ?`,
+      )
+      .run(before - 1000, "conv-1");
+
+    recordConversationToolSurface("conv-1", TOOLS, hash);
+
+    expect(storedRow()!.updated_at).toBe(before - 1000);
+  });
+
+  test("an unchanged surface with no known hash compares against the stored row before writing", () => {
+    recordConversationToolSurface("conv-1", TOOLS);
+    const marker = 42;
+    sqlite
+      .query(
+        `UPDATE conversation_tool_surfaces SET updated_at = ? WHERE conversation_id = ?`,
+      )
+      .run(marker, "conv-1");
+
+    // A freshly loaded conversation knows no hash yet; the stored row matches,
+    // so nothing is rewritten.
+    recordConversationToolSurface("conv-1", TOOLS, undefined);
+
+    expect(storedRow()!.updated_at).toBe(marker);
+  });
+
+  test("a changed surface overwrites the stored one", () => {
+    const first = recordConversationToolSurface("conv-1", TOOLS);
+    const changed = TOOLS.slice(0, 1);
+
+    const second = recordConversationToolSurface("conv-1", changed, first);
+
+    expect(second).not.toBe(first);
+    expect(storedRow()?.tools_hash).toBe(second);
+    expect(getConversationToolSurface("conv-1")).toEqual(changed);
+  });
+});
+
+describe("getConversationToolSurface", () => {
+  test("returns null when no turn has recorded a surface", () => {
+    expect(getConversationToolSurface("conv-1")).toBeNull();
+  });
+
+  test("returns null for an unreadable stored payload", () => {
+    sqlite
+      .query(
+        /*sql*/ `INSERT INTO conversation_tool_surfaces (conversation_id, tools_json, tools_hash, updated_at) VALUES (?, ?, ?, ?)`,
+      )
+      .run("conv-1", "not json", "h", 1);
+
+    expect(getConversationToolSurface("conv-1")).toBeNull();
+  });
+
+  test("the row cascades with its conversation", () => {
+    recordConversationToolSurface("conv-1", TOOLS);
+
+    sqlite.query(`DELETE FROM conversations WHERE id = ?`).run("conv-1");
+
+    expect(getConversationToolSurface("conv-1")).toBeNull();
+  });
+});

package/src/__tests__/plugin-import-boundary-guard.test.ts

@@ -248,7 +248,6 @@ const BASELINE: Record<string, readonly string[]> = {
     "../../../util/sqlite-retry.js",
     "../../../util/strip-comment-lines.js",
     "../../../util/truncate.js",
-    "../../../util/unicode.js",
     "../../../util/worker-compute.js",
     "../../../util/worker-memory.js",
     "../../../util/worker-process.js",