From 4af314a0552ad86ead07b46bf1418c6f5810b79a Mon Sep 17 00:00:00 2001 From: Dotta Date: Tue, 29 Sep 2026 16:23:19 -0500 Subject: [PATCH] Admit and bind Cursor native session modes in profile v5 Co-Authored-By: Paperclip --- .../runner-cursor-capabilities.md | 46 ++++- .../scripts/qualify-cursor-mode.mjs | 63 ++++++ .../acpx/codex-runtime-adapter.test.ts | 30 ++- .../src/drivers/acpx/codex-runtime-adapter.ts | 21 +- .../src/drivers/acpx/cursor-mode.test.ts | 180 ++++++++++++++++++ .../src/drivers/acpx/cursor-mode.ts | 97 ++++++++++ .../drivers/acpx/qualified-profiles.test.ts | 7 +- .../src/drivers/acpx/qualified-profiles.ts | 4 +- .../drivers/acpx/recovery-identity.test.ts | 16 ++ .../src/drivers/acpx/recovery-identity.ts | 16 +- .../src/drivers/acpx/runtime-host.test.ts | 32 +++- .../src/drivers/acpx/runtime-host.ts | 9 + .../cursor-acp/mode-v5-offline-proof.json | 32 ++++ .../cursor-acp/profile-v5-identity.json | 53 ++++++ 14 files changed, 592 insertions(+), 14 deletions(-) create mode 100644 packages/paperclip-runner/scripts/qualify-cursor-mode.mjs create mode 100644 packages/paperclip-runner/src/drivers/acpx/cursor-mode.test.ts create mode 100644 packages/paperclip-runner/src/drivers/acpx/cursor-mode.ts create mode 100644 packages/paperclip-runner/test/fixtures/cursor-acp/mode-v5-offline-proof.json create mode 100644 packages/paperclip-runner/test/fixtures/cursor-acp/profile-v5-identity.json diff --git a/doc/architecture/runner-cursor-capabilities.md b/doc/architecture/runner-cursor-capabilities.md index becdfd34a71..5749096a464 100644 --- a/doc/architecture/runner-cursor-capabilities.md +++ b/doc/architecture/runner-cursor-capabilities.md @@ -2,7 +2,7 @@ Evidence updated: 2026-09-29. Candidate: `2026.09.26-dd393fe`. This profile is **not live-qualified**. One authorized task-context prompt on the initial free account returned an upgrade requirement, invoked no semantic tools, and supplied no usage receipt. Its cost is unknown; the account dashboard remained unchanged at coarse precision. The user then selected another account, whose exact-model local Runner Eval passed task-context and history tools with clean terminal settlement. Its dashboard attributed 56K rounded tokens to included usage and no incremental charge; ACP still supplied no token or dollar receipt. The local Product hello subsequently passed through the real browser, server, database, native runner, and authenticated completion tool. A second local Product case passed file creation, editing, command validation, an independent exact-byte matcher, and visible workspace artifact presentation. The merged-source local Product question and revision-bound Plan approval also passed browser response and semantic-tool continuation. A serialized follow-up passed pending semantic-question recovery across a server restart. A verified native ACP probe also denied a shell write before any observed side effect. Native Cursor questions/plans and their recovery, durable permission presentation, interruption, and Daytona execution remain required qualification gates. -Current source uses **profile v4**, with the instruction admission correction described below. Prior paid results and packaged v3 builds remain historical and cannot qualify the current source. +Current source uses **profile v5**, with native session-mode admission and the instruction correction described below. All prior paid results (including v4) and packaged builds remain historical and cannot qualify v5. The earlier mode-selection limitation below describes the pre-v5 implementation. The reference is the runner's Codex app-server integration and its closed thread-item inventory in `src/provider-events.ts`. Cursor ACP and its private extension methods are the transport; the legacy Cursor adapter is unchanged. @@ -38,7 +38,7 @@ The reference is the runner's Codex app-server integration and its closed thread | Session continuity | `session/new`, `session/load`; load replays historical messages, reasoning, tools, images and children | Existing session load/recovery boundary with identity fencing | Duplicate replay suppression and provider-death recovery need authenticated proof | | Session discovery | `session/list` implemented, cwd filter absolute; pagination cursor rejected | Discovered and reported | Currently unused: runner recovers only its exact recorded session; arbitrary history browsing needs company-scoped discovery API | | Fork/resume methods | `session/fork` and `session/resume` absent in agent implementation and return method-not-found | Unsupported | Session load is available; do not infer fork from SDK schema | -| Modes | `agent`, `plan`, `ask`; `session/set_mode` and `current_mode_update` | Existing review/mode activity plumbing can display changes | Generic operator mode-selection surface not implemented in this provider slice | +| Modes | `agent`, `plan`, `ask`; `session/set_config_option` returns exact mode; native mode updates are observable | v5 admits an explicit selected mode, binds recovery identity, and gates every prompt against native acknowledgement | Default Agent; mode is independent of permission policy. Plan acceptance does not switch to Agent. Native callback availability and Plan-mode completion remain unqualified | | Model selection | `session/set_model`, config option `model`, model-parameter options, `config_option_update`; `cursor/list_available_models` extension | Exact requested model must be selected/verified by shared admission | Authenticated listing and exact Luna variant echo passed. Native parameterized picker metadata and separate parameter changes also passed; this richer configuration path is not exposed by the runner. See the authenticated discovery evidence below | | Available commands | `available_commands_update`, including skills/slash commands | ACPX persists command metadata; runner canonical mapper deliberately emits no display event | Command picker and bounded command-discovery surface are not implemented | | Session metadata | `session_info_update` title after automatic naming | Capability documented | Runner owns normalized session identity; provider title is currently not surfaced | @@ -312,3 +312,45 @@ ACPX contracts, seven materializer cases, and the runner TypeScript compile pass No paid calls or billing mutations were made. A new final-source provider pack and daemon, authenticated instruction semantics, and the remaining live gates are still required before qualification. + +## Cursor profile v5: admitted native session modes (2026-09-29) + +The explicit `acpxSessionMode` configuration selects `agent` (the default), +`plan`, or `ask` for Cursor. The provider/sidecar field is `cursorMode`; it is +separate from ACPX's persistent/oneshot session lifecycle. Other providers reject +this field. Mode is included in the immutable session key and recovery identity; +a missing or changed mode cannot reopen an existing v5 session. + +Admission checks the pinned native `session/new` or `session/load` response's +mode configuration and mode state. If necessary, it sets the selected mode using +`session/set_config_option` and requires its exact echoed configuration before +admitting a prompt. A bare `session/set_mode` response or asynchronous +`current_mode_update` alone is not acknowledgement. Every new native connection +gets a fresh guard: a mismatched automatic reload blocks prompt delivery, and an +unsolicited active mode change fails closed. Explicit startup/reopen admission +can reassert the selected mode within the existing admission deadline and renews +the consumed launch lease after each temporary control connection. + +The pinned CLI maps Agent to native `default`, Plan to `plan`, and Ask to +`search`, and carries that metadata into the native UserMessage mode. The +inspectable `mode-v5-offline-proof.json` executes the pinned native methods with +storage, transport, and enum-converter doubles. Real ACPX fixture tests separately +prove cold-manager load/control ordering and automatic reconnect rejection before +prompt bytes. Neither is paid model/tool qualification. + +Native mode does not change Paperclip permission policy, company governance, or +filesystem isolation. The native descriptions say Plan is read-only planning and +Ask has no edits or command execution; these descriptions are not an OS sandbox +claim. Native ACP CreatePlan acceptance does not itself mutate session mode in +the pinned handler. An approved plan therefore stays in the selected Plan mode; +there is no implicit promotion to Agent mode. Actual native question/plan callback +availability, Plan-mode governed completion, and accepted/revised artifact flows +remain pending Product qualification. Existing v4 paid results and macOS x64 +Rosetta build evidence remain historical and do not qualify v5. + +[The v5 declaration](../../packages/paperclip-runner/test/fixtures/cursor-acp/profile-v5-identity.json) +binds digest `sha256:aa8c0b2b84786982bcd06b7634bf95be6f2bc42bb8def48a8751dc50cf739b6b`. +Profile v5 retains the native distribution closures and instruction patch. Its +canonical declaration adds the admitted mode policy and binds ACPX patch +`79aad2d688b03362e8cfcbf7a08f78a8383869f6882a9c9ed66f1d18efb94f2b`, which preserves +identified empty rich-input chunks at the native parser boundary. diff --git a/packages/paperclip-runner/scripts/qualify-cursor-mode.mjs b/packages/paperclip-runner/scripts/qualify-cursor-mode.mjs new file mode 100644 index 00000000000..2ba1a05da11 --- /dev/null +++ b/packages/paperclip-runner/scripts/qualify-cursor-mode.mjs @@ -0,0 +1,63 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { readFile, writeFile } from "node:fs/promises"; +import { pathToFileURL } from "node:url"; +import { runInNewContext } from "node:vm"; + +const PINNED_ARM_CHUNK = "c01657c111f65153d7a40a923f01a5a86d393d1cd6893eaa03f71b9604d2af0c"; +const hash = source => createHash("sha256").update(source).digest("hex"); +function segment(source, start, end) { + const first = source.indexOf(start); assert.ok(first >= 0, `Missing native method ${start}`); + const last = source.indexOf(end, first + start.length); assert.ok(last > first, `Missing method boundary ${end}`); + return source.slice(first, last); +} +const awaiter = (self, args, _promise, fn) => { + const iterator = fn.apply(self, args ?? []); + const next = value => { const result = iterator.next(value); return result.done ? Promise.resolve(result.value) : Promise.resolve(result.value).then(next); }; + return next(); +}; + +/** Executes the pinned native mode methods with dependency doubles. No network, + * model call, or claim that a selected mode exposes a particular tool. */ +export async function qualifyCursorMode(source) { + assert.equal(hash(source), PINNED_ARM_CHUNK, "Native source identity changed"); + const toAcp = mode => ({ default: "agent", plan: "plan", search: "ask" })[mode]; + const scope = { S: awaiter, T: { ACP_MODE_CONFIG_ID: "mode" }, p: { mb: toAcp }, _: { mb: toAcp }, i: { GI: { invalidParams: value => new Error(value.message) } }, w: { debugLog() {} } }; + const method = (start, end, name) => runInNewContext(`({${segment(source, start, end)}}).${name}`, scope); + const setConfig = method("setSessionConfigOption(e)", "unstable_setSessionModel(e)", "setSessionConfigOption"); + const mapMode = method("mapAcpModeToCliMode(e)", "clientSupportsParameterizedModelPicker()", "mapAcpModeToCliMode"); + const modes = method("buildModesStateFromCliMode(e)", "buildModesState(e)", "buildModesStateFromCliMode"); + const configs = method("buildConfigOptions(e,t)", "buildModelsState(e)", "buildConfigOptions"); + const setMode = method("setMode(e){", "getCliMode(){", "setMode"); + const getCliMode = method("getCliMode(){", "sendCurrentModeUpdate(e)", "getCliMode"); + const rows = []; + for (const selected of ["agent", "plan", "ask"]) { + const metadata = new Map([["mode", "default"]]); const updates = []; + const store = { getMetadata: key => metadata.get(key), setMetadata: (key, value) => metadata.set(key, value) }; + const makeSession = () => ({ agentStore: store, setMode, getCliMode, sendCurrentModeUpdate: async value => updates.push(value) }); + const session = makeSession(); + const host = { sessions: new Map([["native", { session }]]), sharedServices: {}, mapAcpModeToCliMode: mapMode, buildModesStateFromCliMode: modes, buildConfigOptions: configs, getModelPickerMode: () => "variants", getAcpAvailableModels: async () => [], buildVariantModelConfigOptions: async () => [] }; + const response = await setConfig.call(host, { sessionId: "native", configId: "mode", value: selected }); + assert.equal(response.configOptions[0].currentValue, selected); + assert.equal(updates.at(-1), selected); + // A reconstructed native session reads the same admitted metadata. Actual + // database durability is deliberately outside this dependency-double proof. + const loaded = makeSession(); + assert.equal((await configs.call(host, "native", loaded))[0].currentValue, selected); + class Data { constructor(value) { Object.assign(this, value); } } + const promptPart = segment(source, 'r=null!==(o=this.agentStore.getMetadata("mode"))', ',u=new a.h'); + const action = runInNewContext(`(function(){let o;const ${promptPart};return d;})`, { _: { cT: value => ({ nativeModeInput: value }) }, c: { UserMessageAction: Data, UserMessage: Data }, N: "offline fixture", n: {}, crypto: { randomUUID: () => "fixture" } }).call(loaded); + assert.equal(action.userMessage.mode.nativeModeInput, metadata.get("mode")); + rows.push({ selected, nativeMetadata: metadata.get("mode"), configAcknowledgement: selected, currentModeNotification: selected, reconstructedSessionAcknowledgement: selected, userMessageModeInput: action.userMessage.mode.nativeModeInput }); + } + const planHandler = segment(source, '"./src/acp/interaction-handlers/create-plan-handler.ts"(e,t,n)', '},"./src/acp/resource-link-security.ts"'); + assert.doesNotMatch(planHandler, /setMode\(|setMetadata\("mode"/); + return { schema: "paperclip.cursor.native-mode-offline-proof.v1", sourceSha256: hash(source), rows, planHandlerHasModeMutation: false, boundary: "pinned native config/session/UserMessage methods; storage, mode enum converter and transport doubled; no inference" }; +} + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + const [sourcePath, outputPath] = process.argv.slice(2); + if (!sourcePath || !outputPath) throw new Error("Usage: node qualify-cursor-mode.mjs PINNED_ARM_CHUNK OUTPUT_JSON"); + const proof = await qualifyCursorMode(await readFile(sourcePath, "utf8")); + await writeFile(outputPath, `${JSON.stringify(proof, null, 2)}\n`); +} diff --git a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts index 45688ee645e..cd28b25e574 100644 --- a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts +++ b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts @@ -90,7 +90,7 @@ describe("Codex ACPX runtime adapter", () => { const guard = created.protocolGuardFactory!(); const binding = cursorInstructionBinding(options.systemInstructions); guard("outbound", { id: 0, method: "session/load", params: { sessionId: "backend-1" } }); - guard("inbound", { id: 0, result: mode === "missing" ? {} : { _meta: { paperclipCursorInstructions: { + guard("inbound", { id: 0, result: mode === "missing" ? {} : { modes: { currentModeId: "agent" }, configOptions: [{ id: "mode", currentValue: "agent" }], _meta: { paperclipCursorInstructions: { schema: "paperclip.cursor.instructions.v1", digest: binding.digest, byteLength: binding.byteLength, } } } }); if (mode === "unsupported") throw new Error("Exact model unsupported"); @@ -107,6 +107,32 @@ describe("Codex ACPX runtime adapter", () => { expect(runtime.setConfigOption).toHaveBeenCalledExactlyOnceWith({ handle: HANDLE, key: "model", value: options.profile.reportedModelId }); expect(runtime.startTurn).not.toHaveBeenCalled(); }); + it.each(["plan", "ask"] as const)("admission explicitly selects %s and renews temporary command authority", async selected => { + const runtime = fakeRuntime(); const options = openOptions(fakeCommand()); + options.profile = { ...options.profile, agent: "cursor" }; options.cursorMode = selected; + options.refreshConsumedCommand = vi.fn(async () => undefined); + let created!: AcpRuntimeOptions; + const binding = cursorInstructionBinding(options.systemInstructions); + const configs = (mode: string) => [{ id: "mode", currentValue: mode }]; + vi.mocked(runtime.setConfigOption).mockImplementation(async input => { + const guard = created.protocolGuardFactory!(); + guard("outbound", { id: 0, method: "session/load", params: { sessionId: "backend-1" } }); + guard("inbound", { id: 0, result: { modes: { currentModeId: "agent" }, configOptions: configs("agent"), _meta: { paperclipCursorInstructions: { + schema: "paperclip.cursor.instructions.v1", digest: binding.digest, byteLength: binding.byteLength, + } } } }); + guard("outbound", { id: 1, method: "session/set_config_option", params: { sessionId: "backend-1", configId: input.key, value: input.value } }); + guard("inbound", { id: 1, result: { configOptions: configs(input.key === "mode" ? selected : "agent") } }); + }); + const port = await openCodexAcpxRuntime(options, { + createRegistry: () => registry(), createStore: () => store(), createRuntime: value => { created = value; return runtime; }, + }); + expect(vi.mocked(runtime.setConfigOption).mock.calls.map(([call]) => [call.key, call.value])).toEqual([["model", options.profile.reportedModelId], ["mode", selected]]); + expect(options.refreshConsumedCommand).toHaveBeenCalledTimes(2); + expect(await port.identity()).toMatchObject({ cursorMode: selected }); + expect(runtime.startTurn).not.toHaveBeenCalled(); + await port.close({ reason: "mode fixture cleanup" }); + }); + it("routes only profile-allowed extensions to the owning turn and expires late responses", async () => { const runtime = fakeRuntime(); const first = pendingExtensionTurn("turn-1"); @@ -123,7 +149,7 @@ describe("Codex ACPX runtime adapter", () => { const guard = value.protocolGuardFactory!(); const binding = cursorInstructionBinding(options.systemInstructions); guard("outbound", { id: 0, method: "session/new", params: {} }); - guard("inbound", { id: 0, result: { sessionId: "backend-1", _meta: { paperclipCursorInstructions: { schema: "paperclip.cursor.instructions.v1", digest: binding.digest, byteLength: binding.byteLength } } } }); + guard("inbound", { id: 0, result: { sessionId: "backend-1", modes: { currentModeId: "agent" }, configOptions: [{ id: "mode", currentValue: "agent" }], _meta: { paperclipCursorInstructions: { schema: "paperclip.cursor.instructions.v1", digest: binding.digest, byteLength: binding.byteLength } } } }); return runtime; }, }); diff --git a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts index 7d8a2cefb0f..00b6209e29a 100644 --- a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts +++ b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts @@ -32,6 +32,7 @@ import { AcpxApprovalRequiredError, decideAcpxPermission } from "./permission-po import { ACPX_CAPABILITY_PROFILES } from "./capability-profiles.js"; import { assertCopilotPromptPolicy, createCopilotProtocolGuard } from "./copilot-policy.js"; import { admitCursorInstructions, createCursorInstructionAdmission } from "./cursor-instructions.js"; +import { createCursorModeAdmission, resolveCursorSessionMode } from "./cursor-mode.js"; const VERIFIED_COMMAND_SENTINEL = "paperclip-verified-acpx-command"; const DEFAULT_RUNTIME_CLOSE_TIMEOUT_MS = 2_000; @@ -299,12 +300,18 @@ export async function openQualifiedAcpxRuntime( ); }; const commandLaunches = { count: 0, refreshConsumedCommand: options.refreshConsumedCommand }; + const selectedCursorMode = resolveCursorSessionMode(options.profile.agent, options.cursorMode); + const cursorMode = selectedCursorMode ? createCursorModeAdmission(selectedCursorMode) : null; const cursorInstructions = options.profile.agent === "cursor" ? createCursorInstructionAdmission(options.systemInstructions) : null; const runtimeOptions: GoalAwareAcpRuntimeOptions = { cwd: options.cwd, - ...(cursorInstructions ? { protocolGuardFactory: () => cursorInstructions.createGuard() } : {}), + ...(cursorInstructions && cursorMode ? { protocolGuardFactory: () => { + const instructions = cursorInstructions.createGuard(); + const mode = cursorMode.createGuard(); + return (direction: "inbound" | "outbound", message: unknown) => { instructions(direction, message); mode(direction, message); }; + } } : {}), sessionStore, agentRegistry: createRegistry({ // Preserve Claude's ACP capability identity. This is metadata only: the @@ -491,6 +498,15 @@ export async function openQualifiedAcpxRuntime( await commandLaunches.refreshConsumedCommand?.(); }, }); + if (cursorMode && !cursorMode.isReady()) { + if (!runtime.setConfigOption) throw new Error("Cursor mode admission requires native mode configuration"); + await runtime.setConfigOption({ handle: ensuredHandle, key: "mode", value: selectedCursorMode! }); + cursorInstructions.assertReady(); + cursorMode.assertReady(); + await children.verifyLifetimeOwnership(); + options.signal?.throwIfAborted(); + await commandLaunches.refreshConsumedCommand?.(); + } return ensuredHandle; }) : ensuredSession) .catch((error: unknown) => { @@ -506,6 +522,7 @@ export async function openQualifiedAcpxRuntime( ? await raceRuntimeHandshakeWithAbort(boundedHandshake, options.signal) : await boundedHandshake; cursorInstructions?.assertReady(); + cursorMode?.assertReady(); // A provider can answer only after the verified sentinel is armed, but do // not admit the session until the owner has observed that exact handoff. await children.verifyLifetimeOwnership(); @@ -560,7 +577,7 @@ export async function openQualifiedAcpxRuntime( return runtimePort( runtime, handle, - requireIdentity(handle), + { ...requireIdentity(handle), ...(selectedCursorMode ? { cursorMode: selectedCursorMode } : {}) }, baseStore, children, runtimeCloseTimeoutMs, diff --git a/packages/paperclip-runner/src/drivers/acpx/cursor-mode.test.ts b/packages/paperclip-runner/src/drivers/acpx/cursor-mode.test.ts new file mode 100644 index 00000000000..d941429f449 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/cursor-mode.test.ts @@ -0,0 +1,180 @@ +import { describe, expect, it } from "vitest"; +import { createCursorModeAdmission, resolveCursorSessionMode } from "./cursor-mode.js"; + +const config = (mode: string) => [{ id: "mode", type: "select", currentValue: mode, options: ["agent", "plan", "ask"].map(value => ({ value, name: value })) }]; +const session = (mode: string) => ({ sessionId: "native", modes: { currentModeId: mode }, configOptions: config(mode) }); +const prompt = { id: 9, method: "session/prompt", params: { sessionId: "native" } }; +function opened(expected: "agent" | "plan" | "ask", initial = expected) { + const admission = createCursorModeAdmission(expected); const guard = admission.createGuard(); + guard("outbound", { id: 0, method: "session/new", params: {} }); + guard("inbound", { id: 0, result: session(initial) }); + return { admission, guard }; +} + +describe("Cursor native mode admission", () => { + it("defaults only Cursor and rejects unadmitted aliases and other providers", () => { + expect(resolveCursorSessionMode("cursor", undefined)).toBe("agent"); + expect(resolveCursorSessionMode("codex", undefined)).toBeUndefined(); + for (const mode of ["code", "architect", "search", "chat", "", null]) expect(() => resolveCursorSessionMode("cursor", mode)).toThrow(); + expect(() => resolveCursorSessionMode("pi", "agent")).toThrow(/only supported/); + }); + it.each(["agent", "plan", "ask"] as const)("admits %s only after correlated native acknowledgements", expected => { + const { admission, guard } = opened(expected); + admission.assertReady(); guard("outbound", prompt); + const reloaded = admission.createGuard(); + expect(admission.assertReady).toThrow(); + expect(() => guard("outbound", prompt)).toThrow(/replaced/); + reloaded("outbound", { id: 1, method: "session/load", params: { sessionId: "native" } }); + reloaded("inbound", { id: 1, result: session(expected) }); + admission.assertReady(); reloaded("outbound", prompt); + }); + it("permits explicit initial configuration and does not use an update as its acknowledgement", () => { + const { admission, guard } = opened("plan", "agent"); + expect(admission.isReady()).toBe(false); + guard("outbound", { id: 2, method: "session/set_config_option", params: { sessionId: "native", configId: "mode", value: "plan" } }); + guard("inbound", { method: "session/update", params: { sessionId: "native", update: { sessionUpdate: "current_mode_update", currentModeId: "plan" } } }); + expect(admission.isReady()).toBe(false); + guard("inbound", { id: 2, result: { configOptions: config("plan") } }); + admission.assertReady(); guard("outbound", prompt); + }); + it.each(["missing", "conflicting", "wrong"])("gates a reloaded prompt with %s mode acknowledgement", kind => { + const { admission } = opened("plan"); const guard = admission.createGuard(); + guard("outbound", { id: 2, method: "session/load", params: { sessionId: "native" } }); + const result = kind === "missing" ? {} : kind === "conflicting" ? { ...session("plan"), modes: { currentModeId: "ask" } } : session("agent"); + if (kind === "wrong") guard("inbound", { id: 2, result }); + else expect(() => guard("inbound", { id: 2, result })).toThrow(/mode admission/); + expect(() => guard("outbound", prompt)).toThrow(/mode admission/); + }); + it("rejects late mode drift and keeps the connection failed closed", () => { + const { admission, guard } = opened("plan"); + expect(() => guard("inbound", { method: "session/update", params: { sessionId: "native", update: { sessionUpdate: "current_mode_update", currentModeId: "agent" } } })).toThrow(/drifted/); + expect(admission.assertReady).toThrow(/drifted/); + expect(() => guard("outbound", prompt)).toThrow(/drifted/); + }); + it("rejects wrong config echoes, uncorrelated acknowledgements and cross-session control", () => { + const forged = createCursorModeAdmission("plan"); const g = forged.createGuard(); + g("inbound", { id: 2, result: session("plan") }); expect(forged.assertReady).toThrow(); + const { guard } = opened("plan", "agent"); + guard("outbound", { id: 2, method: "session/set_config_option", params: { sessionId: "native", configId: "mode", value: "plan" } }); + expect(() => guard("inbound", { id: 2, result: { configOptions: config("agent") } })).toThrow(/did not apply/); + const other = opened("plan").guard; + expect(() => other("outbound", { id: 3, method: "session/set_config_option", params: { sessionId: "other", configId: "mode", value: "plan" } })).toThrow(/different session/); + }); + it("does not mistake a bare set_mode response for configuration proof", () => { + const { admission, guard } = opened("plan", "agent"); + guard("outbound", { id: 4, method: "session/set_mode", params: { sessionId: "native", modeId: "plan" } }); + guard("inbound", { id: 4, result: {} }); expect(admission.assertReady).toThrow(); + }); +}); + +// Real ACPX runtime/SDK transport with a credential-free deterministic peer. +// This proves reconnection ordering and zero prompt bytes on rejection, not +// Cursor model tool selection or a paid provider interaction. +it.each(["plan", "agent", "missing"])("actual runtime auto-load observes %s mode before prompt delivery", async loadedMode => { + const { spawn } = await import("node:child_process"); + const { mkdtemp, rm } = await import("node:fs/promises"); + const { tmpdir } = await import("node:os"); + const { join } = await import("node:path"); + const { createAcpRuntime, createAgentRegistry, createRuntimeStore } = await import("acpx/runtime"); + const dir = await mkdtemp(join(tmpdir(), "cursor-mode-runtime-")); + const children: ReturnType[] = []; + const methods: string[] = []; + const admission = createCursorModeAdmission("plan"); + const peer = String.raw` +const send=x=>process.stdout.write(JSON.stringify({jsonrpc:'2.0',...x})+'\n'); +let mode=process.env.MODE; +const config=()=>[{id:'mode',name:'Mode',type:'select',currentValue:mode,options:['agent','plan','ask'].map(value=>({value,name:value}))}]; +require('node:readline').createInterface({input:process.stdin}).on('line',line=>{ + const m=JSON.parse(line); + if(m.method==='initialize')send({id:m.id,result:{protocolVersion:1,agentCapabilities:{loadSession:true},authMethods:[]}}); + else if(m.method==='session/new'||m.method==='session/load')send({id:m.id,result:{sessionId:'native',...(mode==='missing'?{}:{modes:{currentModeId:mode,availableModes:['agent','plan','ask'].map(id=>({id,name:id}))},configOptions:config()})}}); + else if(m.method==='session/prompt')send({id:m.id,result:{stopReason:'end_turn'}}); +});`; + const runtime = createAcpRuntime({ cwd: dir, agentRegistry: createAgentRegistry({ overrides: { cursor: "fixture" } }), sessionStore: createRuntimeStore({ stateDir: join(dir, "state") }), permissionMode: "deny-all", + protocolGuardFactory: () => admission.createGuard(), + onAcpMessage: (direction, value) => { if (direction === "outbound") methods.push((value as { method: string }).method); }, + spawnAgent: () => { const child = spawn(process.execPath, ["-e", peer], { cwd: dir, env: { MODE: children.length ? loadedMode : "plan" }, stdio: ["pipe", "pipe", "pipe"] }); children.push(child); return child; }, + }); + let handle; + try { + handle = await runtime.ensureSession({ sessionKey: "mode-recovery", agent: "cursor", mode: "persistent", cwd: dir }); + admission.assertReady(); + const exited = new Promise(resolve => children[0].once("exit", resolve)); children[0].kill("SIGTERM"); await exited; + const turn = runtime.startTurn({ handle, text: "fixture", mode: "prompt", requestId: "reloaded", timeoutMs: 2000 }); + const drain = (async () => { for await (const _event of turn.events) { /* drain */ } })(); + const result = await turn.result; await drain; + expect(children).toHaveLength(2); expect(methods).toContain("session/load"); + if (loadedMode === "plan") { expect(result.status).toBe("completed"); expect(methods.filter(m => m === "session/prompt")).toHaveLength(1); } + else { expect(result.status).toBe("failed"); expect(methods).not.toContain("session/prompt"); } + } finally { + if (handle) await runtime.close({ handle, reason: "fixture cleanup" }).catch(() => {}); + for (const child of children) if (child.exitCode === null) child.kill("SIGKILL"); + await rm(dir, { recursive: true, force: true }); + } +}); + +it.each(["valid", "unsupported", "wrong-echo"])("actual cold manager requires %s mode control before a prompt", async behavior => { + const { spawn } = await import("node:child_process"); + const { mkdtemp, rm } = await import("node:fs/promises"); + const { tmpdir } = await import("node:os"); + const { join } = await import("node:path"); + const { createAcpRuntime, createAgentRegistry, createRuntimeStore } = await import("acpx/runtime"); + const dir = await mkdtemp(join(tmpdir(), "cursor-mode-cold-")); + const children: ReturnType[] = []; const methods: string[] = []; + const peer = String.raw` +const fs=require('node:fs'), path=process.env.STATE; +let mode=fs.existsSync(path)?fs.readFileSync(path,'utf8'):'agent'; +const send=x=>process.stdout.write(JSON.stringify({jsonrpc:'2.0',...x})+'\n'); +const configs=()=>[{id:'mode',name:'Mode',type:'select',currentValue:mode,options:['agent','plan','ask'].map(value=>({value,name:value}))},{id:'model',name:'Model',type:'select',currentValue:'fixture',options:[{value:'fixture',name:'Fixture'}]}]; +require('node:readline').createInterface({input:process.stdin}).on('line',line=>{ + const m=JSON.parse(line); + if(m.method==='initialize')send({id:m.id,result:{protocolVersion:1,agentCapabilities:{loadSession:true},authMethods:[]}}); + else if(m.method==='session/new'||m.method==='session/load')send({id:m.id,result:{sessionId:'native',modes:{currentModeId:mode,availableModes:['agent','plan','ask'].map(id=>({id,name:id}))},configOptions:configs()}}); + else if(m.method==='session/set_config_option'){ + if(m.params.configId==='mode') { + if(process.env.BEHAVIOR==='unsupported')return send({id:m.id,error:{code:-32602,message:'Unsupported native mode'}}); + if(process.env.BEHAVIOR!=='wrong-echo'){mode=m.params.value;fs.writeFileSync(path,mode);} + } + send({id:m.id,result:{configOptions:configs()}}); + } + else if(m.method==='session/prompt')send({id:m.id,result:{stopReason:'end_turn'}}); +});`; + const create = (mode: "agent" | "plan") => { + const admission = createCursorModeAdmission(mode); + const runtime = createAcpRuntime({ cwd: dir, agentRegistry: createAgentRegistry({ overrides: { cursor: "fixture" } }), sessionStore: createRuntimeStore({ stateDir: join(dir, "state") }), permissionMode: "deny-all", + protocolGuardFactory: () => admission.createGuard(), + onAcpMessage: (direction, value) => { if (direction === "outbound") methods.push((value as { method: string }).method); }, + spawnAgent: () => { const child = spawn(process.execPath, ["-e", peer], { cwd: dir, env: { STATE: join(dir, "mode"), BEHAVIOR: behavior }, stdio: ["pipe", "pipe", "pipe"] }); children.push(child); return child; }, + }); + return { runtime, admission }; + }; + const first = create("agent"); let second: ReturnType | undefined; + let firstHandle; let secondHandle; + const options = { sessionKey: "cold-mode", agent: "cursor", mode: "persistent" as const, cwd: dir }; + try { + firstHandle = await first.runtime.ensureSession(options); first.admission.assertReady(); + await first.runtime.close({ handle: firstHandle, reason: "retire first manager" }); firstHandle = undefined; + second = create("plan"); const count = children.length; + secondHandle = await second.runtime.ensureSession(options); expect(children).toHaveLength(count); + await second.runtime.setConfigOption({ handle: secondHandle, key: "model", value: "fixture" }); + expect(second.admission.isReady()).toBe(false); + const selected = second.runtime.setConfigOption({ handle: secondHandle, key: "mode", value: "plan" }); + if (behavior !== "valid") { + await expect(selected).rejects.toThrow(behavior === "unsupported" ? /Unsupported native mode/ : /did not apply/); + expect(methods).not.toContain("session/prompt"); + } else { + await selected; second.admission.assertReady(); + const turn = second.runtime.startTurn({ handle: secondHandle, text: "fixture", mode: "prompt", requestId: "cold-mode-turn", timeoutMs: 2000 }); + const drain = (async () => { for await (const _event of turn.events) { /* drain */ } })(); + expect((await turn.result).status).toBe("completed"); await drain; + expect(methods.filter(m => m === "session/set_config_option")).toHaveLength(2); + expect(methods.filter(m => m === "session/load")).toHaveLength(3); + expect(methods.filter(m => m === "session/prompt")).toHaveLength(1); + } + } finally { + if (firstHandle) await first.runtime.close({ handle: firstHandle, reason: "cleanup" }).catch(() => {}); + if (second && secondHandle) await second.runtime.close({ handle: secondHandle, reason: "cleanup" }).catch(() => {}); + for (const child of children) if (child.exitCode === null) child.kill("SIGKILL"); + await rm(dir, { recursive: true, force: true }); + } +}); diff --git a/packages/paperclip-runner/src/drivers/acpx/cursor-mode.ts b/packages/paperclip-runner/src/drivers/acpx/cursor-mode.ts new file mode 100644 index 00000000000..358fd86281a --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/cursor-mode.ts @@ -0,0 +1,97 @@ +export type CursorSessionMode = "agent" | "plan" | "ask"; + +export function resolveCursorSessionMode(agent: string, mode: unknown): CursorSessionMode | undefined { + if (agent !== "cursor") { + if (mode !== undefined) throw new Error("Cursor session mode is only supported by Cursor"); + return undefined; + } + if (mode === undefined) return "agent"; + if (mode !== "agent" && mode !== "plan" && mode !== "ask") throw new Error("Invalid Cursor session mode"); + return mode; +} + +function object(value: unknown): Record { + return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record : {}; +} + +/** Native mode is independent of permissions. Every connection must prove its + * current mode before a prompt; a persisted ACPX preference is not proof. */ +export function createCursorModeAdmission(expected: CursorSessionMode) { + type State = { sessionId: string | null; mode: CursorSessionMode | null; error: Error | null }; + let current: State | null = null; + const failure = (detail: string) => new Error(`Cursor mode admission failed: ${detail}`); + const assertReady = () => { + if (current?.error) throw current.error; + if (!current?.sessionId || current.mode !== expected) throw failure("native mode does not acknowledge the selected mode"); + }; + const readMode = (result: Record, session: boolean): CursorSessionMode => { + const configs = Array.isArray(result.configOptions) ? result.configOptions.filter(value => object(value).id === "mode") : []; + if (configs.length !== 1) throw failure("native mode configuration is missing or ambiguous"); + const mode = object(configs[0]).currentValue; + if (mode !== "agent" && mode !== "plan" && mode !== "ask") throw failure("native mode is unsupported"); + if (session && object(result.modes).currentModeId !== mode) throw failure("native mode acknowledgements conflict"); + return mode; + }; + return { + assertReady, + isReady() { assertNoError(); return current?.sessionId != null && current.mode === expected; }, + createGuard() { + const state: State = { sessionId: null, mode: null, error: null }; + current = state; + const pending = new Map(); + return (direction: "inbound" | "outbound", value: unknown): void => { + if (current !== state) throw failure("connection authority was replaced"); + assertNoError(); + const message = object(value); + const params = object(message.params); + try { + if (direction === "outbound") { + const method = message.method; + if (method === "session/prompt") { + assertReady(); + if (params.sessionId !== state.sessionId) throw failure("prompt belongs to a different session"); + } else if (method === "session/new" || method === "session/load" || method === "session/set_config_option") { + if (typeof message.id !== "string" && typeof message.id !== "number") throw failure("uncorrelated mode request"); + if (pending.has(message.id)) throw failure("duplicate mode request identity"); + if (method === "session/new" || method === "session/load") { + if (pending.size) throw failure("overlapping session admission"); + state.sessionId = null; state.mode = null; + } else { + if (!state.sessionId || params.sessionId !== state.sessionId) throw failure("configuration belongs to a different session"); + if (params.configId === "mode" && params.value !== expected) throw failure("configuration changes the selected mode"); + } + pending.set(message.id, { method, sessionId: params.sessionId, selectsMode: params.configId === "mode" }); + } else if (method === "session/set_mode") { + if (!state.sessionId || params.sessionId !== state.sessionId || params.modeId !== expected) throw failure("mode control changes the selected mode"); + // This method only returns {}; require a later config/session + // acknowledgement rather than treating that empty result as proof. + state.mode = null; + } + return; + } + if (message.method === "session/update" && object(params.update).sessionUpdate === "current_mode_update") { + if (!state.sessionId || params.sessionId !== state.sessionId) throw failure("mode update belongs to a different session"); + if (object(params.update).currentModeId !== expected) throw failure("native mode drifted from the selected mode"); + return; // Notifications alone never admit a prompt. + } + if (message.method !== undefined || (typeof message.id !== "string" && typeof message.id !== "number")) return; + const request = pending.get(message.id); + if (!request) return; + pending.delete(message.id); + if (message.error !== undefined) { state.mode = null; return; } + const result = object(message.result); + const session = request.method !== "session/set_config_option"; + const sessionId = request.method === "session/new" ? result.sessionId : request.sessionId; + if (typeof sessionId !== "string" || !sessionId.trim()) throw failure("mode acknowledgement has no session identity"); + const mode = readMode(result, session); + if (!session && (request.selectsMode || state.mode === expected) && mode !== expected) throw failure("configuration did not apply the selected mode"); + state.sessionId = sessionId; state.mode = mode; + } catch (error) { + state.error = error instanceof Error ? error : failure("invalid mode acknowledgement"); + throw state.error; + } + }; + }, + }; + function assertNoError() { if (current?.error) throw current.error; } +} diff --git a/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.ts b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.ts index ecb06aba184..8155eae9f2d 100644 --- a/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.ts +++ b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.test.ts @@ -63,10 +63,13 @@ describe("qualified ACPX profiles", () => { }); }); -it("binds Cursor v4 to inspectable native instructions, closures and exact ACPX guard patch", () => { - const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/cursor-acp/profile-v4-identity.json", import.meta.url), "utf8")); +it("binds Cursor v5 to inspectable native instructions, closures and exact ACPX guard patch", () => { + const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/cursor-acp/profile-v5-identity.json", import.meta.url), "utf8")); const distribution = JSON.parse(readFileSync(new URL("../../../cursor-distributions.json", import.meta.url), "utf8")); expect(identity.declaration.distribution).toEqual(distribution); + expect(identity.declaration.sessionModeAdmission).toBe("native-config-ack-recovery-bound-v1"); + expect(identity.declaration.sessionModes).toEqual(["agent", "plan", "ask"]); + expect(identity.declaration.defaultSessionMode).toBe("agent"); expect(identity.declaration.agentProfileVersion).toBe(QUALIFIED_ACPX_PROFILES.cursor.agentProfileVersion); expect(identity.commandDigest).toBe(QUALIFIED_ACPX_PROFILES.cursor.commandDigest); expect(identity.commandDigest).toBe(`sha256:${createHash("sha256").update(JSON.stringify(identity.declaration)).digest("hex")}`); diff --git a/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts index 998278aa92b..858e97df138 100644 --- a/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts +++ b/packages/paperclip-runner/src/drivers/acpx/qualified-profiles.ts @@ -61,10 +61,10 @@ export const QUALIFIED_ACPX_PROFILES: Readonly< }, cursor: { driverKind: ACPX_DRIVER_KIND, protocolVersion: ACPX_DRIVER_PROTOCOL_VERSION, - acpxVersion: QUALIFIED_ACPX_VERSION, agent: "cursor", agentProfileVersion: 4, + acpxVersion: QUALIFIED_ACPX_VERSION, agent: "cursor", agentProfileVersion: 5, agentServerPackage: "cursor-agent", agentServerVersion: "2026.09.26-dd393fe", agentRuntimePackage: null, agentRuntimeVersion: null, - commandDigest: "sha256:b1440d559ebc4eef5c7a582f1c81fc153270cfbafa1731a8ee76d83713bdf61b", + commandDigest: "sha256:aa8c0b2b84786982bcd06b7634bf95be6f2bc42bb8def48a8751dc50cf739b6b", // Authenticated discovery has not established a qualification model. Never // turn this empty declaration into a default; callers must select an ID. qualificationModel: "", reportedModelId: "", permissionPolicy: "interactive", diff --git a/packages/paperclip-runner/src/drivers/acpx/recovery-identity.test.ts b/packages/paperclip-runner/src/drivers/acpx/recovery-identity.test.ts index def42e6c4f5..f3259a02e0a 100644 --- a/packages/paperclip-runner/src/drivers/acpx/recovery-identity.test.ts +++ b/packages/paperclip-runner/src/drivers/acpx/recovery-identity.test.ts @@ -26,6 +26,22 @@ afterEach(async () => { }); describe("ACPX recovery identity", () => { + it("binds Cursor mode on recovery and rejects missing or changed persisted mode", async () => { + const fixture = await recoveryFixture(); + const input = { ...fixture.input, profile: resolveQualifiedAcpxProfile("cursor", fixture.input.requestedModel) }; + const agent = await createAcpxRecoveryBinding(input); + const plan = await createAcpxRecoveryBinding({ ...input, cursorMode: "plan" }); + expect(agent.cursorMode).toBe("agent"); + expect(plan.profileSessionKey).not.toBe(agent.profileSessionKey); + const expected = { ...fixture.expected, profileDigest: plan.commandDigest, cursorMode: "plan" as const }; + const record = createAcpxIdentityRecord(expected, plan); + expect(acpxProviderSessionIdentity(record, plan).cursorMode).toBe("plan"); + expect(() => verifyExpectedAcpxIdentity({ ...expected, cursorMode: undefined }, plan, record)).toThrow(/immutable session/); + expect(() => verifyExpectedAcpxIdentity(expected, agent, record)).toThrow(/immutable session/); + expect(() => verifyExpectedAcpxIdentity(expected, plan, { ...record, cursorMode: undefined })).toThrow(/persisted runtime record/); + await expect(createAcpxRecoveryBinding({ ...fixture.input, cursorMode: "plan" })).rejects.toThrow(/only supported/); + }); + it("derives one stable, filesystem-safe runtime directory name", () => { expect(acpxRuntimeSessionDirectoryName("session/1")).toMatch( /^session_1-[0-9a-f]{16}$/, diff --git a/packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts b/packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts index d3cef031776..b6ec96b0d96 100644 --- a/packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts +++ b/packages/paperclip-runner/src/drivers/acpx/recovery-identity.ts @@ -1,3 +1,4 @@ +import { resolveCursorSessionMode, type CursorSessionMode } from "./cursor-mode.js"; import { createHash } from "node:crypto"; import { realpath, stat } from "node:fs/promises"; import { dirname, join, resolve } from "node:path"; @@ -19,6 +20,7 @@ export interface AcpxRecoveryBinding { requestedModel: string; effectiveModel: string; permissionMode: NativeAcpxPermissionMode; + cursorMode?: CursorSessionMode; profileSessionKey: string; } @@ -33,6 +35,7 @@ export interface AcpxIdentityRecord { requestedModel: string; effectiveModel: string; permissionMode: NativeAcpxPermissionMode; + cursorMode?: CursorSessionMode; providerLifetimeFenceCandidates: readonly [number, number, number]; } @@ -43,9 +46,11 @@ export async function createAcpxRecoveryBinding(input: { profile: QualifiedAcpxProfile; requestedModel: string; permissionMode: NativeAcpxPermissionMode; + cursorMode?: CursorSessionMode; providerPolicy?: { readOnly: boolean; readRoots?: readonly string[]; protectedPaths?: readonly string[] }; }): Promise { validateIdentity(input.normalizedSessionId, "normalized session"); + const cursorMode = resolveCursorSessionMode(input.profile.agent, input.cursorMode); if (input.providerPolicy !== undefined && typeof input.providerPolicy.readOnly !== "boolean") throw new Error("ACPX recovery requires a valid task execution policy"); if (input.requestedModel !== input.profile.qualificationModel) { throw new Error("ACPX recovery requested an unqualified model"); @@ -89,6 +94,7 @@ export async function createAcpxRecoveryBinding(input: { requestedModel: input.requestedModel, profileDigest, permissionMode: input.permissionMode, + ...(cursorMode ? { cursorMode } : {}), }), ).replace("sha256:", "paperclip-"); return { @@ -101,6 +107,7 @@ export async function createAcpxRecoveryBinding(input: { requestedModel: input.requestedModel, effectiveModel: input.requestedModel, permissionMode: input.permissionMode, + ...(cursorMode ? { cursorMode } : {}), profileSessionKey, }; } @@ -121,6 +128,7 @@ export function createAcpxIdentityRecord( requestedModel: binding.requestedModel, effectiveModel: binding.effectiveModel, permissionMode: binding.permissionMode, + ...(binding.cursorMode ? { cursorMode: binding.cursorMode } : {}), providerLifetimeFenceCandidates: Object.freeze([ ...expected.providerLifetimeFenceCandidates, ]) as readonly [number, number, number], @@ -146,6 +154,7 @@ export function acpxProviderSessionIdentity( requestedModel: record.requestedModel, effectiveModel: record.effectiveModel, permissionMode: record.permissionMode, + ...(record.cursorMode ? { cursorMode: record.cursorMode } : {}), providerLifetimeFenceCandidates: record.providerLifetimeFenceCandidates, }; verifyExpectedAcpxIdentity(identity, binding, record); @@ -170,7 +179,8 @@ export function verifyExpectedAcpxIdentity( expected.workspaceDigest !== binding.workspaceDigest || expected.requestedModel !== binding.requestedModel || expected.effectiveModel !== binding.effectiveModel || - expected.permissionMode !== binding.permissionMode + expected.permissionMode !== binding.permissionMode || + expected.cursorMode !== binding.cursorMode ) { throw new Error( "ACPX recovery identity conflicts with the immutable session configuration", @@ -189,6 +199,7 @@ export function verifyExpectedAcpxIdentity( record.requestedModel !== binding.requestedModel || record.effectiveModel !== binding.effectiveModel || record.permissionMode !== binding.permissionMode || + record.cursorMode !== binding.cursorMode || !sameFenceCandidates( record.providerLifetimeFenceCandidates, expected.providerLifetimeFenceCandidates, @@ -213,6 +224,7 @@ function parsePersistedRecord(value: unknown): AcpxIdentityRecord { "requestedModel", "effectiveModel", "permissionMode", + "cursorMode", "providerLifetimeFenceCandidates", ]); return validatedRecord(record); @@ -239,6 +251,7 @@ function validatedRecord(value: Record): AcpxIdentityRecord { if (!isPermissionMode(value.permissionMode)) { throw new Error("ACPX identity permission mode is invalid"); } + if (value.cursorMode !== undefined) resolveCursorSessionMode("cursor", value.cursorMode); validateFenceCandidates(value.providerLifetimeFenceCandidates); return value as unknown as AcpxIdentityRecord; } @@ -267,6 +280,7 @@ function validateExpected(expected: AcpxExpectedSessionIdentity): void { ) { throw new Error("Expected ACPX permission mode is invalid"); } + if (expected.cursorMode !== undefined) resolveCursorSessionMode("cursor", expected.cursorMode); validateFenceCandidates(expected.providerLifetimeFenceCandidates); } diff --git a/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts b/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts index 03669445ea8..0c8ffa797ce 100644 --- a/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts +++ b/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts @@ -195,6 +195,31 @@ afterEach(async () => { }); describe("ACPX runtime host", () => { + it.each([undefined, "plan", "ask"] as const)("requires observed Cursor mode %s in the host identity", async selected => { + const fixture = await hostFixture(); + const mode = selected ?? "agent"; + const options = { ...fixture.options, agent: "cursor" as const, model: "explicit-test-model", cursorMode: selected, permissionMode: "approve-all" as const, environment: { CURSOR_API_KEY: "test" } }; + const openRuntime = vi.fn(async (launch: AcpxRuntimePortOpenOptions) => { + expect(launch.cursorMode).toBe(mode); + return runtimePort({ getStatus: async () => ({ models: { currentModelId: options.model } }), identity: async () => ({ acpxRecordId: "record-1", backendSessionId: "backend-1", agentSessionId: "agent-1", cursorMode: mode }) }); + }); + const host = await AcpxRuntimeHost.open(options, fixture.dependencies({ openRuntime })); + expect(host.identity().cursorMode).toBe(mode); + await host.close({ reason: "mode test complete" }); + }); + + it("rejects missing observed Cursor mode and mode supplied to another provider", async () => { + const fixture = await hostFixture(); + const port = runtimePort({ getStatus: async () => ({ models: { currentModelId: "explicit-test-model" } }) }); + const openRuntime = vi.fn(async () => port); + const options = { ...fixture.options, agent: "cursor" as const, model: "explicit-test-model", permissionMode: "approve-all" as const, environment: { CURSOR_API_KEY: "test" } }; + await expect(AcpxRuntimeHost.open(options, fixture.dependencies({ openRuntime }))).rejects.toThrow(/Cursor mode does not match/); + expect(port.close).toHaveBeenCalled(); + openRuntime.mockClear(); + await expect(AcpxRuntimeHost.open({ ...options, agent: "codex", model: "gpt-5.6-sol", cursorMode: "plan" }, fixture.dependencies({ openRuntime }))).rejects.toThrow(/only supported/); + expect(openRuntime).not.toHaveBeenCalled(); + }); + it.each([ { PAPERCLIP_NATIVE_MCP_NAME: "paperclip-assigned" }, { PAPERCLIP_NATIVE_MCP_NAME: "paperclip", PAPERCLIP_NATIVE_MCP_URL: "http://127.0.0.1:3211/mcp", PAPERCLIP_NATIVE_MCP_TOKEN: "x".repeat(40) }, @@ -842,7 +867,7 @@ describe("ACPX runtime host", () => { const opened: AcpxRuntimePortOpenOptions[] = []; const dependencies = fixture.dependencies({ openRuntime: async launch => { opened.push(launch); - return runtimePort({ getStatus: async () => ({ models: { currentModelId: model } }) }); + return runtimePort({ getStatus: async () => ({ models: { currentModelId: model } }), identity: async () => ({ acpxRecordId: "record-1", backendSessionId: "backend-1", agentSessionId: "agent-1", ...(agent === "cursor" ? { cursorMode: launch.cursorMode } : {}) }) }); } }); // Missing trusted context must not turn ambient values into authority. const withoutCopy = await AcpxRuntimeHost.open(options, dependencies); @@ -1830,6 +1855,7 @@ describe("ACPX runtime host", () => { function runtimePort( input: { + identity?: AcpxRuntimePort["identity"]; getStatus?: AcpxRuntimePort["getStatus"]; setModel?: NonNullable; startTurn?: AcpxRuntimePort["startTurn"]; @@ -1837,11 +1863,11 @@ function runtimePort( } = {}, ): AcpxRuntimePort & { close: ReturnType } { return { - identity: async () => ({ + identity: input.identity ?? (async () => ({ acpxRecordId: "record-1", backendSessionId: "backend-1", agentSessionId: "agent-1", - }), + })), getStatus: input.getStatus ?? (async () => ({ diff --git a/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts b/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts index 66ca501c37c..559dc8344c8 100644 --- a/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts +++ b/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts @@ -1,3 +1,4 @@ +import { resolveCursorSessionMode, type CursorSessionMode } from "./cursor-mode.js"; import { dirname, join } from "node:path"; import { bindAcpxAgentFiles } from "./agent-files-binding.js"; import { assertAcpxProfileEnvironment, assertAcpxProfileWorkspace, classifyAcpxProfileError, verifyAcpxProfileInstallation } from "./profile-installation.js"; @@ -77,6 +78,7 @@ const ACPX_ADMISSION_CLEANUP_RETRY_DELAY_MS = 10; const ACPX_ADMISSION_CLEANUP_RESCHEDULE_MS = 1_000; export interface AcpxRuntimePortIdentity { + cursorMode?: CursorSessionMode; acpxRecordId: string; backendSessionId: string; agentSessionId: string; @@ -153,6 +155,7 @@ export interface AcpxRuntimePortOpenOptions { stateDirectory: string; providerSessionKey: string; permissionMode: NativeAcpxPermissionMode; + cursorMode?: CursorSessionMode; permissionPolicy: ReturnType; launchEnvironment: Readonly; /** Kernel credential-home quorum inherited by the provider sentinel. */ @@ -226,6 +229,7 @@ export interface OpenAcpxRuntimeHostOptions { agent: QualifiedAcpxAgent; model: string; permissionMode: NativeAcpxPermissionMode; + cursorMode?: CursorSessionMode; systemInstructions?: string; runtimeContext?: NativeRuntimeContextSnapshot | null; environment?: NodeJS.ProcessEnv; @@ -334,6 +338,7 @@ export class AcpxRuntimeHost { profile, requestedModel: options.model, permissionMode: options.permissionMode, + cursorMode: resolveCursorSessionMode(options.agent, options.cursorMode), ...(["cursor", "copilot", "pi"].includes(options.agent) && options.providerPolicy !== undefined ? { providerPolicy: options.providerPolicy } : {}), }), @@ -562,6 +567,7 @@ export class AcpxRuntimeHost { stateDirectory: sandbox.stateDirectory, providerSessionKey: binding.profileSessionKey, permissionMode: binding.permissionMode, + cursorMode: binding.cursorMode, permissionPolicy: acpxRuntimePermissionPolicy( binding.permissionMode, ), @@ -619,6 +625,9 @@ export class AcpxRuntimeHost { ), dependencies.retainAdmissionCleanup, ); + if (runtimeIdentity.cursorMode !== binding.cursorMode) { + throw new Error("ACPX runtime Cursor mode does not match the admitted session configuration"); + } const observedIdentity: AcpxExpectedSessionIdentity = { kind: "acpx", normalizedSessionId: binding.normalizedSessionId, diff --git a/packages/paperclip-runner/test/fixtures/cursor-acp/mode-v5-offline-proof.json b/packages/paperclip-runner/test/fixtures/cursor-acp/mode-v5-offline-proof.json new file mode 100644 index 00000000000..7cfcae2876a --- /dev/null +++ b/packages/paperclip-runner/test/fixtures/cursor-acp/mode-v5-offline-proof.json @@ -0,0 +1,32 @@ +{ + "schema": "paperclip.cursor.native-mode-offline-proof.v1", + "sourceSha256": "c01657c111f65153d7a40a923f01a5a86d393d1cd6893eaa03f71b9604d2af0c", + "rows": [ + { + "selected": "agent", + "nativeMetadata": "default", + "configAcknowledgement": "agent", + "currentModeNotification": "agent", + "reconstructedSessionAcknowledgement": "agent", + "userMessageModeInput": "default" + }, + { + "selected": "plan", + "nativeMetadata": "plan", + "configAcknowledgement": "plan", + "currentModeNotification": "plan", + "reconstructedSessionAcknowledgement": "plan", + "userMessageModeInput": "plan" + }, + { + "selected": "ask", + "nativeMetadata": "search", + "configAcknowledgement": "ask", + "currentModeNotification": "ask", + "reconstructedSessionAcknowledgement": "ask", + "userMessageModeInput": "search" + } + ], + "planHandlerHasModeMutation": false, + "boundary": "pinned native config/session/UserMessage methods; storage, mode enum converter and transport doubled; no inference" +} diff --git a/packages/paperclip-runner/test/fixtures/cursor-acp/profile-v5-identity.json b/packages/paperclip-runner/test/fixtures/cursor-acp/profile-v5-identity.json new file mode 100644 index 00000000000..e10e9df1d20 --- /dev/null +++ b/packages/paperclip-runner/test/fixtures/cursor-acp/profile-v5-identity.json @@ -0,0 +1,53 @@ +{ + "commandDigest": "sha256:aa8c0b2b84786982bcd06b7634bf95be6f2bc42bb8def48a8751dc50cf739b6b", + "declaration": { + "schema": "paperclip.acpx_profile_declaration.v1", + "agent": "cursor", + "agentProfileVersion": 5, + "acpxVersion": "0.13.1", + "agentServerVersion": "2026.09.26-dd393fe", + "patchVersion": "paperclip-cursor-instructions-v2", + "distribution": { + "schema": "paperclip.cursor_distribution.v1", + "version": "2026.09.26-dd393fe", + "platforms": { + "darwin-arm64": { + "url": "https://downloads.cursor.com/lab/2026.09.26-dd393fe/darwin/arm64/agent-cli-package.tar.gz", + "archiveSha256": "538827d96a779bab854a865c8e42859e8e87db34b5f69770261b90fc8cfff191", + "closureSha256": "912a37edb67fd7737809c24049dce2db20b1330f98b15a6e43809f0e0943cb6c", + "executable": "node", + "entrypoint": "index.js", + "vendorClosureSha256": "77394184a89b0e7384971181da19c3c82d83a399b04e7944b3f94fe3d7e62b25" + }, + "darwin-x64": { + "url": "https://downloads.cursor.com/lab/2026.09.26-dd393fe/darwin/x64/agent-cli-package.tar.gz", + "archiveSha256": "ed1771c44cbf0f8059c67cac0d939e6a60eb730bd066d7dc4cbb14de314cfb6e", + "closureSha256": "322f54c7bd533b202a311ce8e2c8916bfe0202790ef8a40fbb36bb89cbd506cb", + "executable": "node", + "entrypoint": "index.js", + "vendorClosureSha256": "7c8775160af74e5fb8d25a30e8412c1a6476b0661529078a686e5118fd1c5e5f" + }, + "linux-x64": { + "url": "https://downloads.cursor.com/lab/2026.09.26-dd393fe/linux/x64/agent-cli-package.tar.gz", + "archiveSha256": "8085fd120f5c71f4eae7fea26a043718e5644e3071e4fab3220a0e58c51f9593", + "closureSha256": "a375fc771dfe86b9b24532f95956ec4b02c5f4f24d80f5db06565160eb3b672c", + "executable": "node", + "entrypoint": "index.js", + "vendorClosureSha256": "bf04ef8ea6a63191067a6b3e15139aa2c793d8419daab246aa3f0a012e1bbcd9" + } + }, + "patchVersion": "paperclip-cursor-instructions-v2" + }, + "agentFilesBinding": "registered-runtime-context-v1", + "instructionBinding": "native-global-rules-v1", + "instructionAdmission": "synchronous-protocol-guard-v1", + "acpxPatchSha256": "79aad2d688b03362e8cfcbf7a08f78a8383869f6882a9c9ed66f1d18efb94f2b", + "sessionModeAdmission": "native-config-ack-recovery-bound-v1", + "sessionModes": [ + "agent", + "plan", + "ask" + ], + "defaultSessionMode": "agent" + } +}