@mentiko/pty-mgr 1.3.1 → 1.4.1

package/lib/pty-manager.mjs

@@ -38,10 +38,13 @@ import {
   readFileSync,
   readdirSync,
   statSync,
+  writeFileSync,
 } 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.3.1";
+export const VERSION = "1.4.1";
 import xterm from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 
@@ -210,14 +213,17 @@ class PtySession {
       if (!line) { lines.push(""); continue; }
 
       let out = "";
+      let keep = 0; // output length up to the last cell worth keeping
       let prevFg = -1, prevBg = -1, prevBold = false, prevDim = false;
       let prevItalic = false, prevUnder = false, prevInverse = false;
 
       for (let x = 0; x < line.length; x++) {
         const cell = line.getCell(x);
         if (!cell) continue;
-        const ch = cell.getChars();
-        if (!ch) continue;
+        if (cell.getWidth() === 0) continue; // wide-char continuation cell
+        // null cells (never written; TUIs skip them with cursor moves)
+        // must still occupy a column, or text collapses together
+        const ch = cell.getChars() || " ";
 
         const fg = cell.getFgColor();
         const bg = cell.getBgColor();
@@ -258,8 +264,13 @@ class PtySession {
           prevItalic = italic; prevUnder = under; prevInverse = inverse;
         }
         out += ch;
+        if (ch !== " " || fgMode !== 0 || bgMode !== 0 ||
+            bold || dim || italic || under || inverse) {
+          keep = out.length;
+        }
       }
-      if (prevFg !== -1 || prevBold) out += "\x1b[0m";
+      out = out.slice(0, keep); // drop trailing unstyled blanks
+      if (keep > 0 && (prevFg !== -1 || prevBold)) out += "\x1b[0m";
       lines.push(out);
     }
 
