agent-sh 0.2.0 → 0.3.1

package/dist/utils/output-writer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Abstraction over terminal output.
+ *
+ * All TUI rendering goes through an OutputWriter instead of calling
+ * process.stdout.write directly.  This enables testing (BufferWriter),
+ * alternative frontends, and a single point of control for output.
+ */
+export interface OutputWriter {
+    write(text: string): void;
+    get columns(): number;
+}
+/** Default writer that forwards to process.stdout. */
+export declare class StdoutWriter implements OutputWriter {
+    write(text: string): void;
+    get columns(): number;
+}
+/** Captures all output in memory. Useful for testing. */
+export declare class BufferWriter implements OutputWriter {
+    output: string[];
+    columns: number;
+    write(text: string): void;
+}

package/dist/utils/output-writer.js

@@ -0,0 +1,29 @@
+/**
+ * Abstraction over terminal output.
+ *
+ * All TUI rendering goes through an OutputWriter instead of calling
+ * process.stdout.write directly.  This enables testing (BufferWriter),
+ * alternative frontends, and a single point of control for output.
+ */
+/** Default writer that forwards to process.stdout. */
+export class StdoutWriter {
+    write(text) {
+        if (process.stdout.writable) {
+            try {
+                process.stdout.write(text);
+            }
+            catch { }
+        }
+    }
+    get columns() {
+        return process.stdout.columns || 80;
+    }
+}
+/** Captures all output in memory. Useful for testing. */
+export class BufferWriter {
+    output = [];
+    columns = 80;
+    write(text) {
+        this.output.push(text);
+    }
+}

package/dist/utils/stream-transform.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Stream transform helpers for content pipeline extensions.
+ *
+ * Handles the boilerplate of buffering across chunk boundaries,
+ * pattern matching, and flush-on-done coordination.
+ */
+import type { EventBus, ContentBlock } from "../event-bus.js";
+export interface BlockTransformOptions {
+    /** Opening delimiter (e.g. "$$") */
+    open: string;
+    /** Closing delimiter (e.g. "$$") */
+    close: string;
+    /**
+     * Transform the content between delimiters.
+     * Return a ContentBlock (text, image, or raw) or null to keep original.
+     */
+    transform: (content: string) => ContentBlock | ContentBlock[] | null;
+}
+/**
+ * Register a delimiter-based block transform on the content pipeline.
+ *
+ * Automatically handles:
+ *   - Buffering across chunk boundaries
+ *   - Safe boundary detection (only emits text outside open delimiters)
+ *   - Flush on response-done
+ *
+ * Example:
+ *   createBlockTransform(bus, {
+ *     open: "$$",
+ *     close: "$$",
+ *     transform(latex) {
+ *       const png = renderLatex(latex);
+ *       return png ? { type: "image", data: png } : null;
+ *     },
+ *   });
+ */
+export declare function createBlockTransform(bus: EventBus, opts: BlockTransformOptions): void;
+export interface FencedBlockTransformOptions {
+    /** Regex matching the opening fence line. Captures are passed to transform. */
+    open: RegExp;
+    /** Regex matching the closing fence line. */
+    close: RegExp;
+    /**
+     * Transform a complete fenced block.
+     * Receives the opening fence match and the content between fences.
+     * Return ContentBlock(s), or null to produce a default code-block.
+     */
+    transform: (openMatch: RegExpMatchArray, content: string) => ContentBlock | ContentBlock[] | null;
+}
+/**
+ * Register a line-delimited fenced block transform on the content pipeline.
+ *
+ * Detects patterns like ```lang\n...\n``` in the streaming text,
+ * buffers the content line-by-line, and produces ContentBlocks when
+ * the closing fence arrives.
+ *
+ * Example:
+ *   createFencedBlockTransform(bus, {
+ *     open: /^```(\w*)\s*$/,
+ *     close: /^```\s*$/,
+ *     transform(match, content) {
+ *       return { type: "code-block", language: match[1] || "", code: content };
+ *     },
+ *   });
+ */
+export interface FencedBlockTransformHandle {
+    /** Flush any buffered text (e.g. before tool calls, to preserve interleaving). */
+    flush(): void;
+}
+export declare function createFencedBlockTransform(bus: EventBus, opts: FencedBlockTransformOptions): FencedBlockTransformHandle;

