@mentiko/pty-mgr 1.4.1 → 1.4.2

package/lib/pty-manager.mjs

@@ -1,30 +1,27 @@
 #!/usr/bin/env bun
 /**
- * pty-manager.mjs - PTY-based agent session manager
+ * pty-manager.mjs (v2) - PTY-based agent session manager
  *
  * Uses:
  *   - Bun.spawn        native PTY support (no python, no native addons)
  *   - @xterm/headless   terminal emulator (parses escape codes into screen)
  *
- * capture() returns the actual rendered screen state, not raw output.
+ * capture() returns the actual rendered screen state, not raw output:
  * spinners, progress bars, cursor movements, and TUI redraws are all
  * resolved into clean text.
  *
- * API:
- *   mgr.spawn(name, cmd)       create session
- *   mgr.sendKeys(name, text)   send keystrokes
- *   mgr.capture(name, lines)   capture rendered screen
- *   mgr.has(name)              check if session exists
- *   mgr.kill(name)             kill session
- *   mgr.list()                 list sessions
- *   mgr.pid(name)              get child process pid
+ * v2 refactor: deduplicated the socket client, terminal-size clamps,
+ * capture-stability check, `--log` wiring, telegram send, and transcript
+ * listing; hardened error handling on the socket read path, the attach
+ * input path, and the log write stream. Behavior and the public API are
+ * unchanged (see the test suite).
  *
- * Usage:
- *   import { PtyManager } from './pty-manager.mjs';
+ * Library API:
  *   const mgr = new PtyManager();
- *   mgr.spawn('agent-1', 'claude', ['--print']);
- *   mgr.sendKeys('agent-1', 'fix the bug\r');
- *   console.log(mgr.capture('agent-1', 40));
+ *   mgr.spawn('agent-1', 'claude', ['--print']);  // create session
+ *   mgr.sendKeys('agent-1', 'fix the bug\r');      // send keystrokes
+ *   mgr.capture('agent-1', 40);                    // rendered screen
+ *   mgr.has(name) / mgr.kill(name) / mgr.list() / mgr.pid(name)
  */
 
 import { EventEmitter } from "node:events";
@@ -39,12 +36,13 @@ import {
   readdirSync,
   statSync,
   writeFileSync,
+  appendFileSync,
 } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { spawn as spawnChild } from "node:child_process";
 
 // kept in sync by scripts/version-sync.cjs (rewrites this literal on release)
-export const VERSION = "1.4.1";
+export const VERSION = "1.4.2";
 import xterm from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 
@@ -68,6 +66,15 @@ export function validateSessionName(name) {
   }
 }
 
