agent-sh 0.6.0 → 0.8.0

package/dist/extensions/overlay-agent.js

@@ -0,0 +1,147 @@
+import { MarkdownRenderer } from "../utils/markdown.js";
+import { palette as p } from "../utils/palette.js";
+import { renderToolCall, formatElapsed, } from "../utils/tool-display.js";
+export default function activate(ctx) {
+    const { bus, advise, call, createFloatingPanel } = ctx;
+    const panel = createFloatingPanel({
+        trigger: "\x1c", // Ctrl+\
+        dimBackground: true,
+    });
+    // Suppress TUI renderer when overlay owns agent output
+    advise("tui:should-render-agent", (next) => {
+        return panel.active ? false : next();
+    });
+    // Signal interactive overlay mode in dynamic context
+    advise("dynamic-context:build", (next) => {
+        const base = next();
+        if (!panel.active)
+            return base;
+        return base + "\ninteractive-session: true\n";
+    });
+    // ── Conversation state (persists across hide/show) ─────────
+    const messages = [];
+    let renderer = null;
+    let currentAssistantMsg = null;
+    // ── Tool state ─────────────────────────────────────────────
+    let toolStartTime = 0;
+    function getContentWidth() {
+        return panel.computeGeometry().contentW;
+    }
+    /** Rebuild panel content from full message history. */
+    function rebuildContent() {
+        panel.clearContent();
+        for (const msg of messages) {
+            for (const line of msg.lines) {
+                panel.appendLine(line);
+            }
+            panel.appendLine("");
+        }
+    }
+    /** Append a line to current assistant message and panel (if visible). */
+    function appendLine(line) {
+        currentAssistantMsg?.lines.push(line);
+        if (panel.visible)
+            panel.appendLine(line);
+    }
+    function drainRenderer() {
+        if (!renderer)
+            return;
+        for (const line of renderer.drainLines()) {
+            appendLine(line);
+        }
+    }
+    function flushRenderer() {
+        if (!renderer)
+            return;
+        renderer.flush();
+        drainRenderer();
+    }
+    function startAssistantMessage() {
+        flushRenderer();
+        currentAssistantMsg = { role: "assistant", lines: [] };
+        messages.push(currentAssistantMsg);
+        renderer = new MarkdownRenderer(getContentWidth());
+    }
+    function finalizeAssistantMessage() {
+        flushRenderer();
+        renderer = null;
+        currentAssistantMsg = null;
+    }
+    // ── Panel lifecycle ────────────────────────────────────────
+    panel.handlers.advise("panel:submit", (_next, query) => {
+        messages.push({
+            role: "user",
+            lines: [`${p.accent}${p.bold}❯${p.reset} ${query}`],
+        });
+        panel.setActive();
+        rebuildContent();
+        startAssistantMessage();
+        bus.emit("agent:submit", { query });
+    });
+    panel.handlers.advise("panel:show", (_next) => {
+        rebuildContent();
+        if (renderer)
+            drainRenderer();
+    });
+    // ── Stream agent response into panel ───────────────────────
+    bus.on("agent:response-chunk", (e) => {
+        if (!panel.active)
+            return;
+        if (!currentAssistantMsg)
+            startAssistantMessage();
+        for (const block of e.blocks) {
+            if (block.type === "text" && block.text) {
+                renderer.push(block.text);
+                drainRenderer();
+            }
+            else if (block.type === "code-block") {
+                flushRenderer();
+                // Reuse the shared code-block handler
+                call("render:code-block", block.language, block.code, getContentWidth());
+            }
+        }
+    });
+    // Capture lines emitted by render:code-block into the overlay
+    advise("render:code-block", (next, language, code, width) => {
+        if (!panel.active)
+            return next(language, code, width);
+        // Render code block as indented dim lines for the overlay
+        const label = language ? `${p.dim}${language}${p.reset}` : "";
+        if (label)
+            appendLine(label);
+        for (const codeLine of code.split("\n")) {
+            appendLine(`  ${p.dim}${codeLine}${p.reset}`);
+        }
+    });
+    bus.on("agent:tool-started", (e) => {
+        if (!panel.active)
+            return;
+        if (!currentAssistantMsg)
+            startAssistantMessage();
+        flushRenderer();
+        toolStartTime = Date.now();
+        const lines = renderToolCall({
+            title: e.title,
+            kind: e.kind,
+            icon: e.icon,
+            locations: e.locations,
+            rawInput: e.rawInput,
+            displayDetail: e.displayDetail,
+        }, getContentWidth());
+        for (const line of lines)
+            appendLine(line);
+    });
+    bus.on("agent:tool-completed", (e) => {
+        if (!panel.active)
+            return;
+        const elapsed = toolStartTime ? formatElapsed(Date.now() - toolStartTime) : "";
+        const mark = call("tui:render-tool-complete", e.exitCode, elapsed, undefined);
+        appendLine(`  ${mark}`);
+    });
+    bus.on("agent:processing-done", () => {
+        if (!panel.active)
+            return;
+        finalizeAssistantMessage();
+        panel.setDone();
+    });
+}

