feat: add Cursor Agent CLI support

[brettchien]

What problem does this solve?

OpenAB supports several ACP-compatible coding CLIs (Kiro, Claude Code, Codex, Gemini, Copilot) but not Cursor Agent CLI. Cursor ships native ACP support (cursor-agent acp) and access to 80+ models (Claude, GPT-5, Gemini 3, Grok 4, Kimi K2, Composer, auto) behind one subscription, which is strictly additive for users who already pay for Cursor.

Ref #18

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1493798720142180473

At a Glance

Discord mention
      │
      ▼
openab (Rust) ── spawn("cursor-agent", ["acp", "--model", "auto"])
      │
      ▼
cursor-agent acp                    ← native ACP, stdio JSON-RPC
      │
      ├─ initialize                 → agentCapabilities: { loadSession: true }
      ├─ session/new                → sessionId
      └─ session/prompt             → session/update stream → stopReason: end_turn

No changes to src/ — this is a configuration-only integration.

Prior Art & Industry Research

OpenClaw (openclaw/openclaw) — personal AI assistant gateway across 20+ messaging platforms. Coding‑CLI story is explicitly ACP‑based: a bundled acpx runtime plugin drives harnesses via /acp spawn <agentId> and sessions_spawn({ runtime: "acp" }) (docs/tools/acp-agents.md).

