agent-sh 0.6.0 → 0.8.0

package/dist/agent/nuclear-form.js

@@ -0,0 +1,175 @@
+// ── Tool classification ───────────────────────────────────────────
+/** Read-only tools whose results are dropped at Tier 1→2 (agent can re-read). */
+export const READ_ONLY_TOOLS = new Set([
+    "read_file", "grep", "glob", "ls", "search",
+]);
+/** State-changing tools whose summaries are kept in nuclear memory. */
+export const WRITE_TOOLS = new Set([
+    "write_file", "edit_file", "write", "edit", "patch",
+]);
+// ── Nuclear entry generation ──────────────────────────────────────
+/**
+ * Generate nuclear entries from a logical turn (a sequence of messages
+ * starting with a user message, followed by assistant + tool messages).
+ */
+export function toNuclearEntries(messages, startSeq, instanceId) {
+    const entries = [];
+    let seq = startSeq;
+    const ts = Date.now();
+    for (const msg of messages) {
+        if (msg.role === "user") {
+            const text = typeof msg.content === "string" ? msg.content : "";
+            // Skip compaction markers
+            if (text.startsWith("["))
+                continue;
+            entries.push({
+                seq: seq++, ts, iid: instanceId,
+                kind: "user",
+                sum: `user: "${truncate(text, 80)}"`,
+            });
+        }
+        else if (msg.role === "assistant") {
+            // Process tool calls
+            if ("tool_calls" in msg && msg.tool_calls) {
+                for (const tc of msg.tool_calls) {
+                    if (!("function" in tc))
+                        continue;
+                    const name = tc.function.name;
+                    let args = {};
+                    try {
+                        args = JSON.parse(tc.function.arguments);
+                    }
+                    catch { }
+                    // Store the tool call — we'll enrich it when we see the result
+                    entries.push({
+                        seq: seq++, ts, iid: instanceId,
+                        kind: "tool",
+                        tool: name,
+                        sum: summarizeToolCall(name, args),
+                    });
+                }
+            }
+            else if (typeof msg.content === "string" && msg.content) {
+                entries.push({
+                    seq: seq++, ts, iid: instanceId,
+                    kind: "agent",
+                    sum: `agent: "${truncate(msg.content, 60)}"`,
+                });
+            }
+        }
+        else if (msg.role === "tool") {
+            // Enrich the most recent tool entry with result info
+            const content = typeof msg.content === "string" ? msg.content : "";
+            const lastTool = findLastTool(entries);
+            if (lastTool) {
+                const isError = content.startsWith("Error:");
+                if (isError) {
+                    lastTool.kind = "error";
+                    lastTool.sum = `error: ${lastTool.tool} ${truncate(content.slice(7).trim(), 80)}`;
+                }
+                else {
+                    lastTool.sum = enrichWithResult(lastTool.tool ?? "", lastTool.sum, content);
+                }
+            }
+        }
+    }
+    return entries;
+}
+// ── Formatting ────────────────────────────────────────────────────
+/** Format a nuclear entry as a display line (for in-context injection). */
+export function formatNuclearLine(entry) {
+    const time = new Date(entry.ts).toLocaleTimeString("en-US", {
+        hour: "2-digit", minute: "2-digit", hour12: false,
+    });
+    return `#${entry.seq} ${time} ${entry.sum}`;
+}
+// ── Serialization (JSONL for history file) ────────────────────────
+/** Serialize a nuclear entry to a JSONL line. */
+export function serializeEntry(entry) {
+    return JSON.stringify(entry);
+}
+/** Deserialize a JSONL line to a nuclear entry. Returns null on parse failure. */
+export function deserializeEntry(line) {
+    try {
+        const obj = JSON.parse(line);
+        if (typeof obj.seq === "number" && typeof obj.sum === "string") {
+            return obj;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Classification helpers ────────────────────────────────────────
+/** Check if a nuclear entry represents a read-only action (should be dropped). */
+export function isReadOnly(entry) {
+    return entry.kind === "tool" && entry.tool != null && READ_ONLY_TOOLS.has(entry.tool);
+}
+// ── Internal helpers ──────────────────────────────────────────────
+function truncate(text, maxLen) {
+    const oneLine = text.replace(/\n/g, " ").trim();
+    return oneLine.length > maxLen ? oneLine.slice(0, maxLen) + "..." : oneLine;
+}
+function findLastTool(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].kind === "tool")
+            return entries[i];
+    }
+    return undefined;
+}
+function summarizeToolCall(name, args) {
+    switch (name) {
+        case "bash":
+            return `bash: ${truncate(String(args.command ?? ""), 60)}`;
+        case "user_shell":
+            return `user_shell: ${truncate(String(args.command ?? ""), 60)}`;
+        case "edit_file":
+            return `edit_file ${args.path ?? ""}`;
+        case "write_file":
+        case "write":
+            return `write_file ${args.path ?? args.file_path ?? ""}`;
+        case "read_file":
+            return `read_file ${args.path ?? args.file_path ?? ""}`;
+        case "grep":
+            return `grep "${truncate(String(args.pattern ?? ""), 30)}"`;
+        case "glob":
+            return `glob ${args.pattern ?? ""}`;
+        case "ls":
+            return `ls ${args.path ?? "."}`;
+        case "display":
+            return `display: ${truncate(String(args.command ?? ""), 60)}`;
+        default:
+            return `${name}`;
+    }
+}
+function enrichWithResult(toolName, summary, result) {
+    const lines = result.split("\n");
+    const lineCount = lines.length;
+    switch (toolName) {
+        case "bash":
+        case "user_shell": {
+            // Extract exit code from result if present
+            const exitMatch = result.match(/exit code[:\s]*(\d+)/i) ?? result.match(/exit\s+(\d+)/);
+            const exitCode = exitMatch ? exitMatch[1] : "0";
+            return `${summary} (exit ${exitCode}, ${lineCount} lines)`;
+        }
+        case "edit_file":
+        case "edit": {
+            // Try to extract +/- counts from result
+            const addMatch = result.match(/\+(\d+)/);
+            const delMatch = result.match(/-(\d+)/);
+            if (addMatch || delMatch) {
+                return `${summary} (+${addMatch?.[1] ?? 0}/-${delMatch?.[1] ?? 0})`;
+            }
+            return `${summary} (edited)`;
+        }
+        case "write_file":
+        case "write": {
+            const created = result.toLowerCase().includes("created") ? "created" : "written";
+            return `${summary} (${created}, ${lineCount} lines)`;
+        }
+        default:
+            return `${summary} (${lineCount} lines)`;
+    }
+}

