@vellumai/assistant 0.12.2-dev.202609182214.bd8f92f → 0.12.2-dev.202609182314.c515b72

package/package.json

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

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";
 

package/src/daemon/conversation-interrupt-repair.ts

@@ -15,37 +15,6 @@ import type { Conversation } from "./conversation.js";
 
 const log = getLogger("conversation-interrupt-repair");
 
-/**
- * What the repair leaves behind, for the caller that has to decide whether the
- * model was told its turn was cut off.
- */
-export interface InterruptRepairResult {
-  /**
-   * True when the tail of the history carries a preempted `tool_result`,
-   * whether the agent loop's own abort handler wrote it or this repair did.
-   *
-   * That result is the model's notice that a message preempted it. False means
-   * the abort landed with no tool call in flight, so the notice has to ride on
-   * the interrupting user message instead.
-   */
-  preemptedToolResultOnTail: boolean;
-}
-
-/** Whether the last message answers a tool call with the preemption text. */
-function tailCarriesPreemptedToolResult(messages: Message[]): boolean {
-  const tail = messages.at(-1);
-  if (!tail || tail.role !== "user") {
-    return false;
-  }
-  return tail.content.some(
-    (block) =>
-      // Only a synthetic tool_result carries the preemption text; a
-      // server-side web_search_tool_result never does.
-      block.type === "tool_result" &&
-      block.content === PREEMPTED_TOOL_RESULT_TEXT,
-  );
-}
-
 /**
  * Give every abandoned `tool_use` block at the tail of the history a
  * `tool_result`, so the next provider request is well formed.
@@ -78,22 +47,18 @@ function tailCarriesPreemptedToolResult(messages: Message[]): boolean {
 export async function repairInterruptedToolUseBlocks(
   conversation: Conversation,
   options: { force?: boolean; requireDurable?: boolean } = {},
-): Promise<InterruptRepairResult> {
+): Promise<void> {
   const wasSteerArmed = conversation.pendingSteerRepair;
   const wasArmed = conversation.pendingInterruptRepair;
   if (!wasSteerArmed && !wasArmed && options.force !== true) {
-    return {
-      preemptedToolResultOnTail: tailCarriesPreemptedToolResult(
-        conversation.messages,
-      ),
-    };
+    return;
   }
   conversation.pendingSteerRepair = false;
   conversation.pendingInterruptRepair = false;
 
   const messages = conversation.messages;
   if (messages.length === 0) {
-    return { preemptedToolResultOnTail: false };
+    return;
   }
 
   // Walk backwards from the tail to find the last assistant message with
@@ -127,10 +92,7 @@ export async function repairInterruptedToolUseBlocks(
   if (pendingToolUseIds.length === 0) {
     // Nothing dangling either because the turn made no tool call before the
     // abort, or because the loop's abort handler already answered the batch.
-    // Only the second case leaves the model a notice.
-    return {
-      preemptedToolResultOnTail: tailCarriesPreemptedToolResult(messages),
-    };
+    return;
   }
 
   log.info(
@@ -181,5 +143,4 @@ export async function repairInterruptedToolUseBlocks(
       "Failed to persist the synthetic tool_result repair row; the in-memory history carries the repair and the next turn runs on it",
     );
   }
-  return { preemptedToolResultOnTail: true };
 }

package/src/daemon/conversation-interrupt.ts

@@ -316,13 +316,11 @@ export async function interruptRunningTurn(
   }
 
   let repaired = false;
-  let preemptedToolResultOnTail = false;
   try {
-    const repair = await repairInterruptedToolUseBlocks(conversation, {
+    await repairInterruptedToolUseBlocks(conversation, {
       force: true,
       requireDurable: true,
     });
-    preemptedToolResultOnTail = repair.preemptedToolResultOnTail;
     repaired = true;
   } catch (err) {
     // The repair row is not durable, so the caller must not write the
@@ -352,14 +350,12 @@ export async function interruptRunningTurn(
   // busy conversation with nothing running and no path back to idle.
   conversation.pendingInterruptActivityBridge = true;
 
-  // An abort that landed during the provider call answered no tool call, so
-  // nothing in the history tells the model its turn was cut off. Arm the note
-  // the interrupting user message carries instead. A tail that already holds a
-  // preempted `tool_result` needs none: that result says the same thing, and
-  // saying it twice in one prompt is noise.
-  if (!preemptedToolResultOnTail) {
-    conversation.pendingInterruptNote = true;
-  }
+  // Arm the note the interrupting user message carries. It is the one place
+  // the behavior after an interrupt is spelled out, so it rides on every
+  // handover, tool call stopped or not: a synthetic `tool_result` states only
+  // what happened to the one call it answers, and it lands ahead of the user's
+  // words rather than on them.
+  conversation.pendingInterruptNote = true;
 
   return "released";
 }

package/src/daemon/conversation-messaging.ts

@@ -1611,10 +1611,12 @@ export async function persistQueuedMessageBody(
       updateMessageMetadata(persistedUserMessage.id, { attachmentStoredPaths });
     }
 
-    // An interrupt whose abort landed before the turn made a tool call left
-    // the model no `tool_result` saying it was cut off, so this message
-    // carries the notice instead. Consumed here, once: a second message must
-    // not repeat a note about a turn it did not interrupt. Stamped after the
+    // This is the first user row after a handover, so it carries the note that
+    // tells the model what to do about the work the handover stopped. The note
+    // goes on this row because that work sits directly above it in the history,
+    // which is also why it is usually the interrupting message and never has to
+    // be the one that armed the flag. Consumed here, once: a later message sits
+    // under a completed turn, where the note would be stale. Stamped after the
     // insert, like the stored paths above, so a persist that never lands
     // leaves the flag armed for the send that replaces it.
     const carriesInterruptNote = ctx.pendingInterruptNote === true;

package/src/daemon/conversation.ts

@@ -796,17 +796,22 @@ export class Conversation {
    */
   pendingInterruptActivityBridge = false;
   /**
-   * Set by `interruptRunningTurn` when the abort it ran landed with no tool
-   * call in flight, and consumed exactly once by the persist of the
-   * interrupting user message, which appends
+   * Set by `interruptRunningTurn` on every handover it completes, and consumed
+   * exactly once by the first user message persisted after it, which appends
    * {@link INTERRUPTED_TURN_NOTE_TEXT} to that message's LLM-facing content
    * and stamps `interruptedPriorTurn` on the row.
    *
-   * An interrupt caught mid-tool needs nothing here: the synthetic
-   * `tool_result` the loop or the repair writes already tells the model a
-   * message preempted it. Caught mid-provider-call there is no `tool_use` to
-   * answer, so the note is the only signal, and it rides on the message that
-   * did the interrupting.
+   * The note is the only place the behavior after an interrupt is spelled out.
+   * A synthetic `tool_result` states what happened to the one call it answers
+   * and nothing more, so an interrupt caught mid-tool arms this too.
+   *
+   * It belongs to the history position, not to the send that armed it. That
+   * first row is the one sitting directly under the work the handover stopped,
+   * so it is the row whose note the model reads in the right place. Normally it
+   * is the interrupting message itself. When that send loses the lock race and
+   * queues, the message that persists first was also sent while the assistant
+   * was working, and the note is true of it; the queued one drains after a
+   * completed turn, where the same note would be stale.
    * @internal
    */
   pendingInterruptNote = false;

