@volter/supercode-terminal 0.2.37 → 0.2.39

package/index.d.ts

@@ -72,9 +72,30 @@ export class TmuxTerminalHost {
   dispose(): void;
 }
 
+/**
+ * Terminal panes held by the machine's pane server (a process of its own, reached over a named pipe; Windows):
+ * PtyTerminalHost's surface, asynchronous, and the panes outlive this client, as tmux panes outlive a daemon.
+ */
+export class PaneServerHost {
+  constructor(options: { pipe: string; serverScript?: string });
+  listSessions(): Promise<TerminalSession[]>;
+  createSession(input: { command: TmuxCommand; contextKey?: string; cwd?: string; env?: Record<string, string>; name?: string }): Promise<TerminalSession>;
+  capture(sessionId: string, options?: { lines?: number; preserveEscapes?: boolean }): Promise<string>;
+  sendInput(sessionId: string, data: string, options?: { deadlineMs?: number; submitMode?: 'retry' | 'single' }): Promise<TerminalInputDelivery>;
+  bindContext(sessionId: string, contextKey: string): Promise<TerminalSession>;
+  renameWindow(sessionId: string, title?: string | null): Promise<string>;
+  issueAttachment(sessionId: string, options?: { mode?: 'observe' | 'control' }): Promise<TerminalAttachmentGrant>;
+  attachSocket(attachmentId: string, socket: unknown, size?: { cols?: number; rows?: number }): Promise<{ dispose(): void }>;
+  closeSession(sessionId: string): Promise<void>;
+  localAttachLaunch(sessionId: string): never;
+  openLocalTerminal(sessionId: string): Promise<void>;
+  /** Closes this client's connection; the panes stay with the server. */
+  dispose(): void;
+}
+
 /**
  * Terminal panes without tmux (Windows): ConPTY children of this process, each with a headless screen for
- * capture and attach. Same surface as TmuxTerminalHost; panes end with the host.
+ * capture and attach. Same surface as TmuxTerminalHost; panes end with the host. The pane server runs one.
  */
 export class PtyTerminalHost {
   constructor(options?: { attachmentTtlMs?: number });

package/index.mjs

@@ -1,6 +1,8 @@
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
+import { connect as netConnect } from 'node:net';
+import { fileURLToPath } from 'node:url';
 import { createServer as defaultCreateServer } from 'node:http';
 
 import { NativeTerminalSessionHost } from './substrate/native-host.js';
@@ -808,6 +810,8 @@ export class PtyTerminalHost {
       // The launch directory: another process's current directory is not readable here as tmux reads it.
       cwd: entry.cwd,
       dead: entry.exit !== null,
+      // How a dead pane's program ended (a failed one is kept so its last screen can be read).
+      exitCode: entry.exit ? entry.exit.exitCode ?? null : null,
       id: entry.id,
       label: entry.name,
       owned: true,
@@ -893,6 +897,152 @@ export class PtyTerminalHost {
   }
 }
 
+/**
+ * Terminal panes held by the machine's pane server (substrate/pane-server.mjs), a process of its own reached over a
+ * named pipe: the surface is PtyTerminalHost's, so a daemon drives it the same way, but the panes belong to the
+ * server, as tmux panes belong to tmux's server. Restarting or upgrading the daemon ends only this client's
+ * connection; the panes and their programs go on, and the next daemon finds them there. The server starts on first
+ * use, detached, and leaves a minute after it holds no pane and no client.
+ */
+export class PaneServerHost {
+  #connection = null;
+  #connecting = null;
+  #next = 1;
+  #pending = new Map();
+  #streams = new Map();
+  #pipe;
+  #serverScript;
+
+  constructor(options = {}) {
+    if (!options.pipe) throw new TypeError('PaneServerHost requires a pipe name');
+    this.#pipe = options.pipe;
+    this.#serverScript = options.serverScript ?? fileURLToPath(new URL('./substrate/pane-server.mjs', import.meta.url));
+  }
+
+  listSessions() { return this.#request('listSessions', []); }
+  createSession(input) { return this.#request('createSession', [input]); }
+  capture(sessionId, options = {}) { return this.#request('capture', [sessionId, options]); }
+  sendInput(sessionId, data, options = {}) { return this.#request('sendInput', [sessionId, data, options]); }
+  closeSession(sessionId) { return this.#request('closeSession', [sessionId]); }
+  renameWindow(sessionId, title) { return this.#request('renameWindow', [sessionId, title]); }
+  issueAttachment(sessionId, options = {}) { return this.#request('issueAttachment', [sessionId, options]); }
+  bindContext(sessionId, contextKey) { return this.#request('bindContext', [sessionId, contextKey]); }
+
+  localAttachLaunch() {
+    throw new TerminalHostError('unsupported', 'A pane on this platform has no local terminal to attach: open it through a viewer.');
+  }
+
+  async openLocalTerminal(sessionId) { this.localAttachLaunch(sessionId); }
+
+  /** The viewer's socket, relayed to the pane server's attachment: its frames out, the viewer's input in. */
+  async attachSocket(attachmentId, socket, size = {}) {
+    const connection = await this.#connect();
+    const stream = `s${this.#next++}`;
+    const relay = {
+      socket,
+      onMessage: (raw) => { if (!connection.destroyed) connection.write(`${JSON.stringify({ stream, message: raw.toString() })}\n`); },
+      onClose: () => relay.dispose(),
+      disposed: false,
+      dispose: () => {
+        if (relay.disposed) return;
+        relay.disposed = true;
+        socket?.off?.('message', relay.onMessage);
+        socket?.off?.('close', relay.onClose);
+        this.#streams.delete(stream);
+        if (!connection.destroyed) connection.write(`${JSON.stringify({ stream, closed: true })}\n`);
+      },
+    };
+    this.#streams.set(stream, relay);
+    socket?.on?.('message', relay.onMessage);
+    socket?.once?.('close', relay.onClose);
+    try {
+      await this.#request('attach', [attachmentId, size], { stream });
+    } catch (error) {
+      relay.dispose();
+      throw error;
+    }
+    return { dispose: () => relay.dispose() };
+  }
+
+  /** The daemon is going: its connection closes and its viewers with it; the panes stay with the server. */
+  dispose() {
+    for (const relay of [...this.#streams.values()]) relay.dispose();
+    this.#connection?.end();
+    this.#connection = null;
+  }
+
+  async #request(op, args, extra = {}) {
+    const connection = await this.#connect();
+    const id = this.#next++;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      connection.write(`${JSON.stringify({ id, op, args, ...extra })}\n`);
+    });
+  }
+
+  #connect() {
+    if (this.#connection && !this.#connection.destroyed) return Promise.resolve(this.#connection);
+    return (this.#connecting ??= this.#open().finally(() => { this.#connecting = null; }));
+  }
+
+  async #open() {
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+      try {
+        const connection = await new Promise((resolve, reject) => {
+          const candidate = netConnect(this.#pipe);
+          candidate.once('connect', () => resolve(candidate));
+          candidate.once('error', reject);
+        });
+        this.#adopt(connection);
+        return connection;
+      } catch (error) {
+        // No server on the pipe yet: start one, detached from this daemon, and try again as it comes up.
+        if (attempt === 0 && (error.code === 'ENOENT' || error.code === 'ECONNREFUSED')) {
+          const child = spawn(process.execPath, [this.#serverScript, this.#pipe], { detached: true, stdio: 'ignore', windowsHide: true, env: process.env });
+          child.on('error', () => {});
+          child.unref();
+        }
+        await sleep(250);
+      }
+    }
+    throw new TerminalHostError('pane_server_unreachable', `The pane server at ${this.#pipe} did not answer.`);
+  }
+
+  #adopt(connection) {
+    this.#connection = connection;
+    connection.setEncoding('utf8');
+    let pending = '';
+    connection.on('data', (chunk) => {
+      pending += chunk;
+      for (let end; (end = pending.indexOf('\n')) >= 0; pending = pending.slice(end + 1)) {
+        let message;
+        try { message = JSON.parse(pending.slice(0, end)); } catch { continue; }
+        if (message.stream !== undefined && message.id === undefined) {
+          const relay = this.#streams.get(message.stream);
+          if (!relay) continue;
+          if (typeof message.send === 'string' && relay.socket?.readyState === relay.socket?.OPEN) relay.socket.send(message.send);
+          if (message.close) { this.#streams.delete(message.stream); relay.disposed = true; relay.socket?.close?.(message.close[0], message.close[1]); }
+          continue;
+        }
+        const waiter = this.#pending.get(message.id);
+        if (!waiter) continue;
+        this.#pending.delete(message.id);
+        if (message.error) waiter.reject(new TerminalHostError(message.error.code, message.error.message));
+        else waiter.resolve(message.result);
+      }
+    });
+    // The server went (or this connection did): waiting requests fail, and viewers are told; the next call reconnects.
+    connection.on('close', () => {
+      if (this.#connection === connection) this.#connection = null;
+      for (const waiter of this.#pending.values()) waiter.reject(new TerminalHostError('pane_server_unreachable', 'The pane server connection closed.'));
+      this.#pending.clear();
+      for (const relay of [...this.#streams.values()]) { relay.disposed = true; relay.socket?.close?.(1011, 'pane server connection closed'); }
+      this.#streams.clear();
+    });
+    connection.on('error', () => {});
+  }
+}
+
 /** What a Windows pane runs: the program itself, or a `.cmd`/`.bat` (npm's shims: `claude`, `codex`) through cmd. */
 function windowsLaunch(program, args, env) {
   const resolved = resolveWindowsProgram(program, env);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-terminal",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "type": "module",
   "description": "Optional leak-safe terminal and tmux host adapter for Volter Harness frontends",
   "exports": {

package/substrate/pane-server.mjs

@@ -0,0 +1,109 @@
+// The machine's pane server where there is no tmux (Windows): a process of its own that holds the ConPTY panes, as
+// tmux's server holds tmux panes, so restarting or upgrading the daemon never ends a pane. The daemon is a client
+// (PaneServerHost) over a named pipe; this process serves PtyTerminalHost's surface to it, one JSON line per message.
+//
+//   request   { id, op, args }                     → { id, result } | { id, error: { code, message } }
+//   attach    { id, op: 'attach', args: [attachmentId, size], stream }
+//             then the server sends { stream, send: <text> } per viewer frame and { stream, close: [code, reason] };
+//             the client sends { stream, message: <text> } and { stream, closed: true }
+//
+// It keeps running while it holds a pane or a client is connected, and leaves a minute after it has neither. If the
+// process itself dies, PtyTerminalHost's watchdog ends its panes (nothing is left running unowned).
+import { createServer } from 'node:net';
+import { PtyTerminalHost } from '../index.mjs';
+
+const pipe = process.argv[2];
+if (!pipe) { process.stderr.write('pane-server: a pipe name is required\n'); process.exit(2); }
+
+const host = new PtyTerminalHost();
+const clients = new Set();
+const IDLE_EXIT_MS = 60_000;
+let idleTimer = null;
+
+const OPS = new Set(['listSessions', 'createSession', 'capture', 'sendInput', 'closeSession', 'renameWindow', 'issueAttachment', 'bindContext']);
+
+function scheduleIdleExit() {
+  clearTimeout(idleTimer);
+  idleTimer = setTimeout(async () => {
+    const panes = await host.listSessions().catch(() => []);
+    if (clients.size === 0 && panes.length === 0) { host.dispose(); process.exit(0); }
+    scheduleIdleExit();
+  }, IDLE_EXIT_MS);
+  idleTimer.unref?.();
+}
+
+const server = createServer((connection) => {
+  clients.add(connection);
+  connection.setEncoding('utf8');
+  const streams = new Map(); // stream id → { socketLike, attachment }
+  const write = (value) => { if (!connection.destroyed) connection.write(`${JSON.stringify(value)}\n`); };
+  const answer = (id, result) => write({ id, result: result === undefined ? null : result });
+  const refuse = (id, error) => write({ id, error: { code: error?.code ?? 'pane_server_error', message: error?.message ?? String(error) } });
+
+  const attach = async (id, [attachmentId, size], stream) => {
+    const listeners = { message: new Set(), close: new Set() };
+    const socketLike = {
+      OPEN: 1, CLOSED: 3, readyState: 1,
+      send: (data) => write({ stream, send: String(data) }),
+      close: (code, reason) => {
+        if (socketLike.readyState !== 1) return;
+        socketLike.readyState = 3;
+        write({ stream, close: [code ?? 1000, reason ?? ''] });
+        for (const listener of [...listeners.close]) listener();
+        streams.delete(stream);
+      },
+      on: (event, listener) => { listeners[event]?.add(listener); return socketLike; },
+      once: (event, listener) => { const once = (...a) => { listeners[event]?.delete(once); listener(...a); }; listeners[event]?.add(once); return socketLike; },
+      off: (event, listener) => { listeners[event]?.delete(listener); return socketLike; },
+      emitMessage: (text) => { for (const listener of [...listeners.message]) listener(text); },
+      emitClose: () => { socketLike.readyState = 3; for (const listener of [...listeners.close]) listener(); },
+    };
+    streams.set(stream, { socketLike, attachment: null });
+    try {
+      const attachment = await host.attachSocket(attachmentId, socketLike, size ?? {});
+      const entry = streams.get(stream);
+      if (entry) entry.attachment = attachment; else attachment.dispose();
+      answer(id, true);
+    } catch (error) {
+      streams.delete(stream);
+      refuse(id, error);
+    }
+  };
+
+  let pending = '';
+  connection.on('data', (chunk) => {
+    pending += chunk;
+    for (let end; (end = pending.indexOf('\n')) >= 0; pending = pending.slice(end + 1)) {
+      let message;
+      try { message = JSON.parse(pending.slice(0, end)); } catch { continue; }
+      if (message.stream !== undefined && message.op === undefined) {
+        const entry = streams.get(message.stream);
+        if (!entry) continue;
+        if (typeof message.message === 'string') entry.socketLike.emitMessage(message.message);
+        if (message.closed) { streams.delete(message.stream); entry.socketLike.emitClose(); entry.attachment?.dispose(); }
+        continue;
+      }
+      const { id, op, args = [] } = message;
+      if (op === 'attach') { attach(id, args, message.stream); continue; }
+      if (!OPS.has(op)) { refuse(id, { code: 'unsupported', message: `pane server: no operation ${op}` }); continue; }
+      Promise.resolve().then(() => host[op](...args)).then((result) => answer(id, result), (error) => refuse(id, error));
+    }
+  });
+  // A client that goes (its daemon restarting) takes only its viewers with it: the panes stay.
+  connection.on('close', () => {
+    clients.delete(connection);
+    for (const { socketLike, attachment } of streams.values()) { socketLike.emitClose(); attachment?.dispose(); }
+    streams.clear();
+    scheduleIdleExit();
+  });
+  connection.on('error', () => {});
+  clearTimeout(idleTimer);
+});
+
+server.on('error', (error) => {
+  // Another pane server already holds the pipe: it serves this machine; this one is not needed.
+  if (error.code === 'EADDRINUSE') process.exit(0);
+  process.stderr.write(`pane-server: ${error.message}\n`);
+  process.exit(1);
+});
+server.listen(pipe, () => scheduleIdleExit());