agent-sh 0.5.0 → 0.7.0

package/dist/index.js

@@ -9,8 +9,11 @@ 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";
 /**
  * Capture the user's full shell environment.
  * This picks up env vars exported in .zshrc/.bashrc that the
@@ -129,8 +132,7 @@ Examples:
 
 Inside the shell:
   Type normally        Commands run in your real shell
-  > <query>           Ask the AI agent a question (execute mode)
-  ? <command>         Have the agent run a command in your shell (help mode)
+  > <query>           Ask the AI agent (it decides how to help)
   > /help             Show available slash commands
   Ctrl-C              Cancel agent response (or signal shell as usual)
 `);
@@ -210,40 +212,18 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Shell created');
     }
-    // ── Input modes ──────────────────────────────────────────────
+    // ── Input mode ───────────────────────────────────────────────
     bus.emit("input-mode:register", {
-        id: "execute",
+        id: "agent",
         trigger: ">",
-        label: "execute",
+        label: "agent",
         promptIcon: "❯",
         indicator: "●",
         onSubmit(query, b) {
-            b.emit("agent:submit", { query, modeLabel: "Execute", modeInstruction: "[mode: execute]" });
+            b.emit("agent:submit", { query });
         },
         returnToSelf: true,
     });
-    bus.emit("input-mode:register", {
-        id: "help",
-        trigger: "?",
-        label: "help",
-        promptIcon: "❯",
-        indicator: "❓",
-        onSubmit(query, b) {
-            const onToolDone = (e) => {
-                if (e.kind === "execute") {
-                    b.emit("agent:cancel-request", { silent: true });
-                }
-            };
-            const cleanup = () => {
-                b.off("agent:tool-completed", onToolDone);
-                b.off("agent:processing-done", cleanup);
-            };
-            b.on("agent:tool-completed", onToolDone);
-            b.on("agent:processing-done", cleanup);
-            b.emit("agent:submit", { query, modeLabel: "Help", modeInstruction: "[mode: help]" });
-        },
-        returnToSelf: false,
-    });
     // ── Extensions ────────────────────────────────────────────────
     if (process.env.DEBUG) {
         console.error('[agent-sh] Setting up extensions...');
@@ -254,13 +234,16 @@ 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...');
     }
     const loadExtensionsTimeoutMs = 10000;
+    let loadedExtensions = [];
     await Promise.race([
-        loadExtensions(extCtx, config.extensions),
+        loadExtensions(extCtx, config.extensions).then((names) => { loadedExtensions = names; }),
         new Promise((_, reject) => setTimeout(() => reject(new Error(`Extension loading timeout after ${loadExtensionsTimeoutMs}ms`)), loadExtensionsTimeoutMs)),
     ]).catch((err) => {
         console.error(`Warning: ${err.message}`);
@@ -268,6 +251,8 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Extensions loaded');
     }
+    // ── Discover skills ───────────────────────────────────────────
+    const skills = discoverSkills(process.cwd());
     // ── Activate agent backend ────────────────────────────────────
     // Extensions had their chance to register via agent:register-backend.
     // If none did, the built-in AgentLoop gets wired to bus events.
@@ -275,15 +260,39 @@ async function main() {
     // ── Startup banner ───────────────────────────────────────────
     const settings = getSettings();
     if (settings.startupBanner !== false) {
-        const title = core.llmClient
-            ? `${p.accent}${p.bold}agent-sh${p.reset}${p.dim} · ${core.llmClient.model}${p.reset}`
-            : `${p.accent}${p.bold}agent-sh${p.reset}`;
-        const hint = `${p.muted}Type ${p.warning}>${p.muted} to ask AI · ${p.warning}?${p.muted} to run in shell · ${p.warning}/help${p.muted} for commands${p.reset}`;
         const termW = process.stdout.columns || 80;
-        const borderLine = `${p.muted}${"─".repeat(Math.min(termW, 60))}${p.reset}`;
+        const bannerW = Math.min(termW, 60);
+        const productName = `${p.accent}${p.bold}agent-sh${p.reset}`;
+        const info = agentInfo;
+        const backendName = info?.name ?? "agent-sh";
+        const model = info?.model ?? core.llmClient?.model;
+        const provider = info?.provider;
+        const modelValue = model
+            ? provider ? `${model} [${provider}]` : model
+            : null;
+        let sections = "";
+        sections += `\n\n  ${p.muted}Backend:${p.reset} ${p.dim}${backendName}${p.reset}`;
+        if (modelValue) {
+            sections += `\n  ${p.muted}Model:${p.reset} ${p.dim}${modelValue}${p.reset}`;
+        }
+        if (loadedExtensions.length > 0) {
+            sections += `\n\n  ${p.muted}Extensions:${p.reset}`;
+            for (const name of loadedExtensions) {
+                sections += `\n    ${p.dim}${name}${p.reset}`;
+            }
+        }
+        if (skills.length > 0) {
+            sections += `\n\n  ${p.muted}Skills:${p.reset}`;
+            for (const s of skills) {
+                sections += `\n    ${p.dim}${s.name}${p.reset}`;
+            }
+        }
+        const hint = `${p.muted}Type ${p.warning}>${p.muted} to ask AI · ${p.warning}>/help${p.muted} for commands${p.reset}`;
+        const borderLine = `${p.muted}${"─".repeat(bannerW)}${p.reset}`;
         process.stdout.write("\n" + borderLine + "\n" +
-            "  " + title + "\n" +
-            "  " + hint + "\n" +
+            "  " + productName +
+            sections + "\n" +
+            "\n  " + hint + "\n" +
             borderLine + "\n\n");
     }
     // ── Terminal lifecycle ────────────────────────────────────────

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);
             }
         }
@@ -509,7 +514,8 @@ export class InputHandler {
                         }
                         this.editor.buffer = this.history[this.historyIndex];
                         this.editor.cursor = this.editor.buffer.length;
-                        this.renderModeInput();
+                        this.clearAutocompleteLines();
+                        this.writeModePromptLine();
                     }
                     break;
                 case "arrow-down":
@@ -532,7 +538,8 @@ export class InputHandler {
                             this.editor.buffer = this.savedBuffer;
                         }
                         this.editor.cursor = this.editor.buffer.length;
-                        this.renderModeInput();
+                        this.clearAutocompleteLines();
+                        this.writeModePromptLine();
                     }
                     break;
             }

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/settings.js

@@ -22,7 +22,7 @@ const DEFAULTS = {
     shellTailLines: 5,
     recallExpandMaxLines: 100,
     maxCommandOutputLines: 3,
-    readOutputMaxLines: 0,
+    readOutputMaxLines: 10,
     diffMaxLines: 20,
     skillPaths: [],
     startupBanner: true,

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) {
@@ -274,7 +299,7 @@ export class Shell {
                 const handler = (e) => {
                     clearTimeout(timeout);
                     this.bus.off("shell:command-done", handler);
-                    resolve({ output: e.output, cwd: e.cwd });
+                    resolve({ output: e.output, cwd: e.cwd, exitCode: e.exitCode });
                 };
                 this.bus.on("shell:command-done", handler);
                 this.outputParser.onCommandEntered(payload.command, this.outputParser.getCwd());
@@ -283,7 +308,7 @@ export class Shell {
             this.paused = true;
             this.echoSkip = false;
             this.bus.emit("shell:agent-exec-done", {});
-            return { ...payload, output: output.output, cwd: output.cwd, done: true };
+            return { ...payload, output: output.output, cwd: output.cwd, exitCode: output.exitCode, done: true };
         });
     }
     // ── Public API (used by index.ts) ──

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.

package/dist/utils/diff.js

@@ -39,6 +39,16 @@ export function computeDiff(oldText, newText) {
     // Build LCS table and backtrack to produce diff lines
     const a = oldText.split("\n");
     const b = newText.split("\n");
+    // Bail out if LCS table would be too large (avoids OOM / hang)
+    if (a.length * b.length > 10_000_000) {
+        return {
+            hunks: [],
+            added: b.length,
+            removed: a.length,
+            isIdentical: false,
+            isNewFile: false,
+        };
+    }
     const dp = buildLcs(a, b);
     const raw = backtrack(dp, a, b);
     let added = 0;

package/dist/utils/floating-panel.d.ts

@@ -0,0 +1,198 @@
+import { TerminalBuffer } from "./terminal-buffer.js";
+import { HandlerRegistry } from "./handler-registry.js";
+import type { EventBus } from "../event-bus.js";
+import type { BorderStyle } from "./box-frame.js";
+export interface FloatingPanelConfig {
+    /** Key sequence that toggles the panel (e.g. "\x1c" for Ctrl+\). */
+    trigger: string;
+    /** Panel width. Number = columns, string with % = percentage. Default: "80%". */
+    width?: number | string;
+    /** Max width in columns. Default: 100. */
+    maxWidth?: number;
+    /** Panel height. Number = rows, string with % = percentage. Default: "60%". */
+    height?: number | string;
+    /** Min content rows inside the panel. Default: 6. */
+    minHeight?: number;
+    /** Border style. Default: "rounded". */
+    borderStyle?: BorderStyle;
+    /**
+     * Show dimmed terminal content behind the panel. Default: true.
+     * Requires @xterm/headless — falls back to blank background if unavailable.
+     */
+    dimBackground?: boolean;
+    /** Auto-dismiss delay in ms when done (0 = disabled). Default: 0. */
+    autoDismissMs?: number;
+    /** Icon shown before the input cursor. Default: "\u276f". */
+    promptIcon?: string;
+    /**
+     * Pre-existing TerminalBuffer to reuse. If provided, the panel will
+     * not create its own headless terminal. Useful when sharing a buffer
+     * with other features (e.g. context injection, terminal_read tool).
+     */
+    terminalBuffer?: TerminalBuffer;
+    /**
+     * Handler namespace prefix. Default: "panel".
+     * All handlers are registered as `{prefix}:render-content`,
+     * `{prefix}:submit`, etc. Use different prefixes for multiple panels.
+     */
+    handlerPrefix?: string;
+}
+/**
+ * Context passed to the render-content handler.
+ */
+export interface RenderContext {
+    /** Available width for content (inside box, excluding borders and padding). */
+    width: number;
+    /** Available height for content (rows inside box). */
+    height: number;
+    /** Current panel phase. */
+    phase: Phase;
+    /** Current input buffer text (during input phase). */
+    inputBuffer: string;
+    /** Current input cursor position (during input phase). */
+    inputCursor: number;
+    /** Current scroll offset. */
+    scrollOffset: number;
+    /** Built-in content lines (from appendText/appendLine). */
+    contentLines: readonly string[];
+    /** Current partial line being streamed. */
+    partialLine: string;
+}
+/**
+ * Result from render-content handler.
+ */
+export interface RenderResult {
+    lines: string[];
+    /** Optional cursor position within the content area. */
+    cursor?: {
+        row: number;
+        col: number;
+    };
+}
+/**
+ * Box geometry computed from config + terminal size.
+ */
+export interface BoxGeometry {
+    /** Terminal columns. */
+    cols: number;
+    /** Terminal rows. */
+    rows: number;
+    /** Box width in columns (including borders). */
+    boxW: number;
+    /** Box height in rows (including borders). */
+    boxH: number;
+    /** Box top offset (0-indexed row). */
+    boxTop: number;
+    /** Box left offset (0-indexed column). */
+    boxLeft: number;
+    /** Usable content width inside box. */
+    contentW: number;
+    /** Usable content height inside box. */
+    contentH: number;
+}
+/**
+ * Context passed to the render-frame handler.
+ */
+export interface FrameContext {
+    /** Box geometry. */
+    geo: BoxGeometry;
+    /** Content render result (from render-content handler). */
+    content: RenderResult;
+    /** Background lines from the terminal buffer (null if no dimming). */
+    bgLines: string[] | null;
+    /** Current panel phase. */
+    phase: Phase;
+    /** Current title text. */
+    title: string;
+    /** Current footer text. */
+    footer: string;
+    /** Border characters for the configured border style. */
+    border: {
+        tl: string;
+        tr: string;
+        bl: string;
+        br: string;
+        h: string;
+        v: string;
+    };
+}
+/**
+ * Result from render-frame handler.
+ */
+export interface FrameResult {
+    /** One string per terminal row. */
+    rows: string[];
+    /** ANSI sequence to position the cursor (empty string if no cursor). */
+    cursorSeq: string;
+}
+export type Phase = "idle" | "input" | "active" | "done";
+export declare class FloatingPanel {
+    private readonly config;
+    private readonly bus;
+    private readonly border;
+    private readonly externalBuffer;
+    private readonly prefix;
+    /**
+     * Handler registry for this panel. Extensions use `handlers.advise()`
+     * to customize rendering and behavior.
+     *
+     * Registered handlers:
+     *   - `{prefix}:render-content(ctx: RenderContext) -> RenderResult`
+     *   - `{prefix}:render-frame(ctx: FrameContext) -> FrameResult`
+     *   - `{prefix}:render-border-top(ctx: FrameContext) -> string`
+     *   - `{prefix}:render-border-bottom(ctx: FrameContext) -> string`
+     *   - `{prefix}:composite-row(content: string, bgLine: string|null, boxLeft: number, boxW: number, cols: number) -> string`
+     *   - `{prefix}:submit(query: string) -> void`
+     *   - `{prefix}:dismiss() -> void`
+     *   - `{prefix}:input(data: string) -> boolean`
+     *   - `{prefix}:build-row(content: string, width: number) -> string`
+     */
+    readonly handlers: HandlerRegistry;
+    private buffer;
+    private bufferInitialized;
+    /** All byte sequences that should be recognized as the trigger key. */
+    private readonly triggerSeqs;
+    private phase;
+    private editor;
+    private contentLines;
+    private currentPartialLine;
+    private scrollOffset;
+    private title;
+    private footer;
+    private renderTimer;
+    private autoDismissTimer;
+    private resizeHandler;
+    private prevFrame;
+    private suppressNextRedraw;
+    private ptyBuffer;
+    private usedAltScreen;
+    constructor(bus: EventBus, config: FloatingPanelConfig, handlers?: HandlerRegistry);
+    private registerDefaultHandlers;
+    private wireEvents;
+    /** Check whether data matches any encoding of the trigger key. */
+    private isTrigger;
+    private ensureBuffer;
+    get active(): boolean;
+    get terminalBuffer(): TerminalBuffer | null;
+    open(): void;
+    dismiss(): void;
+    appendText(text: string): void;
+    appendLine(line: string): void;
+    updateLastLine(fn: (line: string) => string): void;
+    clearContent(): void;
+    setTitle(title: string): void;
+    setFooter(footer: string): void;
+    setActive(): void;
+    setDone(): void;
+    getInput(): string;
+    requestRender(): void;
+    private handleIntercept;
+    private handleInputKey;
+    /** Compute box geometry from config + current terminal size. */
+    computeGeometry(): BoxGeometry;
+    private buildFrame;
+    private scheduleRender;
+    private render;
+    private restoreScreen;
+    private resolveSize;
+}