@vellumai/assistant 0.12.2-dev.202609182214.bd8f92f → 0.12.2-dev.202609190043.ee5ba34

package/docs/desktop-browser-cli.md

@@ -24,7 +24,7 @@ The desktop client bypasses personal-browser discovery, extension reconnect wait
 
 Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs. They are never personal extension tab IDs. Initial attachment selects an existing HTTP(S) page or opens a blank tab. Use `tabs list` and `tabs select --tab-id <id>` to choose explicitly. Navigation, tab selection, document replacement and release clear the desktop snapshot map. Personal-browser snapshots use a separate namespace.
 
-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. For logins, the assistant uses saved credentials first and securely collects missing credentials with `assistant credentials prompt`, then fills the login form itself. Every CAPTCHA and bot-detection challenge, including sliders and press-and-hold checks, is handed to the user before the assistant attempts it. When human interaction is needed, the assistant calls `ask_question` with `desktopHelp: { message, doneLabel, skipLabel }` in the user's language. The tool releases held browser input and reserves the desktop before publishing a question with `presentation: "virtual_desktop"`. The live viewer mounts only in the attended Electron window, with browser focus as a fallback on older shells and the web, so conversations release it when focus changes. A busy viewer offers Reconnect if the previous connection has not finished closing. The compact card lives in the scrolling message transcript, with expandable instructions and a preview capped at 384 pixels wide. It hosts the shared live viewer, with Step In opening its full desktop modal and Done or Skip resolving the existing question response. The assistant retains an exclusive human-help reservation while waiting. Done resumes the same conversation's automation lease for its fresh snapshot; Skip, closure, timeout and cancellation release it. The browser idle timer does not expire a pending human-help reservation. The live preview connects after Show live preview or Step In, and reuses an already-open picture-in-picture viewer. Other devices receiving the card do not automatically open a stream. When the request resolves, its interactive viewer closes or returns to the read-only PiP session that was open before the request. Skip does not imply the obstacle was resolved. Older clients show the same request as a normal Done/Skip question, with model-localized labels retained in history. Channels without dynamic UI return guidance to continue in the app rather than waiting on an unusable card.
+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 use the computer-use skill or direct interaction in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation. For logins, the assistant uses saved credentials first and securely collects missing credentials with `assistant credentials prompt`, then fills the login form itself. Every CAPTCHA and bot-detection challenge, including sliders and press-and-hold checks, is handed to the user before the assistant attempts it. When human interaction is needed, the assistant calls `ask_question` with `desktopHelp: { message, doneLabel, skipLabel }` in the user's language. The tool releases held browser input and reserves the desktop before publishing a question with `presentation: "virtual_desktop"`. The live viewer mounts only in the attended Electron window, with browser focus as a fallback on older shells and the web, so conversations release it when focus changes. A busy viewer offers Reconnect if the previous connection has not finished closing. The compact card lives in the scrolling message transcript, with expandable instructions and a preview capped at 384 pixels wide. It hosts the shared live viewer, with Step In opening its full desktop modal and Done or Skip resolving the existing question response. The assistant retains an exclusive human-help reservation while waiting. Done resumes the same conversation's automation lease for its fresh snapshot; Skip, closure, timeout and cancellation release it. The browser idle timer does not expire a pending human-help reservation. The live preview connects after Show live preview or Step In, and reuses an already-open picture-in-picture viewer. Other devices receiving the card do not automatically open a stream. When the request resolves, its interactive viewer closes or returns to the read-only PiP session that was open before the request. Skip does not imply the obstacle was resolved. Older clients show the same request as a normal Done/Skip question, with model-localized labels retained in history. Channels without dynamic UI return guidance to continue in the app rather than waiting on an unusable card.
 
 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.
 
@@ -35,3 +35,22 @@ Validation: focused client tests exercise shared snapshot/click behavior, namesp
 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.
 
 Desktop streaming checks the current in-memory gateway feature flags during connection startup. Once connected, frame and drain callbacks do not check feature flags or load workspace configuration. Turning the flag off prevents new connections; an existing stream continues until it closes or the desktop stops.
