agent-sh 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,16 +1,10 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import * as path from "node:path";
-import { Shell } from "./shell.js";
+import { Shell } from "./shell/shell.js";
 import { createCore } from "./core.js";
 import { palette as p } from "./utils/palette.js";
-import tuiRenderer from "./extensions/tui-renderer.js";
-import slashCommands from "./extensions/slash-commands.js";
-import fileAutocomplete from "./extensions/file-autocomplete.js";
-import shellRecall from "./extensions/shell-recall.js";
-import commandSuggest from "./extensions/command-suggest.js";
-import terminalBuffer from "./extensions/terminal-buffer.js";
-import overlayAgent from "./extensions/overlay-agent.js";
+import { loadBuiltinExtensions } from "./extensions/index.js";
 import { loadExtensions } from "./extension-loader.js";
 import { getSettings } from "./settings.js";
 import { discoverSkills } from "./agent/skills.js";
@@ -160,6 +154,13 @@ async function main() {
         const shellEnv = await captureShellEnvAsync(shellPath);
         if (Object.keys(shellEnv).length > 0) {
             Object.assign(baseEnv, mergeShellEnv(baseEnv, shellEnv));
+            // Expose captured env vars to process.env so extensions can read them.
+            // Only add vars not already present to avoid clobbering runtime state.
+            for (const [k, v] of Object.entries(baseEnv)) {
+                if (process.env[k] === undefined) {
+                    process.env[k] = v;
+                }
+            }
             if (process.env.DEBUG) {
                 console.error('[agent-sh] Shell environment captured');
             }
@@ -195,6 +196,7 @@ async function main() {
     await new Promise(resolve => setTimeout(resolve, 100));
     const shell = new Shell({
         bus,
+        handlers: core.handlers,
         cols,
         rows,
         shell: config.shell || process.env.SHELL || "/bin/bash",
@@ -203,9 +205,6 @@ async function main() {
             if (agentInfo) {
                 return { info: `${p.dim}${agentInfo.name}${agentInfo.model ? ` (${agentInfo.model})` : ""}${p.reset}` };
             }
-            if (core.llmClient) {
-                return { info: `${p.dim}agent-sh (${core.llmClient.model})${p.reset}` };
-            }
             return { info: "" };
         },
     });
@@ -229,13 +228,8 @@ async function main() {
         console.error('[agent-sh] Setting up extensions...');
     }
     const extCtx = core.extensionContext({ quit: cleanup });
-    tuiRenderer(extCtx);
-    slashCommands(extCtx);
-    fileAutocomplete(extCtx);
-    shellRecall(extCtx);
-    commandSuggest(extCtx);
-    terminalBuffer(extCtx);
-    overlayAgent(extCtx);
+    // Load built-in extensions (individually disableable via settings.disabledBuiltins)
+    await loadBuiltinExtensions(extCtx, getSettings().disabledBuiltins);
     // Load user extensions (may register alternative agent backends)
     if (process.env.DEBUG) {
         console.error('[agent-sh] Loading extensions...');
@@ -264,8 +258,8 @@ async function main() {
         const bannerW = Math.min(termW, 60);
         const productName = `${p.accent}${p.bold}agent-sh${p.reset}`;
         const info = agentInfo;
-        const backendName = info?.name ?? "agent-sh";
-        const model = info?.model ?? core.llmClient?.model;
+        const backendName = info?.name ?? "ash";
+        const model = info?.model;
         const provider = info?.provider;
         const modelValue = model
             ? provider ? `${model} [${provider}]` : model

package/dist/settings.d.ts

@@ -52,18 +52,24 @@ export interface Settings {
     historyStartupEntries?: number;
     /** Max nuclear entries kept in-context before flushing to history file (default: 200). */
     nuclearMaxEntries?: number;
+    /** Auto-compact threshold as fraction of conversation budget (0-1, default 0.5). */
+    autoCompactThreshold?: number;
     /** Max command output lines shown inline in TUI. */
     maxCommandOutputLines?: number;
     /** Max read tool output lines shown inline in TUI (0 = hide). */
     readOutputMaxLines?: number;
     /** Max diff lines shown before "ctrl+o to expand". */
     diffMaxLines?: number;
+    /** Tool protocol: "api" (all tools), "deferred" (extensions via meta-tool), "inline" (text). */
+    toolMode?: "api" | "deferred" | "inline";
     /** Additional directories to scan for skills (supports ~ expansion). */
     skillPaths?: string[];
     /** Show a startup banner when agent-sh launches. */
     startupBanner?: boolean;
     /** Show a subtle agent-sh indicator in the shell prompt. */
     promptIndicator?: boolean;
+    /** Names of built-in extensions to disable (e.g. ["command-suggest"]). */
+    disabledBuiltins?: string[];
 }
 declare const DEFAULTS: Required<Settings>;
 /** Load settings from disk (cached after first call). */

package/dist/settings.js

@@ -14,7 +14,8 @@ const DEFAULTS = {
     historySize: 500,
     providers: {},
     defaultProvider: undefined,
-    defaultBackend: "agent-sh",
+    defaultBackend: "ash",
+    toolMode: "api",
     contextWindowSize: 20,
     contextBudget: 16384,
     shellTruncateThreshold: 10,
@@ -25,12 +26,14 @@ const DEFAULTS = {
     historyMaxBytes: 102400,
     historyStartupEntries: 50,
     nuclearMaxEntries: 200,
+    autoCompactThreshold: 0.5,
     maxCommandOutputLines: 3,
     readOutputMaxLines: 10,
     diffMaxLines: 20,
     skillPaths: [],
     startupBanner: true,
     promptIndicator: true,
+    disabledBuiltins: [],
 };
 let cached = null;
 /** Load settings from disk (cached after first call). */

package/dist/{input-handler.d.ts → shell/input-handler.d.ts}

@@ -1,4 +1,4 @@
-import type { EventBus } from "./event-bus.js";
+import type { EventBus } from "../event-bus.js";
 /**
  * Narrow contract between InputHandler and its host (Shell).
  * InputHandler never touches the PTY or EventBus directly —

package/dist/{input-handler.js → shell/input-handler.js}

@@ -1,9 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { visibleLen } from "./utils/ansi.js";
-import { palette as p } from "./utils/palette.js";
-import { LineEditor } from "./utils/line-editor.js";
-import { CONFIG_DIR, getSettings } from "./settings.js";
+import { visibleLen } from "../utils/ansi.js";
+import { palette as p } from "../utils/palette.js";
+import { LineEditor } from "../utils/line-editor.js";
+import { CONFIG_DIR, getSettings } from "../settings.js";
 const HISTORY_FILE = path.join(CONFIG_DIR, "history");
 export class InputHandler {
     ctx;
@@ -86,22 +86,24 @@ export class InputHandler {
         const icon = this.activeMode?.promptIcon ?? "❯";
         const promptPrefix = infoPrefix + p.warning + p.bold + icon + " " + p.reset;
         const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1; // icon + space
-        if (!showBuffer || !this.editor.buffer.includes("\n")) {
+        const display = showBuffer ? this.editor.displayText : "";
+        const dCursor = showBuffer ? this.editor.displayCursor : 0;
+        if (!showBuffer || !display.includes("\n")) {
             // Single-line: simple rendering
-            const bufferText = showBuffer ? p.accent + this.editor.buffer + p.reset : "";
+            const bufferText = showBuffer ? p.accent + display + p.reset : "";
             process.stdout.write(promptPrefix + bufferText);
-            const bufferVisLen = showBuffer ? this.editor.buffer.length : 0;
+            const bufferVisLen = display.length;
             const totalVisLen = promptVisLen + bufferVisLen;
             this.promptWrappedLines = totalVisLen > 0 ? Math.floor((totalVisLen - 1) / termW) : 0;
             // Position cursor within the buffer
-            if (showBuffer && this.editor.cursor < this.editor.buffer.length) {
-                const charsAfterCursor = this.editor.buffer.length - this.editor.cursor;
+            if (showBuffer && dCursor < display.length) {
+                const charsAfterCursor = display.length - dCursor;
                 process.stdout.write(`\x1b[${charsAfterCursor}D`);
             }
         }
         else {
             // Multi-line: render each line with continuation indent
-            const lines = this.editor.buffer.split("\n");
+            const lines = display.split("\n");
             const indent = " ".repeat(promptVisLen);
             let totalTermLines = 0;
             for (let li = 0; li < lines.length; li++) {
@@ -116,8 +118,8 @@ export class InputHandler {
                 totalTermLines += lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
             }
             this.promptWrappedLines = totalTermLines - 1;
-            // Position cursor: find which line and column the cursor is on
-            let charsRemaining = this.editor.cursor;
+            // Position cursor: find which display line and column the cursor is on
+            let charsRemaining = dCursor;
             let cursorLine = 0;
             for (let li = 0; li < lines.length; li++) {
                 if (charsRemaining <= lines[li].length) {
@@ -127,13 +129,31 @@ export class InputHandler {
                 charsRemaining -= lines[li].length + 1; // +1 for \n
                 cursorLine = li + 1;
             }
-            // Move from end position to cursor position
-            const linesFromEnd = lines.length - 1 - cursorLine;
-            if (linesFromEnd > 0) {
-                process.stdout.write(`\x1b[${linesFromEnd}A`);
+            // Compute terminal rows for cursor positioning (not logical lines)
+            // Each logical line may wrap across multiple terminal rows.
+            const cursorColAbs = promptVisLen + charsRemaining;
+            const cursorTermRow = Math.floor(cursorColAbs / termW);
+            // Count terminal rows occupied by lines after cursor's logical line
+            let termRowsAfterCursor = 0;
+            for (let li = cursorLine + 1; li < lines.length; li++) {
+                const lineVisLen = promptVisLen + lines[li].length;
+                termRowsAfterCursor += lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
+            }
+            // Also count remaining terminal rows on cursor's own logical line
+            const cursorLineVisLen = promptVisLen + lines[cursorLine].length;
+            const cursorLineTotalRows = cursorLineVisLen > 0 ? Math.ceil(cursorLineVisLen / termW) : 1;
+            const rowsAfterCursorInLine = cursorLineTotalRows - 1 - cursorTermRow;
+            const totalRowsFromEnd = termRowsAfterCursor + rowsAfterCursorInLine;
+            if (totalRowsFromEnd > 0) {
+                process.stdout.write(`\x1b[${totalRowsFromEnd}A`);
+            }
+            const cursorCol = cursorColAbs % termW;
+            if (cursorCol > 0) {
+                process.stdout.write(`\r\x1b[${cursorCol}C`);
+            }
+            else {
+                process.stdout.write(`\r`);
             }
-            const cursorCol = (cursorLine === 0 ? promptVisLen : promptVisLen) + charsRemaining;
-            process.stdout.write(`\r\x1b[${cursorCol}C`);
         }
     }
     handleInput(data) {
@@ -249,16 +269,17 @@ export class InputHandler {
         this.activeMode = mode;
         this.editor.clear();
         // Enable kitty keyboard protocol (progressive enhancement flag 1)
-        // so Shift+Enter sends \x1b[13;2u instead of plain \r
-        process.stdout.write("\x1b[>1u");
+        // so Shift+Enter sends \x1b[13;2u instead of plain \r.
+        // Enable bracket paste mode so pasted text doesn't trigger submit.
+        process.stdout.write("\x1b[>1u\x1b[?2004h");
         this.writeModePromptLine(false);
     }
     exitMode() {
         this.dismissAutocomplete();
         this.activeMode = null;
         this.editor.clear();
-        // Disable kitty keyboard protocol
-        process.stdout.write("\x1b[<u");
+        // Disable kitty keyboard protocol and bracket paste mode
+        process.stdout.write("\x1b[<u\x1b[?2004l");
         this.clearPromptArea();
         this.printPrompt();
     }
@@ -294,7 +315,7 @@ export class InputHandler {
         this.updateAutocomplete();
     }
     updateAutocomplete() {
-        const buf = this.editor.buffer;
+        const buf = this.editor.text;
         let command = null;
         let commandArgs = null;
         if (buf.startsWith("/")) {
@@ -350,7 +371,7 @@ export class InputHandler {
             : `${indicator} `;
         const icon = this.activeMode?.promptIcon ?? "❯";
         const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1;
-        const col = promptVisLen + this.editor.cursor;
+        const col = promptVisLen + this.editor.displayCursor;
         process.stdout.write(`\r\x1b[${col}C`);
     }
     applyAutocomplete() {
@@ -359,18 +380,16 @@ export class InputHandler {
         const selected = this.autocompleteItems[this.autocompleteIndex];
         if (!selected)
             return;
-        const atPos = this.editor.buffer.lastIndexOf("@");
+        const atPos = this.editor.text.lastIndexOf("@");
         const isFileAc = atPos >= 0 &&
-            (atPos === 0 || this.editor.buffer[atPos - 1] === " ") &&
-            !this.editor.buffer.slice(atPos + 1).includes(" ");
+            (atPos === 0 || this.editor.text[atPos - 1] === " ") &&
+            !this.editor.text.slice(atPos + 1).includes(" ");
         if (isFileAc) {
-            this.editor.buffer =
-                this.editor.buffer.slice(0, atPos) + "@" + selected.name;
+            this.editor.setText(this.editor.text.slice(0, atPos) + "@" + selected.name);
         }
         else {
-            this.editor.buffer = selected.name;
+            this.editor.setText(selected.name);
         }
-        this.editor.cursor = this.editor.buffer.length;
         this.clearAutocompleteLines();
         this.autocompleteActive = false;
         this.autocompleteItems = [];
@@ -419,8 +438,8 @@ export class InputHandler {
             switch (act.action) {
                 case "changed": {
                     // If the buffer is exactly a trigger char for a different mode, switch to it
-                    const switchMode = this.modes.get(this.editor.buffer);
-                    if (this.editor.buffer.length === 1 && switchMode && switchMode !== this.activeMode) {
+                    const switchMode = this.modes.get(this.editor.text);
+                    if (this.editor.text.length === 1 && switchMode && switchMode !== this.activeMode) {
                         this.dismissAutocomplete();
                         this.clearPromptArea();
                         this.activeMode = switchMode;
@@ -437,10 +456,10 @@ export class InputHandler {
                     if (this.autocompleteActive) {
                         this.applyAutocomplete();
                     }
-                    // Use editor.buffer (not act.buffer) so autocomplete selections
+                    // Use editor.text (not act.buffer) so autocomplete selections
                     // take effect — act.buffer is a stale snapshot from before
-                    // applyAutocomplete() updated the buffer.
-                    const query = this.editor.buffer.trim();
+                    // applyAutocomplete() updated the editor.
+                    const query = this.editor.text.trim();
                     if (query) {
                         // Add to history (avoid consecutive duplicates)
                         if (this.history.length === 0 || this.history[this.history.length - 1] !== query) {
@@ -452,7 +471,7 @@ export class InputHandler {
                     this.savedBuffer = "";
                     this.clearAutocompleteLines();
                     this.clearPromptArea();
-                    process.stdout.write("\x1b[<u"); // disable kitty keyboard protocol
+                    process.stdout.write("\x1b[<u\x1b[?2004l"); // disable kitty + bracket paste
                     const currentMode = this.activeMode;
                     this.activeMode = null;
                     this.editor.clear();
@@ -506,14 +525,13 @@ export class InputHandler {
                     }
                     else if (this.history.length > 0) {
                         if (this.historyIndex === -1) {
-                            this.savedBuffer = this.editor.buffer;
+                            this.savedBuffer = this.editor.text;
                             this.historyIndex = this.history.length - 1;
                         }
                         else if (this.historyIndex > 0) {
                             this.historyIndex--;
                         }
-                        this.editor.buffer = this.history[this.historyIndex];
-                        this.editor.cursor = this.editor.buffer.length;
+                        this.editor.setText(this.history[this.historyIndex]);
                         this.clearAutocompleteLines();
                         this.writeModePromptLine();
                     }
@@ -531,13 +549,12 @@ export class InputHandler {
                     else if (this.historyIndex !== -1) {
                         if (this.historyIndex < this.history.length - 1) {
                             this.historyIndex++;
-                            this.editor.buffer = this.history[this.historyIndex];
+                            this.editor.setText(this.history[this.historyIndex]);
                         }
                         else {
                             this.historyIndex = -1;
-                            this.editor.buffer = this.savedBuffer;
+                            this.editor.setText(this.savedBuffer);
                         }
-                        this.editor.cursor = this.editor.buffer.length;
                         this.clearAutocompleteLines();
                         this.writeModePromptLine();
                     }

package/dist/{output-parser.d.ts → shell/output-parser.d.ts}

@@ -1,4 +1,4 @@
-import type { EventBus } from "./event-bus.js";
+import type { EventBus } from "../event-bus.js";
 /**
  * Parses PTY output to detect command boundaries, track cwd,
  * and emit shell events. Owns the command lifecycle state.

package/dist/{output-parser.js → shell/output-parser.js}

@@ -1,4 +1,4 @@
-import { stripAnsi } from "./utils/ansi.js";
+import { stripAnsi } from "../utils/ansi.js";
 /**
  * Parses PTY output to detect command boundaries, track cwd,
  * and emit shell events. Owns the command lifecycle state.

package/dist/{shell.d.ts → shell/shell.d.ts}

@@ -1,8 +1,13 @@
-import type { EventBus } from "./event-bus.js";
+import type { EventBus } from "../event-bus.js";
 import { type InputContext } from "./input-handler.js";
+export interface ShellHandlers {
+    define: (name: string, fn: (...args: any[]) => any) => void;
+    call: (name: string, ...args: any[]) => any;
+}
 export declare class Shell implements InputContext {
     private ptyProcess;
     private bus;
+    private handlers;
     private inputHandler;
     private outputParser;
     private paused;
@@ -14,6 +19,7 @@ export declare class Shell implements InputContext {
     private tmpDir?;
     constructor(opts: {
         bus: EventBus;
+        handlers: ShellHandlers;
         onShowAgentInfo?: () => {
             info: string;
             model?: string;
@@ -43,7 +49,7 @@ export declare class Shell implements InputContext {
      * Routed through shell:redraw-prompt pipe so extensions (e.g. overlay)
      * can suppress it by setting `handled: true`.
      */
-    freshPrompt(): void;
+    freshPrompt(): boolean;
     onCommandEntered(command: string, cwd: string): void;
     private setupOutput;
     private setupInput;

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)
@@ -225,7 +227,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 +269,28 @@ 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.handlers.define("shell:on-processing-done", () => {
             this.paused = false;
             this.agentActive = false;
-            this.echoSkip = true;
             if (!this.inputHandler.handleProcessingDone()) {
-                this.freshPrompt();
+                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", () => {

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).
+     */
+    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/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;
+}