package/dist/agent/system-prompt.d.ts

@@ -4,11 +4,11 @@ import type { ContextManager } from "../context-manager.js";
  * Static system prompt — identical across all queries, cacheable.
  * Contains only identity and behavioral instructions.
  */
-export declare const STATIC_SYSTEM_PROMPT = "You are an AI coding assistant embedded in agent-sh, a terminal shell.\nYou have access to the user's shell environment and can read, write, and execute code.\nYou share the user's working directory, environment variables, and shell history.\n\n# Tool Decision Guide\n\nYou have three categories of tools \u2014 choose based on who needs the output and\nwhether the command has lasting effects:\n\n**Scratchpad tools** (bash, read_file, grep, glob, ls, edit_file, write_file):\nUse these to investigate, search, read, and modify files. Output is returned\nto you for reasoning \u2014 the user doesn't see it directly.\n\n**Display** (display):\nUse this to show output to the user in their terminal. The user sees the\noutput directly, but it is NOT returned to you. Use when:\n- The user asks to see something (cat a file, git log, git diff, man page)\n- The output is for the user to read, not for you to process\n\n**Live shell** (user_shell):\nUse this to run commands with lasting effects in the user's real shell. Use for:\n- Commands that affect shell state (cd, export, source)\n- Installing packages, starting servers, running builds\n- Any command where the user wants real side effects\n- Set return_output=true only if you need to inspect the result\n\nDefault to scratchpad tools for your own investigation. Use display when the\nuser is the intended audience. Use user_shell when the command has real effects.\n\n# Tool Usage Guidelines\n- Use read_file before editing a file you haven't seen\n- Prefer edit_file over write_file for modifying existing files\n- Use grep/glob to find files before reading them\n- Keep bash commands focused; avoid long-running blocking commands\n- Always check command exit codes for errors";
+export declare const STATIC_SYSTEM_PROMPT = "You are an AI coding assistant embedded in agent-sh, a terminal shell.\nYou have access to the user's shell environment and can read, write, and execute code.\nYou share the user's working directory, environment variables, and shell history.\n\n# Tool Decision Guide\n\nYou have three categories of tools \u2014 choose based on who needs the output and\nwhether the command has lasting effects:\n\n**Scratchpad tools** (bash, read_file, grep, glob, ls, edit_file, write_file):\nUse these to investigate, search, read, and modify files. Output is returned\nto you for reasoning \u2014 the user doesn't see it directly.\n\n**Display** (display):\nUse this to show output to the user in their terminal. The user sees the\noutput directly, but it is NOT returned to you. Use when:\n- The user asks to see something (cat a file, git log, git diff, man page)\n- The output is for the user to read, not for you to process\n\n**Live shell** (user_shell):\nUse this to run complete, non-interactive commands in the user's real shell. Use for:\n- Commands that affect shell state (cd, export, source)\n- Installing packages, starting servers, running builds\n- Any command where the user wants real side effects\n- Set return_output=true only if you need to inspect the result\n\n**Terminal interaction** (terminal_read, terminal_keys):\nUse these to observe and interact with what is currently on the user's terminal screen.\n- terminal_read: see what the user sees (current screen contents, cursor position)\n- terminal_keys: send keystrokes as if the user typed them\nUse for: driving interactive programs (vim, htop, less, ssh, REPLs), answering questions\nabout what's on screen, or typing at the shell prompt when a program is already running.\nDo NOT use user_shell to interact with an already-running program \u2014 use these instead.\n\nDefault to scratchpad tools for your own investigation. Use display when the\nuser is the intended audience. Use user_shell when the command has real effects.\nUse terminal_read/terminal_keys when interacting with what's already on screen.\n\n# Interactive Overlay Sessions\n\nWhen the dynamic context includes `interactive-session: true`, the user has summoned you\nvia a hotkey overlay from inside their live terminal. They may be in the middle of using\na program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:\n- Start with terminal_read if you need to understand what's on screen.\n- Prefer terminal_keys to interact with whatever is currently running.\n- Use user_shell only for running new, standalone commands \u2014 not for interacting with\n  what's already on screen.\n- Keep responses concise \u2014 the user is in the middle of a workflow.\n\n# Tool Usage Guidelines\n- Use read_file before editing a file you haven't seen\n- Prefer edit_file over write_file for modifying existing files\n- Use grep/glob to find files before reading them\n- Keep bash commands focused; avoid long-running blocking commands\n- Always check command exit codes for errors";
 /**
  * Build the dynamic context — injected as a user message before each query.
  * Contains everything that changes: tools, shell context, conventions, cwd.
  *
  * Runs through the "agent:dynamic-context" pipe so extensions can append.
  */
