Add cursor_cloud adapter for Cursor SDK + Cloud Agents API v1 (#5664)

## 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>

packages/adapters/cursor-cloud/src/ui/build-config.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+import { buildCursorCloudConfig } from "./build-config.js";
+
+function makeValues(overrides: Partial<CreateConfigValues> = {}): CreateConfigValues {
+  return {
+    adapterType: "cursor_cloud",
+    cwd: "",
+    instructionsFilePath: "",
+    promptTemplate: "",
+    model: "",
+    thinkingEffort: "",
+    chrome: false,
+    dangerouslySkipPermissions: false,
+    search: false,
+    fastMode: false,
+    dangerouslyBypassSandbox: false,
+    command: "",
+    args: "",
+    extraArgs: "",
+    envVars: "",
+    envBindings: {},
+    url: "",
+    bootstrapPrompt: "",
+    payloadTemplateJson: "",
+    workspaceStrategyType: "project_primary",
+    workspaceBaseRef: "",
+    workspaceBranchTemplate: "",
+    worktreeParentDir: "",
+    runtimeServicesJson: "",
+    maxTurnsPerRun: 1000,
+    heartbeatEnabled: false,
+    intervalSec: 300,
+    adapterSchemaValues: {},
+    ...overrides,
+  };
+}
+
+describe("buildCursorCloudConfig", () => {
+  it("persists schema values and top-level prompt fields", () => {
+    const config = buildCursorCloudConfig(
+      makeValues({
+        instructionsFilePath: ".cursor/AGENTS.md",
+        promptTemplate: "hello {{agent.name}}",
+        bootstrapPrompt: "bootstrap",
+        model: "gpt-5.4",
+        adapterSchemaValues: {
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+          runtimeEnvType: "pool",
+          runtimeEnvName: "trusted-workers",
+          autoCreatePR: true,
+        },
+      }),
+    );
+
+    expect(config).toMatchObject({
+      instructionsFilePath: ".cursor/AGENTS.md",
+      promptTemplate: "hello {{agent.name}}",
+      bootstrapPromptTemplate: "bootstrap",
+      model: "gpt-5.4",
+      repoUrl: "https://github.com/paperclipai/paperclip.git",
+      runtimeEnvType: "pool",
+      runtimeEnvName: "trusted-workers",
+      autoCreatePR: true,
+    });
+  });
+
+  it("merges structured env bindings over legacy envVars text", () => {
+    const config = buildCursorCloudConfig(
+      makeValues({
+        envVars: ["CURSOR_API_KEY=legacy-key", "PLAIN=value", "INVALID KEY=nope"].join("\n"),
+        envBindings: {
+          CURSOR_API_KEY: { type: "secret_ref", secretId: "secret-1", version: "latest" },
+          STRUCTURED_ONLY: "from-binding",
+        },
+      }),
+    );
+
+    expect(config.env).toEqual({
+      CURSOR_API_KEY: { type: "secret_ref", secretId: "secret-1", version: "latest" },
+      PLAIN: { type: "plain", value: "value" },
+      STRUCTURED_ONLY: { type: "plain", value: "from-binding" },
+    });
+  });
+});

packages/adapters/cursor-cloud/src/ui/build-config.ts

@@ -0,0 +1,67 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+function parseEnvVars(text: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+function parseEnvBindings(bindings: unknown): Record<string, unknown> {
+  if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};
+  const env: Record<string, unknown> = {};
+  for (const [key, raw] of Object.entries(bindings)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    if (typeof raw === "string") {
+      env[key] = { type: "plain", value: raw };
+      continue;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+    const rec = raw as Record<string, unknown>;
+    if (rec.type === "plain" && typeof rec.value === "string") {
+      env[key] = { type: "plain", value: rec.value };
+      continue;
+    }
+    if (rec.type === "secret_ref" && typeof rec.secretId === "string") {
+      env[key] = {
+        type: "secret_ref",
+        secretId: rec.secretId,
+        ...(typeof rec.version === "number" || rec.version === "latest"
+          ? { version: rec.version }
+          : {}),
+      };
+    }
+  }
+  return env;
+}
+
+export function buildCursorCloudConfig(values: CreateConfigValues): Record<string, unknown> {
+  const config: Record<string, unknown> = {
+    ...(values.adapterSchemaValues ?? {}),
+  };
+  if (values.instructionsFilePath) config.instructionsFilePath = values.instructionsFilePath;
+  if (values.promptTemplate) config.promptTemplate = values.promptTemplate;
+  if (values.bootstrapPrompt) config.bootstrapPromptTemplate = values.bootstrapPrompt;
+  if (values.model?.trim()) config.model = values.model.trim();
+
+  const env = parseEnvBindings(values.envBindings);
+  const legacy = parseEnvVars(values.envVars);
+  for (const [key, value] of Object.entries(legacy)) {
+    if (!Object.prototype.hasOwnProperty.call(env, key)) {
+      env[key] = { type: "plain", value };
+    }
+  }
+  if (Object.keys(env).length > 0) {
+    config.env = env;
+  }
+
+  return config;
+}

packages/adapters/cursor-cloud/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { buildCursorCloudConfig } from "./build-config.js";
+export { parseCursorCloudStdoutLine } from "./parse-stdout.js";

packages/adapters/cursor-cloud/src/ui/parse-stdout.test.ts

@@ -0,0 +1,143 @@
+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" }]);
+  });
+});

