agent-sh 0.15.0 → 0.15.2

package/src/utils/shell-output-spill.ts

@@ -0,0 +1,76 @@
+/**
+ * Spill long shell outputs to per-session tempfiles.
+ *
+ * Captured PTY output that exceeds the truncation threshold is written to
+ * `<tmpdir>/agent-sh-<pid>/<id>.out`. The in-memory exchange keeps only a
+ * head+tail stub pointing at that path, so the agent can fetch the full
+ * text via `read_file` on demand. The session dir is removed on process
+ * exit; stale dirs from dead processes are swept lazily on first use.
+ */
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR_PREFIX = "agent-sh-";
+
+let sessionDir: string | null = null;
+let cleanupRegistered = false;
+
+export function getSessionDir(): string {
+  if (sessionDir) return sessionDir;
+  sessionDir = join(tmpdir(), `${DIR_PREFIX}${process.pid}`);
+  mkdirSync(sessionDir, { recursive: true });
+  sweepStaleDirs();
+  if (!cleanupRegistered) {
+    cleanupRegistered = true;
+    const cleanup = () => {
+      if (!sessionDir) return;
+      try { rmSync(sessionDir, { recursive: true, force: true }); } catch {}
+      sessionDir = null;
+    };
+    process.on("exit", cleanup);
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+      process.on(sig, () => { cleanup(); process.exit(128); });
+    }
+  }
+  return sessionDir;
+}
+
+export function spillOutput(id: number, text: string): string {
+  const path = join(getSessionDir(), `${id}.out`);
+  writeFileSync(path, text);
+  return path;
+}
+
+function sweepStaleDirs(): void {
+  const base = tmpdir();
+  let entries: string[];
+  try {
+    entries = readdirSync(base);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.startsWith(DIR_PREFIX)) continue;
+    const pid = Number(name.slice(DIR_PREFIX.length));
+    if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
+    if (isProcessAlive(pid)) continue;
+    const full = join(base, name);
+    try {
+      // Small safety check: only remove directories.
+      if (statSync(full).isDirectory()) {
+        rmSync(full, { recursive: true, force: true });
+      }
+    } catch {}
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // ESRCH = no such process; EPERM = exists but we can't signal it
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}

package/src/utils/stream-transform.ts

