pi-minimalist 0.1.0

package/src/tool-renderer.ts

@@ -0,0 +1,260 @@
+/**
+ * FEATURE 1: the compact tool renderer.
+ *
+ * Installed on the process-global bridge `Symbol.for("pi.defaultToolRenderer")`
+ * and consulted by the prototype wrappers in `core-patch.ts`.
+ *
+ * Core overrides RENDERING only. Native tool definitions keep their schema,
+ * `execute()`, and builtin source ownership — that ownership is what lets
+ * pi-subagents expose read/bash/write to child runtimes, so this renderer must
+ * never register tools itself.
+ *
+ * This module owns everything derived from a render CONTEXT: the status glyph,
+ * the elapsed badge, and the per-call cached components.
+ */
+
+import type { Component } from "@earendil-works/pi-tui";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { CompactLine, EmptyComponent, GutteredComponent, realTimers, type Timers } from "./components.ts";
+import { Painter, type ThemeLike } from "./row.ts";
+import { describeTool, isBuiltIn, summaryName } from "./tools.ts";
+import { RunGrouping, type Outcome } from "./run-grouping.ts";
+import type { Config } from "./config.ts";
+
+/**
+ * State shared between renderCall and renderResult through `context.state`
+ * (core's rendererState: one object per tool call, stable across renders).
+ */
+export type RenderState = {
+  /**
+   * Component produced by the ORIGINAL built-in renderResult, so consecutive
+   * expanded re-renders reuse one instance (built-ins inspect lastComponent).
+   */
+  originalResult?: unknown;
+  /**
+   * Cached call row. Core's fallback path never passes lastComponent, so this is
+   * the only stable per-call cache there. Without it every repaint allocated a
+   * fresh row and started another ticker while clearing none.
+   */
+  callLine?: unknown;
+  /** Wall-clock timestamp (ms) of the first render after execution started. */
+  startedAt?: number;
+};
+
+/** The render context fields this module reads. Pi's real context has more. */
+export type CallContext = {
+  toolCallId?: string;
+  state: RenderState;
+  isPartial?: boolean;
+  isError?: boolean;
+  executionStarted?: boolean;
+  expanded?: boolean;
+};
+
+/**
+ * `color` is a real ThemeColor so a mistyped token fails to COMPILE. At runtime
+ * theme.fg() would throw and core would silently fall back to a verbose card.
+ */
+export type Status = {
+  glyph: string;
+  color: ThemeColor;
+  /** The grouping view of the same state, so nothing re-derives it from glyph. */
+  outcome: Outcome;
+  /** Seconds since execution started, or undefined when not timing. */
+  elapsed?: number;
+};
+
+/**
+ * Pick the status glyph, color, and outcome for a render context:
+ * - finished: done glyph in label color; failed: failed glyph in error color
+ * - running:  running glyph, with elapsed seconds
+ * - queued:   queued glyph
+ *
+ * GOTCHA: session replay (restart with history) never calls
+ * markExecutionStarted(), so `executionStarted` stays false for reloaded tools.
+ * "Finished" must therefore key off `!isPartial` (a final result exists), NOT off
+ * `executionStarted`, or every historical tool call shows the queued caret after
+ * a restart. `executionStarted` only separates queued from running while live.
+ */
+export function statusGlyph(context: CallContext, config: Config, now: () => number = Date.now): Status {
+  const glyphs = config.glyphs();
+  const { label, error } = config.tokens();
+
+  if (!context.isPartial) {
+    // Final result present: covers both live completion and replayed history.
+    return context.isError
+      ? { glyph: glyphs.failed, color: error, outcome: "failure" }
+      : { glyph: glyphs.done, color: label, outcome: "success" };
+  }
+  if (context.executionStarted) {
+    const state = context.state;
+    state.startedAt ??= now();
+    return {
+      glyph: glyphs.running,
+      color: label,
+      outcome: "pending",
+      // Omitted entirely when the timer is off, so no ticker is ever started.
+      elapsed: config.get("timer") ? Math.floor((now() - state.startedAt) / 1000) : undefined,
+    };
+  }
+  return { glyph: glyphs.queued, color: label, outcome: "pending" };
+}
+
+/**
+ * Elapsed badge, or "" when not running or under one second.
+ *
+ * Hiding the first second avoids a `[⏱ 0s]` flicker on commands that finish
+ * instantly; the 1s ticker repaints the row once it becomes meaningful.
+ */
+export function timerBadge(elapsed: number | undefined, config: Config): string {
+  if (elapsed === undefined || elapsed < 1) return "";
+  const icon = config.glyphs().timer;
+  // The ASCII preset has no clock glyph, so the badge degrades to `[3s]`.
+  return icon ? `[${icon} ${elapsed}s]` : `[${elapsed}s]`;
+}
+
+/** Original result renderer for this tool, handed to us by the core bridge. */
+export type NativeResultRenderer = (result: any, options: any, theme: any, context: any) => Component;
+
+/** The object stored on the process-global renderer symbol. */
+export type ToolRenderer = {
+  renderShell: "self";
+  handles: (name: string) => boolean;
+  renderCall: (name: string, args: unknown, theme: any, context: any) => CompactLine;
+  renderResult: (
+    name: string,
+    result: any,
+    options: any,
+    theme: any,
+    context: any,
+    nativeRenderer?: NativeResultRenderer,
+  ) => Component | undefined;
+};
+
+export type RendererDeps = {
+  /** Live settings; read at render time so toggles apply to existing history. */
+  config: Config;
+  /** Shared grouping state; injected so existing rows update without a patch. */
+  grouping: RunGrouping;
+  /** Clock for the elapsed timer; injectable so tests need no real sleeping. */
+  now?: () => number;
+  /** Repaint scheduler for the ticker; injectable for fake-timer tests. */
+  timers?: Timers;
+};
+
+/**
+ * Build the renderer.
+ *
+ * A factory, not a module-level singleton, so tests drive the exact production
+ * code path with a deterministic clock and timers.
+ */
+export function createToolRenderer(deps: RendererDeps): ToolRenderer {
+  const { config, grouping } = deps;
+  const now = deps.now ?? Date.now;
+  const timers = deps.timers ?? realTimers;
+
+  return {
+    // One custom line instead of Pi's padded Box shell.
+    renderShell: "self",
+    // Blacklist plus the master switch: every tool compacts unless excluded.
+    handles: (name) => config.compacts(name),
+
+    renderCall(name, args, theme: ThemeLike, context: CallContext & { lastComponent?: unknown; invalidate(): void }) {
+      const status = statusGlyph(context, config, now);
+      const component = reuseRow(context, timers);
+
+      // Tick while running; stop at a terminal state. invalidate() re-runs
+      // updateDisplay (recomputing elapsed) then renders — a plain
+      // requestRender would only repaint stale text. Async ticker fires are
+      // safe; never invalidate SYNCHRONOUSLY from a renderer.
+      if (status.elapsed !== undefined) component.startTicker(() => context.invalidate());
+      else component.stopTicker();
+
+      // Painted at render time, because the detail budget depends on the real
+      // viewport width and TUI only reveals it during render().
+      const paint = (width: number) => {
+        const painter = new Painter(theme, config);
+        const badge = timerBadge(status.elapsed, config);
+        const { label, details } = describeTool(name, args, {
+          expanded: context.expanded === true,
+          budget: detailBudget(width, status.glyph, name, badge),
+          config,
+        });
+        // No background while executing — the animated timer already signals
+        // activity, and a highlight flashing on each repaint was distracting.
+        return painter.labeled({ glyph: status.glyph, glyphColor: status.color, label, badge, details });
+      };
+
+      // EVERY call is observed, so a non-foldable one still cuts a run. Core
+      // always supplies toolCallId; without one, skip grouping rather than let
+      // several id-less rows collapse into one accidental group.
+      const id = context.toolCallId;
+      if (!id) {
+        component.setRow(paint);
+        return component;
+      }
+      grouping.observe(id, summaryName(name, args), status.outcome, context.expanded === true);
+      component.setRow((width) => grouping.rowFor(id, new Painter(theme, config), () => paint(width)));
+      return component;
+    },
+
+    renderResult(name, result, options, theme: ThemeLike, context, nativeRenderer) {
+      // The call row already carries status, so a collapsed result adds no height.
+      if (!options.expanded) return new EmptyComponent();
+
+      // A rendererless third-party tool has no native output to preserve;
+      // `undefined` tells core's fallback path to show its own text output.
+      if (!nativeRenderer) return isBuiltIn(name) ? new EmptyComponent() : undefined;
+
+      // Expanded rows delegate to the tool's ORIGINAL renderer, preserving diffs,
+      // syntax highlighting and MCP result formatting.
+      const state = context.state as RenderState;
+      const component = nativeRenderer(result, options, theme, {
+        // Replace only lastComponent: the native renderer must see ITS component,
+        // not our gutter wrapper.
+        ...context,
+        lastComponent: state.originalResult,
+      });
+      state.originalResult = component;
+
+      const wrapper =
+        context.lastComponent instanceof GutteredComponent
+          ? context.lastComponent
+          : new GutteredComponent(component, new Painter(theme, config).outputGutter());
+      wrapper.setInner(component);
+      return wrapper;
+    },
+  };
+}
+
+/**
+ * Columns left for the detail text after the fixed parts of the row.
+ *
+ * Approximate on purpose: `CompactLine` performs the exact, ANSI-aware
+ * truncation. This only decides which field yields first in a composed detail.
+ */
+function detailBudget(width: number, glyph: string, label: string, badge: string): number {
+  const gutter = 3;
+  const fixed = gutter + glyph.length + 1 + label.length + 1 + (badge ? badge.length + 1 : 0);
+  return Math.max(1, width - fixed);
+}
+
+/**
+ * Reuse the row component across repaints so the TUI updates it in place.
+ *
+ * Two caches on purpose: core's renderer path passes `lastComponent`, but its
+ * FALLBACK path always passes undefined, so `context.state` is the only stable
+ * per-call cache there. Allocating a fresh row per repaint used to start another
+ * 1s ticker while clearing none — an interval leak that froze the UI.
+ */
+function reuseRow(context: CallContext & { lastComponent?: unknown }, timers: Timers): CompactLine {
+  const cached =
+    context.lastComponent instanceof CompactLine
+      ? context.lastComponent
+      : context.state.callLine instanceof CompactLine
+        ? context.state.callLine
+        : undefined;
+  const component = cached ?? new CompactLine(timers);
+  context.state.callLine = component;
+  return component;
+}

