agent-sh 0.5.0 → 0.7.0

package/dist/agent/types.d.ts

@@ -21,15 +21,36 @@ export interface ToolResult {
     exitCode: number | null;
     isError: boolean;
 }
+/** Structured result display — returned by formatResult or computed by defaults. */
+export interface ToolResultDisplay {
+    /** One-line summary shown next to ✓/✗ (e.g. "42 papers found", "+3/-1"). */
+    summary?: string;
+    /** Structured content to render below the status line. */
+    body?: ToolResultBody;
+}
+export type ToolResultBody = {
+    kind: "diff";
+    diff: unknown;
+    filePath: string;
+} | {
+    kind: "lines";
+    lines: string[];
+    maxLines?: number;
+};
 export interface ToolDisplayInfo {
-    kind: "read" | "write" | "execute" | "search";
+    kind: "read" | "write" | "execute" | "search" | "display";
     locations?: {
         path: string;
         line?: number | null;
     }[];
+    /** Custom icon character for TUI display (e.g., "◆", "⌕"). When set, the TUI shows
+     *  icon + detail only. When absent, the tool name is shown alongside the detail. */
+    icon?: string;
 }
 export interface ToolDefinition {
     name: string;
+    /** Short label for TUI display (e.g. "search" instead of "ads_search"). Defaults to name. */
+    displayName?: string;
     description: string;
     input_schema: Record<string, unknown>;
     execute(args: Record<string, unknown>, onChunk?: (chunk: string) => void): Promise<ToolResult>;
@@ -41,4 +62,17 @@ export interface ToolDefinition {
     requiresPermission?: boolean;
     /** Derive display metadata (icon kind, file paths) for the TUI. */
     getDisplayInfo?: (args: Record<string, unknown>) => ToolDisplayInfo;
+    /**
+     * Format a short display string for the TUI when this tool is called.
+     * Return a concise summary of the args (e.g. the query, the file path).
+     * When absent, the TUI derives the detail from common arg fields (command, path, pattern).
+     */
+    formatCall?: (args: Record<string, unknown>) => string;
+    /**
+     * Format result display for the TUI after execution completes.
+     * Return a summary string and/or structured body to render.
+     * When absent, defaults are computed based on tool kind.
+     * Extensions can further override via bus.onPipe("agent:tool-completed", ...).
+     */
+    formatResult?: (args: Record<string, unknown>, result: ToolResult) => ToolResultDisplay;
 }

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.d.ts

@@ -36,9 +36,7 @@ export interface AgentShellCore {
     /** Activate the agent backend (call after extensions load). */
     activateBackend(): void;
     /** Convenience: emit agent:submit and await the response. */
-    query(text: string, opts?: {
-        mode?: string;
-    }): Promise<string>;
+    query(text: string): Promise<string>;
     /** Convenience: emit agent:cancel-request. */
     cancel(): void;
     /** Build an ExtensionContext for loading extensions against this core. */

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,17 +218,27 @@ 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,
         llmClient,
         activateBackend() {
+            // Silent — backend info is shown in the startup banner.
+            // Runtime switches (config:switch-backend) still emit ui:info.
             const preferred = settings.defaultBackend;
             if (preferred && backends.has(preferred)) {
-                activateByName(preferred);
+                activateByName(preferred, true);
             }
             else if (backends.size > 0 && !agentLoop) {
-                activateByName(backends.keys().next().value);
+                activateByName(backends.keys().next().value, true);
             }
             else if (agentLoop) {
                 agentLoop.wire();
@@ -234,13 +246,10 @@ export function createCore(config) {
                 bus.emit("agent:info", { name: "agent-sh", version: "0.4", model: llmClient?.model, provider: activeProvider?.id, contextWindow: activeProvider?.contextWindow });
             }
             else if (backends.size > 0) {
-                activateByName(backends.keys().next().value);
-            }
-            if (activeBackendName) {
-                bus.emit("ui:info", { message: `Backend: ${activeBackendName}` });
+                activateByName(backends.keys().next().value, true);
             }
         },
-        async query(text, opts) {
+        async query(text) {
             return new Promise((resolve, reject) => {
                 let response = "";
                 let settled = false;
@@ -271,10 +280,7 @@ export function createCore(config) {
                 bus.on("agent:response-chunk", onChunk);
                 bus.on("agent:processing-done", onDone);
                 bus.on("agent:error", onError);
-                bus.emit("agent:submit", {
-                    query: text,
-                    modeInstruction: opts?.mode,
-                });
+                bus.emit("agent:submit", { query: text });
             });
         },
         cancel() {
@@ -296,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

@@ -1,4 +1,5 @@
 import type { AgentMode } from "./types.js";
+import type { ToolResultDisplay } from "./agent/types.js";
 /**
  * Typed event map — every event has a known payload shape.
  */
@@ -21,10 +22,23 @@ 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;
-        modeInstruction?: string;
-        modeLabel?: string;
     };
     "agent:cancel-request": {
         silent?: boolean;
@@ -32,7 +46,6 @@ export interface ShellEvents {
     "input-mode:register": import("./types.js").InputModeConfig;
     "agent:query": {
         query: string;
-        modeLabel?: string;
     };
     "agent:thinking-chunk": {
         text: string;
@@ -63,21 +76,37 @@ export interface ShellEvents {
         output: string;
         exitCode: number | null;
     };
+    "agent:tool-batch": {
+        groups: Array<{
+            kind: string;
+            tools: Array<{
+                name: string;
+                displayDetail?: string;
+            }>;
+        }>;
+    };
     "agent:tool-started": {
         title: string;
         toolCallId?: string;
         kind?: string;
+        icon?: string;
         locations?: {
             path: string;
             line?: number | null;
         }[];
         rawInput?: unknown;
+        /** Pre-formatted display detail from tool's formatCall(). */
+        displayDetail?: string;
+        batchIndex?: number;
+        batchTotal?: number;
     };
     "agent:tool-completed": {
         toolCallId?: string;
         exitCode: number | null;
         rawOutput?: unknown;
         kind?: string;
+        /** Structured result display — set by formatResult or defaults, overridable via onPipe. */
+        resultDisplay?: ToolResultDisplay;
     };
     "agent:tool-output-chunk": {
         chunk: string;
@@ -109,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;
@@ -123,6 +160,7 @@ export interface ShellEvents {
         command: string;
         output: string;
         cwd: string;
+        exitCode: number | null;
         done: boolean;
     };
     "agent:info": {

package/dist/extension-loader.d.ts

@@ -13,4 +13,4 @@ import type { ExtensionContext } from "./types.js";
  * Each module should export a default or named `activate(ctx)` function.
  * Errors are non-fatal — logged via ui:error and skipped.
  */
-export declare function loadExtensions(ctx: ExtensionContext, cliExtensions?: string[]): Promise<void>;
+export declare function loadExtensions(ctx: ExtensionContext, cliExtensions?: string[]): Promise<string[]>;

package/dist/extension-loader.js

@@ -102,9 +102,7 @@ export async function loadExtensions(ctx, cliExtensions) {
             });
         }
     }
-    if (loaded.length > 0) {
-        ctx.bus.emit("ui:info", { message: `Extensions: ${loaded.join(", ")}` });
-    }
+    return loaded;
 }
 /**
  * Find an index file in a directory extension.

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