agent-sh 0.8.0 → 0.10.0

package/dist/{shell.js → shell/shell.js}

@@ -4,11 +4,12 @@ import * as path from "path";
 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";
+import { getSettings } from "../settings.js";
+import { RefCounter } from "../utils/output-writer.js";
 export class Shell {
     ptyProcess;
     bus;
+    handlers;
     inputHandler;
     outputParser;
     paused = false;
@@ -139,6 +140,7 @@ export class Shell {
             }
         }
         this.bus = opts.bus;
+        this.handlers = opts.handlers;
         this.outputParser = new OutputParser(opts.bus, opts.cwd);
         // Ensure temp dir cleanup on abnormal exit (SIGKILL won't fire this,
         // but it covers uncaught exceptions and normal process.exit paths)
@@ -195,6 +197,11 @@ export class Shell {
      * For bash, falls back to sending \n for a fresh prompt cycle.
      */
     redrawPrompt() {
+        // A stale echoSkip or paused flag (left over from handleProcessingDone
+        // re-entering a mode) would swallow the redrawn prompt and make the
+        // terminal appear frozen. Reset both before emitting.
+        this.echoSkip = false;
+        this.paused = false;
         const result = this.bus.emitPipe("shell:redraw-prompt", {
             cwd: this.outputParser.getCwd(),
             handled: false,
@@ -225,7 +232,9 @@ export class Shell {
         });
         if (!result.handled) {
             this.ptyProcess.write("\n");
+            return true;
         }
+        return false;
     }
     onCommandEntered(command, cwd) {
         this.outputParser.onCommandEntered(command, cwd);
@@ -265,18 +274,32 @@ export class Shell {
      * zero frontend knowledge; any frontend can subscribe to the same events.
      */
     setupAgentLifecycle() {
-        this.bus.on("agent:processing-start", () => {
+        // Default agent lifecycle: pause the shell while the agent works,
+        // then redraw the prompt when done. Extensions advise these handlers
+        // to change behavior (e.g. tmux split keeps the shell interactive).
+        this.handlers.define("shell:on-processing-start", () => {
             this.agentActive = true;
             this.paused = true;
         });
-        this.bus.on("agent:processing-done", () => {
-            this.paused = false;
+        this.handlers.define("shell:on-processing-done", () => {
             this.agentActive = false;
-            this.echoSkip = true;
+            // If handleProcessingDone re-entered a mode, leave stdout paused so
+            // stale PTY output doesn't overwrite the mode prompt (exitMode →
+            // redrawPrompt will unpause). Setting echoSkip here would swallow
+            // that PTY output since no \n was sent.
             if (!this.inputHandler.handleProcessingDone()) {
-                this.freshPrompt();
+                this.paused = false;
+                if (this.freshPrompt()) {
+                    this.echoSkip = true;
+                }
             }
         });
+        this.bus.on("agent:processing-start", () => {
+            this.handlers.call("shell:on-processing-start");
+        });
+        this.bus.on("agent:processing-done", () => {
+            this.handlers.call("shell:on-processing-done");
+        });
         // Permission prompts need stdout unpaused so the interactive UI renders,
         // then re-paused after the decision.
         this.bus.on("permission:request", () => {
@@ -303,11 +326,19 @@ export class Shell {
                 const handler = (e) => {
                     clearTimeout(timeout);
                     this.bus.off("shell:command-done", handler);
+                    // Re-pause stdout so the prompt text following the marker doesn't
+                    // leak to the terminal while the agent is still processing.
+                    this.paused = true;
                     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());
-                this.ptyProcess.write(payload.command + "\r");
+                // Collapse literal newlines to spaces so the PTY receives a single-line
+                // command. Multi-line commands (e.g. git commit -m "...\n...") would
+                // cause the shell to execute prematurely, producing garbled output from
+                // syntax highlighting plugins (zsh syntax highlighting, etc).
+                const oneLine = payload.command.replace(/\n/g, " ");
+                this.ptyProcess.write(oneLine + "\r");
             });
             this.paused = true;
             this.echoSkip = false;

package/dist/types.d.ts

@@ -1,13 +1,37 @@
 import type { EventBus } from "./event-bus.js";
 import type { ContextManager } from "./context-manager.js";
-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";
+import type { Compositor } from "./utils/compositor.js";
 export type { ContentBlock } from "./event-bus.js";
 export type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
+export type { RenderSurface } from "./utils/compositor.js";
+export interface RemoteSessionOptions {
+    /** The surface to render agent output to. */
+    surface: import("./utils/compositor.js").RenderSurface;
+    /** Suppress response borders (default: true). */
+    suppressBorders?: boolean;
+    /** Suppress user query box (default: false).
+     *  True for sessions with their own input (rsplit, overlay).
+     *  False for sessions where input comes from the main shell (split). */
+    suppressQueryBox?: boolean;
+    /** Suppress usage stats line (default: true). */
+    suppressUsage?: boolean;
+    /** Set interactive-session dynamic context (default: false). */
+    interactive?: boolean;
+}
+export interface RemoteSession {
+    /** Submit a query to the agent from this session. */
+    submit(query: string): void;
+    /** The surface this session renders to. */
+    readonly surface: import("./utils/compositor.js").RenderSurface;
+    /** Whether this session is currently active. */
+    readonly active: boolean;
+    /** Tear down — restores all routing and advisors. */
+    close(): void;
+}
 /** A model entry in the cycling list, optionally tied to a provider. */
 export interface AgentMode {
     model: string;
@@ -45,8 +69,8 @@ export interface AgentShellConfig {
 export interface ExtensionContext {
     bus: EventBus;
     contextManager: ContextManager;
-    /** LLM client for fast-path features (null in ACP mode). */
-    llmClient: LlmClient | null;
+    /** Stable per-instance identifier (4-char hex). */
+    readonly instanceId: string;
     quit: () => void;
     /** Override color palette slots for theming. */
     setPalette: (overrides: Partial<ColorPalette>) => void;
@@ -56,29 +80,56 @@ export interface ExtensionContext {
     createFencedBlockTransform: (opts: FencedBlockTransformOptions) => void;
     /** Read extension-namespaced settings from ~/.agent-sh/settings.json. */
     getExtensionSettings: <T extends Record<string, unknown>>(namespace: string, defaults: T) => T;
+    /**
+     * Get (and lazily create) a per-extension storage directory under
+     * ~/.agent-sh/<namespace>/. Returns the absolute path. Lets extensions
+     * persist state without each one re-deriving the location.
+     */
+    getStoragePath: (namespace: string) => string;
     /** Register a slash command available in any input mode. */
     registerCommand: (name: string, description: string, handler: (args: string) => Promise<void> | void) => void;
     /** Register a tool for the built-in agent. No-op when using bridge backends. */
     registerTool: (tool: ToolDefinition) => void;
+    /** Unregister a tool by name. */
+    unregisterTool: (name: string) => void;
     /** Get all registered tools (for subagent tool subsets). Returns [] when using bridge backends. */
     getTools: () => ToolDefinition[];
+    /** Register a named instruction block for the agent's system prompt. */
+    registerInstruction: (name: string, text: string) => void;
+    /** Remove a named instruction block from the system prompt. */
+    removeInstruction: (name: string) => void;
+    /** Register a skill (on-demand reference material) for the agent. */
+    registerSkill: (name: string, description: string, filePath: string) => void;
+    /** Remove a registered skill by name. */
+    removeSkill: (name: string) => void;
     /** Register a named handler. */
     define: (name: string, fn: (...args: any[]) => any) => void;
-    /** Wrap a named handler. Receives `next` (original) + args. */
-    advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => void;
+    /** Wrap a named handler. Receives `next` (original) + args. Returns an unadvise function. */
+    advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => () => void;
     /** Call a named handler. */
     call: (name: string, ...args: any[]) => any;
+    /** Names of all registered handlers — for diagnostic / introspection use. */
+    list: () => string[];
     /**
      * 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.
+     * Routes named render streams ("agent", "query", "status") to surfaces.
+     * Extensions use `compositor.redirect()` to capture output (e.g. overlay panels).
+     */
+    compositor: Compositor;
+    /**
+     * Create a remote session that routes agent output to a surface and
+     * optionally accepts queries. Handles all compositor routing, shell
+     * lifecycle advisors, and chrome suppression.
+     *
+     *   const session = ctx.createRemoteSession({ surface, interactive: true });
+     *   session.submit("what's on screen?");
+     *   session.close();  // restores everything
      */
-    createFloatingPanel: (config: FloatingPanelConfig) => FloatingPanel;
+    createRemoteSession: (opts: RemoteSessionOptions) => RemoteSession;
 }
 /**
  * Configuration for a registered input mode.

package/dist/utils/ansi.d.ts

@@ -6,6 +6,11 @@ export declare const RED = "\u001B[31m";
 export declare const GRAY = "\u001B[90m";
 export declare const BOLD = "\u001B[1m";
 export declare const RESET = "\u001B[0m";
+/**
+ * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
+ * Returns 2 for wide chars, 1 for normal chars.
+ */
+export declare function charWidth(codePoint: number): number;
 /**
  * Measure visible string length in terminal columns.
  * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.

package/dist/utils/ansi.js

@@ -12,7 +12,7 @@ export const RESET = "\x1b[0m";
  * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
  * Returns 2 for wide chars, 1 for normal chars.
  */
-function charWidth(codePoint) {
+export function charWidth(codePoint) {
     // CJK Unified Ideographs
     if (codePoint >= 0x4e00 && codePoint <= 0x9fff)
         return 2;

package/dist/utils/compositor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Compositor — routes named render streams to surfaces.
+ *
+ * Components write to named streams ("agent", "query", "status").
+ * The compositor decides where each stream actually goes based on
+ * the current routing table.  Extensions override routing with
+ * `redirect()` to capture output (e.g. overlay panels).
+ *
+ * Streams are hierarchical: "agent:diff" falls back to "agent" if
+ * no override or default is registered for "agent:diff" specifically.
+ * This enables fine-grained interception — redirect just diffs into
+ * a panel, or just a subagent's output ("agent:sub:abc123"), while
+ * everything else flows to the parent stream's surface.
+ *
+ *   // tui-renderer registers default surfaces
+ *   compositor.setDefault("agent", stdoutSurface);
+ *
+ *   // overlay-agent redirects when active
+ *   const restore = compositor.redirect("agent", panelSurface);
+ *   // ... later ...
+ *   restore();  // back to stdout
+ *
+ *   // fine-grained: redirect only diffs to a viewer panel
+ *   compositor.redirect("agent:diff", diffPanelSurface);
+ *   // "agent:text", "agent:tool" etc. still go to stdout
+ */
+import type { EventBus } from "../event-bus.js";
+/**
+ * A surface accepts rendered output.  Stdout is a surface.
+ * A floating panel's content area is a surface.  A test buffer is a surface.
+ */
+export interface RenderSurface {
+    /** Raw write — supports \r, partial lines, escape codes. */
+    write(text: string): void;
+    /** Convenience: write + newline. */
+    writeLine(line: string): void;
+    /** Available width in columns. */
+    readonly columns: number;
+}
+export interface Compositor {
+    /** Get the currently active surface for a stream. */
+    surface(stream: string): RenderSurface;
+    /** Override routing: redirect a stream to a different surface.
+     *  Returns a restore function that undoes the redirect. */
+    redirect(stream: string, target: RenderSurface): () => void;
+    /** Register the default surface for a stream. */
+    setDefault(stream: string, target: RenderSurface): void;
+}
+/** Silent sink — drops all output. Used when no surface is registered. */
+export declare const nullSurface: RenderSurface;
+/** Surface backed by process.stdout. */
+export declare class StdoutSurface implements RenderSurface {
+    write(text: string): void;
+    writeLine(line: string): void;
+    get columns(): number;
+}
+export declare class DefaultCompositor implements Compositor {
+    private defaults;
+    private overrides;
+    private readonly bus?;
+    constructor(bus?: EventBus);
+    surface(stream: string): RenderSurface;
+    redirect(stream: string, target: RenderSurface): () => void;
+    setDefault(stream: string, target: RenderSurface): void;
+    /** Wrap a surface so writes emit `compositor:write` before delegating. */
+    private wrap;
+}

package/dist/utils/compositor.js

@@ -0,0 +1,116 @@
+/**
+ * Compositor — routes named render streams to surfaces.
+ *
+ * Components write to named streams ("agent", "query", "status").
+ * The compositor decides where each stream actually goes based on
+ * the current routing table.  Extensions override routing with
+ * `redirect()` to capture output (e.g. overlay panels).
+ *
+ * Streams are hierarchical: "agent:diff" falls back to "agent" if
+ * no override or default is registered for "agent:diff" specifically.
+ * This enables fine-grained interception — redirect just diffs into
+ * a panel, or just a subagent's output ("agent:sub:abc123"), while
+ * everything else flows to the parent stream's surface.
+ *
+ *   // tui-renderer registers default surfaces
+ *   compositor.setDefault("agent", stdoutSurface);
+ *
+ *   // overlay-agent redirects when active
+ *   const restore = compositor.redirect("agent", panelSurface);
+ *   // ... later ...
+ *   restore();  // back to stdout
+ *
+ *   // fine-grained: redirect only diffs to a viewer panel
+ *   compositor.redirect("agent:diff", diffPanelSurface);
+ *   // "agent:text", "agent:tool" etc. still go to stdout
+ */
+/** Silent sink — drops all output. Used when no surface is registered. */
+export const nullSurface = {
+    write() { },
+    writeLine() { },
+    get columns() { return 80; },
+};
+/** Surface backed by process.stdout. */
+export class StdoutSurface {
+    write(text) {
+        if (process.stdout.writable) {
+            try {
+                process.stdout.write(text);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    writeLine(line) {
+        this.write(line + "\n");
+    }
+    get columns() {
+        return process.stdout.columns || 80;
+    }
+}
+export class DefaultCompositor {
+    defaults = new Map();
+    overrides = new Map();
+    bus;
+    constructor(bus) {
+        this.bus = bus;
+    }
+    surface(stream) {
+        const stack = this.overrides.get(stream);
+        if (stack && stack.length > 0)
+            return stack[stack.length - 1];
+        if (this.defaults.has(stream))
+            return this.defaults.get(stream);
+        // Hierarchical fallback: "agent:diff" → "agent"
+        const colon = stream.lastIndexOf(":");
+        if (colon !== -1)
+            return this.surface(stream.slice(0, colon));
+        return nullSurface;
+    }
+    redirect(stream, target) {
+        const wrapped = this.wrap(stream, target);
+        let stack = this.overrides.get(stream);
+        if (!stack) {
+            stack = [];
+            this.overrides.set(stream, stack);
+        }
+        stack.push(wrapped);
+        let restored = false;
+        return () => {
+            if (restored)
+                return;
+            restored = true;
+            const s = this.overrides.get(stream);
+            if (!s)
+                return;
+            const idx = s.indexOf(wrapped);
+            if (idx !== -1)
+                s.splice(idx, 1);
+        };
+    }
+    setDefault(stream, target) {
+        this.defaults.set(stream, this.wrap(stream, target));
+    }
+    /** Wrap a surface so writes emit `compositor:write` before delegating. */
+    wrap(stream, target) {
+        const bus = this.bus;
+        if (!bus)
+            return target;
+        return {
+            write: (text) => {
+                try {
+                    bus.emit("compositor:write", { stream, text });
+                }
+                catch { }
+                target.write(text);
+            },
+            writeLine: (line) => {
+                try {
+                    bus.emit("compositor:write", { stream, text: line + "\n" });
+                }
+                catch { }
+                target.writeLine(line);
+            },
+            get columns() { return target.columns; },
+        };
+    }
+}

package/dist/utils/diff-renderer.d.ts

@@ -18,3 +18,12 @@ export interface DiffRenderOptions {
 export declare function selectMode(width: number): DiffDisplayMode;
 /** Render a diff result as an array of ANSI-formatted terminal lines. */
 export declare function renderDiff(diff: DiffResult, opts: DiffRenderOptions): string[];
+/**
+ * Async variant of renderDiff that yields to the event loop between hunks.
+ * Use when rendering in a context where a spinner or other UI needs to stay
+ * responsive (e.g. showing a large diff during a permission prompt).
+ *
+ * @param onLines - Callback invoked with each batch of rendered lines as they
+ *                  are produced. Allows progressive/streaming display.
+ */
+export declare function renderDiffAsync(diff: DiffResult, opts: DiffRenderOptions, onLines: (lines: string[]) => void): Promise<void>;