package/src/tools.ts

@@ -0,0 +1,195 @@
+/**
+ * Tool vocabulary: how each tool describes itself on one line.
+ *
+ * Pure and deterministic — no components, no theme, no globals. Which tools get
+ * compacted is `Config.compacts()`, not this file.
+ *
+ * `describeTool` returns the label and details SEPARATELY and must never join
+ * them: the painter colors each part, and an earlier version that returned one
+ * string forced the painter to split it back apart on the first space, silently
+ * assuming no label ever contains one.
+ */
+
+import type { Config } from "./config.ts";
+
+/** Native tools with a per-tool details extractor below. */
+// `as const` preserves literal names instead of widening every item to string.
+export const BUILT_INS = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+
+// `(typeof BUILT_INS)[number]` turns the tuple values into a union type.
+export type ToolName = (typeof BUILT_INS)[number];
+
+/** True for native tools with a hand-written one-line description. */
+export function isBuiltIn(name: string): name is ToolName {
+  return BUILT_INS.includes(name as ToolName);
+}
+
+/** MCP tools discovered from their registering extension's source metadata. */
+const mcpTools = new Set<string>();
+
+/**
+ * Refresh after MCP adapter registration.
+ *
+ * No longer decides what gets COMPACTED (the blacklist does that). It is kept
+ * because it decides what gets LABELED `mcp`, which is real information: a bare
+ * `atlassian_getConfluencePage` row does not tell you it crossed an MCP server.
+ */
+export function refreshMcpTools(tools: { name: string; sourceInfo: { path: string } }[]): void {
+  mcpTools.clear();
+  for (const tool of tools) {
+    if (tool.sourceInfo.path.includes("pi-mcp-adapter")) mcpTools.add(tool.name);
+  }
+}
+
+export function isMcpTool(name: string): boolean {
+  return name === "mcp" || name === "mcpScript" || name.startsWith("mcp__") || mcpTools.has(name);
+}
+
+/**
+ * Collapse whitespace and truncate for one-line display.
+ *
+ * `max` is a DISPLAY budget in characters; `hardCap` is a sanity limit that
+ * exists only so a multi-megabyte heredoc is not whitespace-collapsed, colored
+ * and measured on every repaint. Neither is the final word on width —
+ * `CompactLine` truncates at the real viewport column count.
+ */
+export function compact(value: unknown, max = Number.POSITIVE_INFINITY, hardCap = 4000): string {
+  const limit = Math.min(max, hardCap);
+  // Slice BEFORE the regex so a huge string is never fully scanned. The extra
+  // headroom leaves room for whitespace runs that collapse away.
+  const raw = String(value ?? "");
+  const sliced = Number.isFinite(limit) ? raw.slice(0, limit * 2 + 16) : raw.slice(0, hardCap * 2 + 16);
+  // Replacing every whitespace run prevents multi-line call rows.
+  const text = sliced.replace(/\s+/g, " ").trim();
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** Minimum columns a composed field keeps, so it never vanishes entirely. */
+const MIN_FIELD = 12;
+
+export type DescribeOptions = {
+  /** Expanded rows keep full-length details (still on ONE physical line). */
+  expanded?: boolean;
+  /**
+   * Columns available for the details segment.
+   *
+   * Approximate on purpose: `CompactLine` performs the exact, ANSI-aware,
+   * wide-character-aware truncation. This budget only decides WHICH field is
+   * sacrificed when a composed detail (`/pattern/ in path`) cannot fit.
+   */
+  budget?: number;
+  config?: Config;
+};
+
+/**
+ * The one-line description of a call: `read` + `src/a.ts:1-50`, `bash` +
+ * `go test ./...`, or a third-party tool's name plus its most identifying
+ * argument.
+ */
+export function describeTool(name: string, args: any, options: DescribeOptions = {}): { label: string; details: string } {
+  const hardCap = options.config?.get("maxDetailChars") ?? 4000;
+  const budget = options.budget ?? Number.POSITIVE_INFINITY;
+  const a = args ?? {};
+
+  if (name === "mcp") return { label: "mcp", details: mcpDetails(a, budget, hardCap) };
+  if (name === "mcpScript") return { label: "mcpScript", details: compact(a.code, budget, hardCap) };
+  if (name.startsWith("mcp__")) {
+    const server = name.slice("mcp__".length);
+    const tool = compact(a.tool, budget, hardCap);
+    return { label: "mcp", details: tool ? `${tool} @ ${server}` : `@ ${server}` };
+  }
+  if (isMcpTool(name)) return { label: "mcp", details: name };
+  if (isBuiltIn(name)) return { label: name, details: builtInDetails(name, a, options, hardCap) };
+  // Any other tool: show the name plus whichever argument identifies the call.
+  return { label: name, details: genericDetails(a, budget, hardCap) };
+}
+
+/**
+ * Name shown in a folded run summary: the concrete operation, never a category.
+ *
+ * `mcp` rows label themselves `mcp` for readability, but a summary of five
+ * different MCP calls reading `mcp ×5` would hide which servers were touched.
+ */
+export function summaryName(name: string, args: any): string {
+  if (isBuiltIn(name) || name === "mcpScript") return name;
+  if (name === "mcp") return compact(args?.tool) || "mcp";
+  if (name.startsWith("mcp__")) {
+    const tool = compact(args?.tool);
+    return tool ? `${tool} @ ${name.slice("mcp__".length)}` : name;
+  }
+  return name;
+}
+
+function mcpDetails(args: any, budget: number, hardCap: number): string {
+  if (args.tool) return compact(args.tool, budget, hardCap);
+  for (const key of ["search", "describe", "connect", "action"] as const) {
+    if (args[key]) return `${key} ${compact(args[key], budget, hardCap)}`;
+  }
+  return "";
+}
+
+/**
+ * Argument keys worth showing for a tool we know nothing about, most
+ * identifying first. Without this a blacklist default would render every
+ * third-party tool as a bare name, which is less information than Pi's own
+ * verbose card — the compaction would be a downgrade rather than a cleanup.
+ */
+const GENERIC_KEYS = [
+  "command", "path", "file", "filePath", "pattern", "query", "url", "name",
+  "tool", "action", "id", "target", "message", "text", "prompt",
+] as const;
+
+function genericDetails(args: any, budget: number, hardCap: number): string {
+  for (const key of GENERIC_KEYS) {
+    const value = args[key];
+    // Only scalars: an object would serialize into noise on a one-line row.
+    if (value !== undefined && value !== null && typeof value !== "object") {
+      const text = compact(value, budget, hardCap);
+      if (text) return text;
+    }
+  }
+  return "";
+}
+
+function builtInDetails(name: ToolName, args: any, options: DescribeOptions, hardCap: number): string {
+  const expanded = options.expanded === true;
+  const budget = options.budget ?? Number.POSITIVE_INFINITY;
+  // Paths are shown verbatim (no ~/ home abbreviation — it was decorative and
+  // cost a homedir() call per render).
+  const path = (value: unknown) => String(value ?? "");
+
+  switch (name) {
+    case "bash":
+      // ONE field, so no budget split is needed: CompactLine truncates at the
+      // real viewport width. An earlier version also capped this at 100
+      // characters, which threw away ~89 usable columns on a 200-column
+      // terminal. Newlines still collapse so a heredoc cannot escape the row.
+      return compact(args.command, expanded ? Number.POSITIVE_INFINITY : budget, hardCap);
+    case "read": {
+      // Show the line range when offset/limit were used, mirroring the built-in
+      // read tool's "path:start-end" notation.
+      const start = args.offset ?? 1;
+      const range = args.offset !== undefined || args.limit !== undefined
+        ? `:${start}${args.limit ? `-${start + args.limit - 1}` : ""}`
+        : "";
+      return `${path(args.path)}${range}`;
+    }
+    case "edit":
+    case "write":
+      return path(args.path);
+    case "grep":
+    case "find": {
+      // COMPOSED detail: two fields competing for one row. The path identifies
+      // the search, so it keeps its columns and the pattern takes the rest;
+      // otherwise a long regex pushed the path off the end of the line.
+      const where = path(args.path ?? ".");
+      const wrapper = name === "grep" ? 2 : 0; // the two slashes in /pattern/
+      const overhead = where.length + " in ".length + wrapper;
+      const room = Number.isFinite(budget) ? Math.max(MIN_FIELD, budget - overhead) : Number.POSITIVE_INFINITY;
+      const pattern = compact(args.pattern, room, hardCap);
+      return name === "grep" ? `/${pattern}/ in ${where}` : `${pattern} in ${where}`;
+    }
+    case "ls":
+      return path(args.path ?? ".");
+  }
+}