forked from farhoodlabs/paperclip
Devin Foley
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>
82 lines
2.8 KiB
JSON
82 lines
2.8 KiB
JSON
{
|
|
"name": "@paperclipai/ui",
|
|
"version": "0.3.1",
|
|
"description": "Prebuilt Paperclip board UI assets.",
|
|
"license": "MIT",
|
|
"homepage": "https://github.com/paperclipai/paperclip",
|
|
"bugs": {
|
|
"url": "https://github.com/paperclipai/paperclip/issues"
|
|
},
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "https://github.com/paperclipai/paperclip",
|
|
"directory": "ui"
|
|
},
|
|
"type": "module",
|
|
"scripts": {
|
|
"dev": "vite",
|
|
"build": "tsc -b && vite build",
|
|
"storybook": "storybook dev -p 6006 -c storybook/.storybook",
|
|
"build-storybook": "storybook build -c storybook/.storybook -o storybook-static",
|
|
"preview": "vite preview",
|
|
"typecheck": "tsc -b",
|
|
"clean": "rm -rf dist storybook-static tsconfig.tsbuildinfo",
|
|
"prepack": "rm -f package.dev.json && cp package.json package.dev.json && node ../scripts/generate-ui-package-json.mjs",
|
|
"postpack": "if [ -f package.dev.json ]; then mv package.dev.json package.json; fi"
|
|
},
|
|
"publishConfig": {
|
|
"access": "public"
|
|
},
|
|
"dependencies": {
|
|
"@assistant-ui/react": "0.12.23",
|
|
"@dnd-kit/core": "^6.3.1",
|
|
"@dnd-kit/sortable": "^10.0.0",
|
|
"@dnd-kit/utilities": "^3.2.2",
|
|
"@lexical/link": "0.35.0",
|
|
"@mdxeditor/editor": "^3.52.4",
|
|
"@paperclipai/adapter-acpx-local": "workspace:*",
|
|
"@paperclipai/adapter-claude-local": "workspace:*",
|
|
"@paperclipai/adapter-codex-local": "workspace:*",
|
|
"@paperclipai/adapter-cursor-cloud": "workspace:*",
|
|
"@paperclipai/adapter-cursor-local": "workspace:*",
|
|
"@paperclipai/adapter-gemini-local": "workspace:*",
|
|
"@paperclipai/adapter-openclaw-gateway": "workspace:*",
|
|
"@paperclipai/adapter-opencode-local": "workspace:*",
|
|
"@paperclipai/adapter-pi-local": "workspace:*",
|
|
"@paperclipai/adapter-utils": "workspace:*",
|
|
"@paperclipai/shared": "workspace:*",
|
|
"@radix-ui/react-slot": "^1.2.4",
|
|
"@tailwindcss/typography": "^0.5.19",
|
|
"@tanstack/react-query": "^5.90.21",
|
|
"class-variance-authority": "^0.7.1",
|
|
"clsx": "^2.1.1",
|
|
"cmdk": "^1.1.1",
|
|
"hermes-paperclip-adapter": "^0.2.0",
|
|
"lexical": "0.35.0",
|
|
"lucide-react": "^0.574.0",
|
|
"mermaid": "^11.12.0",
|
|
"radix-ui": "^1.4.3",
|
|
"react": "^19.0.0",
|
|
"react-dom": "^19.0.0",
|
|
"react-markdown": "^10.1.0",
|
|
"react-router-dom": "^7.1.5",
|
|
"remark-gfm": "^4.0.1",
|
|
"tailwind-merge": "^3.4.1"
|
|
},
|
|
"devDependencies": {
|
|
"@tailwindcss/vite": "^4.0.7",
|
|
"@storybook/addon-a11y": "10.3.5",
|
|
"@storybook/addon-docs": "10.3.5",
|
|
"@storybook/react-vite": "10.3.5",
|
|
"@types/node": "^25.2.3",
|
|
"@types/react": "^19.0.8",
|
|
"@types/react-dom": "^19.0.3",
|
|
"@vitejs/plugin-react": "^4.3.4",
|
|
"tailwindcss": "^4.0.7",
|
|
"typescript": "^5.7.3",
|
|
"storybook": "10.3.5",
|
|
"vite": "^6.1.0",
|
|
"vitest": "^3.0.5"
|
|
}
|
|
}
|