agent-sh 0.7.0 → 0.9.0

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;
@@ -60,12 +84,18 @@ export interface ExtensionContext {
     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 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;
     /**
@@ -74,11 +104,20 @@ export interface ExtensionContext {
      */
     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).
      */
-    createFloatingPanel: (config: FloatingPanelConfig) => FloatingPanel;
+    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
+     */
+    createRemoteSession: (opts: RemoteSessionOptions) => RemoteSession;
 }
 /**
  * Configuration for a registered input mode.
@@ -101,12 +140,6 @@ export interface TerminalSession {
     done: boolean;
     resolve?: (value: void) => void;
 }
-export interface ToolCallRecord {
-    tool: string;
-    args: Record<string, unknown>;
-    output: string;
-    exitCode: number | null;
-}
 export type Exchange = {
     type: "shell_command";
     id: number;
@@ -124,20 +157,4 @@ export type Exchange = {
     id: number;
     timestamp: number;
     query: string;
-} | {
-    type: "agent_response";
-    id: number;
-    timestamp: number;
-    response: string;
-    toolCalls: ToolCallRecord[];
-} | {
-    type: "tool_execution";
-    id: number;
-    timestamp: number;
-    tool: string;
-    args: Record<string, unknown>;
-    output: string;
-    exitCode: number | null;
-    outputLines: number;
-    outputBytes: number;
 };

package/dist/utils/ansi.d.ts

@@ -11,5 +11,15 @@ export declare const RESET = "\u001B[0m";
  * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
  */
 export declare function visibleLen(str: string): number;