@@ -790,15 +801,18 @@ function startDaemon() {
               const session = mgr.get(req.name);
               const cols = session.terminal.cols;
               const rows = session.terminal.rows;
-              // send initial ack with terminal size
-              conn.write(JSON.stringify({ ok: true, mode: "attach", cols, rows }) + "\n");
-
-              // send current buffer as plain text, then SIGWINCH for colored redraw
-              conn.write("\x1b[2J\x1b[H");
-              const screen = session.capture(session.terminal.rows);
-              if (screen) conn.write(screen.replace(/\n/g, "\r\n") + "\r\n");
-
-              // force TUI apps to redraw on top
+              const alt = session.terminal.buffer.active.type === "alternate";
+              // send initial ack with terminal size + buffer state
+              conn.write(JSON.stringify({ ok: true, mode: "attach", cols, rows, alt }) + "\n");
+
+              // replay the session's full terminal state: scrollback, screen,
+              // colors, cursor, modes. history lands in the client's own
+              // scrollback so it stays scrollable. if the session is inside a
+              // TUI, the serializer emits the alt-screen switch itself and the
+              // client pops back out on detach.
+              conn.write("\x1b[2J\x1b[H" + session.captureAnsi());
+
+              // nudge the app to repaint so live output aligns with the replay
               if (session.childPid) {
                 try { process.kill(session.childPid, "SIGWINCH"); } catch {}
               }
@@ -812,7 +826,10 @@ function startDaemon() {
               // when session exits, notify and close
               const onExit = () => {
                 try {
-                  conn.write("\r\n[session exited]\r\n");
+                  if (session.terminal.buffer.active.type === "alternate") {
+                    conn.write("\x1b[?1049l");
+                  }
+                  conn.write("\x1b[0m\r\n[session exited]\r\n");
                   conn.end();
                 } catch {}
               };
@@ -1093,6 +1110,7 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
           name: DAEMON_NAME,
           pid: process.pid,
           socket: SOCKET_PATH,
+          cwd: process.cwd(),
           startedAt: daemonStartedAt.toISOString(),
           uptimeMs,
           uptime: formatUptime(uptimeMs),
@@ -1147,9 +1165,10 @@ 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
+      // 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(process.cwd(), "agents", "logs");
+        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;
@@ -1301,10 +1320,11 @@ async function handleCommand(mgr, req, daemonStartedAt, config, tgState = {}) {
         const path = session.stopLog();
         return { ok: true, stopped: true, path };
       }
-      // default log dir: ./agents/logs/
+      // default log dir: <session cwd>/agents/logs/ -- follow the session's
+      // own dir, not the daemon's frozen cwd.
       const format = args?.format || "jsonl";
       const ext = format === "jsonl" ? "jsonl" : format === "rendered" ? "log" : "raw";
-      const logDir = args?.dir || join(process.cwd(), "agents", "logs");
+      const logDir = args?.dir || join(session.cwd, "agents", "logs");
       const ts = Date.now();
       const logPath = args?.path || join(logDir, `${name}-${ts}.${ext}`);
       session.startLog(logPath, format);
@@ -1431,8 +1451,12 @@ function sendCommand(req) {
 function attachToSession(name) {
   return new Promise((resolve, reject) => {
     const conn = createConnection(SOCKET_PATH);
+    // set on any pre-attach failure so the close handler doesn't run the
+    // detach cleanup (stray "detached" + terminal resets after an error)
+    let failed = false;
 
     conn.on("error", (err) => {
+      failed = true;
       if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
         reject(new Error("daemon not running. start with: pty-mgr daemon"));
       } else {
@@ -1447,6 +1471,15 @@ function attachToSession(name) {
       let gotAck = false;
       let headerBuf = "";
 
+      // last-seen alt-screen state: detach pops the client back to its
+      // normal screen only if the session left it in the alternate buffer
+      let altActive = false;
+      const trackAlt = (chunk) => {
+        const h = chunk.lastIndexOf("\x1b[?1049h");
+        const l = chunk.lastIndexOf("\x1b[?1049l");
+        if (h !== -1 || l !== -1) altActive = h > l;
+      };
+
       conn.on("data", (data) => {
         if (!gotAck) {
           // first line is the JSON ack
@@ -1461,19 +1494,20 @@ function attachToSession(name) {
           try {
             ack = JSON.parse(ackStr);
             if (!ack.ok) {
-              console.error("error:", ack.error);
+              failed = true;
               conn.end();
               reject(new Error(ack.error));
               return;
             }
           } catch {
-            console.error("bad ack from daemon");
+            failed = true;
             conn.end();
-            reject(new Error("bad ack"));
+            reject(new Error("bad ack from daemon"));
             return;
           }
 
           gotAck = true;
+          altActive = !!ack.alt;
 
           // resize client terminal to match session
           if (ack.cols && ack.rows) {
@@ -1489,6 +1523,7 @@ function attachToSession(name) {
 
           // write any remaining data after the ack
           if (remainder) {
+            trackAlt(remainder);
             process.stdout.write(remainder);
           }
 
@@ -1506,6 +1541,7 @@ function attachToSession(name) {
         }
 
         // streaming mode: write pty output to terminal
+        trackAlt(data);
         process.stdout.write(data);
       });
 
@@ -1515,15 +1551,22 @@ function attachToSession(name) {
 
       let detached = false;
       function detach() {
-        if (detached) return;
+        if (detached || failed) return;
         detached = true;
         if (process.stdin.isRaw) {
           process.stdin.setRawMode(false);
           process.stdin.pause();
           process.stdin.removeAllListeners("data");
         }
+        // pop the alt screen only if the session left us in one, then
+        // reset SGR/cursor and any modes the replayed TUI enabled
+        // (keypad, cursor keys, bracketed paste, mouse tracking)
+        if (altActive) process.stdout.write("\x1b[?1049l");
+        process.stdout.write(
+          "\x1b[0m\x1b[?25h\x1b>\x1b[?1l\x1b[?2004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1004l\x1b[?9l"
+        );
         conn.end();
-        console.log("\r\ndetached");
+        console.log("detached");
         resolve();
       }
     });
@@ -1569,6 +1612,8 @@ usage:
   p flow list [--verbose] [--config file] list configured agent workflows
   p flow show <name> [--config file]   show one configured agent workflow
   p flow run <name> --task <text>     run a configured agent workflow
+  p flow new [name] [--global]        scaffold an example flow (project cwd, or --global user config)
+  p open config [editor]              open config dir in editor (--local project, --defaults packaged)
   p demo                             run self-test (no daemon needed)
   p tg <message>                     send telegram notification
   p tg <message> --reply             send message and wait for reply (blocking)
@@ -1967,6 +2012,104 @@ export function loadFlowConfig(configPath = "pty-mgr.config.json") {
   return { adapters: {}, flows: {} };
 }
 
+function xdgConfigHome() {
+  return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+
+export function userConfigPath() {
+  return process.env.PTY_MGR_CONFIG || join(xdgConfigHome(), "pty-mgr", "config.json");
+}
+
+function packagedDefaultsConfigPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "pty-mgr.config.json");
+}
+
+export function findProjectConfigPath(cwd = process.cwd()) {
+  let dir = cwd;
+  const home = homedir();
+  while (true) {
+    const candidate = join(dir, "pty-mgr.config.json");
+    if (existsSync(candidate)) return candidate;
+    if (existsSync(join(dir, ".git")) || dir === home) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// merge flow configs low->high precedence; higher layers override by top-level key.
+// returns { adapters, flows, scopes } where scopes maps flow name -> layer it came from.
+export function resolveMergedConfig({ cwd = process.cwd(), explicitPath = null } = {}) {
+  if (explicitPath) {
+    const config = loadFlowConfig(explicitPath);
+    const scopes = {};
+    for (const name of Object.keys(config.flows || {})) scopes[name] = "config";
+    return { adapters: config.adapters || {}, flows: config.flows || {}, scopes };
+  }
+  const layers = [];
+  const defaultsPath = packagedDefaultsConfigPath();
+  if (existsSync(defaultsPath)) layers.push(["default", loadFlowConfig(defaultsPath)]);
+  const userPath = userConfigPath();
+  if (existsSync(userPath)) layers.push(["user", loadFlowConfig(userPath)]);
+  const projectPath = findProjectConfigPath(cwd);
+  if (projectPath && projectPath !== defaultsPath) layers.push(["project", loadFlowConfig(projectPath)]);
+
+  const adapters = {};
+  const flows = {};
+  const scopes = {};
+  for (const [scope, config] of layers) {
+    Object.assign(adapters, config.adapters || {});
+    for (const [name, flow] of Object.entries(config.flows || {})) {
+      flows[name] = flow;
+      scopes[name] = scope;
+    }
+  }
+  return { adapters, flows, scopes };
+}
+
+function exampleFlow() {
+  return {
+    agents: {
+      writer: { kind: "codex", base: "flow-writer" },
+      reviewer: { kind: "claude", base: "flow-reviewer" },
+    },
+    start: { to: "writer", template: "{task}" },
+    turns: [
+      {
+        from: "writer",
+        to: "reviewer",
+        append:
+          "Review what the other agent just did in this repository. Give specific, actionable feedback as a short numbered list, each item referencing file:line.",
+      },
+      {
+        from: "reviewer",
+        to: "writer",
+        append:
+          "Apply the feedback you agree with, note anything you skip and why, then report the final state. Original task: {goal}",
+      },
+    ],
+    maxCycles: 1,
+    watchInterval: "10s",
+    settleMs: 1500,
+  };
+}
+
+function scaffoldFlowConfig(targetPath, name) {
+  const dir = dirname(targetPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const config = existsSync(targetPath) ? loadFlowConfig(targetPath) : { flows: {} };
+  if (!config.flows) config.flows = {};
+  if (config.flows[name]) {
+    console.error(`flow already exists: ${name} (${targetPath})`);
+    process.exit(1);
+  }
+  config.flows[name] = exampleFlow();
+  writeFileSync(targetPath, JSON.stringify(config, null, 2) + "\n");
+  console.log(`created flow "${name}" in ${targetPath}`);
+  console.log(`  edit: p open config${targetPath === userConfigPath() ? "" : " --local"}`);
+  console.log(`  run:  p flow run ${name} --task "..."`);
+}
+
 function walkJsonlFiles(root, files = []) {
   root = expandHome(root);
   if (!root || !existsSync(root)) return files;
@@ -2650,20 +2793,55 @@ async function cli() {
     return;
   }
 
+  if (command === "open") {
+    const sub = args[0];
+    if (sub !== "config") {
+      console.error("usage: p open config [editor] [--local|--defaults]");
+      process.exit(1);
+    }
+    const { flags: openFlags, rest: openRest } = parseFlagArgs(args, 1);
+    const editor = openRest[0] || process.env.VISUAL || process.env.EDITOR || "code";
+    let dir;
+    if (openFlags.defaults) {
+      dir = dirname(packagedDefaultsConfigPath());
+    } else if (openFlags.local) {
+      const projectPath = findProjectConfigPath(process.cwd());
+      dir = projectPath ? dirname(projectPath) : process.cwd();
+    } else {
+      dir = dirname(userConfigPath());
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    }
+    console.log(`opening ${dir} with ${editor}`);
+    await new Promise((resolve) => {
+      const child = spawnChild(editor, [dir], { stdio: "inherit" });
+      child.on("error", (err) => {
+        console.error(`could not launch ${editor}: ${err.message}`);
+        resolve();
+      });
+      child.on("exit", () => resolve());
+    });
+    return;
+  }
+
   if (command === "flow") {
     const subcommand = args[0];
-    const { flags } = parseFlagArgs(args, 1);
-    const configPath = flags.config || "pty-mgr.config.json";
+    const { flags, rest } = parseFlagArgs(args, 1);
+    if (subcommand === "new") {
+      const name = rest[0] || "example";
+      const target = flags.global ? userConfigPath() : join(process.cwd(), "pty-mgr.config.json");
+      scaffoldFlowConfig(target, name);
+      return;
+    }
     if (subcommand === "list") {
-      const config = loadFlowConfig(configPath);
-      const names = Object.keys(config.flows || {});
+      const { flows, scopes } = resolveMergedConfig({ cwd: process.cwd(), explicitPath: flags.config });
+      const names = Object.keys(flows);
       if (names.length === 0) {
         console.log("no flows configured");
       } else {
         for (const name of names) {
-          console.log(name);
+          console.log(flags.config ? name : `${name} [${scopes[name]}]`);
           if (flags.verbose) {
-            const flow = config.flows[name] || {};
+            const flow = flows[name] || {};
             for (const [alias, agent] of Object.entries(flow.agents || {})) {
               console.log(`  ${alias} -> ${flowAgentKind(agent)}`);
             }
@@ -2680,8 +2858,8 @@ async function cli() {
         console.error("usage: pty-mgr flow show <name>");
         process.exit(1);
       }
-      const config = loadFlowConfig(configPath);
-      const flow = config.flows?.[name];
+      const { flows } = resolveMergedConfig({ cwd: process.cwd(), explicitPath: flags.config });
+      const flow = flows[name];
       if (!flow) {
         console.error(`flow not found: ${name}`);
         process.exit(1);
@@ -2716,19 +2894,20 @@ async function cli() {
         console.error("flow run requires --task <text>");
         process.exit(1);
       }
+      const runCwd = runFlags.cwd || process.cwd();
+      const merged = resolveMergedConfig({ cwd: runCwd, explicitPath: runFlags.config || flags.config });
       try {
         const result = await runFlowWorkflow({
           workflow,
           task,
           goal: runFlags.goal,
-          config: runFlags.config || configPath,
-          cwd: runFlags.cwd || process.cwd(),
+          cwd: runCwd,
           maxCycles: runFlags["max-cycles"],
           watchInterval: runFlags["watch-interval"],
           settleMs: runFlags["settle-ms"],
           timeoutMs: runFlags["timeout-ms"],
           intervalMs: runFlags["interval-ms"],
-        });
+        }, { config: merged });
         console.log(JSON.stringify(result, null, 2));
       } catch (err) {
         console.error(err.message);
@@ -3031,6 +3210,7 @@ async function cli() {
       console.log(`pty-manager daemon (${st.name})`);
       console.log(`  pid:      ${st.pid}`);
       console.log(`  socket:   ${st.socket}`);
+      console.log(`  cwd:      ${st.cwd}`);
       console.log(`  uptime:   ${st.uptime}`);
       console.log(`  sessions: ${st.sessions.alive} alive, ${st.sessions.dead} dead, ${st.sessions.total} total`);
       console.log(`  screen:   ${st.config.cols}x${st.config.rows}`);
@@ -3119,7 +3299,10 @@ const isMain = _isBunCompiled || (_basename1 && _pat.test(_basename1)) || (_base
 
 if (isMain) {
   cli().catch((err) => {
-    console.error(err);
+    // message only -- a raw error object prints a stack trace for what are
+    // usually plain user-facing failures (session not found, daemon down)
+    console.error("error:", err.message);
+    if (process.env.PTY_MGR_DEBUG) console.error(err.stack);
     process.exit(1);
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentiko/pty-mgr",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "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.3.1",
-    "@mentiko/pty-mgr-linux-arm64": "1.3.1",
-    "@mentiko/pty-mgr-darwin-x64": "1.3.1",
-    "@mentiko/pty-mgr-darwin-arm64": "1.3.1"
+    "@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"
   },
   "engines": {
     "bun": ">=1.0"