fix(session): force cold replay instead of degrading multi-turn resume

Address PR #57 review findings:

- language-model: on a count/tail mismatch (classifier invariant broken),
  never degrade to sending only the latest message — that silently drops
  messages 1..N-1 while the record keeps the full fingerprint. Clear the
  resume id pre-acquire so a fresh agent gets the full transcript instead.
- agent-events: sendAgentTurnSilently now treats any terminal status other
  than "finished" as non-delivery and throws, except cancellation caused
  by our own abort signal (caller drops the record on abort).
- document silent-turn trade-offs: tool invisibility, serial latency, and
  why concatenating queued messages was rejected (message fidelity).

Author: justin-carper

src/provider/agent-events.ts

@@ -202,9 +202,22 @@ async function sendWithBusyRetry(
  * Honors `options.abortSignal`: an abort cancels the in-flight run so the
  * caller can stop before sending the next queued message.
  *
- * Known trade-off: token usage from silent turns is not reported (no onDelta
- * means the `turn-ended` usage update is never observed), so opencode slightly
- * undercounts usage on multi-message turns.
+ * Known trade-offs of silent turns being FULL agent runs:
+ *  - Tool invisibility: the agent may execute tools (shell, edits, MCP) during
+ *    a silent turn with zero streamed output or tool display — the user sees
+ *    nothing until the final message streams. Accepted because interjections
+ *    are typically short course-corrections, and opencode itself folds
+ *    interjected messages into one visible turn.
+ *  - Serial latency: each silent turn is awaited to completion before the next
+ *    send, so an N-message interjection costs N sequential agent runs.
+ *  - Usage undercount: no onDelta means the `turn-ended` usage update is never
+ *    observed, so opencode slightly undercounts tokens on multi-message turns.
+ *
+ * Concatenating the queued messages into one Cursor message was rejected for
+ * message fidelity: each interjection must land as a distinct user turn in the
+ * agent's conversation memory (mirroring opencode's transcript), so the model
+ * sees the same message boundaries the user created and later fingerprint
+ * classification stays aligned turn-for-turn.
  */
 export async function sendAgentTurnSilently(
   agent: AgentLike,
@@ -226,9 +239,16 @@ export async function sendAgentTurnSilently(
     // was populated, so onAbort had nothing to cancel); cancel now.
     if (options.abortSignal?.aborted) void Promise.resolve(run.cancel()).catch(() => {});
     const result = await run.wait();
-    if (result.status === "error") {
+    if (result.status !== "finished") {
+      // Our own abort cancelled the run mid-flight: expected, not a failure.
+      // The caller's abort check stops the multi-send sequence and drops the
+      // session record, so this partial turn is never counted as delivered.
+      if (options.abortSignal?.aborted) return;
+      // Anything else ("error", an external "cancelled", unknown states) means
+      // the message was NOT delivered; treating it as success would leave the
+      // session record claiming the agent saw a message it never received.
       throw new Error(
-        `Cursor run ended with status "error"${result.result ? `: ${result.result}` : ""}`,
+        `Cursor run ended with status "${result.status}"${result.result ? `: ${result.result}` : ""}`,
       );
     }
   } finally {

src/provider/language-model.ts

@@ -12,6 +12,7 @@ import type {
 	McpServerConfig,
 	SettingSource,
 	AgentModeOption,
+	SDKUserMessage,
 } from "@cursor/sdk";
 import { resolveCursorApiKey } from "../api-key.js";
 import {
@@ -207,6 +208,28 @@ export class CursorLanguageModel implements LanguageModelV3 {
 			}
 		}
 
+		// A multi-message interjection: two-or-more user messages were queued while
+		// the agent was busy, forming a contiguous user-turn tail (the classifier
+		// guarantees this shape for "continuation-multi"). On a resumed agent we
+		// replay just those new messages as sequential turns.
+		//
+		// Defensive invariant check: if the recovered tail doesn't match the
+		// classifier's count (unreachable today, but one classifier refactor away
+		// from real), we must NOT degrade to sending only the latest message —
+		// the session record keeps the full N-message fingerprint, so messages
+		// 1..N-1 would be silently lost. Instead force the cold path: clear the
+		// resume id so a FRESH agent gets the FULL transcript, which matches the
+		// record being written and loses nothing.
+		let multiTurns: SDKUserMessage[] | undefined;
+		if (multiNewUserCount >= 2) {
+			const turns = trailingUserMessages(options.prompt, multiNewUserCount);
+			if (turns.length === multiNewUserCount) {
+				multiTurns = turns;
+			} else {
+				resumeAgentId = undefined;
+			}
+		}
+
 		const acquired = await acquireAgent({
 			apiKey: this.requireApiKey(),
 			modelSelection,
@@ -226,21 +249,13 @@ export class CursorLanguageModel implements LanguageModelV3 {
 			...(record ? { record } : {}),
 		});
 
-		// A multi-message interjection: two-or-more user messages were queued while
-		// the agent was busy, forming a contiguous user-turn tail (the classifier
-		// guarantees this shape for "continuation-multi"). On a resumed agent,
-		// replay just those new messages as sequential turns — send the leading
-		// ones silently and stream only the final one. If the tail can't be
-		// recovered (defensive; shouldn't happen post-classifier), skip the multi
-		// path: on a resumed agent that means sending only the latest message, so
-		// the empty/short check below treats it as a normal single continuation.
-		const multiTurns =
-			acquired.resumed && multiNewUserCount >= 2
-				? trailingUserMessages(options.prompt, multiNewUserCount)
-				: undefined;
-
 		try {
-			if (multiTurns && multiTurns.length === multiNewUserCount) {
+			// Replay the queued messages as sequential turns: leading ones silent,
+			// only the final one streamed. Note silent turns are FULL agent runs —
+			// tools may execute with nothing surfaced until the last turn streams,
+			// and each run is awaited serially (see sendAgentTurnSilently for the
+			// trade-offs and why concatenation was rejected).
+			if (acquired.resumed && multiTurns) {
 				// The pool record was written optimistically with the FULL new
 				// fingerprint before any send. If delivery stops partway (error or
 				// abort), drop the record so the next turn classifies fresh instead

test/agent-events.test.ts

@@ -140,6 +140,39 @@ describe("sendAgentTurnSilently", () => {
 		).rejects.toThrow(/error/i);
 	});
 
+	it("throws when the run ends 'cancelled' without our abort (message never delivered)", async () => {
+		// Cancellation we did NOT request (external cancel, CLI kill, …) means the
+		// silent turn was not delivered; treating it as success would let the
+		// caller keep a session record for a message the agent never received.
+		const agent = fakeAgent({ result: { status: "cancelled" } });
+		await expect(
+			sendAgentTurnSilently(agent, MESSAGE, { mode: "agent" }),
+		).rejects.toThrow(/cancelled/);
+	});
+
+	it("throws when the run ends with an unknown terminal status", async () => {
+		const agent = fakeAgent({ result: { status: "expired" } });
+		await expect(
+			sendAgentTurnSilently(agent, MESSAGE, { mode: "agent" }),
+		).rejects.toThrow(/expired/);
+	});
+
+	it("does not throw on 'cancelled' when our own abort signal caused it", async () => {
+		const controller = new AbortController();
+		controller.abort();
+		// Already-aborted signal: returns early without sending at all.
+		const sendCalls: Array<Record<string, unknown> | undefined> = [];
+		const agent = fakeAgent({
+			result: { status: "cancelled" },
+			sendCalls,
+		});
+		await sendAgentTurnSilently(agent, MESSAGE, {
+			mode: "agent",
+			abortSignal: controller.signal,
+		});
+		expect(sendCalls).toHaveLength(0);
+	});
+
 	it("retries with local.force on AgentBusyError", async () => {
 		const busy = new Error("agent busy");
 		busy.name = "AgentBusyError";

test/language-model-multiturn-fallback.test.ts

@@ -0,0 +1,140 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type {
+	LanguageModelV3CallOptions,
+	LanguageModelV3Prompt,
+} from "@ai-sdk/provider";
+
+// Sandbox the on-disk session store away from the user's real cache dir.
+process.env.XDG_CACHE_HOME = mkdtempSync(join(tmpdir(), "cursor-lm-fb-test-"));
+
+interface SentTurn {
+	text: string;
+	streamed: boolean;
+}
+
+const sentTurns: SentTurn[] = [];
+const create = vi.fn();
+const resume = vi.fn();
+
+vi.mock("../src/cursor-runtime.js", () => ({
+	loadCursorSdk: async () => ({ Agent: { create, resume } }),
+}));
+
+// The classifier guarantees `continuation-multi` prompts end in a contiguous
+// user tail of exactly `newUserCount` messages, so the count/tail mismatch the
+// model guards against is unreachable through the public API. Construct it
+// artificially: make trailingUserMessages return one message fewer than asked,
+// as a stand-in for a future refactor breaking the classifier invariant.
+vi.mock("../src/provider/message-map.js", async (importOriginal) => {
+	const actual =
+		await importOriginal<typeof import("../src/provider/message-map.js")>();
+	return {
+		...actual,
+		trailingUserMessages: (prompt: LanguageModelV3Prompt, count: number) =>
+			actual.trailingUserMessages(prompt, count).slice(1),
+	};
+});
+
+const { CursorLanguageModel } = await import(
+	"../src/provider/language-model.js"
+);
+const { clearAgentPool, getSessionRecord } = await import(
+	"../src/provider/session-pool.js"
+);
+
+const SESSION_ID = "sess-fallback";
+
+function makeFakeAgent(agentId: string) {
+	return {
+		agentId,
+		close: vi.fn(),
+		send: async (
+			message: { text: string },
+			sendOptions?: Record<string, unknown>,
+		) => {
+			sentTurns.push({
+				text: message.text,
+				streamed: Boolean(sendOptions?.["onDelta"]),
+			});
+			return {
+				id: "run",
+				wait: async () => ({ status: "finished", result: message.text }),
+				cancel: async () => {},
+			};
+		},
+	};
+}
+
+function model() {
+	return new CursorLanguageModel("cursor/auto", {
+		providerName: "cursor",
+		apiKey: "k",
+		cwd: "/tmp",
+		mode: "agent",
+	});
+}
+
+async function drain(prompt: LanguageModelV3Prompt): Promise<void> {
+	const options = {
+		prompt,
+		providerOptions: { cursor: { sessionID: SESSION_ID } },
+	} as unknown as LanguageModelV3CallOptions;
+	const { stream } = await model().doStream(options);
+	const reader = stream.getReader();
+	// eslint-disable-next-line no-constant-condition
+	while (true) {
+		const { done } = await reader.read();
+		if (done) break;
+	}
+}
+
+const sys = { role: "system" as const, content: "S" };
+const user = (text: string): LanguageModelV3Prompt[number] => ({
+	role: "user",
+	content: [{ type: "text", text }],
+});
+const assistant = (text: string): LanguageModelV3Prompt[number] => ({
+	role: "assistant",
+	content: [{ type: "text", text }],
+});
+
+afterEach(() => {
+	create.mockReset();
+	resume.mockReset();
+	sentTurns.length = 0;
+	clearAgentPool();
+});
+
+describe("multi-turn tail mismatch (defensive fallback)", () => {
+	it("forces a cold full-transcript replay instead of degrading to the latest message", async () => {
+		// Turn 1: pool the agent with a single-user fingerprint.
+		create.mockResolvedValue(makeFakeAgent("a1"));
+		await drain([sys, user("a")]);
+		expect(getSessionRecord(SESSION_ID)).toBeDefined();
+
+		// Turn 2: continuation-multi (2 new user msgs), but the mocked
+		// trailingUserMessages recovers only 1 of them — the mismatch case.
+		// The model must NOT resume-and-send-only-"c" (which silently drops "b");
+		// it must fall back to a fresh agent + full transcript so nothing is lost.
+		create.mockClear();
+		create.mockResolvedValue(makeFakeAgent("a2"));
+		resume.mockResolvedValue(makeFakeAgent("a1"));
+		sentTurns.length = 0;
+		await drain([sys, user("a"), assistant("x"), user("b"), user("c")]);
+
+		expect(resume).not.toHaveBeenCalled();
+		expect(create).toHaveBeenCalledOnce();
+		expect(sentTurns).toHaveLength(1);
+		expect(sentTurns[0]?.streamed).toBe(true);
+		// Full transcript: every queued message is present, none dropped.
+		expect(sentTurns[0]?.text).toContain("b");
+		expect(sentTurns[0]?.text).toContain("c");
+
+		// The record now reflects the fully delivered transcript: the NEXT turn
+		// is a clean continuation on the fresh agent.
+		expect(getSessionRecord(SESSION_ID)).toMatchObject({ agentId: "a2" });
+	});
+});