path: root/pi-ext/slop-tool-boxes.ts

/**
 * sl0p Tool Boxes
 *
 * Reframes the built-in tool rows (bash, read, edit, write, grep, find, ls)
 * in the same rounded-border "sl0peration" style used by the last-prompt
 * topbar widget — a labelled top border, side rails, and a rounded bottom. While
 * a tool executes the top/bottom borders pulse and the side rails are gray
 * dotted; when it finalizes the rails solidify to the status color.
 *
 * It does NOT reimplement tool behavior or output: it grabs each built-in
 * tool *definition* (execute + native renderCall/renderResult, so syntax
 * highlighting, diffs, truncation warnings etc. are preserved) and wraps the
 * lines those native renderers produce inside the frame.
 *
 * Border/state palette (matches last-prompt.ts):
 *   pending  -> warning  (◉)
 *   success  -> dim      (✓)
 *   error    -> error    (✗)
 *
 * Note: overriding built-in tools makes interactive mode print a one-time
 * "overriding built-in tool" warning per tool. That is expected.
 */

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import {
  createBashToolDefinition,
  createReadToolDefinition,
  createEditToolDefinition,
  createWriteToolDefinition,
  createGrepToolDefinition,
  createFindToolDefinition,
  createLsToolDefinition,
  keyHint,
} from "@earendil-works/pi-coding-agent";
import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";

// Minimal structural types so we don't fight the full generics.
type Theme = any;
type Component = { render(width: number): string[]; invalidate?: () => void };
type ToolDef = {
  name: string;
  label?: string;
  description: string;
  parameters: any;
  promptSnippet?: string;
  execute: (...a: any[]) => any;
  renderCall?: (args: any, theme: Theme, context: any) => Component;
  renderResult?: (result: any, options: any, theme: Theme, context: any) => Component;
};

const H = "─";
const V = "│";
const DOTTED_RAIL = "┊"; // gray dotted side rail while a tool is in-flight
const TL = "╭";
const TR = "╮";
const BL = "╰";
const BR = "╯";

type Status = "pending" | "ok" | "error";
type Paint = (s: string) => string;

function borderColorFor(status: Status): string {
  return status === "error" ? "error" : status === "pending" ? "warning" : "dim";
}

// ── Pulsing border for in-progress tools ────────────────────────────────────
// Design after three flicker bugs — the invariant is: WE NEVER FORCE A REPAINT.
//
// 1. "Active" is driven strictly by live tool_execution_start/end events keyed
//    by toolCallId, never by render-time status. On session restore (`pi -c`)
//    finished rows re-render but fire no start event, so they never animate.
//    (An earlier version inferred "pending" from the default status and started
//    a 10fps invalidate storm over every restored row — the startup lockup.)
//
// 2. There is NO animation timer. The pulse color is a pure function of
//    wall-clock time, so any render shows the current color. It advances only
//    on renders that were going to happen anyway — chiefly the natural re-renders
//    that streaming tool output already triggers ("the stream hydrates the
//    pulse", with irregular cadence). Forcing periodic re-renders of a large,
//    taller-than-screen streaming box is exactly what flickered. A silent tool
//    just holds a static active color until it streams output or finishes.
//
// 3. Only the horizontal top/bottom borders pulse. The body side rails are a
//    STATIC color (gray dotted while in-flight, solid status color once
//    settled), so a repaint never has to recolor body lines.
const PULSE: Array<[number, number, number]> = [
  [0xff, 0x8a, 0x1e], // amber
  [0xff, 0x2e, 0x88], // hot pink
  [0xb0, 0x5c, 0xff], // violet
  [0x2e, 0xd6, 0xff], // cyan
];
const CYCLE_MS = 4000; // one full palette trip (~4s), advanced by wall-clock time

