agent-sh 0.12.25 → 0.12.26

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import * as path from "node:path";
-import { activateShell } from "./shell/index.js";
+import { activateShell, registerShellHandlers } from "./shell/index.js";
 import { createCore } from "./core.js";
 import { palette as p } from "./utils/palette.js";
 import { loadBuiltinExtensions } from "./extensions/index.js";
@@ -237,6 +237,8 @@ async function main() {
         process.exit(0);
     };
     const extCtx = core.extensionContext({ quit: cleanup });
+    // Before loadExtensions: extensions look up shell handlers at activation.
+    registerShellHandlers(extCtx);
     // Load before spawning the shell so PS1 lands below the banner.
     await loadBuiltinExtensions(extCtx, getSettings().disabledBuiltins);
     const loadExtensionsTimeoutMs = 10000;

package/dist/shell/index.d.ts

@@ -27,6 +27,11 @@ export interface ShellHandle {
     /** Forward terminal size changes to the PTY. */
     resize(cols: number, rows: number): void;
 }
+/**
+ * Register shell-owned handlers extensions can `ctx.call`. Must run before
+ * `loadExtensions`; the handlers only need the bus, not the PTY.
+ */
+export declare function registerShellHandlers(ctx: ExtensionContext): void;
 /**
  * Construct the Shell, wire resize forwarding, and register cleanup with the
  * provided ExtensionContext. Returns a handle the caller (typically

package/dist/shell/index.js

@@ -1,6 +1,19 @@
 import { Shell } from "./shell.js";
 import { StdoutSurface } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.js";
+/**
+ * Register shell-owned handlers extensions can `ctx.call`. Must run before
+ * `loadExtensions`; the handlers only need the bus, not the PTY.
+ */
+export function registerShellHandlers(ctx) {
+    let terminalBufferSingleton;
+    ctx.define("terminal-buffer", () => {
+        if (terminalBufferSingleton !== undefined)
+            return terminalBufferSingleton;
+        terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
+        return terminalBufferSingleton;
+    });
+}
 /**
  * Construct the Shell, wire resize forwarding, and register cleanup with the
  * provided ExtensionContext. Returns a handle the caller (typically
@@ -13,14 +26,6 @@ export function activateShell(ctx, opts) {
     ctx.compositor.setDefault("agent", stdoutSurface);
     ctx.compositor.setDefault("query", stdoutSurface);
     ctx.compositor.setDefault("status", stdoutSurface);
-    // Lazy because @xterm/headless is optional; null when not installed.
-    let terminalBufferSingleton;
-    ctx.define("terminal-buffer", () => {
-        if (terminalBufferSingleton !== undefined)
-            return terminalBufferSingleton;
-        terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
-        return terminalBufferSingleton;
-    });
     const shell = new Shell({
         bus: ctx.bus,
         handlers: { define: ctx.define, call: ctx.call },

package/dist/shell/input-handler.js

@@ -229,9 +229,15 @@ export class InputHandler {
         return false;
     }
     renderModeInput() {
-        this.view.clearAutocomplete();
-        this.drawPrompt();
-        this.updateAutocomplete();
+        this.view.beginFrame();
+        try {
+            this.view.clearAutocomplete();
+            this.drawPrompt();
+            this.updateAutocomplete();
+        }
+        finally {
+            this.view.endFrame();
+        }
     }
     updateAutocomplete() {
         const buf = this.editor.text;
@@ -278,13 +284,19 @@ export class InputHandler {
         else {
             this.editor.setText(selected.name);
         }
-        this.view.clearAutocomplete();
-        this.autocompleteActive = false;
-        this.autocompleteItems = [];
-        this.autocompleteIndex = 0;
-        this.drawPrompt();
-        if (isFileAc)
-            this.updateAutocomplete();
+        this.view.beginFrame();
+        try {
+            this.view.clearAutocomplete();
+            this.autocompleteActive = false;
+            this.autocompleteItems = [];
+            this.autocompleteIndex = 0;
+            this.drawPrompt();
+            if (isFileAc)
+                this.updateAutocomplete();
+        }
+        finally {
+            this.view.endFrame();
+        }
     }
     dismissAutocomplete() {
         this.view.clearAutocomplete();
@@ -314,11 +326,17 @@ export class InputHandler {
                 case "changed": {
                     const switchMode = this.modes.get(this.editor.text);
                     if (this.editor.text.length === 1 && switchMode && switchMode !== this.activeMode) {
-                        this.dismissAutocomplete();
-                        this.view.clearPromptArea();
-                        this.activeMode = switchMode;
-                        this.editor.clear();
-                        this.drawPrompt(false);
+                        this.view.beginFrame();
+                        try {
+                            this.dismissAutocomplete();
+                            this.view.clearPromptArea();
+                            this.activeMode = switchMode;
+                            this.editor.clear();
+                            this.drawPrompt(false);
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                         break;
                     }
                     this.historyIndex = -1;
@@ -371,8 +389,14 @@ export class InputHandler {
                 }
                 case "cancel":
                     if (this.autocompleteActive) {
-                        this.dismissAutocomplete();
-                        this.drawPrompt();
+                        this.view.beginFrame();
+                        try {
+                            this.dismissAutocomplete();
+                            this.drawPrompt();
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     else {
                         this.exitMode();
@@ -393,9 +417,15 @@ export class InputHandler {
                             this.autocompleteIndex === 0
                                 ? this.autocompleteItems.length - 1
                                 : this.autocompleteIndex - 1;
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
-                        this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                            this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     else if (this.history.length > 0) {
                         if (this.historyIndex === -1) {
@@ -406,8 +436,14 @@ export class InputHandler {
                             this.historyIndex--;
                         }
                         this.editor.setText(this.history[this.historyIndex]);
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     break;
                 case "arrow-down":
@@ -416,9 +452,15 @@ export class InputHandler {
                             this.autocompleteIndex === this.autocompleteItems.length - 1
                                 ? 0
                                 : this.autocompleteIndex + 1;
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
-                        this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                            this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     else if (this.historyIndex !== -1) {
                         if (this.historyIndex < this.history.length - 1) {
@@ -429,8 +471,14 @@ export class InputHandler {
                             this.historyIndex = -1;
                             this.editor.setText(this.savedBuffer);
                         }
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     break;
             }

package/dist/shell/tui-input-view.d.ts

@@ -26,7 +26,12 @@ export declare class TuiInputView {
     private cursorTermCol;
     private autocompleteLines;
     private readonly surface;
+    private frameBuf;
     constructor(surface?: RenderSurface);
+    beginFrame(): void;
+    endFrame(): void;
+    private emit;
+    private autoFrame;
     resetCursor(): void;
     enableModeKeys(): void;
     disableModeKeys(): void;

package/dist/shell/tui-input-view.js

@@ -11,130 +11,171 @@ export class TuiInputView {
     cursorTermCol = 1;
     autocompleteLines = 0;
     surface;
+    frameBuf = null;
     constructor(surface) {
         this.surface = surface ?? new StdoutSurface();
     }
+    // Frame buffering: coalesces all emit() calls until endFrame() into one
+    // surface.write, bracketed by cursor hide/show so intermediate redraw
+    // states never flicker through.
+    beginFrame() {
+        if (this.frameBuf === null)
+            this.frameBuf = "\x1b[?25l";
+    }
+    endFrame() {
+        if (this.frameBuf === null)
+            return;
+        const out = this.frameBuf + "\x1b[?25h";
+        this.frameBuf = null;
+        this.surface.write(out);
+    }
+    emit(s) {
+        if (this.frameBuf !== null)
+            this.frameBuf += s;
+        else
+            this.surface.write(s);
+    }
+    autoFrame(fn) {
+        const owned = this.frameBuf === null;
+        if (owned)
+            this.beginFrame();
+        try {
+            return fn();
+        }
+        finally {
+            if (owned)
+                this.endFrame();
+        }
+    }
     resetCursor() {
         this.cursorRowsBelow = 0;
         this.cursorTermCol = 1;
     }
     enableModeKeys() {
         // Kitty progressive enhancement + bracket paste (Shift+Enter → \x1b[13;2u).
-        this.surface.write("\x1b[>1u\x1b[?2004h");
+        this.emit("\x1b[>1u\x1b[?2004h");
     }
     disableModeKeys() {
-        this.surface.write("\x1b[<u\x1b[?2004l");
+        this.emit("\x1b[<u\x1b[?2004l");
     }
     clearPromptArea() {
-        if (this.cursorRowsBelow > 0) {
-            this.surface.write(`\x1b[${this.cursorRowsBelow}A`);
-        }
-        this.surface.write("\r\x1b[J");
-        this.cursorRowsBelow = 0;
+        this.autoFrame(() => {
+            if (this.cursorRowsBelow > 0) {
+                this.emit(`\x1b[${this.cursorRowsBelow}A`);
+            }
+            this.emit("\r\x1b[J");
+            this.cursorRowsBelow = 0;
+        });
     }
     drawPrompt(vm) {
-        const termW = this.surface.columns;
-        if (this.cursorRowsBelow > 0) {
-            this.surface.write(`\x1b[${this.cursorRowsBelow}A`);
-        }
-        this.surface.write("\r\x1b[J");
-        const infoPrefix = vm.agentInfo.info
-            ? `${vm.agentInfo.info} ${p.success}${vm.indicator}${p.reset} `
-            : `${p.success}${vm.indicator}${p.reset} `;
-        const promptPrefix = infoPrefix + p.warning + p.bold + vm.promptIcon + " " + p.reset;
-        const promptVisLen = visibleLen(infoPrefix) + visibleLen(vm.promptIcon) + 1;
-        const display = vm.showBuffer ? vm.displayText : "";
-        const dCursor = vm.showBuffer ? vm.displayCursor : 0;
-        if (!vm.showBuffer) {
-            this.surface.write(promptPrefix);
-            const N = promptVisLen;
-            this.cursorRowsBelow = N > 0 ? Math.ceil(N / termW) - 1 : 0;
-            this.cursorTermCol = N === 0 ? 1 : (N % termW === 0 ? termW : (N % termW) + 1);
-        }
-        else if (!display.includes("\n")) {
-            // DECSC/DECRC bracket the after-cursor text so the cursor lands mid-line.
-            const before = display.slice(0, dCursor);
-            const after = display.slice(dCursor);
-            this.surface.write(promptPrefix + p.accent + before + p.reset +
-                "\x1b7" +
-                p.accent + after + p.reset +
-                "\x1b8");
-            const cursorVisCol = promptVisLen + visibleLen(before);
-            this.cursorRowsBelow = cursorVisCol > 0 ? Math.ceil(cursorVisCol / termW) - 1 : 0;
-            this.cursorTermCol = cursorVisCol === 0 ? 1 : (cursorVisCol % termW === 0 ? termW : (cursorVisCol % termW) + 1);
-        }
-        else {
-            const lines = display.split("\n");
-            const indent = " ".repeat(promptVisLen);
-            let charsRemaining = dCursor;
-            let cursorLine = 0;
-            for (let li = 0; li < lines.length; li++) {
-                if (charsRemaining <= lines[li].length) {
-                    cursorLine = li;
-                    break;
-                }
-                charsRemaining -= lines[li].length + 1;
-                cursorLine = li + 1;
+        this.autoFrame(() => {
+            const termW = this.surface.columns;
+            if (this.cursorRowsBelow > 0) {
+                this.emit(`\x1b[${this.cursorRowsBelow}A`);
             }
-            let output = "";
-            let cursorRowFromTop = 0;
-            let rowsSoFar = 0;
-            for (let li = 0; li < lines.length; li++) {
-                const prefix = li === 0 ? promptPrefix : indent;
-                const lineText = lines[li];
-                const lineVisLen = promptVisLen + visibleLen(lineText);
-                const lineTermRows = lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
-                if (li === cursorLine) {
-                    const before = lineText.slice(0, charsRemaining);
-                    const after = lineText.slice(charsRemaining);
-                    output += prefix + p.accent + before + p.reset;
-                    output += "\x1b7";
-                    output += p.accent + after + p.reset;
-                    const beforeVisCol = promptVisLen + visibleLen(before);
-                    cursorRowFromTop = rowsSoFar + (beforeVisCol > 0 ? Math.ceil(beforeVisCol / termW) - 1 : 0);
-                    this.cursorTermCol = beforeVisCol === 0 ? 1 : (beforeVisCol % termW === 0 ? termW : (beforeVisCol % termW) + 1);
+            this.emit("\r\x1b[J");
+            const infoPrefix = vm.agentInfo.info
+                ? `${vm.agentInfo.info} ${p.success}${vm.indicator}${p.reset} `
+                : `${p.success}${vm.indicator}${p.reset} `;
+            const promptPrefix = infoPrefix + p.warning + p.bold + vm.promptIcon + " " + p.reset;
+            const promptVisLen = visibleLen(infoPrefix) + visibleLen(vm.promptIcon) + 1;
+            const display = vm.showBuffer ? vm.displayText : "";
+            const dCursor = vm.showBuffer ? vm.displayCursor : 0;
+            if (!vm.showBuffer) {
+                this.emit(promptPrefix);
+                const N = promptVisLen;
+                this.cursorRowsBelow = N > 0 ? Math.ceil(N / termW) - 1 : 0;
+                this.cursorTermCol = N === 0 ? 1 : (N % termW === 0 ? termW : (N % termW) + 1);
+            }
+            else if (!display.includes("\n")) {
+                // DECSC/DECRC bracket the after-cursor text so the cursor lands mid-line.
+                const before = display.slice(0, dCursor);
+                const after = display.slice(dCursor);
+                this.emit(promptPrefix + p.accent + before + p.reset +
+                    "\x1b7" +
+                    p.accent + after + p.reset +
+                    "\x1b8");
+                const cursorVisCol = promptVisLen + visibleLen(before);
+                this.cursorRowsBelow = cursorVisCol > 0 ? Math.ceil(cursorVisCol / termW) - 1 : 0;
+                this.cursorTermCol = cursorVisCol === 0 ? 1 : (cursorVisCol % termW === 0 ? termW : (cursorVisCol % termW) + 1);
+            }
+            else {
+                const lines = display.split("\n");
+                const indent = " ".repeat(promptVisLen);
+                let charsRemaining = dCursor;
+                let cursorLine = 0;
+                for (let li = 0; li < lines.length; li++) {
+                    if (charsRemaining <= lines[li].length) {
+                        cursorLine = li;
+                        break;
+                    }
+                    charsRemaining -= lines[li].length + 1;
+                    cursorLine = li + 1;
                 }
-                else {
-                    output += prefix + p.accent + lineText + p.reset;
+                let output = "";
+                let cursorRowFromTop = 0;
+                let rowsSoFar = 0;
+                for (let li = 0; li < lines.length; li++) {
+                    const prefix = li === 0 ? promptPrefix : indent;
+                    const lineText = lines[li];
+                    const lineVisLen = promptVisLen + visibleLen(lineText);
+                    const lineTermRows = lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
+                    if (li === cursorLine) {
+                        const before = lineText.slice(0, charsRemaining);
+                        const after = lineText.slice(charsRemaining);
+                        output += prefix + p.accent + before + p.reset;
+                        output += "\x1b7";
+                        output += p.accent + after + p.reset;
+                        const beforeVisCol = promptVisLen + visibleLen(before);
+                        cursorRowFromTop = rowsSoFar + (beforeVisCol > 0 ? Math.ceil(beforeVisCol / termW) - 1 : 0);
+                        this.cursorTermCol = beforeVisCol === 0 ? 1 : (beforeVisCol % termW === 0 ? termW : (beforeVisCol % termW) + 1);
+                    }
+                    else {
+                        output += prefix + p.accent + lineText + p.reset;
+                    }
+                    if (li < lines.length - 1)
+                        output += "\n";
+                    rowsSoFar += lineTermRows;
                 }
-                if (li < lines.length - 1)
-                    output += "\n";
-                rowsSoFar += lineTermRows;
+                this.emit(output + "\x1b8");
+                this.cursorRowsBelow = cursorRowFromTop;
             }
-            this.surface.write(output + "\x1b8");
-            this.cursorRowsBelow = cursorRowFromTop;
-        }
+        });
     }
     drawAutocomplete(vm) {
         if (vm.items.length === 0)
             return;
-        const lines = [];
-        for (let i = 0; i < vm.items.length; i++) {
-            const item = vm.items[i];
-            const selected = i === vm.selected;
-            if (selected) {
-                lines.push(`  \x1b[7m ${p.accent}${item.name.padEnd(12)}${p.reset}\x1b[7m ${item.description} ${p.reset}`);
+        this.autoFrame(() => {
+            const lines = [];
+            for (let i = 0; i < vm.items.length; i++) {
+                const item = vm.items[i];
+                const selected = i === vm.selected;
+                if (selected) {
+                    lines.push(`  \x1b[7m ${p.accent}${item.name.padEnd(12)}${p.reset}\x1b[7m ${item.description} ${p.reset}`);
+                }
+                else {
+                    lines.push(`   ${p.muted}${item.name.padEnd(12)} ${item.description}${p.reset}`);
+                }
             }
-            else {
-                lines.push(`   ${p.muted}${item.name.padEnd(12)} ${item.description}${p.reset}`);
+            this.emit("\n" + lines.join("\n"));
+            this.autocompleteLines = lines.length;
+            if (this.autocompleteLines > 0) {
+                this.emit(`\x1b[${this.autocompleteLines}A`);
             }
-        }
-        this.surface.write("\n" + lines.join("\n"));
-        this.autocompleteLines = lines.length;
-        if (this.autocompleteLines > 0) {
-            this.surface.write(`\x1b[${this.autocompleteLines}A`);
-        }
-        // Absolute column set — preceding \n may have scrolled, invalidating DECSC.
-        this.surface.write(`\x1b[${this.cursorTermCol}G`);
+            // Absolute column set — preceding \n may have scrolled, invalidating DECSC.
+            this.emit(`\x1b[${this.cursorTermCol}G`);
+        });
     }
     clearAutocomplete() {
         if (this.autocompleteLines <= 0)
             return;
-        // CSI B (cursor down, bounded) so we don't scroll on the last row.
-        for (let i = 0; i < this.autocompleteLines; i++) {
-            this.surface.write("\x1b[B\x1b[2K");
-        }
-        this.surface.write(`\x1b[${this.autocompleteLines}A\x1b[${this.cursorTermCol}G`);
-        this.autocompleteLines = 0;
+        this.autoFrame(() => {
+            // CSI B (cursor down, bounded) so we don't scroll on the last row.
+            for (let i = 0; i < this.autocompleteLines; i++) {
+                this.emit("\x1b[B\x1b[2K");
+            }
+            this.emit(`\x1b[${this.autocompleteLines}A\x1b[${this.cursorTermCol}G`);
+            this.autocompleteLines = 0;
+        });
     }
 }

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

@@ -1,6 +1,4 @@
 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;
@@ -31,15 +29,14 @@ export declare class TerminalBuffer {
     /** Flush pending drip-feed data (set by createWired). */
     _flushPending: (() => void) | null;
     private constructor();