package/dist/extensions/slash-commands.js

@@ -75,6 +75,34 @@ export default function activate({ bus, contextManager }) {
             }
         },
     });
+    register({
+        name: "/compact",
+        description: "Compact conversation (move full content to nuclear summaries)",
+        handler: () => {
+            bus.emit("agent:compact-request", {});
+        },
+    });
+    register({
+        name: "/context",
+        description: "Show context budget usage",
+        handler: () => {
+            const stats = bus.emitPipe("context:get-stats", {
+                activeTokens: 0,
+                nuclearEntries: 0,
+                recallArchiveSize: 0,
+                budgetTokens: 0,
+            });
+            const pct = stats.budgetTokens > 0
+                ? Math.round((stats.activeTokens / stats.budgetTokens) * 100)
+                : 0;
+            const lines = [
+                `Active context: ~${stats.activeTokens.toLocaleString()} tokens / ${stats.budgetTokens.toLocaleString()} budget (${pct}%)`,
+                `Nuclear entries: ${stats.nuclearEntries} in-context`,
+                `Recall archive: ${stats.recallArchiveSize} entries`,
+            ];
+            bus.emit("ui:info", { message: lines.join("\n") });
+        },
+    });
     // ── Extension registration ────────────────────────────────────
     bus.on("command:register", (cmd) => {
         register(cmd);

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

@@ -0,0 +1,14 @@
+/**
+ * Built-in terminal buffer extension.
+ *
+ * Registers two agent tools:
+ *   - terminal_read: get the current screen contents + cursor position
+ *   - terminal_keys: send raw keystrokes into the user's live PTY
+ *
+ * Together these let the agent operate inside interactive programs
+ * (vim, htop, less, etc.) by reading the screen and typing keys.
+ *
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ */
+import type { ExtensionContext } from "../types.js";
+export default function activate({ bus, terminalBuffer: tb, registerTool }: ExtensionContext): void;

package/dist/extensions/terminal-buffer.js

@@ -0,0 +1,125 @@
+/** Interpret C-style escape sequences (e.g. \r → CR, \x1b → ESC). */
+function interpretEscapes(str) {
+    return str.replace(/\\(x[0-9a-fA-F]{2}|r|n|t|\\|0)/g, (_, seq) => {
+        if (seq === "r")
+            return "\r";
+        if (seq === "n")
+            return "\n";
+        if (seq === "t")
+            return "\t";
+        if (seq === "\\")
+            return "\\";
+        if (seq === "0")
+            return "\0";
+        if (seq.startsWith("x"))
+            return String.fromCharCode(parseInt(seq.slice(1), 16));
+        return seq;
+    });
+}
+function settle(ms = 100) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export default function activate({ bus, terminalBuffer: tb, registerTool }) {
+    if (!tb)
+        return; // @xterm/headless not installed
+    registerTool({
+        name: "terminal_read",
+        description: "Read what is currently visible on the user's terminal screen. Returns clean text (ANSI stripped) " +
+            "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
+            "Use this to observe what the user sees — helpful for answering questions about terminal output, " +
+            "diagnosing errors on screen, or checking state before/after sending keystrokes with terminal_keys.",
+        input_schema: {
+            type: "object",
+            properties: {},
+        },
+        showOutput: true,
+        getDisplayInfo: () => ({
+            kind: "read",
+            icon: "⊞",
+            locations: [],
+        }),
+        async execute() {
+            const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+            const info = [
+                altScreen ? "mode: alternate screen" : "mode: normal",
+                `cursor: row=${cursorY} col=${cursorX}`,
+            ].join(", ");
+            return {
+                content: `[${info}]\n\n${text}`,
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    });
+    registerTool({
+        name: "terminal_keys",
+        description: "Send keystrokes directly into the user's live terminal PTY, as if the user typed them. " +
+            "Use this to interact with programs already running in the terminal (vim, htop, less, ssh, REPLs, etc.) " +
+            "or to type commands at the shell prompt. Do NOT use user_shell for this — user_shell runs a new " +
+            "command in a subshell, while terminal_keys types into whatever is currently on screen.\n\n" +
+            "Escape sequences for special keys:\n" +
+            "  - Escape: \\x1b\n" +
+            "  - Enter/Return: \\r\n" +
+            "  - Tab: \\t\n" +
+            "  - Ctrl+C: \\x03\n" +
+            "  - Ctrl+D: \\x04\n" +
+            "  - Ctrl+Z: \\x1a\n" +
+            "  - Arrow keys: \\x1b[A (up), \\x1b[B (down), \\x1b[C (right), \\x1b[D (left)\n" +
+            "  - Backspace: \\x7f\n\n" +
+            "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\" (Escape, :q!, Enter).\n" +
+            "Always call terminal_read after sending keys to verify the result.",
+        input_schema: {
+            type: "object",
+            properties: {
+                keys: {
+                    type: "string",
+                    description: "The keystrokes to send. Use \\x1b for Escape, \\r for Enter, \\t for Tab, " +
+                        "\\x03 for Ctrl+C, etc. Regular characters are sent as-is.",
+                },
+                settle_ms: {
+                    type: "number",
+                    description: "Milliseconds to wait after sending keys for the terminal to settle before " +
+                        "returning (default: 150). Increase for slow programs.",
+                },
+            },
+            required: ["keys"],
+        },
+        showOutput: false,
+        getDisplayInfo: () => ({
+            kind: "execute",
+            icon: "⌨",
+            locations: [],
+        }),
+        formatCall: (args) => {
+            const keys = args.keys;
+            return keys
+                .replace(/\\x1b|\x1b/g, "ESC")
+                .replace(/\\r|\r/g, "⏎")
+                .replace(/\\n|\n/g, "↵")
+                .replace(/\\t|\t/g, "TAB")
+                .replace(/\\x03|\x03/g, "^C")
+                .replace(/\\x04|\x04/g, "^D")
+                .replace(/\\x7f|\x7f/g, "BS");
+        },
+        async execute(args) {
+            const raw = args.keys;
+            const keys = interpretEscapes(raw);
+            const settleMs = args.settle_ms ?? 150;
+            bus.emit("shell:stdout-show", {});
+            process.stdout.write("\n");
+            bus.emit("shell:pty-write", { data: keys });
+            await settle(settleMs);
+            bus.emit("shell:stdout-hide", {});
+            const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+            const info = [
+                altScreen ? "mode: alternate screen" : "mode: normal",
+                `cursor: row=${cursorY} col=${cursorX}`,
+            ].join(", ");
+            return {
+                content: `Keys sent. Screen after:\n[${info}]\n\n${text}`,
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    });
+}