packages/adapters/cursor-cloud/src/ui/parse-stdout.ts

@@ -0,0 +1,186 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function stringifyUnknown(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return "";
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function parseAssistantMessage(message: Record<string, unknown>, ts: string): TranscriptEntry[] {
+  const content = Array.isArray(message.content) ? message.content : [];
+  const entries: TranscriptEntry[] = [];
+  for (const partRaw of content) {
+    const part = asRecord(partRaw);
+    if (!part) continue;
+    const type = asString(part.type).trim();
+    if (type === "text") {
+      const text = asString(part.text).trim();
+      if (text) entries.push({ kind: "assistant", ts, text });
+      continue;
+    }
+    if (type === "tool_use") {
+      entries.push({
+        kind: "tool_call",
+        ts,
+        name: asString(part.name, "tool"),
+        toolUseId: asString(part.id) || undefined,
+        input: part.input ?? {},
+      });
+    }
+  }
+  return entries;
+}
+
+function parseSdkMessage(messageRaw: unknown, ts: string): TranscriptEntry[] {
+  const message = asRecord(messageRaw);
+  if (!message) return [];
+  const type = asString(message.type);
+
+  if (type === "assistant") {
+    const body = asRecord(message.message);
+    return body ? parseAssistantMessage(body, ts) : [];
+  }
+
+  if (type === "user") {
+    const body = asRecord(message.message);
+    const content = Array.isArray(body?.content) ? body.content : [];
+    const text = content
+      .map((entry) => asRecord(entry))
+      .filter((entry): entry is Record<string, unknown> => Boolean(entry))
+      .map((entry) => asString(entry.text).trim())
+      .filter(Boolean)
+      .join("\n");
+    return text ? [{ kind: "user", ts, text }] : [];
+  }
+
+  if (type === "thinking") {
+    const text = asString(message.text).trim();
+    return text ? [{ kind: "thinking", ts, text }] : [];
+  }
+
+  if (type === "tool_call") {
+    const toolUseId = asString(message.call_id, asString(message.id, "tool_call"));
+    const status = asString(message.status).toLowerCase();
+    if (status === "running") {
+      return [{
+        kind: "tool_call",
+        ts,
+        name: asString(message.name, "tool"),
+        toolUseId,
+        input: message.args ?? {},
+      }];
+    }
+    if (status === "completed" || status === "error") {
+      return [{
+        kind: "tool_result",
+        ts,
+        toolUseId,
+        toolName: asString(message.name, "tool"),
+        content: stringifyUnknown(message.result ?? message.args ?? {}),
+        isError: status === "error",
+      }];
+    }
+    return [];
+  }
+
+  if (type === "tool_result") {
+    const toolUseId = asString(message.call_id, asString(message.id, "tool_result"));
+    const isError =
+      message.is_error === true ||
+      asString(message.status).toLowerCase() === "error";
+    return [{
+      kind: "tool_result",
+      ts,
+      toolUseId,
+      toolName: asString(message.name, "tool"),
+      content: stringifyUnknown(message.result ?? message.content ?? message.output ?? {}),
+      isError,
+    }];
+  }
+
+  if (type === "status") {
+    const status = asString(message.status);
+    const statusMessage = asString(message.message);
+    return [{
+      kind: "system",
+      ts,
+      text: `status: ${status}${statusMessage ? ` - ${statusMessage}` : ""}`,
+    }];
+  }
+
+  if (type === "task") {
+    const text = asString(message.text).trim();
+    return text ? [{ kind: "system", ts, text }] : [];
+  }
+
+  return [];
+}
+
+export function parseCursorCloudStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  const parsed = asRecord(safeJsonParse(line));
+  if (!parsed) {
+    return [{ kind: "stdout", ts, text: line }];
+  }
+
+  const type = asString(parsed.type);
+  if (type === "cursor_cloud.init") {
+    const sessionId = asString(parsed.sessionId, asString(parsed.agentId));
+    return [{
+      kind: "init",
+      ts,
+      model: asString(parsed.model, "cursor_cloud"),
+      sessionId,
+    }];
+  }
+
+  if (type === "cursor_cloud.status") {
+    return [{
+      kind: "system",
+      ts,
+      text: `${asString(parsed.status, "status")}${parsed.message ? `: ${asString(parsed.message)}` : ""}`,
+    }];
+  }
+
+  if (type === "cursor_cloud.message") {
+    return parseSdkMessage(parsed.message, ts);
+  }
+
+  if (type === "cursor_cloud.result") {
+    const status = asString(parsed.status, "error");
+    return [{
+      kind: "result",
+      ts,
+      text: asString(parsed.result),
+      inputTokens: 0,
+      outputTokens: 0,
+      cachedTokens: 0,
+      costUsd: 0,
+      subtype: status,
+      isError: status !== "finished",
+      errors: parsed.error ? [asString(parsed.error)] : [],
+    }];
+  }
+
+  return [{ kind: "stdout", ts, text: line }];
+}