function lerp(a: number, b: number, t: number): number {
  return Math.round(a + (b - a) * t);
}
function pulseRGB(phase: number): [number, number, number] {
  const n = PULSE.length;
  const x = ((((phase % 1) + 1) % 1) * n);
  const i = Math.floor(x) % n;
  const j = (i + 1) % n;
  const t = x - Math.floor(x);
  const a = PULSE[i];
  const b = PULSE[j];
  return [lerp(a[0], b[0], t), lerp(a[1], b[1], t), lerp(a[2], b[2], t)];
}
function fgRGB(rgb: [number, number, number], s: string): string {
  return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${s}\x1b[39m`;
}

const activeIds = new Set<string>(); // toolCallIds executing in THIS session
const rowsById = new Map<string, FrameState>(); // toolCallId -> row state (start/end nudges)
// toolCallId -> execution timing. `end` is set on tool_execution_end; while a
// tool is still running `end` is undefined and elapsed is measured live (only
// advancing on renders that were going to happen anyway — no forced repaint).
const timingById = new Map<string, { start: number; end?: number }>();

// Tools that get a right-aligned runtime stamped into their bottom border.
const RUNTIME_TOOLS = new Set<string>(["bash"]);

function fmtDuration(ms: number): string {
  if (ms < 1000) return `${Math.round(ms)}ms`;
  const s = ms / 1000;
  if (s < 10) return `${s.toFixed(1)}s`;
  if (s < 60) return `${Math.round(s)}s`;
  const m = Math.floor(s / 60);
  const rem = Math.round(s % 60);
  return `${m}m${rem}s`;
}

// Painted ` 1.2s ` label for the bottom border, or undefined if untimed.
function runtimeLabel(st: FrameState, theme: Theme): string | undefined {
  const id = st.toolCallId;
  if (!id) return undefined;
  const t = timingById.get(id);
  if (!t) return undefined;
  const ms = (t.end ?? Date.now()) - t.start;
  return " " + theme.fg("muted", fmtDuration(ms)) + " ";
}

function pulsePaint(): Paint {
  // Pure function of wall-clock time — no counter, no timer.
  const rgb = pulseRGB((Date.now() % CYCLE_MS) / CYCLE_MS);
  return (s: string) => fgRGB(rgb, s);
}
function solidPaint(theme: Theme, color: string): Paint {
  return (s: string) => theme.fg(color, s);
}

function markActive(id: string | undefined): void {
  if (id) activeIds.add(id);
}
function clearActive(id: string | undefined): void {
  if (id) activeIds.delete(id);
}
// Settle any still-active rows (e.g. a missed end event) and clear. No timer.
function stopAllAnim(): void {
  for (const id of activeIds) rowsById.get(id)?.ctxInvalidate?.();
  activeIds.clear();
}

function statusIcon(status: Status, theme: Theme): string {
  if (status === "error") return theme.fg("error", "✗");
  if (status === "pending") return theme.fg("warning", "◉");
  return theme.fg("success", "✓");
}

// Collapse $HOME to ~ for tidier header paths.
function prettyPath(p: string): string {
  const home = process.env.HOME;
  return home && p.startsWith(home) ? "~" + p.slice(home.length) : p;
}

function stripAnsi(s: string): string {
  // eslint-disable-next-line no-control-regex
  return s.replace(/\x1b\[[0-9;]*m/g, "");
}

// ── Diff line backgrounds (edit tool) ───────────────────────────────────────
const DIFF_ADDED_BG = "#123521"; // dark green fill behind added lines
const DIFF_REMOVED_BG = "#3a1620"; // dark red fill behind removed lines

function hexBg(hex: string, s: string): string {
  const h = hex.replace("#", "");
  const r = parseInt(h.slice(0, 2), 16);
  const g = parseInt(h.slice(2, 4), 16);
  const b = parseInt(h.slice(4, 6), 16);
  return `\x1b[48;2;${r};${g};${b}m${s}\x1b[49m`;
}

// Remove any background SGR codes so our diff background is the only one and
// isn't overridden by the native edit component's per-line Box background.
function stripBg(s: string): string {
  return s
    // eslint-disable-next-line no-control-regex
    .replace(/\x1b\[48;2;\d+;\d+;\d+m/g, "")
    // eslint-disable-next-line no-control-regex
    .replace(/\x1b\[48;5;\d+m/g, "")
    // eslint-disable-next-line no-control-regex
    .replace(/\x1b\[(?:4[0-7]|10[0-7]|49)m/g, "");
}

// Fill added/removed diff rows with a background across the full inner width.
// Detects the leading +/- marker (ignoring +++/--- headers) on the stripped
// text; context/other lines are left untouched.
function applyDiffBackgrounds(lines: string[], bodyInner: number): string[] {
  return lines.map((line) => {
    // Drop the native per-line background so ours actually shows.
    const stripped = stripBg(line);
    // The native edit component indents diff rows (Box padding), so look at the
    // first non-space char for the +/- marker (ignoring +++/--- headers).
    const t = stripAnsi(stripped).replace(/^\s+/, "");
    let bg: string | undefined;
    if (t[0] === "+" && t[1] !== "+") bg = DIFF_ADDED_BG;
    else if (t[0] === "-" && t[1] !== "-") bg = DIFF_REMOVED_BG;
    if (!bg) return stripped; // context/other rows: native tint removed, no fill
    let s = stripped;
    if (visibleWidth(s) > bodyInner) s = truncateToWidth(s, bodyInner, "…");
    const pad = Math.max(0, bodyInner - visibleWidth(s));
    return hexBg(bg, s + " ".repeat(pad));
  });
}

// When we hoist the path into the header, drop the native call's redundant
// leading "<tool> <path>" line (and any following blank spacer) while keeping
// the rest of its body (e.g. edit renders its diff in renderCall).
function stripRedundantCallLines(lines: string[], name: string): string[] {
  let i = 0;
  while (i < lines.length) {
    const t = stripAnsi(lines[i]).trim();
    if (t === "" || t === name || t.startsWith(name + " ")) {
      i++;
      continue;
    }
    break;
  }
  return lines.slice(i);
}

// Per-tool header summary: the key argument hoisted into the top border so we
// can drop the redundant native call line (e.g. "edit <path>").
const HEADER_SUMMARY: Record<string, (args: any) => string | undefined> = {
  edit: (a) => (a?.path ? prettyPath(a.path) : undefined),
  read: (a) => (a?.path ? prettyPath(a.path) : undefined),
  write: (a) => (a?.path ? prettyPath(a.path) : undefined),
  ls: (a) => (a?.path ? prettyPath(a.path) : undefined),
};

const READ_PREVIEW_LINES = 10;

// Per-tool result-body override. Returning undefined falls back to the native
// renderResult. Read hides its content unless expanded, so we synthesize a
// short inline preview of the chunk it read (native full output on expand).
const RESULT_PREVIEW: Record<
  string,
  (result: any, options: any, theme: Theme) => string[] | undefined
> = {
  read: (result, options, theme) => {
    if (options?.expanded) return undefined; // expanded -> use native full output
    const block = Array.isArray(result?.content)
      ? result.content.find((b: any) => b?.type === "text")
      : undefined;
    const text = typeof block?.text === "string" ? block.text : "";
    if (!text.trim()) return undefined;
    const all = text.split("\n");
    while (all.length && all[all.length - 1].trim() === "") all.pop();
    const shown = all.slice(0, READ_PREVIEW_LINES).map((l: string) => theme.fg("toolOutput", l));
    const more = all.length - READ_PREVIEW_LINES;
    if (more > 0) {
      shown.push(theme.fg("muted", `… ${more} more lines (`) + keyHint("app.tools.expand", "to expand") + theme.fg("muted", ")"));
    }
    return shown;
  },
};

// Top border: ╭─ ✓ bash ───────────────╮   (label carries its own colors)
function frameTop(width: number, label: string, paint: Paint): string {
  const innerWidth = Math.max(0, width - 2);
  const leftLen = innerWidth > 2 ? 1 : 0;
  let content = ` ${label} `;
  // Keep at least one trailing dash; truncate an over-long header so it never
  // overflows the box width.
  const maxContent = Math.max(0, innerWidth - leftLen - 1);
  if (visibleWidth(content) > maxContent) content = truncateToWidth(content, maxContent, "…");
  const rightLen = Math.max(0, innerWidth - leftLen - visibleWidth(content));
  return (
    paint(TL) +
    paint(H.repeat(leftLen)) +
    content +
    paint(H.repeat(rightLen)) +
    paint(TR)
  );
}

// Bottom border, optionally with an already-painted `label` stamped near the
// right edge (kept clear of the corner by one trailing dash). Falls back to a
// plain border if the label can't fit.
function frameBottom(width: number, paint: Paint, label?: string): string {
  const innerWidth = Math.max(0, width - 2);
  if (label) {
    const segW = visibleWidth(label);
    const rightLen = 1;
    if (segW + rightLen + 1 <= innerWidth) {
      const leftLen = innerWidth - segW - rightLen;
      return paint(BL + H.repeat(leftLen)) + label + paint(H.repeat(rightLen) + BR);
    }
  }
  return paint(BL + H.repeat(innerWidth) + BR);
}

// Wrap inner lines with side rails. `rail` is the ALREADY-PAINTED rail glyph
// (gray dotted while in-flight, solid status-colored when settled). Crucially the
// rail is a STATIC string for the whole render pass — it does not carry the
// pulse — so streaming output never recolors existing body lines and can't cause
// a full-box repaint. Only the horizontal top/bottom borders pulse.
function frameBody(lines: string[], width: number, rail: string): string[] {
  const innerWidth = Math.max(0, width - 4); // 2 rails + 2 padding spaces
  return lines.map((raw) => {
    let line = raw;
    if (visibleWidth(line) > innerWidth) line = truncateToWidth(line, innerWidth, "…");
    const pad = Math.max(0, innerWidth - visibleWidth(line));
    return `${rail} ${line}${" ".repeat(pad)} ${rail}`;
  });
}

type FrameState = {
  inner: Record<string, unknown>; // private state bag handed to the native renderer
  callInner?: Component;
  resultInner?: Component;
  status: Status;
  resultActive: boolean; // true once the result slot starts rendering (it then owns the bottom border)
  ctxInvalidate?: () => void; // row rerender trigger (updateDisplay + requestRender)
  toolCallId?: string; // used to match live tool_execution_start/end events
  // Inner-line caches persisted on the row state so they survive updateDisplay()
  // rebuilds. Keyed by width; reset when the underlying args/result change (or on
  // invalidate/theme change).
  callArgsRef?: any;
  summaryText?: string;
  callW: number;
  callLines?: string[];
  resultRef?: any;
  resultExpanded?: boolean;
  resultW: number;
  resultLines?: string[];
};

function ensureState(context: any): FrameState {
  if (!context.state.__slopFrame) {
    context.state.__slopFrame = {
      inner: {},
      status: "pending" as Status,
      resultActive: false,
      callW: -1,
      resultW: -1,
    };
  }
  const st = context.state.__slopFrame as FrameState;
  if (context.toolCallId) {
    st.toolCallId = context.toolCallId;
    rowsById.set(context.toolCallId, st);
  }
  return st;
}

// A row animates only if its tool is executing in THIS session (event-driven).
function isActiveRow(st: FrameState): boolean {
  return !!st.toolCallId && activeIds.has(st.toolCallId);
}

// A context for the native renderer: its own state bag + its own lastComponent.
function childCtx(context: any, st: FrameState, slot: "call" | "result") {
  return {
    ...context,
    state: st.inner,
    lastComponent: slot === "call" ? st.callInner : st.resultInner,
  };
}

function registerFramedTool(pi: ExtensionAPI, def: ToolDef) {
  const displayName = def.name;
  const summarize = HEADER_SUMMARY[def.name];

  pi.registerTool({
    name: def.name,
    label: def.label ?? def.name,
    description: def.description,
    parameters: def.parameters,
    promptSnippet: def.promptSnippet,
    renderShell: "self", // we draw our own frame + background

    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return def.execute(toolCallId, params, signal, onUpdate, ctx);
    },

    renderCall(args, theme, context) {
      const st = ensureState(context);
      st.ctxInvalidate = context.invalidate;
      // Rebuild the native call component only when the args actually change
      // (not on every pulse-driven updateDisplay). edit draws its diff here; the
      // redundant leading "<tool> <path>" line is stripped in the inner cache.
      if (args !== st.callArgsRef) {
        st.callInner = def.renderCall
          ? def.renderCall(args, theme, childCtx(context, st, "call"))
          : undefined;
        st.callArgsRef = args;
        st.summaryText = summarize ? summarize(args) : undefined;
        st.callW = -1;
      }
      // (Whether this row animates is decided by live tool_execution events, not
      // here — see isActiveRow / the event handlers in the default export.)

      // Inner-line cache lives on `st` (survives updateDisplay). Only the native
      // render + diff regex are expensive; the frame is rebuilt cheaply so it can
      // re-paint with the pulse color per render without recomputing content.
      const innerLines = (width: number): string[] => {
        if (st.callW === width && st.callLines) return st.callLines;
        let lines = st.callInner ? st.callInner.render(Math.max(1, width - 4)) : [];
        if (st.summaryText) lines = stripRedundantCallLines(lines, displayName);
        if (displayName === "edit") lines = applyDiffBackgrounds(lines, Math.max(1, width - 4));
        st.callW = width;
        st.callLines = lines;
        return lines;
      };

      let cw = -1;
      let cl: string[] = [];
      return {
        render(width: number): string[] {
          const activeNow = isActiveRow(st);
          const status: Status = activeNow ? "pending" : st.status;
          const base =
            statusIcon(status, theme) + " " + theme.fg("toolTitle", theme.bold(displayName));
          const label = st.summaryText ? base + " " + theme.fg("accent", st.summaryText) : base;
          const inner = innerLines(width);
          // IMPORTANT (anti-flicker): the side rails + body use a STATIC status
          // color; only the horizontal top/bottom borders pulse. Pulsing the
          // rails recolors every body line each frame, which forces a full-box
          // repaint while a tool streams output (edit/write) and reads as violent
          // flicker. Keeping rails static means streaming only redraws the new
          // content line, and the pulse only touches 1-2 border lines. (NOTES.md)
          const rt = RUNTIME_TOOLS.has(displayName) ? runtimeLabel(st, theme) : undefined;
          const build = (border: Paint, rail: string): string[] => {
            const out = [frameTop(width, label, border), ...frameBody(inner, width, rail)];
            // While the result slot hasn't started rendering yet (still-running
            // tool), close the box here so the frame is never bottomless.
            if (!st.resultActive) out.push(frameBottom(width, border, rt));
            return out;
          };
          if (activeNow) {
            cw = -1; // don't cache while animating; recompute solid once settled
            // in-flight: pulsing top/bottom borders + STATIC gray dotted rails
            return build(pulsePaint(), theme.fg("muted", DOTTED_RAIL));
          }
          if (width === cw) return cl;
          // settled: solid borders + rails in the status color
          const solid = solidPaint(theme, borderColorFor(status));
          cl = build(solid, theme.fg(borderColorFor(status), V));
          cw = width;
          return cl;
        },
        invalidate() {
          cw = -1;
          st.callW = -1;
          st.callArgsRef = undefined; // rebuild native on theme change
          st.callInner?.invalidate?.();
        },
      };
    },

    renderResult(result, options, theme, context) {
      const st = ensureState(context);
      st.ctxInvalidate = context.invalidate;
      st.status = context.isError ? "error" : options.isPartial ? "pending" : "ok";
      st.resultActive = true; // the result slot now owns the bottom border
      // NOTE: do NOT call context.invalidate() here. renderResult runs during
      // rendering, so invalidating would schedule another render that calls
      // renderResult again -> infinite render loop (hangs pi). The pulse timer
      // drives invalidation from OUTSIDE the render pass instead.
      // Rebuild the native result component only when result/expand changes.
      if (result !== st.resultRef || options.expanded !== st.resultExpanded) {
        st.resultInner = def.renderResult
          ? def.renderResult(result, options, theme, childCtx(context, st, "result"))
          : {
              render: () => {
                const c = result?.content?.[0];
                const text = c?.type === "text" ? String(c.text) : "";
                return text.split("\n");
              },
            };
        st.resultRef = result;
        st.resultExpanded = options.expanded;
        st.resultW = -1;
      }
      // (Animation is event-driven; see isActiveRow / default export handlers.)
      const preview = RESULT_PREVIEW[displayName];

      const innerLines = (width: number): string[] => {
        if (st.resultW === width && st.resultLines) return st.resultLines;
        let lines: string[] | undefined;
        if (preview) lines = preview(result, options, theme);
        if (lines === undefined) {
          lines = st.resultInner ? st.resultInner.render(Math.max(1, width - 4)) : [];
        }
        // Completed edits render their diff in the result slot — give +/- rows a bg.
        if (displayName === "edit") lines = applyDiffBackgrounds(lines, Math.max(1, width - 4));
        st.resultW = width;
        st.resultLines = lines;
        return lines;
      };

      let cw = -1;
      let cl: string[] = [];
      return {
        render(width: number): string[] {
          const inner = innerLines(width);
          const activeNow = isActiveRow(st);
          // in-flight: gray dotted rails; settled: solid status-colored rails.
          const railStr = activeNow
            ? theme.fg("muted", DOTTED_RAIL)
            : theme.fg(borderColorFor(st.status), V);
          const rt = RUNTIME_TOOLS.has(displayName) ? runtimeLabel(st, theme) : undefined;
          const build = (border: Paint): string[] => [
            ...frameBody(inner, width, railStr),
            frameBottom(width, border, rt),
          ];
          if (activeNow) {
            cw = -1;
            return build(pulsePaint());
          }
          if (width === cw) return cl;
          cl = build(solidPaint(theme, borderColorFor(st.status)));
          cw = width;
          return cl;
        },
        invalidate() {
          cw = -1;
          st.resultW = -1;
          st.resultRef = undefined; // rebuild native on theme change
          st.resultInner?.invalidate?.();
        },
      };
    },
  });
}

export default function (pi: ExtensionAPI) {
  const cwd = process.cwd();
  const defs: ToolDef[] = [
    createBashToolDefinition(cwd) as unknown as ToolDef,
    createReadToolDefinition(cwd) as unknown as ToolDef,
    createEditToolDefinition(cwd) as unknown as ToolDef,
    createWriteToolDefinition(cwd) as unknown as ToolDef,
    createGrepToolDefinition(cwd) as unknown as ToolDef,
    createFindToolDefinition(cwd) as unknown as ToolDef,
    createLsToolDefinition(cwd) as unknown as ToolDef,
  ];

  for (const def of defs) registerFramedTool(pi, def);

  // Animation is driven ONLY by live execution events, so restored/finished rows
  // (e.g. on `pi -c`) never animate. A row pulses from tool_execution_start until
  // tool_execution_end; the refresh() nudges the row to repaint immediately.
  const refresh = (id: string | undefined) => {
    if (id) rowsById.get(id)?.ctxInvalidate?.();
  };
  pi.on("tool_execution_start", (event: any) => {
    markActive(event.toolCallId);
    if (event.toolCallId) timingById.set(event.toolCallId, { start: Date.now() });
    refresh(event.toolCallId);
  });
  pi.on("tool_execution_end", (event: any) => {
    clearActive(event.toolCallId);
    const t = event.toolCallId ? timingById.get(event.toolCallId) : undefined;
    if (t) t.end = Date.now();
    refresh(event.toolCallId);
  });

  // Safety net: guarantee the timer stops even if an end event is missed
  // (abort/error). agent_settled fires when the run is no longer producing tool
  // output; session_shutdown on teardown.
  pi.on("agent_settled", stopAllAnim);
  pi.on("session_shutdown", stopAllAnim);
}