forked from farhoodlabs/paperclip
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>
187 lines
5.1 KiB
TypeScript
187 lines
5.1 KiB
TypeScript
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 }];
|
|
}
|