hop2 0.10.0 → 0.11.0

package/README-MCP.md

@@ -6,7 +6,7 @@ restarts.
 
 ## Quick Start
 
-1. Ensure the Hop daemon is running locally.
+1. Ensure the Hop daemon is running locally by running `hop` (interactive) or `hop start` (daemon only).
 
 2. Auto-configure supported MCP clients:
 
@@ -49,7 +49,7 @@ The server auto-connects to the local Hop daemon via `~/.hop2/.tunnel-state`.
 
 Recommended flow for driving one Claude/Codex/Gemini terminal safely:
 
-1. Launch a dedicated terminal:
+1. Launch a dedicated terminal (the returned `id` is the `terminal_id` used by every other tool):
 
 ```
 hop_create_terminal(name="subagent", cwd="/path/to/repo")
@@ -58,33 +58,56 @@ hop_create_terminal(name="subagent", cwd="/path/to/repo")
 2. Start the agent CLI:
 
 ```
-hop_write_terminal(data="claude\n")
+hop_write_terminal(terminal_id=<id>, data="claude\n")
 # or
-hop_write_terminal(data="codex\n")
+hop_write_terminal(terminal_id=<id>, data="codex\n")
 ```
 
 3. Wait for a prompt before sending work:
 
 ```
-hop_wait_terminal(until_prompt=true, start_from="latest")
+hop_wait_terminal(terminal_id=<id>, until_prompt=true, start_from="latest")
 ```
 
 4. Run a multi-turn loop:
-- Preferred: `hopx_agent_turn(data="<task>", mode="auto")`
-- Good lower-level helper: `hopx_send_and_wait(data="<task>", press_enter=true, capture="readable_raw")`
+- Preferred: `hopx_agent_turn(terminal_id=<id>, data="<task>", mode="auto")`
+- Good lower-level helper: `hopx_send_and_wait(terminal_id=<id>, data="<task>", press_enter=true, capture="readable_raw")`
 - Manual split only when needed:
-- send with `hop_write_terminal(data="<task>\n")`
-- wait with `hop_wait_terminal(capture="readable_raw")`
-- continue via cursor deltas from `hop_read_terminal(start_from="cursor", cursor=...)`
+- send with `hop_write_terminal(terminal_id=<id>, data="<task>\n")`
+- wait with `hop_wait_terminal(terminal_id=<id>, capture="readable_raw")`
+- continue via cursor deltas from `hop_read_terminal(terminal_id=<id>, start_from="cursor", cursor=...)`
 
 5. Stop or clean up:
-- interrupt with `hop_send_key(key="ctrl_c")`
-- close with `hop_close_terminal(killSession=false)`
+- interrupt with `hop_send_key(terminal_id=<id>, key="ctrl_c")`
+- close with `hop_close_terminal(terminal_id=<id>, killSession=false)`
 
 Safety notes:
 - Keep one subagent per terminal (no multiplexing multiple agent CLIs in one PTY).
 - For existing user sessions, verify `agentPermitted` (or set with `hop_set_agent_permission`) before writing input.
 
+## Shell Commands: `hopx_exec`
+
+For plain shell work (not interactive TUIs), `hopx_exec` behaves like a Bash
+tool on a persistent terminal: it sends the command, waits for the next shell
+prompt, and returns clean plain-text output.
+
+Worked example:
+
+```
+hop_create_terminal(name="builder", cwd="/path/to/repo")   # returns id
+hopx_exec(terminal_id=<id>, command="npm test")
+# -> { "ok": true, "exit_code": 0, "stdout": "...", "next_cursor": ... }
+hopx_exec(terminal_id=<id>, command="ls /nope")
+# -> { "ok": true, "exit_code": 1, "stdout": "ls: /nope: No such file or directory", ... }
+```
+
+Semantics:
+- `ok` means the shell prompt returned within `timeout_ms` — NOT that the command succeeded.
+- `exit_code` is the command's real exit status, captured by appending a POSIX sentinel (`<cmd>; printf '\n__HOPX_RC_<nonce>=%d\n' "$?"`). It is `null` when the sentinel was never observed (timeout, or a shell without POSIX `$?` semantics) — in that case behavior degrades gracefully to prompt-based capture.
+- The sentinel line, the echoed command, the trailing prompt, and ANSI codes are stripped from `stdout`.
+- On timeout, `timed_out: true` is set and `ok` is `false`.
+- For SSH sessions or unusual prompts, pass `prompt_regex`; for commands with non-standard output endings, pass `idle_ms` as a fallback condition.
+
 ## Remote Hop
 
 To connect to a remote hop instance, set env vars or use `connect_server`:
@@ -108,29 +131,32 @@ connect_server(base_url="https://hop2.example.com", token="<token>", verify=true
 ## Tools
 
 Core tools (`hop_`): stable atomic operations.
-- `connect_server`
-- `hop_server_info`
-- `hop_list_sessions`
-- `hop_list_terminals`
-- `hop_create_terminal`
-- `hop_attach_terminal`
-- `hop_write_terminal`
-- `hop_send_key`
-- `hop_wait_terminal`
-- `hop_wait_start`
-- `hop_wait_poll`
-- `hop_resize_terminal`
-- `hop_read_terminal`
-- `hop_close_terminal`
-- `hop_set_agent_permission`
-- `hop_list_workspaces`
-- `hop_save_workspace`
-- `hop_load_workspace`
-- `hop_use_workspace`
+- `connect_server` — connect to a Hop API base_url (optional token); use for remote hop instances
+- `hop_server_info` — hop-mcp runtime diagnostics (version, script path, read-mode capabilities)
+- `hop_list_sessions` — list Hop sessions and metadata
+- `hop_list_terminals` — list terminal API sessions (created via `hop_create_terminal` / `hop_attach_terminal`)
+- `hop_create_terminal` — create a terminal session and optionally run a startup command; returns the `id` used as `terminal_id` everywhere else
+- `hop_attach_terminal` — attach to an existing terminal session by name or internalName
+- `hop_write_terminal` — write raw input to a terminal session
+- `hop_send_key` — send a named keypress (enter, esc, tab, shift_tab, arrows, f1-f12, ctrl+[a-z], ...)
+- `hop_wait_terminal` — wait for output conditions (regex, prompt, idle, agent_done); `async=true` returns a `wait_id`
+- `hop_wait_start` — deprecated legacy alias for `hop_wait_terminal(async=true)`
+- `hop_wait_poll` — poll or await completion of a background wait job
+- `hop_resize_terminal` — resize the terminal PTY
+- `hop_read_terminal` — read terminal output events (default `mode="readable_raw"`); returns a cursor for incremental reads
+- `hop_close_terminal` — detach the terminal API session; optionally kill the underlying hop session
+- `hop_set_agent_permission` — allow or block agent access for a session
+- `hop_list_workspaces` — list available workspaces
+- `hop_create_workspace` — create an empty workspace by name
+- `hop_show_workspace` — show saved definitions in a workspace
+- `hop_save_workspace` — save a workspace snapshot from live sessions
+- `hop_delete_workspace` — delete a workspace by name
+- `hop_load_workspace` — load a workspace and optionally start sessions
 
 Helper tools (`hopx_`): convenience wrappers built on top of core tools.
-- `hopx_send_and_wait` (single-call send + wait wrapper)
-- `hopx_agent_turn` (single-turn send + wait + mode-aware output, default `mode="auto"`)
+- `hopx_send_and_wait` — single-call send + wait wrapper
+- `hopx_exec` — Bash-tool-style shell execution: command in, clean stdout + `exit_code` out (see section above)
+- `hopx_agent_turn` — single-turn send + wait + mode-aware output, default `mode="auto"`
 
 ## Resources
 
@@ -151,6 +177,11 @@ Helper tools (`hopx_`): convenience wrappers built on top of core tools.
 
 ### `hop_read_terminal`
 
+- Defaults are token-thrifty:
+  - `mode` defaults to `"readable_raw"` (pass `"raw"` or `"ui"` explicitly when needed)
+  - `maxEvents` defaults to `200` and `maxBytes` to `65536`; pass `0` explicitly for unlimited (the buffer keeps the last 2000 events)
+  - when these caps truncate a read, the payload includes `truncated: true` plus a `hint`; continue with `start_from="cursor"`, `cursor=<next_cursor>`
+  - `start_from` defaults to `cursor` when `cursor` is provided, otherwise `beginning`
 - `hop_read_terminal` supports `mode: "ui"` for structured terminal snapshots:
   - `ui.lines`: visible screen lines
   - `ui.cursor`: cursor position
@@ -194,9 +225,9 @@ Helper tools (`hopx_`): convenience wrappers built on top of core tools.
 
 ### Async wait helpers
 
-- `hop_wait_start` / `hop_wait_poll` provide explicit async wait orchestration for long-running conditions:
-  - start with `hop_wait_start(...)` and poll with `hop_wait_poll(wait_id=..., wait=true)`
+- For long-running conditions, start a background wait with `hop_wait_terminal(terminal_id=<id>, async=true, ...)` (returns `wait_id` immediately) and poll with `hop_wait_poll(wait_id=..., wait=true)`
   - use `consume=true` on poll to remove completed jobs
+- `hop_wait_start` is a deprecated legacy alias for `hop_wait_terminal(async=true)`; prefer the latter
 
 ### `hopx_send_and_wait`
 
@@ -225,8 +256,11 @@ Helper tools (`hopx_`): convenience wrappers built on top of core tools.
 
 ### Error model
 
-- Tool calls that fail at the Hop API layer now return MCP errors (`isError: true`) with normalized fields:
+- Tool calls that fail at the Hop API layer return MCP tool errors (`isError: true`) with normalized fields:
   - `ok`
   - `status`
   - `endpoint`
   - `error`
+  - `hint` (when a remedy is known)
+- Connection-level failures (daemon not running, unreachable host, timeouts) also come back as normalized tool errors with `status: null` and a `hint` explaining how to start the daemon (`hop` or `hop start`) or reconnect via `connect_server(base_url=...)` — not as raw JSON-RPC protocol errors.
+- A `403` "Agent access not permitted" error includes a hint to enable access with `hop_set_agent_permission(name=..., allowed=true)` or `hop session permit <name>`.

package/README.md

@@ -140,21 +140,21 @@ Use one dedicated terminal per subagent.
 2. Start the agent CLI with `hop_write_terminal`.
 3. Wait for readiness with `hop_wait_terminal(until_prompt=true)`.
 4. Prefer `hopx_agent_turn(mode="auto")` or `hopx_send_and_wait(...)` for one turn at a time.
-5. For long waits, use `hopx_agent_turn(async=true, ...)` or the lower-level `hop_wait_start(...)` / `hop_wait_poll(...)`.
+5. For long waits, use `hopx_agent_turn(async=true, ...)` or the lower-level `hop_wait_terminal(async=true, ...)` + `hop_wait_poll(...)` (`hop_wait_start` remains only as a legacy alias).
 6. Interrupt with `hop_send_key(key="ctrl_c")` and close with `hop_close_terminal`.
 
 Safety tips:
 
 - Keep one subagent per terminal.
 - Do not queue a second instruction before reading the first response.
-- For attached user sessions, confirm `agentPermitted` before sending input.
+- For attached user sessions, confirm `agentPermitted` before sending input (grant it with `hop session permit <name>`).
 
 ### Share a Local Web App
 
 Expose a local HTTP or WebSocket service through your Hop tunnel:
 
 ```bash