-export declare function buildDynamicContext(tools: ToolDefinition[], contextManager: ContextManager): string;
+export declare function buildDynamicContext(tools: ToolDefinition[], contextManager: ContextManager, shellBudgetTokens?: number): string;

package/dist/agent/system-prompt.js

@@ -56,14 +56,34 @@ output directly, but it is NOT returned to you. Use when:
 - The output is for the user to read, not for you to process
 
 **Live shell** (user_shell):
-Use this to run commands with lasting effects in the user's real shell. Use for:
+Use this to run complete, non-interactive commands in the user's real shell. Use for:
 - Commands that affect shell state (cd, export, source)
 - Installing packages, starting servers, running builds
 - Any command where the user wants real side effects
 - Set return_output=true only if you need to inspect the result
 
+**Terminal interaction** (terminal_read, terminal_keys):
+Use these to observe and interact with what is currently on the user's terminal screen.
+- terminal_read: see what the user sees (current screen contents, cursor position)
+- terminal_keys: send keystrokes as if the user typed them
+Use for: driving interactive programs (vim, htop, less, ssh, REPLs), answering questions
+about what's on screen, or typing at the shell prompt when a program is already running.
+Do NOT use user_shell to interact with an already-running program — use these instead.
+
 Default to scratchpad tools for your own investigation. Use display when the
 user is the intended audience. Use user_shell when the command has real effects.