+    static create(config?: TerminalBufferConfig): TerminalBuffer;
     /**
-     * Create a new TerminalBuffer. Returns null if xterm is not installed.
+     * Create a TerminalBuffer wired to a bus's `shell:pty-data` event.
+     * Drip-feeds writes asynchronously: synchronous `term.write()` in the
+     * pty-data handler changes PTY read coalescing enough to introduce
+     * visual artifacts.
      */
-    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;
+    static createWired(bus: EventBus, config?: TerminalBufferConfig): TerminalBuffer;
     /** Flush any pending drip-feed data into the virtual terminal. */
     flush(): void;
     /** Write raw data into the virtual terminal. */

package/dist/utils/terminal-buffer.js

@@ -9,38 +9,19 @@
  *   - 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
  */
+// xterm is loaded lazily on first TerminalBuffer.create(). Subcommands
+// (init/install/list) and non-shell frontends (web bridges) import this
+// file transitively but never instantiate a buffer; they shouldn't pay
+// the xterm parse cost at startup.
 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();
-}
+// Node's require cache memoizes the first hit; subsequent calls are
+// just a hashmap lookup, so this stays lazy without our own caching.
+const loadXterm = () => ({
+    Terminal: require("@xterm/headless").Terminal,
+    SerializeAddon: require("@xterm/addon-serialize").SerializeAddon,
+});
 /**
  * Format a screen snapshot as an XML context block for agent injection.
  * Trims, caps to `maxLines` (from the bottom), and wraps in `<terminal_buffer>`.
@@ -71,47 +52,35 @@ export class TerminalBuffer {
         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 { Terminal, SerializeAddon } = loadXterm();
         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();
+        const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback });
+        const serialize = new SerializeAddon();
         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.
+     * Create a TerminalBuffer wired to a bus's `shell:pty-data` event.
+     * Drip-feeds writes asynchronously: synchronous `term.write()` in the
+     * pty-data handler changes PTY read coalescing enough to introduce
+     * visual artifacts.
      */
     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);
