agent-sh 0.14.1 → 0.14.3

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/output-parser.d.ts

@@ -1,42 +1,31 @@
 import type { EventBus } from "../core/event-bus.js";
-/**
- * Parses PTY output to detect command boundaries, track cwd,
- * and emit shell events. Owns the command lifecycle state.
- */
+export interface OutputParserOpts {
+    /** Optional shell-specific cleanup applied to raw output before stripAnsi. */
+    cleanOutput?(raw: string): string;
+}
 export declare class OutputParser {
     private bus;
     private cwd;
     private ownTag;
+    private cleanOutput;
     private currentOutputCapture;
     private lastCommand;
     private foregroundBusy;
     private promptReady;
-    constructor(bus: EventBus, initialCwd: string, ownTag: string);
-    /** Process a chunk of PTY output data. */
+    constructor(bus: EventBus, initialCwd: string, ownTag: string, opts?: OutputParserOpts);
     processData(data: string): void;
-    /** Called when user presses Enter on a non-empty line. */
     onCommandEntered(command: string, cwd: string): void;
-    /** Whether the shell's prompt is fully rendered and ready for input. */
     isPromptReady(): boolean;
     isForegroundBusy(): boolean;
     getCwd(): string;
-    /**
-     * Detect preexec marker (OSC 9997) emitted by the shell's preexec hook.
-     * This carries the actual command text from the shell — more reliable than
-     * the InputHandler's lineBuffer which can't track history recall or tab
-     * completion. Returns data with the OSC stripped out.
-     */
+    /** Pulls the actual command from the shell's OSC 9997 preexec marker —
+     *  more reliable than the InputHandler's lineBuffer, which can't track
+     *  history recall or tab completion. Returns data with the OSC stripped. */
     private handlePreexec;
     private parseOSC7;
-    /**
-     * Detect our custom prompt marker (OSC 9999) in the PTY stream.
-     * Each time a prompt appears, we finalize the previous command's output.
-     */
+    /** OSC 9999 marker — each occurrence finalizes the previous command's output. */
     private parsePromptMarker;
-    /**
-     * Detect end-of-prompt marker (OSC 9998). The prompt is fully rendered
-     * and the shell is ready for input.
-     */
+    /** OSC 9998 — prompt is fully rendered and the shell is ready for input. */
     private parsePromptEnd;
     private removeEchoedCommand;
 }

package/dist/shell/output-parser.js

@@ -4,32 +4,27 @@ import { stripAnsi } from "../utils/ansi.js";
 const PROMPT_RE = /\x1b\]9999;(?:id=([a-f0-9]+);)?PROMPT\x07/;
 const PREEXEC_RE = /\x1b\]9997;(?:id=([a-f0-9]+);)?([^\x07]*)\x07/;
 const READY_RE = /\x1b\]9998;(?:id=([a-f0-9]+);)?READY\x07/;