-hop session add myapp --port 3000
+hop session add myapp --port 3000 --workspace dev
 ```
 
 Result:
@@ -172,6 +172,7 @@ hop attach <session>
 ```
 
 This is useful when you want a browser, an MCP client, and a local shell to converge on the same named session.
+Local terminal sessions are persistent by default: they keep running in the Hay host if the local CLI detaches or the Hop daemon restarts. The local CLI status line shows `persists`; use `Ctrl+Q` inside the local Hop view to kill the session.
 
 ### Use Hop on Mobile
 
@@ -263,12 +264,21 @@ Hop uses the external Hay host runtime for PTY hosting and session recovery.
 
 | Command | Description |
 |---------|-------------|
-| `hop` | Start hop daemon/tunnel if needed, then launch a local terminal |
+| `hop` | Start hop daemon/tunnel if needed, then launch a local terminal. Unnamed launches do not reuse a session that already has a local CLI attached. |
+| `hop start` | Start the hop daemon and print QR codes |
+| `hop attach [session]` | Attach to an existing terminal session |
 | `hop attach all` | Attach sequentially to all terminal sessions |
 | `hop local [session]` | Start a daemonless local terminal (`[session]` attaches if it exists) |
+| `hop stop` | Stop the hop daemon (terminal sessions keep running) |
+| `hop stop --all` | Stop the daemon, the hay-host, and all terminal sessions |
+| `hop status` | Show daemon, tunnel, and session status |
+| `hop doctor` | Run environment/health checks |
+| `hop logs [-f]` | Show daemon logs (`-f` to follow) |
+| `hop health [--restart]` | Check tunnel health (`--restart` forces a tunnel restart) |
 | `hop url` | Print current tunnel URL |
 | `hop qr` | Show QR code for current tunnel URL |
 | `hop qr auth` | Show QR code for authenticator app setup |