package/dist/utils/stream-transform.js

@@ -0,0 +1,229 @@
+/**
+ * Register a delimiter-based block transform on the content pipeline.
+ *
+ * Automatically handles:
+ *   - Buffering across chunk boundaries
+ *   - Safe boundary detection (only emits text outside open delimiters)
+ *   - Flush on response-done
+ *
+ * Example:
+ *   createBlockTransform(bus, {
+ *     open: "$$",
+ *     close: "$$",
+ *     transform(latex) {
+ *       const png = renderLatex(latex);
+ *       return png ? { type: "image", data: png } : null;
+ *     },
+ *   });
+ */
+export function createBlockTransform(bus, opts) {
+    let buffer = "";
+    bus.onPipe("agent:response-chunk", (e) => {
+        // Process text from e.text and from text blocks in e.blocks
+        const outBlocks = [];
+        if (e.blocks) {
+            for (const block of e.blocks) {
+                if (block.type === "text") {
+                    // Run delimiter detection on text blocks
+                    buffer += block.text;
+                    const { blocks: parsed, pending } = processBuffer(buffer, opts);
+                    buffer = pending;
+                    outBlocks.push(...parsed);
+                }
+                else {
+                    // Pass through non-text blocks unchanged
+                    outBlocks.push(block);
+                }
+            }
+        }
+        // Also process any raw text not yet in blocks
+        if (e.text) {
+            buffer += e.text;
+            const { blocks: parsed, pending } = processBuffer(buffer, opts);
+            buffer = pending;
+            outBlocks.push(...parsed);
+        }
+        return { ...e, text: "", blocks: outBlocks };
+    });
+    bus.onPipe("agent:response-done", (e) => {
+        if (buffer) {
+            // Unclosed pattern — flush as text
+            bus.emitTransform("agent:response-chunk", {
+                text: buffer,
+                blocks: [{ type: "text", text: buffer }],
+            });
+            buffer = "";
+        }
+        return e;
+    });
+}
+export function createFencedBlockTransform(bus, opts) {
+    let buffer = "";
+    let inFence = false;
+    let fenceMatch = null;
+    let fenceLines = [];
+    let flushing = false;
+    bus.onPipe("agent:response-chunk", (e) => {
+        if (flushing)
+            return e; // pass through during flush to avoid re-buffering
+        // Collect text from blocks or raw text
+        let incoming = "";
+        if (e.blocks) {
+            // Process text blocks, pass through non-text blocks
+            const passthrough = [];
+            for (const block of e.blocks) {
+                if (block.type === "text") {
+                    incoming += block.text;
+                }
+                else {
+                    passthrough.push(block);
+                }
+            }
+            const { blocks, pending } = processFencedBuffer(buffer + incoming, opts, inFence, fenceMatch, fenceLines);
+            buffer = pending.text;
+            inFence = pending.inFence;
+            fenceMatch = pending.fenceMatch;
+            fenceLines = pending.fenceLines;
+            return { ...e, text: "", blocks: [...passthrough, ...blocks] };
+        }
+        // No blocks yet — work with raw text
+        incoming = buffer + e.text;
+        const { blocks, pending } = processFencedBuffer(incoming, opts, inFence, fenceMatch, fenceLines);
+        buffer = pending.text;
+        inFence = pending.inFence;
+        fenceMatch = pending.fenceMatch;
+        fenceLines = pending.fenceLines;
+        const existing = e.blocks ?? [];
+        return { ...e, text: "", blocks: [...existing, ...blocks] };
+    });
+    function flushBuffer() {
+        if (!buffer && !inFence)
+            return;
+        let remaining = buffer;
+        if (inFence) {
+            remaining = (fenceMatch?.[0] ?? "") + "\n" + fenceLines.join("\n") + (remaining ? "\n" + remaining : "");
+            inFence = false;
+            fenceMatch = null;
+            fenceLines = [];
+        }
+        buffer = "";
+        if (remaining) {
+            flushing = true;
+            bus.emitTransform("agent:response-chunk", {
+                text: "",
+                blocks: [{ type: "text", text: remaining }],
+            });
+            flushing = false;
+        }
+    }
+    bus.onPipe("agent:response-done", (e) => {
+        flushBuffer();
+        return e;
+    });
+    return { flush: flushBuffer };
+}
+function processFencedBuffer(text, opts, inFence, fenceMatch, fenceLines) {
+    const blocks = [];
+    const lines = text.split("\n");
+    // Last element might be an incomplete line — hold it back
+    const incompleteLine = lines.pop();
+    let textAccum = ""; // accumulate non-fence text as one block
+    for (const line of lines) {
+        if (inFence) {
+            // Check for closing fence
+            if (opts.close.test(line)) {
+                const content = fenceLines.join("\n");
+                const result = opts.transform(fenceMatch, content);
+                if (result === null) {
+                    const lang = fenceMatch?.[1] ?? "";
+                    blocks.push({ type: "code-block", language: lang, code: content });
+                }
+                else if (Array.isArray(result)) {
+                    blocks.push(...result);
+                }
+                else {
+                    blocks.push(result);
+                }
+                inFence = false;
+                fenceMatch = null;
+                fenceLines = [];
+            }
+            else {
+                fenceLines.push(line);
+            }
+        }
+        else {
+            // Check for opening fence
+            const match = line.match(opts.open);
+            if (match) {
+                // Flush accumulated text before the fence
+                if (textAccum) {
+                    blocks.push({ type: "text", text: textAccum });
+                    textAccum = "";
+                }
+                inFence = true;
+                fenceMatch = match;
+                fenceLines = [];
+            }
+            else {
+                // Accumulate non-fence text (keep contiguous for downstream transforms)
+                textAccum += line + "\n";
+            }
+        }
+    }
+    // Flush remaining accumulated text
+    if (textAccum) {
+        blocks.push({ type: "text", text: textAccum });
+    }
+    return {
+        blocks,
+        pending: {
+            text: incompleteLine,
+            inFence,
+            fenceMatch,
+            fenceLines,
+        },
+    };
+}
+// ── Inline delimiter block transform ─────────────────────────────
+function processBuffer(text, opts) {
+    const blocks = [];
+    let i = 0;
+    while (i < text.length) {
+        const openIdx = text.indexOf(opts.open, i);
+        if (openIdx === -1) {
+            // No more delimiters — everything is safe text
+            const remainder = text.slice(i);
+            if (remainder)
+                blocks.push({ type: "text", text: remainder });
+            return { blocks, pending: "" };
+        }
+        const searchFrom = openIdx + opts.open.length;
+        const closeIdx = text.indexOf(opts.close, searchFrom);
+        if (closeIdx === -1) {
+            // Unclosed delimiter — emit text before, hold back from delimiter
+            const before = text.slice(i, openIdx);
+            if (before)
+                blocks.push({ type: "text", text: before });
+            return { blocks, pending: text.slice(openIdx) };
+        }
+        // Complete match
+        const before = text.slice(i, openIdx);
+        if (before)
+            blocks.push({ type: "text", text: before });
+        const inner = text.slice(searchFrom, closeIdx).trim();
+        const result = opts.transform(inner);
+        if (result === null) {
+            // Transform declined — keep original text with delimiters
+            blocks.push({ type: "text", text: opts.open + inner + opts.close });
+        }
+        else if (Array.isArray(result)) {
+            blocks.push(...result);
+        }
+        else {
+            blocks.push(result);
+        }
+        i = closeIdx + opts.close.length;
+    }
+    return { blocks, pending: "" };
+}

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

