loreli 0.0.0 → 2.0.0

package/packages/tmux/README.md

@@ -0,0 +1,261 @@
+# loreli/tmux
+
+Zero-dependency Node.js wrapper for tmux with pane-level control and automatic session lifecycle management.
+
+This package exists because no adequate Node.js tmux library provides pane-level management. It wraps the `tmux` CLI binary with a clean async API, mapping each method ~1:1 to a tmux command.
+
+## Installation
+
+```bash
+pnpm add loreli
+```
+
+Requires `tmux` to be installed on the system (`brew install tmux` on macOS, `apt install tmux` on Linux).
+
+## Session Lifecycle
+
+Sessions created via `create()` are tracked in an in-memory set. This enables batch cleanup via `cleanup()` when the orchestrator shuts down gracefully. For crash recovery where in-memory state is lost, `prune()` queries tmux directly by session-name prefix.
+
+The key design insight is **no garbage default windows**. When `create()` is called with a `command` option, that command becomes the initial window's process. tmux auto-destroys a session when its last window dies, so when all agents exit, the session disappears naturally — no orphaned sessions.
+
+The following example shows the recommended spawn pattern used by Loreli's backends. The first agent creates the session, and subsequent agents join as additional windows.
+
+```js
+import { Tmux } from 'loreli/tmux';
+
+const tmux = new Tmux();
+
+// First agent IS the session's initial window — no garbage default window
+const pane1 = await tmux.create('loreli', { cwd: '/tmp', command: './agent1.sh' });
+
+// Second agent joins as an additional window
+const pane2 = await tmux.window('loreli', { cwd: '/tmp', command: './agent2.sh' });
+
+// Both agents die → tmux auto-destroys the session. No orphans.
+```
+
+## API Reference
+
+### `Tmux.available()`
+
+Static method. Returns `true` if tmux is on PATH, `false` otherwise. Does not throw.
+
+```js
+import { Tmux } from 'loreli/tmux';
+
+if (Tmux.available()) {
+  const tmux = new Tmux();
+}
+```
+
+### `new Tmux()`
+
+Creates a new Tmux instance. All subsequent methods are called on this instance. Each instance maintains its own set of tracked sessions.
+
+### Session Management
+
+#### `tmux.create(name, opts?)` → `Promise<string|void>`
+
+Create a new detached tmux session. Throws if a session with the same name already exists.
+
+When `opts.command` is provided, it becomes the initial window's process and the pane ID is returned. When no command is provided, a bare session with an empty default window is created (useful for test sessions with specific dimensions).
+
+- `name` `{string}` — The session name.
+- `opts.width` `{number}` — Initial window width (tmux `-x` flag).
+- `opts.height` `{number}` — Initial window height (tmux `-y` flag).
+- `opts.cwd` `{string}` — Working directory for the initial window.
+- `opts.command` `{string}` — Command for the initial window.
+
+The following example shows creating a session with an agent command as its initial window. The pane ID is returned so you can capture output or set options on the pane.
+
+```js
+// Agent command IS the initial window — no garbage default window
+const paneId = await tmux.create('loreli', {
+  cwd: '/tmp/workspace',
+  command: '/path/to/launch.sh'
+});
+
+// Test session with specific dimensions (no command — bare session)
+await tmux.create('test-session', { width: 200, height: 50 });
+```
+
+#### `tmux.kill(name)` → `Promise<void>`
+
+Kill (destroy) a tmux session. Throws if the session does not exist. Removes the session from the tracked set.
+
+#### `tmux.list()` → `Promise<string[]>`
+
+List all active tmux session names. Returns an empty array when no server is running.
+
+#### `tmux.has(name)` → `Promise<boolean>`
+
+Check whether a session with the given name exists.
+
+#### `tmux.owned()` → `string[]`
+
+Return session names created by this Tmux instance. Synchronous — reads from the in-memory tracking set.
+
+```js
+const tmux = new Tmux();
+await tmux.create('session-a');
+await tmux.create('session-b');
+tmux.owned(); // ['session-a', 'session-b']
+```
+
+#### `tmux.cleanup()` → `Promise<void>`
+
+Kill all sessions created by this instance. Best-effort — errors on individual sessions are swallowed so one stuck session does not prevent others from being cleaned. Clears the tracking set.
+
+This is the recommended path for graceful orchestrator shutdown.
+
+```js
+// In graceful shutdown handler
+await tmux.cleanup();
+```
+
+#### `tmux.prune(prefix?)` → `Promise<string[]>`
+
+Kill all tmux sessions whose name starts with the given prefix (default: `'loreli'`). Queries tmux directly — does not rely on in-memory tracking. Returns the names of sessions that were killed.
+
+This is the crash-recovery / manual-reset path. It is destructive: any matching session is killed regardless of whether its agents are still doing useful work.
+
+```js
+// After a crash, clean up all loreli-prefixed sessions
+const killed = await tmux.prune('loreli');
+// ['loreli', 'loreli-debug', 'loreli-agent-test-12345']
+```
+
+### Stale Session Detection
+
+#### `tmux.stale(name)` → `Promise<boolean>`
+
+Check whether a session exists but was not created by this instance. A session is stale when it survives from a previous MCP server process — the current Tmux instance has no record of it because in-memory tracking is per-process. Stale sessions contain agent panes running with outdated environment variables (API keys, budgets, tokens).
+
+The following example shows the pattern start uses to detect leftover sessions before spawning new agents.
+
+```js
+const tmux = new Tmux();
+if (await tmux.stale('loreli')) {
+  // Session exists from a dead MCP server — agents inside have stale env
+}
+```
+
+#### `tmux.reap(name)` → `Promise<{killed: boolean, panes: number}>`
+
+Destroy a stale session and report what was killed. Only acts on sessions not owned by this instance — owned sessions are left untouched, preventing accidental self-destruction during a start re-run within the same process.
+
+Returns `{killed: true, panes: N}` when a stale session was destroyed, or `{killed: false, panes: 0}` when the session doesn't exist or belongs to this instance.
+
+The following example shows how start reaps stale tmux sessions during its cleanup phase. The pane count is logged so operators know how many ghost agents were terminated.
+
+```js
+const tmux = new Tmux();
+const result = await tmux.reap('loreli');
+if (result.killed) {
+  console.log(`reaped stale session (${result.panes} panes)`);
+}
+```
+
+### Window Management
+
+#### `tmux.window(session, opts?)` → `Promise<string>`
+
+Create a new window in an existing session and return its pane ID (e.g. `%3`). Each agent gets its own full-size window instead of splitting an existing one, avoiding the `no space for new pane` error.
+
+When `opts.command` is provided, the process runs directly without an intermediate shell, avoiding `.zshrc` initialization prompts.
+
+- `session` `{string}` — The target session name.
+- `opts.cwd` `{string}` — Working directory for the new window.
+- `opts.command` `{string}` — Shell command to run directly.
+
+```js
+const paneId = await tmux.window('loreli', {
+  cwd: '/tmp/workspace',
+  command: '/path/to/launch.sh'
+});
+```
+
+### Pane Management
+
+#### `tmux.split(session, opts?)` → `Promise<string>`
+
+Split the current window into a new pane. Returns the new pane ID (e.g. `%3`).
+
+- `opts.cwd` `{string}` — Working directory for the new pane.
+- `opts.vertical` `{boolean}` — Split vertically instead of horizontally.
+
+#### `tmux.send(target, text)` → `Promise<void>`
+
+Send keystrokes followed by Enter to a pane. The `target` is a pane ID (e.g. `%3`).
+
+#### `tmux.keys(target, ...keys)` → `Promise<void>`
+
+Send raw key sequences to a pane without appending Enter. Useful for TUI navigation (arrow keys, Escape, Tab). Each argument is a tmux key name: `Down`, `Up`, `Enter`, `Escape`, etc.
+
+The following example shows navigating a TUI dialog, which is how the Claude backend accepts its bypass-permissions confirmation.
+
+```js
+await tmux.keys(paneId, 'Down');   // Move to "Yes, I accept"
+await tmux.keys(paneId, 'Enter');  // Confirm selection
+```
+
+#### `tmux.capture(target, lines?)` → `Promise<string>`
+
+Capture the visible content of a pane. Uses `-J` to join wrapped lines. Default capture depth is 500 lines.
+
+#### `tmux.command(target)` → `Promise<string>`
+
+Query the current foreground command running in a pane. Returns the process name (e.g. `'zsh'`, `'claude'`, `'codex'`), or empty string if the pane is dead.
+
+```js
+const cmd = await tmux.command(paneId);
+if (cmd === 'claude') { /* agent is still running */ }
+```
+
+#### `tmux.panes(session)` → `Promise<Array<{id, pid, active, title}>>`
+
+List panes in a session with metadata.
+
+#### `tmux.alive(target)` → `Promise<boolean>`
+
+Check whether a specific pane still exists and its process is running. Uses `list-panes` with filtering for reliable detection.
+
+#### `tmux.killPane(target)` → `Promise<void>`
+
+Kill a specific pane by ID.
+
+#### `tmux.set(target, option, value)` → `Promise<void>`
+
+Set a pane-level option. Commonly used with `remain-on-exit` for agent backends:
+
+```js
+await tmux.set(paneId, 'remain-on-exit', 'on');
+```
+
+## Error Handling
+
+| Scenario | Error |
+|----------|-------|
+| tmux not installed | `Tmux.available()` returns `false`; instance methods throw with the underlying stderr message |
+| Session already exists | `create()` throws `Session "<name>" already exists` |
+| Session not found | `kill()` throws with tmux's error message |
+| Pane not found | `killPane()`, `send()`, `capture()` throw with tmux's error message |
+
+## Configuration via loreli/config
+
+When used through Loreli's orchestration layer, the following tmux settings are configurable via `loreli.yml`:
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `tmux.session` | `loreli` | Tmux session name used by `CliAgent` |
+| `tmux.capture` | `500` | Number of history lines captured by `capture()` |
+
+These values are resolved through `loreli/config`'s four-layer resolution (start params > `loreli.yml` > env vars > defaults). When using `loreli/tmux` directly without the orchestration layer, the defaults above apply.
+
+## Testing
+
+```bash
+node --test packages/tmux/test/index.test.js
+```
+
+Tests require tmux to be installed on the system.