agentp 1.12.1 → 1.14.0

package/README.md

@@ -47,7 +47,7 @@ Notes:
 
 - `agentp` connects to the OpenCode event endpoint over HTTP.
 - In practice this means running `opencode serve` (or equivalent serve mode) so the port is open.
-- `opencode attach` is optional but useful to monitor the full conversation in another terminal/tmux pane.
+- `opencode attach` (older OpenCode) / `opencode --server <url>` (OpenCode v2) is optional but useful to monitor the full conversation in another terminal/tmux pane. `ocmux` picks the right form automatically.
 - If the OpenCode server is password-protected (`OPENCODE_SERVER_PASSWORD`), both `agentp` and `ocmux` automatically send the required HTTP Basic Auth credentials.
 
 ## Usage
@@ -59,7 +59,8 @@ agentp [options] [url]
 Options:
 
 - `--qa`: print the original prompt and answer with labels (useful when used as a filter)
-- `--defer`: deferred execution — submit prompt, get immediate ticket, retrieve result later
+- `--defer [N]`: deferred execution — submit a prompt and get a ticket immediately (or wait up to N seconds for the answer and print it if it arrives); pipe the ticket back to retrieve the result later
+- `--onlineTicket`: print deferred tickets on a single line (default: pretty-printed JSON)
 - `--tg`: forward the answer to Telegram via tgagentp gateway (error if unreachable)
 - `--no-tg`: do not forward to Telegram
 - `--flush`: flush tgagentp's recorded buffer without prepending it to output
@@ -72,9 +73,17 @@ Options:
 By default, `--qa` auto-detects tgagentp (silently degrades if unavailable); standalone mode implies `--no-tg`.
 With `--tg`, errors if tgagentp is unavailable.
 
+> **Telegram notification from deferred jobs:** Use `--defer --tg` (or
+> `--defer N --tg`) to forward the answer to Telegram automatically when the
+> background job completes. The detached child process runs the full `--tg`
+> flow, including gateway detection and notification. If the gateway is
+> unreachable at completion time, a warning is printed on stderr; the answer
+> is still saved in the temp file and retrievable via ticket re-submission.
+
 Arguments:
 
 - `url`: OpenCode TUI server URL or port number (defaults to `4096`). Examples: `4096`, `http://localhost:4096`, `http://192.168.1.50:4096`
+- Tip: `$(ocmux)` expands to the URL of the current project's server, so you can run `agentp $(ocmux)` from any shell.
 
 ## Examples
 
@@ -147,18 +156,83 @@ context for a new topic.
 
 Deferred execution with `--defer`:
 
-Submit a prompt and get an immediate ticket to retrieve the result later:
+Submit a prompt and get a ticket to retrieve the result later:
 
 ```bash
-# Submit a prompt and get a deferred reference
+# Submit a prompt and get a deferred ticket (optionally wait up to N seconds)
 DEFERRED=$(printf "Refactor the authentication module" | agentp --defer)
-# Output: <agentp-deferred>/tmp/agentp_deferred_20260803_1430_a1b2.tmp</agentp-deferred>
+# Output: agentp_ticket {
+#            "ctime": "2026-08-03T14:30:00.000Z",
+#            "path": "/tmp/agentp_deferred_20260803_1430_a1b2.tmp",
+#            "server": "http://localhost:4096",
+#            "sessionId": "ses_abc123"
+#          }
+
+# Or wait up to 60s for the answer; only get a ticket if it's not ready in time
+DEFERRED=$(printf "Refactor the authentication module" | agentp --defer 60)
 
 # Continue working... retrieve the result when ready
 printf '%s\n' "$DEFERRED" | agentp --defer
 # Output: (the agent's response)
 ```
 
+`--defer` takes an optional numeric timeout in seconds (default `0`). With a
+timeout, the invocation blocks until the answer arrives or the timeout expires:
+if the answer arrives in time it is printed immediately; otherwise a ticket is
+returned and the agent keeps working in the background.
+
+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.
+- `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.
+
+Tickets are printed as pretty-printed (multi-line) JSON for easier reading and
+editing; pass `--onlineTicket` to print them on a single line instead:
+
+```bash
+printf "Refactor the auth module" | agentp --defer --onlineTicket
+# Output: agentp_ticket {"ctime":"...","path":"/tmp/agentp_deferred_....tmp"}
+```
+
+Both formats are accepted when piping a ticket back to `agentp --defer`.
+
+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:
+
+```bash
+cat <<'EOF' | agentp --defer
+agentp_ticket {
+  "ctime": "2026-08-03T14:30:00.000Z",
+  "path": "/tmp/agentp_deferred_...tmp",
+  "server": "http://localhost:4096",
+  "sessionId": "ses_abc123"
+}
+Also make sure the migration is reversible.
+EOF
+```
+
+If the answer is already ready, the appended text is not sent to OpenCode; it is
+printed after the returned answer so you can edit and re-submit it if needed. In
+`--qa` output, it appears after the final ruler. If the answer is not ready, the
+appended text is sent through OpenCode's async prompt endpoint for the ticket's
+`server`/`sessionId`, stored with the ticket, and the ticket is re-printed with
+updated `elapsed` without echoing the extra text in that interim output. When
+the final answer is later retrieved with `--qa`, all stored follow-ups are
+printed inside the prompt block under `📝` separators. Without `--qa`, stored
+follow-ups are not printed. Older tickets without `server` and `sessionId` can
+still retrieve results, but cannot queue follow-up text.
+
+Piping a ticket back to `agentp --defer` ignores the `--defer` argument and uses
+the ticket's own `defer` value as the timeout (default `0`):
+
+- If the answer is ready, it is returned and the temp file is removed.
+- If not, the ticket is re-printed with the elapsed time updated.
+
 Works as a Vim/Neovim filter with deferred execution:
 
 ```vim
