agent-sh 0.6.0 → 0.7.0

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

@@ -0,0 +1,65 @@
+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;
+    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;
+    /** 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,166 @@
+/**
+ * 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;
+    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);
+        process.stdout.on("resize", () => {
+            tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
+        });
+        return tb;
+    }
+    /** 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/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();
+  });
+}

package/examples/extensions/terminal-buffer.ts

@@ -0,0 +1,184 @@
+/**
+ * Terminal buffer extension.
+ *
+ * Maintains a headless xterm.js terminal fed from raw PTY data.
+ * Provides an accurate, clean-text snapshot of the terminal screen
+ * that the agent can use for context — handling ANSI codes, cursor
+ * movement, alternate screen (vim/htop), and line wrapping correctly.
+ *
+ * Registers two agent tools:
+ *   - terminal_read: get the current screen contents + cursor position
+ *   - terminal_keys: send raw keystrokes into the user's live PTY
+ *
+ * Together these let the agent operate inside interactive programs
+ * (vim, htop, less, etc.) by reading the screen and typing keys.
+ *
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/terminal-buffer.ts
+ *
+ *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
+ *   cp examples/extensions/terminal-buffer.ts ~/.agent-sh/extensions/
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+/** Wait for PTY output to settle after sending keystrokes. */
+function settle(ms = 100): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Interpret C-style escape sequences in a string (e.g. \r → CR, \x1b → ESC). */
+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;
+  });
+}
+
+export default function activate({ bus, terminalBuffer: tb, registerTool }: ExtensionContext): void {
+  if (!tb) {
+    console.warn("terminal-buffer: @xterm/headless not installed — extension disabled");
+    return;
+  }
+
+  // ── Agent tools ─────────────────────────────────────────────
+  // Context injection is intentionally NOT done here — the terminal
+  // buffer content would bloat every agent message.  The agent can
+  // call terminal_read on demand, and the overlay extension injects
+  // context only when the overlay is active.
+
+  registerTool({
+    name: "terminal_read",
+    description:
+      "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.",
+    input_schema: {
+      type: "object",
+      properties: {},
+    },
+    showOutput: true,
+
+    getDisplayInfo: () => ({
+      kind: "read" as const,
+      icon: "⊞",
+      locations: [],
+    }),
+
+    async execute() {
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+
+      return {
+        content: `[${info}]\n\n${text}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+
+  registerTool({
+    name: "terminal_keys",
+    description:
+      "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\n" +
+      "  - Enter/Return: \\r\n" +
+      "  - Tab: \\t\n" +
+      "  - Ctrl+C: \\x03\n" +
+      "  - Ctrl+D: \\x04\n" +
+      "  - Ctrl+Z: \\x1a\n" +
+      "  - Arrow keys: \\x1b[A (up), \\x1b[B (down), \\x1b[C (right), \\x1b[D (left)\n" +
+      "  - Backspace: \\x7f\n\n" +
+      "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\" (Escape, :q!, Enter).\n" +
+      "Always call terminal_read after sending keys to verify the result.",
+    input_schema: {
+      type: "object",
+      properties: {
+        keys: {
+          type: "string",
+          description:
+            "The keystrokes to send. Use \\x1b for Escape, \\r for Enter, \\t for Tab, " +
+            "\\x03 for Ctrl+C, etc. Regular characters are sent as-is.",
+        },
+        settle_ms: {
+          type: "number",
+          description:
+            "Milliseconds to wait after sending keys for the terminal to settle before " +
+            "returning (default: 150). Increase for slow programs.",
+        },
+      },
+      required: ["keys"],
+    },
+    showOutput: false,
+
+    getDisplayInfo: (args) => ({
+      kind: "execute" as const,
+      icon: "⌨",
+      locations: [],
+    }),
+
+    formatCall: (args) => {
+      const keys = args.keys as string;
+      // Show a readable version of the keys — handle both literal
+      // escape strings (\\x1b) and actual bytes (\x1b)
+      return keys
+        .replace(/\\x1b|\x1b/g, "ESC")
+        .replace(/\\r|\r/g, "⏎")
+        .replace(/\\n|\n/g, "↵")
+        .replace(/\\t|\t/g, "TAB")
+        .replace(/\\x03|\x03/g, "^C")
+        .replace(/\\x04|\x04/g, "^D")
+        .replace(/\\x7f|\x7f/g, "BS");
+    },
+
+    async execute(args) {
+      const raw = args.keys as string;
+      const keys = interpretEscapes(raw);
+      const settleMs = (args.settle_ms as number) ?? 150;
+
+      // Force PTY output visible so the user sees the program's response.
+      // Stays visible for the rest of agent processing — Shell resets
+      // paused=false on processing-done anyway.
+      bus.emit("shell:stdout-show", {});
+      process.stdout.write("\n");
+      bus.emit("shell:pty-write", { data: keys });
+
+      // Wait for the terminal to process the keystrokes and render
+      await settle(settleMs);
+
+      // Return the screen state after the keystrokes
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+      const info = [
+        altScreen ? "mode: alternate screen" : "mode: normal",
+        `cursor: row=${cursorY} col=${cursorX}`,
+      ].join(", ");
+
+      return {
+        content: `Keys sent. Screen after:\n[${info}]\n\n${text}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+
+  // ── Bus snapshot for other extensions ───────────────────────
+
+  bus.on("shell:buffer-request", () => {
+    const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+    bus.emit("shell:buffer-snapshot", {
+      text,
+      altScreen,
+      cursor: { x: cursorX, y: cursorY },
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -29,6 +29,10 @@
     "./utils/stream-transform": {
       "types": "./dist/utils/stream-transform.d.ts",
       "default": "./dist/utils/stream-transform.js"
+    },
+    "./utils/terminal-buffer": {
+      "types": "./dist/utils/terminal-buffer.d.ts",
+      "default": "./dist/utils/terminal-buffer.js"
     }
   },
   "files": [