mirror of https://github.com/wu736139669/hapi.git synced 2026-08-05 06:24:37 +00:00

Files

T

HeavyGeeandGitHub dc0d21e05b fix(cursor): intercept fabricated Questions skipped AskQuestion result in headless mode (#784 ) (#801 )

* fix(cursor): intercept fabricated 'Questions skipped' AskQuestion result in headless mode (#784)

When cursor-agent runs under `--print --output-format stream-json` (HAPI's
current Cursor remote launcher), the CLI returns a synthetic
`Questions skipped by the user, continue with the information you already have`
response for the `AskQuestion` tool in ~zero seconds with no error flag,
because there is no IDE surface to render the question. The underlying
model can interpret this as legitimate user consent and act on it.

This patch intercepts the synthetic result in
`cli/src/cursor/utils/cursorEventConverter.ts` and rewrites the
`tool_call`/completed event to a structured `no_input_surface` failure
(`status: 'failed'`, which downstream becomes `is_error: true`).

Detection has two strategies:

1. String match - any `tool_call`/completed payload whose serialized form
   contains the synthetic-skip marker is rewritten. This is robust to
   wherever cursor-agent stuffs the marker inside the `tool_call` object.
2. Timing + name heuristic (defense in depth) - any completion that arrives
   within 500 ms of its 'started' event with a trivial result, for a tool
   call named `AskQuestion`, `askQuestion`, `ask_question`, or the
   converter's `unknown` fallback, is also rewritten. This catches the case
   where cursor-agent changes the synthetic-string text in a future release.

The converter tracks per-call timestamps in a bounded `Map` (`<= 1024`
entries, oldest evicted on overflow) and clears entries when the
corresponding 'completed' event arrives. A small test-only reset hook
isolates state between Vitest cases.

This is a transitional safety patch. It auto-deletes when #781's ACP
launcher replaces the stream-json launcher and `cursor/ask_question`
becomes a proper bidirectional ACP method where fabrication is
structurally impossible.

Scope is intentionally tiny: only `cli/src/cursor/utils/cursorEventConverter.ts`,
its colocated Vitest file, and a section in `docs/guide/cursor.md`. No
changes to `cursorRemoteLauncher.ts`, ACP code, web normalizer, or
permission UI.

Refs: tiann/hapi#781 (long-term resolution via ACP migration)
Closes: tiann/hapi#784

* fix(cursor): gate AskQuestion intercept on tool name (#784 PR #801 review)

Address regression flagged by the HAPI auto-review bot on #801:

`containsSyntheticSkipMarker` previously stringified the entire `tool_call`
payload and matched the literal marker substring. Because this PR also adds
that exact marker to `docs/guide/cursor.md` (to document the intercept), a
Cursor `read_file` of that documentation page would surface the marker
inside `readToolCall.result.content` and be rewritten as a
`no_input_surface` failure, corrupting an unrelated, legitimate result.

The intercept is now gated on the tool name resolving to an
AskQuestion-shaped call (`AskQuestion`, `askQuestion`, `ask_question`, or
the converter's `unknown` fallback for unnamed function-shaped tools).
`read_file` / `write_file` tool calls - which have explicit `read_file`
and `write_file` names from `extractToolName` - no longer fall under the
intercept, regardless of what their payload contains.

The marker check itself now walks values recursively (string / array /
object), guarded by a `WeakSet` against cycles, instead of relying on
`JSON.stringify`. Slightly tidier; behaviour is otherwise unchanged for
the AskQuestion path.

Regression tests added:

- `read_file` result whose `content` contains the marker -> passes
  through with `status: 'completed'` and no `no_input_surface`.
- `write_file` whose serialized `args` contain the marker -> same.
- A non-AskQuestion function tool (`MyCustomTool`) whose result quotes
  the marker -> same.

All 846 cli tests pass (17 in this file). `bun run typecheck` exits 0.

* fix(cursor): scope synthetic-skip check to extracted result (#784 PR #801 review-2)

Address second Major finding from the HAPI auto-review bot on #801:

After the previous fix gated the intercept on the tool name, the marker
check still recursed into the entire `tool_call` object - which includes
`function.arguments`, the agent's own prompt text. A legitimate
AskQuestion whose prompt quotes the synthetic-skip marker (e.g. an agent
debugging this exact bug, or any prompt that pastes the marker verbatim)
would have been rewritten as `no_input_surface` even when the operator
actually answered.

Changes:

1. `extractToolResult` now extracts the cursor-side response from
   function-shaped tool calls. Previously it returned `{}` for anything
   that wasn't `readToolCall` or `writeToolCall`. It now returns
   `function.result` when present, otherwise every field of `function`
   except `name` and `arguments`. This excludes the agent's input from
   what downstream sees as the tool result, and as a side effect surfaces
   the actual cursor response for function-shaped tools (which was
   previously lost - see the #784 incident note about HAPI storing
   `output: {}` for AskQuestion in the message DB).

2. `shouldRewriteAsNoInputSurface` now searches only the extracted
   `result`, not the whole `tool_call`. The bot's exact recommendation.

3. Test added: an AskQuestion whose `arguments` quote the marker but
   whose `result` is a real user answer, with elapsed time past the
   500 ms threshold so the timing heuristic does not apply. Asserts the
   tool_result passes through with `status: 'completed'` and the
   operator's actual answer.

All 847 cli tests pass (18 in `cursorEventConverter.test.ts`).
`bun run typecheck` exits 0.

The widened `extractToolResult` scope is necessary for the marker check
to actually find the synthetic string (it lives inside `function.result`
or a sibling field), and is the bot's explicit recommendation. It also
removes the long-standing data-loss bug where AskQuestion responses were
surfaced to the message DB as opaque `{}` - regardless of fabrication.

2026-06-05 21:44:37 +08:00

.github/workflows

refactor: rename daemon to runner throughout codebase

2026-01-19 11:12:48 +08:00

bin

refactor(cli): extract platform validation and error reporting from binary launcher

2026-03-02 11:58:08 +08:00

npm

feat: add npx/bunx binary distribution support

2025-12-24 14:39:05 +08:00

scripts

Clean up cross-package build coupling

2026-05-20 19:29:43 +08:00

src

fix(cursor): intercept fabricated Questions skipped AskQuestion result in headless mode (#784 ) (#801 )

2026-06-05 21:44:37 +08:00

tools

init

2025-12-16 15:03:50 +08:00

.cursorrules

init

2025-12-16 15:03:50 +08:00

.gitattributes

init

2025-12-16 15:03:50 +08:00

.gitignore

Fix npm release wrapper package

2026-01-03 22:22:45 +08:00

.npmignore

feat: add npx/bunx binary distribution support

2025-12-24 14:39:05 +08:00

.npmrc

init

2025-12-16 15:03:50 +08:00

bunfig.toml

fix(cli): resolve path alias with bun link using bunfig.toml configuration

2025-12-22 16:44:27 +08:00

LICENSE

chore: migrate to AGPL-3.0-only

2026-01-04 20:45:15 +08:00

local-client-launcher.ts

fix(cli): preserve invoked cwd for local launcher (#299 )

2026-03-17 22:55:23 +08:00

NOTICE

refactor: rename daemon to runner throughout codebase

2026-01-19 11:12:48 +08:00

package.json

Release version 0.19.0

2026-06-01 12:37:32 +08:00

README.md

feat: add hapi resume command (#647 )

2026-05-20 06:18:42 +08:00

tsconfig.json

Clean up cross-package build coupling

2026-05-20 19:29:43 +08:00

vitest.config.ts

fix(test): isolate integration tests from production hub via temp hub globalSetup (#734 )

2026-05-31 20:31:05 +08:00

README.md

hapi CLI

Run Claude Code, Codex, Cursor Agent, Gemini, or OpenCode sessions from your terminal and control them remotely through the hapi hub.

What it does

Starts Claude Code sessions and registers them with hapi-hub.
Starts Codex mode for OpenAI-based sessions.
Starts Cursor Agent mode for Cursor CLI sessions.
Starts Gemini mode via ACP (Anthropic Code Plugins).
Starts OpenCode mode via ACP and its plugin hook system.
Provides an MCP stdio bridge for external tools.
Manages a background runner for long-running sessions.
Includes diagnostics and auth helpers.

Typical flow

Start the hub and set env vars (see ../hub/README.md).
Set the same CLI_API_TOKEN on this machine or run hapi auth login.
Run hapi to start a session.
Use the web app or Telegram Mini App to monitor and control.

Commands

Session commands

hapi - Start a Claude Code session (passes through Claude CLI flags). See src/index.ts.
hapi codex - Start Codex mode. See src/codex/runCodex.ts.
hapi codex resume <sessionId> - Resume existing Codex session.
hapi cursor - Start Cursor Agent mode. See src/cursor/runCursor.ts. Supports hapi cursor resume <chatId>, hapi cursor --continue, --mode plan|ask, --yolo, --model. Local and remote modes supported; remote uses agent -p with stream-json.
hapi gemini - Start Gemini mode via ACP. See src/agent/runners/runAgentSession.ts. Note: Gemini runs in remote mode only; it waits for messages from the hub UI/Telegram.
hapi opencode - Start OpenCode mode via ACP. See src/opencode/runOpencode.ts. Note: OpenCode supports local and remote modes; local mode streams via OpenCode plugins.
hapi resume [sessionId] - List resumable sessions for this machine or resume one locally.

Resume a remote session locally

hapi resume
hapi resume <session-id>

hapi resume lists resumable sessions for the current machine. hapi resume <session-id> hands off an active remote session and opens the same HAPI session in the local terminal.

Authentication

hapi auth status - Show authentication configuration and token source.
hapi auth login - Interactively enter and save CLI_API_TOKEN.
hapi auth logout - Clear saved credentials.

See src/commands/auth.ts.

Runner management

hapi runner start - Start runner as detached process.
hapi runner stop - Stop runner gracefully.
hapi runner status - Show runner diagnostics.
hapi runner list - List active sessions managed by runner.
hapi runner stop-session <sessionId> - Terminate specific session.
hapi runner logs - Print path to latest runner log file.

Both start and start-sync accept repeatable --workspace-root <path> (or --workspace-root=<path>). When set:

The web /browse page surfaces scoped file trees rooted at those paths.
The runner refuses list-directory and spawn-session requests for paths outside the configured roots.
~ and ~/foo are expanded.

Omitting the flag keeps the legacy behavior: no scoping, no /browse feature.

See src/runner/run.ts.

Diagnostics

hapi doctor - Show full diagnostics (version, runner status, logs, processes).
hapi doctor clean - Kill runaway HAPI processes.

See src/ui/doctor.ts.

Other

hapi mcp - Start MCP stdio bridge. See src/codex/happyMcpStdioBridge.ts.
hapi hub - Start the bundled hub (single binary workflow).
hapi server - Alias for hapi hub.

Configuration

See src/configuration.ts for all options.

Required

CLI_API_TOKEN - Shared secret; must match the hub. Can be set via env or ~/.hapi/settings.json (env wins).
HAPI_API_URL - Hub base URL (default: http://localhost:3006).

Optional

HAPI_HOME - Config/data directory (default: ~/.hapi).
HAPI_EXPERIMENTAL - Enable experimental features (true/1/yes).
HAPI_EXTRA_HEADERS_JSON - JSON object of extra headers to send on CLI → hub requests, e.g. {"Cookie":"CF_Authorization=..."}.
HAPI_CLAUDE_PATH - Path to a specific claude executable.
HAPI_HTTP_MCP_URL - Default MCP target for hapi mcp.

Runner

HAPI_RUNNER_HEARTBEAT_INTERVAL - Heartbeat interval in ms (default: 60000).
HAPI_RUNNER_HTTP_TIMEOUT - HTTP timeout for runner control in ms (default: 10000).

Worktree (set by runner)

HAPI_WORKTREE_BASE_PATH - Base repository path.
HAPI_WORKTREE_BRANCH - Current branch name.
HAPI_WORKTREE_NAME - Worktree name.
HAPI_WORKTREE_PATH - Full worktree path.
HAPI_WORKTREE_CREATED_AT - Creation timestamp (ms).

Storage

Data is stored in ~/.hapi/ (or $HAPI_HOME):

settings.json - User settings (machineId, token, onboarding flag). See src/persistence.ts.
runner.state.json - Runner state (pid, port, version, heartbeat).
logs/ - Log files.

Requirements

Claude CLI installed and logged in (claude on PATH).
Cursor Agent CLI installed (agent on PATH) for hapi cursor. Install: curl https://cursor.com/install -fsS | bash (macOS/Linux), irm 'https://cursor.com/install?win32=true' | iex (Windows).
OpenCode CLI installed (opencode on PATH).
Bun for building from source.

Build from source

From the repo root:

bun install
bun run build:cli
bun run build:cli:exe

For an all-in-one binary that also embeds the web app:

bun run build:single-exe

Source structure

src/api/ - Bot communication (Socket.IO + REST).
src/claude/ - Claude Code integration.
src/codex/ - Codex mode integration.
src/cursor/ - Cursor Agent integration.
src/agent/ - Multi-agent support (Gemini via ACP).
src/opencode/ - OpenCode ACP + hook integration.
src/runner/ - Background service.
src/commands/ - CLI command handlers.
src/ui/ - User interface and diagnostics.
src/modules/ - Tool implementations (ripgrep, difftastic, git).

../hub/README.md
../web/README.md

README.md

hapi CLI

What it does

Typical flow

Commands

Session commands

Resume a remote session locally

Authentication

Runner management

Diagnostics

Other

Configuration

Required

Optional

Runner

Worktree (set by runner)

Storage

Requirements

Build from source

Source structure

Related docs