+
+## Computer use on the same desktop
+
+The existing `computer-use` skill defaults to this desktop in platform-hosted
+web conversations. Native desktop clients, including the Mac app connected to a
+platform-hosted assistant, keep the connected-computer default and require
+`target: "assistant-desktop"` to select the virtual desktop explicitly.
+Non-platform assistants keep their connected-computer behavior.
+
+Explicit `target: "connected-computer"` or `target_client_id` selects a connected
+computer on every client. The selected target never falls back to another
+computer when unavailable. Virtual desktop observations return full-screen
+screenshots and mouse actions use screen coordinates.
+
+Observe first and pass the returned `observation_id` with each native action.
+Browser commands, user handoff, errors, and interruption require a fresh
+observation before returning to native input. Browser commands and computer use
+share session ownership, cancellation, and the user-help reservation. Use
+browser commands for page-level operations and computer use for desktop UI.

package/node_modules/@vellumai/gateway-client/src/gateway-ipc-contracts.ts

@@ -43,6 +43,26 @@ export type GatewayLogsTailRouteParams = z.infer<
   typeof GatewayLogsTailRouteParamsSchema
 >;
 
+/**
+ * `gateway_debug_export`: a consistent copy of the gateway database plus its
+ * recent log files, as one gzipped tar, for a debug bundle. No params.
+ */
+export const GatewayDebugExportIpcParamsSchema = z
+  .object({})
+  .strict()
+  .default({});
+
+export const GatewayDebugExportIpcResponseSchema = z.object({
+  ok: z.literal(true),
+  /** `tar.gz` bytes, base64. Contains gateway.sqlite and gateway-logs/. */
+  archive_base64: z.string(),
+  size_bytes: z.number().int().nonnegative(),
+});
+
+export type GatewayDebugExportIpcResponse = z.infer<
+  typeof GatewayDebugExportIpcResponseSchema
+>;
+
 export const GatewayLogsTailIpcResponseSchema = z.object({
   lines: z.array(z.record(z.string(), z.unknown())),
   truncated: z.boolean(),

package/openapi.yaml

@@ -23549,6 +23549,14 @@ paths:
                 description:
                   description: Human-readable export description.
                   type: string
+                profile:
+                  description:
+                    "Export profile. 'migration' (default) builds a teleport bundle. 'debug' builds a bundle for Vellum staff
+                    to open on a debug clone: no credentials, plus the gateway's database and logs under gateway/."
+                  type: string
+                  enum:
+                    - migration
+                    - debug
               required:
                 - upload_url
       responses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609182214.bd8f92f",
+  "version": "0.12.2-dev.202609190043.ee5ba34",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/checker.test.ts

@@ -140,9 +140,17 @@ registerSkillTools("app-builder", [mockBundledSkillTool]);
 
 // Register CU tools so check() can look them up in the tool registry
 // instead of falling through to Medium (unknown tool).
-import { allComputerUseTools } from "../tools/computer-use/definitions.js";
-for (const tool of allComputerUseTools) {
-  registerTool(tool);
+import { COMPUTER_USE_TOOL_NAMES } from "./test-support/computer-use-skill-harness.js";
+for (const name of COMPUTER_USE_TOOL_NAMES) {
+  registerTool({
+    name,
+    description: name,
+    category: "computer-use",
+    defaultRiskLevel: RiskLevel.Low,
+    executionTarget: "host",
+    input_schema: { type: "object", properties: {} },
+    execute: async () => ({ content: "ok", isError: false }),
+  });
 }
 
 function writeSkill(

package/src/__tests__/computer-use-skill-manifest-regression.test.ts

@@ -3,7 +3,6 @@ import { resolve } from "node:path";
 import { afterAll, describe, expect, test } from "bun:test";
 
 import { RiskLevel } from "../permissions/types.js";
-import { allComputerUseTools } from "../tools/computer-use/definitions.js";
 import {
   __resetRegistryForTesting,
   getTool,
@@ -74,30 +73,6 @@ describe("computer-use skill manifest regression", () => {
     }
   });
 
-  test("manifest descriptions match core definitions", async () => {
-    await initializeTools();
-
-    for (const cuTool of allComputerUseTools) {
-      const manifestTool = manifest.tools.find(
-        (t: { name: string }) => t.name === cuTool.name,
-      );
-      expect(manifestTool).toBeDefined();
-      expect(manifestTool.description).toBe(cuTool.description);
-    }
-  });
-
-  test("manifest input_schema matches core definitions", async () => {
-    await initializeTools();
-
-    for (const cuTool of allComputerUseTools) {
-      const manifestTool = manifest.tools.find(
-        (t: { name: string }) => t.name === cuTool.name,
-      );
-      expect(manifestTool).toBeDefined();
-      expect(manifestTool.input_schema).toEqual(cuTool.input_schema);
-    }
-  });
-
   test("CU action tools are not registered as core tools after initializeTools()", async () => {
     await initializeTools();
 

package/src/__tests__/computer-use-tools.test.ts

@@ -1,246 +1,14 @@
 import { describe, expect, test } from "bun:test";
 
-import {
-  allComputerUseTools,
-  computerUseClickTool,
-  computerUseDoneTool,
-  computerUseDragTool,
-  computerUseKeyTool,
-  computerUseObserveTool,
-  computerUseOpenAppTool,
-  computerUseRespondTool,
-  computerUseRunAppleScriptTool,
-  computerUseScrollTool,
-  computerUseTypeTextTool,
-  computerUseWaitTool,
-} from "../tools/computer-use/definitions.js";
 import { forwardComputerUseProxyTool } from "../tools/computer-use/skill-proxy-bridge.js";
 import type { ToolContext } from "../tools/types.js";
 
-interface JsonSchema {
-  type?: string;
-  required?: string[];
-  properties?: Record<string, unknown>;
-}
-
-/** Cast a tool definition's input_schema to a usable JSON Schema shape. */
-function schema(tool: { input_schema?: object }): JsonSchema {
-  return tool.input_schema as JsonSchema;
-}
-
 const ctx: ToolContext = {
   workingDir: "/tmp",
-  conversationId: "test-conversation",
+  conversationId: "conv-123",
   trustClass: "guardian",
 };
 
-// ── Tool definitions ────────────────────────────────────────────────
-
-describe("computer-use tool definitions", () => {
-  test("allComputerUseTools contains 12 tools", () => {
-    expect(allComputerUseTools.length).toBe(12);
-  });
-
-  test("all tools belong to computer-use category", () => {
-    for (const tool of allComputerUseTools) {
-      expect(tool.category).toBe("computer-use");
-    }
-  });
-
-  test("all tools have unique names", () => {
-    const names = allComputerUseTools.map((t) => t.name);
-    expect(new Set(names).size).toBe(names.length);
-  });
-
-  test("all tools have descriptions", () => {
-    for (const tool of allComputerUseTools) {
-      expect(tool.description!.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-// ── observe ─────────────────────────────────────────────────────────
-
-describe("computer_use_observe", () => {
-  test("supports target_client_id", () => {
-    const props = schema(computerUseObserveTool).properties as Record<
-      string,
-      { type: string }
-    >;
-    expect(props.target_client_id.type).toBe("string");
-  });
-});
-
-// ── Unified click tool ──────────────────────────────────────────────
-
-describe("computer_use_click (unified)", () => {
-  test("has correct name", () => {
-    expect(computerUseClickTool.name).toBe("computer_use_click");
-  });
-
-  test("schema requires reasoning", () => {
-    expect(schema(computerUseClickTool).required).toContain("reasoning");
-  });
-
-  test("schema supports click_type enum", () => {
-    const props = schema(computerUseClickTool).properties as Record<
-      string,
-      { type: string; enum?: string[] }
-    >;
-    expect(props.click_type.type).toBe("string");
-    expect(props.click_type.enum).toEqual(["single", "double", "right"]);
-  });
-
-  test("schema supports element_id and coordinates", () => {
-    const props = schema(computerUseClickTool).properties as Record<
-      string,
-      { type: string }
-    >;
-    expect(props.element_id.type).toBe("integer");
-    expect(props.x.type).toBe("integer");
-    expect(props.y.type).toBe("integer");
-  });
-
-  test("execute returns isError when no proxy resolver is configured", async () => {
-    const result = await computerUseClickTool.execute({}, ctx);
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "The Vellum desktop app is needed to view or control your screen",
-    );
-    expect(result.content).toContain("https://www.vellum.ai/downloads");
-  });
-});
-
-// ── type_text ───────────────────────────────────────────────────────
-
-describe("computer_use_type_text", () => {
-  test("requires text and reasoning", () => {
-    expect(schema(computerUseTypeTextTool).required).toContain("text");
-    expect(schema(computerUseTypeTextTool).required).toContain("reasoning");
-  });
-
-  test("execute returns isError when no proxy resolver is configured", async () => {
-    const result = await computerUseTypeTextTool.execute({}, ctx);
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "The Vellum desktop app is needed to view or control your screen",
-    );
-    expect(result.content).toContain("https://www.vellum.ai/downloads");
-  });
-});
-
-// ── key ─────────────────────────────────────────────────────────────
-
-describe("computer_use_key", () => {
-  test("requires key and reasoning", () => {
-    expect(schema(computerUseKeyTool).required).toContain("key");
-    expect(schema(computerUseKeyTool).required).toContain("reasoning");
-  });
-
-  test("execute returns isError when no proxy resolver is configured", async () => {
-    const result = await computerUseKeyTool.execute({}, ctx);
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "The Vellum desktop app is needed to view or control your screen",
-    );
-    expect(result.content).toContain("https://www.vellum.ai/downloads");
-  });
-});
-
-// ── scroll ──────────────────────────────────────────────────────────
-
-describe("computer_use_scroll", () => {
-  test("requires direction, amount, and reasoning", () => {
-    expect(schema(computerUseScrollTool).required).toContain("direction");
-    expect(schema(computerUseScrollTool).required).toContain("amount");
-    expect(schema(computerUseScrollTool).required).toContain("reasoning");
-  });
-
-  test("direction enum includes up, down, left, right", () => {
-    const props = schema(computerUseScrollTool).properties as Record<
-      string,
-      { enum?: string[] }
-    >;
-    expect(props.direction.enum).toEqual(["up", "down", "left", "right"]);
-  });
-});
-
-// ── drag ────────────────────────────────────────────────────────────
-
-describe("computer_use_drag", () => {
-  test("supports source and destination coordinates", () => {
-    const props = schema(computerUseDragTool).properties as Record<
-      string,
-      { type: string }
-    >;
-    expect(props.element_id.type).toBe("integer");
-    expect(props.to_element_id.type).toBe("integer");
-    expect(props.x.type).toBe("integer");
-    expect(props.y.type).toBe("integer");
-    expect(props.to_x.type).toBe("integer");
-    expect(props.to_y.type).toBe("integer");
-  });
-
-  test("requires reasoning only", () => {
-    expect(schema(computerUseDragTool).required).toEqual(["reasoning"]);
-  });
-});
-
-// ── wait ────────────────────────────────────────────────────────────
-
-describe("computer_use_wait", () => {
-  test("requires duration_ms and reasoning", () => {
-    expect(schema(computerUseWaitTool).required).toContain("duration_ms");
-    expect(schema(computerUseWaitTool).required).toContain("reasoning");
-  });
-});
-
-// ── open_app ────────────────────────────────────────────────────────
-
-describe("computer_use_open_app", () => {
-  test("requires app_name and reasoning", () => {
-    expect(schema(computerUseOpenAppTool).required).toContain("app_name");
-    expect(schema(computerUseOpenAppTool).required).toContain("reasoning");
-  });
-});
-
-// ── run_applescript ─────────────────────────────────────────────────
-
-describe("computer_use_run_applescript", () => {
-  test("requires script and reasoning", () => {
-    expect(schema(computerUseRunAppleScriptTool).required).toContain("script");
-    expect(schema(computerUseRunAppleScriptTool).required).toContain(
-      "reasoning",
-    );
-  });
-
-  test("description warns against do shell script", () => {
-    expect(computerUseRunAppleScriptTool.description).toContain(
-      "do shell script",
-    );
-    expect(computerUseRunAppleScriptTool.description).toContain("blocked");
-  });
-});
-
-// ── done ────────────────────────────────────────────────────────────
-
-describe("computer_use_done", () => {
-  test("requires summary", () => {
-    expect(schema(computerUseDoneTool).required).toContain("summary");
-  });
-});
-
-// ── respond ─────────────────────────────────────────────────────────
-
-describe("computer_use_respond", () => {
-  test("requires answer and reasoning", () => {
-    expect(schema(computerUseRespondTool).required).toContain("answer");
-    expect(schema(computerUseRespondTool).required).toContain("reasoning");
-  });
-});
-
-// ── skill-proxy-bridge ──────────────────────────────────────────────
-
 describe("forwardComputerUseProxyTool", () => {
   test("returns error when no proxy resolver available", async () => {
     const result = await forwardComputerUseProxyTool(

package/src/__tests__/conversation-tool-setup-attribution.test.ts

@@ -10,6 +10,7 @@
 import { beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
 
 import type { Conversation } from "../daemon/conversation.js";
+import { shouldUseVirtualDesktop } from "../desktop/virtual-desktop-feature.js";
 import type { PermissionPrompter } from "../permissions/prompter.js";
 import type { SecretPrompter } from "../permissions/secret-prompter.js";
 import type { ToolExecutor } from "../tools/executor.js";
@@ -307,6 +308,28 @@ describe("createToolExecutor attribution threading", () => {
   });
 });
 
+test("desktop routing honors the pinned interface when the live client changes", async () => {
+  for (const transportInterface of ["web", "macos"] as const) {
+    const { executor, calls } = makeCapturingExecutor();
+    await makeToolFn(
+      executor,
+      makeCtx({
+        transportInterface: transportInterface === "web" ? "macos" : "web",
+        toolContextPin: { hasNoClient: false, transportInterface },
+        getTurnActorPrincipalId: () => "user-123",
+        currentTurnTrustContext: {
+          sourceChannel: "vellum",
+          trustClass: "guardian",
+        },
+      }),
+    )("computer_use_observe", {});
+
+    expect(shouldUseVirtualDesktop(calls[0].context, true)).toBe(
+      transportInterface === "web",
+    );
+  }
+});
+
 describe("createToolExecutor isInteractive threading", () => {
   test("uses the resolved turn-level interactivity over live client state", async () => {
     // A scheduled/background turn (currentTurnIsNonInteractive=true) must read

package/src/__tests__/interrupt-on-send.test.ts

@@ -21,6 +21,7 @@ import {
   abortedToolResultText,
   CANCELLED_TOOL_RESULT_TEXT,
   createAbortReason,
+  INTERRUPTED_TURN_NOTE_TEXT,
   PREEMPTED_TOOL_RESULT_TEXT,
 } from "../util/abort-reasons.js";
 
@@ -378,8 +379,8 @@ describe("interruptRunningTurn", () => {
 
   test("arms the interrupted-turn note when the abort caught no tool call", async () => {
     // The abort landed during the provider call, so there is no `tool_use` to
-    // answer and nothing in the history says the turn was cut off. The note
-    // rides on the interrupting user message instead.
+    // answer. The note on the interrupting user message is the only thing that
+    // tells the model what happened.
     const turn = registerBusyTurn({
       messages: [
         { role: "user", content: [{ type: "text", text: "research this" }] },
@@ -393,9 +394,9 @@ describe("interruptRunningTurn", () => {
     expect(persisted).toEqual([]);
   });
 
-  test("leaves the note disarmed when the repair answered a tool call", async () => {
-    // The preempted `tool_result` already tells the model a message cut it
-    // off, so repeating that in a note on the message is noise.
+  test("arms the note alongside the fact-only result of a stopped tool call", async () => {
+    // The two texts do different jobs: the `tool_result` states what happened
+    // to that one call, the note says what to do about the interruption.
     const turn = registerBusyTurn({
       messages: [assistantWithToolUse("tool-1")],
     });
@@ -404,13 +405,36 @@ describe("interruptRunningTurn", () => {
 
     expect(persisted).toHaveLength(1);
     expect(persisted[0].content).toContain(PREEMPTED_TOOL_RESULT_TEXT);
-    expect(turn.conversation.pendingInterruptNote).toBe(false);
+    expect(turn.conversation.pendingInterruptNote).toBe(true);
+  });
+
+  test("arms exactly one note however many parallel calls were stopped", async () => {
+    // Every stopped call gets its own fact-only result; the behavior
+    // instruction is read once, off the interrupting message.
+    const turn = registerBusyTurn({
+      messages: [assistantWithToolUse("tool-1", "tool-2", "tool-3")],
+    });
+
+    await interruptRunningTurn(turn.conversation, { origin: "test" });
+
+    const results = JSON.parse(persisted[0].content) as Array<{
+      tool_use_id: string;
+      content: string;
+    }>;
+    expect(results.map((block) => block.tool_use_id)).toEqual([
+      "tool-1",
+      "tool-2",
+      "tool-3",
+    ]);
+    for (const block of results) {
+      expect(block.content).toBe(PREEMPTED_TOOL_RESULT_TEXT);
+    }
+    expect(turn.conversation.pendingInterruptNote).toBe(true);
   });
 
-  test("leaves the note disarmed when the loop wrote its own preempted result", async () => {
+  test("arms the note when the loop wrote its own preempted result", async () => {
     // The agent loop's abort handler unwound cleanly and answered the batch
-    // itself, so the repair finds nothing to do and the notice is already
-    // there.
+    // itself, so the repair finds nothing to do. The note is owed all the same.
     const turn = registerBusyTurn({
       messages: [
         assistantWithToolUse("tool-1"),
@@ -421,12 +445,10 @@ describe("interruptRunningTurn", () => {
     await interruptRunningTurn(turn.conversation, { origin: "test" });
 
     expect(persisted).toEqual([]);
-    expect(turn.conversation.pendingInterruptNote).toBe(false);
+    expect(turn.conversation.pendingInterruptNote).toBe(true);
   });
 
   test("arms the note when the cut-off tool call was an ordinary cancel", async () => {
-    // A tail answered with the plain cancel wording is a stop the user made
-    // earlier, not this interrupt's notice, so the note is still owed.
     const turn = registerBusyTurn({
       messages: [
         assistantWithToolUse("tool-1"),
@@ -633,6 +655,9 @@ describe("interruptRunningTurn", () => {
     // Armed instead, so the drain that runs the queued message repairs it.
     expect(turn.conversation.pendingInterruptRepair).toBe(true);
     expect(turn.activityEvents).toEqual([]);
+    // The message joins the queue rather than replacing the turn, so it is not
+    // the message that interrupted anything and carries no note.
+    expect(turn.conversation.pendingInterruptNote).toBe(false);
   });
 
   test("a second interrupt stops the turn the first one started", async () => {
@@ -932,7 +957,7 @@ describe("repairInterruptedToolUseBlocks", () => {
     } as unknown as Conversation;
   }
 
-  test("writes one result per abandoned call, worded for a preemption", async () => {
+  test("writes one fact-only result per abandoned call", async () => {
     const messages: Message[] = [assistantWithToolUse("tool-1", "tool-2")];
 
     await repairInterruptedToolUseBlocks(fakeConversation(messages), {
@@ -961,31 +986,6 @@ describe("repairInterruptedToolUseBlocks", () => {
     );
   });
 
-  test("reports the preempted result it wrote", async () => {
-    const messages: Message[] = [assistantWithToolUse("tool-1")];
-
-    const result = await repairInterruptedToolUseBlocks(
-      fakeConversation(messages),
-      { force: true },
-    );
-
-    expect(result.preemptedToolResultOnTail).toBe(true);
-  });
-
-  test("reports no preempted result on a history that ends on plain text", async () => {
-    const messages: Message[] = [
-      { role: "user", content: [{ type: "text", text: "hi" }] },
-      { role: "assistant", content: [{ type: "text", text: "hello" }] },
-    ];
-
-    const result = await repairInterruptedToolUseBlocks(
-      fakeConversation(messages),
-      { force: true },
-    );
-
-    expect(result.preemptedToolResultOnTail).toBe(false);
-  });
-
   test("adds nothing when the loop already wrote its own results", async () => {
     // The agent loop's abort handler synthesizes results of its own when it
     // unwinds cleanly, so exactly one result per call exists either way.
@@ -994,14 +994,12 @@ describe("repairInterruptedToolUseBlocks", () => {
       toolResult("tool-1", PREEMPTED_TOOL_RESULT_TEXT),
     ];
 
-    const result = await repairInterruptedToolUseBlocks(
-      fakeConversation(messages),
-      { force: true },
-    );
+    await repairInterruptedToolUseBlocks(fakeConversation(messages), {
+      force: true,
+    });
 
     expect(messages).toHaveLength(2);
     expect(persisted).toEqual([]);
-    expect(result.preemptedToolResultOnTail).toBe(true);
   });
 
   test("does nothing on a history that ends on an ordinary assistant reply", async () => {
@@ -1083,3 +1081,19 @@ describe("abortedToolResultText", () => {
     );
   });
 });
+
+describe("the interrupt texts", () => {
+  test("the tool result states the fact and nothing more", () => {
+    // Repeated once per stopped call in a parallel batch, so an instruction
+    // here is read as many times as the batch was wide.
+    expect(PREEMPTED_TOOL_RESULT_TEXT).toBe(
+      "Stopped early because the user sent a new message. This call may have completed anyway; check before repeating it.",
+    );
+  });
+
+  test("the note carries the behavior and leads with the reply", () => {
+    expect(INTERRUPTED_TURN_NOTE_TEXT).toBe(
+      "<interrupted_turn>The user sent this while you were still working, so that work stopped. Reply right away, in a line or two, before any more thinking or tool calls, so the user knows you heard them. Then pick the earlier work back up only if it is still wanted. Never apologize for or mention the interruption.</interrupted_turn>",
+    );
+  });
+});

package/src/__tests__/interrupt-turn-note.test.ts

@@ -1,10 +1,9 @@
 /**
- * An interrupt whose abort landed during the provider call leaves no
- * `tool_use` to answer, so nothing in the history tells the model its turn was
- * cut off. The interrupting user message carries the notice instead, on its
- * LLM-facing content only: the persisted row stays exactly what the user
- * typed, so no client renders it, and `interruptedPriorTurn` in the row's
- * metadata is what rebuilds the identical block on every later load.
+ * The message that interrupted a turn carries the note saying what to do about
+ * the interruption, on its LLM-facing content only: the persisted row stays
+ * exactly what the user typed, so no client renders it, and
+ * `interruptedPriorTurn` in the row's metadata is what rebuilds the identical
+ * block on every later load.
  */
 import { beforeEach, describe, expect, test } from "bun:test";