package/src/persistence/conversation-crud.ts

@@ -489,10 +489,10 @@ export const messageMetadataSchema = z
      */
     attachmentStoredPaths: z.record(z.string(), z.string()).optional(),
     /**
-     * Marks a role-`"user"` row whose arrival interrupted a turn that had made
-     * no tool call yet. `loadFromDb` rebuilds the LLM-facing
-     * `<interrupted_turn>` note from it; the row's own content is exactly what
-     * the user sent, so clients render nothing extra.
+     * Marks a role-`"user"` row whose arrival interrupted a running turn.
+     * `loadFromDb` rebuilds the LLM-facing `<interrupted_turn>` note from it;
+     * the row's own content is exactly what the user sent, so clients render
+     * nothing extra.
      */
     interruptedPriorTurn: z.boolean().optional(),
     memoryInjectedBlock: z.string().optional(),

package/src/runtime/AGENTS.md

@@ -24,7 +24,7 @@ Queueing remains the fallback, not a legacy path, and every non-`released` outco
 
 A repair that fell back to the queue carries its durable requirement onto the drain that runs the queued message, and `pendingInterruptRepair` is what carries it: the drain reads that flag and asks `repairInterruptedToolUseBlocks` for `requireDurable`, so a second persist failure leaves the flag armed and the message queued instead of persisting the prompt behind an unmatched durable `tool_use`. Only a steered drain settles for an in-memory repair, because it has no row of its own to persist behind it.
 
-**The model has to be told its turn was cut off, once.** An interrupt caught mid-tool says so through the synthetic `tool_result` (`PREEMPTED_TOOL_RESULT_TEXT`). An interrupt caught during the provider call has no `tool_use` to answer, so `repairInterruptedToolUseBlocks` reports `preemptedToolResultOnTail: false` and the handover arms `pendingInterruptNote`. The persist of the interrupting user message consumes that flag exactly once: it stamps `interruptedPriorTurn` on the row and appends `INTERRUPTED_TURN_NOTE_TEXT` to the message's LLM-facing content only, so the persisted row stays what the user typed and no client renders the note. `reinjectInterruptTurnNote` rebuilds the identical block at history load, next to the attachment annotations and for the same reason: a reload that rebuilds it differently breaks provider prefix-cache parity. Do not add a second annotation for the same interrupt; one notice per cut-off turn.
+**The two interrupt texts are split by job, and the behavior instruction lives in exactly one of them.** A synthetic `tool_result` (`PREEMPTED_TOOL_RESULT_TEXT`) states the fact about the one call it answers: the call stopped early and may have taken effect anyway. It is repeated once per stopped call in a parallel batch, so it holds no instruction. Every completed handover arms `pendingInterruptNote`, whether or not a tool call was stopped. The persist of the interrupting user message consumes that flag exactly once: it stamps `interruptedPriorTurn` on the row and appends `INTERRUPTED_TURN_NOTE_TEXT` to the message's LLM-facing content only, so the persisted row stays what the user typed and no client renders the note. That note is the single place the behavior after an interrupt is written, it leads with the short acknowledgement the user is waiting for, and it sits after the user's words instead of before them. `reinjectInterruptTurnNote` rebuilds the identical block at history load, next to the attachment annotations and for the same reason: a reload that rebuilds it differently breaks provider prefix-cache parity. Do not add a third annotation, and do not put instructions back in the tool result.
 
 Two ordering rules a change here must not break. The synthetic `tool_result` is persisted BEFORE the caller writes the interrupting user row, because a user message between a `tool_use` and its result is a sequence every provider rejects. And the `thinking` / `message_interrupted` activity state is emitted by the agent loop at the head of the replacement turn, never at the handover: activity states are cached in `lastActivityStateMsg` and replayed to reconnecting clients, so a send that fails before its turn starts would otherwise strand every client on a busy conversation that is running nothing.
 

