agent-sh 0.15.0 → 0.15.2

package/src/utils/ansi.ts

@@ -0,0 +1,140 @@
+import stringWidth from "string-width";
+import stripAnsiPkg from "strip-ansi";
+
+// ── ANSI escape code constants ────────────────────────────────
+
+export const CYAN = "\x1b[36m";
+export const DIM = "\x1b[2m";
+export const YELLOW = "\x1b[33m";
+export const GREEN = "\x1b[32m";
+export const RED = "\x1b[31m";
+export const GRAY = "\x1b[90m";
+export const BOLD = "\x1b[1m";
+export const RESET = "\x1b[0m";
+
+// ── ANSI utility functions ───────────────────────────────────
+
+// Reused across iterations. Segmenter construction is not free, and the API
+// is pure (no per-call state) so a module-level instance is safe.
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/**
+ * Width of a single Unicode code point in terminal columns.
+ *
+ * For correct rendering of emoji clusters (ZWJ, flags, skin-tone, VS16)
+ * prefer `clusterWidth` or `visibleLen`, which segment graphemes first.
+ * This code-point-level primitive is kept for callers that iterate over
+ * chars for wrap-detection purposes (e.g. CJK line-break rules).
+ */
+export function charWidth(codePoint: number): number {
+  return stringWidth(String.fromCodePoint(codePoint));
+}
+
+/**
+ * Width of one grapheme cluster in terminal columns. Handles ZWJ sequences,
+ * regional-indicator flags, skin-tone modifiers, and VS16 emoji presentation.
+ */
+export function clusterWidth(cluster: string): number {
+  return stringWidth(cluster);
+}
+
+/** Strip SGR (color/style) sequences from a string. */
+function stripSGR(str: string): string {
+  return str.replace(/\x1b\[[^m]*m/g, "");
+}
+
+/**
+ * Measure visible string length in terminal columns.
+ * Excludes SGR (color/style) sequences, and counts each grapheme cluster
+ * (emoji, CJK, combining marks) as one terminal-visible unit.
+ */
+export function visibleLen(str: string): number {
+  return stringWidth(stripSGR(str));
+}
+
+/**
+ * Truncate a string to fit within `maxWidth` visible columns.
+ * Iterates by grapheme cluster so emoji sequences (ZWJ, flags, VS16) are
+ * kept intact rather than split mid-cluster. Appends `…` if truncated.
+ */
+export function truncateToWidth(str: string, maxWidth: number): string {
+  const clean = stripSGR(str);
+  if (maxWidth <= 0) return "";
+  if (visibleLen(clean) <= maxWidth) return clean;
+  if (maxWidth === 1) return "…";
+  const target = maxWidth - 1;
+  let width = 0;
+  let out = "";
+  for (const { segment } of GRAPHEME_SEGMENTER.segment(clean)) {
+    const cw = clusterWidth(segment);
+    if (width + cw > target) break;
+    width += cw;
+    out += segment;
+  }
+  if (out === "") return "…";
+  return out + "…";
+}
+
+/** Truncate to visible width while preserving SGR sequences — use when
+ *  input carries color/bold codes. `truncateToWidth` strips them. */
+export function truncateAnsiToWidth(str: string, maxWidth: number): string {
+  if (maxWidth <= 0) return "";
+  if (visibleLen(str) <= maxWidth) return str;
+  if (maxWidth === 1) return "…";
+  const target = maxWidth - 1;
+
+  // Walk the string preserving SGR escapes in-place; buffer text between
+  // escapes and segment it into graphemes to count width correctly.
+  let width = 0;
+  let out = "";
+  let buf = "";
+  let i = 0;
+  const flushBuf = (): boolean => {
+    if (!buf) return false;
+    for (const { segment } of GRAPHEME_SEGMENTER.segment(buf)) {
+      const cw = clusterWidth(segment);
+      if (width + cw > target) {
+        buf = "";
+        return true; // budget exhausted
+      }
+      width += cw;
+      out += segment;
+    }
+    buf = "";
+    return false;
+  };
+
+  while (i < str.length) {
+    if (str[i] === "\x1b" && str[i + 1] === "[") {
+      const end = str.indexOf("m", i);
+      if (end !== -1) {
+        if (flushBuf()) break;
+        out += str.slice(i, end + 1);
+        i = end + 1;
+        continue;
+      }
+    }
+    const cp = str.codePointAt(i) ?? 0;
+    const chLen = cp > 0xffff ? 2 : 1;
+    buf += str.slice(i, i + chLen);
+    i += chLen;
+  }
+  flushBuf();
+  return out + "\x1b[0m…";
+}
+
+/**
+ * Pad a string with spaces to fill `targetWidth` visible columns.
+ */
+export function padEndToWidth(str: string, targetWidth: number): string {
+  const gap = targetWidth - visibleLen(str);
+  return gap > 0 ? str + " ".repeat(gap) : str;
+}
+
+/** Strip ANSI escape sequences and carriage returns.
+ *  Delegates escape handling to the `strip-ansi` package (covers SGR, OSC,
+ *  CSI, private-mode, 8-bit CSI, and newer variants). `\r` is not an escape
+ *  but callers rely on it being stripped alongside. */
+export function stripAnsi(str: string): string {
+  return stripAnsiPkg(str).replace(/\r/g, "");
+}

package/src/utils/box-frame.ts

@@ -0,0 +1,138 @@
+/**
+ * Box frame component for bordered TUI panels.
+ *
+ * Follows the render(width) -> string[] protocol — pure function,
+ * never writes to stdout. Supports multiple border styles and
+ * optional title/footer sections with dividers.
+ */
+import { visibleLen, truncateToWidth, truncateAnsiToWidth } from "./ansi.js";
+import { palette as p } from "./palette.js";
+
+// ── Types ────────────────────────────────────────────────────────
+
+export type BorderStyle = "rounded" | "square" | "double" | "heavy";
+
+interface BorderChars {
+  tl: string; // top-left
+  tr: string; // top-right
+  bl: string; // bottom-left
+  br: string; // bottom-right
+  h: string;  // horizontal
+  v: string;  // vertical
+  ml: string; // middle-left (├)
+  mr: string; // middle-right (┤)
+}
+
+const BORDERS: Record<BorderStyle, BorderChars> = {
+  rounded: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│", ml: "├", mr: "┤" },
+  square:  { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│", ml: "├", mr: "┤" },
+  double:  { tl: "╔", tr: "╗", bl: "╚", br: "╝", h: "═", v: "║", ml: "╠", mr: "╣" },
+  heavy:   { tl: "┏", tr: "┓", bl: "┗", br: "┛", h: "━", v: "┃", ml: "┣", mr: "┫" },
+};
+
+export interface BoxFrameOptions {
+  /** Total width including borders. */
+  width: number;
+  /** Border style. Default "rounded". */
+  style?: BorderStyle;
+  /** Border color (ANSI escape). Default DIM. */
+  borderColor?: string;
+  /** Title text shown on the left of the top border. */
+  title?: string;
+  /** Title text shown on the right of the top border. */
+  titleRight?: string;
+  /** Footer lines shown below a divider, inside the box. */
+  footer?: string[];
+  /** Raw bg ANSI open code (e.g. "\x1b[48;2;40;50;40m"). When set, fills
+   *  the frame interior with this bg and rewrites internal `\x1b[49m` /
+   *  `\x1b[0m` resets so per-cell colors in content don't punch holes. */
+  bgColor?: string;
+}
+
+// ── Public API ───────────────────────────────────────────────────
+
+/**
+ * Render content lines inside a bordered frame.
+ *
+ * @param content - Array of pre-rendered content lines (no border)
+ * @param opts - Frame options
+ * @returns Array of terminal-ready lines with borders
+ */
+export function renderBoxFrame(content: string[], opts: BoxFrameOptions): string[] {
+  const { width: rawWidth, borderColor = p.dim } = opts;
+  const width = Math.max(6, rawWidth);
+  const style = opts.style ?? "rounded";
+  const b = BORDERS[style];
+  const bc = borderColor;
+  const bg = opts.bgColor ?? "";
+
+  // Content area width = total - 2 borders - 2 padding spaces
+  const innerW = Math.max(1, width - 4);
+  const output: string[] = [];
+
+  // Top border (with optional left/right titles)
+  if (opts.title || opts.titleRight) {
+    // Budget: 2 corners + 1 minimum dash + space-padding around each title.
+    // Truncate the left title first if combined widths overflow — titleRight
+    // is typically short metadata (model name, stats) worth preserving.
+    let title = opts.title;
+    const rightVis = opts.titleRight ? visibleLen(opts.titleRight) + 2 : 0;
+    const leftBudget = width - 2 - 1 - rightVis; // total - corners - min dash - right
+    let leftVis = title ? visibleLen(title) + 2 : 0;
+    if (title && leftVis > leftBudget) {
+      const maxTitleVis = Math.max(1, leftBudget - 2);
+      title = truncateAnsiToWidth(title, maxTitleVis);
+      leftVis = visibleLen(title) + 2;
+    }
+    const leftPart = title ? `${p.reset} ${title} ${bc}` : "";
+    const rightPart = opts.titleRight ? `${p.reset} ${opts.titleRight} ${bc}` : "";
+
+    const dashCount = Math.max(1, width - 2 - leftVis - rightVis);
+    output.push(
+      paintBg(`${bc}${b.tl}${leftPart}${b.h.repeat(dashCount)}${rightPart}${b.tr}${p.reset}`, bg),
+    );
+  } else {
+    output.push(paintBg(`${bc}${b.tl}${b.h.repeat(width - 2)}${b.tr}${p.reset}`, bg));
+  }
+
+  // Content lines
+  for (const line of content) {
+    output.push(paintBg(boxLine(line, innerW, b.v, bc), bg));
+  }
+
+  // Footer with divider
+  if (opts.footer && opts.footer.length > 0) {
+    output.push(paintBg(`${bc}${b.ml}${b.h.repeat(width - 2)}${b.mr}${p.reset}`, bg));
+    for (const line of opts.footer) {
+      output.push(paintBg(boxLine(line, innerW, b.v, bc), bg));
+    }
+  }
+
+  // Bottom border
+  output.push(paintBg(`${bc}${b.bl}${b.h.repeat(width - 2)}${b.br}${p.reset}`, bg));
+
+  return output;
+}
+
+/** Wrap a line with a uniform bg, rewriting internal `\x1b[49m` (bg-default)
+ *  and `\x1b[0m` (full-reset) so embedded colors don't punch through. */
+function paintBg(line: string, bg: string): string {
+  if (!bg) return line;
+  const fixed = line
+    .replaceAll("\x1b[49m", bg)
+    .replaceAll("\x1b[0m", "\x1b[0m" + bg);
+  return `${bg}${fixed}\x1b[49m`;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function boxLine(text: string, innerW: number, v: string, bc: string): string {
+  const textWidth = visibleLen(text);
+  if (textWidth > innerW) {
+    // Content is too wide — truncate to fit exactly
+    const truncated = truncateToWidth(text, innerW);
+    return `${bc}${v}${p.reset} ${truncated} ${bc}${v}${p.reset}`;
+  }
+  const pad = innerW - textWidth;
+  return `${bc}${v}${p.reset} ${text}${" ".repeat(pad)} ${bc}${v}${p.reset}`;
+}

package/src/utils/compositor.ts

@@ -0,0 +1,157 @@
+/**
+ * Compositor — routes named render streams to surfaces.
+ *
+ * Components write to named streams ("agent", "query", "status").
+ * The compositor decides where each stream actually goes based on
+ * the current routing table.  Extensions override routing with
+ * `redirect()` to capture output (e.g. overlay panels).
+ *
+ * Streams are hierarchical: "agent:diff" falls back to "agent" if
+ * no override or default is registered for "agent:diff" specifically.
+ * This enables fine-grained interception — redirect just diffs into
+ * a panel, or just a subagent's output ("agent:sub:abc123"), while
+ * everything else flows to the parent stream's surface.
+ *
+ *   // tui-renderer registers default surfaces
+ *   compositor.setDefault("agent", stdoutSurface);
+ *
+ *   // overlay-agent redirects when active
+ *   const restore = compositor.redirect("agent", panelSurface);
+ *   // ... later ...
+ *   restore();  // back to stdout
+ *
+ *   // fine-grained: redirect only diffs to a viewer panel
+ *   compositor.redirect("agent:diff", diffPanelSurface);
+ *   // "agent:text", "agent:tool" etc. still go to stdout
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { EventBus } from "../core/event-bus.js";
+
+/**
+ * A surface accepts rendered output.  Stdout is a surface.
+ * A floating panel's content area is a surface.  A test buffer is a surface.
+ */
+export interface RenderSurface {
+  /** Raw write — supports \r, partial lines, escape codes. */
+  write(text: string): void;
+  /** Convenience: write + newline. */
+  writeLine(line: string): void;
+  /** Available width in columns. */
+  readonly columns: number;
+  /** Available height in rows. */
+  readonly rows: number;
+  /** Subscribe to size changes. Returns unsubscribe. */
+  onResize(cb: (cols: number, rows: number) => void): () => void;
+}
+
+export interface Compositor {
+  /** Get the currently active surface for a stream. */
+  surface(stream: string): RenderSurface;
+
+  /** Override routing: redirect a stream to a different surface.
+   *  Returns a restore function that undoes the redirect. */
+  redirect(stream: string, target: RenderSurface): () => void;
+
+  /** Register the default surface for a stream. */
+  setDefault(stream: string, target: RenderSurface): void;
+}
+
+/** Silent sink — drops all output. Used when no surface is registered. */
+export const nullSurface: RenderSurface = {
+  write() {},
+  writeLine() {},
+  get columns() { return 80; },
+  get rows() { return 24; },
+  onResize() { return () => {}; },
+};
+
+/** Surface backed by process.stdout — the only sanctioned bridge to it. */
+export class StdoutSurface implements RenderSurface {
+  write(text: string): void {
+    if (process.stdout.writable) {
+      // OPOST is cleared on the TTY; add CR to lone \n so we don't staircase.
+      try { process.stdout.write(text.replace(/(?<!\r)\n/g, "\r\n")); } catch { /* ignore */ }
+    }
+  }
+  writeLine(line: string): void {
+    this.write(line + "\n");
+  }
+  get columns(): number {
+    return process.stdout.columns || 80;
+  }
+  get rows(): number {
+    return process.stdout.rows || 24;
+  }
+  onResize(cb: (cols: number, rows: number) => void): () => void {
+    const handler = () => cb(this.columns, this.rows);
+    process.stdout.on("resize", handler);
+    return () => { process.stdout.off("resize", handler); };
+  }
+}
+
+export class DefaultCompositor implements Compositor {
+  private defaults = new Map<string, RenderSurface>();
+  private overrides = new Map<string, RenderSurface[]>();
+  private readonly bus?: EventBus;
+
+  constructor(bus?: EventBus) {
+    this.bus = bus;
+  }
+
+  surface(stream: string): RenderSurface {
+    const stack = this.overrides.get(stream);
+    if (stack && stack.length > 0) return stack[stack.length - 1]!;
+    if (this.defaults.has(stream)) return this.defaults.get(stream)!;
+
+    // Hierarchical fallback: "agent:diff" → "agent"
+    const colon = stream.lastIndexOf(":");
+    if (colon !== -1) return this.surface(stream.slice(0, colon));
+
+    return nullSurface;
+  }
+
+  redirect(stream: string, target: RenderSurface): () => void {
+    const wrapped = this.wrap(stream, target);
+    let stack = this.overrides.get(stream);
+    if (!stack) {
+      stack = [];
+      this.overrides.set(stream, stack);
+    }
+    stack.push(wrapped);
+
+    let restored = false;
+    return () => {
+      if (restored) return;
+      restored = true;
+      const s = this.overrides.get(stream);
+      if (!s) return;
+      const idx = s.indexOf(wrapped);
+      if (idx !== -1) s.splice(idx, 1);
+    };
+  }
+
+  setDefault(stream: string, target: RenderSurface): void {
+    this.defaults.set(stream, this.wrap(stream, target));
+  }
+
+  /** Wrap a surface so writes emit `compositor:write` before delegating. */
+  private wrap(stream: string, target: RenderSurface): RenderSurface {
+    const bus = this.bus;
+    if (!bus) return target;
+    return {
+      write: (text: string) => {
+        try { bus.emit("compositor:write", { stream, text }); } catch {}
+        target.write(text);
+      },
+      writeLine: (line: string) => {
+        try { bus.emit("compositor:write", { stream, text: line + "\n" }); } catch {}
+        target.writeLine(line);
+      },
+      get columns() { return target.columns; },
+      get rows() { return target.rows; },
+      onResize: (cb) => target.onResize(cb),
+    };
+  }
+}