diff --git a/docs/harnesses/cursor/cursor-cli-experimental.md b/docs/harnesses/cursor/cursor-cli-experimental.md index 00af94cbc..634937b6d 100644 --- a/docs/harnesses/cursor/cursor-cli-experimental.md +++ b/docs/harnesses/cursor/cursor-cli-experimental.md @@ -83,7 +83,19 @@ references. This is an undocumented native format, not a supported Cursor API. The snapshot body comes from native ACP `session/load` and is reused only while the native history root is unchanged. It is accepted only when session, workspace, turn count, order and exact prompt text match native -history. A successful live turn must introduce exactly one native user-turn ID. +history. A successful live turn must introduce exactly one non-notification native +user-turn ID whose text matches the submitted prompt, while preserving the existing +history prefix. Both the terminal identity and an available checkpoint use that ID. +A checkpoint is offered only when Fork is supported and the prompt is the last +native record or the next record has a verified native rewind root, matching replay +projection and Fork validation. Missing rewind roots do not invalidate the Turn's +successful outcome or native identity. +In the observed Cursor CLI `2026.10.22-27dcf5f` store, background task completion +records carry field 15 (`simulated_message_metadata`). Records with this field are +treated as Cursor-generated notifications for live prompt identity verification; +they remain in the native history for replay and Fork boundaries. This field is not +a dedicated notification flag, and other native versions or simulated message types +are not established by this compatibility rule. Missing/ambiguous history is an error; generated UUIDs, array positions and text hashes are never used as native turn keys. The adapter keeps no shadow transcript. diff --git a/packages/adapters/cursor-cli/src/adapter.ts b/packages/adapters/cursor-cli/src/adapter.ts index 01deb6edb..294efa6d8 100644 --- a/packages/adapters/cursor-cli/src/adapter.ts +++ b/packages/adapters/cursor-cli/src/adapter.ts @@ -814,24 +814,34 @@ export class CursorSession implements HarnessSession { if (administrative && JSON.stringify(before) === JSON.stringify(after)) { // This native command returns a local message without persisting a user Turn. } else { + // Cursor appends its own user records when a background task finishes; those are not + // the echo of this prompt and must not make the prompt's identity ambiguous. + const prompted = added.filter((turn) => !turn.notification); + const own = prompted[0]; if ( - added.length !== 1 || - after.length !== before.length + 1 || + !own || + prompted.length !== 1 || + after.length !== before.length + added.length || before.some((turn, index) => after[index]?.id !== turn.id) || - added[0]?.text !== command.input.map((part) => part.text).join("\n") + own.text !== command.input.map((part) => part.text).join("\n") ) throw new Error("Cursor terminal has no unique, verified native turn identity"); nativeTurnRef = nativeTurnRefSchema.parse({ harnessId: "cursor-cli", nativeSessionId: this.transport.sessionId, - nativeTurnKey: added[0].id, + nativeTurnKey: own.id, formatVersion: 1, }); this.#fresh = false; - if (outcome.status === "succeeded" && cursorForkAvailable()) + const ownIndex = after.findIndex((turn) => turn.id === own.id); + if ( + outcome.status === "succeeded" && + cursorForkAvailable() && + (ownIndex === after.length - 1 || after[ownIndex + 1]?.rewindRoot) + ) outcome = { ...outcome, - checkpoint: cursorCheckpoint(this.transport.sessionId, added[0].id), + checkpoint: cursorCheckpoint(this.transport.sessionId, own.id), }; } } catch (error) { diff --git a/packages/adapters/cursor-cli/src/native-history.ts b/packages/adapters/cursor-cli/src/native-history.ts index 757a4555d..272ba278e 100644 --- a/packages/adapters/cursor-cli/src/native-history.ts +++ b/packages/adapters/cursor-cli/src/native-history.ts @@ -8,6 +8,9 @@ export interface CursorNativeTurn { text: string; /** Native conversation root immediately before this user turn, when available. */ rewindRoot?: string; + /** Cursor wrote this user record itself to report a finished background task (field 15), + * not as the echo of a prompt the Host submitted. */ + notification?: true; } export function cursorConfigDirectory(environment: NodeJS.ProcessEnv): string { @@ -140,6 +143,7 @@ export function readCursorNativeHistory( id, text: one(user, 1).toString("utf8"), ...(rewindRoot ? { rewindRoot } : {}), + ...(user.get(15)?.length ? { notification: true as const } : {}), }); } } diff --git a/packages/adapters/cursor-cli/test/cursor.test.ts b/packages/adapters/cursor-cli/test/cursor.test.ts index 333e72b11..7f84b2ce0 100644 --- a/packages/adapters/cursor-cli/test/cursor.test.ts +++ b/packages/adapters/cursor-cli/test/cursor.test.ts @@ -13,8 +13,11 @@ import { CursorTransport, type CursorCallbacks } from "../src/transport.js"; import { cursorModelRef, cursorCatalog, cursorNativeModel } from "../src/models.js"; import { CursorInteractions } from "../src/interactions.js"; import { cursorSnapshot } from "../src/projection.js"; +import * as forkSupport from "../src/fork-support.js"; -const native = vi.hoisted(() => ({ turns: [] as Array<{ id: string; text: string }> })); +const native = vi.hoisted(() => ({ + turns: [] as Array<{ id: string; text: string; notification?: true; rewindRoot?: string }>, +})); vi.mock("../src/native-history.js", () => ({ readCursorNativeTurns: () => structuredClone(native.turns), readCursorNativeHistory: () => ({ @@ -287,6 +290,82 @@ describe("Cursor turn lifecycle", () => { }), ); }); + it.each([true, false])( + "keeps prompt identity with notifications (rewind anchor=%s)", + async (hasRewindRoot) => { + vi.spyOn(forkSupport, "cursorForkAvailable").mockReturnValue(true); + const f = session(); + const notification = (id: string) => + native.turns.push({ + id: randomUUID(), + text: `\n\ntask_id: ${id}\n\n`, + notification: true, + ...(hasRewindRoot ? { rewindRoot: "a".repeat(64) } : {}), + }); + notification("before"); + f.transport.action = async (text, callbacks) => { + callbacks.update({ + sessionId: info.sessionId, + update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "ok" } }, + }); + native.turns.push({ id: randomUUID(), text }); + notification("one"); + notification("two"); + return { stopReason: "end_turn" }; + }; + await f.session.execute(start); + await vi.waitFor(() => + expect(f.output.some((x) => x.kind === "event" && x.event.type === "turn.completed")).toBe( + true, + ), + ); + await f.session.close(); + await f.done; + const terminal = f.output.filter( + (x) => x.kind === "event" && x.event.type === "turn.completed", + ); + expect(terminal[0]).toMatchObject({ + event: { + outcome: { status: "succeeded" }, + nativeTurnRef: { nativeTurnKey: native.turns[1]?.id }, + }, + }); + if (hasRewindRoot) { + expect(terminal[0]).toHaveProperty("event.outcome.checkpoint", { + harnessId: "cursor-cli", + nativeSessionId: info.sessionId, + checkpointId: native.turns[1]?.id, + locator: { kind: "cursor-turn" }, + formatVersion: 1, + }); + } else { + expect(terminal[0]).not.toHaveProperty("event.outcome.checkpoint"); + } + }, + ); + it("still fails when only background task notifications were added", async () => { + const f = session(); + f.transport.action = async () => { + native.turns.push({ id: randomUUID(), text: "", notification: true }); + return { stopReason: "end_turn" }; + }; + await f.session.execute(start); + await vi.waitFor(() => + expect(f.output.some((x) => x.kind === "event" && x.event.type === "turn.completed")).toBe( + true, + ), + ); + await f.session.close(); + await f.done; + expect(f.output).toContainEqual( + expect.objectContaining({ + event: expect.objectContaining({ + type: "turn.completed", + outcome: expect.objectContaining({ status: "failed" }), + }), + }), + ); + }); it("rejects a concurrent turn and closes pending approval on cancel", async () => { const f = session(); f.transport.action = async (text, callbacks) => { diff --git a/packages/adapters/cursor-cli/test/native-history.test.ts b/packages/adapters/cursor-cli/test/native-history.test.ts index a5aa2a4e2..54cd1733a 100644 --- a/packages/adapters/cursor-cli/test/native-history.test.ts +++ b/packages/adapters/cursor-cli/test/native-history.test.ts @@ -22,7 +22,7 @@ function field(id: number, value: Buffer | string) { const data = Buffer.isBuffer(value) ? value : Buffer.from(value); return Buffer.concat([varint(id * 8 + 2), varint(data.length), data]); } -function fixture(texts = ["first", "second"]) { +function fixture(texts = ["first", "second"], notifications: number[] = []) { const home = mkdtempSync(path.join(os.tmpdir(), "codexhost-cursor-history-")); temporary.push(home); const sessionId = randomUUID(); @@ -38,13 +38,31 @@ function fixture(texts = ["first", "second"]) { db.prepare("INSERT OR IGNORE INTO blobs VALUES(?,?)").run(id.toString("hex"), data); return id; }; - const turns = texts.map((text) => ({ id: randomUUID(), text })); + const turns = texts.map((text, index) => ({ + id: randomUUID(), + text, + ...(notifications.includes(index) ? { notification: true as const } : {}), + })); const root = put( Buffer.concat( turns.map((turn) => field( 8, - put(field(1, field(1, put(Buffer.concat([field(1, turn.text), field(2, turn.id)]))))), + put( + field( + 1, + field( + 1, + put( + Buffer.concat([ + field(1, turn.text), + field(2, turn.id), + ...(turn.notification ? [field(15, field(1, "background task"))] : []), + ]), + ), + ), + ), + ), ), ), ), @@ -81,6 +99,13 @@ describe("Cursor read-only native identity", () => { ); expect(readCursorNativeTurns(f.sessionId, requested, { HOME: f.home })).toEqual(f.turns); }); + it("marks user records Cursor wrote for finished background tasks", () => { + const f = fixture(["prompt", "task finished"], [1]); + const turns = readCursorNativeTurns(f.sessionId, f.home, { HOME: f.home }); + expect(turns).toEqual(f.turns); + expect(turns[0]).not.toHaveProperty("notification"); + expect(turns[1]).toMatchObject({ notification: true }); + }); it("allows a new empty history without inventing IDs", () => { const f = fixture([]); expect(readCursorNativeTurns(f.sessionId, f.home, { HOME: f.home })).toEqual([]);