Migrate Cursor integration from `agent -p` stream-json mode to Cursor ACP mode

[swear01]

What feature would you like to see?

HAPI currently integrates Cursor Agent CLI remote mode through agent -p --output-format stream-json --trust. This works for basic streaming/tool activity, but it misses richer client-side interaction support.

Cursor CLI now supports ACP via agent acp, and HAPI should migrate the Cursor integration to ACP mode for a more complete remote-control experience.

Expected Cursor ACP support in HAPI:

• Use agent acp instead of agent -p --output-format stream-json --trust for remote Cursor sessions.
• Handle ACP session/request_permission so HAPI web/mobile can show approve/deny UI.
  • approve once
  • approve for session / allow always
  • reject once
  • cancel/abort
• Preserve Cursor session resume/load behavior through ACP if supported.
• Render ACP session/update events:
  • assistant/user message chunks
  • tool calls / tool call updates
  • plan updates
  • mode changes
  • available commands
• Support Cursor ACP extension methods:
  • cursor/ask_question
  • cursor/create_plan
  • cursor/update_todos
  • cursor/task
  • cursor/generate_image
• Support Cursor modes via ACP:
  • agent/default
  • plan
  • ask
• Support Cursor model selection through ACP where possible:
  • session/set_model
  • session configOptions
• Keep MCP server wiring compatible with HAPI’s existing happy MCP bridge.
• Prefer reusing HAPI’s existing ACP infrastructure:
  • AcpSdkBackend
  • PermissionAdapter
  • existing web permission cards
  • existing ACP message conversion path used by Gemini/OpenCode/Kimi

This would make Cursor behave more like the other ACP-backed agents in HAPI and avoid the limitations of current headless agent -p mode.

Additional information

Related Cursor issues already filed in HAPI:

• Cursor plan mode: plan items not rendered in web UI (ACP plan message type unhandled) #687 — Cursor plan mode: plan items not rendered in web UI
• fix(web/cli): Cursor model catalog — Composer 2.5 hard to find or absent in picker #705 — Cursor model catalog / model picker issue

Those issues are narrower bugs. This issue proposes the broader integration migration: move Cursor remote mode to ACP so permission approval, plan approval, questions, todos, model/mode changes, and richer tool updates can be handled through one protocol.

Current limitation in docs/guide/cursor.md says remote Cursor mode uses agent -p and --trust, so tools run without per-request approval. ACP should let HAPI remove that limitation.

[github-actions]

Verified against the current codebase: this is a real migration request, not already implemented for Cursor remote mode.

Current Cursor remote mode still launches one agent -p process per queued message with --output-format stream-json and --trust. Generic ACP infrastructure already exists and covers several pieces this issue asks for, including session/request_permission, ACP session/update conversion, session/load, session/set_model, and session/set_config_option; however I did not find a Cursor ACP backend/launcher using agent acp, and I did not find handlers for the Cursor-specific ACP extension methods (cursor/ask_question, cursor/create_plan, cursor/update_todos, cursor/task, cursor/generate_image).

So the likely implementation area is replacing or augmenting the Cursor remote launcher with an ACP-backed path, while preserving Cursor-specific resume/mode/model behavior.

Relevant code:

• docs/guide/cursor.md:43 - documents local vs remote Cursor mode; remote is described as agent -p stream-json with --trust.
• cli/src/cursor/cursorRemoteLauncher.ts:26 - builds current remote args: -p, --output-format stream-json, --trust, --workspace.
• cli/src/cursor/cursorRemoteLauncher.ts:138 - runs the spawned Cursor process and converts stream-json events.
• cli/src/cursor/cursorRemoteLauncher.ts:139 - captures Cursor session_id from stream-json init events for resume continuity.
• cli/src/cursor/runCursor.ts:109 - Cursor session config RPC currently applies permission mode/model state separately from ACP.
• cli/src/agent/backends/acp/AcpSdkBackend.ts:94 - generic ACP stdio backend setup.
• cli/src/agent/backends/acp/AcpSdkBackend.ts:110 - generic ACP session/request_permission handler registration.
• cli/src/agent/backends/acp/AcpSdkBackend.ts:169 - generic ACP session/load support.
• cli/src/agent/backends/acp/AcpSdkBackend.ts:195 - generic ACP session/set_model support.
• cli/src/agent/backends/acp/AcpSdkBackend.ts:232 - generic ACP session/set_config_option support.
• cli/src/agent/backends/acp/AcpSdkBackend.ts:264 - generic ACP session/prompt and session/update message path.
• cli/src/agent/permissionAdapter.ts:150 - maps web permission decisions to ACP outcomes, including approve once, approve for session, reject, and abort/cancel.
• shared/src/modes.ts:32 - Cursor modes currently exposed by HAPI: default, plan, ask, yolo.

---

HAPI Bot

[heavygee]

+1 on the ACP migration approach. The current agent -p --output-format stream-json --trust path is exactly why Cursor sessions in HAPI feel thinner than Claude - no tool-call detail, no plan items, no permission UI, no mode hints. ACP fixes all of that in one architectural move and aligns Cursor with the Claude rendering surface that already works.

The full migration is rightly the larger campaign - multiple PRs across cli/src/cursor/, ACP method handlers, the web normalizer, the permission UI, and the Cursor extension methods (cursor/ask_question, cursor/create_plan, cursor/update_todos, cursor/task, cursor/generate_image).

To keep momentum without stepping on this work, I'm going to take #687 separately: the narrow gap in web/src/lib/normalizeAgent.ts:719 where ACP sessionUpdate { type: "plan" } is dropped because only plan_update (the Codex variant) is handled. That's small, isolated to the web normalizer, doesn't touch your CLI migration surface, and gives Cursor plan mode a place to render today on the existing ACP code path. Happy to rebase or close if it conflicts with where you take this. Will reference this thread from the PR.

[swear01]

Thanks @heavygee — fully agree on moving Cursor remote off stream-json to ACP.

Re #687: this is already covered in #799 (web/src/chat/normalizeAgent.ts handles ACP data.type === 'plan' in addition to plan_update; PR body has Fixes #687). Plan checklist UI on the ACP path ships with the #781 migration on that track.

If you still want to land a narrow #687-only PR on main before #799 merges, that’s fine from a scope perspective (web-only, no CLI overlap) — but #799 is the priority track for this area. I’d prefer we don’t duplicate the same normalizer change in parallel. Options:

1. Wait for / help review feat(cursor): migrate remote sessions to ACP with model/variant pickers #799 (includes Cursor plan mode: plan items not rendered in web UI (ACP plan message type unhandled) #687 + full ACP migration), or
2. Open Cursor plan mode: plan items not rendered in web UI (ACP plan message type unhandled) #687 first and I’ll rebase feat(cursor): migrate remote sessions to ACP with model/variant pickers #799 on top after it lands (small surface in normalizeAgent.ts only).

Either way I’ll reference this thread from #799. Let me know which you prefer.

[heavygee]

Thanks @swear01 - that's exactly the right call. We weren't aware #799 already covered the #687 normalizer change; standing down on our narrow PR per Option 1.

Spinning down the peer worktree and standing by to help review #799 when you're ready for eyes on it. The disjoint piece we already shipped (PR #801, intercept of fabricated Questions skipped by the user results in headless stream-json mode for #784) is deliberately scoped to cli/src/cursor/utils/cursorEventConverter.ts only - it does not touch cursorRemoteLauncher.ts, ACP code, the web normalizer, or the permission UI, so it should auto-delete cleanly when #799 lands and the stream-json launcher is replaced. If that complicates your migration I'm happy to close #801 too; just say the word.