agent-sh 0.14.1 → 0.14.2

package/dist/shell/index.js

@@ -5,12 +5,13 @@
  */
 import "./events.js"; // augments BusEvents with shell-owned events
 import { Shell } from "./shell.js";
-import { DefaultCompositor, StdoutSurface } from "../utils/compositor.js";
+import { DefaultCompositor } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.js";
 import { setPalette } from "../utils/palette.js";
 import * as streamTransform from "../utils/stream-transform.js";
 import activateShellContext from "./shell-context.js";
 import activateTuiRenderer from "./tui-renderer.js";
+import { processTerminal, surfaceFromTerminal } from "./terminal.js";
 /**
  * Register shell-owned handlers extensions can `ctx.call`, and attach
  * the shell surface to ctx. Must run before `loadExtensions` so user
@@ -77,10 +78,11 @@ export function registerShellHandlers(ctx) {
  * `src/cli/index.ts`) uses to drive lifecycle from process-level events.
  */
 export function activateShell(ctx, opts) {
-    const stdoutSurface = new StdoutSurface();
-    ctx.shell.compositor.setDefault("agent", stdoutSurface);
-    ctx.shell.compositor.setDefault("query", stdoutSurface);
-    ctx.shell.compositor.setDefault("status", stdoutSurface);
+    const terminal = opts.terminal ?? processTerminal();
+    const surface = surfaceFromTerminal(terminal);
+    ctx.shell.compositor.setDefault("agent", surface);
+    ctx.shell.compositor.setDefault("query", surface);
+    ctx.shell.compositor.setDefault("status", surface);
     const shell = new Shell({
         bus: ctx.bus,
         handlers: { define: ctx.define, call: ctx.call },
@@ -90,13 +92,11 @@ export function activateShell(ctx, opts) {
         cwd: opts.cwd,
         instanceId: ctx.instanceId,
         onShowAgentInfo: opts.onShowAgentInfo,
+        terminal,
     });
-    const onResize = () => {
-        shell.resize(process.stdout.columns || 80, process.stdout.rows || 24);
-    };
-    process.stdout.on("resize", onResize);
+    const offResize = terminal.onResize((cols, rows) => shell.resize(cols, rows));
     ctx.onDispose(() => {
-        process.stdout.off("resize", onResize);
+        offResize();
         shell.kill();
     });
     return {

package/dist/shell/shell.d.ts

@@ -1,5 +1,6 @@
 import type { EventBus } from "../core/event-bus.js";
 import { type InputContext } from "./input-handler.js";
+import { type Terminal } from "./terminal.js";
 export interface ShellHandlers {
     define: (name: string, fn: (...args: any[]) => any) => void;
     call: (name: string, ...args: any[]) => any;
@@ -19,6 +20,8 @@ export declare class Shell implements InputContext {
     private handlers;
     private inputHandler;
     private outputParser;
+    private terminal;
+    private inputDispose;
     private hardMuteScopes;
     private softMuteScopes;
     private unmuteScopes;
@@ -38,6 +41,7 @@ export declare class Shell implements InputContext {
         shell: string;
         cwd: string;
         instanceId: string;
+        terminal?: Terminal;
     });
     /** Compositing-layer claim — overrides any unmute. */
     acquireHardMute(reason: string): ShellScope;

package/dist/shell/shell.js

@@ -5,6 +5,7 @@ import { InputHandler } from "./input-handler.js";
 import { OutputParser } from "./output-parser.js";
 import { getSettings } from "../core/settings.js";
 import { clearOpost } from "../utils/tty.js";
+import { processTerminal } from "./terminal.js";
 import { pickStrategy, FALLBACK_STRATEGY, SUPPORTED_SHELL_NAMES, } from "./strategies/index.js";
 export class Shell {
     ptyProcess;
@@ -12,6 +13,8 @@ export class Shell {
     handlers;
     inputHandler;
     outputParser;
+    terminal;
+    inputDispose = null;
     // hardMute is unconditional (overlay compositing); softMute is overridable
     // by unmute (terminal_keys, permission UI). Gate: hard wins; otherwise
     // muted iff softMute held without an unmute.
@@ -23,6 +26,7 @@ export class Shell {
     strategy;
     tmpDir;
     constructor(opts) {
+        this.terminal = opts.terminal ?? processTerminal();
         // Build environment — filter out undefined values (node-pty's native
         // posix_spawnp fails if any env value is undefined)
         const env = {};
@@ -58,18 +62,10 @@ export class Shell {
         this.tmpDir = spawnConfig.tmpDir;
         Object.assign(env, spawnConfig.envOverrides);
         const shellArgs = spawnConfig.args;
-        // Pause stdin before spawning PTY to avoid TTY contention on macOS.
-        // The PTY will become the controlling terminal for the child shell.
-        const wasRaw = process.stdin.isTTY && process.stdin.isRaw;
-        if (process.stdin.isTTY) {
-            try {
-                process.stdin.setRawMode(false);
-                process.stdin.pause();
-            }
-            catch {
-                // Ignore
-            }
-        }
+        // The PTY will become the controlling terminal for the child shell;
+        // suspend the host terminal's input around spawn to avoid TTY contention
+        // on macOS. Headless terminals make this a no-op.
+        const suspended = this.terminal.suspendInput?.();
         this.ptyProcess = pty.spawn(shellBin, shellArgs, {
             name: "xterm-256color",
             cols: opts.cols,
@@ -77,18 +73,7 @@ export class Shell {
             cwd: opts.cwd,
             env,
         });
-        // Restore stdin after PTY is created
-        if (process.stdin.isTTY) {
-            try {
-                process.stdin.resume();
-                if (wasRaw) {
-                    process.stdin.setRawMode(true);
-                }
-            }
-            catch {
-                // Ignore - will be set up later in index.ts
-            }
-        }
+        suspended?.resume();
         clearOpost();
         this.bus = opts.bus;
         this.handlers = opts.handlers;
@@ -259,15 +244,14 @@ export class Shell {
                 this.pendingEchoSkips--;
                 const rest = data.slice(nlIdx + 1);
                 if (rest)
-                    process.stdout.write(rest);
+                    this.terminal.write(rest);
                 return;
             }
-            process.stdout.write(data);
+            this.terminal.write(data);
         });
     }
     setupInput() {
-        process.stdin.on("data", (data) => {
-            const str = data.toString("utf-8");
+        this.inputDispose = this.terminal.onInput((str) => {
             this.inputHandler.handleInput(str);
         });
     }
@@ -304,7 +288,7 @@ export class Shell {
         this.bus.onPipeAsync("shell:exec-request", async (payload) => {
             const visible = this.acquireUnmute("exec-request");
             this.skipNextLine();
-            process.stdout.write("\r\n");
+            this.terminal.write("\r\n");
             this.bus.emit("shell:agent-exec-start", {});
             try {
                 const output = await new Promise((resolve, reject) => {
@@ -347,6 +331,8 @@ export class Shell {
         this.ptyProcess.onExit(callback);
     }
     kill() {
+        this.inputDispose?.();
+        this.inputDispose = null;
         this.ptyProcess.kill();
         if (this.tmpDir) {
             fs.rmSync(this.tmpDir, { recursive: true, force: true });

package/dist/shell/terminal.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Terminal — the user-facing I/O endpoint that a Shell talks to.
+ *
+ * Shell wraps a *pseudo*-terminal (the PTY the child shell sees). This
+ * interface is the *real* terminal (or its substitute) on the other end:
+ * bytes in, bytes out, dimensions, resize notifications. The default
+ * factory wires it to process.stdin/stdout for the CLI; headless hosts
+ * (multi-session web hubs, tests) supply their own.
+ */
+import type { RenderSurface } from "../utils/compositor.js";
+export interface Terminal {
+    write(data: string): void;
+    onInput(cb: (data: string) => void): () => void;
+    onResize(cb: (cols: number, rows: number) => void): () => void;
+    cols(): number;
+    rows(): number;
+    /**
+     * Called around PTY spawn to avoid TTY contention: the child PTY becomes
+     * the controlling tty for the spawned shell. No-op when the terminal
+     * isn't a real tty.
+     */
+    suspendInput?(): {
+        resume(): void;
+    };
+}
+/** Default Terminal: wraps process.stdin/stdout. */
+export declare function processTerminal(): Terminal;
+/**
+ * Adapt a Terminal to a RenderSurface (the compositor's sink type). Adds
+ * the OPOST-cleared `\n` → `\r\n` translation that StdoutSurface applies,
+ * since the PTY has OPOST disabled.
+ */
+export declare function surfaceFromTerminal(terminal: Terminal): RenderSurface;

package/dist/shell/terminal.js

@@ -0,0 +1,62 @@
+/** Default Terminal: wraps process.stdin/stdout. */
+export function processTerminal() {
+    return {
+        write(data) {
+            if (process.stdout.writable) {
+                try {
+                    process.stdout.write(data);
+                }
+                catch { /* ignore */ }
+            }
+        },
+        onInput(cb) {
+            const handler = (b) => cb(b.toString("utf-8"));
+            process.stdin.on("data", handler);
+            return () => { process.stdin.off("data", handler); };
+        },
+        onResize(cb) {
+            const handler = () => cb(process.stdout.columns || 80, process.stdout.rows || 24);
+            process.stdout.on("resize", handler);
+            return () => { process.stdout.off("resize", handler); };
+        },
+        cols() { return process.stdout.columns || 80; },
+        rows() { return process.stdout.rows || 24; },
+        suspendInput() {
+            const wasRaw = process.stdin.isTTY && process.stdin.isRaw;
+            if (process.stdin.isTTY) {
+                try {
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                }
+                catch { /* ignore */ }
+            }
+            return {
+                resume() {
+                    if (process.stdin.isTTY) {
+                        try {
+                            process.stdin.resume();
+                            if (wasRaw)
+                                process.stdin.setRawMode(true);
+                        }
+                        catch { /* ignore */ }
+                    }
+                },
+            };
+        },
+    };
+}
+/**
+ * Adapt a Terminal to a RenderSurface (the compositor's sink type). Adds
+ * the OPOST-cleared `\n` → `\r\n` translation that StdoutSurface applies,
+ * since the PTY has OPOST disabled.
+ */
+export function surfaceFromTerminal(terminal) {
+    const write = (text) => terminal.write(text.replace(/(?<!\r)\n/g, "\r\n"));
+    return {
+        write,
+        writeLine: (line) => write(line + "\n"),
+        get columns() { return terminal.cols(); },
+        get rows() { return terminal.rows(); },
+        onResize: (cb) => terminal.onResize(cb),
+    };
+}