OpenHands / OpenHands/software-agent-sdk
[Feature]: Add Cursor CLI as a built-in ACP provider (agent acp)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 539
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
Goal
Register Cursor's official ACP server (agent acp) as a built-in provider with the same registry / settings / TS-mirror surface as claude-code, codex, gemini-cli, kimi-code, pi, and opencode.
This is the binary-distribution counterpart of the npm harnesses tracked in #4820. Cursor is not on npm — the CLI is a first-party curl/PowerShell install (https://cursor.com/install) whose entry point is agent (symlink to cursor-agent). There is no download-on-demand path, so this must stay registry-only (not in DEFAULT_PREINSTALLED_ACP_PROVIDERS / the default image).
Why this is not Antigravity (#4624)
#4823 (install_method) was closed as a watch item because Antigravity is a 650 MiB archive with no on-demand install. Cursor is the opposite shape:
- user-preinstalled binary already on
PATH - launch command is just
agent acp - adding it to the registry does not grow the image
_prefer_pinned_binaryalready no-ops for a non-npxcommand
So the catalog needs a third flavour (preinstalled binary) that render_docker_install_plan rejects, not a runtime fetcher.
Desired Behavior
Selecting acp_server="cursor" resolves to ["agent", "acp"], exposes CURSOR_API_KEY / CURSOR_API_ENDPOINT, and advertises a curated Auto-first model list. The provider is selectable in settings but is not baked into the default agent-server image.
Acceptance Criteria
-
ACP_PROVIDERSandACPServerKindincludecursor - Catalog entry is
ACPPreinstalledBinaryInstallSpecwithlaunch_command() == ("agent", "acp") -
render_docker_install_plan(["cursor"])raises;DEFAULT_PREINSTALLED_ACP_PROVIDERSis unchanged - TypeScript mirror (
acp-providers.json) matches the Python registry - Unit tests cover metadata, command detection, and settings resolution
Live verification (Cursor CLI 2026.09.02-c22c1a3)
Handshake against agent acp:
| Call | Result |
|---|---|
initialize |
protocolVersion 1; auth method cursor_login only; no agentInfo.name |
authenticate(cursor_login) |
{} after agent login |
session/new |
modes agent / plan / ask; models.currentModelId = default[] (Auto); 36 availableModels; configOptions includes mode + model |
session/set_mode |
accepts agent and ask |
session/set_model |
accepts composer-2.5[fast=true] |
session/set_config_option(model=…) |
succeeds (session advertises a model select) |
Env vars the CLI documents: CURSOR_API_KEY, CURSOR_API_ENDPOINT. Login state lives under ~/.cursor; there is no dedicated config-dir var that relocates sessions without dropping the login, so data_dir_env_var should be None.
Parity contract (#4820)
| Field | Proposed value | Evidence |
|---|---|---|
key / display_name |
cursor / Cursor |
new discriminator |
default_command |
("agent", "acp") |
official ACP entry |
binary_name |
agent |
installer PATH name |
api_key_env_var |
CURSOR_API_KEY |
CLI --api-key |
base_url_env_var |
CURSOR_API_ENDPOINT |
CLI --endpoint |
data_dir_env_var |
None |
no session-only override; HOME would unauthenticate |
default_session_mode |
agent |
tool-executing default; no permission-bypass mode |
agent_name_patterns |
("cursor-agent", "agent") |
command-time detection; initialize omits agentInfo.name |
supports_set_session_model |
True |
live set_model / set_config_option |
supports_runtime_model_switch |
True |
same |
session_meta_key |
None |
unused |
default_model |
default[] |
Auto router (currentModelId) |
available_models |
curated Auto + stable subset of ACP ids | ACP ids ≠ --list-models names |
file_secrets |
none | login / CURSOR_API_KEY, not a pasteable file |
Out of scope
- Baking Cursor into the default agent-server image
- A runtime downloader for the Cursor binary (reopen #4823 if that becomes necessary)
- Agent Canvas branding / onboarding copy (downstream of this registry; see #4833 / #4841)
Related
- #4820 (ACP harness parity)
- #4823 (closed watch item —
install_method) - #4624 (Antigravity deferred for image-size reasons)
- https://cursor.com/docs/cli/acp
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ACP_PROVIDERS, ACPServerKind, DEFAULT_PREINSTALLED_ACP_PROVIDERS, and render_docker_install_plan, then compare the existing providers named in the issue. Update the Python registry and acp-providers.json mirror, add unit coverage for metadata, command detection, and settings resolution, and verify Cursor resolves to agent acp while remaining registry-only.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, typescript
- Domain
- backend, devtools
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 70/100