feat(cursor): add support for Cursor Agent CLI integration

[hairyf]

Closes #207

Summary

Add cursor-cli support to HAPI. Cursor CLI usage is similar to claude code, gemini, codex - this PR enables \hapi cursor\ to run Cursor Agent with remote control via web/phone.

Changes

• Add \cursor\ to AgentFlavor in shared/modes
• Add \cursor\ CLI subcommand and cursor runner (mirroring codex structure)
• Update agentFlavorUtils for cursor
• Update docs and help text

[github-actions]

[MAJOR] Bug: internal flag forwarded to Cursor CLI

Why this is a problem: runner appends --hapi-starting-mode remote for spawned sessions, but the cursor command does not consume it. That flag is then forwarded to agent via cursorArgs, and Cursor CLI does not define it, so runner-spawned cursor sessions can fail to start.

Suggested fix:

} else if (arg === '--hapi-starting-mode') {
    const value = commandArgs[++i]
    if (value !== 'local' && value !== 'remote') {
        throw new Error('Invalid --hapi-starting-mode (expected local or remote)')
    }
    // consume only; do not forward to cursorArgs
    continue
}

[github-actions]

[MAJOR] Bug: web spawn offers Cursor while remote mode exits immediately

Why this is a problem: web new-session flow is remote-start, but the Cursor remote launcher exits immediately with a "not supported" message. Exposing Cursor in the web selector creates a broken flow where newly spawned sessions terminate right away.

Suggested fix:

{(['claude', 'codex', 'gemini', 'opencode'] as const).map((agentType) => (

[github-actions]

Findings

• [Major] Internal runner flag forwarded to Cursor CLI — runner adds --hapi-starting-mode, cursor command forwards unknown args to agent; likely startup failure for runner-spawned sessions. Evidence cli/src/commands/cursor.ts:24-75, cli/src/runner/run.ts:345.
  Suggested fix:

  } else if (arg === '--hapi-starting-mode') {
      const value = commandArgs[++i]
      if (value !== 'local' && value !== 'remote') {
          throw new Error('Invalid --hapi-starting-mode (expected local or remote)')
      }
      // consume only; do not forward to cursorArgs
      continue
  }

• [Major] Web spawn offers Cursor while remote mode exits immediately — Cursor remote launcher always exits; exposing Cursor in web selector creates broken remote-start flow. Evidence web/src/components/NewSession/AgentSelector.tsx:16-33, cli/src/cursor/cursorRemoteLauncher.ts:26-43, cli/src/runner/run.ts:345.
  Suggested fix:

  {(['claude', 'codex', 'gemini', 'opencode'] as const).map((agentType) => (

Summary

• 2 major issues; runner-spawned cursor sessions can fail; web spawn path broken for cursor.

Testing

• Not run (automation)

HAPI Bot

[hairyf]

Reply to review

Thanks for the review. Addressed both issues in 602a9c1:

1. --hapi-starting-mode forwarded to Cursor CLI

Fixed. The cursor command now consumes --hapi-starting-mode and its value (local/remote) without forwarding to the agent CLI. See cli/src/commands/cursor.ts.

2. Web spawn offers Cursor while remote mode exits immediately

Fixed. Implemented full Cursor remote mode:

• cursorRemoteLauncher now spawns agent -p "message" --output-format stream-json --trust
• Parses NDJSON from stdout (system/init, assistant, tool_call, result)
• Multi-turn via --resume <session_id>
• Cursor in the web selector now works for remote spawn

Cursor Agent CLI supports --print + --output-format stream-json for programmatic use (per Cursor docs).

[tiann]

@tiann review again

[github-actions]

Findings

1. Cursor model mode UI shown for cursor sessions; HappyComposer uses !isCodexFamilyFlavor so cursor gets Claude model toggle/shortcut and modelMode updates even though cursor has no model modes. web/src/components/AssistantChat/HappyComposer.tsx:325-401, web/src/lib/agentFlavorUtils.ts:1-3.
2. Cursor local resume never updates metadata/sessionId; cursorLocalLauncher does not pass onChatFound, so session.onSessionFound not called and cursorSessionId stays unset. Remote switch can’t resume same chat. cli/src/cursor/cursorLocalLauncher.ts:30-38, cli/src/cursor/cursorLocal.ts:23-38.
3. Duplicate cursor CLI flags in local mode: cursorCommand forwards --resume/--mode/--model/--yolo into cursorArgs, then cursorLocal adds them again, so agent gets duplicates. cli/src/commands/cursor.ts:37-63, cli/src/cursor/cursorLocal.ts:35-55.

Tests

• not run (review only)

---

HAPI Bot