pi-better-harness 0.27.2 → 0.28.0

package/README.md

@@ -68,11 +68,12 @@ The bundled harness provides **Tool output: Normal / Minimal** in
 `/harness-settings`. `/tool-output minimal`, `/tool-output normal`, and
 `/tool-output` (toggle) remain compatibility shortcuts to the same preference.
 Minimal mode folds each tool call into a single-line header, including running
-calls. Each row has a single tool-specific icon: accent-colored while running,
-muted when completed, and error-colored when failed. Tool names stay muted;
-inline command/path arguments use the theme's distinct dim tone. Running and
-failed calls retain text labels so state never depends on color alone. Activity
-stays quieter than conversation text. Tool rows are indented two columns past
+calls. The tool-specific icon and tool name share a state color: accent while
+running, muted when completed, and error-colored when failed. In fullscreen Pi, a soft highlight travels through visible running names; inline
+command/path arguments stay dim. Scrollback terminals keep static state colors.
+Choose **Tool animation: Off** in `/harness-settings` for static running headers.
+Running and failed calls retain text labels so state never depends on color or
+motion alone. Tool rows are indented two columns past
 the assistant text padding. Long
 headers are truncated to the terminal width; result bodies,
 images, boxes, and tool spacers are hidden. Built-in, extension, and MCP calls
@@ -130,8 +131,10 @@ to the `/agents` catalog. `/sandbox`, `/subagents settings`, `/agents`, and
 `/goal settings` remain available in standalone installations.
 Packages without a settings screen are not listed. Pi's `/settings` is unchanged.
 
-The hub includes **Tool output** when the bundled renderer extension is loaded.
-Changes apply immediately and also save the default for future sessions.
+The hub includes **Tool output** and **Tool animation** when the bundled renderer
+extension is loaded. Changes apply immediately and save the default for future
+sessions. The animation preference is stored in `piBetterHarness.toolAnimation`;
+normal output and expanded tool details are never animated.
 The hub also owns **Completions while busy**, shared by Subagents and Background
 Tasks. Choose **Wait until idle** (the default) or **Steer active run**. Changes
 apply immediately and autosave to the current session branch, including across

package/extensions/minimal-output/hook.ts

@@ -5,8 +5,10 @@ import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { supportsToolShimmer, toolIdentity } from "./tool-identity.ts";
+import { toolVisibility, type ViewportUI } from "./tool-visibility.ts";
 
