feat(cli): wire Cursor /summarize for hub-driven context compaction

[heavygee]

Summary

Cursor has context summarization (/summarize, auto-summarize near window limit) in the product, but HAPI does not route slash/special commands for the Cursor agent flavor. Peer relocate and post-fork parent compaction depend on queuing /summarize (or equivalent) through the hub message path — today that only works reliably for Claude (/compact) and Codex.

Gap: integration, not missing Cursor capability. See fork dogfood: docs/plans/peer-relocate-dogfood-1.md and peer-agent spec §4.4.1.

Current behavior

• shared/src/slashCommands.ts: BUILTIN_SLASH_COMMANDS.cursor is [] (empty).
• cli/src/cursor/cursorRemoteLauncher.ts: hub messages go to agent -p … --resume … with no parseSpecialCommand handling (unlike cli/src/claude/runClaude.ts + claudeRemote.ts).
• Web may list slash commands from session metadata, but Cursor builtins are not seeded.

Desired behavior

1. Builtin slash list for cursor — at minimum: summarize (and document whether IDE /summarize works headless via -p).
2. parseSpecialCommand parity in cursorRemoteLauncher (or shared remote path):
   • /summarize → trigger Cursor context summarization with optional trailing instructions (peer relocate compact prompt).
   • Consider /clear if supported by Cursor CLI.
3. Hub spawn-peer parentContext — when parentContext.policy=compact and flavor is cursor, queue /summarize … and observe token-count / usage drop (target 40% utilization per product spec).
4. Tests — unit tests for command parsing; optional integration note in cursorRemoteLauncher tests.

Related

• Peer agent offering (fork plan): relocate + parent compact
• Cursor CLI support #571 Cursor CLI support (merged)
• feat(cursor): support model selection #684 Cursor model selection (merged)
• Cursor plan mode: plan items not rendered in web UI (ACP plan message type unhandled) #687 Cursor plan mode UI (open, different scope)
• Dogfood parent session used raw /summarize message — unverified on runner

Acceptance criteria

• getBuiltinSlashCommands('cursor') includes summarize with accurate description.
• User/hub message /summarize … on a Cursor session is handled intentionally (not passed as opaque prompt only — or documented if opaque pass-through is sufficient and verified).
• Peer relocate dogfood can set parentCompact.reachedTarget on Cursor after summarize (measure via existing token-count events).
• No regression to normal Cursor message delivery.

Investigation notes for implementer

• Verify Cursor headless CLI: does -p "/summarize" or -p "/summarize <instructions>" invoke the same summarization as IDE?
• Forum reports: /summarize exists; quality varies; may compress ~190k → ~1k tokens.
• If slash pass-through works without parser, document and add tests; else wire explicit branch like Claude /compact.

[heavygee]

Peer agent spawned (operator dogfood)

HAPI session: peer feature session 309ebaf8-c19c-4cc4-83eb-698f50c948d9 (Cursor /summarize work — see issue body)
Parent (peer-agent spec): parent orchestrator session 8d4f8729-90b2-438c-9b01-63c1e9037a7e

Preflight: No existing upstream issue/PR found for Cursor /summarize HAPI wiring (searched cursor summarize, slash, compact). This issue filed from peer-relocate dogfood §4.4.1.

Peer mandate: Assess code paths, search PRs, comment findings here, then minimal PR if none exists.

Related: #737 (mermaid — different peer), peer-agent relocate spec (fork).

[heavygee]

Peer assessment (slash / summarize wiring)

