agentp 2.0.0 → 2.1.0

package/CONTRIBUTING.md

@@ -6,7 +6,8 @@ agentp is a collection of three **zero-dependency** Node.js CLI tools that
 extend [OpenCode](https://opencode.ai) v2:
 
 - **`agentp`** — pipes prompt text into a running OpenCode session and streams the answer back to stdout.
-- **`ocmux`** — manages per-project TUI windows in tmux (session picker, project switcher, create/rename/delete/annotate sessions) on top of a single **user-managed** OpenCode server.
+- **`ocmux`** — routes project sessions and optional user-placed dedicated/shared
+  TUI panes in tmux on top of user-managed OpenCode servers.
 - **`tgagentp`** — bridges a Telegram bot chat with OpenCode (multi-chat, multi-server, file sharing). *Experimental.*
 
 The project aims to stay **zero npm dependencies** — everything uses only the
@@ -42,12 +43,13 @@ npm install -g .
 agentp/
 ├── bin/
 │   ├── agentp            — stdin-to-session pipe
-│   ├── ocmux             — project/TUI window manager + interactive pickers
+│   ├── ocmux             — project/session router + interactive pickers
 │   └── tgagentp          — Telegram bot bridge
 ├── lib/
 │   ├── opencode.js       — OpenCode v2 HTTP/SSE client (shared by all three)
-│   ├── ocmux.js          — tmux helpers (shared by ocmux + tgagentp)
+│   ├── ocmux.js          — registered-TUI routing helpers
 │   ├── project-state.js  — `.ocmux.json` v2 schema + per-session reminders
+│   ├── tui-registry.js   — private runtime registry + tmux pane operations
 │   ├── tui-cmd.js        — tmux send-keys passthrough (tgagentp)
 │   ├── file-share.js     — telegram-shared directory + upload/download
 │   └── telegram-*.js     — Telegram API + formatting helpers
@@ -72,8 +74,8 @@ agentp/
 ### Conventions
 
 - **HTTP:** use `lib/opencode.js` helpers — never raw `http.request`.
-- **tmux:** use `lib/ocmux.js` helpers (`_tmux` / exported wrappers) — never raw
-  `spawnSync`.
+- **tmux TUI registrations:** use `lib/tui-registry.js`; keep socket, pane,
+  token, and PID data out of `.ocmux.json`.
 - **State:** `.ocmux.json` I/O goes through `lib/project-state.js`
   (`readProjectState`, `writeProjectState`, `readAnnotations`, `writeAnnotation`,
   atomic writes). Never hand-roll reads/writes.

package/README.md

@@ -8,7 +8,9 @@
 This package provides three CLI tools:
 
 - **`agentp`** — pipes prompt text into a running OpenCode server and streams the assistant final answer back to stdout
-- **`ocmux`** — manages project TUI windows in tmux on top of a single user-managed OpenCode server (session picker, project switcher, create/rename/delete/annotate sessions)
+- **`ocmux`** — routes project sessions and optionally drives user-placed,
+  registered OpenCode TUI panes in tmux (session picker, project switcher,
+  create/rename/delete/annotate sessions)
 - **`tgagentp`** — bridges a Telegram bot chat with all running OpenCode servers (receives messages from Telegram, routes them to the active server, sends answers back). Supports slash commands for multi-server management, session switching, agent/model listing, including file sharing from the chat.
 
 It is designed for prompt-driven workflows where you want to do things like:
@@ -42,7 +44,7 @@ npm link
 
 - Node.js 18+
 - **OpenCode v2** (`opencode serve`) — the server is user-managed; these tools only check it is reachable and complain otherwise.
-- [tmux](https://github.com/tmux/tmux) when using `ocmux` (project TUI windows).
+- [tmux](https://github.com/tmux/tmux) when using registered `ocmux` TUIs.
 
 ## Servers
 
@@ -214,7 +216,8 @@ The ticket is `agentp_ticket` followed by a JSON object with these fields:
 - `ctime` — creation timestamp (ISO 8601). Only used to compute `elapsed`.
 - `path` — path to the temp file holding the result.
 - `server` — OpenCode server URL used by the deferred job.
-- `sessionId` — OpenCode session ID used by the deferred job.
+- `sessionId` — OpenCode session ID used by a normal deferred job.
+- `sessionIds` — array of OpenCode session IDs used by a **broadcast** deferred job (replaces `sessionId`).
 - `elapsed` — seconds since `ctime`, included only when the ticket is re-printed (not on first print).
 - `defer` — the timeout requested at submission, included only when it was > 0.
 - `cancelled` — always present (defaults to `false`). Set it to `true` and pipe the ticket back to cancel the running job (see below).
@@ -229,6 +232,13 @@ printf "Refactor the auth module" | agentp --defer --onlineTicket
 
 Both formats are accepted when piping a ticket back to `agentp --defer`.
 
+When `ocmux` has a broadcast selection, `agentp --defer` creates a ticket with
+`sessionIds` and sends the prompt to every selected session. On retrieval,
+`--qa` includes the original prompt plus one `💬 <name> [<id>]` answer section
+per session. Individual failures/incomplete sessions are listed with an error
+and timestamp. Broadcast tickets do **not** support queued follow-up text (a
+follow-up is inherently ambiguous across multiple sessions).
+
 You can also append follow-up text after a not-yet-ready ticket to queue more
 input into the original running task, similar to typing into the OpenCode TUI
 while the agent is busy:
@@ -315,59 +325,151 @@ Useful to grab recent answers without sending a new prompt.
 
 ## ocmux
 
-Manage **project TUI windows** in tmux on top of a single user-managed OpenCode
-server. A project is a directory holding a `.ocmux.json` state file recording
-the target session; an `Opencode` tmux session holds one window per project
-(TUI only, pane 0).
+Manage project/session routing on top of a user-managed OpenCode server. A
+project is a directory holding a `.ocmux.json` state file recording its target
+session. TUIs are optional: `ocmux tui` can register any tmux pane as a
+project-dedicated display, while `ocmux tui --shared` registers one fallback
+display that follows session switches from every project.
 
 ```bash
-ocmux [-l] [<subcommand>] [<directory>]
+ocmux [-l] [--all-projects] [<subcommand>] [<directory>]
 ```
 
 Without arguments (and with a TTY), opens an **interactive session picker** for
 the project found upward from `<directory>` (default: `$PWD`):
 
+- the title bar names the project being worked on — `ocmux — <project> sessions`
+  — so the list is never ambiguous
 - sessions are listed most-recently-viewed first
-- `Enter`/`Space` switches (menu stays open) · `n` create (name input) ·
-  `r` rename (edit in place) · `R` set a reminder · `d` delete (confirm) ·
-  `a` switch agent · `m` switch model · `p` project switcher · `h` help ·
-  `q`/`Ctrl+C` quit
-- switching updates `.ocmux.json` and relaunches the TUI on the chosen session
-  (`opencode --server <url> --session <id>`); silent on success
+- `/` starts an **incremental search** of the list (matches title/id,
+  case-insensitive, space-separated tokens are ANDed). While the search line is
+  active it shows `Enter: confirm · Esc: cancel` on the right: `Enter` keeps the
+  filter and returns to normal navigation, `ESC` clears it, `/` resumes editing
+  it, and `Backspace` on an already-empty search also exits it. The same `/`
+  search works in the model/agent pickers and the project switcher.
+- `Enter` switches (menu stays open). `Space` over a different session enters
+  **broadcast mode**: Space selects/deselects sessions; `Enter` keeps the list
+  and switches normally; `ESC`/`q` cancels back to the session list and returns
+  the TUI to the stored session; deselecting down to a single session selects
+  that remaining session. New selections open in the TUI for inspection.
+  Broadcast mode also has `h` help, `d` delete, and `m` to change the model for
+  every selected session.
+- `n` create (name input) · `r` rename (edit in place) · `R` set a reminder ·
+  `d` delete (confirm) · `a` switch agent · `m` switch model · `p` project
+  switcher (inspect-only by default) · `h` help · `q` quit
+- `m` opens the model list **sorted by provider** with the cursor already on the
+  session's **current model** — also in broadcast mode, where it starts from the
+  cursor session's model, so a bulk change begins where you are
+- **`q` only quits the session picker.** In every other menu (model/agent
+  pickers, project switcher, help/input prompts) `q`/`ESC` just closes that menu
+  and returns to the previous one. **`Ctrl+C` fully exits** `ocmux` from any menu.
+- switching updates `.ocmux.json` and refreshes the project's dedicated TUI, or
+  the shared TUI when no live dedicated one exists; silent on success. The file
+  updated is always the one of the project being listed — your own project
+  unless ocmux was started with `--all-projects`
 - new sessions inherit the model of the previously selected session (v2
   sessions created via the API have no model and won't run a prompt until set)
 
 Reminders (`R`) are stored in the `.ocmux.json` `annotations` map; `agentp`
 prepends a session's reminder to every prompt sent to it.
 
+Broadcast selections are stored in `.ocmux.json` as `broadcast`. `agentp`
+sends a prompt to all selected sessions (waiting for busy sessions to go idle),
+and prints a labeled answer section for each. Errors/incomplete targets are
+reported individually with session name, id, error, and timestamp.
+
 Subcommands:
 
-- **`serve [--server <url>] [--git|--GIT] [dir]`** — create a project TUI window
+- **`serve [--server <url>] [--git|--GIT] [dir]`** — initialize project state
   (checks the server is reachable first). Aliased as `new` for backwards
   compatibility. `--git`/`--GIT` resolve `dir` to the nearest parent with a
   `.git` entry / directory.
+- **`tui [--shared] [--server <url>] [dir]`** — register the current tmux pane and run OpenCode
+  in it. Without `--shared`, the pane follows only that project. With
+  `--shared`, it becomes the one fallback TUI for all projects and can reconnect
+  across server URLs as selections change. Re-registering a slot stops its old
+  wrapper without destroying the old pane. Closing the TUI unregisters it.
+  `tui --list` lists live registrations; `tui [--shared] --status` inspects a
+  dedicated/shared slot; `tui [--shared] --detach` unregisters that slot without
+  closing the pane or its current TUI.
 - **`session <id|title> [dir]`** — non-interactive session switch.
-- **`list [-l]`** — list project windows (with `-l`, their server URL).
-- **`model [ref]`** — switch the model of the selected session.
-- **`kill [dir]`** — close the project's TUI window. **Keeps `.ocmux.json`**
-  (session memory; marks it `stopped`).
-- **`resurrect [dir]`** — recreate the project window from its state file.
+- **`list [-l]`** — list configured projects and whether their route is
+  `project`, `shared`, or `headless` (with `-l`, their server URL).
 - **`migrate`** — rewrite legacy (v1-style) `.ocmux.json` files to the v2 schema.
 
 The old `switch` subcommand is gone: press **`p`** inside the session picker to
-open the (read-only) project switcher instead. `ocmux` never starts or stops the
+open the project switcher instead. The switcher is a **foldable tree**: `▸`/`▾`
+marks a project as folded/unfolded, `Space` folds/unfolds a project's sessions
+(fetched once per project, most recent first), and `/` searches projects *and*
+their unfolded sessions (a matching session keeps its project header visible).
+
+By default the switcher is an **inspector**: `Enter` on a project row routes its
+current session to the applicable registered TUI, `Enter`/`Space` on a session
+row shows that session, and you **always come back to your own project's
+list** when you leave it (`q`). No `.ocmux.json` is ever written from there, so
+`agentp` — which reads the state file of the directory it runs in — keeps
+prompting your own project's session.
+
+Pass **`--all-projects`** to turn it into a real switcher: selecting a project
+then moves the session picker over to that project, and picking a session there
+updates *that* project's `.ocmux.json` (which is what `agentp` reads when it
+runs in that directory). The title bar always names the project being listed, so
+either way you can tell where you are. `ocmux` never starts or stops the
 OpenCode server — run `opencode serve` yourself (see [Versioning](#versioning)
 for the pairing policy).
 
-Options: `-l` · `--version` · `-h` · `--` (treat the next argument as a directory).
+Options: `-l` · `--all-projects` · `--shared` (only with `tui`) · `--version` ·
+`-h` · `--` (treat the next argument as a directory). There is no `--global`
+alias.
 
 Notes:
 
-- If `<directory>` is not a valid path, `ocmux` matches it against the basenames
-  of existing project windows (exact unique match).
 - If the server is password-protected (`OPENCODE_SERVER_PASSWORD`), both
   `agentp` and `ocmux` send the required HTTP Basic Auth credentials.
 
+### TUI runtime registry
+
+TUI placement is ephemeral and is never written to `.ocmux.json`. Registrations
+live in `$XDG_RUNTIME_DIR/agentp/ocmux-tuis.json` (falling back to a private
+`/tmp/agentp-<uid>/` directory); `OCMUX_RUNTIME_DIR` overrides that location.
+The directory is mode `0700`, registry files are mode `0600`, and updates use a
+lock plus atomic rename.
+
+A registration stores the tmux socket, pane ID, diagnostic wrapper PID, and a
+random pane verification token. Matching ID/token options are also written to
+the pane before it can be respawned. This prevents stale entries from targeting
+an unrelated pane and lets a pane move between windows or tmux sessions on the
+same socket without re-registering. Dead registrations are pruned when queried.
+
+Closing OpenCode makes its foreground `ocmux tui` wrapper unregister itself if
+it still owns the token. Replacing a dedicated/shared registration interrupts
+the previous wrapper but preserves its pane. `--detach` only unregisters and
+clears the pane markers; it does not close the pane or the OpenCode process.
+
+Registry commands:
+
+```bash
+ocmux tui                         # dedicated TUI for the current project
+ocmux tui /path/to/project        # dedicated TUI for another project
+ocmux tui --shared                # the single cross-project fallback TUI
+ocmux tui --list                  # all live dedicated/shared registrations
+ocmux tui --status                # current project's dedicated slot
+ocmux tui --status --shared       # shared slot
+ocmux tui --detach                # unregister current project's slot
+ocmux tui --detach --shared       # unregister shared slot
+```
+
+Routing precedence is:
+
+1. a live TUI dedicated to the selected project;
+2. the single live shared TUI;
+3. headless operation (the session still switches successfully).
+
+Switching respawns the registered pane with `ocmux tui`, which reconnects
+OpenCode to the selected server, directory, and session. Server-side work keeps
+running, but client-local TUI state such as a draft prompt or scroll position is
+lost during the refresh.
+
 ### State file
 
 `.ocmux.json` (in the project directory) stores `version`, `directory`,
@@ -380,8 +482,8 @@ gitignored — never commit it.
 2. Resolves the target from the nearest `.ocmux.json`: server URL, project
    directory, and the stored session id (falls back to the most recently viewed
    session in that directory, or creates one pinned to the directory).
-3. Focuses the project's TUI window, prepends the session annotation (if any),
-   and sends the prompt via the v2 session API (`POST /api/session/:id/prompt`,
+3. Prepends the session annotation (if any) and sends the prompt via the v2
+    session API (`POST /api/session/:id/prompt`,
    delivering to that session regardless of what the TUI shows).
 4. Attaches to the SSE stream first so no events are missed, and streams text
    until the session is quiescent after its terminal signal.
@@ -423,7 +525,7 @@ Non-text Telegram updates (photos, stickers, etc.) are silently ignored.
 | `/servers` | List all ocmux-served projects (▶ active, 🔌 disconnected, 💀 dead) |
 | `/server <name>` | Switch active server; matches by full path, basename, or substring |
 | `/server --force <name>` | Take over a server from another chat |
-| `/resurrect [path]` | Restart a crashed server from its `.ocmux.json`; accepts optional directory path |
+| `/resurrect [path]` | Check the configured user-managed server and explain how to restart it externally |
 | `/sessions` | List sessions (numbered, newest first) |
 | `/session <name-or-number>` | Switch to a session by name or position |
 | `/session new [name]` | Create a new session |