+Use terminal_read/terminal_keys when interacting with what's already on screen.
+
+# Interactive Overlay Sessions
+
+When the dynamic context includes \`interactive-session: true\`, the user has summoned you
+via a hotkey overlay from inside their live terminal. They may be in the middle of using
+a program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:
+- Start with terminal_read if you need to understand what's on screen.
+- Prefer terminal_keys to interact with whatever is currently running.
+- Use user_shell only for running new, standalone commands — not for interacting with
+  what's already on screen.
+- Keep responses concise — the user is in the middle of a workflow.
 
 # Tool Usage Guidelines
 - Use read_file before editing a file you haven't seen
@@ -77,7 +97,7 @@ user is the intended audience. Use user_shell when the command has real effects.
  *
  * Runs through the "agent:dynamic-context" pipe so extensions can append.
  */
-export function buildDynamicContext(tools, contextManager) {
+export function buildDynamicContext(tools, contextManager, shellBudgetTokens) {
     const sections = [];
     // Tools
     sections.push("# Available Tools\n" +
@@ -92,8 +112,9 @@ export function buildDynamicContext(tools, contextManager) {
     if (skills.length > 0) {
         sections.push(`You have access to ${skills.length} skill(s). Use the list_skills tool to see them, then read_file to load one.`);
     }
-    // Shell context
-    const shellContext = contextManager.getContext();
+    // Shell context — pass token budget converted to bytes (~4 chars/token)
+    const shellBudgetBytes = shellBudgetTokens != null ? shellBudgetTokens * 4 : undefined;
+    const shellContext = contextManager.getContext(shellBudgetBytes);
     if (shellContext) {
         sections.push(shellContext);
     }

package/dist/agent/tools/user-shell.js

@@ -8,7 +8,10 @@
 export function createUserShellTool(opts) {
     return {
         name: "user_shell",
-        description: "Run a command with lasting effects in the user's live shell (cd, export, install packages, start servers, apply changes). Output is shown directly to the user but NOT returned to you by default — set return_output=true if you need to inspect the result.",
+        description: "Run a complete, non-interactive command in the user's live shell (cd, export, install packages, start servers, git commands). " +
+            "Use this for commands that have side effects or that the user wants to see. Output is shown directly to the user but NOT returned " +
+            "to you by default — set return_output=true if you need to inspect the result. " +
+            "Do NOT use this to interact with programs that are already running in the terminal — use terminal_keys/terminal_read instead.",
         input_schema: {
             type: "object",
             properties: {

package/dist/context-manager.d.ts

@@ -1,13 +1,14 @@
 import type { EventBus } from "./event-bus.js";
+import type { HandlerRegistry } from "./utils/handler-registry.js";
 export declare class ContextManager {
     private exchanges;
     private nextId;
     private currentCwd;
     private sessionStart;
-    private pendingToolCalls;
     private firstPrompt;
     private agentShellActive;
-    constructor(bus: EventBus);
+    private handlers;
+    constructor(bus: EventBus, handlers?: HandlerRegistry);
     getCwd(): string;
     /**
      * Build the <shell_context> block for the agent prompt.

package/dist/context-manager.js

@@ -1,19 +1,18 @@
 import { getSettings } from "./settings.js";
-// Non-configurable thresholds (agent response and tool output follow shell settings)
-const AGENT_RESPONSE_TRUNCATE_THRESHOLD = 20;
-const AGENT_RESPONSE_HEAD_LINES = 15;
-const TOOL_TRUNCATE_THRESHOLD = 20;
-const TOOL_HEAD_LINES = 5;
-const TOOL_TAIL_LINES = 5;
 export class ContextManager {
     exchanges = [];
     nextId = 1;
     currentCwd;
     sessionStart;
-    pendingToolCalls = [];
     firstPrompt = true;
     agentShellActive = false; // true while user_shell command is executing
-    constructor(bus) {
+    handlers = null;
+    constructor(bus, handlers) {
+        if (handlers) {
+            this.handlers = handlers;
+            // Extensions can advise this to inject extra context (e.g. terminal buffer)
+            handlers.define("context:build-extra", () => "");
+        }
         this.currentCwd = process.cwd();
         this.sessionStart = Date.now();
         // ── Subscribe to shell events ──
@@ -37,46 +36,11 @@ export class ContextManager {
         bus.on("shell:agent-exec-start", () => { this.agentShellActive = true; });
         bus.on("shell:agent-exec-done", () => { this.agentShellActive = false; });
         // ── Subscribe to agent events ──
+        // Only track queries (as markers). Agent responses and tool outputs
+        // live exclusively in ConversationState to avoid duplication.
         bus.on("agent:query", (e) => {
-            this.pendingToolCalls = [];
             this.addExchange({ type: "agent_query", query: e.query });
         });
-        bus.on("agent:response-done", (e) => {
-            this.addExchange({
-                type: "agent_response",
-                response: e.response,
-                toolCalls: this.pendingToolCalls,
-            });
-            this.pendingToolCalls = [];
-        });
-        bus.on("agent:tool-call", (e) => {
-            // Accumulate tool calls for the agent_response summary
-            this.pendingToolCalls.push({
-                tool: e.tool,
-                args: e.args,
-                output: "",
-                exitCode: null,
-            });
-        });
-        bus.on("agent:tool-output", (e) => {
-            // Update the last pending tool call with output
-            const last = this.pendingToolCalls[this.pendingToolCalls.length - 1];
-            if (last) {
-                last.output = e.output;
-                last.exitCode = e.exitCode;
-            }
-            // Also store as a separate exchange for chronological log
-            const lines = e.output.split("\n");
-            this.addExchange({
-                type: "tool_execution",
-                tool: e.tool,
-                args: {},
-                output: e.output,
-                exitCode: e.exitCode,
-                outputLines: lines.length,
-                outputBytes: e.output.length,
-            });
-        });
     }
     // ── Public query API ──────────────────────────────────────────
     getCwd() {
@@ -225,7 +189,6 @@ export class ContextManager {
      */
     clear() {
         this.exchanges = [];
-        this.pendingToolCalls = [];
         this.firstPrompt = true;
         // Don't reset nextId — IDs should be globally unique within a session
     }
@@ -243,12 +206,7 @@ export class ContextManager {
                 const s = getSettings();
                 ex.output = truncateOutput(ex.output, s.shellTruncateThreshold, s.shellHeadLines, s.shellTailLines, ex.id);
             }
-            else if (ex.type === "agent_response") {
-                ex.response = truncateHead(ex.response, AGENT_RESPONSE_TRUNCATE_THRESHOLD, AGENT_RESPONSE_HEAD_LINES, ex.id);
-            }
-            else if (ex.type === "tool_execution") {
-                ex.output = truncateOutput(ex.output, TOOL_TRUNCATE_THRESHOLD, TOOL_HEAD_LINES, TOOL_TAIL_LINES, ex.id);
-            }
+            // agent_query has no output to truncate
         }
         // Pass 2: budget enforcement — strip output from oldest if over budget
         let totalSize = result.reduce((sum, ex) => sum + this.exchangeSize(ex), 0);
@@ -258,12 +216,6 @@ export class ContextManager {
             if (ex.type === "shell_command") {
                 ex.output = `[output omitted, use shell_recall tool to expand id ${ex.id}]`;
             }
-            else if (ex.type === "tool_execution") {
-                ex.output = `[output omitted, use shell_recall tool to expand id ${ex.id}]`;
-            }
-            else if (ex.type === "agent_response") {
-                ex.response = `[response omitted, use shell_recall tool to expand id ${ex.id}]`;
-            }
             totalSize -= before - this.exchangeSize(ex);
         }
         return result;
@@ -282,7 +234,8 @@ export class ContextManager {
             out += `- When the user asks to see, list, view, or display anything, ALWAYS use user_shell. NEVER use internal tools like ls/read/bash for display — the user won't see it.\n`;
             out += `- Only use internal tools when YOU need to reason about content silently (e.g. reading a file to answer a question about it).\n`;
             out += `- After a user_shell command, the user already saw the output. Do NOT repeat or summarize it.\n`;
