agent-sh 0.7.0 → 0.9.0

package/dist/utils/floating-panel.js

@@ -31,6 +31,7 @@
  *   import { FloatingPanel } from "agent-sh/utils/floating-panel.js";
  */
 import { stripAnsi } from "./ansi.js";
+import { wrapLine } from "./markdown.js";
 import { LineEditor } from "./line-editor.js";
 import { TerminalBuffer } from "./terminal-buffer.js";
 import { HandlerRegistry } from "./handler-registry.js";
@@ -88,6 +89,7 @@ export class FloatingPanel {
      *   - `{prefix}:composite-row(content: string, bgLine: string|null, boxLeft: number, boxW: number, cols: number) -> string`
      *   - `{prefix}:submit(query: string) -> void`
      *   - `{prefix}:dismiss() -> void`
+     *   - `{prefix}:show() -> void`
      *   - `{prefix}:input(data: string) -> boolean`
      *   - `{prefix}:build-row(content: string, width: number) -> string`
      */
@@ -100,19 +102,26 @@ export class FloatingPanel {
     triggerSeqs;
     // ── State ───────────────────────────────────────────────────
     phase = "idle";
+    _visible = false; // whether the panel box is shown on screen
+    _passthrough = false; // hidden but still rendering TerminalBuffer
     editor = new LineEditor();
     contentLines = [];
     currentPartialLine = "";
     scrollOffset = 0;
+    userScrolled = false; // true when user manually scrolled away from bottom
     title = "";
     footer = "";
     renderTimer = null;
-    autoDismissTimer = null;
     resizeHandler = null;
     prevFrame = [];
     suppressNextRedraw = false;
+    autoDismissTimer = null;
     ptyBuffer = ""; // PTY output accumulated while overlay is open
     usedAltScreen = false; // whether we entered our own alt screen
+    wrapCache = new Map(); // line → wrapped lines (invalidated on width change)
+    wrapCacheWidth = 0;
+    passthroughTimer = null;
+    prevSerialized = "";
     constructor(bus, config, handlers) {
         this.bus = bus;
         this.externalBuffer = config.terminalBuffer;
@@ -140,28 +149,59 @@ export class FloatingPanel {
         const p = this.prefix;
         // Default content renderer: uses built-in appendText/appendLine buffer
         this.handlers.define(`${p}:render-content`, (ctx) => {
+            const raw = [...ctx.contentLines, ...(ctx.partialLine ? [ctx.partialLine] : [])];
+            // Invalidate wrap cache if width changed
+            if (ctx.width !== this.wrapCacheWidth) {
+                this.wrapCache.clear();
+                this.wrapCacheWidth = ctx.width;
+            }
+            const all = [];
+            for (const line of raw) {
+                let wrapped = this.wrapCache.get(line);
+                if (!wrapped) {
+                    wrapped = wrapLine(line, ctx.width);
+                    this.wrapCache.set(line, wrapped);
+                }
+                all.push(...wrapped);
+            }
+            // In input phase, append the prompt line at the bottom of content
             if (ctx.phase === "input") {
-                return {
-                    lines: [`\x1b[36m${this.config.promptIcon}${RESET} ${ctx.inputBuffer}`],
-                    cursor: { row: 0, col: this.config.promptIcon.length + 1 + ctx.inputCursor },
-                };
+                const promptLine = `\x1b[36m${this.config.promptIcon}${RESET} ${ctx.inputBuffer}`;
+                all.push(promptLine);
             }
-            const all = [...ctx.contentLines, ...(ctx.partialLine ? [ctx.partialLine] : [])];
-            // Auto-scroll
+            // Scroll: auto-scroll to bottom unless user manually scrolled
             let offset = ctx.scrollOffset;
-            if (all.length > ctx.height) {
-                offset = all.length - ctx.height;
+            const maxOffset = Math.max(0, all.length - ctx.height);
+            if (this.userScrolled) {
+                offset = Math.min(offset, maxOffset);
+                // Resume auto-scroll if user scrolled back to bottom
+                if (offset >= maxOffset)
+                    this.userScrolled = false;
             }
             else {
-                offset = 0;
+                offset = maxOffset;
             }
             this.scrollOffset = offset;
-            return { lines: all.slice(offset, offset + ctx.height) };
+            const visible = all.slice(offset, offset + ctx.height);
+            // Cursor position for input mode
+            if (ctx.phase === "input") {
+                const promptRow = visible.length - 1;
+                // If prompt is visible, set cursor
+                if (promptRow >= 0) {
+                    return {
+                        lines: visible,
+                        cursor: { row: promptRow, col: this.config.promptIcon.length + 1 + ctx.inputCursor },
+                    };
+                }
+            }
+            return { lines: visible };
         });
         // Default submit: no-op (extension overrides)
         this.handlers.define(`${p}:submit`, (_query) => { });
         // Default dismiss: no-op
         this.handlers.define(`${p}:dismiss`, () => { });
+        // Default show: no-op (extension overrides to rebuild content on re-show)
+        this.handlers.define(`${p}:show`, () => { });
         // Default custom input handler: don't consume
         this.handlers.define(`${p}:input`, (_data) => false);
         // Default row builder: truncate and pad
@@ -186,7 +226,8 @@ export class FloatingPanel {
         this.handlers.define(`${p}:render-border-bottom`, (ctx) => {
             const { geo, border: b } = ctx;
             if (ctx.footer) {
-                const footerPad = Math.max(0, geo.boxW - ctx.footer.length - 3);
+                const visLen = stripAnsi(ctx.footer).length;
+                const footerPad = Math.max(0, geo.boxW - visLen - 3);
                 return `${b.bl}${b.h.repeat(footerPad)}${DIM}${ctx.footer}${RESET}${b.h}${b.br}`;
             }
             return `${b.bl}${b.h.repeat(geo.boxW - 2)}${b.br}`;
@@ -243,15 +284,15 @@ export class FloatingPanel {
     }
     // ── Bus event wiring ───────────────────────────────────────
     wireEvents() {
-        // Buffer PTY output while overlay is open so we can replay it on dismiss.
-        // Alt screen restore discards anything written while it was active.
+        // Buffer PTY output while overlay is visible (alt screen discards it).
+        // Don't buffer when hidden — PTY flows to terminal directly via stdout-show.
         this.bus.on("shell:pty-data", ({ raw }) => {
-            if (this.phase !== "idle")
+            if (this._visible)
                 this.ptyBuffer += raw;
         });
         this.bus.onPipe("input:intercept", (payload) => this.handleIntercept(payload));
         this.bus.onPipe("shell:redraw-prompt", (payload) => {
-            if (this.phase !== "idle") {
+            if (this._visible || this._passthrough) {
                 return { ...payload, handled: true };
             }
             // After dismiss, suppress one redraw — restoreScreen already
@@ -283,12 +324,22 @@ export class FloatingPanel {
         return this.buffer;
     }
     // ── Public lifecycle ────────────────────────────────────────
+    /** Whether the panel has an active conversation (may be hidden). */
     get active() {
         return this.phase !== "idle";
     }
+    /** Whether the agent is currently processing a query. */
+    get processing() {
+        return this.phase === "active";
+    }
+    /** Whether the panel is currently visible on screen. */
+    get visible() {
+        return this._visible;
+    }
     get terminalBuffer() {
         return this.buffer;
     }
+    /** Open a fresh panel with a new conversation. */
     open() {
         if (this.phase !== "idle")
             return;
@@ -298,54 +349,98 @@ export class FloatingPanel {
         this.contentLines = [];
         this.currentPartialLine = "";
         this.scrollOffset = 0;
+        this.userScrolled = false;
         this.title = "";
         this.footer = "";
         this.prevFrame = [];
-        this.ptyBuffer = "";
-        this.bus.emit("shell:stdout-hold", {});
-        // If a foreground program (vim, htop) is already on alt screen,
-        // don't enter a second alt screen — it doesn't nest.  Instead,
-        // render directly on the current screen and restore from the
-        // xterm buffer on dismiss.
-        this.usedAltScreen = !(this.buffer?.altScreen);
-        if (this.usedAltScreen) {
-            process.stdout.write("\x1b[?1049h");
-        }
-        this.resizeHandler = () => { this.prevFrame = []; this.render(); };
-        process.stdout.on("resize", this.resizeHandler);
-        this.render();
+        this.enterScreen();
     }
-    dismiss() {
-        if (this.phase === "idle")
+    /** Hide the panel without destroying conversation state. */
+    hide() {
+        if (!this._visible)
             return;
         if (this.renderTimer) {
             clearTimeout(this.renderTimer);
             this.renderTimer = null;
         }
+        this._visible = false;
+        this.prevFrame = [];
+        if (this.phase === "active" && this.buffer) {
+            // Agent still working — enter passthrough mode.
+            // Keep alt screen + stdout held. Render TerminalBuffer directly
+            // so the background program's screen stays correct without
+            // handing rendering control back to ncurses.
+            this._passthrough = true;
+            this.ptyBuffer = "";
+            this.startPassthrough();
+        }
+        else {
+            // Agent idle or done — full teardown, hand back control.
+            this.teardownScreen();
+        }
+        this.handlers.call(`${this.prefix}:dismiss`);
+    }
+    /** Show the panel again after hide(), preserving conversation. */
+    show() {
+        if (this._visible || this.phase === "idle")
+            return;
+        if (this._passthrough) {
+            // Resume from passthrough — alt screen + stdout hold already active.
+            this.stopPassthrough();
+            this._passthrough = false;
+            this._visible = true;
+            this.prevFrame = [];
+            this.render();
+        }
+        else {
+            // Cold show — need full screen setup.
+            this.prevFrame = [];
+            this.enterScreen();
+        }
+        this.handlers.call(`${this.prefix}:show`);
+    }
+    /** Fully destroy the panel, resetting all state. */
+    dismiss() {
+        if (this.phase === "idle")
+            return;
         if (this.autoDismissTimer) {
             clearTimeout(this.autoDismissTimer);
             this.autoDismissTimer = null;
         }
-        if (this.resizeHandler) {
-            process.stdout.off("resize", this.resizeHandler);
-            this.resizeHandler = null;
+        if (this._passthrough) {
+            this.stopPassthrough();
+            this._passthrough = false;
+            this.teardownScreen();
+        }
+        else if (this._visible) {
+            this._visible = false;
+            if (this.renderTimer) {
+                clearTimeout(this.renderTimer);
+                this.renderTimer = null;
+            }
+            this.prevFrame = [];
+            this.teardownScreen();
         }
-        this.suppressNextRedraw = true;
         this.phase = "idle";
         this.editor.clear();
-        this.prevFrame = [];
-        this.restoreScreen();
-        // Replay any PTY output that arrived while the overlay was open.
-        // Alt screen restore discarded it, but it represents real work
-        // the agent did (commands run, output produced).
-        if (this.ptyBuffer) {
-            process.stdout.write(this.ptyBuffer);
-            this.ptyBuffer = "";
+        this.contentLines = [];
+        this.currentPartialLine = "";
+        this.scrollOffset = 0;
+        this.title = "";
+        this.footer = "";
+    }
+    /** Common screen enter logic shared by open() and show(). */
+    enterScreen() {
+        this._visible = true;
+        this.ptyBuffer = "";
+        this.bus.emit("shell:stdout-hold", {});
+        this.usedAltScreen = !(this.buffer?.altScreen);
+        if (this.usedAltScreen) {
+            process.stdout.write("\x1b[?1049h");
         }
-        // Reset any accumulated stdout-show refs, then release hold.
-        this.bus.emit("shell:stdout-hide", {});
-        this.bus.emit("shell:stdout-release", {});
-        this.handlers.call(`${this.prefix}:dismiss`);
+        this.resizeHandler = () => { this.prevFrame = []; this.render(); };
+        process.stdout.on("resize", this.resizeHandler);
+        this.render();
     }
     // ── Public content API ──────────────────────────────────────
     appendText(text) {
@@ -392,17 +487,39 @@ export class FloatingPanel {
         this.phase = "active";
     }
     setDone() {
-        this.phase = "done";
-        this.render();
+        if (this._passthrough) {
+            // Agent finished while hidden — session over, hand back control.
+            this.dismiss();
+            return;
+        }
         if (this.config.autoDismissMs > 0) {
+            // Legacy behavior: enter done state, auto-dismiss after delay
+            this.phase = "done";
+            this.render();
             this.autoDismissTimer = setTimeout(() => {
                 if (this.phase === "done")
                     this.dismiss();
             }, this.config.autoDismissMs);
         }
+        else {
+            // Auto-prompt: transition to input for follow-up conversation
+            this.phase = "input";
+            this.editor.clear();
+            this.render();
+        }
+    }
+    scrollUp(lines = 3) {
+        this.scrollOffset = Math.max(0, this.scrollOffset - lines);
+        this.userScrolled = true;
+        this.render();
+    }
+    scrollDown(lines = 3) {
+        this.scrollOffset += lines;
+        this.userScrolled = true;
+        this.render();
     }
     getInput() {
-        return this.editor.buffer;
+        return this.editor.text;
     }
     requestRender() {
         this.scheduleRender();
@@ -411,6 +528,15 @@ export class FloatingPanel {
     handleIntercept(payload) {
         const consumed = { ...payload, consumed: true };
         const { data } = payload;
+        // Toggle visibility when trigger is pressed and panel is hidden but active
+        if (this.isTrigger(data) && this.phase !== "idle" && !this._visible) {
+            this.show();
+            return consumed;
+        }
+        // When not visible, only intercept the trigger key
+        if (!this._visible && this.phase !== "idle") {
+            return payload;
+        }
         switch (this.phase) {
             case "done":
                 this.dismiss();
@@ -419,12 +545,18 @@ export class FloatingPanel {
                 this.handleInputKey(data);
                 return consumed;
             case "active":
-                if (data === "\x03")
+                if (data === "\x03") {
                     this.bus.emit("agent:cancel-request", {});
-                else if (data === "\x1b" || this.isTrigger(data))
-                    this.dismiss();
-                else
+                }
+                else if (data === "\x1b" || this.isTrigger(data)) {
+                    this.hide();
+                }
+                else if (this.handleScroll(data)) {
+                    // scroll handled
+                }
+                else {
                     this.handlers.call(`${this.prefix}:input`, data);
+                }
                 return consumed;
             default: // idle
                 if (this.isTrigger(data)) {
@@ -434,45 +566,107 @@ export class FloatingPanel {
                 return payload;
         }
     }
+    /** Handle scroll input. Returns true if consumed. */
+    handleScroll(data) {
+        // Arrow up / mouse wheel up
+        if (data === "\x1b[A" || data === "\x1bOA") {
+            this.scrollUp(1);
+            return true;
+        }
+        // Arrow down / mouse wheel down
+        if (data === "\x1b[B" || data === "\x1bOB") {
+            this.scrollDown(1);
+            return true;
+        }
+        // Page up (CSI 5~)
+        if (data === "\x1b[5~") {
+            this.scrollUp(this.computeGeometry().contentH - 1);
+            return true;
+        }
+        // Page down (CSI 6~)
+        if (data === "\x1b[6~") {
+            this.scrollDown(this.computeGeometry().contentH - 1);
+            return true;
+        }
+        // Mouse wheel: CSI M followed by button byte (64 = wheel up, 65 = wheel down)
+        if (data.length >= 6 && data.startsWith("\x1b[M")) {
+            const button = data.charCodeAt(3);
+            if (button === 96) {
+                this.scrollUp(3);
+                return true;
+            } // wheel up
+            if (button === 97) {
+                this.scrollDown(3);
+                return true;
+            } // wheel down
+        }
+        // SGR mouse: CSI < 64;x;yM (wheel up) / CSI < 65;x;yM (wheel down)
+        const sgr = data.match(/^\x1b\[<(64|65);\d+;\d+M$/);
+        if (sgr) {
+            if (sgr[1] === "64") {
+                this.scrollUp(3);
+                return true;
+            }
+            if (sgr[1] === "65") {
+                this.scrollDown(3);
+                return true;
+            }
+        }
+        return false;
+    }
     handleInputKey(data) {
         // Check full data string against trigger sequences (may be multi-byte)
         if (this.isTrigger(data)) {
-            this.dismiss();
+            this.hide();
             return;
         }
         for (let i = 0; i < data.length; i++) {
             const ch = data[i];
             if (ch === "\x1b" && data[i + 1] == null) {
-                this.dismiss();
+                this.hide();
                 return;
             }
             if (ch.charCodeAt(0) === 0x03) {
-                this.dismiss();
+                this.hide();
                 return;
             }
         }
+        // Page Up/Down and mouse wheel scroll even in input phase
+        if (this.handleScroll(data))
+            return;
         const actions = this.editor.feed(data);
         for (const action of actions) {
             switch (action.action) {
                 case "submit": {
-                    const query = this.editor.buffer.trim();
+                    const query = this.editor.text.trim();
                     if (!query) {
-                        this.dismiss();
+                        this.hide();
                         return;
                     }
+                    this.editor.pushHistory(query);
                     this.phase = "active";
                     this.editor.clear();
                     this.handlers.call(`${this.prefix}:submit`, query);
                     return;
                 }
                 case "cancel":
-                    this.dismiss();
+                    this.hide();
                     return;
+                case "arrow-up": {
+                    const hist = this.editor.historyBack();
+                    if (hist)
+                        this.render();
+                    break;
+                }
+                case "arrow-down": {
+                    const hist = this.editor.historyForward();
+                    if (hist)
+                        this.render();
+                    break;
+                }
                 case "changed":
                 case "tab":
                 case "shift+tab":
-                case "arrow-up":
-                case "arrow-down":
                 case "delete-empty":
                     this.render();
                     break;
@@ -498,8 +692,8 @@ export class FloatingPanel {
             width: geo.contentW,
             height: geo.contentH,
             phase: this.phase,
-            inputBuffer: this.editor.buffer,
-            inputCursor: this.editor.cursor,
+            inputBuffer: this.editor.displayText,
+            inputCursor: this.editor.displayCursor,
             scrollOffset: this.scrollOffset,
             contentLines: this.contentLines,
             partialLine: this.currentPartialLine,
@@ -529,7 +723,7 @@ export class FloatingPanel {
         }, 32);
     }
     render() {
-        if (this.phase === "idle")
+        if (this.phase === "idle" || !this._visible)
             return;
         const { rows: frame, cursorSeq } = this.buildFrame();
         // Differential write — only send rows that changed
@@ -555,27 +749,66 @@ export class FloatingPanel {
         this.prevFrame = frame;
     }
     // ── Screen helpers ────────────────────────────────────────
-    restoreScreen() {
+    /** Full screen teardown: exit alt screen, release stdout, force redraw. */
+    teardownScreen() {
+        if (this.resizeHandler) {
+            process.stdout.off("resize", this.resizeHandler);
+            this.resizeHandler = null;
+        }
+        this.suppressNextRedraw = true;
+        // Re-check alt screen state: the program we overlaid may have exited
+        // (e.g. agent quit vim via terminal_keys) while the panel was active.
+        const stillInAltScreen = !this.usedAltScreen && !!this.buffer?.altScreen;
+        const programExited = !this.usedAltScreen && !stillInAltScreen;
         if (this.usedAltScreen) {
-            // Leave alt screen — the terminal restores the saved main buffer.
             process.stdout.write("\x1b[?1049l");
         }
-        else {
-            // We were already on alt screen (vim, htop, etc.) so we didn't
-            // enter our own.  Restore by rewriting the screen content from
-            // the xterm buffer, which mirrors what the foreground program
-            // had rendered.
-            const raw = this.buffer?.serialize() ?? "";
+        // Replay PTY output that arrived while the overlay was active.
+        // Without this, commands run by the agent (e.g. user_shell ls)
+        // would vanish — the alt screen exit restores the saved screen
+        // from before the overlay opened, losing any shell output produced
+        // during the session.
+        if (this.ptyBuffer) {
+            process.stdout.write(this.ptyBuffer);
+        }
+        this.ptyBuffer = "";
+        this.bus.emit("shell:stdout-release", {});
+        if (stillInAltScreen || programExited) {
+            // Either a TUI app is still running and needs SIGWINCH to repaint,
+            // or the overlaid program exited (e.g. agent quit vim) and we
+            // discarded its stale buffer — SIGWINCH makes the shell redraw
+            // its prompt cleanly.
+            const cols = process.stdout.columns || 80;
             const rows = process.stdout.rows || 24;
-            const lines = raw.split("\n");
-            const out = [SYNC_START];
-            for (let i = 0; i < rows; i++) {
-                out.push(`\x1b[${i + 1};1H\x1b[2K`);
-                if (i < lines.length)
-                    out.push(lines[i]);
-            }
-            out.push(SYNC_END);
-            process.stdout.write(out.join(""));
+            this.bus.emit("shell:pty-resize", { cols, rows: rows - 1 });
+            setTimeout(() => {
+                this.bus.emit("shell:pty-resize", { cols, rows });
+            }, 50);
+        }
+    }
+    // ── Passthrough rendering ─────────────────────────────────
+    /** Start rendering TerminalBuffer directly (no overlay box). */
+    startPassthrough() {
+        this.prevSerialized = "";
+        this.renderPassthrough();
+        this.passthroughTimer = setInterval(() => this.renderPassthrough(), 50);
+    }
+    stopPassthrough() {
+        if (this.passthroughTimer) {
+            clearInterval(this.passthroughTimer);
+            this.passthroughTimer = null;
+        }
+        this.prevSerialized = "";
+    }
+    /** Render the TerminalBuffer's screen content directly (no overlay). */
+    renderPassthrough() {
+        if (!this.buffer)
+            return;
+        this.buffer.flush();
+        const serialized = this.buffer.serialize();
+        if (serialized && serialized !== this.prevSerialized) {
+            this.prevSerialized = serialized;
+            process.stdout.write(`${SYNC_START}\x1b[H${serialized}${SYNC_END}`);
         }
     }
     resolveSize(spec, available) {

package/dist/utils/handler-registry.d.ts

@@ -11,27 +11,42 @@
  *     if (lang === "latex") return renderLatex(code);
  *     return next(lang, code);  // call original
  *   });
+ *
+ * Internally, each handler is stored as a base function plus an ordered
+ * list of advisors. `call` builds the chain on invocation, so advisors
+ * can be added or removed at any time without closure entanglement.
  */
+type HandlerFn = (...args: any[]) => any;
+type Advisor = (next: HandlerFn, ...args: any[]) => any;
+/** The subset of HandlerRegistry methods available to extensions. */
+export interface HandlerFunctions {
+    define(name: string, fn: (...args: any[]) => any): void;
+    advise(name: string, advisor: (next: (...args: any[]) => any, ...args: any[]) => any): () => void;
+    call(name: string, ...args: any[]): any;
+}
 export declare class HandlerRegistry {
-    private handlers;
+    private entries;
     /**
-     * Register a named handler. If one already exists, it's replaced.
+     * Register a named handler. If one already exists, its base is replaced
+     * but existing advisors are preserved.
      */
-    define(name: string, fn: (...args: any[]) => any): void;
+    define(name: string, fn: HandlerFn): void;
     /**
-     * Wrap a named handler with advice. The wrapper receives the
-     * previous handler as `next` and all original arguments.
+     * Add an advisor to a named handler. The advisor receives `next`
+     * (the rest of the chain) and all original arguments.
      *
-     * - Call `next(...args)` to invoke the original (around/before/after)
+     * - Call `next(...args)` to invoke the rest of the chain
      * - Don't call `next` to replace entirely (override)
      * - Call `next` conditionally to wrap (around)
      *
-     * Multiple advisors chain: each wraps the previous one.
-     * If no handler exists yet, `next` is a no-op.
+     * Advisors run outermost-first (last added = outermost).
+     * Returns an unadvise function that cleanly removes this advisor.
      */
-    advise(name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any): void;
+    advise(name: string, advisor: Advisor): () => void;
     /**
-     * Call a named handler. Returns undefined if no handler is registered.
+     * Call a named handler. Builds the advisor chain on each call:
+     * outermost advisor wraps the next, down to the base handler.
+     * Returns undefined if no handler is registered.
      */
     call(name: string, ...args: any[]): any;
     /**
@@ -39,3 +54,4 @@ export declare class HandlerRegistry {
      */
     has(name: string): boolean;
 }
+export {};