-interface ToolUI {
+interface ToolUI extends ViewportUI {
   requestRender(): void;
   children?: TranscriptComponent[];
   handleViewportInput?(data: string): unknown;
@@ -70,6 +72,8 @@ interface ToolPrototype {
 }
 interface HookState {
   enabled: boolean;
+  animationEnabled: boolean;
+  stopAnimation(): void;
   owners: number;
   redraw(collapse?: boolean): void;
   restore(): void;
@@ -79,6 +83,7 @@ interface HookState {
 }
 export interface MinimalOutputHook {
   setEnabled(enabled: boolean): void;
+  setAnimationEnabled(enabled: boolean): void;
   completeRun(): void;
   restoreCompletedCalls(ids: Iterable<string>): void;
   dispose(): void;
@@ -146,7 +151,7 @@ function harnessCallDetail(name: string, input: unknown): string | undefined {
   }
 }
 
-function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3): string[] {
+function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3, animationTime?: number): string[] {
   if (width <= 0) return [];
   // Render the call alone at a wider width so terminal wrapping becomes truncation.
   const header = Boolean(component.getCallRenderer?.()) && component.callRendererComponent?.render(Math.max(4096, width + 1))
@@ -170,7 +175,7 @@ function compactCall(component: ToolComponent, width: number, theme?: Theme, ind
   const icon = TOOL_ICONS[component.toolName] ?? "\u25c7";
   const title = ` ${icon} ${label}`;
   const styled = theme
-    ? ` ${theme.fg(failed ? "error" : running ? "accent" : "muted", icon)} ${theme.fg("muted", label)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
+    ? ` ${toolIdentity(icon, label, failed ? "error" : running ? "accent" : "muted", theme, animationTime)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
     : `${title}${detail ? `  ${detail}` : ""}${suffix}`;
   return [truncateToWidth(`${" ".repeat(Math.min(indent, Math.max(0, width - 1)))}${styled}`, width)];
 }
@@ -304,6 +309,50 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     };
     const seen = new WeakSet<ToolComponent>();
     const components = new Set<WeakRef<ToolComponent>>();
+    const animationReferences = new WeakMap<ToolComponent, WeakRef<ToolComponent>>();
+    const animated = new Map<WeakRef<ToolComponent>, number>();
+    const settled = new WeakSet<ToolComponent>();
+    let animationTimer: ReturnType<typeof setInterval> | undefined;
+    const stopAnimation = () => {
+      if (animationTimer !== undefined) clearInterval(animationTimer);
+      animationTimer = undefined;
+      animated.clear();
+    };
+    const canAnimate = (component: ToolComponent) => {
+      const theme = getTheme?.();
+      return state!.enabled && state!.animationEnabled && component.ui.mode === "fullscreen"
+        && !!theme && supportsToolShimmer(theme)
+        && !component.expanded && !component.result?.isError && (!component.result || component.isPartial)
+        && !settled.has(component);
+    };
+    const pruneAnimation = () => {
+      for (const [reference, lastRender] of animated) {
+        const component = reference.deref();
+        if (!component || !canAnimate(component) || Date.now() - lastRender > 400
+          || toolVisibility(component.ui, component) !== true) animated.delete(reference);
+      }
+      if (!animated.size) stopAnimation();
+    };
+    const animationTime = (component: ToolComponent, width: number, indent: number) => {
+      if (width <= indent + 3 || !canAnimate(component) || toolVisibility(component.ui, component) === false) return undefined;
+      let reference = animationReferences.get(component);
+      if (!reference) { reference = new WeakRef(component); animationReferences.set(component, reference); }
+      animated.set(reference, Date.now());
+      if (animationTimer === undefined) {
+        animationTimer = setInterval(() => {
+          pruneAnimation();
+          const uis = new Set<ToolUI>();
+          for (const reference of animated.keys()) {
+            const component = reference.deref();
+            if (!component) continue;
+            uis.add(component.ui);
+          }
+          for (const ui of uis) ui.requestRender();
+        }, 80);
+        animationTimer.unref?.();
+      }
+      return toolVisibility(component.ui, component) === true ? Date.now() : undefined;
+    };
     let completed = new Map<string, object>();
     let groups = new WeakMap<ToolComponent, ToolGroup>();
     let layouts = new WeakMap<ToolComponent, { parent: TranscriptComponent; anchor?: TranscriptComponent }>();
@@ -344,11 +393,15 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     };
     state = {
       enabled: false,
+      animationEnabled: true,
+      stopAnimation,
       owners: 0,
       completeRun() {
+        stopAnimation();
         const run = {};
         for (const reference of components) {
           const component = reference.deref();
+          if (component) settled.add(component);
           if (component?.result && !component.isPartial && !completed.has(component.toolCallId)) {
             completed.set(component.toolCallId, run);
             if (this.enabled) component.setExpanded(false);
@@ -357,6 +410,11 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         this.redraw();
       },
       restoreCompletedCalls(ids) {
+        stopAnimation();
+        for (const reference of components) {
+          const component = reference.deref();
+          if (component) settled.add(component);
+        }
         const history = {};
         completed = new Map(Array.from(ids, id => [id, history]));
         groups = new WeakMap();
@@ -372,8 +430,10 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
           else component.invalidate();
           component.ui.requestRender();
         }
+        pruneAnimation();
       },
       restore() {
+        stopAnimation();
         clearHover();
         for (const [ui, { original, wrapper }] of inputWrappers) {
           if (ui.handleViewportInput === wrapper) ui.handleViewportInput = original;
@@ -498,6 +558,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
           this.ui.handleViewportInput = wrapper;
         }
         if (!seen.has(this)) { seen.add(this); components.add(new WeakRef(this)); }
+        pruneAnimation();
         if (!current.enabled || this.expanded) return originals.updateDisplay.apply(this, args);
         const showImages = this.showImages;
         const lastRenderer = this.resultRendererComponent;
@@ -517,6 +578,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         if (args[0] === false && !mouseHandling && group) group.open = false;
         const result = originals.setExpanded.apply(this, args);
         if (group) group.expanded += Number(this.expanded) - Number(wasExpanded);
+        pruneAnimation();
         return result;
       },
       getResultRenderer(this: ToolComponent, ...args: unknown[]) {
@@ -531,7 +593,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         const padding = layout?.anchor?.outputPad ?? 1;
         const indent = Number.isFinite(padding) ? Math.max(0, Math.floor(padding)) + 2 : 3;
         const group = groupFor(this, layout?.parent);
-        if (!group) return highlight(this, compactCall(this, width, getTheme?.(), indent), width);
+        if (!group) return highlight(this, compactCall(this, width, getTheme?.(), indent, animationTime(this, width, indent)), width);
         const open = group.open || group.expanded > 0;
         const first = group.members[0] === this;
         const lines: string[] = [];
@@ -591,6 +653,12 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
       current.enabled = enabled;
       current.redraw(enabled);
     },
+    setAnimationEnabled(enabled) {
+      if (disposed) return;
+      current.animationEnabled = enabled;
+      if (!enabled) current.stopAnimation();
+      current.redraw();
+    },
     dispose() {
       if (disposed) return;
       disposed = true;

package/extensions/minimal-output/index.ts

@@ -10,6 +10,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   let enabled = false;
   let running = false;
   let initialDefault: boolean | undefined;
+  let motionEnabled = true;
 
   function defaultEnabled(): boolean {
     if (initialDefault !== undefined) return initialDefault;
@@ -52,6 +53,16 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
       enabled = false;
       ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
     }
+    try {
+      const motion = readHarnessSetting<{ version?: unknown; enabled?: unknown }>("toolAnimation");
+      if (motion !== undefined && (motion?.version !== 1 || typeof motion.enabled !== "boolean")) {
+        throw new Error("Invalid tool-animation default in global settings.json.");
+      }
+      motionEnabled = motion?.enabled !== false;
+    } catch (error) {
+      motionEnabled = false;
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom" && entry.customType === ENTRY) {
         const data = entry.data as { version?: unknown; enabled?: unknown } | undefined;
@@ -60,6 +71,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
     // Observe transcript components from startup, so the toggle also redraws existing rows.
     if (await ensureHook(ctx)) {
+      hook!.setAnimationEnabled(motionEnabled);
       hook!.restoreCompletedCalls(ctx.sessionManager.getBranch().flatMap(entry =>
         entry.type === "message" && entry.message.role === "toolResult" ? [entry.message.toolCallId] : []));
       if (enabled) collapseTools(ctx);
@@ -93,7 +105,21 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     id: "tool-output", label: "Tool output", values: ["Normal", "Minimal"],
     get: () => enabled ? "Minimal" : "Normal", change,
   };
-  const register = () => pi.events.emit("harness-settings:register", setting);
+  const animationSetting: SettingsControl = {
+    id: "tool-animation", label: "Tool animation", values: ["Shimmer", "Off"],
+    get: () => motionEnabled ? "Shimmer" : "Off",
+    async change(value, ctx) {
+      if (value !== "Shimmer" && value !== "Off") throw new Error("Invalid tool animation mode.");
+      if (!await ensureHook(ctx)) throw new Error("Tool animation settings are unavailable in this Pi runtime.");
+      updateHarnessSetting("toolAnimation", () => ({ version: 1, enabled: value === "Shimmer" }));
+      motionEnabled = value === "Shimmer";
+      hook!.setAnimationEnabled(motionEnabled);
+    },
+  };
+  const register = () => {
+    pi.events.emit("harness-settings:register", setting);
+    pi.events.emit("harness-settings:register", animationSetting);
+  };
   let stopSettings: (() => void) | undefined;
   const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
   subscribe();
@@ -115,6 +141,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     enabled = false;
     running = false;
     initialDefault = undefined;
+    motionEnabled = true;
   });
 
   pi.registerCommand("tool-output", {

package/extensions/minimal-output/tool-identity.ts

@@ -0,0 +1,66 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+type RGB = [number, number, number];
+interface ConcreteColor { kind: string; index?: number; r?: number; g?: number; b?: number }
+const concreteColors = (theme: Theme) => (theme as Theme & { colors?: Record<string, ConcreteColor> }).colors;
+const PERIOD = 2400;
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function themeRgb(theme: Theme, token: "accent" | "text"): RGB | undefined {
+  const color = concreteColors(theme)?.[token];
+  if (color?.kind === "rgb" && color.r !== undefined && color.g !== undefined && color.b !== undefined) {
+    return [color.r, color.g, color.b];
+  }
+  return rgb(theme.getFgAnsi(token));
+}
+
+export function supportsToolShimmer(theme: Theme): boolean {
+  const base = themeRgb(theme, "accent");
+  const light = themeRgb(theme, "text");
+  const accent = concreteColors(theme)?.accent;
+  return (!!base && !!light && base.some((value, index) => value !== light[index]))
+    || (accent?.kind === "indexed" && accent.index !== undefined && accent.index >= 0 && accent.index < 16);
+}
+
+function rgb(ansi: string): RGB | undefined {
+  const direct = /\x1b\[38;2;(\d+);(\d+);(\d+)m/.exec(ansi);
+  if (direct) return [Number(direct[1]), Number(direct[2]), Number(direct[3])];
+  const indexed = /\x1b\[38;5;(\d+)m/.exec(ansi);
+  if (!indexed) return undefined;
+  const index = Number(indexed[1]);
+  // The first 16 colors are terminal-defined; keep them untouched rather than guess.
+  if (index < 16 || index > 255) return undefined;
+  if (index >= 232) { const gray = 8 + (index - 232) * 10; return [gray, gray, gray]; }
+  const cube = index - 16;
+  const channel = (value: number) => value === 0 ? 0 : 55 + value * 40;
+  return [channel(Math.floor(cube / 36)), channel(Math.floor(cube / 6) % 6), channel(cube % 6)];
+}
+
+function foreground(color: RGB, mode: "truecolor" | "256color"): string {
+  if (mode === "truecolor") return `\x1b[38;2;${color.join(";")}m`;
+  const channel = (value: number) => Math.max(0, Math.min(5, Math.round((value - 55) / 40)));
+  const index = 16 + channel(color[0]) * 36 + channel(color[1]) * 6 + channel(color[2]);
+  return `\x1b[38;5;${index}m`;
+}
+
+export function toolIdentity(icon: string, label: string, tone: "accent" | "muted" | "error", theme: Theme, time?: number): string {
+  if (tone !== "accent" || time === undefined) return theme.fg(tone, `${icon} ${label}`);
+  const base = themeRgb(theme, "accent");
+  const light = themeRgb(theme, "text");
+  if (!supportsToolShimmer(theme)) return theme.fg(tone, `${icon} ${label}`);
+  const letters = Array.from(graphemes.segment(label), part => part.segment);
+  const radius = Math.max(2, Math.min(4, letters.length / 3));
+  const position = (time % PERIOD) / PERIOD * (letters.length + radius * 2) - radius;
+  const mode = theme.getColorMode();
+  const name = letters.map((letter, index) => {
+    const distance = Math.abs(index - position) / radius;
+    const shine = distance < 1 ? (1 + Math.cos(distance * Math.PI)) * 0.48 : 0;
+    if (!base || !light) {
+      const intensity = shine > 0.72 ? "\x1b[1m" : shine > 0.18 ? "" : "\x1b[2m";
+      return `\x1b[22m${intensity}${letter}`;
+    }
+    const color = base.map((value, channel) => Math.round(value + (light[channel] - value) * shine)) as RGB;
+    return `${foreground(color, mode)}${letter}`;
+  }).join("");
+  return theme.fg(tone, `${icon} \x1b[22m${name}\x1b[22m`);
+}

package/extensions/minimal-output/tool-visibility.ts

@@ -0,0 +1,61 @@
+interface Rect { x: number; y: number; width: number; height: number }
+interface LegacyComponent {
+  mouseLayout?: { children: { component: LegacyComponent; height: number }[] };
+  paddingX?: number;
+  paddingY?: number;
+}
+interface LayoutBox {
+  component: LegacyComponent;
+  rect: Rect;
+  clip: Rect;
+  children: LayoutBox[];
+  lineOffset?: number;
+}
+export interface ViewportUI { mode?: string; currentLayout?: { root: LayoutBox }; hasOverlay?(): boolean; hasActiveSelection?(): boolean }
+const frames = new WeakMap<ViewportUI, { root: LayoutBox; known: Set<object>; visible: Set<object> }>();
+
+function intersects(a: Rect, b: Rect): boolean {
+  return a.width > 0 && a.height > 0 && b.width > 0 && b.height > 0
+    && a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+
+// The guarded fullscreen adapter uses the last painted layout, never calls render()
+// to measure visibility, and leaves scrollback hosts on static state colors.
+export function toolVisibility(ui: ViewportUI, component: object): boolean | undefined {
+  if (ui.mode !== "fullscreen" || ui.hasOverlay?.() || ui.hasActiveSelection?.()) return false;
+  const root = ui.currentLayout?.root;
+  if (!root) return undefined;
+  if (!root.rect || !root.clip || !Array.isArray(root.children)) return false;
+  let frame = frames.get(ui);
+  if (frame?.root !== root) {
+    frame = { root, known: new Set(), visible: new Set() };
+    const current = frame;
+    const legacy = (child: LegacyComponent, rect: Rect, clip: Rect) => {
+      if (!child || typeof child !== "object") return;
+      current.known.add(child);
+      if (!intersects(rect, clip)) return;
+      current.visible.add(child);
+      const children = child.mouseLayout?.children;
+      if (!children) return;
+      const paddingY = child.paddingY ?? 0;
+      const paddingX = child.paddingX ?? 0;
+      if (children.reduce((height, entry) => height + entry.height, 0) + paddingY * 2 !== rect.height) return;
+      let y = rect.y + paddingY;
+      for (const entry of children) {
+        legacy(entry.component, { x: rect.x + paddingX, y, width: Math.max(0, rect.width - paddingX * 2), height: entry.height }, clip);
+        y += entry.height;
+      }
+    };
+    const visit = (box: LayoutBox) => {
+      if (!box?.component || !box.rect || !box.clip || !Array.isArray(box.children)) return;
+      current.known.add(box.component);
+      if (!intersects(box.rect, box.clip)) return;
+      current.visible.add(box.component);
+      if (box.children.length) for (const child of box.children) visit(child);
+      else legacy(box.component, { ...box.rect, y: box.rect.y - (box.lineOffset ?? 0) }, box.clip);
+    };
+    visit(root);
+    frames.set(ui, frame);
+  }
+  return frame.known.has(component) ? frame.visible.has(component) : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",