-/**
- * Parses PTY output to detect command boundaries, track cwd,
- * and emit shell events. Owns the command lifecycle state.
- */
 export class OutputParser {
     bus;
     cwd;
     ownTag;
+    cleanOutput;
     currentOutputCapture = "";
     lastCommand = "";
     foregroundBusy = false;
     promptReady = false;
-    constructor(bus, initialCwd, ownTag) {
+    constructor(bus, initialCwd, ownTag, opts = {}) {
         this.bus = bus;
         this.cwd = initialCwd;
-        // Strip the "id=" prefix; we compare the value alone.
         this.ownTag = ownTag.startsWith("id=") ? ownTag.slice(3) : ownTag;
+        this.cleanOutput = opts.cleanOutput ?? ((raw) => raw);
     }
-    /** Process a chunk of PTY output data. */
     processData(data) {
         this.parseOSC7(data);
         data = this.handlePreexec(data);
         this.parsePromptMarker(data);
         this.parsePromptEnd(data);
     }
-    /** Called when user presses Enter on a non-empty line. */
     onCommandEntered(command, cwd) {
         this.lastCommand = command;
         this.currentOutputCapture = "";
@@ -39,7 +34,6 @@ export class OutputParser {
             this.bus.emit("shell:foreground-busy", { busy: true });
         }
     }
-    /** Whether the shell's prompt is fully rendered and ready for input. */
     isPromptReady() {
         return this.promptReady;
     }
@@ -49,13 +43,9 @@ export class OutputParser {
     getCwd() {
         return this.cwd;
     }
-    // ── Parsing ─────────────────────────────────────────────────
-    /**
-     * Detect preexec marker (OSC 9997) emitted by the shell's preexec hook.
-     * This carries the actual command text from the shell — more reliable than
-     * the InputHandler's lineBuffer which can't track history recall or tab
-     * completion. Returns data with the OSC stripped out.
-     */
+    /** Pulls the actual command from the shell's OSC 9997 preexec marker —
+     *  more reliable than the InputHandler's lineBuffer, which can't track
+     *  history recall or tab completion. Returns data with the OSC stripped. */
     handlePreexec(data) {
         const match = PREEXEC_RE.exec(data);
         if (!match)
@@ -66,7 +56,8 @@ export class OutputParser {
         }
         const command = match[2];
         this.lastCommand = command;
-        this.currentOutputCapture = ""; // discard echo accumulated before preexec
+        // Discard echo accumulated before preexec.
+        this.currentOutputCapture = "";
         if (!this.foregroundBusy) {
             this.foregroundBusy = true;
             this.bus.emit("shell:foreground-busy", { busy: true });
@@ -84,21 +75,16 @@ export class OutputParser {
             }
         }
     }
-    /**
-     * Detect our custom prompt marker (OSC 9999) in the PTY stream.
-     * Each time a prompt appears, we finalize the previous command's output.
-     */
+    /** OSC 9999 marker — each occurrence finalizes the previous command's output. */
     parsePromptMarker(data) {
         const match = PROMPT_RE.exec(data);
         if (match) {
             if (match[1] !== this.ownTag) {
-                // Nested instance or untagged foreign emission — treat as opaque
-                // foreground output, do not finalize our own command.
+                // Nested or untagged emission: keep as opaque foreground output.
                 this.currentOutputCapture += data;
                 return;
             }
             const markerIdx = match.index;
-            // Capture any output that arrived in the same chunk before the marker
             if (markerIdx > 0) {
                 this.currentOutputCapture += data.slice(0, markerIdx);
             }
@@ -108,7 +94,8 @@ export class OutputParser {
                 this.bus.emit("shell:foreground-busy", { busy: false });
             }
             if (this.lastCommand) {
-                const output = stripAnsi(this.currentOutputCapture).trim();
+                const raw = this.cleanOutput(this.currentOutputCapture);
+                const output = stripAnsi(raw).trim();
                 const cleaned = this.removeEchoedCommand(output, this.lastCommand);
                 this.bus.emit("shell:command-done", {
                     command: this.lastCommand,
@@ -121,21 +108,16 @@ export class OutputParser {
             this.currentOutputCapture = "";
         }
         else {
-            // Cap capture buffer to avoid unbounded growth when a foreground
-            // program (tmux, vim, etc.) produces output without prompt markers.
-            // Keep only the tail — the final output is what matters for
-            // command-done context.
-            const MAX_CAPTURE = 128 * 1024; // 128 KB
+            // Cap to the tail so a long-running foreground program (tmux, vim)
+            // emitting output without prompt markers can't grow this unboundedly.
+            const MAX_CAPTURE = 128 * 1024;
             this.currentOutputCapture += data;
             if (this.currentOutputCapture.length > MAX_CAPTURE) {
                 this.currentOutputCapture = this.currentOutputCapture.slice(-MAX_CAPTURE);
             }
         }
     }
-    /**
-     * Detect end-of-prompt marker (OSC 9998). The prompt is fully rendered
-     * and the shell is ready for input.
-     */
+    /** OSC 9998 — prompt is fully rendered and the shell is ready for input. */
     parsePromptEnd(data) {
         const match = READY_RE.exec(data);
         if (!match)

package/dist/shell/shell-context.d.ts

@@ -1,8 +1,5 @@
-/**
- * Tracks PTY commands and cwd, spills long outputs, contributes the
- * per-query `<cwd>` (always) and `<shell_events>` (when there are fresh
- * user-shell exchanges) signals. Frontends without a PTY skip this
- * built-in and the agent runs cwd-aware via core's process.cwd() default.
- */
+/** Tracks PTY commands and cwd, spills long outputs, contributes per-query
+ *  `<cwd>` (always) and `<shell_events>` (fresh user exchanges). Frontends
+ *  without a PTY skip this and fall back to core's process.cwd() default. */
 import type { ExtensionContext } from "./host-types.js";
 export default function activate(ctx: ExtensionContext): void;

package/dist/shell/shell-context.js

@@ -6,12 +6,13 @@ export default function activate(ctx) {
     let nextId = 1;
     let currentCwd = process.cwd();
     let agentShellActive = false;
+    let nextUserExcluded = false;
     let lastSeq = 0;
     bus.on("shell:command-done", (e) => {
         const lines = e.output.split("\n");
         const s = getSettings();
-        // Long outputs spill to a tempfile so the agent can `read_file` them
-        // on demand instead of carrying the full text in LLM context.
+        // Long outputs spill to a tempfile the agent can `read_file` instead of
+        // carrying the full text in LLM context.
         let output = e.output;
         let spillPath;
         if (lines.length > s.shellTruncateThreshold) {
@@ -25,6 +26,13 @@ export default function activate(ctx) {
                 spillPath = undefined;
             }
         }
+        const source = agentShellActive
+            ? "agent"
+            : nextUserExcluded
+                ? "user-excluded"
+                : "user";
+        if (nextUserExcluded)
+            nextUserExcluded = false;
         exchanges.push({
             id: nextId++,
             timestamp: Date.now(),
@@ -34,22 +42,22 @@ export default function activate(ctx) {
             exitCode: e.exitCode,
             outputLines: lines.length,
             outputBytes: e.output.length,
-            source: agentShellActive ? "agent" : "user",
+            source,
             spillPath,
         });
     });
     bus.on("shell:cwd-change", (e) => { currentCwd = e.cwd; });
     bus.on("shell:agent-exec-start", () => { agentShellActive = true; });
     bus.on("shell:agent-exec-done", () => { agentShellActive = false; });
-    // Override core's process.cwd() default with the PTY-tracked value.
+    bus.on("shell:user-exec-exclude-next", () => { nextUserExcluded = true; });
     ctx.advise("cwd", () => currentCwd);
-    // Advises the core handler directly: shell-context loads before the
-    // agent host attaches `ctx.agent`, so the sugar isn't available yet.
+    // Advise the core handler directly: this loads before the agent host
+    // attaches `ctx.agent`, so the sugar isn't available yet.
     ctx.advise("query-context:build", (next) => {
         const base = next();
         const part = (() => {
             const cwdTag = `<cwd>${currentCwd}</cwd>`;
-            const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source !== "agent");
+            const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source === "user");
             if (fresh.length === 0)
                 return cwdTag;
             lastSeq = exchanges[exchanges.length - 1].id;

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,22 +73,13 @@ 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;
-        this.outputParser = new OutputParser(opts.bus, opts.cwd, instanceTag);
+        this.outputParser = new OutputParser(opts.bus, opts.cwd, instanceTag, {
+            cleanOutput: this.strategy.cleanOutput?.bind(this.strategy),
+        });
         // Ensure temp dir cleanup on abnormal exit (SIGKILL won't fire this,
         // but it covers uncaught exceptions and normal process.exit paths)
         if (this.tmpDir) {
@@ -259,15 +246,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 +290,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 +333,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/strategies/types.d.ts

@@ -47,4 +47,10 @@ export interface ShellStrategy {
      * Returns null if the shell can't redraw — caller falls back to freshPrompt.
      */
     redrawEscape(): string | null;
+    /**
+     * Strip shell-specific artifacts from raw PTY output before stripAnsi
+     * collapses SGR codes (e.g. zsh's PROMPT_SP inverse-video `%`). Default
+     * is identity — most shells need no cleanup.
+     */
+    cleanOutput?(raw: string): string;
 }

package/dist/shell/strategies/zsh.js

@@ -69,4 +69,11 @@ export const zshStrategy = {
     redrawEscape() {
         return "\x1b[9999~";
     },
+    cleanOutput(raw) {
+        return raw.replace(PROMPT_SP_RE, "");
+    },
 };
+/** PROMPT_SP marker (inverse-video PROMPT_EOL_MARK, default `%`) zsh prints
+ *  before a prompt when prior output didn't end at column 0. Matching the
+ *  inverse-video wrapper preserves legitimate trailing `%`. */
+const PROMPT_SP_RE = /\x1b\[7m.\x1b\[(?:0|27)m/g;

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),
+    };
+}