agent-sh 0.6.0 → 0.7.0

package/dist/context-manager.d.ts

@@ -1,4 +1,5 @@
 import type { EventBus } from "./event-bus.js";
+import type { HandlerRegistry } from "./utils/handler-registry.js";
 export declare class ContextManager {
     private exchanges;
     private nextId;
@@ -7,7 +8,8 @@ export declare class ContextManager {
     private pendingToolCalls;
     private firstPrompt;
     private agentShellActive;
-    constructor(bus: EventBus);
+    private handlers;
+    constructor(bus: EventBus, handlers?: HandlerRegistry);
     getCwd(): string;
     /**
      * Build the <shell_context> block for the agent prompt.

package/dist/context-manager.js

@@ -13,7 +13,13 @@ export class ContextManager {
     pendingToolCalls = [];
     firstPrompt = true;
     agentShellActive = false; // true while user_shell command is executing
-    constructor(bus) {
+    handlers = null;
+    constructor(bus, handlers) {
+        if (handlers) {
+            this.handlers = handlers;
+            // Extensions can advise this to inject extra context (e.g. terminal buffer)
+            handlers.define("context:build-extra", () => "");
+        }
         this.currentCwd = process.cwd();
         this.sessionStart = Date.now();
         // ── Subscribe to shell events ──
@@ -291,6 +297,10 @@ export class ContextManager {
         for (const ex of exchanges) {
             out += "\n" + this.formatExchangeTruncated(ex);
         }
+        // Allow extensions to inject extra context (e.g. terminal buffer snapshot)
+        const extra = this.handlers?.call("context:build-extra");
+        if (extra)
+            out += "\n" + extra + "\n";
         out += "\n</shell_context>\n";
         return out;
     }

package/dist/core.js

@@ -25,6 +25,8 @@ import * as streamTransform from "./utils/stream-transform.js";
 import * as settingsMod from "./settings.js";
 import { resolveProvider, getProviderNames } from "./settings.js";
 import { HandlerRegistry } from "./utils/handler-registry.js";
+import { TerminalBuffer } from "./utils/terminal-buffer.js";
+import { FloatingPanel } from "./utils/floating-panel.js";
 // Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
@@ -33,7 +35,7 @@ export { LlmClient } from "./utils/llm-client.js";
 export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
-    const contextManager = new ContextManager(bus);
+    const contextManager = new ContextManager(bus, handlers);
     // ── Resolve provider ─────────────────────────────────────────
     const settings = settingsMod.getSettings();
     let activeProvider = null;
@@ -216,6 +218,14 @@ export function createCore(config) {
         bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
         bus.emit("config:changed", {});
     });
+    // ── Lazy singleton terminal buffer ──────────────────────────
+    let terminalBufferSingleton; // undefined = not yet created
+    const getTerminalBuffer = () => {
+        if (terminalBufferSingleton !== undefined)
+            return terminalBufferSingleton;
+        terminalBufferSingleton = TerminalBuffer.createWired(bus);
+        return terminalBufferSingleton;
+    };
     return {
         bus,
         contextManager,
@@ -292,6 +302,11 @@ export function createCore(config) {
                 define: (name, fn) => handlers.define(name, fn),
                 advise: (name, wrapper) => handlers.advise(name, wrapper),
                 call: (name, ...args) => handlers.call(name, ...args),
+                get terminalBuffer() { return getTerminalBuffer(); },
+                createFloatingPanel: (config) => {
+                    const tb = config.dimBackground !== false ? getTerminalBuffer() : null;
+                    return new FloatingPanel(bus, { ...config, terminalBuffer: tb ?? undefined });
+                },
             };
         },
         kill() {

package/dist/event-bus.d.ts

@@ -22,6 +22,21 @@ export interface ShellEvents {
     };
     "shell:agent-exec-start": Record<string, never>;
     "shell:agent-exec-done": Record<string, never>;
+    "shell:pty-data": {
+        raw: string;
+    };
+    "shell:pty-write": {
+        data: string;
+    };
+    "shell:buffer-request": Record<string, never>;
+    "shell:buffer-snapshot": {
+        text: string;
+        altScreen: boolean;
+        cursor: {
+            x: number;
+            y: number;
+        };
+    };
     "agent:submit": {
         query: string;
     };
@@ -123,6 +138,14 @@ export interface ShellEvents {
     "input:keypress": {
         key: string;
     };
+    "input:intercept": {
+        data: string;
+        consumed: boolean;
+    };
+    "shell:stdout-hold": Record<string, never>;
+    "shell:stdout-release": Record<string, never>;
+    "shell:stdout-show": Record<string, never>;
+    "shell:stdout-hide": Record<string, never>;
     "agent:terminal-intercept": {
         command: string;
         cwd: string;

package/dist/extensions/overlay-agent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Built-in overlay agent.
+ *
+ * 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
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate({ bus, createFloatingPanel }: ExtensionContext): void;

package/dist/extensions/overlay-agent.js

@@ -0,0 +1,43 @@
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+export default function activate({ bus, createFloatingPanel }) {
+    const panel = createFloatingPanel({
+        trigger: "\x1c", // Ctrl+\
+        dimBackground: true,
+        autoDismissMs: 2000,
+    });
+    // ── Panel lifecycle ────────────────────────────────────────
+    panel.handlers.advise("panel:submit", (_next, query) => {
+        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/dist/extensions/terminal-buffer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in terminal buffer extension.
+ *
+ * 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
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate({ bus, terminalBuffer: tb, registerTool }: ExtensionContext): void;

package/dist/extensions/terminal-buffer.js

@@ -0,0 +1,120 @@
+/** Interpret C-style escape sequences (e.g. \r → CR, \x1b → ESC). */
+function interpretEscapes(str) {
+    return str.replace(/\\(x[0-9a-fA-F]{2}|r|n|t|\\|0)/g, (_, seq) => {
+        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) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export default function activate({ bus, terminalBuffer: tb, registerTool }) {
+    if (!tb)
+        return; // @xterm/headless not installed
+    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",
+            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: () => ({
+            kind: "execute",
+            icon: "⌨",
+            locations: [],
+        }),
+        formatCall: (args) => {
+            const keys = args.keys;
+            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;
+            const keys = interpretEscapes(raw);
+            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 { 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,
+            };
+        },
+    });
+}

package/dist/extensions/tui-renderer.js

@@ -71,6 +71,9 @@ export default function activate(ctx) {
     const { bus, llmClient, define } = ctx;
     const writer = new StdoutWriter();
     const s = createRenderState();
+    // Suppress all TUI output while stdout is held (overlay extensions)
+    bus.on("shell:stdout-hold", () => { writer.hold(); });
+    bus.on("shell:stdout-release", () => { writer.release(); });
     // Track backend/model info for display on response border
     let backendInfo = null;
     bus.on("agent:info", (info) => { backendInfo = info; });

package/dist/index.js

@@ -9,6 +9,8 @@ import slashCommands from "./extensions/slash-commands.js";
 import fileAutocomplete from "./extensions/file-autocomplete.js";
 import shellRecall from "./extensions/shell-recall.js";
 import commandSuggest from "./extensions/command-suggest.js";
+import terminalBuffer from "./extensions/terminal-buffer.js";
+import overlayAgent from "./extensions/overlay-agent.js";
 import { loadExtensions } from "./extension-loader.js";
 import { getSettings } from "./settings.js";
 import { discoverSkills } from "./agent/skills.js";
@@ -232,6 +234,8 @@ async function main() {
     fileAutocomplete(extCtx);
     shellRecall(extCtx);
     commandSuggest(extCtx);
+    terminalBuffer(extCtx);
+    overlayAgent(extCtx);
     // Load user extensions (may register alternative agent backends)
     if (process.env.DEBUG) {
         console.error('[agent-sh] Loading extensions...');

package/dist/input-handler.js

@@ -137,6 +137,10 @@ export class InputHandler {
         }
     }
     handleInput(data) {
+        // Allow extensions to capture raw input (e.g. overlay prompt during vim)
+        const intercepted = this.bus.emitPipe("input:intercept", { data, consumed: false });
+        if (intercepted.consumed)
+            return;
         // If agent is running (processing a query), only Ctrl-C and control keys
         if (this.ctx.isAgentActive()) {
             if (data === "\x03") {
@@ -235,7 +239,8 @@ export class InputHandler {
                     this.enterMode(mode);
                     return; // don't process remaining chars
                 }
-                this.lineBuffer += ch;
+                if (!this.ctx.isForegroundBusy())
+                    this.lineBuffer += ch;
                 this.ctx.writeToPty(ch);
             }
         }

package/dist/output-parser.js

@@ -109,7 +109,15 @@ 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
             this.currentOutputCapture += data;
+            if (this.currentOutputCapture.length > MAX_CAPTURE) {
+                this.currentOutputCapture = this.currentOutputCapture.slice(-MAX_CAPTURE);
+            }
         }
     }
     /**

package/dist/shell.d.ts

@@ -6,6 +6,8 @@ export declare class Shell implements InputContext {
     private inputHandler;
     private outputParser;
     private paused;
+    private stdoutHold;
+    private stdoutShow;
     private echoSkip;
     private agentActive;
     private isZsh;
@@ -37,6 +39,9 @@ export declare class Shell implements InputContext {
      * Heavy redraw: send \n to PTY to trigger a full precmd → prompt cycle.
      * Use this after agent responses where stdout has moved far from where
      * zle expects the cursor. The blank line is acceptable as a separator.
+     *
+     * Routed through shell:redraw-prompt pipe so extensions (e.g. overlay)
+     * can suppress it by setting `handled: true`.
      */
     freshPrompt(): void;
     onCommandEntered(command: string, cwd: string): void;

package/dist/shell.js

@@ -5,12 +5,15 @@ import * as pty from "node-pty";
 import { InputHandler } from "./input-handler.js";
 import { OutputParser } from "./output-parser.js";
 import { getSettings } from "./settings.js";
+import { RefCounter } from "./utils/output-writer.js";
 export class Shell {
     ptyProcess;
     bus;
     inputHandler;
     outputParser;
     paused = false;
+    stdoutHold = new RefCounter();
+    stdoutShow = new RefCounter();
     echoSkip = false;
     agentActive = false;
     isZsh = false;
@@ -156,6 +159,16 @@ export class Shell {
         this.setupOutput();
         this.setupInput();
         this.setupAgentLifecycle();
+        // Allow extensions to inject raw keystrokes into the PTY
+        this.bus.on("shell:pty-write", ({ data }) => {
+            this.ptyProcess.write(data);
+        });
+        // Ref-counted stdout hold — overlay extensions suppress PTY output
+        this.bus.on("shell:stdout-hold", () => { this.stdoutHold.increment(); });
+        this.bus.on("shell:stdout-release", () => { this.stdoutHold.decrement(); });
+        // Ref-counted stdout show — tools temporarily force output visible during agent processing
+        this.bus.on("shell:stdout-show", () => { this.stdoutShow.increment(); });
+        this.bus.on("shell:stdout-hide", () => { this.stdoutShow.decrement(); });
     }
     // ── InputContext implementation (delegates to OutputParser) ──
     isForegroundBusy() {
@@ -197,9 +210,18 @@ export class Shell {
      * Heavy redraw: send \n to PTY to trigger a full precmd → prompt cycle.
      * Use this after agent responses where stdout has moved far from where
      * zle expects the cursor. The blank line is acceptable as a separator.
+     *
+     * Routed through shell:redraw-prompt pipe so extensions (e.g. overlay)
+     * can suppress it by setting `handled: true`.
      */
     freshPrompt() {
-        this.ptyProcess.write("\n");
+        const result = this.bus.emitPipe("shell:redraw-prompt", {
+            cwd: this.outputParser.getCwd(),
+            handled: false,
+        });
+        if (!result.handled) {
+            this.ptyProcess.write("\n");
+        }
     }
     onCommandEntered(command, cwd) {
         this.outputParser.onCommandEntered(command, cwd);
@@ -207,8 +229,11 @@ export class Shell {
     // ── PTY I/O wiring ─────────────────────────────────────────
     setupOutput() {
         this.ptyProcess.onData((data) => {
+            this.bus.emit("shell:pty-data", { raw: data });
             this.outputParser.processData(data);
-            if (this.paused)
+            if (this.stdoutHold.active)
+                return;
+            if (this.paused && !this.stdoutShow.active)
                 return;
             // During user_shell exec, skip the command echo (first line)
             if (this.echoSkip) {

package/dist/types.d.ts

@@ -4,6 +4,8 @@ import type { LlmClient } from "./utils/llm-client.js";
 import type { ColorPalette } from "./utils/palette.js";
 import type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 import type { ToolDefinition } from "./agent/types.js";
+import type { TerminalBuffer } from "./utils/terminal-buffer.js";
+import type { FloatingPanel, FloatingPanelConfig } from "./utils/floating-panel.js";
 export type { ContentBlock } from "./event-bus.js";
 export type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 /** A model entry in the cycling list, optionally tied to a provider. */
@@ -66,6 +68,17 @@ export interface ExtensionContext {
     advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => void;
     /** Call a named handler. */
     call: (name: string, ...args: any[]) => any;
+    /**
+     * Shared headless terminal buffer mirroring PTY output.
+     * Lazily created on first access. Returns null if @xterm/headless is not installed.
+     */
+    terminalBuffer: TerminalBuffer | null;
+    /**
+     * Create a floating panel overlay. The panel composites a bordered box
+     * over the terminal with input routing, dimmed background, and
+     * handler-based customization.
+     */
+    createFloatingPanel: (config: FloatingPanelConfig) => FloatingPanel;
 }
 /**
  * Configuration for a registered input mode.