+| `hop config theme [name]` | Show or set the session naming theme |
 | `hop domain <hostname>` | Set custom domain (named tunnel) |
 | `hop domain-clear` | Remove custom domain, use random URLs |
 | `hop password set` | Set/change password |
@@ -278,19 +288,24 @@ Hop uses the external Hay host runtime for PTY hosting and session recovery.
 | `hop user remove <name>` | Remove user |
 | `hop user export <name>` | Export user credentials |
 | `hop session list` | List live terminal sessions |
-| `hop session list --all` | Include saved definitions from all workspaces alongside live sessions |
+| `hop session list --all` | Include saved definitions from all workspaces alongside live sessions (`-a` is shorthand) |
 | `hop session add <name> [--cwd P] --workspace W` | Save a terminal session definition to a named workspace |
 | `hop session add <name> --port N --workspace W` | Save a port session definition to a named workspace |
+| `hop session permit <name>` | Allow agent access to a session |
+| `hop session block <name>` | Block agent access to a session |
+| `hop workspace list` | List workspaces |
 | `hop workspace create <name>` | Create an empty workspace |
 | `hop workspace show <name>` | Show saved definitions in a workspace |
 | `hop workspace save <name>` | Save selected live terminal sessions into a workspace |
 | `hop workspace load <name>` | Start sessions defined in a workspace |