-            out += `- You can browse or search session history with shell_recall.\n`;
+            out += `- You can browse or search shell history with shell_recall.\n`;
+            out += `- You can browse or search evicted conversation turns with conversation_recall.\n`;
             out += `\n`;
             this.firstPrompt = false;
         }
@@ -291,6 +244,10 @@ export class ContextManager {
         for (const ex of exchanges) {
             out += "\n" + this.formatExchangeTruncated(ex);
         }
+        // Allow extensions to inject extra context (e.g. terminal buffer snapshot)
+        const extra = this.handlers?.call("context:build-extra");
+        if (extra)
+            out += "\n" + extra + "\n";
         out += "\n</shell_context>\n";
         return out;
     }
@@ -316,25 +273,6 @@ export class ContextManager {
             }
             case "agent_query":
                 return `#${ex.id} [you] > ${ex.query}\n`;
-            case "agent_response": {
-                let s = `#${ex.id} [agent] `;
-                if (ex.response)
-                    s += ex.response.split("\n")[0] + "\n";
-                if (ex.response.includes("\n")) {
-                    const rest = ex.response.slice(ex.response.indexOf("\n") + 1);
-                    if (rest.trim())
-                        s += indent(rest, "  ") + "\n";
-                }
-                return s;
-            }
-            case "tool_execution": {
-                let s = `#${ex.id} [tool] ${ex.tool}\n`;
-                if (ex.output)
-                    s += indent(ex.output, "  ") + "\n";
-                if (ex.exitCode !== null)
-                    s += `  exit ${ex.exitCode}\n`;
-                return s;
-            }
         }
     }
     formatExchangeFull(ex) {
@@ -351,16 +289,6 @@ export class ContextManager {
             }
             case "agent_query":
                 return `#${ex.id} [you] > ${ex.query}`;
-            case "agent_response":
-                return `#${ex.id} [agent]\n${ex.response}`;
-            case "tool_execution": {
-                let s = `#${ex.id} [tool] ${ex.tool} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
-                if (ex.output)
-                    s += ex.output + "\n";
-                if (ex.exitCode !== null)
-                    s += `exit ${ex.exitCode}\n`;
-                return s;
-            }
         }
     }
     exchangeOneLiner(ex) {
@@ -371,12 +299,6 @@ export class ContextManager {
             }
             case "agent_query":
                 return `#${ex.id} query: ${ex.query}`;
-            case "agent_response": {
-                const preview = ex.response.split("\n")[0]?.slice(0, 80) ?? "";
-                return `#${ex.id} agent: ${preview}${ex.response.length > 80 ? "..." : ""}`;
-            }
-            case "tool_execution":
-                return `#${ex.id} tool: ${ex.tool} (${ex.outputLines} lines, exit ${ex.exitCode ?? "?"})`;
         }
     }
     exchangeSearchText(ex) {
@@ -385,10 +307,6 @@ export class ContextManager {
                 return `${ex.command}\n${ex.output}`;
             case "agent_query":
                 return ex.query;
-            case "agent_response":
-                return ex.response;
-            case "tool_execution":
-                return `${ex.tool}\n${ex.output}`;
         }
     }
     exchangeSize(ex) {
@@ -397,10 +315,6 @@ export class ContextManager {
                 return ex.command.length + ex.output.length;
             case "agent_query":
                 return ex.query.length;
-            case "agent_response":
-                return ex.response.length;
-            case "tool_execution":
-                return ex.tool.length + ex.output.length;
         }
     }
 }
