* 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).
* feat(cli,web,hub): migrate Cursor remote sessions to ACP with model/effort pickers
Move stream-json remote launcher to legacy path and add ACP launcher with
set_config_option model/mode sync, optimistic keepalive on config changes, and
shared catalog caching. Web gets dual base/effort Cursor pickers for session and
new-session flows; hide composer status bar when Cursor sends no usage_update.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(cli,web,shared): Cursor model picker — ACP wires + CLI sku variants
Enrich the web/mobile picker with agent --list-models SKUs grouped under
ACP wire bases, fix session-open base highlight, and keep catalog discovery
safe while the ACP transport holds the CLI lock.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(cursor-acp): apply ACP default model when web resets to Default
Web sends model: null for Default; push session/set_config_option with the
ACP default[] wire so Cursor backend matches hub state. Regression tests
for setModel(null) and applyModelConfig(null).
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(acp): clear stale agent-acp lock when owning process is gone
Check lock pid with signal 0; remove orphaned lock dirs after SIGKILL or
crash so listCursorModels can run cold probes again. Regression tests for
guard and catalog discovery.
Co-authored-by: Cursor <cursoragent@cursor.com>
* test(cursor): use live pid for ACP lock handler tests
Stale-lock cleanup clears dead pids; handler tests must simulate an
active lock with the current process pid to avoid cold probes/timeouts.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(acp): scope agent CLI lock guard to Cursor agent command only
Gemini/OpenCode/Kimi ACP sessions must not register agent-acp-active;
that blocked listCursorModels while unrelated backends were running.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(hub,web): reject Cursor model changes for local sessions
Hub returns 409 when controlledByUser is set, matching Codex. Web hides
model and variant pickers for local Cursor sessions so users do not hit
a dead RPC path. Document pre-push-review in AGENTS.md.
Verified: bun typecheck; bun run test (919 cli + 243 hub + 768 web + 46 shared).
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(web): send stable ids for Cursor ask_question replies
Parse and submit question.id and option.id so ACP receives keys like
{ approach: ['a'] } instead of index/label. Verified: bun typecheck && bun run test.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
* 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.
* feat(web): group consecutive tool-use cards
Add a web-only visible projection that groups consecutive root-level execution tools into expandable cards.
Keep approval and question tools standalone, reuse older-history loading on expand, and add regression coverage for grouping and UI behavior.
* fix(web): hydrate oldest visible tool group
Mark needsOlderHistory on the first visible grouped tool run even when earlier visible blocks are non-tool content, and add regression coverage for the boundary.
* fix(web): continue grouped history hydration
Decouple ToolGroupCard older-history chaining from the shared loading flag, invalidate stale hydration runs safely, and add regression coverage for multi-page hydration.
* fix(web): harden grouped tool hydration
- retry incomplete group hydration after transient pagination contention\n- keep approved and denied permissioned tool cards eligible for grouping\n- cover both regressions with targeted web tests
* fix(web): keep Codex permission cards standalone
- treat CodexPermission as a semantic grouping boundary even after approval\n- keep permissioned execution tools groupable while preserving permission milestones\n- add regression coverage for Codex permission eligibility and boundary behavior
* fix(web): narrow incomplete tool-group hydration
- only mark groups at the oldest visible boundary as needing older history\n- avoid auto-paginating complete groups behind text, standalone tools, or permission milestones\n- add regression coverage for the adjacent boundary cases
* feat(cli): support extra headers for hub requests
* fix(types): normalize missing session fields to null
* refactor(cli): simplify socket extra headers config
* feat(cursor): add support for Cursor Agent CLI integration
- Introduced new command `hapi cursor` to start Cursor Agent sessions.
- Added functionality for resuming sessions and managing permission modes.
- Updated documentation to include Cursor Agent usage and installation instructions.
- Enhanced existing codebase to accommodate Cursor as a recognized agent flavor.
- Implemented local and remote session handling for Cursor Agent.
This update expands HAPI's capabilities by integrating support for the Cursor Agent, allowing users to leverage its features alongside existing agents.
* Remove TODO.md file as it is no longer needed following the integration of Cursor Agent CLI support. This cleanup helps streamline project documentation and reflects the completion of the associated tasks.
* feat(cursor): implement remote mode and fix --hapi-starting-mode
- Consume --hapi-starting-mode in cursor command (do not forward to agent)
- Implement cursorRemoteLauncher: spawn agent -p with stream-json, --trust
- Add cursorEventConverter for NDJSON parsing (system/assistant/tool_call/result)
- Multi-turn via --resume session_id
- Update docs: cursor supports both local and remote modes
Made-with: Cursor
* fix: type error
* fix(cursor): address PR review - model UI, sessionId metadata, duplicate flags
- HappyComposer: use isClaudeFlavor for model mode (cursor has no model modes)
- cursorLocalLauncher: call onSessionFound for resume so cursorSessionId in metadata
- cursorCommand: do not forward parsed flags to cursorArgs (avoid duplicates)
Made-with: Cursor
Update installation guides to specify the official npm registry
and add a recommendation to use it for global installs, as some
mirrors may not sync platform packages in time.
- Remove Quick Tunnel (TryCloudflare) documentation as it doesn't support SSE which HAPI uses for real-time updates
- Add warning note explaining the limitation with link to Cloudflare docs
- Keep only Named Tunnel as the recommended approach
- Add tip about HAPI_RELAY_FORCE_TCP environment variable for users experiencing connectivity issues
- Add settings.json column to environment variables table with key name mappings
- Document missing ENV variables: TELEGRAM_BOT_TOKEN, TELEGRAM_NOTIFICATION,
HAPI_RELAY_FORCE_TCP, VAPID_SUBJECT
- Add settings.json example with configuration priority explanation
- Create JSON Schema file for settings.json validation and editor autocompletion
with all fields, descriptions, and ENV variable references
clsoe #113
Corrects outdated information about HAPI's decentralized architecture compared
to Happy's centralized approach. Updates user model, encryption strategy,
and deployment details to reflect current design. Clarifies that HAPI supports
both self-hosted and relay modes with proper security implications.
- Replace outdated WEBAPP_URL with HAPI_PUBLIC_URL in server and web READMEs
- Add CLI version verification steps in prerequisites section
- Enhance Cloudflare Tunnel documentation with quick and named tunnel examples
- Add --protocol http2 recommendation for tunnel stability
- Include pm2 alternative for runner process management
- Add Telegram Mini App troubleshooting notes and verification steps
Update documentation across README, installation, and quick-start guides
to highlight the new relay-based access method with WireGuard + TLS
end-to-end encryption. Changes include:
- Recommend `hapi server --relay` as the default startup command
- Explain URL and QR code generation in terminal for instant access
- Note end-to-end encryption for security assurance
- Reorganize self-hosted tunnel options (Cloudflare, Tailscale, IP)
- Update website installation steps and add E2EE badge
Use relative paths with .md extension for docs/guide/*.md files and
relative paths in README.md to support both GitHub rendering and
VitePress website (which has base: '/docs/'). Fixes#36
Introduce comprehensive documentation of HAPI's Seamless Handoff feature:
- README: Add Seamless Handoff to Features section
- how-it-works: Add complete Seamless Handoff guide with local/remote modes and switching workflow
- quick-start: Add Seamless Handoff link to Next steps
- AppShowcase: Add third card featuring "Switch Freely" mode switching capability
- Locales: Update English and Chinese translations for showcase content
- Support both local and remote server deployment
- Add direct public IP access option for remote servers
- Remove tunnel requirement messaging
- Organize remote access options with details sections
- Replace VitePress router with window.location for docs index redirect
- Add redirect rules for /docs and /docs/ paths to quick-start guide
- Simplify navigation by removing section anchor links
- Update all CTA buttons to link directly to /docs/ instead of home sections
- Consolidate navigation layout on both desktop and mobile views
- Set VitePress base to '/docs/' for serving documentation at /docs/ route
- Update favicon path in head config to '/docs/favicon.ico'
- Add build:site script to build website and docs, then merge outputs
- Initialize VitePress documentation site with config, index, and guides
- Add guides for quick-start, installation, PWA, how-it-works, FAQ, and why HAPI
- Update .gitignore to exclude VitePress cache directory
- Update logo.svg with actual icon from web/public/icon.svg
- Simplify README.md with link to full installation guide
- Remove redundant WHY_NOT_HAPPY.md (content migrated to why-hapi guide)
Add comprehensive WHY_NOT_HAPPY.md documenting the architectural
differences between HAPI's local-first design and Happy's cloud-first
approach. Update README with clearer project description and link to
new documentation.
