Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -477,6 +477,7 @@ export function makeCursorAgentSdkReplayRunner(
},
catch: (cause) => replayRunnerError(transcript, cause, "replay.session.send"),
}),
rollback: () => Effect.die("Cursor replay rollback is not recorded"),
listMessages: Effect.try({
try: () => {
assertOutbound({
Expand Down
12 changes: 12 additions & 0 deletions apps/server/src/orchestration-v2/CommandPolicy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,18 @@ layer("CommandPolicyV2", (it) => {
}),
);

it.effect("allows Cursor conversation rollback", () =>
Effect.gen(function* () {
const policy = yield* CommandPolicy.CommandPolicyV2;
yield* policy.ensureRollback({
commandId,
threadId,
providerInstanceId: ProviderInstanceId.make("cursor"),
capabilities: CursorProviderCapabilitiesV2,
});
}),
);

it.effect("falls back to portable context when Cursor cannot fork natively", () =>
Effect.gen(function* () {
const policy = yield* CommandPolicy.CommandPolicyV2;
Expand Down
8 changes: 6 additions & 2 deletions docs/user/cursor.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,13 @@ The adapter supports:
- thread-scoped T3 Code MCP tools alongside ambient Cursor MCP/plugins from disk;
- image attachments;
- interruption, queued app messages, and in-turn steering;
- editing sent messages and reverting conversations through persisted SDK checkpoints;
- provider conversation snapshots through `Agent.messages.list()`;
- Cursor `task` subagents, projected as read-only child app threads with their tool activity and
final result.

The public SDK does not currently expose native agent fork, conversation rollback, or interactive
approval callbacks. A text-only steer reaches the current run without restarting it.
The public SDK does not currently expose native agent fork or interactive approval
callbacks. A text-only steer reaches the current run without restarting it.
When Cursor cannot deliver the steer, the same message is queued for the next turn after
this run finishes. If you press Stop, that follow-up stays held until you resume the queue. Steers
with attachments and provider or runtime changes that must apply immediately interrupt and restart
Expand All @@ -64,6 +65,9 @@ Same-provider Cursor forks use the orchestrator's portable full-thread context h
Cursor agent. The SDK has in-process custom callback tools, but the V2 adapter intentionally uses the
authenticated, thread-scoped MCP server instead.

Editing a sent message rewinds the conversation to before that message. Rollback requires the
local Cursor checkpoint data to still be available on the environment running the thread.

Portable handoffs summarize eligible timeline items and can omit the end of long messages. Read
[Context in portable handoffs](./portable-handoffs.md) before using a fork for work whose exact
instructions must carry forward.
Expand Down
69 changes: 69 additions & 0 deletions packages/provider-cursor/src/server/CursorAgentSdk.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { assert, describe, it } from "@effect/vitest";
import { ProviderSessionId, ThreadId } from "@t3tools/contracts";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import { JsonlLocalAgentStore } from "@cursor/sdk";
import * as Layer from "effect/Layer";
import * as Exit from "effect/Exit";
import * as Cause from "effect/Cause";
Expand Down Expand Up @@ -186,6 +187,74 @@ describe("CursorAgentSdkRunner", () => {
}).pipe(Effect.provide(NodeServices.layer)),
);

it.effect("restores persisted run boundaries and rejects unavailable or active targets", () =>
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
const root = yield* fs.makeTempDirectoryScoped({ prefix: "cursor-rollback-" });
const store = new JsonlLocalAgentStore(root);
const agentId = "agent-cursor-agent-sdk-test";
const checkpoint = { schemaVersion: 1 as const, rootBlobId: "retained" };
const document = {
agentId,
cwd: root,
status: "idle" as const,
activeRunId: null,
createdAt: 0,
updatedAt: 0,
latestCheckpoint: { ...checkpoint, rootBlobId: "discarded" },
sdkMetadata: { preserved: true },
};
yield* Effect.promise(async () => {
await store.agents.create({ agent: document });
await store.checkpoints.create({
agentId,
blobId: checkpoint.rootBlobId,
data: new Uint8Array([1]),
});
await store.runs.create({
run: {
agentId,
runId: "retained-run",
turnNumber: 1,
status: "finished",
createdAt: 0,
updatedAt: 0,
latestCheckpointRef: checkpoint,
},
});
});
cursorSdkMock.setAgentCloseFailure(undefined);
const runner = yield* CursorAgentSdk.CursorAgentSdkRunner;
const session = yield* runner.open({
operation: "resume",
agentId,
threadId: ThreadId.make("rollback"),
providerSessionId: ProviderSessionId.make("rollback"),
options: { local: { cwd: root, store } },
});
yield* session.rollback("retained-run");
const reopened = new JsonlLocalAgentStore(root);
const restored = yield* Effect.promise(() => reopened.agents.get({ agentId }));
assert.deepStrictEqual(restored?.latestCheckpoint, checkpoint);
assert.deepStrictEqual(restored?.sdkMetadata, document.sdkMetadata);
const missing = yield* session.rollback("missing").pipe(Effect.exit);
assert(Exit.isFailure(missing));
yield* Effect.promise(() =>
store.agents.update({ agent: { ...document, status: "running" } }),
);
assert(Exit.isFailure(yield* session.rollback(null).pipe(Effect.exit)));
yield* Effect.promise(() => store.agents.update({ agent: document }));
yield* Effect.promise(() =>
store.checkpoints.delete({
filter: { agentIds: [agentId], blobIds: [checkpoint.rootBlobId] },
}),
);
assert(Exit.isFailure(yield* session.rollback("retained-run").pipe(Effect.exit)));
yield* session.rollback(null);
assert.isNull((yield* Effect.promise(() => store.agents.get({ agentId })))?.latestCheckpoint);
}).pipe(Effect.provide(Layer.merge(layerTest, NodeServices.layer))),
);

it.effect("constructs without loading and reports first-use load failures as runner errors", () =>
Effect.gen(function* () {
const failure = new Error("missing SDK chunk");
Expand Down
45 changes: 45 additions & 0 deletions packages/provider-cursor/src/server/CursorAgentSdk.ts
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ export interface CursorAgentSdkSession {
readonly send: <Error>(
input: CursorAgentSdkSendInput<Error>,
) => Effect.Effect<CursorAgentSdkRun, CursorAgentSdkRunnerError>;
readonly rollback: (runId: string | null) => Effect.Effect<void, CursorAgentSdkRunnerError>;
readonly listMessages: Effect.Effect<ReadonlyArray<AgentMessage>, CursorAgentSdkRunnerError>;
/** Context fill at the latest checkpoint, if Cursor saved one. Absent on test doubles. */
readonly readContextUsage?: Effect.Effect<
Expand Down Expand Up @@ -731,6 +732,50 @@ export const makeCursorAgentSdkRunner = Effect.fn("makeCursorAgentSdkRunner")(fu
),
} satisfies CursorAgentSdkRun;
}),
rollback: Effect.fn("CursorAgentSdkSession.rollback")(function* (runId) {
yield* Effect.tryPromise({
try: async () => {
const ownedStore =
input.options.local?.store === undefined
? await sdk.loadSqlite().SqliteLocalAgentStore.open({
workspaceRef: storeCwd ?? cwd ?? process.cwd(),
})
: undefined;
const store = input.options.local?.store ?? ownedStore!;
try {
const document = await store.agents.get({ agentId: agent.agentId });
if (document === null) throw new Error("Cursor agent is unavailable for rollback.");
if (document.status === "running" || document.activeRunId != null)
throw new Error("Cannot roll back an active Cursor agent.");
const run =
runId === null ? null : await store.runs.get({ agentId: agent.agentId, runId });
if (
runId !== null &&
(run === null ||
run.agentId !== agent.agentId ||
run.status === "running" ||
run.status === "queued" ||
run.latestCheckpointRef == null)
)
throw new Error("Cursor turn checkpoint is unavailable for rollback.");
const checkpoint = run?.latestCheckpointRef ?? null;
if (
checkpoint !== null &&
(await store.checkpoints.get({
agentId: agent.agentId,
blobId: checkpoint.rootBlobId,
})) === null
)
throw new Error("Cursor checkpoint blob is unavailable for rollback.");
agent.close();
await store.agents.update({ agent: { ...document, latestCheckpoint: checkpoint } });
} finally {
await ownedStore?.dispose();
}
},
catch: (cause) => runnerError(cause, "agent.rollback"),
});
}),
listMessages: log({
direction: "outgoing",
stage: "decoded",
Expand Down
Loading
Loading