• Cursor support: Yes — Cursor is a listed ACP target alongside Codex, Claude Code, Gemini, Copilot under the shared acpx runtime.
• Abstraction: ACP is primary (src/acp/*, extensions/acpx/); a separate text-only "CLI Backends" path exists as fallback but is not ACP.
• Pluggability: Unified — any acpx-registered harness is swappable by agentId.
• Known Cursor pain: Cursor ACP via gateway: 'queue owner unavailable' — works from CLI, fails through gateway plugin openclaw/openclaw#56463 (cursor-agent acp works from CLI but dies via gateway — "queue owner unavailable"), [Bug]: ACP server rejects MCP protocolVersion: 2025-11-25 from VS Code 1.113 / Cursor openclaw/openclaw#56102 (MCP protocolVersion: 2025-11-25 rejection from VS Code/Cursor).

Hermes Agent (NousResearch/hermes-agent) — Nous Research's self-hosted agent across Telegram/Discord/Slack/WhatsApp/Signal/Email + CLI. Uses ACP in the opposite direction from openab: runs as an ACP server for editors via hermes acp (docs/acp-setup.md).

• Cursor CLI as backend: No. Only in-tree ACP client is Copilot-specific (agent/copilot_acp_client.py). Generalizing it is still an open proposal — feat: Generalized ACP client for multi-agent CLI orchestration NousResearch/hermes-agent#5257 (open, unmerged) and Feature: Agent Migration System — Auto-Detect & Import Settings from Claude Code, Codex, Gemini CLI, Cursor, Aider, Roo Code & Others on First Install NousResearch/hermes-agent#524 (Cursor config import, also open).
• Abstraction: LLM-provider-centric (hermes_cli/providers.py); coding CLIs are not first-class backends.
• Pluggability: No runtime-swap story for CLI harnesses yet.

Takeaway: OpenClaw ships the closest analog but through a heavier acpx router (and the Cursor path has known gateway bugs). Hermes doesn't do this at all yet. OpenAB's existing direct spawn(cli, ["acp"]) → stdio JSON-RPC pattern is already well-aligned; this PR just adds Cursor as one more entry in the same pluggable model.

Proposed Solution

Add Cursor as a first-class agent backend alongside the existing five, without touching src/:

File	Change	Description
Dockerfile.cursor	NEW	Multi-stage: rust:1-bookworm builder + debian:bookworm-slim runtime; pinned tarball from downloads.cursor.com; agent user (uid 1000)
docs/cursor.md	NEW	Setup guide: architecture, config, Docker, auth, Helm, model selection, limitations
config.toml.example	MOD	Commented cursor-agent [agent] block
README.md	MOD	Cursor row in the agent backends table
.github/workflows/build.yml	MOD	-cursor variant in all 3 CI matrix sections
RELEASING.md	MOD	cursor (and missing copilot) in image variants, count 4 → 6
charts/openab/values.yaml	MOD	Commented cursor example block
charts/openab/templates/NOTES.txt	MOD	cursor-agent login auth instructions

Why This Approach

Native ACP over adapter. cursor-agent acp speaks ACP directly over stdio JSON-RPC. Our existing src/acp/connection.rs already sends protocolVersion: 1 as an integer, which matches the Cursor response verbatim — no shim required. Verified against cursor-agent v2026.04.08-a41fba1:

→ initialize  { protocolVersion: 1, clientInfo: { name: "test", version: "0.1" } }
← { protocolVersion: 1,
    agentCapabilities: { loadSession: true,
      mcpCapabilities: { http: true, sse: true },
      promptCapabilities: { audio: false, embeddedContext: false, image: true } },
    authMethods: [{ id: "cursor_login", name: "Cursor Login" }] }

debian:bookworm-slim base, not node:22. The Cursor tarball is self-contained — it bundles its own node binary and JS chunks. A Node base image would add ~170 MB of runtime we'd never use.

Pinned tarball, not npm/npx. Cursor Agent CLI is not published on npm; the canonical distribution is downloads.cursor.com/lab/{version}/linux/{arch}/agent-cli-package.tar.gz. ARG CURSOR_VERSION=2026.04.08-a41fba1 pins the version for reproducible builds.

Tradeoffs: (1) Cursor Agent CLI requires interactive cursor-agent login for auth — same story as kiro-cli; PVC persistence required. (2) Cursor is a separate distribution from Cursor Desktop; version upgrades happen on Cursor's cadence, not ours.

Alternatives Considered

Alternative	Rejected because
node:22 base image + npm install -g	Cursor isn't published on npm; node:22 adds ~170 MB of runtime the self-contained tarball doesn't need
Third-party ACP adapter (like codex-acp pattern)	Cursor ships native ACP — adding an adapter would be strict regression in surface area and latency
cursor-agent exec (non-interactive mode)	Loses ACP session persistence, streaming, and tool-call plumbing that openab already relies on
Bundling Cursor into the default Dockerfile	Would force all users to pull Cursor even if they use Kiro/Claude/Codex; separate Dockerfile.cursor keeps the default image lean

Validation

• cargo check passes (no src/ changes, but verified clean — 45.09s cold)
• cargo test passes — 34 passed, 0 failed (ran locally on this branch)
• Docker build: docker build -f Dockerfile.cursor -t openab-cursor:local . succeeds
• K8s deploy: Helm install with agents.cursor values on OrbStack + hostPath auth mount
• ACP handshake: JSON-RPC initialize round-trip verified against cursor-agent v2026.04.08-a41fba1 (see response above)
• End-to-end: Octocat bot mentioned in Discord, spawned cursor-agent acp --model auto, streamed reply back to thread ✅
• CI matrix (.github/workflows/build.yml) will run on merge — local act run not attempted

Manual test steps (reproducible):

# 1. Build
docker build -f Dockerfile.cursor -t openab-cursor:local .

# 2. Deploy (OrbStack k8s)
helm upgrade --install openab openab/openab -n openab --create-namespace \
  --set agents.cursor.enabled=true \
  --set agents.cursor.image=openab-cursor:local \
  --set agents.cursor.command=cursor-agent \
  --set 'agents.cursor.args={acp,--model,auto}' \
  --set agents.cursor.discord.botToken=$TOKEN

# 3. Auth (one-time, device flow)
kubectl exec -it deployment/openab-cursor -n openab -- cursor-agent login
kubectl rollout restart deployment/openab-cursor -n openab

# 4. Test
#    In Discord: @Octocat who are you?
#    → thread opens, streams reply from Cursor agent

[masami-agent]

Review — PR #301

Excellent work, @brettchien. This is a well-researched, config-only integration with thorough documentation and end-to-end validation. The prior art analysis (OpenClaw, Hermes) and the live ACP handshake verification are particularly valuable.

✅ What looks good

1. Zero src/ changes — pure configuration integration, lowest risk
2. Dockerfile.cursor — correct pattern: debian:bookworm-slim base (not node), pinned tarball, agent user (uid 1000), pgrep healthcheck
3. CI matrix — all 3 sections updated consistently (build, merge-manifests, chart-version)
4. docs/cursor.md — comprehensive: architecture, config, Docker, auth, Helm, model selection, limitations
5. RELEASING.md — updated image count 4 → 6 (also adds missing copilot entry)
6. ACP handshake verified — protocolVersion: 1 integer match confirmed against cursor-agent v2026.04.08-a41fba1

🔴 Must fix before merge

1. values.yaml cursor example has wrong workingDir

#   workingDir: /home/node

Cursor uses debian:bookworm-slim (not node:22), so the user is agent with home at /home/agent. This should be:

#   workingDir: /home/agent

The config.toml.example and docs/cursor.md correctly use /home/agent — just values.yaml is inconsistent.

2. Dockerfile.cursor missing procps

The healthcheck uses pgrep -x openab, but procps is not installed. Same issue as #232 / PR #234. Add procps to the apt-get install line:

RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl procps && rm -rf /var/lib/apt/lists/*

🟡 Non-blocking

3. Cursor tarball URL stability

downloads.cursor.com/lab/${CURSOR_VERSION}/linux/${ARCH}/agent-cli-package.tar.gz — is this URL documented/stable, or could it change without notice? If Cursor changes their distribution path, the Dockerfile breaks silently. A comment in the Dockerfile noting the source would help future maintainers.

4. --model auto not in default args

config.toml.example uses args = ["acp"] without --model. The docs mention --model auto as an option. Consider whether the default should include --model auto for consistency with the Helm example in the PR description.

5. RELEASING.md copilot addition

Adding the missing openab-copilot line is correct but technically out of scope for this PR. Not blocking — just noting it's a bonus fix.

📝 Summary

Priority	Item	Status
🔴	values.yaml workingDir should be /home/agent	Needs fix
🔴	Dockerfile.cursor missing procps for healthcheck	Needs fix
🟡	Tarball URL stability comment	Non-blocking
🟡	Default --model auto consideration	Non-blocking
🟡	RELEASING.md copilot bonus fix	Non-blocking

Two small fixes and this is ready to approve. Great contribution!

[brettchien]

@masami-agent Thanks for the thorough review! Addressed all 5 items below.

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1493798720142180473

🔴 Must-fix (both addressed)

1. values.yaml cursor example workingDir — 38628bf

Changed /home/node → /home/agent. Cursor uses debian:bookworm-slim with a self-created agent user (uid 1000), not the node user baked into node:22-bookworm-slim.

2. Dockerfile.cursor missing procps — 654b743

Added procps to the runtime apt install so pgrep -x openab in the HEALTHCHECK actually resolves. Same fix pattern as pending #234 for the other Dockerfiles — scoped here to Dockerfile.cursor only.

🟡 Non-blocking (items 3 & 4 done, item 5 already in PR)

3. Cursor tarball URL stability comment — eeb122e

Added a 4-line comment above the ARG CURSOR_VERSION pointing maintainers at the URL pattern and Cursor's official downloads page. If the URL scheme changes, the build fails with a curl 404 at build time so the failure is obvious.

4. Default --model auto in example args — 20fcd10, 146a2f2

• config.toml.example: args = ["acp"] → args = ["acp", "--model", "auto", "--workspace", "/home/agent"]
• charts/openab/values.yaml cursor example: added matching --model auto + --workspace /home/agent

Aligned with docs/cursor.md and the Helm example in the PR body.

5. RELEASING.md copilot

Already in the PR (line 150 ghcr.io/openabdev/openab-copilot # copilot + 6 multi-arch image count). Keeping as a bonus fix — happy to split out if strictly preferred.

🆕 Bonus — MCP usage documentation — 2a1167f

Added a "MCP Usage (ACP mode caveats)" section to docs/cursor.md covering:

• How --workspace anchors both .cursor/mcp.json lookup and the mcp-approvals.json slug
• --approve-mcps is a no-op in ACP mode (interactive CLI only) — confirmed against cursor-agent v2026.04.08-a41fba1 and the Cursor community forum
• Two ways to approve MCP servers (pre-create file / interactive approve + persist)
• How openab's session/request_permission auto-reply (allow_always in src/acp/connection.rs) interacts with the approval file
• How to verify with cursor-agent mcp list

Commits in this update

2a1167f docs(cursor): add MCP usage and --workspace / approval quirks
146a2f2 docs(config): align cursor example args with runtime defaults
20fcd10 docs(config): add --model auto to cursor example args
eeb122e docs(docker): document Cursor tarball URL source in Dockerfile.cursor
654b743 fix(docker): add procps to Dockerfile.cursor for pgrep healthcheck
38628bf fix(chart): cursor example workingDir /home/node → /home/agent

Verified locally: cursor-agent in pod reports playwright: ready, ACP handshake still passes, CI is green on the latest push.

[masami-agent]

Re-review — PR #301

All 5 items from my initial review have been addressed. Verified the latest diff:

✅ Must-fix (resolved)

1. values.yaml workingDir — /home/node → /home/agent ✓
2. Dockerfile.cursor procps — added to runtime apt install ✓

✅ Non-blocking (resolved)

3. Tarball URL stability comment — clear 4-line comment above ARG CURSOR_VERSION ✓
4. Default --model auto — aligned across config.toml.example, values.yaml, and docs/cursor.md ✓
5. RELEASING.md copilot line — already present, image count updated to 6 ✓

✅ Bonus: MCP documentation

The new "MCP Usage (ACP mode caveats)" section in docs/cursor.md is thorough and well-researched — covers --workspace anchoring, --approve-mcps no-op in ACP mode, approval file mechanics, and interaction with openab allow_always. This is genuinely useful for anyone deploying Cursor with MCP servers.

Code quality

• Dockerfile follows the established multi-stage pattern
• CI matrix additions are consistent with existing variants
• Helm values example is properly commented out
• Documentation is clear and complete

LGTM. Approving as agent reviewer.