docs: Cursor SDK harness gap analysis and implementation plan

[conradkoh]

Summary

Planning document for migrating chatroom from the Cursor CLI harness (agent -p) to @cursor/sdk durable agents. No implementation in this PR — documentation only.

Backlog: Cursor SDK based harness (multi-agent chatroom)

Related: Cursor SDK based direct harness

Release train: Targets release/v1.47.0 → master via #567

Document sections (docs/plans/cursor-sdk-harness-gap-analysis.md)

1. Cursor TypeScript SDK — Agent/Run/SDKMessage model, local vs cloud runtimes, Agent.create / send / stream / wait, Agent.resume, Agent.prompt, auth (CURSOR_API_KEY), errors, disposal
2. Harness inventory — (A) RemoteAgentService multi-agent daemon path (cursor, opencode, pi, copilot); (B) BoundHarness direct-harness path (opencode-sdk + Convex directHarness + webapp UI)
3. Gap analysis — CLI single-shot process-per-turn vs SDK durable agents; recommended cursor-sdk RemoteAgentService first, then optional BoundHarness wrapper
4. Backlog mapping — ties to ps78zy4r890k7tkxy4xwx6a9q187k79x and ps71e1zb1p8b313qsx0w57dv2187jp8s
5. Implementation phases — Foundation → session persistence → model discovery → direct harness → hardening (no code in this PR)

Test plan

• Documentation only — no runtime changes
• pnpm typecheck && pnpm test run before handoff

Made with Cursor

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
chatroom	Ready	Preview, Comment	May 28, 2026 5:55am

[conradkoh]

Closing as stale: the Cursor SDK harness shipped in #569 (merged to master via release v1.47.0). This planning-only doc PR on release/v1.47.0 is superseded by the implementation; the gap-analysis doc was never merged and is not on master.

If you still want the gap-analysis doc in-repo, we can reopen or cherry-pick docs/plans/cursor-sdk-harness-gap-analysis.md onto a fresh branch.