534aee66ae
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - There are many adapter types, one per agent-runtime product (Claude,
Codex, OpenCode, Cursor local CLI, etc.)
> - Cursor shipped a public TypeScript SDK on 2026-04-29 that exposes
Cursor's full hosted-agent platform (cloud VMs, harness, MCP, skills,
hooks)
> - Paperclip had no first-class adapter for this — agents that wanted
to use Cursor's managed cloud runtime had to fall back to the local CLI
adapter, which loses the cloud session, streaming, and durable run model
> - This PR adds a new `cursor_cloud` adapter built directly on
`@cursor/sdk`, with Paperclip's heartbeat mapped to Cursor's
durable-agent + per-run model
> - The benefit is that any Paperclip agent can now drive a Cursor cloud
agent across heartbeats with native session reuse, streaming, and
cancellation, while Paperclip remains the source of truth for issue/task
state
## What Changed
- New built-in adapter package `packages/adapters/cursor-cloud` (15
files, ~1.7k LOC) backed by `@cursor/sdk` ^1.0.12
- `src/server/execute.ts` — SDK-first lifecycle: `Agent.create` /
`Agent.resume` / `Agent.getRun` / `agent.send` / `run.stream` /
`run.wait`, with session reuse keyed on the (runtime env type, env name,
repo set) tuple
- `src/server/session.ts` — codec for `cursorAgentId` + `latestRunId` +
repo metadata, persisted in `runtime.sessionParams`
- `src/server/test.ts` — environment probe via `Cursor.me()` and
optional model validation via `Cursor.models.list()`
- `src/ui/parse-stdout.ts` + `src/cli/format-event.ts` — normalize
Cursor SDK message types (`status`, `thinking`, `assistant`, `user`,
`tool_call`, `tool_result`, `result`) into Paperclip transcript events
for the UI and CLI
- Registrations: `packages/shared/src/constants.ts`,
`packages/adapter-utils/src/session-compaction.ts`,
`server/src/adapters/{registry,builtin-adapter-types}.ts`,
`ui/src/adapters/{registry,adapter-display-registry}.ts` +
`ui/src/adapters/cursor-cloud/index.ts`, `cli/src/adapters/registry.ts`,
plus workspace deps in `cli`/`server`/`ui` `package.json`
- `ui/src/components/AgentConfigForm.tsx` — hide local-Cursor
`mode`/thinking-effort field for `cursor_cloud` (different config
surface)
- 11 vitest tests covering execute paths (fresh create, matching-resume,
active-run reattach, non-finished result), session codec round-trip,
transcript parsing, and config building
## Verification
Reviewer steps:
```bash
pnpm install
pnpm --filter @paperclipai/adapter-cursor-cloud typecheck # → clean
pnpm vitest run packages/adapters/cursor-cloud # → 11/11 passing
```
End-to-end check against a real Cursor cloud agent (requires
`CURSOR_API_KEY` and Cursor GitHub-app install on the target repo):
1. Create a `cursor_cloud` agent in Paperclip with `repoUrl` set to the
test repo, `repoStartingRef: main`, and `env.CURSOR_API_KEY` set
2. Trigger a heartbeat → adapter calls `Agent.create({ cloud: { env: {
type: "cloud" }, repos: [...] } })`, streams events, terminates on
`finished`
3. Trigger a second heartbeat → adapter calls `Agent.resume` or
`agent.send` follow-up depending on prior-run state, reusing
`cursorAgentId`
4. The Paperclip UI/CLI transcript reflects Cursor `status` / `thinking`
/ `assistant` events as they stream
5. Cancellation from Paperclip maps to `run.cancel()` or Cloud API v1
`cancelRun` for cross-heartbeat cancellation
A direct-SDK smoke run against a real repo (devinfoley/my_test_project @
main) confirmed: `Cursor.me()` ok → `Agent.create` → `agent.send` →
`run.stream()` (30 events) → terminal status `finished` in ~11s.
## Risks
- **New adapter, additive only.** No existing adapter or registry is
replaced; current `cursor` local-CLI adapter is untouched. Default
behavior of any existing agent is unchanged.
- **External dependency on `@cursor/sdk`.** Cursor's SDK is v1.0.x and
may evolve. Mocked unit tests cover the public surface used here; if the
SDK breaks compatibility we update the adapter independently.
- **Cost/budget.** `cursor_cloud` runs on Cursor's billed cloud VMs;
operators must understand they are spending money outside Paperclip's
budget controls when they enable this adapter. Same shape as other
API-billed adapters.
- **No webhook support in V1.** The SDK already provides
stream/wait/cancel/reattach, so V1 does not require a public callback
URL. If a future use case needs out-of-band wakes, we add a Cloud API v1
webhook bridge as a separate change. This is called out in the issue
plan document.
- **Lockfile.** Per repo policy, `pnpm-lock.yaml` is intentionally not
in this PR — CI's lockfile workflow will update it on merge given the
manifest changes.
## Model Used
- Provider: Anthropic Claude (via Claude Code / Paperclip `claude_local`
adapter)
- Model: `claude-opus-4-7` (Claude Opus 4.7), knowledge cutoff January
2026
- Mode: standard tool-use with extended reasoning
- Context: ~200k token window
- Capabilities used: code generation, multi-file edits, shell/test
execution, GitHub PR workflow
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass (11/11 in
`packages/adapters/cursor-cloud`)
- [x] I have added or updated tests where applicable (4 new test files,
11 cases)
- [ ] If this change affects the UI, I have included before/after
screenshots (the only UI change is hiding the local-Cursor mode field on
the `cursor_cloud` adapter — happy to attach a screenshot if the
reviewer wants one)
- [x] I have updated relevant documentation to reflect my changes (issue
plan document supersedes the pre-SDK design; tracked in PAPA-203)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
144 lines
3.9 KiB
TypeScript
144 lines
3.9 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import { parseCursorCloudStdoutLine } from "./parse-stdout.js";
|
|
|
|
const ts = "2026-05-10T05:10:00.000Z";
|
|
|
|
describe("parseCursorCloudStdoutLine", () => {
|
|
it("parses init and status events", () => {
|
|
expect(
|
|
parseCursorCloudStdoutLine(
|
|
JSON.stringify({ type: "cursor_cloud.init", sessionId: "agent-123", model: "gpt-5.4" }),
|
|
ts,
|
|
),
|
|
).toEqual([{ kind: "init", ts, sessionId: "agent-123", model: "gpt-5.4" }]);
|
|
|
|
expect(
|
|
parseCursorCloudStdoutLine(
|
|
JSON.stringify({ type: "cursor_cloud.status", status: "running", message: "Reattached" }),
|
|
ts,
|
|
),
|
|
).toEqual([{ kind: "system", ts, text: "running: Reattached" }]);
|
|
});
|
|
|
|
it("parses assistant text and tool lifecycle SDK messages", () => {
|
|
const assistantLine = JSON.stringify({
|
|
type: "cursor_cloud.message",
|
|
message: {
|
|
type: "assistant",
|
|
message: {
|
|
content: [
|
|
{ type: "text", text: "Working on it." },
|
|
{ type: "tool_use", id: "tool-1", name: "read_file", input: { path: "README.md" } },
|
|
],
|
|
},
|
|
},
|
|
});
|
|
expect(parseCursorCloudStdoutLine(assistantLine, ts)).toEqual([
|
|
{ kind: "assistant", ts, text: "Working on it." },
|
|
{ kind: "tool_call", ts, name: "read_file", toolUseId: "tool-1", input: { path: "README.md" } },
|
|
]);
|
|
|
|
const toolStartLine = JSON.stringify({
|
|
type: "cursor_cloud.message",
|
|
message: {
|
|
type: "tool_call",
|
|
id: "call-1",
|
|
name: "bash",
|
|
status: "running",
|
|
args: { command: "pwd" },
|
|
},
|
|
});
|
|
expect(parseCursorCloudStdoutLine(toolStartLine, ts)).toEqual([
|
|
{ kind: "tool_call", ts, name: "bash", toolUseId: "call-1", input: { command: "pwd" } },
|
|
]);
|
|
|
|
const toolEndLine = JSON.stringify({
|
|
type: "cursor_cloud.message",
|
|
message: {
|
|
type: "tool_call",
|
|
id: "call-1",
|
|
name: "bash",
|
|
status: "completed",
|
|
result: { stdout: "/repo" },
|
|
},
|
|
});
|
|
expect(parseCursorCloudStdoutLine(toolEndLine, ts)).toEqual([
|
|
{
|
|
kind: "tool_result",
|
|
ts,
|
|
toolUseId: "call-1",
|
|
toolName: "bash",
|
|
content: JSON.stringify({ stdout: "/repo" }, null, 2),
|
|
isError: false,
|
|
},
|
|
]);
|
|
});
|
|
|
|
it("parses standalone tool_result SDK messages", () => {
|
|
const line = JSON.stringify({
|
|
type: "cursor_cloud.message",
|
|
message: {
|
|
type: "tool_result",
|
|
call_id: "call-9",
|
|
name: "read_file",
|
|
result: { contents: "file body" },
|
|
},
|
|
});
|
|
expect(parseCursorCloudStdoutLine(line, ts)).toEqual([
|
|
{
|
|
kind: "tool_result",
|
|
ts,
|
|
toolUseId: "call-9",
|
|
toolName: "read_file",
|
|
content: JSON.stringify({ contents: "file body" }, null, 2),
|
|
isError: false,
|
|
},
|
|
]);
|
|
|
|
const errorLine = JSON.stringify({
|
|
type: "cursor_cloud.message",
|
|
message: {
|
|
type: "tool_result",
|
|
call_id: "call-10",
|
|
name: "bash",
|
|
is_error: true,
|
|
content: "exit 1",
|
|
},
|
|
});
|
|
expect(parseCursorCloudStdoutLine(errorLine, ts)).toEqual([
|
|
{
|
|
kind: "tool_result",
|
|
ts,
|
|
toolUseId: "call-10",
|
|
toolName: "bash",
|
|
content: "exit 1",
|
|
isError: true,
|
|
},
|
|
]);
|
|
});
|
|
|
|
it("parses result events and preserves unknown lines as stdout", () => {
|
|
expect(
|
|
parseCursorCloudStdoutLine(
|
|
JSON.stringify({ type: "cursor_cloud.result", status: "finished", result: "Done", model: "gpt-5.4" }),
|
|
ts,
|
|
),
|
|
).toEqual([
|
|
{
|
|
kind: "result",
|
|
ts,
|
|
text: "Done",
|
|
inputTokens: 0,
|
|
outputTokens: 0,
|
|
cachedTokens: 0,
|
|
costUsd: 0,
|
|
subtype: "finished",
|
|
isError: false,
|
|
errors: [],
|
|
},
|
|
]);
|
|
|
|
expect(parseCursorCloudStdoutLine("plain text", ts)).toEqual([{ kind: "stdout", ts, text: "plain text" }]);
|
|
});
|
|
});
|