HeavyGeeandGitHub
6d2d0d4707
* fix(cursor): drop timing heuristic from #784 intercept; scan raw payload (#801 follow-up) PR #801 shipped a two-strategy intercept for the synthetic AskQuestion skip response in legacy stream-json mode. Real-traffic data from a post-merge run shows the marker-match strategy never fires (the converter's `extractToolResult` discards the marker for tool shapes it does not recognize, returning `{}`) and the timing-signature defense-in-depth strategy fires only on false positives - notably the Anthropic Vertex Claude tool calls cursor-agent surfaces in legacy sessions, which all land as `name=unknown` with the `{}` extracted result and frequently complete under the 500 ms threshold. Measured on a single legacy-resumed session (`7b769423`): 1,136 `name=unknown` tool calls, 16 rewritten as `no_input_surface`, zero actual marker strings stored anywhere in the session. The 16 rewrites were legitimate fast tool calls (Anthropic Vertex `toolu_vrtx_*` IDs) mischaracterized as fabricated skip responses. Changes: - Remove the timing-signature heuristic and its supporting state (started-at map, elapsed-ms calculation, latency threshold, test-only state reset). - Move the marker scan from the post-`extractToolResult` output to the raw `tool_call` payload, so it can see the marker on stream-json shapes the converter does not specifically recognize. Function-shaped tools exclude `function.arguments` from the scan to avoid matching agent-controlled input. Other shapes scan the full payload (no agent-input field exists at the top level). - Refresh tests: drop timing-based positive cases, add a marker-in-raw- payload positive case for `name=unknown` shapes, and add a regression that legitimate fast `name=unknown` tool calls without the marker pass through with `status: completed`. - Document scope: this intercept now lives only on the legacy stream- json path, which only resumed pre-ACP sessions hit. New cursor remote sessions go through `cursorAcpBackend` and the `cursor/ask_question` ACP extension method (#799) - immune to this bug. The intercept drains with the legacy session population. Tracking: #784. Builds on #801, complements #799. * fix(cursor): exclude agent input from marker scan; surface top-level Anthropic tool names (Codex P2) Codex flagged a false-positive case on the fork-stage review of this branch (heavygee/hapi#35, P2): an Anthropic tool_use shape with a top-level `name` (e.g. `{id, name: 'TodoWrite', input: { ... }}`) gets labelled `name=unknown` by the converter and passes the AskQuestion gate. If the agent's `input` quotes the synthetic-skip marker - which happens whenever an agent edits or documents this very bug - the intercept would rewrite a perfectly fine TodoWrite as a fabricated skip. Two-part fix: 1. `extractToolName` now reads the top-level `name` field as a final fallback. A real `TodoWrite` / `Bash` / `str_replace_based_edit_tool` surfaces with its actual name and is rejected by the AskQuestion gate before the marker scan runs. The original AskQuestion fabrication case still surfaces as `unknown` (per #784 issue body the name is stripped in the fabricated payload) and remains detectable. 2. Defense in depth: introduce `AGENT_INPUT_KEYS = {input, args, arguments}` and exclude these from the non-function shape's marker scan. Even if a tool reaches this code path with `name=unknown` and the marker buried in its `input`, the intercept won't fire on agent- controlled text. Two new regression tests: - Anthropic tool_use shape `{id, name: 'TodoWrite', input: {todos: [ marker]}}` → passes through with `status: 'completed'`. - `name=unknown` shape with marker only inside `input` → passes through with `status: 'completed'`. All 20/20 tests pass; typecheck clean (cli + web + hub).
3.7 KiB
Cursor Agent
HAPI supports Cursor Agent CLI for running Cursor's AI coding agent with remote control via web and phone.
Prerequisites
Install Cursor Agent CLI:
- macOS/Linux:
curl https://cursor.com/install -fsS | bash - Windows:
irm 'https://cursor.com/install?win32=true' | iex
Verify installation:
agent --version
Usage
hapi cursor # Start Cursor Agent session
hapi cursor resume <chatId> # Resume a specific chat
hapi cursor --continue # Resume the most recent chat
hapi cursor --mode plan # Start in Plan mode
hapi cursor --mode ask # Start in Ask mode
hapi cursor --yolo # Bypass approval prompts (--force)
hapi cursor --model <model> # Specify model
Permission Modes
| Mode | Description |
|---|---|
default |
Standard agent behavior |
plan |
Plan mode - design approach before coding |
ask |
Ask mode - explore code without edits |
yolo |
Bypass approval prompts |
Set mode via --mode flag or change from the web UI during a session.
Modes
- Local mode - Run
hapi cursorfrom terminal. Full interactive experience. - Remote mode - Spawn from web/phone when no terminal. New Cursor sessions use
agent acpwith HAPI permission approval, plan/question UI, and richer tool updates. Legacy sessions created before the ACP migration may still resume via the oldagent -pstream-json path temporarily.
Limitations
- Legacy sessions - Cursor sessions created before the ACP migration can still resume temporarily via stream-json. Start a new Cursor session to get ACP permissions, plans, todos, and question support.
- Session resume - ACP sessions resume through
session/load. Old stream-jsonsession_idvalues are not loadable via ACP; those sessions keep using the legacy path until you start fresh.
Legacy stream-json safety: AskQuestion behavior
New cursor remote sessions go through ACP, which handles AskQuestion via the bidirectional cursor/ask_question extension method and is immune to the issue below. The intercept described here exists only for legacy sessions that resume via the older agent -p stream-json launcher.
When running cursor-agent under --print --output-format stream-json, the cursor-agent CLI returns a synthetic Questions skipped by the user, continue with the information you already have response for the AskQuestion tool because there is no IDE surface to render the question. The agent's underlying model can interpret this as legitimate user consent and act on it.
HAPI's legacy event converter intercepts this synthetic response and rewrites it to an explicit no_input_surface error (status: failed), so downstream consumers (web UI, Telegram, log readers) surface the fabrication as an error instead of silently passing through fabricated consent. The intercept scans the raw tool_call payload for the literal marker text and is scoped to AskQuestion-shaped (and converter-fallback name=unknown) calls; legitimate read/write/function tools are not affected.
The intercept drains naturally with the legacy session population - resumed pre-ACP sessions are the only path that still hits this code.
Tracking issue: tiann/hapi#784.
Integration
Once running, your Cursor session appears in the HAPI web app and Telegram Mini App. You can:
- Monitor session activity
- Approve permissions from your phone
- Send messages when in local mode (messages queue for when you switch)
Related
- Cursor CLI Documentation
- How it Works - Architecture and data flow