@@ -0,0 +1,292 @@
+/**
+ * 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 "../core/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 function createBlockTransform(
+  bus: EventBus,
+  opts: BlockTransformOptions,
+): void {
+  let buffer = "";
+
+  bus.onPipe("agent:response-chunk", (e) => {
+    const outBlocks: ContentBlock[] = [];
+
+    for (const block of e.blocks) {
+      if (block.type === "text") {
+        buffer += block.text;
+        const { blocks: parsed, pending } = processBuffer(buffer, opts);
+        buffer = pending;
+        outBlocks.push(...parsed);
+      } else {
+        outBlocks.push(block);
+      }
+    }
+
+    return { blocks: outBlocks };
+  });
+
+  bus.onPipe("agent:response-done", (e) => {
+    if (buffer) {
+      bus.emitTransform("agent:response-chunk", {
+        blocks: [{ type: "text", text: buffer }],
+      });
+      buffer = "";
+    }
+    return e;
+  });
+}
+
+// ── Fenced block transform ────────────────────────────────────────
+
+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 function createFencedBlockTransform(
+  bus: EventBus,
+  opts: FencedBlockTransformOptions,
+): FencedBlockTransformHandle {
+  let buffer = "";
+  let inFence = false;
+  let fenceMatch: RegExpMatchArray | null = null;
+  let fenceLines: string[] = [];
+  let flushing = false;
+
+  bus.onPipe("agent:response-chunk", (e) => {
+    if (flushing) return e; // pass through during flush to avoid re-buffering
+
+    // Separate text blocks (to buffer) from non-text blocks (pass through)
+    let incoming = "";
+    const passthrough: ContentBlock[] = [];
+    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 { blocks: [...passthrough, ...blocks] };
+  });
+
+  function flushBuffer(): void {
+    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", {
+        blocks: [{ type: "text", text: remaining }],
+      });
+      flushing = false;
+    }
+  }
+
+  bus.onPipe("agent:response-done", (e) => {
+    flushBuffer();
+    return e;
+  });
+
+  return { flush: flushBuffer };
+}
+
+interface FencedPendingState {
+  text: string;
+  inFence: boolean;
+  fenceMatch: RegExpMatchArray | null;
+  fenceLines: string[];
+}
+
+function processFencedBuffer(
+  text: string,
+  opts: FencedBlockTransformOptions,
+  inFence: boolean,
+  fenceMatch: RegExpMatchArray | null,
+  fenceLines: string[],
+): { blocks: ContentBlock[]; pending: FencedPendingState } {
+  const blocks: ContentBlock[] = [];
+  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: string,
+  opts: BlockTransformOptions,
+): { blocks: ContentBlock[]; pending: string } {
+  const blocks: ContentBlock[] = [];
+  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/src/utils/terminal-buffer.ts

@@ -0,0 +1,213 @@
+/**
+ * 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
+ */
+// xterm is loaded lazily on first TerminalBuffer.create(). Subcommands
+// (init/install/list) and non-shell frontends (web bridges) import this
+// file transitively but never instantiate a buffer; they shouldn't pay
+// the xterm parse cost at startup.
+import { createRequire } from "module";
+import type { Terminal, IBuffer } from "@xterm/headless";
+import type { SerializeAddon } from "@xterm/addon-serialize";
+import type { EventBus } from "../core/event-bus.js";
+
+const require = createRequire(import.meta.url);
+
+// Node's require cache memoizes the first hit; subsequent calls are
+// just a hashmap lookup, so this stays lazy without our own caching.
+const loadXterm = (): { Terminal: typeof Terminal; SerializeAddon: typeof SerializeAddon } => ({
+  Terminal: require("@xterm/headless").Terminal,
+  SerializeAddon: require("@xterm/addon-serialize").SerializeAddon,
+});
+
+// ── Types ───────────────────────────────────────────────────────
+
+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 function formatScreenContext(
+  screen: ScreenSnapshot,
+  maxLines = 80,
+  baseContext?: string,
+): string {
+  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 {
+  private readonly term: Terminal;
+  private readonly serializeAddon: SerializeAddon;
+
+  /** Flush pending drip-feed data (set by createWired). */
+  _flushPending: (() => void) | null = null;
+
+  private constructor(term: Terminal, serialize: SerializeAddon) {
+    this.term = term;
+    this.serializeAddon = serialize;
+  }
+
+  static create(config?: TerminalBufferConfig): TerminalBuffer {
+    const { Terminal, SerializeAddon } = loadXterm();
+    const cols = config?.cols ?? (process.stdout.columns || 80);
+    const rows = config?.rows ?? (process.stdout.rows || 24);
+    const scrollback = config?.scrollback ?? 200;
+
+    const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback });
+    const serialize = new SerializeAddon();
+    term.loadAddon(serialize);
+    return new TerminalBuffer(term, serialize);
+  }
+
+  /**
+   * Create a TerminalBuffer wired to a bus's `shell:pty-data` event.
+   * Drip-feeds writes asynchronously: synchronous `term.write()` in the
+   * pty-data handler changes PTY read coalescing enough to introduce
+   * visual artifacts.
+   */
+  static createWired(bus: EventBus, config?: TerminalBufferConfig): TerminalBuffer {
+    const tb = TerminalBuffer.create(config);
+    let pending = "";
+    const drain = (): void => {
+      if (pending) { const d = pending; pending = ""; tb.write(d); }
+    };
+    bus.on("shell:pty-data", ({ raw }) => { pending += raw; });
+    setInterval(drain, 50);
+    tb._flushPending = drain;
+    process.stdout.on("resize", () => {
+      tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
+    });
+    return tb;
+  }
+
+  /** Flush any pending drip-feed data into the virtual terminal. */
+  flush(): void {
+    this._flushPending?.();
+  }
+
+  /** Write raw data into the virtual terminal. */
+  write(data: string): void {
+    this.term.write(data);
+  }
+
+  /** Get the raw serialized terminal output (includes ANSI sequences). */
+  serialize(): string {
+    return this.serializeAddon.serialize();
+  }
+
+  /** Read clean screen text with metadata. */
+  readScreen(opts?: { includeScrollback?: boolean }): ScreenSnapshot {
+    const buf = this.term.buffer.active;
+    const lines = opts?.includeScrollback
+      ? this.readAllLines(buf)
+      : this.readViewportLines(buf);
+    return {
+      text: lines.join("\n"),
+      altScreen: buf.type === "alternate",
+      cursorX: buf.cursorX,
+      cursorY: buf.cursorY,
+    };
+  }
+
+  /** Read the screen and wrap it as a `<terminal_buffer>` context block. */
+  formatScreen(maxLines?: number, baseContext?: string): string {
+    return formatScreenContext(this.readScreen(), maxLines, baseContext);
+  }
+
+  /**
+   * 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[] {
+    const targetRows = rows ?? (process.stdout.rows || 24);
+    return this.readViewportLines(this.term.buffer.active, targetRows);
+  }
+
+  /** Read visible viewport lines from a buffer. */
+  private readViewportLines(buf: IBuffer, rows?: number): string[] {
+    const targetRows = rows ?? buf.length;
+    const base = buf.baseY ?? 0;
+    const lines: string[] = [];
+    for (let y = 0; y < targetRows; y++) {
+      const line = buf.getLine(base + y);
+      lines.push(line ? line.translateToString(true) : "");
+    }
+    return lines;
+  }
+
+  /** Read all lines including scrollback from a buffer. */
+  private readAllLines(buf: IBuffer): string[] {
+    const total = (buf.baseY ?? 0) + buf.length;
+    const lines: string[] = [];
+    for (let y = 0; y < total; y++) {
+      const line = buf.getLine(y);
+      lines.push(line ? line.translateToString(true) : "");
+    }
+    while (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines.pop();
+    }
+    return lines;
+  }
+
+  /** Get cursor position. */
+  getCursor(): { x: number; y: number } {
+    return {
+      x: this.term.buffer.active.cursorX,
+      y: this.term.buffer.active.cursorY,
+    };
+  }
+
+  /** Resize the virtual terminal. */
+  resize(cols: number, rows: number): void {
+    this.term.resize(cols, rows);
+  }
+
+  /** Whether the alternate screen buffer is active. */
+  get altScreen(): boolean {
+    return this.term.buffer.active.type === "alternate";
+  }
+}