@@ -416,15 +330,6 @@ function truncateOutput(text, threshold, headLines, tailLines, id) {
         ...lines.slice(-tailLines),
     ].join("\n");
 }
-function truncateHead(text, threshold, headLines, id) {
-    const lines = text.split("\n");
-    if (lines.length <= threshold)
-        return text;
-    return [
-        ...lines.slice(0, headLines),
-        `[... truncated, use shell_recall tool with expand and id ${id} for full response ...]`,
-    ].join("\n");
-}
 function indent(text, prefix) {
     return text
         .split("\n")

package/dist/core.js

@@ -25,6 +25,8 @@ import * as streamTransform from "./utils/stream-transform.js";
 import * as settingsMod from "./settings.js";
 import { resolveProvider, getProviderNames } from "./settings.js";
 import { HandlerRegistry } from "./utils/handler-registry.js";
+import { TerminalBuffer } from "./utils/terminal-buffer.js";
+import { FloatingPanel } from "./utils/floating-panel.js";
 // Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
@@ -33,7 +35,7 @@ export { LlmClient } from "./utils/llm-client.js";
 export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
-    const contextManager = new ContextManager(bus);
+    const contextManager = new ContextManager(bus, handlers);
     // ── Resolve provider ─────────────────────────────────────────
     const settings = settingsMod.getSettings();
     let activeProvider = null;
@@ -173,6 +175,20 @@ export function createCore(config) {
             supportsReasoningEffort: p.supportsReasoningEffort,
             modelCapabilities: caps.size > 0 ? caps : undefined,
         });
