pi-better-harness 0.40.4 → 0.40.6

package/extensions/minimal-output/hook.ts

@@ -278,6 +278,19 @@ function sdkEntry(require: ReturnType<typeof createRequire>): string {
 }
 
 /** Internal TUI adapter: no tools are replaced and no result content is changed. */
+const FRAME_MS = 80;
+const IDLE_FRAME_MS = 1000;
+const STALE_RENDER_MS = 400;
+
+/**
+ * Shimmer cadence for the next frame. Fast while any animated row rendered recently, one frame
+ * a second once none has, and never off: an unfocused window can stop repainting without the row
+ * being gone, and stopping the timer would latch the animation until an unrelated render restarted it.
+ */
+export function shimmerFrameDelay(lastRenderMs: number, nowMs: number): number {
+  return nowMs - lastRenderMs <= STALE_RENDER_MS ? FRAME_MS : IDLE_FRAME_MS;
+}
+
 export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: () => Theme, compactionPrototype?: CompactionPrototype, customMessagePrototype?: CustomMessagePrototype): MinimalOutputHook {
   for (const name of ["updateDisplay", "getResultRenderer", "getTextOutput", "setExpanded", "invalidate", "render"] as const) {
     if (typeof prototype[name] !== "function") {
@@ -319,10 +332,16 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     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;
+    // Frame while the transcript paints, then one frame a second once it stops. An unfocused
+    // window may stop repainting, and clearing the timer outright would latch the animation off
+    // until an unrelated render happened to restart it. Slowing keeps the saving without the latch.
+    let animationTimer: ReturnType<typeof setTimeout> | undefined;
+    let animationIdle = false;
+    let paintingFrame = false;
     const stopAnimation = () => {
-      if (animationTimer !== undefined) clearInterval(animationTimer);
+      if (animationTimer !== undefined) clearTimeout(animationTimer);
       animationTimer = undefined;
+      animationIdle = false;
       animated.clear();
     };
     const canAnimate = (component: ToolComponent) => {
@@ -333,30 +352,57 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         && !settled.has(component);
     };
     const pruneAnimation = () => {
-      for (const [reference, lastRender] of animated) {
+      for (const reference of animated.keys()) {
         const component = reference.deref();
-        if (!component || !canAnimate(component) || Date.now() - lastRender > 400
+        if (!component || !canAnimate(component)
           || toolVisibility(component.ui, component) !== true) animated.delete(reference);
       }
       if (!animated.size) stopAnimation();
     };
+    const scheduleFrame = (delayMs: number) => {
+      if (animationTimer !== undefined) clearTimeout(animationTimer);
+      animationTimer = setTimeout(paintFrame, Math.max(0, delayMs));
+      animationTimer.unref?.();
+    };
+    const paintFrame = () => {
+      animationTimer = undefined;
+      pruneAnimation();
+      if (!animated.size) return;
+      const uis = new Set<ToolUI>();
+      for (const reference of animated.keys()) {
+        const component = reference.deref();
+        if (!component) continue;
+        uis.add(component.ui);
+      }
+      paintingFrame = true;
+      try {
+        for (const ui of uis) ui.requestRender();
+      } finally {
+        paintingFrame = false;
+      }
+      pruneAnimation();
+      if (!animated.size) return;
+      // Choose the cadence from the timestamps this frame produced. Reading them before the
+      // renders instead would keep seeing the previous idle gap and re-arm the idle period
+      // forever, so painting that resumed on a timer-driven frame could never speed back up.
+      let newestRender = 0;
+      for (const lastRender of animated.values()) {
+        if (lastRender > newestRender) newestRender = lastRender;
+      }
+      const delay = shimmerFrameDelay(newestRender, Date.now());
+      animationIdle = delay === IDLE_FRAME_MS;
+      scheduleFrame(delay);
+    };
     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?.();
+      // A render outside the clock means painting resumed. Re-arm at the frame cadence rather
+      // than waiting out a pending idle period, which would otherwise cost up to a second.
+      if (!paintingFrame && (animationTimer === undefined || animationIdle)) {
+        animationIdle = false;
+        scheduleFrame(FRAME_MS);
       }
       return toolVisibility(component.ui, component) === true ? Date.now() : undefined;
     };

package/extensions/tool-call-guard/index.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SettingsControl } from "../settings/registry.ts";
+import { readHarnessSetting, updateHarnessSetting } from "../shared-harness-settings.ts";
+import { blockReason, detectForegroundWait, type WaitMatch } from "./waits.ts";
+
+const SETTING_KEY = "toolCallGuard";
+
+interface GuardSetting { version?: unknown; enabled?: unknown }
+
+/**
+ * Block a foreground command that waits on an external system.
+ *
+ * Returns the block result from `tool_call`, which pi turns into a failed tool result carrying
+ * `reason`. Nothing is executed. `isEnabled` is read per call so the setting takes effect
+ * without reloading the extension.
+ */
+export function installToolCallGuard(
+  pi: ExtensionAPI,
+  isEnabled: () => boolean,
+  onBlock?: (match: WaitMatch, command: string) => void,
+): void {
+  pi.on("tool_call", (event) => {
+    if (!isEnabled()) return;
+    if (event.toolName !== "bash") return;
+    // `input` is the current SDK field; older typings and some hosts expose `args`.
+    const payload = event as { input?: { command?: unknown }; args?: { command?: unknown } };
+    const command = payload.input?.command ?? payload.args?.command;
+    if (typeof command !== "string") return;
+    const match = detectForegroundWait(command);
+    if (!match) return;
+    onBlock?.(match, command);
+    return { block: true, reason: blockReason(match) };
+  });
+}
+
+export default function toolCallGuardExtension(pi: ExtensionAPI): void {
+  let enabled = true;
+
+  const read = (): void => {
+    const value = readHarnessSetting<GuardSetting>(SETTING_KEY);
+    if (value !== undefined && (value?.version !== 1 || typeof value.enabled !== "boolean")) {
+      throw new Error("Invalid tool-call guard setting in global settings.json.");
+    }
+    enabled = value?.enabled !== false;
+  };
+
+  const setting: SettingsControl = {
+    id: "tool-call-guard", label: "Tool call guard", values: ["On", "Off"],
+    get: () => enabled ? "On" : "Off",
+    change(value: string, _ctx: ExtensionCommandContext) {
+      if (value !== "On" && value !== "Off") throw new Error("Invalid tool-call guard value.");
+      updateHarnessSetting(SETTING_KEY, () => ({ version: 1, enabled: value === "On" }));
+      enabled = value === "On";
+    },
+  };
+
+  const register = () => pi.events.emit("harness-settings:register", setting);
+  let stopSettings: (() => void) | undefined;
+  const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
+
+  subscribe();
+  register();
+  installToolCallGuard(pi, () => enabled);
+
+  pi.on("session_start", () => {
+    subscribe();
+    try { read(); }
+    catch {
+      // A malformed value must not take the session down; fall back to guarding.
+      enabled = true;
+    }
+    register();
+  });
+
+  pi.on("session_shutdown", () => {
+    stopSettings?.();
+    stopSettings = undefined;
+  });
+}

package/extensions/tool-call-guard/waits.ts

@@ -0,0 +1,59 @@
+/**
+ * Recognise a foreground command that waits on something outside this machine.
+ *
+ * The guard keys off command shape rather than duration: a five minute test run belongs in the
+ * foreground where its output streams, while `gh pr checks --watch` can only end when GitHub
+ * says so. Duration cannot tell those apart, and blocking the first would be wrong.
+ */
+export interface WaitMatch {
+  /** Which rule matched, quoted back to the caller so the block is explainable. */
+  rule: string;
+  /** What the command is waiting for. */
+  waitsOn: string;
+}
+
+/** A foreground pause shorter than this is ordinary command flow, not a wait. */
+export const SLEEP_THRESHOLD_SECONDS = 3;
+
+const RULES: readonly { rule: RegExp; waitsOn: string }[] = [
+  { rule: /\bgh\s+pr\s+checks\b[^\n]*--watch\b/, waitsOn: "a pull request's checks" },
+  { rule: /\bgh\s+run\s+(?:view|watch)\b[^\n]*--watch\b/, waitsOn: "a workflow run" },
+  { rule: /\bgh\s+run\s+watch\b/, waitsOn: "a workflow run" },
+  { rule: /\bgh\s+workflow\s+run\b[^\n]*--watch\b/, waitsOn: "a workflow run" },
+  // A helper script whose name starts with watch- polls an external system, whatever its flags.
+  { rule: /\bwatch[-_][\w.-]*/, waitsOn: "an external state change" },
+  // --watch and --until only mean polling on provider CLIs; `git log --until` is a plain filter.
+  { rule: /\b(?:gh|github|glab)\b[^\n]*--(?:watch|until)\b/, waitsOn: "an external state change" },
+  { rule: /(?:^|[;&|]\s*)watch\s+\S/, waitsOn: "a repeating command" },
+  { rule: /\btail\s+-[a-zA-Z]*[fF]/, waitsOn: "a growing file" },
+  { rule: /\bdocker\s+(?:logs|events)\b[^\n]*\s-f\b/, waitsOn: "a container's log stream" },
+  { rule: /\bkubectl\b[^\n]*(?:--watch\b|\s-w\b)/, waitsOn: "cluster state" },
+  // A poll loop only counts when its body actually waits on something.
+  { rule: /\b(?:until|while)\b[^\n]*\b(?:sleep|curl|gh\s|docker\s|kubectl\s|pg_isready)\b/, waitsOn: "a repeated external check" },
+];
+
+const SLEEP = /(?:^|[;&|(]\s*|\bsudo\s+)sleep\s+(\d+(?:\.\d+)?)/;
+
+export function detectForegroundWait(command: string): WaitMatch | undefined {
+  for (const { rule, waitsOn } of RULES) {
+    if (rule.test(command)) return { rule: rule.source, waitsOn };
+  }
+  const sleep = SLEEP.exec(command);
+  if (sleep) {
+    const seconds = Number(sleep[1]);
+    if (Number.isFinite(seconds) && seconds > SLEEP_THRESHOLD_SECONDS) {
+      return { rule: SLEEP.source, waitsOn: `${seconds} seconds of wall clock` };
+    }
+  }
+  return undefined;
+}
+
+/** The message the model reads instead of the command's output. */
+export function blockReason(match: WaitMatch): string {
+  return [
+    `This command waits on ${match.waitsOn}, so it belongs in a background task.`,
+    "Spawn it with bg_task_spawn, then call wait_for_operations to park until it reports; a background task survives the end of the turn, while a foreground wait does not.",
+    "Read bg_task_status and bg_task_log for the verdict.",
+    'To run this command in the foreground anyway, set Tool call guard to Off in Harness settings.',
+  ].join(" ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.40.4",
+  "version": "0.40.6",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, model routing, and Outcome & Todo.",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
       "extensions/model-router/index.ts",
       "extensions/task-context/index.ts",
       "extensions/minimal-output/index.ts",
+      "extensions/tool-call-guard/index.ts",
       "extensions/settings/index.ts"
     ],
     "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-harness.png"
@@ -51,7 +52,7 @@
   ],
   "scripts": {
     "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/stage-harness-dependencies.mjs",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node extensions/minimal-output/index.ts extensions/minimal-output/hook.ts extensions/settings/index.ts extensions/execution-policy.ts extensions/task-context/index.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node extensions/minimal-output/index.ts extensions/minimal-output/hook.ts extensions/settings/index.ts extensions/execution-policy.ts extensions/tool-call-guard/index.ts extensions/tool-call-guard/waits.ts extensions/task-context/index.ts",
     "test": "node --import tsx --import ../../scripts/isolate-registry.mjs --test test/*.test.mjs test/*.test.ts test/task-context/*.test.ts"
   },
   "dependencies": {