agent-sh 0.6.0 → 0.8.0

package/dist/utils/line-editor.d.ts

@@ -27,6 +27,9 @@ export declare class LineEditor {
     buffer: string;
     cursor: number;
     private pendingSeq;
+    private history;
+    private historyIndex;
+    private savedBuffer;
     /** Process raw terminal input, return actions for the consumer. */
     feed(data: string): LineEditAction[];
     /** Check if there's a pending incomplete escape sequence. */
@@ -34,6 +37,12 @@ export declare class LineEditor {
     /** Flush a pending sequence — treat bare \x1b as cancel, discard incomplete CSI. */
     flushPendingEscape(): LineEditAction[];
     clear(): void;
+    /** Add a line to history (most recent first). */
+    pushHistory(line: string): void;
+    /** Navigate to a previous history entry. Returns changed action or null. */
+    historyBack(): LineEditAction | null;
+    /** Navigate to a more recent history entry. Returns changed action or null. */
+    historyForward(): LineEditAction | null;
     private readonly bindings;
     /** Resolve a key name from the bindings table and execute it. */
     private dispatch;

package/dist/utils/line-editor.js

@@ -14,6 +14,10 @@ export class LineEditor {
     buffer = "";
     cursor = 0;
     pendingSeq = ""; // buffered incomplete escape sequence
+    // ── History ──────────────────────────────────────────────────
+    history = [];
+    historyIndex = -1; // -1 = current input, 0..N = history entries (newest first)
+    savedBuffer = ""; // saves current input when browsing history
     /** Process raw terminal input, return actions for the consumer. */
     feed(data) {
         // If we had a pending incomplete escape sequence, prepend it
@@ -147,6 +151,46 @@ export class LineEditor {
         this.buffer = "";
         this.cursor = 0;
         this.pendingSeq = "";
+        this.historyIndex = -1;
+        this.savedBuffer = "";
+    }
+    /** Add a line to history (most recent first). */
+    pushHistory(line) {
+        if (!line.trim())
+            return;
+        // Deduplicate: remove if already at top
+        if (this.history.length > 0 && this.history[0] === line)
+            return;
+        this.history.unshift(line);
+        // Cap history size
+        if (this.history.length > 100)
+            this.history.pop();
+    }
+    /** Navigate to a previous history entry. Returns changed action or null. */
+    historyBack() {
+        if (this.historyIndex + 1 >= this.history.length)
+            return null;
+        if (this.historyIndex === -1) {
+            this.savedBuffer = this.buffer; // save current input
+        }
+        this.historyIndex++;
+        this.buffer = this.history[this.historyIndex];
+        this.cursor = this.buffer.length;
+        return { action: "changed" };
+    }
+    /** Navigate to a more recent history entry. Returns changed action or null. */
+    historyForward() {
+        if (this.historyIndex <= -1)
+            return null;
+        this.historyIndex--;
+        if (this.historyIndex === -1) {
+            this.buffer = this.savedBuffer;
+        }
+        else {
+            this.buffer = this.history[this.historyIndex];
+        }
+        this.cursor = this.buffer.length;
+        return { action: "changed" };
     }
     // ── Key bindings ────────────────────────────────────────────
     //

package/dist/utils/markdown.js

@@ -1,4 +1,4 @@
-import { visibleLen } from "./ansi.js";
+import { visibleLen, truncateToWidth, padEndToWidth } from "./ansi.js";
 import { palette as p } from "./palette.js";
 const MAX_CONTENT_WIDTH = 90;
 /**
@@ -177,7 +177,7 @@ export class MarkdownRenderer {
         const colWidths = new Array(numCols).fill(0);
         for (const row of dataRows) {
             for (let c = 0; c < numCols; c++) {
-                colWidths[c] = Math.max(colWidths[c], row[c].length);
+                colWidths[c] = Math.max(colWidths[c], visibleLen(row[c]));
             }
         }
         // Shrink columns proportionally if total exceeds content width
@@ -201,7 +201,7 @@ export class MarkdownRenderer {
             const isHeader = hasHeader && i === 0;
             const cells = row.map((cell, c) => {
                 const w = colWidths[c];
-                const text = cell.length > w ? cell.slice(0, w - 1) + "…" : cell.padEnd(w);
+                const text = visibleLen(cell) > w ? truncateToWidth(cell, w) : padEndToWidth(cell, w);
                 return isHeader ? `${p.bold}${text}${p.reset}` : text;
             });
             this.writeLine(`${p.dim}│${p.reset} ${cells.join(` ${p.dim}│${p.reset} `)} ${p.dim}│${p.reset}`);

package/dist/utils/output-writer.d.ts

@@ -5,12 +5,26 @@
  * process.stdout.write directly.  This enables testing (BufferWriter),
  * alternative frontends, and a single point of control for output.
  */
+/** Simple ref-counted counter. Increment/decrement never goes below zero. */
+export declare class RefCounter {
+    private count;
+    increment(): void;
+    decrement(): void;
+    reset(): void;
+    get active(): boolean;
+    get value(): number;
+}
 export interface OutputWriter {
     write(text: string): void;
     get columns(): number;
 }
 /** Default writer that forwards to process.stdout. */
 export declare class StdoutWriter implements OutputWriter {
+    /** When > 0, all writes are silently dropped. Ref-counted. */
+    private readonly _hold;
+    hold(): void;
+    release(): void;
+    get held(): boolean;
     write(text: string): void;
     get columns(): number;
 }

package/dist/utils/output-writer.js

@@ -5,9 +5,25 @@
  * process.stdout.write directly.  This enables testing (BufferWriter),
  * alternative frontends, and a single point of control for output.
  */
+/** Simple ref-counted counter. Increment/decrement never goes below zero. */
+export class RefCounter {
+    count = 0;
+    increment() { this.count++; }
+    decrement() { this.count = Math.max(0, this.count - 1); }
+    reset() { this.count = 0; }
+    get active() { return this.count > 0; }
+    get value() { return this.count; }
+}
 /** Default writer that forwards to process.stdout. */
 export class StdoutWriter {
+    /** When > 0, all writes are silently dropped. Ref-counted. */
+    _hold = new RefCounter();
+    hold() { this._hold.increment(); }
+    release() { this._hold.decrement(); }
+    get held() { return this._hold.active; }
     write(text) {
+        if (this._hold.active)
+            return;
         if (process.stdout.writable) {
             try {
                 process.stdout.write(text);

package/dist/utils/terminal-buffer.d.ts

@@ -0,0 +1,69 @@
+import type { EventBus } from "../event-bus.js";
+/** Check if @xterm/headless is installed without loading it. */
+export declare function isXtermAvailable(): boolean;
+export interface TerminalBufferConfig {
+    /** Terminal width in columns. Default: process.stdout.columns || 80. */
+    cols?: number;
+    /** Terminal height in rows. Default: process.stdout.rows || 24. */
+    rows?: number;
+    /** Scrollback buffer size. Default: 200. */
+    scrollback?: number;
+}
+export interface ScreenSnapshot {
+    /** Clean text with ANSI sequences stripped. */
+    text: string;
+    /** Whether the alternate screen buffer is active (vim, htop, etc.). */
+    altScreen: boolean;
+    /** Cursor position. */
+    cursorX: number;
+    cursorY: number;
+}
+/**
+ * Format a screen snapshot as an XML context block for agent injection.
+ * Trims, caps to `maxLines` (from the bottom), and wraps in `<terminal_buffer>`.
+ * Returns the combined context string (baseContext + section), or just
+ * baseContext if the screen is empty.
+ */
+export declare function formatScreenContext(screen: ScreenSnapshot, maxLines?: number, baseContext?: string): string;
+export declare class TerminalBuffer {
+    private readonly term;
+    private readonly serializeAddon;
+    /** Flush pending drip-feed data (set by createWired). */
+    _flushPending: (() => void) | null;
+    private constructor();
+    /**
+     * Create a new TerminalBuffer. Returns null if xterm is not installed.
+     */
+    static create(config?: TerminalBufferConfig): TerminalBuffer | null;
+    /**
+     * Create a TerminalBuffer and wire it to a bus's shell:pty-data event.
+     * Returns null if xterm is not installed.
+     */
+    static createWired(bus: EventBus, config?: TerminalBufferConfig): TerminalBuffer | null;
+    /** Flush any pending drip-feed data into the virtual terminal. */
+    flush(): void;
+    /** Write raw data into the virtual terminal. */
+    write(data: string): void;
+    /** Get the raw serialized terminal output (includes ANSI sequences). */
+    serialize(): string;
+    /** Read clean screen text with metadata. */
+    readScreen(): ScreenSnapshot;
+    /**
+     * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
+     * Clean text only (ANSI stripped).  Reads from the active buffer's
+     * viewport (not scrollback), so it works correctly on both the normal
+     * and alternate screen buffers.
+     */
+    getScreenLines(rows?: number): string[];
+    /** Read visible viewport lines from a buffer. */
+    private readViewportLines;
+    /** Get cursor position. */
+    getCursor(): {
+        x: number;
+        y: number;
+    };
+    /** Resize the virtual terminal. */
+    resize(cols: number, rows: number): void;
+    /** Whether the alternate screen buffer is active. */
+    get altScreen(): boolean;
+}

package/dist/utils/terminal-buffer.js

@@ -0,0 +1,179 @@
+/**
+ * Headless terminal buffer backed by xterm.js.
+ *
+ * Provides accurate terminal screen capture — correctly handles ANSI
+ * codes, cursor movement, alternate screen (vim/htop), line wrapping,
+ * and scrollback.
+ *
+ * Used by:
+ *   - floating-panel.ts: composited overlay rendering + screen restore
+ *   - terminal-buffer extension: agent tools (terminal_read, terminal_keys)
+ *   - Any extension needing a virtual terminal snapshot
+ *
+ * The xterm dependency is loaded lazily on first use. If @xterm/headless
+ * is not installed, create() returns null.
+ *
+ * Install (optional):
+ *   npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ */
+import { createRequire } from "module";
+// ── Lazy xterm loader ───────────────────────────────────────────
+const require = createRequire(import.meta.url);
+let loadAttempted = false;
+let available = false;
+let TerminalCtor;
+let SerializeAddonCtor;
+function ensureXterm() {
+    if (loadAttempted)
+        return available;
+    loadAttempted = true;
+    try {
+        TerminalCtor = require("@xterm/headless").Terminal;
+        SerializeAddonCtor = require("@xterm/addon-serialize").SerializeAddon;
+        available = true;
+    }
+    catch {
+        available = false;
+    }
+    return available;
+}
+/** Check if @xterm/headless is installed without loading it. */
+export function isXtermAvailable() {
+    return ensureXterm();
+}
+/**
+ * Format a screen snapshot as an XML context block for agent injection.
+ * Trims, caps to `maxLines` (from the bottom), and wraps in `<terminal_buffer>`.
+ * Returns the combined context string (baseContext + section), or just
+ * baseContext if the screen is empty.
+ */
+export function formatScreenContext(screen, maxLines = 80, baseContext) {
+    const trimmed = screen.text.trim();
+    if (!trimmed)
+        return baseContext ?? "";
+    const lines = trimmed.split("\n");
+    const capped = lines.length > maxLines
+        ? lines.slice(-maxLines).join("\n")
+        : trimmed;
+    const header = screen.altScreen
+        ? "<terminal_buffer mode=\"alternate\">"
+        : "<terminal_buffer>";
+    const section = `${header}\n${capped}\n</terminal_buffer>`;
+    return baseContext ? baseContext + "\n" + section : section;
+}
+// ── TerminalBuffer ──────────────────────────────────────────────
+export class TerminalBuffer {
+    term;
+    serializeAddon;
+    /** Flush pending drip-feed data (set by createWired). */
+    _flushPending = null;
+    constructor(term, serialize) {
+        this.term = term;
+        this.serializeAddon = serialize;
+    }
+    /**
+     * Create a new TerminalBuffer. Returns null if xterm is not installed.
+     */
+    static create(config) {
+        if (!ensureXterm())
+            return null;
+        const cols = config?.cols ?? (process.stdout.columns || 80);
+        const rows = config?.rows ?? (process.stdout.rows || 24);
+        const scrollback = config?.scrollback ?? 200;
+        const term = new TerminalCtor({ cols, rows, allowProposedApi: true, scrollback });
+        const serialize = new SerializeAddonCtor();
+        term.loadAddon(serialize);
+        return new TerminalBuffer(term, serialize);
+    }
+    /**
+     * Create a TerminalBuffer and wire it to a bus's shell:pty-data event.
+     * Returns null if xterm is not installed.
+     */
+    static createWired(bus, config) {
+        const tb = TerminalBuffer.create(config);
+        if (!tb)
+            return null;
+        // Buffer PTY data and drip-feed to xterm in the background.
+        // Synchronous term.write() in the pty-data handler introduces enough
+        // latency to change PTY read coalescing, causing visual artifacts.
+        let pending = "";
+        bus.on("shell:pty-data", ({ raw }) => { pending += raw; });
+        setInterval(() => {
+            if (pending) {
+                const d = pending;
+                pending = "";
+                tb.write(d);
+            }
+        }, 50);
+        tb._flushPending = () => {
+            if (pending) {
+                const d = pending;
+                pending = "";
+                tb.write(d);
+            }
+        };
+        process.stdout.on("resize", () => {
+            tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
+        });
+        return tb;
+    }
+    /** Flush any pending drip-feed data into the virtual terminal. */
+    flush() {
+        this._flushPending?.();
+    }
+    /** Write raw data into the virtual terminal. */
+    write(data) {
+        this.term.write(data);
+    }
+    /** Get the raw serialized terminal output (includes ANSI sequences). */
+    serialize() {
+        return this.serializeAddon.serialize();
+    }
+    /** Read clean screen text with metadata. */
+    readScreen() {
+        const buf = this.term.buffer.active;
+        const lines = this.readViewportLines(buf);
+        return {
+            text: lines.join("\n"),
+            altScreen: buf.type === "alternate",
+            cursorX: buf.cursorX,
+            cursorY: buf.cursorY,
+        };
+    }
+    /**
+     * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
+     * Clean text only (ANSI stripped).  Reads from the active buffer's
+     * viewport (not scrollback), so it works correctly on both the normal
+     * and alternate screen buffers.
+     */
+    getScreenLines(rows) {
+        const targetRows = rows ?? (process.stdout.rows || 24);
+        return this.readViewportLines(this.term.buffer.active, targetRows);
+    }
+    /** Read visible viewport lines from a buffer. */
+    readViewportLines(buf, rows) {
+        const targetRows = rows ?? buf.length;
+        const base = buf.baseY ?? 0;
+        const lines = [];
+        for (let y = 0; y < targetRows; y++) {
+            const line = buf.getLine(base + y);
+            lines.push(line ? line.translateToString(true) : "");
+        }
+        return lines;
+    }
+    /** Get cursor position. */
+    getCursor() {
+        return {
+            x: this.term.buffer.active.cursorX,
+            y: this.term.buffer.active.cursorY,
+        };
+    }
+    /** Resize the virtual terminal. */
+    resize(cols, rows) {
+        this.term.resize(cols, rows);
+    }
+    /** Whether the alternate screen buffer is active. */
+    get altScreen() {
+        return this.term.buffer.active.type === "alternate";
+    }
+}

package/dist/utils/tool-display.d.ts

@@ -30,6 +30,7 @@ export declare function selectToolDisplayMode(width: number): ToolDisplayMode;
 export declare function renderToolCall(tool: ToolCallRender, width: number): string[];
 export declare function renderToolResult(result: ToolResultRender, width: number): string[];
 export declare function formatElapsed(ms: number): string;
+export declare const SPINNER_FRAMES: string[];
 export interface SpinnerState {
     frame: number;
     startTime: number;

package/dist/utils/tool-display.js

@@ -205,7 +205,7 @@ export function formatElapsed(ms) {
     return rm > 0 ? `${h}h ${rm}m` : `${h}h`;
 }
 // ── Spinner with elapsed timer ───────────────────────────────────
-const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 export function createSpinner(opts) {
     return { frame: 0, startTime: opts?.startTime || Date.now() };
 }

package/examples/extensions/claude-code-bridge/index.ts

@@ -23,6 +23,23 @@ import { z } from "zod";
 import type { ExtensionContext } from "../../src/types.js";
 import type { EventBus } from "../../src/event-bus.js";
 
+// ── Helpers ──────────────────────────────────────────────────────
+function interpretEscapes(str: string): string {
+  return str.replace(/\\(x[0-9a-fA-F]{2}|r|n|t|\\|0)/g, (_, seq: string) => {
+    if (seq === "r") return "\r";
+    if (seq === "n") return "\n";
+    if (seq === "t") return "\t";
+    if (seq === "\\") return "\\";
+    if (seq === "0") return "\0";
+    if (seq.startsWith("x")) return String.fromCharCode(parseInt(seq.slice(1), 16));
+    return seq;
+  });
+}
+
+function settle(ms = 100): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // ── user_shell MCP tool ───────────────────────────────────────────
 function createUserShellTool(bus: EventBus) {
   let liveCwd = process.cwd();
@@ -56,15 +73,72 @@ function createUserShellTool(bus: EventBus) {
   );
 }
 
+// ── terminal_read MCP tool ────────────────────────────────────────
+function createTerminalReadTool(ctx: ExtensionContext) {
+  return tool(
+    "terminal_read",
+    "Read the current terminal screen contents. Returns clean text (ANSI stripped) " +
+    "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
+    "Use this to see what the user sees before sending keystrokes with terminal_keys.",
+    {},
+    async () => {
+      const tb = ctx.terminalBuffer;
+      if (!tb) return { content: [{ type: "text" as const, text: "terminal buffer not available" }] };
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+      return { content: [{ type: "text" as const, text: `[${info}]\n\n${text}` }] };
+    },
+  );
+}
+
+// ── terminal_keys MCP tool ───────────────────────────────────────
+function createTerminalKeysTool(bus: EventBus, ctx: ExtensionContext) {
+  return tool(
+    "terminal_keys",
+    "Send keystrokes to the user's live terminal. The keys are written directly to the PTY " +
+    "as if the user typed them. Use escape sequences for special keys:\n" +
+    "  - Escape: \\x1b  - Enter: \\r  - Tab: \\t\n" +
+    "  - Ctrl+C: \\x03  - Arrow keys: \\x1b[A/B/C/D  - Backspace: \\x7f\n" +
+    "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\".\n" +
+    "Always call terminal_read after sending keys to verify the result.",
+    {
+      keys: z.string().describe("Keystrokes to send (use \\x1b for Escape, \\r for Enter, etc.)"),
+      settle_ms: z.number().optional().describe("Wait time in ms after sending keys (default: 150)"),
+    },
+    async (args) => {
+      const keys = interpretEscapes(args.keys);
+      const settleMs = args.settle_ms ?? 150;
+      bus.emit("shell:stdout-show", {});
+      process.stdout.write("\n");
+      bus.emit("shell:pty-write", { data: keys });
+      await settle(settleMs);
+
+      const tb = ctx.terminalBuffer;
+      if (!tb) return { content: [{ type: "text" as const, text: "Keys sent." }] };
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+      return { content: [{ type: "text" as const, text: `Keys sent. Screen after:\n[${info}]\n\n${text}` }] };
+    },
+  );
+}
+
 // ── Extension entry point ─────────────────────────────────────────
 export default function activate(ctx: ExtensionContext): void {
   const { bus } = ctx;
 
   const shellTool = createUserShellTool(bus);
+  const termReadTool = createTerminalReadTool(ctx);
+  const termKeysTool = createTerminalKeysTool(bus, ctx);
   const shellServer = createSdkMcpServer({
     name: "agent-sh",
     version: "1.0.0",
-    tools: [shellTool],
+    tools: [shellTool, termReadTool, termKeysTool],
   });
 
   let activeQuery: Query | null = null;
@@ -95,6 +169,8 @@ export default function activate(ctx: ExtensionContext): void {
             mcpServers: { "agent-sh": shellServer },
             allowedTools: [
               "mcp__agent-sh__user_shell",
+              "mcp__agent-sh__terminal_read",
+              "mcp__agent-sh__terminal_keys",
               "Read", "Edit", "Write", "Bash", "Glob", "Grep",
             ],
             permissionMode: "acceptEdits",

package/examples/extensions/overlay-agent.ts

@@ -0,0 +1,70 @@
+/**
+ * Overlay agent extension.
+ *
+ * Provides a hotkey (Ctrl+\) to summon the agent from anywhere — even
+ * inside vim, htop, or ssh. Composites a floating response box on top
+ * of the current terminal content.
+ *
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/overlay-agent.ts
+ *
+ *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
+ *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
+ */
+import type { ExtensionContext } from "agent-sh/types";
+import { formatScreenContext } from "agent-sh/utils/terminal-buffer.js";
+
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+export default function activate({ bus, advise, createFloatingPanel, terminalBuffer }: ExtensionContext): void {
+  const panel = createFloatingPanel({
+    trigger: "\x1c", // Ctrl+\
+    dimBackground: true,
+    autoDismissMs: 2000,
+  });
+
+  // ── Inject terminal buffer into agent context ──────────────
+  if (terminalBuffer) {
+    advise("context:build-extra", (next: () => string) =>
+      formatScreenContext(terminalBuffer.readScreen(), 80, next()),
+    );
+  }
+
+  // ── Panel lifecycle ────────────────────────────────────────
+  panel.handlers.advise("panel:submit", (_next, query: string) => {
+    panel.setActive();
+    panel.appendLine(`${CYAN}${BOLD}❯${RESET} ${query}`);
+    panel.appendLine("");
+    bus.emit("agent:submit", { query });
+  });
+
+  // ── Stream agent response into panel ───────────────────────
+  bus.on("agent:response-chunk", (e) => {
+    if (!panel.active) return;
+    for (const block of e.blocks) {
+      if (block.type === "text" && block.text) {
+        panel.appendText(block.text);
+      }
+    }
+  });
+
+  bus.on("agent:tool-started", (e) => {
+    if (!panel.active) return;
+    panel.appendLine(`▶ ${e.title}${e.displayDetail ? " " + e.displayDetail : ""}`);
+  });
+
+  bus.on("agent:tool-completed", (e) => {
+    if (!panel.active) return;
+    const mark = e.exitCode === 0 ? " ✓" : ` ✗ exit ${e.exitCode}`;
+    panel.updateLastLine((line) => line + mark);
+  });
+
+  bus.on("agent:processing-done", () => {
+    if (!panel.active) return;
+    panel.setDone();
+  });
+}