package/src/util/abort-reasons.ts

@@ -78,49 +78,41 @@ export function isUserInterruptAbort(reason: AbortReason | undefined): boolean {
  */
 export const CANCELLED_TOOL_RESULT_TEXT = "Cancelled by user";
 
-/**
- * The instruction both interrupt annotations end on: answer the message that
- * interrupted, then decide what happens to the work it cut off.
- *
- * Shared so the two annotations cannot drift. Resuming the work inline is the
- * trap the last clause closes: the reply the user is waiting for arrives only
- * once the resumed work finishes, so an interrupt that was meant to get their
- * question answered first buys nothing. A subagent carries the work in
- * parallel and leaves the conversation free.
- */
-const INTERRUPT_PRIORITY_INSTRUCTION =
-  "reply to it first, then decide whether to resume or abandon the work that was in progress, and if it is still wanted and too big to finish inline, hand it to a subagent so it continues in parallel instead of holding up the conversation. This is the normal way a conversation flows, not a problem: do not apologize, do not mention that anything was stopped or interrupted, and do not ask the user to wait.";
-
 /**
  * Synthetic `tool_result` text for a tool call a newly arrived user message
  * cut off.
  *
+ * States the fact about this one call and nothing else. What the model should
+ * do about the interruption belongs on the interrupting message
+ * ({@link INTERRUPTED_TURN_NOTE_TEXT}), which is read once no matter how many
+ * calls the abort stopped and which sits after the user's words rather than
+ * before them.
+ *
  * Distinct from {@link CANCELLED_TOOL_RESULT_TEXT} because the model's next
  * decision is different. A plain cancel ends the work; a preemption means a
- * message is waiting, the abandoned call may well have taken effect on the
- * outside world before the abort landed, and the model has to answer the new
- * message before it decides what to do about the work it was doing.
+ * message is waiting, and the abandoned call may well have taken effect on the
+ * outside world before the abort landed.
  */
-export const PREEMPTED_TOOL_RESULT_TEXT = `A new message from the user arrived, so this tool call was stopped early. It may still have completed; check before repeating it. Treat the new message as the priority: ${INTERRUPT_PRIORITY_INSTRUCTION}`;
+export const PREEMPTED_TOOL_RESULT_TEXT =
+  "Stopped early because the user sent a new message. This call may have completed anyway; check before repeating it.";
 
 /**
  * Annotation appended to the LLM-facing content of the user message that
- * interrupted a turn, for the interrupt that landed with no tool call in
- * flight.
+ * interrupted a turn.
  *
- * A preemption caught mid-tool tells the model what happened through the
- * synthetic {@link PREEMPTED_TOOL_RESULT_TEXT} result. An abort that lands
- * during the provider call has no `tool_use` to answer, so the history the
- * next turn reads is the abandoned turn followed by this message, with nothing
- * saying the plan behind it was cut off. Without the note the model answers
- * the new message and drops the work it had just committed to.
+ * The one place the behavior after an interrupt is spelled out, and it rides
+ * on every interrupt, whether or not a tool call was stopped. Leading with the
+ * short reply is the point: the user is waiting to learn they were heard, and
+ * a turn that opens with more reasoning or another tool call leaves them
+ * staring at silence.
  *
  * Tagged rather than written as prose so it reads as a system annotation on
  * the message instead of something the user typed. It rides on the LLM-facing
  * content only: the persisted row stays exactly what the user sent, so no
  * client renders it.
  */
-export const INTERRUPTED_TURN_NOTE_TEXT = `<interrupted_turn>This message arrived while the previous turn was still thinking, before it had made any tool call, so that turn ended here. Treat this message as the priority: ${INTERRUPT_PRIORITY_INSTRUCTION}</interrupted_turn>`;
+export const INTERRUPTED_TURN_NOTE_TEXT =
+  "<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>";
 
 /**
  * The synthetic `tool_result` text that matches why the turn was aborted.