mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
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).
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# Cursor Agent
|
|
|
|
HAPI supports [Cursor Agent CLI](https://cursor.com/docs/cli/using) 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:
|
|
|
|
```bash
|
|
agent --version
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
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 cursor` from terminal. Full interactive experience.
|
|
- **Remote mode** - Spawn from web/phone when no terminal. New Cursor sessions use `agent acp` with HAPI permission approval, plan/question UI, and richer tool updates. Legacy sessions created before the ACP migration may still resume via the old `agent -p` stream-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-json `session_id` values 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](https://github.com/tiann/hapi/issues/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](https://cursor.com/docs/cli/using)
|
|
- [How it Works](./how-it-works.md) - Architecture and data flow
|