+        // Push registered models into the agent loop so they appear in
+        // autocomplete and are selectable via /model.
+        const addModes = modelIds.map((m) => {
+            const mc = caps.get(m);
+            return {
+                model: m,
+                provider: p.id,
+                providerConfig: { apiKey: p.apiKey ?? "", baseURL: p.baseURL },
+                contextWindow: mc?.contextWindow,
+                reasoning: mc?.reasoning,
+                supportsReasoningEffort: p.supportsReasoningEffort,
+            };
+        });
+        bus.emit("config:add-modes", { modes: addModes });
     });
     bus.on("config:switch-provider", ({ provider: name }) => {
         const p = providerRegistry.get(name);
@@ -216,6 +232,14 @@ export function createCore(config) {
         bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
         bus.emit("config:changed", {});
     });
+    // ── Lazy singleton terminal buffer ──────────────────────────
+    let terminalBufferSingleton; // undefined = not yet created
+    const getTerminalBuffer = () => {
+        if (terminalBufferSingleton !== undefined)
+            return terminalBufferSingleton;
+        terminalBufferSingleton = TerminalBuffer.createWired(bus);
+        return terminalBufferSingleton;
+    };
     return {
         bus,
         contextManager,
@@ -292,6 +316,11 @@ export function createCore(config) {
                 define: (name, fn) => handlers.define(name, fn),
                 advise: (name, wrapper) => handlers.advise(name, wrapper),
                 call: (name, ...args) => handlers.call(name, ...args),
+                get terminalBuffer() { return getTerminalBuffer(); },
+                createFloatingPanel: (config) => {
+                    const tb = config.dimBackground !== false ? getTerminalBuffer() : null;
+                    return new FloatingPanel(bus, { ...config, terminalBuffer: tb ?? undefined });
+                },
             };
         },
         kill() {

package/dist/event-bus.d.ts

@@ -22,6 +22,25 @@ export interface ShellEvents {
     };
     "shell:agent-exec-start": Record<string, never>;
     "shell:agent-exec-done": Record<string, never>;
+    "shell:pty-data": {
+        raw: string;
+    };
+    "shell:pty-write": {
+        data: string;
+    };
+    "shell:pty-resize": {
+        cols: number;
+        rows: number;
+    };
+    "shell:buffer-request": Record<string, never>;
+    "shell:buffer-snapshot": {
+        text: string;
+        altScreen: boolean;
+        cursor: {
+            x: number;
+            y: number;
+        };
+    };
     "agent:submit": {
         query: string;
     };
@@ -123,6 +142,14 @@ export interface ShellEvents {
     "input:keypress": {
         key: string;
     };
+    "input:intercept": {
+        data: string;
+        consumed: boolean;
+    };
+    "shell:stdout-hold": Record<string, never>;
+    "shell:stdout-release": Record<string, never>;
+    "shell:stdout-show": Record<string, never>;
+    "shell:stdout-hide": Record<string, never>;
     "agent:terminal-intercept": {
         command: string;
         cwd: string;
@@ -148,6 +175,13 @@ export interface ShellEvents {
         contextWindow?: number;
     };
     "agent:reset-session": Record<string, never>;
+    "agent:compact-request": Record<string, never>;
+    "context:get-stats": {
+        activeTokens: number;
+        nuclearEntries: number;
+        recallArchiveSize: number;
+        budgetTokens: number;
+    };
     "agent:register-backend": {
         name: string;
         kill: () => void;
@@ -187,6 +221,9 @@ export interface ShellEvents {
     "config:set-modes": {
         modes: AgentMode[];
     };
+    "config:add-modes": {
+        modes: AgentMode[];
+    };
     "provider:register": {
         id: string;
         apiKey?: string;

package/dist/extensions/overlay-agent.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in overlay agent.
+ *
+ * Provides a hotkey (Ctrl+\) to summon the agent from anywhere — even
+ * inside vim, htop, or ssh. Composites a floating response box on top
+ * of the current terminal content.
+ *
+ * Rendering reuses the shared tui:render-* handlers so that extensions
+ * advising those handlers affect both the main TUI and the overlay.
+ *
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate(ctx: ExtensionContext): void;