@mentiko/pty-mgr 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+## 1.3.0 - 2026-07-02
+
+### Added
+
+- `p view <name1> <name2> [interval]` — live, read-only side-by-side session
+  viewer. Renders two sessions in split panes with a divider and name headers,
+  refreshes on an interval (default `500ms`), handles terminal resizes, and
+  exits cleanly on `q` / `Ctrl-C`. Requires at least 21 terminal columns.
+- `p flow show <name>` — prints a single configured flow in detail: agents and
+  their adapter kinds, the start target, each turn's routing and steering text,
+  and cycle/interval/settle settings. Errors on unknown flow names.
+- `p flow list --verbose` — shows each flow's agents, adapter kinds, start
+  target, and maxCycles alongside the flow name.
+- `code-review` flow added to the shipped `pty-mgr.config.json`: Codex writes,
+  Claude reviews the actual `git diff` on disk, and Codex applies the fixes.
+
+### Fixed
+
+- Flow prompt submission: sending a prompt to a freshly booted TUI could leave
+  the text typed but un-submitted (Enter races startup), so no transcript was
+  ever created and the flow waited out the full timeout with zero turns. Now
+  confirms the sent message appears in the agent's transcript and nudges with a
+  bare Enter if not; a stranded start fails fast with a clear reason.
+- Waits for the agent CLI to boot before sending the first prompt.
+
+## 1.2.11 - 2026-06-06
+
+### Fixed
+
+- Made the standalone `p demo` command exit explicitly after cleanup so
+  linux PTY handles cannot keep Bun alive after the demo prints complete.
+
+## 1.2.10 - 2026-06-06
+
+### Fixed
+
+- Replaced the demo smoke test's interactive shell prompt dependency with a
+  deterministic scripted PTY shell reader.
+- Added a CI timeout around the demo smoke step so future PTY hangs fail loudly
+  instead of parking the workflow.
+
+## 1.2.9 - 2026-06-06
+
+### Fixed
+
+- Made `waitFor` poll the rendered screen while listening for data so fast
+  command output cannot be missed between spawn and listener timing.
+- Made the demo smoke test exit its interactive shell cleanly and verify `kill`
+  with a separate disposable process so CI cannot hang on a lingering PTY.
+
+## 1.2.8 - 2026-06-06
+
+### Fixed
+
+- Made the demo smoke test spawn `zsh -f` so CI cannot be blocked by user
+  startup files or compinit prompts.
+
+## 1.2.7 - 2026-06-06
+
+### Fixed
+
+- Moved the demo smoke check out of the concurrent `bun test` suite; CI still
+  runs it as its own dedicated step.
+- Made `waitForExit` tests use a self-exiting PTY command instead of sending
+  `exit` into an interactive shell before the prompt is ready.
+
+## 1.2.6 - 2026-06-06
+
+### Fixed
+
+- Fixed a CI-only test race where delayed PTY test callbacks could fire after
+  test cleanup destroyed their sessions.
+- Supersedes the v1.2.5 tag for the same agent-flow feature set with a stable
+  CI run.
+
+## 1.2.5 - 2026-06-06
+
+### Added
+
+- Added `p flow list` and `p flow run <name> --task <text>` for configurable
+  multi-agent workflows.
+- Added `pty-mgr.config.json` with Claude and Codex adapter examples plus
+  `spec-writer` and `review-loop` flow examples.
+- Added config-driven transcript parsing for sent user messages and completed
+  assistant messages so flows can route between CLI tools without hardcoded
+  agent-specific logic.
+- Added flow regression tests for competing transcripts, reused sessions, custom
+  adapters, steering templates, and CLI argument handling.
+
+### Changed
+
+- Promoted the agent relay prototype into the main single-file implementation
+  under `lib/pty-manager.mjs`.
+- Removed the old demo relay harness and standardized on `pty-mgr.config.json`.
+- Improved setup wrappers, daemon argument parsing, wrap shell quoting, and
+  client-supplied environment filtering.
+
+### Fixed
+
+- Fixed flow relay log binding so `p watch` completion cannot cause the relay to
+  grab another active agent's newer transcript.
+- Fixed reused-session flow handling by binding to the sent prompt instead of
+  filtering only by transcript start time.
+- Fixed `@...` payload handling so messages like `@everyone` are not mistaken
+  for daemon selectors after the command position.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Almazan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -19,15 +19,23 @@ Compiles to a single self-contained binary via `bun build --compile`.
 ### Binary (no dependencies)
 
 ```
-curl -fsSL https://raw.githubusercontent.com/maarco/pty-mgr/main/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/kollaborai/pty-mgr/main/install.sh | sh
 ```
 
 Installs to `~/.pty-mgr/bin/` and adds to PATH. Works on Linux and macOS (x64, arm64).
 