-        tb._flushPending = () => {
+        const drain = () => {
             if (pending) {
                 const d = pending;
                 pending = "";
                 tb.write(d);
             }
         };
+        bus.on("shell:pty-data", ({ raw }) => { pending += raw; });
+        setInterval(drain, 50);
+        tb._flushPending = drain;
         process.stdout.on("resize", () => {
             tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
         });
@@ -171,7 +140,6 @@ export class TerminalBuffer {
             const line = buf.getLine(y);
             lines.push(line ? line.translateToString(true) : "");
         }
-        // Trim trailing empty lines
         while (lines.length > 0 && lines[lines.length - 1] === "") {
             lines.pop();
         }

package/examples/extensions/opencode-bridge/index.ts

@@ -5,9 +5,20 @@
  *
  * Requires opencode authenticated locally (`opencode auth login`).
  */
-import { createOpencode, type OpencodeClient, type Event, type Part, type ToolPart } from "@opencode-ai/sdk";
+import {
+  createOpencode,
+  type OpencodeClient,
+  type Event,
+  type Part,
+  type ToolPart,
+  type QuestionRequest,
+  type QuestionInfo,
+} from "@opencode-ai/sdk/v2";
 import type { ExtensionContext } from "agent-sh/types";
+import type { InteractiveSession } from "agent-sh/agent/types";
 import { computeDiff, type DiffResult } from "agent-sh/utils/diff";
+import { createToolUI } from "agent-sh/utils/tool-interactive";
+import { palette as p } from "agent-sh/utils/palette";
 
 function parseUnifiedDiff(patch: string): DiffResult | null {
   if (!patch) return null;
@@ -49,7 +60,7 @@ function parseUnifiedDiff(patch: string): DiffResult | null {
 }
 
 export default function activate(ctx: ExtensionContext): void {
-  const { bus, call } = ctx;
+  const { bus, call, compositor } = ctx;
 
   const cwd = (): string => {
     const v = call("cwd");
@@ -81,6 +92,7 @@ export default function activate(ctx: ExtensionContext): void {
   // prompt() and SSE deltas race; resolve the turn on session.idle.
   let pendingTurnEnd: (() => void) | null = null;
   let turnIdleSeen = false;
+  let turnError: string | null = null;
 
   const listeners: Array<{ event: string; fn: Function }> = [];
 
@@ -112,6 +124,9 @@ export default function activate(ctx: ExtensionContext): void {
 
   function handleToolPart(part: ToolPart): void {
     const { callID, tool: toolName, state } = part;
+    // Question tool is presented via an interactive picker (see question.asked) —
+    // skip the timeline entry to avoid a duplicate "running" bar.
+    if (toolName === "question") return;
     const kind = toolKind(toolName);
 
     if (state.status !== "pending" && !announcedTools.has(callID)) {
@@ -177,6 +192,7 @@ export default function activate(ctx: ExtensionContext): void {
     turnText += text;
   }
 
+
   function handleEvent(event: Event): void {
     if (!sessionId) return;
     const evType = (event as any).type as string;
@@ -209,23 +225,86 @@ export default function activate(ctx: ExtensionContext): void {
       }
       case "session.error": {
         const err = props.error as { message?: string } | undefined;
-        bus.emit("agent:error", { message: err?.message ?? "opencode session error" });
+        const message = err?.message ?? "opencode session error";
+        // session.prompt() does not always reject on session error;
+        // drive turn-end ourselves and abort to unstick a hanging prompt().
+        turnError = message;
+        bus.emit("agent:error", { message });
+        turnIdleSeen = true;
+        pendingTurnEnd?.();
+        if (runtime && sessionId) {
+          runtime.client.session
+            .abort({ sessionID: sessionId, directory: sessionDirectory ?? undefined })
+            .catch(() => { /* abort is best-effort */ });
+        }
+        break;
+      }
+      case "question.asked": {
+        const req = props as QuestionRequest;
+        if (!runtime) break;
+        const ui = createToolUI(bus, compositor.surface("agent"));
+        ui.custom(createQuestionSession(req.questions)).then(async (result: QuestionResult) => {
+          if (!runtime) return;
+          // Record the question + answer as a synthetic tool entry so the
+          // timeline shows what was asked and what the user picked.
+          const callID = `question-${req.id}`;
+          const detail = req.questions.length === 1
+            ? req.questions[0]!.question
+            : req.questions.map((q, i) => `${q.header || `Q${i + 1}`}: ${q.question}`).join("; ");
+          bus.emit("agent:tool-started", {
+            title: "question",
+            toolCallId: callID,
+            kind: "execute",
+            displayDetail: detail,
+          });
+          if (result.cancelled) {
+            bus.emitTransform("agent:tool-completed", {
+              toolCallId: callID,
+              exitCode: 1,
+              rawOutput: "cancelled",
+              kind: "execute",
+              resultDisplay: { summary: "cancelled" },
+            });
+            runtime.client.question
+              .reject({ requestID: req.id, directory: sessionDirectory ?? undefined })
+              .catch(() => { /* best-effort */ });
+            return;
+          }
+          const summary = result.answers.length === 1
+            ? result.answers[0]!.join(", ")
+            : result.answers
+                .map((ans, i) => `${req.questions[i]!.header || `Q${i + 1}`}: ${ans.join(", ")}`)
+                .join("; ");
+          bus.emitTransform("agent:tool-completed", {
+            toolCallId: callID,
+            exitCode: 0,
+            rawOutput: summary,
+            kind: "execute",
+            resultDisplay: { summary },
+          });
+          try {
+            await runtime.client.question.reply({
+              requestID: req.id,
+              answers: result.answers,
+              directory: sessionDirectory ?? undefined,
+            });
+          } catch (err) {
+            bus.emit("agent:error", {
+              message: err instanceof Error ? err.message : String(err),
+            });
+          }
+        });
         break;
       }
       // Without a reply the gated tool hangs forever. The bridge has no
       // interactive approval UI, so auto-approve — mirrors claude-code-
       // bridge's permissionMode: "acceptEdits". Set permission.edit:
       // "allow" in opencode.json to skip the round-trip entirely.
-      case "permission.asked":
-      case "permission.updated": {
-        const permissionID = props.id as string | undefined;
-        if (!permissionID || !runtime || !sessionId) break;
-        runtime.client
-          .postSessionIdPermissionsPermissionId({
-            path: { id: sessionId, permissionID },
-            query: sessionDirectory ? { directory: sessionDirectory } : undefined,
-            body: { response: "once" },
-          })
+      case "permission.asked": {
+        const requestID = props.id as string | undefined;
+        if (!requestID || !runtime) break;
+        runtime.client.permission
+          .reply({ requestID, reply: "once", directory: sessionDirectory ?? undefined })
           .catch(() => { /* approval is best-effort */ });
         break;
       }
@@ -235,7 +314,7 @@ export default function activate(ctx: ExtensionContext): void {
   async function consumeEvents(client: OpencodeClient, signal: AbortSignal): Promise<void> {
     while (!signal.aborted) {
       try {
-        const result = await client.event.subscribe({ signal });
+        const result = await client.event.subscribe({}, { signal });
         for await (const ev of result.stream) {
           if (signal.aborted) return;
           handleEvent(ev as Event);
@@ -261,6 +340,7 @@ export default function activate(ctx: ExtensionContext): void {
       bus.emit("agent:processing-start", {});
       turnText = "";
       turnIdleSeen = false;
+      turnError = null;
       // Set the idle waiter BEFORE prompt() so a fast session.idle can't
       // race in before we're listening.
       const idlePromise = new Promise<void>((resolve) => {
@@ -272,11 +352,9 @@ export default function activate(ctx: ExtensionContext): void {
 
       try {
         const res = await runtime.client.session.prompt({
-          path: { id: sessionId },
-          query: sessionDirectory ? { directory: sessionDirectory } : undefined,
-          body: {
-            parts: [{ type: "text", text: finalPrompt }],
-          },
+          sessionID: sessionId,
+          directory: sessionDirectory ?? undefined,
+          parts: [{ type: "text", text: finalPrompt }],
         });
         if (!turnIdleSeen) {
           await Promise.race([
@@ -284,23 +362,29 @@ export default function activate(ctx: ExtensionContext): void {
             new Promise<void>((r) => setTimeout(r, 60_000)),
           ]);
         }
-        // Fallback if SSE never delivered text (network blip, missed
-        // partKinds entry); the prompt response always carries the final.
-        if (!turnText && res.data?.parts) {
-          for (const p of res.data.parts) {
-            if (p.type === "text" && p.text) turnText += p.text;
-          }
-          if (turnText) {
-            bus.emitTransform("agent:response-chunk", {
-              blocks: [{ type: "text" as const, text: turnText }],
-            });
+        if (turnError) {
+          bus.emitTransform("agent:response-done", { response: "" });
+        } else {
+          // Fallback if SSE never delivered text (network blip, missed
+          // partKinds entry); the prompt response always carries the final.
+          if (!turnText && res.data?.parts) {
+            for (const p of res.data.parts) {
+              if (p.type === "text" && p.text) turnText += p.text;
+            }
+            if (turnText) {
+              bus.emitTransform("agent:response-chunk", {
+                blocks: [{ type: "text" as const, text: turnText }],
+              });
+            }
           }
+          bus.emitTransform("agent:response-done", { response: turnText });
         }
-        bus.emitTransform("agent:response-done", { response: turnText });
       } catch (err) {
-        bus.emit("agent:error", {
-          message: err instanceof Error ? err.message : String(err),
-        });
+        if (!turnError) {
+          bus.emit("agent:error", {
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
       } finally {
         pendingTurnEnd = null;
         bus.emit("agent:processing-done", {});
@@ -310,7 +394,7 @@ export default function activate(ctx: ExtensionContext): void {
     const onCancel = async () => {
       if (!runtime || !sessionId) return;
       try {
-        await runtime.client.session.abort({ path: { id: sessionId } });
+        await runtime.client.session.abort({ sessionID: sessionId, directory: sessionDirectory ?? undefined });
       } catch { /* abort is best-effort */ }
     };
 
@@ -321,7 +405,7 @@ export default function activate(ctx: ExtensionContext): void {
       partKinds.clear();
       // /reset is the one moment we deliberately let the project switch.
       sessionDirectory = cwd();
-      const res = await runtime.client.session.create({ query: { directory: sessionDirectory } });
+      const res = await runtime.client.session.create({ directory: sessionDirectory });
       sessionId = res.data?.id ?? null;
     };
 
@@ -352,13 +436,13 @@ export default function activate(ctx: ExtensionContext): void {
         void consumeEvents(runtime.client, streamAbort.signal);
 
         sessionDirectory = cwd();
-        const res = await runtime.client.session.create({ query: { directory: sessionDirectory } });
+        const res = await runtime.client.session.create({ directory: sessionDirectory });
         sessionId = res.data?.id ?? null;
         if (!sessionId) throw new Error("session.create returned no id");
 
         wireListeners();
         booting = false;
-        bus.emit("agent:info", { name: "opencode", version: "1.x" });
+        bus.emit("agent:info", { name: "opencode", version: "2.x" });
       } catch (err) {
         booting = false;
         bus.emit("ui:error", {
@@ -381,3 +465,137 @@ export default function activate(ctx: ExtensionContext): void {
     },
   });
 }
+
+// ── Interactive question picker ──────────────────────────────────
+
+type QuestionResult = { answers: string[][]; cancelled: boolean };
+
+function isKey(data: string, key: string): boolean {
+  switch (key) {
+    case "up":     return data === "\x1b[A" || data === "\x1bOA";
+    case "down":   return data === "\x1b[B" || data === "\x1bOB";
+    case "left":   return data === "\x1b[D" || data === "\x1bOD";
+    case "right":  return data === "\x1b[C" || data === "\x1bOC";
+    case "enter":  return data === "\r" || data === "\n";
+    case "escape": return data === "\x1b";
+    case "tab":    return data === "\t";
+    default:       return data === key;
+  }
+}
+
+function createQuestionSession(questions: QuestionInfo[]): InteractiveSession<QuestionResult> {
+  const isMulti = questions.length > 1;
+  let tab = 0;
+  let optionIdx = 0;
+  // Per-question selected option indices (set, to support `multiple`).
+  const selections: Set<number>[] = questions.map(() => new Set());
+
+  return {
+    render(width) {
+      const w = Math.min(80, width);
+      const lines: string[] = [];
+      const q = questions[tab]!;
+      const sel = selections[tab]!;
+
+      lines.push(`${p.muted}${"─".repeat(w)}${p.reset}`);
+
+      if (isMulti) {
+        const tabs = questions.map((qq, i) => {
+          const answered = selections[i]!.size > 0;
+          const active = i === tab;
+          const box = answered ? "■" : "□";
+          const label = ` ${box} ${qq.header || `Q${i + 1}`} `;
+          return active
+            ? `${p.accent}${p.bold}${label}${p.reset}`
+            : `${p.muted}${label}${p.reset}`;
+        });
+        lines.push(` ${tabs.join(" ")}`);
+        lines.push("");
+      }
+
+      lines.push(` ${q.question}`);
+      lines.push("");
+      for (let i = 0; i < q.options.length; i++) {
+        const opt = q.options[i]!;
+        const cursor = i === optionIdx ? p.accent : "";
+        const reset = i === optionIdx ? p.reset : "";
+        const arrow = i === optionIdx ? `${p.accent}>${p.reset} ` : "  ";
+        const mark = q.multiple
+          ? (sel.has(i) ? "[x]" : "[ ]")
+          : (sel.has(i) ? "(o)" : "( )");
+        lines.push(`${arrow}${cursor}${mark} ${i + 1}. ${opt.label}${reset}`);
+        if (opt.description) {
+          lines.push(`     ${p.muted}${opt.description}${p.reset}`);
+        }
+      }
+
+      lines.push("");
+      const navKeys = isMulti ? "Tab/←→ switch • " : "";
+      const actionKeys = q.multiple
+        ? "↑↓ navigate • Space toggle • Enter confirm • Esc cancel"
+        : "↑↓ navigate • Enter select • Esc cancel";
+      lines.push(` ${p.dim}${navKeys}${actionKeys}${p.reset}`);
+      lines.push(`${p.muted}${"─".repeat(w)}${p.reset}`);
+      return lines;
+    },
+
+    handleInput(data, done) {
+      const q = questions[tab]!;
+      const sel = selections[tab]!;
+
+      if (isKey(data, "escape")) {
+        done({ answers: [], cancelled: true });
+        return;
+      }
+
+      if (isMulti) {
+        if (isKey(data, "tab") || isKey(data, "right")) {
+          tab = (tab + 1) % questions.length;
+          optionIdx = 0;
+          return;
+        }
+        if (isKey(data, "left")) {
+          tab = (tab - 1 + questions.length) % questions.length;
+          optionIdx = 0;
+          return;
+        }
+      }
+
+      if (isKey(data, "up")) {
+        optionIdx = Math.max(0, optionIdx - 1);
+        return;
+      }
+      if (isKey(data, "down")) {
+        optionIdx = Math.min(q.options.length - 1, optionIdx + 1);
+        return;
+      }
+
+      if (q.multiple && data === " ") {
+        if (sel.has(optionIdx)) sel.delete(optionIdx); else sel.add(optionIdx);
+        return;
+      }
+
+      if (isKey(data, "enter")) {
+        if (!q.multiple) {
+          sel.clear();
+          sel.add(optionIdx);
+        }
+        if (sel.size === 0) return;
+
+        const allAnswered = selections.every((s) => s.size > 0);
+        if (!isMulti || allAnswered) {
+          const answers = questions.map((qq, i) =>
+            Array.from(selections[i]!).map((idx) => qq.options[idx]!.label),
+          );
+          done({ answers, cancelled: false });
+          return;
+        }
+        const next = selections.findIndex((s) => s.size === 0);
+        if (next !== -1) {
+          tab = next;
+          optionIdx = 0;
+        }
+      }
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.12.25",
+  "version": "0.12.26",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",