agent-sh 0.5.0 → 0.7.0

package/dist/utils/output-writer.js

@@ -5,9 +5,25 @@
  * process.stdout.write directly.  This enables testing (BufferWriter),
  * alternative frontends, and a single point of control for output.
  */
+/** Simple ref-counted counter. Increment/decrement never goes below zero. */
+export class RefCounter {
+    count = 0;
+    increment() { this.count++; }
+    decrement() { this.count = Math.max(0, this.count - 1); }
+    reset() { this.count = 0; }
+    get active() { return this.count > 0; }
+    get value() { return this.count; }
+}
 /** Default writer that forwards to process.stdout. */
 export class StdoutWriter {
+    /** When > 0, all writes are silently dropped. Ref-counted. */
+    _hold = new RefCounter();
+    hold() { this._hold.increment(); }
+    release() { this._hold.decrement(); }
+    get held() { return this._hold.active; }
     write(text) {
+        if (this._hold.active)
+            return;
         if (process.stdout.writable) {
             try {
                 process.stdout.write(text);

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

@@ -0,0 +1,65 @@
+import type { EventBus } from "../event-bus.js";
+/** Check if @xterm/headless is installed without loading it. */
+export declare function isXtermAvailable(): boolean;
+export interface TerminalBufferConfig {
+    /** Terminal width in columns. Default: process.stdout.columns || 80. */
+    cols?: number;
+    /** Terminal height in rows. Default: process.stdout.rows || 24. */
+    rows?: number;
+    /** Scrollback buffer size. Default: 200. */
+    scrollback?: number;
+}
+export interface ScreenSnapshot {
+    /** Clean text with ANSI sequences stripped. */
+    text: string;
+    /** Whether the alternate screen buffer is active (vim, htop, etc.). */
+    altScreen: boolean;
+    /** Cursor position. */
+    cursorX: number;
+    cursorY: number;
+}
+/**
+ * Format a screen snapshot as an XML context block for agent injection.
+ * Trims, caps to `maxLines` (from the bottom), and wraps in `<terminal_buffer>`.
+ * Returns the combined context string (baseContext + section), or just
+ * baseContext if the screen is empty.
+ */
+export declare function formatScreenContext(screen: ScreenSnapshot, maxLines?: number, baseContext?: string): string;
+export declare class TerminalBuffer {
+    private readonly term;
+    private readonly serializeAddon;
+    private constructor();
+    /**
+     * Create a new TerminalBuffer. Returns null if xterm is not installed.
+     */
+    static create(config?: TerminalBufferConfig): TerminalBuffer | null;
+    /**
+     * Create a TerminalBuffer and wire it to a bus's shell:pty-data event.
+     * Returns null if xterm is not installed.
+     */
+    static createWired(bus: EventBus, config?: TerminalBufferConfig): TerminalBuffer | null;
+    /** Write raw data into the virtual terminal. */
+    write(data: string): void;
+    /** Get the raw serialized terminal output (includes ANSI sequences). */
+    serialize(): string;
+    /** Read clean screen text with metadata. */
+    readScreen(): ScreenSnapshot;
+    /**
+     * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
+     * Clean text only (ANSI stripped).  Reads from the active buffer's
+     * viewport (not scrollback), so it works correctly on both the normal
+     * and alternate screen buffers.
+     */
+    getScreenLines(rows?: number): string[];
+    /** Read visible viewport lines from a buffer. */
+    private readViewportLines;
+    /** Get cursor position. */
+    getCursor(): {
+        x: number;
+        y: number;
+    };
+    /** Resize the virtual terminal. */
+    resize(cols: number, rows: number): void;
+    /** Whether the alternate screen buffer is active. */
+    get altScreen(): boolean;
+}

package/dist/utils/terminal-buffer.js

@@ -0,0 +1,166 @@
+/**
+ * Headless terminal buffer backed by xterm.js.
+ *
+ * Provides accurate terminal screen capture — correctly handles ANSI
+ * codes, cursor movement, alternate screen (vim/htop), line wrapping,
+ * and scrollback.
+ *
+ * Used by:
+ *   - floating-panel.ts: composited overlay rendering + screen restore
+ *   - terminal-buffer extension: agent tools (terminal_read, terminal_keys)
+ *   - Any extension needing a virtual terminal snapshot
+ *
+ * The xterm dependency is loaded lazily on first use. If @xterm/headless
+ * is not installed, create() returns null.
+ *
+ * Install (optional):
+ *   npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ */
+import { createRequire } from "module";
+// ── Lazy xterm loader ───────────────────────────────────────────
+const require = createRequire(import.meta.url);
+let loadAttempted = false;
+let available = false;
+let TerminalCtor;
+let SerializeAddonCtor;
+function ensureXterm() {
+    if (loadAttempted)
+        return available;
+    loadAttempted = true;
+    try {
+        TerminalCtor = require("@xterm/headless").Terminal;
+        SerializeAddonCtor = require("@xterm/addon-serialize").SerializeAddon;
+        available = true;
+    }
+    catch {
+        available = false;
+    }
+    return available;
+}
+/** Check if @xterm/headless is installed without loading it. */
+export function isXtermAvailable() {
+    return ensureXterm();
+}
+/**
+ * Format a screen snapshot as an XML context block for agent injection.
+ * Trims, caps to `maxLines` (from the bottom), and wraps in `<terminal_buffer>`.
+ * Returns the combined context string (baseContext + section), or just
+ * baseContext if the screen is empty.
+ */
+export function formatScreenContext(screen, maxLines = 80, baseContext) {
+    const trimmed = screen.text.trim();
+    if (!trimmed)
+        return baseContext ?? "";
+    const lines = trimmed.split("\n");
+    const capped = lines.length > maxLines
+        ? lines.slice(-maxLines).join("\n")
+        : trimmed;
+    const header = screen.altScreen
+        ? "<terminal_buffer mode=\"alternate\">"
+        : "<terminal_buffer>";
+    const section = `${header}\n${capped}\n</terminal_buffer>`;
+    return baseContext ? baseContext + "\n" + section : section;
+}
+// ── TerminalBuffer ──────────────────────────────────────────────
+export class TerminalBuffer {
+    term;
+    serializeAddon;
+    constructor(term, serialize) {
+        this.term = term;
+        this.serializeAddon = serialize;
+    }
+    /**
+     * Create a new TerminalBuffer. Returns null if xterm is not installed.
+     */
+    static create(config) {
+        if (!ensureXterm())
+            return null;
+        const cols = config?.cols ?? (process.stdout.columns || 80);
+        const rows = config?.rows ?? (process.stdout.rows || 24);
+        const scrollback = config?.scrollback ?? 200;
+        const term = new TerminalCtor({ cols, rows, allowProposedApi: true, scrollback });
+        const serialize = new SerializeAddonCtor();
+        term.loadAddon(serialize);
+        return new TerminalBuffer(term, serialize);
+    }
+    /**
+     * Create a TerminalBuffer and wire it to a bus's shell:pty-data event.
+     * Returns null if xterm is not installed.
+     */
+    static createWired(bus, config) {
+        const tb = TerminalBuffer.create(config);
+        if (!tb)
+            return null;
+        // Buffer PTY data and drip-feed to xterm in the background.
+        // Synchronous term.write() in the pty-data handler introduces enough
+        // latency to change PTY read coalescing, causing visual artifacts.
+        let pending = "";
+        bus.on("shell:pty-data", ({ raw }) => { pending += raw; });
+        setInterval(() => {
+            if (pending) {
+                const d = pending;
+                pending = "";
+                tb.write(d);
+            }
+        }, 50);
+        process.stdout.on("resize", () => {
+            tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
+        });
+        return tb;
+    }
+    /** Write raw data into the virtual terminal. */
+    write(data) {
+        this.term.write(data);
+    }
+    /** Get the raw serialized terminal output (includes ANSI sequences). */
+    serialize() {
+        return this.serializeAddon.serialize();
+    }
+    /** Read clean screen text with metadata. */
+    readScreen() {
+        const buf = this.term.buffer.active;
+        const lines = this.readViewportLines(buf);
+        return {
+            text: lines.join("\n"),
+            altScreen: buf.type === "alternate",
+            cursorX: buf.cursorX,
+            cursorY: buf.cursorY,
+        };
+    }
+    /**
+     * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
+     * Clean text only (ANSI stripped).  Reads from the active buffer's
+     * viewport (not scrollback), so it works correctly on both the normal
+     * and alternate screen buffers.
+     */
+    getScreenLines(rows) {
+        const targetRows = rows ?? (process.stdout.rows || 24);
+        return this.readViewportLines(this.term.buffer.active, targetRows);
+    }
+    /** Read visible viewport lines from a buffer. */
+    readViewportLines(buf, rows) {
+        const targetRows = rows ?? buf.length;
+        const base = buf.baseY ?? 0;
+        const lines = [];
+        for (let y = 0; y < targetRows; y++) {
+            const line = buf.getLine(base + y);
+            lines.push(line ? line.translateToString(true) : "");
+        }
+        return lines;
+    }
+    /** Get cursor position. */
+    getCursor() {
+        return {
+            x: this.term.buffer.active.cursorX,
+            y: this.term.buffer.active.cursorY,
+        };
+    }
+    /** Resize the virtual terminal. */
+    resize(cols, rows) {
+        this.term.resize(cols, rows);
+    }
+    /** Whether the alternate screen buffer is active. */
+    get altScreen() {
+        return this.term.buffer.active.type === "alternate";
+    }
+}

package/dist/utils/tool-display.d.ts

@@ -6,6 +6,8 @@ export interface ToolCallRender {
     command?: string;
     /** Tool kind from ACP (read, edit, execute, search, etc.). */
     kind?: string;
+    /** Custom icon character — when set, tool name is omitted (icon implies tool). */
+    icon?: string;
     /** File locations affected by the tool call. */
     locations?: {
         path: string;
@@ -13,6 +15,8 @@ export interface ToolCallRender {
     }[];
     /** Raw input parameters sent to the tool. */
     rawInput?: unknown;
+    /** Pre-formatted display detail from tool's formatCall(). Takes precedence over rawInput extraction. */
+    displayDetail?: string;
 }
 export interface ToolResultRender {
     exitCode: number | null;

package/dist/utils/tool-display.js

@@ -39,6 +39,7 @@ const KIND_ICONS = {
     move: "↗",
     search: "⌕",
     execute: "▶",
+    display: "◇",
     think: "◇",
     fetch: "↓",
     switch_mode: "⇄",
@@ -49,7 +50,10 @@ function kindIcon(kind) {
 // ── Tool call rendering ──────────────────────────────────────────
 export function renderToolCall(tool, width) {
     const mode = selectToolDisplayMode(width);
-    const icon = kindIcon(tool.kind);
+    const icon = tool.icon ?? kindIcon(tool.kind);
+    // If the tool registered a custom icon, it's self-describing — omit the name.
+    // Otherwise, include the tool name so the user knows what ran.
+    const hasCustomIcon = !!tool.icon;
     if (mode === "summary") {
         const text = truncateVisible(`${icon} ${tool.title}`, width);
         return [`${p.warning}${text}${p.reset}`];
@@ -58,7 +62,10 @@ export function renderToolCall(tool, width) {
     // Build a compact detail string to append after the title
     let detail = "";
     const cwd = process.cwd();
-    if (mode === "full") {
+    if (mode === "full" && tool.displayDetail) {
+        detail = tool.displayDetail;
+    }
+    else if (mode === "full") {
         if (tool.command) {
             detail = `$ ${tool.command}`;
         }
@@ -97,14 +104,24 @@ export function renderToolCall(tool, width) {
             }
         }
     }
-    // Render as single line: icon + detail (icon implies the tool type)
-    // Falls back to icon + title when no detail is available
+    // Render as single line: icon + kind + detail
     const maxDetailW = Math.max(1, width - 4);
-    if (detail) {
+    if (detail && hasCustomIcon && tool.kind) {
+        const combined = `${tool.kind} ${detail}`;
+        const truncated = combined.length > maxDetailW ? combined.slice(0, maxDetailW - 1) + "…" : combined;
+        lines.push(`${p.warning}${icon}${p.reset} ${p.dim}${truncated}${p.reset}`);
+    }
+    else if (detail && hasCustomIcon) {
         if (detail.length > maxDetailW)
             detail = detail.slice(0, maxDetailW - 1) + "…";
         lines.push(`${p.warning}${icon}${p.reset} ${p.dim}${detail}${p.reset}`);
     }
+    else if (detail) {
+        const prefix = `${tool.title}: `;
+        const combined = prefix + detail;
+        const truncated = combined.length > maxDetailW ? combined.slice(0, maxDetailW - 1) + "…" : combined;
+        lines.push(`${p.warning}${icon}${p.reset} ${p.dim}${truncated}${p.reset}`);
+    }
     else {
         lines.push(`${p.warning}${icon} ${tool.title}${p.reset}`);
     }

package/examples/extensions/claude-code-bridge/index.ts

@@ -30,8 +30,8 @@ function createUserShellTool(bus: EventBus) {
 
   return tool(
     "user_shell",
-    "Run a command in the user's live shell (visible in terminal). " +
-    "Use for cd, export, source, or commands the user wants to see. " +
+    "Run a command with lasting effects in the user's live shell (cd, export, " +
+    "install packages, start servers) or show output the user wants to see. " +
     "Set return_output=true only if you need to inspect the result.",
     {
       command: z.string().describe("Command to execute in user's shell"),
@@ -71,12 +71,8 @@ export default function activate(ctx: ExtensionContext): void {
   const listeners: Array<{ event: string; fn: Function }> = [];
 
   const wireListeners = () => {
-    const onSubmit = async ({ query: userQuery, modeInstruction, modeLabel }: any) => {
-      const prompt = modeInstruction
-        ? `${modeInstruction}\n${userQuery}`
-        : userQuery;
-
-      bus.emit("agent:query", { query: userQuery, modeLabel });
+    const onSubmit = async ({ query: userQuery }: any) => {
+      bus.emit("agent:query", { query: userQuery });
       bus.emit("agent:processing-start", {});
 
       let fullResponseText = "";
@@ -84,7 +80,7 @@ export default function activate(ctx: ExtensionContext): void {
 
       try {
         activeQuery = query({
-          prompt,
+          prompt: userQuery,
           options: {
             cwd: process.cwd(),
             systemPrompt: {
@@ -92,9 +88,9 @@ export default function activate(ctx: ExtensionContext): void {
               preset: "claude_code",
               append:
                 "You are running inside agent-sh, a terminal wrapper.\n" +
-                "EXECUTE mode ('>'): Use your standard tools. Do NOT use user_shell.\n" +
-                "HELP mode ('?'): Run the command via mcp__agent-sh__user_shell. Just run it, no explanation.\n" +
-                "Each prompt includes a per-query mode instruction — follow it.",
+                "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.\n" +
+                "Use mcp__agent-sh__user_shell to run commands in the user's live shell when they ask to see output or need lasting effects (cd, install, start servers).\n" +
+                "Default to standard tools. Use user_shell when the user is the intended audience for the output or the command has real effects.",
             },
             mcpServers: { "agent-sh": shellServer },
             allowedTools: [

package/examples/extensions/overlay-agent.ts

@@ -0,0 +1,70 @@
+/**
+ * Overlay agent extension.
+ *
+ * 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.
+ *
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/overlay-agent.ts
+ *
+ *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
+ *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
+ */
+import type { ExtensionContext } from "agent-sh/types";
+import { formatScreenContext } from "agent-sh/utils/terminal-buffer.js";
+
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+export default function activate({ bus, advise, createFloatingPanel, terminalBuffer }: ExtensionContext): void {
+  const panel = createFloatingPanel({
+    trigger: "\x1c", // Ctrl+\
+    dimBackground: true,
+    autoDismissMs: 2000,
+  });
+
+  // ── Inject terminal buffer into agent context ──────────────
+  if (terminalBuffer) {
+    advise("context:build-extra", (next: () => string) =>
+      formatScreenContext(terminalBuffer.readScreen(), 80, next()),
+    );
+  }
+
+  // ── Panel lifecycle ────────────────────────────────────────
+  panel.handlers.advise("panel:submit", (_next, query: string) => {
+    panel.setActive();
+    panel.appendLine(`${CYAN}${BOLD}❯${RESET} ${query}`);
+    panel.appendLine("");
+    bus.emit("agent:submit", { query });
+  });
+
+  // ── Stream agent response into panel ───────────────────────
+  bus.on("agent:response-chunk", (e) => {
+    if (!panel.active) return;
+    for (const block of e.blocks) {
+      if (block.type === "text" && block.text) {
+        panel.appendText(block.text);
+      }
+    }
+  });
+
+  bus.on("agent:tool-started", (e) => {
+    if (!panel.active) return;
+    panel.appendLine(`▶ ${e.title}${e.displayDetail ? " " + e.displayDetail : ""}`);
+  });
+
+  bus.on("agent:tool-completed", (e) => {
+    if (!panel.active) return;
+    const mark = e.exitCode === 0 ? " ✓" : ` ✗ exit ${e.exitCode}`;
+    panel.updateLastLine((line) => line + mark);
+  });
+
+  bus.on("agent:processing-done", () => {
+    if (!panel.active) return;
+    panel.setDone();
+  });
+}

package/examples/extensions/pi-bridge/index.ts

@@ -48,17 +48,16 @@ function createUserShellToolDef(bus: EventBus) {
     name: "user_shell",
     label: "user_shell",
     description:
-      "Run a command in the user's live shell (visible in terminal). " +
-      "Use for cd, export, source, or commands the user wants to see. " +
+      "Run a command with lasting effects in the user's live shell (cd, export, " +
+      "install packages, start servers) or show output the user wants to see. " +
       "Output is shown directly to the user. Set return_output=true only " +
       "if you need to inspect the result.",
-    promptSnippet: "Execute commands in the user's live terminal (PTY). Use in HELP mode.",
+    promptSnippet: "Execute commands in the user's live terminal (PTY).",
     promptGuidelines: [
-      "You are running inside agent-sh, a terminal wrapper with two interaction modes.",
-      "EXECUTE mode (triggered by '>'): Use your standard tools (bash, file ops). Do NOT use user_shell.",
-      "HELP mode (triggered by '?'): Run the command via user_shell. Do not explain or confirm — just run it.",
-      "Each prompt includes a per-query mode instruction — follow it.",
-      "user_shell executes in the user's actual shell (their aliases, env vars, cwd). Use bash for background work.",
+      "You are running inside agent-sh, a terminal wrapper.",
+      "Use your standard tools (bash, file ops) for investigation — output goes to you, not the user.",
+      "Use user_shell to run commands in the user's live shell when they ask to see output or need lasting effects (cd, install, start servers).",
+      "Default to standard tools. Use user_shell when the user is the intended audience for the output or the command has real effects.",
     ],
     parameters: schema,
 
@@ -203,7 +202,7 @@ export default function activate(ctx: ExtensionContext): void {
   const listeners: Array<{ event: string; fn: Function }> = [];
 
   const wireListeners = () => {
-    const onSubmit = async ({ query, modeInstruction, modeLabel }: any) => {
+    const onSubmit = async ({ query }: any) => {
       if (!session) {
         bus.emit("agent:error", {
           message: booting ? "pi is still starting up..." : "pi session not initialized",
@@ -212,12 +211,11 @@ export default function activate(ctx: ExtensionContext): void {
         return;
       }
 
-      const prompt = modeInstruction ? `${modeInstruction}\n${query}` : query;
-      bus.emit("agent:query", { query, modeLabel });
+      bus.emit("agent:query", { query });
       bus.emit("agent:processing-start", {});
 
       try {
-        await session.prompt(prompt);
+        await session.prompt(query);
       } catch (err) {
         bus.emit("agent:error", {
           message: err instanceof Error ? err.message : String(err),

package/examples/extensions/secret-guard.ts

@@ -0,0 +1,100 @@
+/**
+ * Secret guard extension.
+ *
+ * Redacts sensitive patterns (API keys, tokens, passwords) from tool output
+ * — both the streamed terminal display and the content sent back to the LLM.
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/secret-guard.ts
+ *
+ *   # Or install permanently:
+ *   cp examples/extensions/secret-guard.ts ~/.agent-sh/extensions/
+ *
+ * Configuration (~/.agent-sh/settings.json):
+ *   {
+ *     "secret-guard": {
+ *       "extraPatterns": ["CUSTOM_\\w+=\\S+"],
+ *       "redactText": "***REDACTED***"
+ *     }
+ *   }
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+// Common secret patterns — each matches key=value or key: value formats
+const DEFAULT_PATTERNS = [
+  // API keys and tokens (generic)
+  /(?:api[_-]?key|api[_-]?secret|access[_-]?token|auth[_-]?token|secret[_-]?key|private[_-]?key)\s*[=:]\s*\S+/gi,
+  // AWS
+  /(?:AKIA|ASIA)[A-Z0-9]{16}/g,
+  /(?:aws_secret_access_key|aws_session_token)\s*[=:]\s*\S+/gi,
+  // Bearer tokens
+  /Bearer\s+[A-Za-z0-9\-._~+/]+=*/g,
+  // GitHub tokens
+  /gh[pousr]_[A-Za-z0-9_]{36,}/g,
+  // Anthropic / OpenAI keys
+  /sk-(?:ant-)?[A-Za-z0-9\-_]{10,}/g,
+  // Generic long hex/base64 secrets (env var assignment)
+  /(?:SECRET|TOKEN|PASSWORD|PASSWD|API_KEY|PRIVATE_KEY)\s*[=:]\s*\S+/gi,
+  // Connection strings with passwords
+  /[a-z+]+:\/\/[^:]+:[^@\s]+@/gi,
+];
+
+export default function activate(ctx: ExtensionContext) {
+  const { bus } = ctx;
+  const config = ctx.getExtensionSettings("secret-guard", {
+    extraPatterns: [] as string[],
+    redactText: "***REDACTED***",
+  });
+
+  const patterns = [
+    ...DEFAULT_PATTERNS,
+    ...config.extraPatterns.map((p: string) => new RegExp(p, "gi")),
+  ];
+
+  function redact(text: string): string {
+    let result = text;
+    for (const pattern of patterns) {
+      // Reset lastIndex for stateful regex (global flag)
+      pattern.lastIndex = 0;
+      result = result.replace(pattern, config.redactText);
+    }
+    return result;
+  }
+
+  // Redact the dynamic context (shell history, cwd, etc.) before it's sent
+  // to the LLM. This is the chokepoint — everything the model sees passes
+  // through dynamic-context:build.
+  ctx.advise("dynamic-context:build", (next) => {
+    return redact(next());
+  });
+
+  // Advise tool:execute to wrap both streaming output and final result.
+  // Chunks from child processes arrive at arbitrary byte boundaries, so a
+  // secret like "sk-ant-abc123" could be split across two chunks.  We
+  // line-buffer: accumulate until we see '\n', redact complete lines, flush.
+  ctx.advise("tool:execute", async (next, toolCtx) => {
+    const origOnChunk = toolCtx.onChunk;
+    if (origOnChunk) {
+      let buf = "";
+      toolCtx.onChunk = (chunk: string) => {
+        buf += chunk;
+        const lastNl = buf.lastIndexOf("\n");
+        if (lastNl !== -1) {
+          // Flush all complete lines, redacted
+          origOnChunk(redact(buf.slice(0, lastNl + 1)));
+          buf = buf.slice(lastNl + 1);
+        }
+      };
+
+      const result = await next(toolCtx);
+
+      // Flush any remaining partial line
+      if (buf) origOnChunk(redact(buf));
+
+      return { ...result, content: redact(result.content) };
+    }
+
+    const result = await next(toolCtx);
+    return { ...result, content: redact(result.content) };
+  });
+}