PR search (gh search prs on tiann/hapi): no open or merged PR for Cursor /summarize, parseSpecialCommand + cursor, or cursor slash builtins. Hits were unrelated (#603 model slash, #567 chat polish). Related merged: #236 Cursor CLI integration, #684 model selection.

Code paths (confirmed)

Layer	Behavior
shared/src/slashCommands.ts	BUILTIN_SLASH_COMMANDS.cursor is [] — web autocomplete / hub metadata get no Cursor builtins
cli/src/cursor/cursorRemoteLauncher.ts	Every hub batch → agent -p <message> --resume … with no special-command branch (unlike runClaude.ts + claudeRemote.ts, codexRemoteLauncher + parseCodexSpecialCommand)
cli/src/parsers/specialCommands.ts	Claude-only: /compact, /clear, /plan — no /summarize

Product vs HAPI

• Cursor product: IDE has /summarize (manual) + auto-summarize near context limit (forum). Not documented on headless CLI as a distinct flag.
• HAPI today: Hub message /summarize … is already passed verbatim to agent -p (opaque pass-through). Dogfood relocate queued /summarize on parent — not yet verified with token-count before/after on runner.
• Gap: integration = UI builtins + explicit parser contract + tests + telemetry, not missing Cursor physics. Claude uses pushIsolateAndClear for /compact; Codex uses thread/compact/start RPC. Cursor has no analogous HAPI RPC — pass-through is the v1 mechanism.

Proposed minimal upstream PR

1. Seed BUILTIN_SLASH_COMMANDS.cursor: summarize (optional trailing instructions), clear (document as pass-through; IDE command, CLI support TBD).
2. Add cli/src/cursor/cursorSpecialCommands.ts + tests (allow /summarize + args; strict /clear like Codex).
3. cursorRemoteLauncher: detect via parser, log + optional status line, still pass full message to agent -p.
4. Follow-up (out of minimal PR): E2E dogfood measuring token-count after relocate; spawn-peer parentContext.policy=compact for cursor flavor.

Next (this peer): implement (1)-(3) on an upstream/main worktree branch unless operator wants assessment-only.

[github-actions]

Confirmed: this is a real integration gap in the current codebase. Cursor remote messages are delivered as normal prompts to agent -p; there is no Cursor-specific /summarize builtin and no special-command branch equivalent to Claude /compact or Codex /compact.

I also did not find docs/plans/peer-relocate-dogfood-1.md, spawn-peer, parentContext, or parentCompact.reachedTarget in this checkout, so the peer-relocate acceptance path is not verifiable from the tracked files currently available here.

Relevant code:

• shared/src/slashCommands.ts:36 - BUILTIN_SLASH_COMMANDS.cursor is currently an empty list.
• cli/src/modules/common/slashCommands.ts:276 - CLI slash-command listing starts from getBuiltinSlashCommands(agent), so Cursor gets no seeded builtins unless custom commands are found.
• hub/src/web/routes/sessions.ts:508 - hub uses session.metadata.flavor to request slash commands for the active agent flavor.
• cli/src/cursor/cursorRemoteLauncher.ts:25 - Cursor process args are built as agent -p <message> --output-format stream-json --trust --workspace <cwd>.
• cli/src/cursor/cursorRemoteLauncher.ts:88 - remote loop reads queued hub messages.
• cli/src/cursor/cursorRemoteLauncher.ts:101 - queued message is passed directly into buildAgentArgs; no parseSpecialCommand import or branch exists in this launcher.
• cli/src/claude/runClaude.ts:255 - Claude checks parseSpecialCommand(...) before queueing.
• cli/src/claude/claudeRemote.ts:99 - Claude remote parses special commands and marks /compact handling intentionally.
• cli/src/codex/codexSpecialCommands.ts:6 - Codex has a dedicated parser for /clear and /compact.
• cli/src/cursor/utils/cursorEventConverter.ts:8 - Cursor stream event typing currently covers system, thinking, user, assistant, tool_call, and result only.
• cli/src/cursor/utils/cursorEventConverter.ts:90 - Cursor conversion emits assistant text/tool/turn-complete messages only; no usage/token-count or compaction event mapping is present.

Need more info:

• Verified Cursor Agent CLI behavior for agent -p "/summarize" and agent -p "/summarize <instructions>": whether it triggers actual context summarization headlessly or is treated as an ordinary prompt.

---

HAPI Bot