-| `hop workspace delete <name>` | Delete a workspace |
+| `hop workspace delete <name> [--yes]` | Delete a workspace (asks before deleting a non-empty one) |
 | `hop session rename <old> <new>` | Rename a session |
 | `hop session remove <name>` | Remove a session |
 | `hop client <credentials>` | Run hop with exported credentials |
-| `hop wipe [--all]` | Remove workspace-defined sessions (`--all` also kills live sessions) |
-| `quit` | Type at exit prompt to shut down the tunnel |
+| `hop wipe [--all] [--yes]` | Remove workspace-defined sessions (`--all` also kills live sessions after a confirmation; `--yes` skips it) |
+| `hop wipe --agent` | Close all agent-created terminal API sessions |
+
+Local CLI mouse capture is off by default so terminal-native selection and context menus keep working. Use Option+M / Alt+M inside the local Hop view to toggle Hop mouse selection when needed. Use Option+B / Alt+B to toggle the status bar. CLI defaults live under `hay-cli` in `~/.hop.json`.
 
 ### Development
 

package/hay/CHANGELOG.md

@@ -1,10 +1,40 @@
 # Changelog
 
-## [Unreleased]
+## [0.9.0] - 2026-06-12
+
+### New Features
+
+#### CLI Client
+- **Scrollback search (Opt+F)**: incremental search over the buffer; all matches are highlighted (current match bright), `Enter`/`↓` jump to the next match and `↑` to the previous one.
+- **Presence names + take/release control (Opt+C)**: peer names (with typing markers) in the status bar and exclusive-control parity with the web client.
+- **Persistent reconnect indicator**: a banner with the failure reason, countdown to the next retry, and attempt count stays visible while disconnected (CLI and web); the CLI now exits with a clear error if the first ~5 connection attempts never succeed.
+- **Kill confirmation**: `Ctrl+Q` must be pressed twice within 2s to kill the session; the end-of-session message names who killed it and includes the exit code/signal when relevant.
+- **Scroll indicator**: when the viewport is detached from live output the status bar shows `scroll <pos>/<total> · Opt+0 live`; exiting search keeps your scrollback position and hints the way back.
+- **Send-literal escape hatch (Opt+\\)**: forwards the next key verbatim so reserved keys (`Ctrl+Q`/`Ctrl+G`) can reach remote programs.
+- **Hints toggle moved to Opt+T** (was `Ctrl+T`), matching the other Opt toggles; `Ctrl+T` now passes through to the remote terminal (readline transpose-chars, fzf, etc.).
+- **Adaptive bar themes**: status/hint bars auto-detect light vs dark terminal backgrounds (OSC 11 query, `$COLORFGBG` fallback) with truecolor palettes; pin with `--theme light|dark|auto` or `{"hay-cli": {"theme": "dark"}}` in `.hop.json`.
+- **Status bar redesign**: semantic state dot at the right edge (green connected / amber reconnecting / red disconnected / purple locked), session name as an accent chip at the left edge, dim cwd, `·` separators, `manual` shown only when autofit is off.
+- **Bigger reattach scrollback**: the server now retains ~2MB of raw output per room for reattach snapshots (was 200KB, which TUI-heavy streams exhausted in a screenful); override with `HAY_SNAPSHOT_BUFFER_BYTES`. Client scrollback raised to 5000 lines (CLI and web).
+- **Hint bar redesign**: keycap-style hints (`⌃G detach · ⌥F find …` on macOS) with keys at full strength and labels dim; notices render as toasts (`✓` confirmations, `!` warnings, accent edge for info); the hint line surface is one step fainter than the status line.
+- **Clearer session feedback**: "Created new session" vs "Attached to (N participants)" notice on connect, named control-handoff notices ("alice took control…"), friendlier control-locked rejection with the controller's name, and a reattach hint on detach.
+- **CLI argument validation**: unknown flags and extra positional arguments are rejected with an error instead of silently becoming the room name.
+
+#### Server
+- Optional `created` flag on `hello` and `by` attribution on `session_ended` (both backwards compatible).
+- Invalid client messages are rejected with the message type and offending field (e.g. `Invalid resize message: rows …`) instead of a bare "Invalid message".
+
+### Performance
+
+- CLI rendering uses dirty-line diffing with a ~60fps frame throttle, repainting only rows that changed.
 
 ### Bug Fixes
 
 - Fixed the mobile terminal layout so the virtual keyboard anchors to the viewport bottom and no longer leaves a large gap above the screen edge.