@@ -166,15 +240,18 @@ Works as a Vim/Neovim filter with deferred execution:
 :'<,'>!agentp --defer --qa
 
 " Later, retrieve the result
-:r !printf '%s\n' "<agentp-deferred>/tmp/agentp_deferred_...tmp</agentp-deferred>" | agentp --defer
+:r !printf '%s\n' "$(cat <<'EOF'
+agentp_ticket {"ctime":"2026-08-03T14:30:00.000Z","path":"/tmp/agentp_deferred_...tmp","server":"http://localhost:4096","sessionId":"ses_abc123"}
+EOF
+)" | agentp --defer
 ```
 
 The deferred workflow:
-1. Submit prompt with `--defer` → get immediate ticket (`<agentp-deferred>...</agentp-deferred>`)
+1. Submit prompt with `--defer` → get a ticket (`agentp_ticket {...}`)
 2. Continue working (the agent processes in background)
 3. When ready, pipe the ticket back to `agentp --defer` to retrieve the result
-4. If the agent is still processing, you get your input back (identity filter)
-4. If complete, you get the agent's response and the temp file is cleaned up
+4. If the agent is still processing, you get the ticket back with the elapsed time updated
+5. If complete, you get the agent's response and the temp file is cleaned up
 
 Useful for long-running tasks where you don't want to block your editor.
 
@@ -204,6 +281,8 @@ Subcommands:
   - `--print-logs` passes `--print-logs` to `opencode serve`, which prints server logs to stderr in the server tmux pane.
 - **`kill [dir]`** — Kill the server found upward from `dir`. Removes its tmux window and state file.
 - **`resurrect [--print-logs] [dir]`** — Recover a dead/crashed server: reads `.ocmux.json`, kills old tmux window, removes state file, then creates a fresh server + TUI in the same directory. Works even if no tmux window exists (stale state file).
+- **`model [ref]`** — Switch the model of the newest session on the current project's server. With no `ref`, shows an interactive model picker (TTY required). With `ref`, switches directly and prints the server URL on stdout so `agentp $(ocmux model <ref>)` composes: the switch (a side effect) takes effect before agentp sends the next prompt. `ref` supports partial matches when unique (`ocmux model deepseek`, `opencode-go/deepseek`, `...#high`); multiple matches open the picker (or error when not a TTY).
+- **`switch`** — Interactive session picker: an interactive menu of all running servers (columns: dirname, status, url, full path). Arrow keys or `j`/`k` move the selection; `Enter`/`Space` switches to the selected server's tmux window (the menu stays open, so you can hop between servers); `q` or `Ctrl+C` exits. The currently active server (queried live from tmux on every redraw) is highlighted across the full line width. Prints the URL of the last selected server on exit. Requires a TTY.
 - **`list`** — List all running servers with their directories, URLs, and status.
 
 Options:
@@ -217,6 +296,7 @@ Notes:
 
 - If `<directory>` is not a valid path, `ocmux` tries to match it against the basenames of existing sessions (exact unique match).
 - When using `--git`/`--GIT`, `ocmux` refuses to create a new server above an existing `.ocmux.json` found while searching for the git root.
+- In default mode, if no server is found, the primary error line is printed to stdout. This intentionally makes `agentp $(ocmux)` fail instead of silently falling back to `agentp`'s default `localhost:4096` server.
 
 ### Requirements
 
@@ -246,7 +326,7 @@ The session API ensures the request is processed even when no TUI is attached, a
 
 Operational hint:
 
-- You can keep a separate `opencode attach` view open to see the full run context while `agentp` is used from shell scripts or editor buffers.
+- You can keep a separate TUI view open to see the full run context while `agentp` is used from shell scripts or editor buffers: `opencode --server '<url>' --continue` on OpenCode v2, or `opencode attach --continue '<url>'` on older versions (`ocmux` uses the right one automatically).
 
 ## tgagentp