+/**
+ * Truncate a string to fit within `maxWidth` visible columns.
+ * Accounts for CJK double-width characters. Appends `…` if truncated.
+ */
+export declare function truncateToWidth(str: string, maxWidth: number): string;
+/**
+ * Pad a string with spaces to fill `targetWidth` visible columns.
+ * Accounts for CJK double-width characters.
+ */
+export declare function padEndToWidth(str: string, targetWidth: number): string;
 /** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
 export declare function stripAnsi(str: string): string;

package/dist/utils/ansi.js

@@ -70,6 +70,33 @@ export function visibleLen(str) {
     }
     return width;
 }
+/**
+ * Truncate a string to fit within `maxWidth` visible columns.
+ * Accounts for CJK double-width characters. Appends `…` if truncated.
+ */
+export function truncateToWidth(str, maxWidth) {
+    const clean = str.replace(/\x1b\[[^m]*m/g, "");
+    let width = 0;
+    let i = 0;
+    for (const char of clean) {
+        const cw = charWidth(char.codePointAt(0) ?? 0);
+        if (width + cw > maxWidth - 1) {
+            // Need room for the "…" (1 column wide)
+            return clean.slice(0, i) + "…";
+        }
+        width += cw;
+        i += char.length;
+    }
+    return clean;
+}
+/**
+ * Pad a string with spaces to fill `targetWidth` visible columns.
+ * Accounts for CJK double-width characters.
+ */
+export function padEndToWidth(str, targetWidth) {
+    const gap = targetWidth - visibleLen(str);
+    return gap > 0 ? str + " ".repeat(gap) : str;
+}
 /** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
 export function stripAnsi(str) {
     return str

package/dist/utils/compositor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+    surface(stream: string): RenderSurface;
+    redirect(stream: string, target: RenderSurface): () => void;
+    setDefault(stream: string, target: RenderSurface): void;
+}

package/dist/utils/compositor.js

@@ -0,0 +1,88 @@
+/**
+ * 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();
+    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) {
+        let stack = this.overrides.get(stream);
+        if (!stack) {
+            stack = [];
+            this.overrides.set(stream, stack);
+        }
+        stack.push(target);
+        let restored = false;
+        return () => {
+            if (restored)
+                return;
+            restored = true;
+            const s = this.overrides.get(stream);
+            if (!s)
+                return;
+            const idx = s.indexOf(target);
+            if (idx !== -1)
+                s.splice(idx, 1);
+        };
+    }
+    setDefault(stream, target) {
+        this.defaults.set(stream, target);
+    }
+}

package/dist/utils/diff-renderer.js

@@ -254,7 +254,7 @@ function renderUnified(diff, opts) {
         const renderedAsPartOfPair = new Set();
         for (let i = 0; i < hunk.lines.length; i++) {
             const line = hunk.lines[i];
-            const no = String(line.oldNo ?? line.newNo ?? "").padStart(noW);
+            const no = String(line.type === "removed" ? (line.oldNo ?? "") : (line.newNo ?? line.oldNo ?? "")).padStart(noW);
             if (line.type === "context") {
                 const raw = truncateText(line.text, lineTextW);
                 const text = lang ? highlightLine(raw, lang) : raw;
@@ -468,6 +468,91 @@ function truncateText(text, maxWidth) {
     }
     return text.slice(0, i) + p.reset + "…";
 }
+// ── Truncation ──────────────────────────────────────────────────
+/**
+ * Trim context lines from hunks so the rendered output fits within a budget.
+ * Change lines are never removed — only the surrounding context shrinks.
+ */
+function trimHunksToFit(hunks, maxLines) {
+    // Count change lines across all hunks
+    let changeCount = 0;
+    for (const hunk of hunks) {
+        for (const line of hunk.lines) {
+            if (line.type !== "context")
+                changeCount++;
+        }
+    }
+    // Separators between hunks
+    const separators = Math.max(0, hunks.length - 1);
+    // How many context lines can we afford?
+    const contextBudget = Math.max(0, maxLines - changeCount - separators);
+    // Count total context to see if trimming is needed
+    let totalContext = 0;
+    for (const hunk of hunks) {
+        for (const line of hunk.lines) {
+            if (line.type === "context")
+                totalContext++;
+        }
+    }
+    if (totalContext <= contextBudget)
+        return hunks;
+    // Determine how many context lines to keep per side of each change.
+    // Binary-search for the largest per-side context that fits.
+    let lo = 0;
+    let hi = 3; // original context size from groupHunks
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (countContextWithLimit(hunks, mid) <= contextBudget)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return rebuildHunks(hunks, lo);
+}
+/** Count how many context lines remain if we keep at most `ctx` per side of each change. */
+function countContextWithLimit(hunks, ctx) {
+    let count = 0;
+    for (const hunk of hunks) {
+        const lines = hunk.lines;
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].type !== "context")
+                continue;
+            // Keep this context line if it's within `ctx` of any change
+            let nearChange = false;
+            for (let d = 1; d <= ctx; d++) {
+                if ((i - d >= 0 && lines[i - d].type !== "context") ||
+                    (i + d < lines.length && lines[i + d].type !== "context")) {
+                    nearChange = true;
+                    break;
+                }
+            }
+            if (nearChange)
+                count++;
+        }
+    }
+    return count;
+}
+/** Rebuild hunks keeping only context lines within `ctx` distance of a change. */
+function rebuildHunks(hunks, ctx) {
+    return hunks.map((hunk) => {
+        const lines = hunk.lines;
+        const kept = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].type !== "context") {
+                kept.push(lines[i]);
+                continue;
+            }
+            for (let d = 1; d <= ctx; d++) {
+                if ((i - d >= 0 && lines[i - d].type !== "context") ||
+                    (i + d < lines.length && lines[i + d].type !== "context")) {
+                    kept.push(lines[i]);
+                    break;
+                }
+            }
+        }
+        return { lines: kept };
+    });
+}
 // ── Public API ───────────────────────────────────────────────────
 /** Select display mode based on available terminal width. */
 export function selectMode(width) {
@@ -487,16 +572,19 @@ export function renderDiff(diff, opts) {
     if (mode === "summary") {
         return [header, ...renderSummary(diff)];
     }
+    // Trim context lines from hunks if the diff would exceed the budget,
+    // so that actual changes are always visible.
+    const trimmed = { ...diff, hunks: trimHunksToFit(diff.hunks, maxLines) };
     let bodyLines;
     switch (mode) {
         case "split":
-            bodyLines = renderSplit(diff, opts);
+            bodyLines = renderSplit(trimmed, opts);
             break;
         case "unified":
-            bodyLines = renderUnified(diff, opts);
+            bodyLines = renderUnified(trimmed, opts);
             break;
     }
-    // Truncation
+    // Final safety net — if still over budget, simple tail truncation.
     if (bodyLines.length > maxLines) {
         const overflow = bodyLines.length - maxLines;
         bodyLines = bodyLines.slice(0, maxLines);

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

@@ -20,7 +20,7 @@ export interface FloatingPanelConfig {
      * Requires @xterm/headless — falls back to blank background if unavailable.
      */
     dimBackground?: boolean;
-    /** Auto-dismiss delay in ms when done (0 = disabled). Default: 0. */
+    /** Auto-dismiss delay in ms when done (0 = auto-prompt for follow-up). Default: 0. */
     autoDismissMs?: number;
     /** Icon shown before the input cursor. Default: "\u276f". */
     promptIcon?: string;
@@ -144,6 +144,7 @@ export declare 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`
      */
@@ -153,29 +154,49 @@ export declare class FloatingPanel {
     /** All byte sequences that should be recognized as the trigger key. */
     private readonly triggerSeqs;
     private phase;
+    private _visible;
+    private _passthrough;
     private editor;
     private contentLines;
     private currentPartialLine;
     private scrollOffset;
+    private userScrolled;
     private title;
     private footer;
     private renderTimer;
-    private autoDismissTimer;
     private resizeHandler;
     private prevFrame;
     private suppressNextRedraw;
+    private autoDismissTimer;
     private ptyBuffer;
     private usedAltScreen;
+    private wrapCache;
+    private wrapCacheWidth;
+    private passthroughTimer;
+    private prevSerialized;
     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;
+    /** Whether the panel has an active conversation (may be hidden). */
     get active(): boolean;
+    /** Whether the agent is currently processing a query. */
+    get processing(): boolean;
+    /** Whether the panel is currently visible on screen. */
+    get visible(): boolean;
     get terminalBuffer(): TerminalBuffer | null;
+    /** Open a fresh panel with a new conversation. */
     open(): void;
+    /** Hide the panel without destroying conversation state. */
+    hide(): void;
+    /** Show the panel again after hide(), preserving conversation. */
+    show(): void;
+    /** Fully destroy the panel, resetting all state. */
     dismiss(): void;
+    /** Common screen enter logic shared by open() and show(). */
+    private enterScreen;
     appendText(text: string): void;
     appendLine(line: string): void;
     updateLastLine(fn: (line: string) => string): void;
@@ -184,15 +205,25 @@ export declare class FloatingPanel {
     setFooter(footer: string): void;
     setActive(): void;
     setDone(): void;
+    scrollUp(lines?: number): void;
+    scrollDown(lines?: number): void;
     getInput(): string;
     requestRender(): void;
     private handleIntercept;
+    /** Handle scroll input. Returns true if consumed. */
+    private handleScroll;
     private handleInputKey;
     /** Compute box geometry from config + current terminal size. */
     computeGeometry(): BoxGeometry;
     private buildFrame;
     private scheduleRender;
     private render;
-    private restoreScreen;
+    /** Full screen teardown: exit alt screen, release stdout, force redraw. */
+    private teardownScreen;
+    /** Start rendering TerminalBuffer directly (no overlay box). */
+    private startPassthrough;
+    private stopPassthrough;
+    /** Render the TerminalBuffer's screen content directly (no overlay). */
+    private renderPassthrough;
     private resolveSize;
 }