+- `Ctrl+Q` while disconnected no longer falsely prints "Session terminated."; it now explains the server is unreachable and that the session may still be running.
+- Tiny terminal windows no longer send `resize` messages below the protocol minimum (2x2), which the server used to reject.
+- Reserved `Ctrl` keys pressed in the brief post-connect grace window are swallowed instead of being forwarded to the remote shell.
+- Mouse-copy notice hedges to "Sent N line(s) to clipboard (OSC 52)" since terminal support for OSC 52 varies.
+- README/`--help` keyboard documentation corrected (all viewport shortcuts require Opt/Alt) and completed (Opt+0, Opt+F, Opt+C, Opt+H/J/K/L, Shift fast-pan, Opt+\\).
 
 ## [0.8.0] - 2025-01-25
 

package/hay/README.md

@@ -68,17 +68,55 @@ After building:
 node apps/cli/dist/index.js -r my-room -n alice
 ```
 
+### Theming
+
+The status and hint bars adapt to your terminal. By default (`auto`) the CLI
+queries the terminal's background color (OSC 11, with `$COLORFGBG` as an
+immediate fallback) and picks a light or dark palette to match. Colors use
+truecolor when `$COLORTERM` advertises support, with 256-color fallbacks.
+
+Pin a palette per run with `--theme light|dark|auto`, or persist it in
+`.hop.json` (local or `~/.hop.json`):
+
+```json
+{ "hay-cli": { "theme": "dark" } }
+```
+
+The dot at the right edge of the status bar is semantic: green = connected,
+amber = connecting/reconnecting, red = disconnected, purple = control locked.
+
 ### Keyboard Shortcuts
 
+`Opt` means the Option key on macOS and `Alt` elsewhere. Run `hay --help` for
+the authoritative, up-to-date list.
+
 | Key | Action |
 |-----|--------|
-| `←` `→` `↑` `↓` | Pan viewport |
-| `0` | Center on cursor |
-| `A` | Auto-fit viewport to content |
-| `M` | Toggle mouse mode |
-| `Ctrl+T` | Toggle hints bar |
-| `Ctrl+G` | Detach from session |
-| `Ctrl+Q` | Kill session |
+| `Opt+←` `Opt+→` `Opt+↑` `Opt+↓` | Pan viewport (add `Shift` for faster panning) |
+| `Opt+H` `Opt+J` `Opt+K` `Opt+L` | Pan viewport, vim-style (`Shift` = faster) |
+| `Opt+0` | Return to live output (center on cursor) |
+| `Opt+A` | Toggle autofit of the remote size to the local window |
+| `Opt+B` | Toggle status bar |
+| `Opt+M` | Toggle mouse capture (off by default, so terminal context menus keep working) |
+| `Opt+F` | Search scrollback (`Enter`/`↓` next, `↑` previous, `Esc` close) |
+| `Opt+C` | Take/release exclusive control |
+| `Opt+T` | Toggle hints bar |
+| `Opt+\` | Send the next key literally to the remote terminal (lets reserved keys like `Ctrl+Q`/`Ctrl+G` reach remote programs) |
+| `Ctrl+G` | Detach from session; the session keeps running |
+| `Ctrl+Q` `Ctrl+Q` | Kill session for all participants (press twice within 2s to confirm) |
+
+`Opt`/`Alt` letter shortcuts arrive as ESC-prefixed keys: on non-macOS
+terminals (and macOS terminals without "Option as Meta") enable the
+option/alt-as-meta or ESC-prefix setting in your terminal emulator for them to
+work.
+
+Local sessions are persistent by default: they keep running in the Hay host if
+the local CLI detaches or the Hop daemon restarts. Use `Ctrl+Q` (pressed twice)
+to end the session itself; reattach to a running session with `hay -r <room>`.
+
+Mouse-selection copy uses OSC 52, so it lands in your local clipboard only if
+your terminal emulator supports and allows OSC 52 clipboard writes (iTerm2,
+kitty, WezTerm, recent tmux with `set-clipboard on`, etc.).
 
 When the viewport is at the bottom, the CLI follows new output automatically.
 If you pan upward to inspect scrollback, incoming output no longer forces the
@@ -100,6 +138,9 @@ Example `.hop.json`:
 {
   "hay-cli": {
     "showHints": true,
+    "showStatusBar": true,
+    "mouseCapture": false,
+    "syncSize": true,
     "scrollOff": 3
   }
 }
@@ -110,6 +151,9 @@ Configuration options:
 | Option | Default | Description |
 |--------|---------|-------------|
 | `showHints` | `true` | Show keyboard shortcut hints at the bottom |
+| `showStatusBar` | `true` | Show the session/status bar |
+| `mouseCapture` | `false` | Capture mouse events for Hop selection and local wheel scrolling |
+| `syncSize` | `true` | Auto-fit the remote terminal size to the local viewport |
 | `scrollOff` | `3` | Lines of context to keep above/below the cursor |
 
 ## Web Client
@@ -188,12 +232,13 @@ Client to server:
 Server to client:
 
 ```ts
-{ type: "hello", clientId, roomId, color, collabMode, controllerId }
+{ type: "hello", clientId, roomId, color, collabMode, controllerId, created? }
 { type: "output", data: string }
 { type: "snapshot", data: string }
 { type: "presence", clients: [...] }
 { type: "collab", enabled, controllerId }
 { type: "input_rejected", reason: string }
+{ type: "session_ended", exitCode, signal, message, by? }
 ```
 
 ## Environment Variables

package/hay/apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hay-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "private": true,
   "bin": {