+// terminal-size clamps: keep buffers sane, prevent memory exhaustion from a
+// hostile/typo'd size. shared by PtySession.resize and the daemon spawn/wrap.
+function clampCols(value, fallback) {
+  return Math.max(20, Math.min(500, value || fallback));
+}
+function clampRows(value, fallback) {
+  return Math.max(5, Math.min(200, value || fallback));
+}
+
 class PtySession {
   constructor(name, opts = {}) {
     this.name = name;
@@ -152,16 +159,9 @@ class PtySession {
   }
 
   /**
-   * capture the rendered screen buffer.
-   *
-   * returns what you'd actually see on the terminal right now.
-   * escape codes, cursor movements, line erases -- all resolved.
-   * equivalent of reading the full terminal screen buffer.
-   *
-   * @param {number} [tailLines] - last N lines (0 or omit = visible screen)
-   * @param {object} [opts] - options
-   * @param {boolean} [opts.screen] - only capture visible rows (skip scrollback)
-   * @returns {string}
+   * capture the rendered screen: what you'd see now, with escape codes, cursor
+   * moves and line-erases all resolved. tailLines>0 returns the last N lines;
+   * opts.screen limits to visible rows (skips scrollback).
    */
   capture(tailLines, opts = {}) {
     const buf = this.terminal.buffer.active;
@@ -187,21 +187,15 @@ class PtySession {
     return lines.join("\n");
   }
 
-  /**
-   * capture the rendered screen with ANSI color/attribute escape codes.
-   * uses @xterm/addon-serialize to preserve colors, bold, etc.
-   * @returns {string}
-   */
+  /** rendered screen with ANSI color/attribute codes (via addon-serialize). */
   captureAnsi() {
     return this._serializer.serialize();
   }
 
   /**
-   * capture visible content with ANSI colors, trimmed of empty lines.
-   * reads cells individually to build colored output line by line.
-   * result starts from line 0 (no leading empty rows).
-   * @param {number} [tailLines] - last N lines (0 = all content)
-   * @returns {string}
+   * visible content with ANSI colors, trimmed of leading/trailing empty lines.
+   * reads cells individually (line by line) so colors/attributes survive.
+   * tailLines>0 = last N lines.
    */
   captureAnsiCompact(tailLines) {
     const buf = this.terminal.buffer.active;
@@ -289,14 +283,10 @@ class PtySession {
     return lines.join("\r\n");
   }
 
-  /**
-   * resize the PTY and headless terminal.
-   * @param {number} cols
-   * @param {number} rows
-   */
+  /** resize the PTY and headless terminal (clamped to sane bounds). */
   resize(cols, rows) {
-    cols = Math.max(20, Math.min(500, cols));
-    rows = Math.max(5, Math.min(200, rows));
+    cols = clampCols(cols, cols);
+    rows = clampRows(rows, rows);
     this.terminal.resize(cols, rows);
     if (this._pty && !this.exited) {
       try { this._pty.resize(cols, rows); } catch {}
@@ -335,15 +325,10 @@ class PtySession {
   }
 
   /**
-   * start logging session output to a file.
-   *
-   * format:
+   * start logging session output to a file. format:
    *   "raw"      - raw PTY bytes (escape codes included, replayable)
-   *   "rendered"  - clean screen snapshots on each data event
-   *   "jsonl"     - timestamped JSON lines { t, type, data }
-   *
-   * @param {string} logPath - file path to write to
-   * @param {string} [format="raw"] - log format
+   *   "rendered" - clean screen snapshots on each data event
+   *   "jsonl"    - timestamped JSON lines { t, type, data }
    */
   startLog(logPath, format = "raw") {
     if (this._logStream) this.stopLog();
@@ -354,6 +339,10 @@ class PtySession {
     this._logPath = logPath;
     this._logFormat = format;
     this._logStream = createWriteStream(logPath, { flags: "a" });
+    // a write error (disk full, perms, unlinked path) emits 'error'; without a
+    // listener node throws it as uncaught and takes the daemon down. drop
+    // logging on error rather than crash the session.
+    this._logStream.on("error", () => { try { this.stopLog(); } catch {} });
 
     // write header for jsonl
     if (format === "jsonl") {
@@ -470,18 +459,9 @@ export class PtyManager {
   }
 
   /**
-   * spawn a command inside a real PTY with terminal emulation
-   *
-   * @param {string} name - unique session name
-   * @param {string} cmd - command to run
-   * @param {string[]} [args] - arguments
-   * @param {object} [opts]
-   * @param {string} [opts.cwd] - working directory
-   * @param {object} [opts.env] - extra env vars
-   * @param {number} [opts.cols] - terminal columns (default 200)
-   * @param {number} [opts.rows] - terminal rows (default 50)
-   * @param {number} [opts.scrollback] - scrollback lines (default 5000)
-   * @returns {string} session name
+   * spawn a command inside a real PTY with terminal emulation. opts: cwd, env
+   * (extra vars), cols (default 100), rows (default 35), scrollback (5000).
+   * returns the session name.
    */
   spawn(name, cmd, args = [], opts = {}) {
     validateSessionName(name);
@@ -776,9 +756,11 @@ function startDaemon() {
       });
 
       conn.on("data", async (data) => {
-        // in attach mode, forward raw input to the pty
+        // in attach mode, forward raw input to the pty. the session can exit
+        // between attach and this write (write() throws once exited); swallow
+        // so a late keystroke can't crash the daemon's data handler.
         if (attached) {
-          attached.write(data.toString());
+          try { attached.write(data.toString()); } catch {}
           return;
         }
 
@@ -878,15 +860,9 @@ function startDaemon() {
 
     async function tgSend(chatId, text) {
       const token = process.env.TELEGRAM_BOT_TOKEN;
-      // telegram max message length is 4096
-      const chunks = [];
-      for (let i = 0; i < text.length; i += 4000) chunks.push(text.slice(i, i + 4000));
-      for (const chunk of chunks) {
-        await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ chat_id: chatId, text: chunk }),
-        });
+      // telegram max message length is 4096; chunk under it
+      for (let i = 0; i < text.length; i += 4000) {
+        await telegramSend(token, chatId, text.slice(i, i + 4000));
       }
     }
 
@@ -1088,6 +1064,15 @@ export function buildSafeEnv(extra) {
   return safeEnv;
 }
 
+// start default jsonl logging for a session, under the session's own cwd (the
+// client's dir, not the daemon's frozen cwd). used by the `--log` shortcut on
+// spawn/wrap; the `log` command does its own format/dir handling. returns path.
+function startDefaultLog(mgr, name) {
+  const logPath = join(mgr.get(name).cwd, "agents", "logs", `${name}-${Date.now()}.jsonl`);
+  mgr.get(name).startLog(logPath, "jsonl");
+  return logPath;
+}
+
 // POSIX single-quote escaping: wrap in '...' and replace each ' with '\''.
 // Makes a token literal to the shell -- no expansion, no command substitution,
 // no word splitting. Used to build the `zsh -lic` command line for `wrap`.
@@ -1095,6 +1080,17 @@ export function shellQuote(arg) {
   return `'${String(arg).replace(/'/g, "'\\''")}'`;
 }
 
+// one place that talks to the Telegram Bot API. returns the fetch promise so
+// callers keep their existing error semantics (handleCommand's try/catch for
+// the tg-send/tg-wait commands; the poller's own catch for notifications).
+function telegramSend(token, chatId, text) {
+  return fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ chat_id: chatId, text }),
+  });
+}
+
 async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
   const { cmd, name, args } = req;
 
@@ -1153,8 +1149,8 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       const cmdToRun = args?.cmd || "zsh";
       const cmdArgs = args?.args || [];
       // clamp terminal size to prevent memory exhaustion
-      const cols = Math.max(20, Math.min(500, args?.cols || config.cols));
-      const rows = Math.max(5, Math.min(200, args?.rows || config.rows));
+      const cols = clampCols(args?.cols, config.cols);
+      const rows = clampRows(args?.rows, config.rows);
       const safeEnv = buildSafeEnv(args?.env);
       safeEnv.PTY_MGR_SESSION = name;
       const opts = {
@@ -1165,14 +1161,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       };
       mgr.spawn(name, cmdToRun, cmdArgs, opts);
       const res = { ok: true, name, pid: mgr.pid(name) };
-      // auto-start logging if --log flag. logs live under the session's own
-      // cwd (client's dir), not the daemon's frozen cwd.
-      if (args?.log) {
-        const logDir = join(mgr.get(name).cwd, "agents", "logs");
-        const logPath = join(logDir, `${name}-${Date.now()}.jsonl`);
-        mgr.get(name).startLog(logPath, "jsonl");
-        res.logPath = logPath;
-      }
+      if (args?.log) res.logPath = startDefaultLog(mgr, name);
       return res;
     }
     case "wrap": {
@@ -1195,8 +1184,8 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       if (maxNum === 0) maxNum = 1;
       const nextName = `${baseName}-${maxNum}`;
 
-      const cols = Math.max(20, Math.min(500, args?.cols || config.cols));
-      const rows = Math.max(5, Math.min(200, args?.rows || config.rows));
+      const cols = clampCols(args?.cols, config.cols);
+      const rows = clampRows(args?.rows, config.rows);
 
       // wrap spawns through user's login shell so shell functions/aliases work
       // (like tmux does). this means glm, nvm, conda, etc. all resolve.
@@ -1223,13 +1212,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
 
       mgr.spawn(nextName, shellCmd, shellArgs, { cwd: clientCwd, env: wrapEnv, cols, rows });
       const res = { ok: true, name: nextName, pid: mgr.pid(nextName) };
-
-      if (args?.log) {
-        const logDir = join(clientCwd, "agents", "logs");
-        const logPath = join(logDir, `${nextName}-${Date.now()}.jsonl`);
-        mgr.get(nextName).startLog(logPath, "jsonl");
-        res.logPath = logPath;
-      }
+      if (args?.log) res.logPath = startDefaultLog(mgr, nextName);
       return res;
     }
     case "send": {
@@ -1346,11 +1329,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       const msg = req.args?.message;
       if (!msg) return { ok: false, error: "message required" };
       if (req.args?.session) tgState.lastSession = req.args.session;
-      await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ chat_id: chatId, text: msg }),
-      });
+      await telegramSend(token, chatId, msg);
       return { ok: true };
     }
     case "tg-wait": {
@@ -1360,11 +1339,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
       if (tgState.waiter) return { ok: false, error: "ALREADY_WAITING" };
       const msg = req.args?.message;
       const timeoutMs = req.args?.timeout ?? 60000;
-      await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ chat_id: chatId, text: msg }),
-      });
+      await telegramSend(token, chatId, msg);
       const sessionName = req.args?.session;
       return new Promise((resolve) => {
         const timer = setTimeout(() => {
@@ -1389,58 +1364,55 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
 }
 
 /**
- * client: send a single command to the daemon, print result.
+ * client: send one newline-framed JSON command to a daemon socket and resolve
+ * with the parsed JSON reply. Rejects with a friendly message when the daemon
+ * is absent, and — unlike a bare JSON.parse in the data handler — turns a
+ * malformed or truncated reply into a rejection instead of an uncaught throw.
  */
-function sendCommandTo(sock, req) {
+function requestSocket(sock, req, notRunningMsg) {
   return new Promise((resolve, reject) => {
     const conn = createConnection(sock);
+    let buf = "";
+    let settled = false;
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      try { conn.end(); } catch {}
+      fn(value);
+    };
+    const parseAndSettle = (chunk) => {
+      try { settle(resolve, JSON.parse(chunk)); }
+      catch (err) { settle(reject, new Error(`bad response from daemon: ${err.message}`)); }
+    };
     conn.on("error", (err) => {
-      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
-        reject(new Error("daemon not running"));
-      } else {
-        reject(err);
-      }
+      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") settle(reject, new Error(notRunningMsg));
+      else settle(reject, err);
     });
     conn.on("connect", () => {
-      conn.write(JSON.stringify(req) + "\n");
+      try { conn.write(JSON.stringify(req) + "\n"); }
+      catch (err) { settle(reject, err); }
     });
-    let buf = "";
     conn.on("data", (data) => {
       buf += data.toString();
       const nl = buf.indexOf("\n");
-      if (nl !== -1) {
-        const res = JSON.parse(buf.slice(0, nl));
-        conn.end();
-        resolve(res);
-      }
+      if (nl !== -1) parseAndSettle(buf.slice(0, nl));
+    });
+    conn.on("end", () => {
+      if (settled) return;
+      if (buf) parseAndSettle(buf); // reply without a trailing newline
+      else settle(reject, new Error(notRunningMsg));
     });
   });
 }
 
+// send to a specific socket file (used by `stop all` sweeping ~/.pty-manager).
+function sendCommandTo(sock, req) {
+  return requestSocket(sock, req, "daemon not running");
+}
+
+// send to the daemon selected by @name / --daemon / $PTY_DAEMON.
 function sendCommand(req) {
-  return new Promise((resolve, reject) => {
-    const conn = createConnection(SOCKET_PATH);
-    conn.on("error", (err) => {
-      if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
-        reject(new Error("daemon not running. start with: pty-mgr daemon"));
-      } else {
-        reject(err);
-      }
-    });
-    conn.on("connect", () => {
-      conn.write(JSON.stringify(req) + "\n");
-    });
-    let buf = "";
-    conn.on("data", (data) => {
-      buf += data.toString();
-      const nl = buf.indexOf("\n");
-      if (nl !== -1) {
-        const res = JSON.parse(buf.slice(0, nl));
-        conn.end();
-        resolve(res);
-      }
-    });
-  });
+  return requestSocket(SOCKET_PATH, req, "daemon not running. start with: pty-mgr daemon");
 }
 
 /**
@@ -1994,6 +1966,20 @@ function capturePayloadText(res) {
   return res.output || "";
 }
 
+// capture a session (or glob/all) twice, intervalMs apart, and report whether
+// the rendered bottom-100 lines are stable ("done") or still changing
+// ("working"). shared by `p watch` and the flow engine's turn-completion check.
+async function captureStability(name, intervalMs) {
+  const capture = () => sendCommand({ cmd: "capture", name, args: { lines: 100 } });
+  const first = await capture();
+  if (!first.ok) throw new Error(first.error || `failed to capture ${name}`);
+  const firstHash = hashText(capturePayloadText(first));
+  await sleep(intervalMs);
+  const second = await capture();
+  if (!second.ok) throw new Error(second.error || `failed to capture ${name}`);
+  return firstHash === hashText(capturePayloadText(second)) ? "done" : "working";
+}
+
 function expandHome(value) {
   if (!value) return value;
   if (value === "~") return homedir();
@@ -2191,11 +2177,14 @@ export function transcriptRootsForKind(kind, config, cwd = process.cwd()) {
     .filter((root, index, roots) => existsSync(root) || index === roots.length - 1);
 }
 
+// flatten every .jsonl transcript under a kind's configured roots.
+function transcriptFiles(kind, config, cwd = process.cwd()) {
+  return transcriptRootsForKind(kind, config, cwd).flatMap((root) => walkJsonlFiles(root));
+}
+
 export function findNewestTranscript({ kind, cwd = process.cwd(), sinceMs = 0, config }) {
   const adapter = adapterForKind(kind, config);
-  const roots = transcriptRootsForKind(kind, config, cwd);
-  const candidates = roots
-    .flatMap((root) => walkJsonlFiles(root))
+  const candidates = transcriptFiles(kind, config, cwd)
     .map((path) => {
       const mtimeMs = statSync(path).mtimeMs;
       const startedMs = transcriptStartedAtMs(path, adapter);
@@ -2338,8 +2327,7 @@ export function findTranscriptForSentMessage({
 }) {
   if (file) return findSentMessageInTranscript(file, kind, text, config);
 
-  const candidates = transcriptRootsForKind(kind, config, cwd)
-    .flatMap((root) => walkJsonlFiles(root))
+  const candidates = transcriptFiles(kind, config, cwd)
     .map((path) => ({ path, mtimeMs: statSync(path).mtimeMs }))
     .sort((a, b) => b.mtimeMs - a.mtimeMs);
 
@@ -2489,14 +2477,7 @@ async function sendFlowMessageConfirmed(meta, text, config, deps = {}) {
 
 async function watchFlowSession(session, intervalMs, deps = {}) {
   if (deps.watchSession) return deps.watchSession(session, intervalMs);
-  const first = await sendCommand({ cmd: "capture", name: session, args: { lines: 100 } });
-  if (!first.ok) throw new Error(first.error || `failed to capture ${session}`);
-  const firstHash = hashText(capturePayloadText(first));
-  await sleep(intervalMs);
-  const second = await sendCommand({ cmd: "capture", name: session, args: { lines: 100 } });
-  if (!second.ok) throw new Error(second.error || `failed to capture ${session}`);
-  const secondHash = hashText(capturePayloadText(second));
-  return firstHash === secondHash ? "done" : "working";
+  return captureStability(session, intervalMs);
 }
 
 async function waitForFlowMessage({
@@ -2674,8 +2655,6 @@ function detectRcFile() {
 }
 
 async function runSetup() {
-  const { appendFileSync, readFileSync, writeFileSync } = await import("node:fs");
-
   console.log("pty-mgr setup");
   console.log("wrap CLI tools in managed PTY sessions.\n");
   console.log("when you type a wrapped command (e.g. claude), pty-mgr will:");
@@ -2952,12 +2931,11 @@ async function cli() {
   if (command === "daemon") {
     // fork into background as a true daemon (survives terminal close)
     if (!process.env.__PTY_DAEMON_CHILD) {
-      const { spawn: cpSpawn } = await import("node:child_process");
       // re-exec ourselves with the same args
       // process.execPath = bun (dev) or the compiled binary
       // filter out internal /$bunfs/ paths from argv
       const realArgs = process.argv.slice(1).filter(a => !a.startsWith("/$bunfs/"));
-      const child = cpSpawn(process.execPath, realArgs, {
+      const child = spawnChild(process.execPath, realArgs, {
         detached: true,
         stdio: ["ignore", "ignore", "ignore", "ipc"],
         env: { ...process.env, __PTY_DAEMON_CHILD: "1" },
@@ -2991,7 +2969,6 @@ async function cli() {
     const target = args[0]; // "all" or undefined (= current daemon)
     if (target === "all") {
       // find all pty-manager sockets and shut them down
-      const { readdirSync } = await import("node:fs");
       const dir = join(homedir(), ".pty-manager");
       let socks = [];
       try {
@@ -3079,20 +3056,7 @@ async function cli() {
     }
 
     try {
-      const first = await sendCommand({ cmd: "capture", name, args: { lines: 100 } });
-      if (!first.ok) {
-        console.error("error:", first.error);
-        process.exit(1);
-      }
-      const firstHash = hashText(capturePayloadText(first));
-      await sleep(intervalMs);
-      const second = await sendCommand({ cmd: "capture", name, args: { lines: 100 } });
-      if (!second.ok) {
-        console.error("error:", second.error);
-        process.exit(1);
-      }
-      const secondHash = hashText(capturePayloadText(second));
-      console.log(firstHash === secondHash ? "done" : "working");
+      console.log(await captureStability(name, intervalMs));
       process.exit(0);
     } catch (err) {
       console.error(err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentiko/pty-mgr",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "PTY session manager with terminal emulation for programmatic session control.",
   "type": "module",
   "main": "lib/pty-manager.mjs",
@@ -26,10 +26,10 @@
     "@xterm/headless": "^6.0.0"
   },
   "optionalDependencies": {
-    "@mentiko/pty-mgr-linux-x64": "1.4.1",
-    "@mentiko/pty-mgr-linux-arm64": "1.4.1",
-    "@mentiko/pty-mgr-darwin-x64": "1.4.1",
-    "@mentiko/pty-mgr-darwin-arm64": "1.4.1"
+    "@mentiko/pty-mgr-linux-x64": "1.4.2",
+    "@mentiko/pty-mgr-linux-arm64": "1.4.2",
+    "@mentiko/pty-mgr-darwin-x64": "1.4.2",
+    "@mentiko/pty-mgr-darwin-arm64": "1.4.2"
   },
   "engines": {
     "bun": ">=1.0"