@@ -29,14 +29,17 @@ export declare function formatElapsed(ms: number): string;
 export interface SpinnerState {
     frame: number;
     startTime: number;
-    interval: ReturnType<typeof setInterval> | null;
 }
-export declare function createSpinner(): SpinnerState;
-/**
- * Start a spinner that writes to stdout on the current line.
- * Returns the SpinnerState for later stopping.
- */
-export declare function startSpinner(label: string, opts?: {
+export interface SpinnerOpts {
     color?: string;
+    hint?: string;
+    startTime?: number;
+}
+export declare function createSpinner(opts?: {
+    startTime?: number;
 }): SpinnerState;
-export declare function stopSpinner(state: SpinnerState): void;
+/**
+ * Pure function: render the current spinner line and advance the frame.
+ * Does not write to stdout — the caller is responsible for output.
+ */
+export declare function renderSpinnerLine(state: SpinnerState, label: string, opts?: SpinnerOpts): string;

package/dist/utils/tool-display.js

@@ -1,9 +1,3 @@
-/**
- * Tool display renderer with elapsed timer and width-adaptive output.
- *
- * Follows the render(width) -> string[] protocol for completed tools.
- * Also provides a spinner/timer component for in-progress tools.
- */
 import { visibleLen } from "./ansi.js";
 import { palette as p } from "./palette.js";
 // ── Quiet command detection ──────────────────────────────────────
@@ -61,28 +55,54 @@ export function renderToolCall(tool, width) {
         return [`${p.warning}${text}${p.reset}`];
     }
     const lines = [];
-    lines.push(`${p.warning}${p.bold}${icon} ${tool.title}${p.reset}`);
+    // Build a compact detail string to append after the title
+    let detail = "";
+    const cwd = process.cwd();
     if (mode === "full") {
-        // Show file locations if available
-        if (tool.locations && tool.locations.length > 0) {
-            for (const loc of tool.locations) {
-                const lineInfo = loc.line ? `:${loc.line}` : "";
-                lines.push(`  ${p.dim}${loc.path}${lineInfo}${p.reset}`);
-            }
-        }
-        // Show command string for terminal tools
         if (tool.command) {
-            const maxCmdW = Math.max(1, width - 4);
-            const cmd = tool.command.length > maxCmdW
-                ? tool.command.slice(0, maxCmdW - 1) + "…"
-                : tool.command;
-            lines.push(`  ${p.dim}$ ${cmd}${p.reset}`);
+            detail = `$ ${tool.command}`;
         }
-        // Show raw input args for non-terminal, non-file tools
-        if (!tool.command && !tool.locations?.length && tool.rawInput) {
-            const detail = formatRawInput(tool.rawInput, width - 4);
-            if (detail)
-                lines.push(`  ${p.dim}${detail}${p.reset}`);
+        else if (tool.locations && tool.locations.length > 0) {
+            const loc = tool.locations[0];
+            const lineInfo = loc.line ? `:${loc.line}` : "";
+            detail = `${shortenPath(loc.path, cwd)}${lineInfo}`;
+        }
+        else if (tool.rawInput) {
+            const raw = tool.rawInput;
+            if (raw && typeof raw === "object") {
+                if (typeof raw.command === "string") {
+                    detail = `$ ${raw.command}`;
+                }
+                else if (typeof raw.operation === "string") {
+                    detail = raw.operation;
+                    if (raw.ids && Array.isArray(raw.ids)) {
+                        detail += ` #${raw.ids.join(",")}`;
+                    }
+                    if (typeof raw.query === "string") {
+                        detail += ` "${raw.query}"`;
+                    }
+                }
+                else {
+                    detail = formatRawInput(tool.rawInput, width - tool.title.length - 6);
+                }
+            }
+        }
+    }
+    // Render as single line: ► title: detail
+    const maxDetailW = Math.max(1, width - tool.title.length - 6);
+    if (detail) {
+        if (detail.length > maxDetailW)
+            detail = detail.slice(0, maxDetailW - 1) + "…";
+        lines.push(`${p.warning}${p.bold}${icon} ${tool.title}${p.reset}${p.dim}: ${detail}${p.reset}`);
+    }
+    else {
+        lines.push(`${p.warning}${p.bold}${icon} ${tool.title}${p.reset}`);
+    }
+    // Show additional file locations on separate lines (if more than one)
+    if (mode === "full" && tool.locations && tool.locations.length > 1) {
+        for (const loc of tool.locations.slice(1)) {
+            const lineInfo = loc.line ? `:${loc.line}` : "";
+            lines.push(`  ${p.dim}${shortenPath(loc.path, cwd)}${lineInfo}${p.reset}`);
         }
     }
     return lines;
@@ -159,33 +179,36 @@ export function formatElapsed(ms) {
 }
 // ── Spinner with elapsed timer ───────────────────────────────────
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-export function createSpinner() {
-    return { frame: 0, startTime: Date.now(), interval: null };
+export function createSpinner(opts) {
+    return { frame: 0, startTime: opts?.startTime || Date.now() };
 }
 /**
- * Start a spinner that writes to stdout on the current line.
- * Returns the SpinnerState for later stopping.
+ * Pure function: render the current spinner line and advance the frame.
+ * Does not write to stdout — the caller is responsible for output.
  */
-export function startSpinner(label, opts) {
-    const state = createSpinner();
+export function renderSpinnerLine(state, label, opts) {
+    const frame = SPINNER_FRAMES[state.frame % SPINNER_FRAMES.length];
+    state.frame++;
     const color = opts?.color ?? p.accent;
-    state.interval = setInterval(() => {
-        const frame = SPINNER_FRAMES[state.frame % SPINNER_FRAMES.length];
-        const elapsed = formatElapsed(Date.now() - state.startTime);
-        const timer = elapsed ? ` ${p.dim}${elapsed}${p.reset}` : "";
-        process.stdout.write(`\r  ${color}${frame} ${label}...${p.reset}${timer}\x1b[K`);
-        state.frame++;
-    }, 80);
-    return state;
-}
-export function stopSpinner(state) {
-    if (state.interval) {
-        clearInterval(state.interval);
-        state.interval = null;
-        process.stdout.write("\r\x1b[2K");
-    }
+    const elapsed = formatElapsed(Date.now() - state.startTime);
+    const timer = elapsed ? ` ${p.dim}${elapsed}${p.reset}` : "";
+    const hint = opts?.hint ? ` ${p.dim}${opts.hint}${p.reset}` : "";
+    return `${color}${frame} ${label}...${p.reset}${timer}${hint}`;
 }
 // ── Helpers ──────────────────────────────────────────────────────
+/**
+ * Shorten an absolute path to a relative or tilde-prefixed form.
+ */
+function shortenPath(p, cwd) {
+    if (p.startsWith(cwd + "/"))
+        return p.slice(cwd.length + 1);
+    if (p.startsWith(cwd))
+        return p.slice(cwd.length) || ".";
+    const home = process.env.HOME;
+    if (home && p.startsWith(home + "/"))
+        return "~/" + p.slice(home.length + 1);
+    return p;
+}
 function truncateVisible(text, maxWidth) {
     if (visibleLen(text) <= maxWidth)
         return text;

package/examples/extensions/latex-images.ts

@@ -0,0 +1,142 @@
+/**
+ * LaTeX image overlay extension.
+ *
+ * Renders $$...$$ equations as inline terminal images using the same
+ * pipeline as Emacs org-mode: latex → dvipng.
+ *
+ * Uses the content transform pipeline (createBlockTransform + ContentBlock)
+ * so the extension just defines delimiters and a transform function —
+ * no manual buffering, no process.stdout hacks.
+ *
+ * Requirements:
+ *   - latex and dvipng (typically from TeX Live: `brew install --cask mactex`)
+ *   - iTerm2, WezTerm, Kitty, or Ghostty terminal
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/latex-images.ts
+ */
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionContext } from "agent-sh/types";
+
+// Settings loaded in activate() via ctx.getExtensionSettings
+let config = { dpi: 300, fgColor: "d4d4d4" };
+
+/** Encode PNG as iTerm2 or Kitty inline image escape sequence. */
+function encodeImage(data: Buffer): string {
+  const b64 = data.toString("base64");
+  if (process.env.TERM_PROGRAM === "iTerm.app" || process.env.TERM_PROGRAM === "WezTerm") {
+    return `\x1b]1337;File=inline=1;size=${data.length};preserveAspectRatio=1:${b64}\x07`;
+  }
+  if (process.env.KITTY_WINDOW_ID || process.env.TERM_PROGRAM === "ghostty") {
+    const chunks: string[] = [];
+    for (let i = 0; i < b64.length; i += 4096) {
+      const chunk = b64.slice(i, i + 4096);
+      const isLast = i + 4096 >= b64.length;
+      chunks.push(i === 0
+        ? `\x1b_Gf=100,t=d,a=T,m=${isLast ? 0 : 1};${chunk}\x1b\\`
+        : `\x1b_Gm=${isLast ? 0 : 1};${chunk}\x1b\\`);
+    }
+    return chunks.join("");
+  }
+  return "";
+}
+
+// ── LaTeX rendering via latex + dvipng ───────────────────────────
+
+const LATEX_TEMPLATE = (equation: string, fg: string) => `
+\\documentclass[border=1pt]{standalone}
+\\usepackage{amsmath,amssymb,amsfonts}
+\\usepackage{xcolor}
+\\begin{document}
+\\color[HTML]{${fg}}
+$\\displaystyle ${equation}$
+\\end{document}
+`;
+
+let tmpDir: string | null = null;
+let renderCounter = 0;
+
+function ensureTmpDir(): string {
+  if (!tmpDir) {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "latex-img-"));
+  }
+  return tmpDir;
+}
+
+function renderEquation(equation: string): Buffer | null {
+  const dir = ensureTmpDir();
+  const idx = renderCounter++;
+  const texPath = path.join(dir, `eq${idx}.tex`);
+  const dviPath = path.join(dir, `eq${idx}.dvi`);
+  const pngPath = path.join(dir, `eq${idx}.png`);
+
+  try {
+    fs.writeFileSync(texPath, LATEX_TEMPLATE(equation, config.fgColor));
+
+    execSync(
+      `latex -interaction=nonstopmode -output-directory="${dir}" "${texPath}"`,
+      { timeout: 10000, stdio: "pipe", cwd: dir },
+    );
+
+    execSync(
+      `dvipng -D ${config.dpi} -T tight -bg Transparent --truecolor -o "${pngPath}" "${dviPath}"`,
+      { timeout: 10000, stdio: "pipe" },
+    );
+
+    return fs.readFileSync(pngPath);
+  } catch (err) {
+    if (process.env.DEBUG) {
+      const msg = err instanceof Error ? (err as any).stderr?.toString() || err.message : String(err);
+      process.stderr.write(`[latex-images] render failed: ${msg}\n`);
+    }
+    return null;
+  }
+}
+
+// ── Extension entry point ────────────────────────────────────────
+
+export default function activate(ctx: ExtensionContext) {
+  const { bus } = ctx;
+
+  // Load settings: ~/.agent-sh/settings.json → "latex-images": { dpi, fgColor }
+  config = ctx.getExtensionSettings("latex-images", config);
+
+  // Check for latex + dvipng
+  try {
+    execSync("latex --version", { stdio: "ignore", timeout: 3000 });
+    execSync("dvipng --version", { stdio: "ignore", timeout: 3000 });
+  } catch {
+    bus.emit("ui:error", {
+      message: "latex-images: latex and dvipng required (brew install --cask mactex)",
+    });
+    return;
+  }
+
+  // Handle inline $$...$$ display math
+  ctx.createBlockTransform({
+    open: "$$",
+    close: "$$",
+    transform(latex) {
+      const png = renderEquation(latex);
+      if (!png) return null;
+      return { type: "image", data: png };
+    },
+  });
+
+  // Advise the code block renderer — wrap the default syntax highlighter
+  ctx.advise("render:code-block", (next, language: string, code: string, width: number) => {
+    if (language !== "latex" && language !== "tex") return next(language, code, width);
+    const png = renderEquation(code);
+    if (!png) return next(language, code, width); // render failed — fall through
+    ctx.call("render:image", png);
+  });
+
+  process.on("exit", () => {
+    if (tmpDir) {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+    }
+  });
+}