+### NPM package
+
+```
+npm install -g @mentiko/pty-mgr
+```
+
+Installs the wrapper plus the platform binary for your OS/arch.
+
 ### Bun package (for library use)
 
 ```
-bun add pty-mgr
+bun add @mentiko/pty-mgr
 ```
 
 Requires [Bun](https://bun.sh) runtime.
@@ -37,7 +45,7 @@ Requires [Bun](https://bun.sh) runtime.
 ### As a library
 
 ```js
-import { PtyManager } from 'pty-mgr';
+import { PtyManager } from '@mentiko/pty-mgr';
 
 const mgr = new PtyManager();
 mgr.spawn('my-session', 'zsh', [], { cols: 120, rows: 30 });
@@ -75,9 +83,18 @@ p send agent-1 "fix the login bug"
 # capture rendered screen (last 20 lines)
 p capture agent-1 20
 
+# send raw text with no trailing enter
+p send agent-1 --raw "partial input"
+
+# poll whether a session is still working (diffs two captures)
+p watch agent-1 4s
+
 # attach interactively (ctrl-] to detach)
 p attach agent-1
 
+# watch two sessions side-by-side, live (q or Ctrl-C to exit)
+p view agent-1 agent-2
+
 # rename a session
 p rename agent-1 agent-refactored
 
@@ -85,10 +102,164 @@ p rename agent-1 agent-refactored
 p capture all 50
 p kill refa*
 
+# daemon status + config
+p status
+
 # stop daemon
 p stop
 ```
 
+## Command Reference
+
+Every command (`p --help`):
+
+| Command | Description |
+|---------|-------------|
+| `p daemon` | Start daemon (forks to background) |
+| `p daemon @myproject` | Named daemon (isolated sessions) |
+| `p status` | Daemon info + config |
+| `p config` | Show current config |
+| `p config screen 100x50` | Set default terminal size |
+| `p config cap-on-send on\|off` | Return a capture with every send |
+| `p config send-delay <ms>` | Delay before enter (default 1000) |
+| `p spawn <name> [cmd] [args...]` | Create session (default `zsh`) |
+| `p wrap [cmd] [args...]` | Spawn with auto-incrementing cwd name |
+| `p attach <name>` | Interactive mode (ctrl-] detach) |
+| `p view <name1> <name2> [interval]` | Read-only split-pane live viewer |
+| `p send <name> <text>` | Send text + enter |
+| `p send <name> --raw <text>` | Send text as-is (no enter) |
+| `p capture <name> [lines]` | Capture rendered screen |
+| `p capture all [lines]` | Capture from all sessions |
+| `p capture <glob*> [lines]` | Capture matching sessions |
+| `p watch <name> [interval]` | Diff two bottom-100 captures → `done`/`working` |
+| `p list` | List all sessions |
+| `p alive <name>` | Check if a session is alive |
+| `p info <name>` | Session details |
+| `p kill <name>` | Kill session |
+| `p kill all` | Kill all sessions |
+| `p kill <glob*>` | Kill matching sessions |
+| `p rename <old> <new>` | Rename a session |
+| `p remove <name\|all\|glob*>` | Kill + remove |
+| `p log <name> on [jsonl\|raw\|rendered]` | Start logging |
+| `p log <name> off` | Stop logging |
+| `p spawn <name> --log [cmd]` | Spawn with logging (jsonl) |
+| `p stop` | Stop current daemon |
+| `p stop all` | Stop all daemons |
+| `p setup` | Wrap CLI tools (claude, etc.) |
+| `p flow list [--verbose] [--config file]` | List configured agent workflows |
+| `p flow show <name> [--config file]` | Show one configured agent workflow in detail |
+| `p flow run <name> --task <text>` | Run a configured agent workflow |
+| `p tg <message>` | Send a Telegram notification |
+| `p tg <message> --reply [--timeout N]` | Send and block for a reply |
+| `p demo` | Run self-test (no daemon needed) |
+
+`p watch <name> [interval]` captures the bottom 100 lines, waits `interval`
+(default `4s`; accepts `4s`, `1000ms`, or a bare millisecond value), captures
+again, and prints `done` if the screen is unchanged or `working` if it moved —
+a cheap idle check for polling long-running agents.
+
+## Side-by-Side Viewer
+
+`p view <name1> <name2>` renders two sessions side-by-side in split panes with a
+vertical divider and live refresh. It's read-only — great for watching two agents
+work in parallel (e.g. a writer and a reviewer in a code-review flow) without
+switching terminals.
+
+```
+p daemon
+
+# spawn two agents
+p spawn writer claude
+p spawn reviewer claude
+
+# watch both live, side-by-side (refresh every 500ms by default)
+p view writer reviewer
+
+# custom refresh interval (4s, 1000ms, or bare milliseconds)
+p view writer reviewer 1000ms
+
+# "v" is an alias for "view"
+p v writer reviewer
+```
+
+The viewer enters the alternate screen, draws a header row with each session's
+name, refreshes both panes on the interval you set, and handles terminal resizes.
+Press `q` or `Ctrl-C` to exit. Requires at least 21 terminal columns.
+
+## Agent Flows
+
+`p flow` runs configurable agent-collaboration workflows. The workflow lives in
+`pty-mgr.config.json`; the binary provides the PTY/session/log plumbing.
+
+```
+p daemon
+p flow list                          # list configured flow names
+p flow list --verbose                # show each flow's agents + routing
+p flow show code-review              # full detail: agents, turns, settings
+p flow run spec-writer --task "Create a spec for the auth rewrite."
+p flow run review-loop --task "Review this repo." --max-cycles 2
+
+# one agent implements, another reviews the real git diff, the first revises
+p flow run code-review --task "Add rate limiting to the /login route" --cwd ~/dev/myapp
+```
+
+Both agents in a flow launch in the same working directory (`--cwd`, or wherever
+you run the command), so a reviewer agent can open the actual files the writer
+produced — not just react to its chat summary.
+
+A flow has:
+
+- `adapters`: how to launch each CLI and parse sent user + assistant logs.
+- `agents`: named participants in a workflow, each using an adapter kind.
+- `start`: which agent receives the initial task.
+- `turns`: routing and steering templates between agents.
+
+Useful run flags:
+
+- `--goal <text>`: separate long-running goal text from the initial task.
+- `--max-cycles <n>`: override the workflow's configured cycle count.
+- `--watch-interval <duration>`: compare bottom-100-line captures after this
+  interval to detect a stable screen (`4s`, `1000ms`, or a bare millisecond
+  value; default `10s`).
+- `--interval-ms <n>`: poll cadence between stability checks (default `1000`).
+- `--settle-ms <n>`: wait after a stable capture before reading the transcript.
+- `--timeout-ms <n>`: return incomplete instead of waiting forever.
+
+Example steering:
+
+```json
+{
+  "from": "author",
+  "to": "reviewer",
+  "append": "Based on this, what gaps do you see and what should change next?"
+}
+```
+
+Supported template variables:
+
+- `{task}`: the initial task passed on the CLI.
+- `{goal}`: `--goal` if provided, otherwise the task.
+- `{lastMessage}`: the completed assistant response being relayed.
+- `{cycle}`: current cycle number.
+- `{from}` / `{to}`: source and target agent names.
+
+The shipped `pty-mgr.config.json` includes three examples for Claude/Codex:
+
+- `spec-writer`: author drafts, reviewer critiques, author revises.
+- `review-loop`: two agents trade a task back and forth.
+- `code-review`: Codex implements the task, then Claude reviews the actual
+  `git diff` (correctness, edge cases, security) and Codex applies the fixes.
+  This is the "one agent writes code, another reviews it" workflow — run it
+  with `p flow run code-review --task "..." --cwd <repo>`.
+
+Add new adapters for Gemini, OpenCode, or another CLI by defining where that
+tool stores JSONL logs and how to extract the latest sent user message and
+completed assistant message.
+
+Flow transcript lookup is bound to the exact user prompt sent to the session,
+then assistant extraction starts after that prompt. That prevents one active
+agent from accidentally relaying another agent's newer log.
+
 ### CLI Aliases
 
 | Short | Full    | Short | Full    |
@@ -96,7 +267,7 @@ p stop
 | n/new  | spawn   | w/wrap  | wrap    |
 | s      | send    | k       | kill    |
 | c/cap  | capture | l/ls    | list    |
-| a      | attach  | r/rm    | remove  |
+| a      | attach  | v       | view    |
 | st     | status  | mv/ren  | rename  |
 | i      | info    | d       | daemon  |
 | cfg    | config  | x       | stop    |
@@ -136,7 +307,7 @@ $ p attach my-app-1          # jump back into agent 1
 ### Programmatic (parallel agents)
 
 ```js
-import { PtyManager } from 'pty-mgr';
+import { PtyManager } from '@mentiko/pty-mgr';
 
 const mgr = new PtyManager();
 
@@ -159,6 +330,49 @@ for (const name of agents) {
 mgr.destroyAll();
 ```
 
+## Telegram Remote Control
+
+Drive your sessions from Telegram — check on agents, capture output, send input,
+and get notified when a task needs you, all from your phone.
+
+Set two env vars before starting the daemon:
+
+```
+export TELEGRAM_BOT_TOKEN=<token from @BotFather>
+export TELEGRAM_CHAT_ID=<your chat id>
+p daemon
+```
+
+When `TELEGRAM_BOT_TOKEN` is set, the daemon starts a bot poller automatically.
+Only messages from `TELEGRAM_CHAT_ID` are honored. Bot commands:
+
+| Command | Description |
+|---------|-------------|
+| `/list` (`/ls`) | List sessions |
+| `/capture <name> [lines]` (`/cap`, `/c`) | Capture output (defaults to last used session) |
+| `/send <name> <text>` (`/s`) | Send text + enter, then auto-capture once the session settles |
+| `/kill <name>` (`/k`) | Kill a session |
+| `/spawn <name> [cmd]` (`/n`) | Spawn a session |
+| `/status` | Daemon info |
+| `/help` (`/start`) | List commands |
+
+`/capture` and `/send` remember the last session you touched, so you can omit
+the name on follow-ups.
+
+From inside a session (or a script), push notifications the other direction with
+the `tg` command:
+
+```
+p tg "build finished, needs review"          # fire-and-forget notification
+p tg "approve deploy? (y/n)" --reply          # block until you reply, print it
+p tg "still there?" --reply --timeout 120     # wait up to 120s (default 60)
+```
+
+`--reply` blocks the caller until you answer in Telegram and prints your reply to
+stdout — useful for human-in-the-loop gates inside an agent flow. The `tg` sender
+uses `PTY_MGR_SESSION` (set automatically in wrapped/managed sessions) to tag
+which session is asking.
+
 ## Daemon Protocol
 
 The daemon listens on a Unix socket at `~/.pty-manager/<name>.sock`.
@@ -169,9 +383,17 @@ Communication is newline-delimited JSON:
 {"cmd": "wrap", "args": {"cmd": "zsh", "cwd": "/Users/you/dev/myproject"}}
 {"cmd": "send", "name": "agent-1", "args": {"text": "echo hi\r"}}
 {"cmd": "capture", "name": "agent-1", "args": {"lines": 20}}
+{"cmd": "resize", "name": "agent-1", "args": {"cols": 120, "rows": 40}}
 {"cmd": "list"}
+{"cmd": "info", "name": "agent-1"}
+{"cmd": "alive", "name": "agent-1"}
+{"cmd": "status"}
+{"cmd": "config", "args": {"key": "screen", "value": "120x40"}}
+{"cmd": "log", "name": "agent-1", "args": {"action": "on", "format": "jsonl"}}
 {"cmd": "kill", "name": "agent-1"}
+{"cmd": "remove", "name": "agent-1"}
 {"cmd": "rename", "name": "agent-1", "args": {"newName": "agent-refactored"}}
+{"cmd": "tg-send", "args": {"message": "done"}}
 {"cmd": "shutdown"}
 ```
 
@@ -181,10 +403,15 @@ interactive use.
 ## Configuration
 
 ```
+p status                     # daemon info + current config
+p config                     # show current config
 p config screen 120x40       # default terminal size for new sessions
 p config cap-on-send on      # return capture with every send command
+p config send-delay 500      # ms to wait before the trailing enter (default 1000)
 ```
 
+Config persists in the daemon and applies to new sessions.
+
 ## Logging
 
 ```