pi-better-harness 0.20.0 → 0.22.0

package/README.md

@@ -64,14 +64,20 @@ need interactive confirmation. Full policy: [pi-better-sandbox](https://github.c
 
 ## Minimal Tool Output
 
-The bundled harness also provides `/tool-output minimal`, `/tool-output normal`,
-and `/tool-output` (toggle). Minimal mode folds each tool call into a single-line
-header, including running calls. Long headers are truncated to the terminal
-width; result bodies, images, boxes, and tool spacers are hidden. Built-in,
-extension, and MCP calls are included. Execution, sandboxing, and agent-facing
-payloads are unchanged. Ctrl+O reveals the original tool blocks; Ctrl+O again
-folds them. `/tool-output normal` restores ordinary rendering. Error result
-bodies are also hidden in minimal mode and remain available when expanded.
+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. Muted tool names and quieter inline command/path context distinguish
+activity from conversation text; running and failed calls retain visible state
+markers. Long headers are truncated to the terminal width; result bodies,
+images, boxes, and tool spacers are hidden. Built-in, extension, and MCP calls
+are included. Execution, sandboxing, and agent-facing payloads are unchanged.
+In newer Pi fullscreen mode, click a folded row to expand its original details,
+then click the expanded call/result to collapse it. Regular terminals keep mouse
+input for terminal selection and scrollback; Ctrl+O expands tools in all modes.
+`/tool-output normal` restores ordinary rendering. Error result bodies are also
+hidden in minimal mode and remain available when expanded.
 
 Normal mode is the default. The preference is saved in the current session,
 including resume/reload. This is a version-sensitive internal TUI adapter,
@@ -86,6 +92,41 @@ Load the bundled harness or run it directly from a checkout:
 pi -e ./packages/pi-better-harness/extensions/minimal-output/index.ts
 ```
 
+## Harness Settings
+
+The bundled harness provides `/harness-settings`, using Pi's native settings
+list. It opens the settings screens of loaded Sandbox, Subagents, and Goal
+packages without duplicating their configuration. `/sandbox`, `/subagents
+settings`, 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 to the current session and do not save a global
+default. 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
+reloads. Press **Ctrl+S** to save the current choice as your default for future
+Pi sessions; changing a session afterward does not change that saved default.
+Saving a default leaves already-open sessions unchanged, including when
+navigating to a branch without a session override.
+The user default is stored in
+`<agent-dir>/extensions/pi-better-callback-preferences.json` and also applies
+when either callback package is loaded standalone. The former
+`PI_BETTER_CALLBACK_WHILE_BUSY` environment variable is no longer supported.
+
+Next-prompt inference is deferred pending safe public auth/header resolution in
+Pi's SDK. It is not loaded by the bundle, has no toggle or preference store in
+this version, and makes no auxiliary model requests. The integration blocker is
+[issue #426](https://github.com/1aboveio/pi-better-harness/issues/426).
+
+The hub is TUI-only. The standalone-package installer does not install
+Harness-only extensions; load the bundle or the settings extension from the
+checkout to use the hub:
+
+```sh
+pi -e ./packages/pi-better-harness/extensions/settings/index.ts
+```
+
 ## When To Use
 
 Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, synchronous SSH, goal tracking, or plans.

package/extensions/minimal-output/hook.ts

@@ -4,12 +4,15 @@ import { createRequire } from "node:module";
 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";
 
 interface ToolComponent {
   toolName: string;
   args: unknown;
   callRendererComponent?: Component;
   expanded: boolean;
+  isPartial?: boolean;
+  result?: { isError?: boolean };
   showImages: boolean;
   resultRendererComponent?: unknown;
   ui: { requestRender(): void };
@@ -19,7 +22,10 @@ interface ToolComponent {
 }
 
 type Method = (this: ToolComponent, ...args: unknown[]) => unknown;
+interface ToolMouseEvent { type: string; button: string; y: number; shift?: boolean; alt?: boolean; ctrl?: boolean }
+type MouseHandler = (this: ToolComponent, event: ToolMouseEvent) => unknown;
 interface ToolPrototype {
+  handleMouse?: MouseHandler;
   updateDisplay: Method;
   getResultRenderer: Method;
   getTextOutput: Method;
@@ -42,7 +48,7 @@ export interface MinimalOutputHook {
 const HOOK = Symbol.for("pi-better-harness.minimal-output-hook");
 const emptyResult = () => ({ render: () => [] as string[], invalidate() {} });
 
-function compactCall(component: ToolComponent, width: number): string[] {
+function compactCall(component: ToolComponent, width: number, theme?: Theme): string[] {
   if (width <= 0) return [];
   // Render the call alone at a wider width so terminal wrapping becomes truncation.
   const header = component.callRendererComponent?.render(Math.max(4096, width + 1))
@@ -50,10 +56,24 @@ function compactCall(component: ToolComponent, width: number): string[] {
     .find((line) => line.length > 0);
   let text = header;
   if (!text) {
-    const args = JSON.stringify(component.args);
-    text = `${component.toolName}${args && args !== "{}" ? ` ${args}` : ""}`;
+    const args = component.args as Record<string, unknown> | undefined;
+    const hint = args?.command ?? args?.path ?? args?.pattern;
+    const detail = typeof hint === "string" ? hint.replace(/\r?\n/g, " ") : JSON.stringify(component.args);
+    text = `${component.toolName}${detail && detail !== "{}" ? ` ${detail}` : ""}`;
   }
-  return [truncateToWidth(text, width)];
+  const failed = component.result?.isError === true;
+  const running = !component.result || component.isPartial;
+  const detail = text.startsWith(`${component.toolName} `) ? text.slice(component.toolName.length).trimStart()
+    : text === component.toolName ? "" : text;
+  const label = component.toolName === "bash" ? "Shell"
+    : component.toolName.replace(/_/g, " ").replace(/^./, letter => letter.toUpperCase());
+  const marker = failed ? "!" : running ? "~" : ">";
+  const suffix = failed ? " (failed)" : running ? " (running)" : "";
+  const title = `${marker} ${label}`;
+  const styled = theme
+    ? `${theme.fg(failed ? "error" : "muted", title)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "muted", suffix)}`
+    : `${title}${detail ? `  ${detail}` : ""}${suffix}`;
+  return [truncateToWidth(styled, width)];
 }
 
 function hostRequire(): NodeRequire {
@@ -104,7 +124,7 @@ function sdkEntry(require: ReturnType<typeof createRequire>): string {
 }
 
 /** Internal TUI adapter: no tools are replaced and no result content is changed. */
-export function installMinimalOutputHook(prototype: ToolPrototype): MinimalOutputHook {
+export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: () => Theme): MinimalOutputHook {
   for (const name of ["updateDisplay", "getResultRenderer", "getTextOutput", "setExpanded", "invalidate", "render"] as const) {
     if (typeof prototype[name] !== "function") {
       throw new Error(`Pi's tool display API is incompatible: missing ${name}. Normal output remains enabled.`);
@@ -117,6 +137,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype): MinimalOutpu
       getResultRenderer: prototype.getResultRenderer,
       getTextOutput: prototype.getTextOutput,
       render: prototype.render,
+      ...(typeof prototype.handleMouse === "function" ? { handleMouse: prototype.handleMouse } : {}),
     };
     const seen = new WeakSet<ToolComponent>();
     const components = new Set<WeakRef<ToolComponent>>();
@@ -133,10 +154,11 @@ export function installMinimalOutputHook(prototype: ToolPrototype): MinimalOutpu
         }
       },
       restore() {
-        for (const name of Object.keys(originals) as Array<keyof typeof originals>) {
+        for (const name of ["updateDisplay", "getResultRenderer", "getTextOutput", "render"] as const) {
           // Do not remove another extension's subsequently installed wrapper.
           if (prototype[name] === wrappers[name]) Object.assign(prototype, { [name]: originals[name] });
         }
+        if (originals.handleMouse && prototype.handleMouse === mouseWrapper) prototype.handleMouse = originals.handleMouse;
         delete prototype[HOOK];
         components.clear();
       },
@@ -164,9 +186,19 @@ export function installMinimalOutputHook(prototype: ToolPrototype): MinimalOutpu
         return current.enabled && !this.expanded ? "" : originals.getTextOutput.apply(this, args);
       },
       render(this: ToolComponent, width: number): string[] {
-        return current.enabled && !this.expanded ? compactCall(this, width) : originals.render.call(this, width);
+        return current.enabled && !this.expanded ? compactCall(this, width, getTheme?.()) : originals.render.call(this, width);
       },
     };
+    const mouseWrapper: MouseHandler = function(event) {
+      if (current.enabled && !this.expanded) {
+        if (event.type !== "click" || event.button !== "left" || event.y !== 0 || event.shift || event.alt || event.ctrl) return undefined;
+        this.setExpanded(true);
+        this.ui.requestRender();
+        return { handled: true, render: true };
+      }
+      return originals.handleMouse?.call(this, event);
+    };
+    if (originals.handleMouse) prototype.handleMouse = mouseWrapper;
     Object.assign(prototype, wrappers);
     prototype[HOOK] = state;
   }

package/extensions/minimal-output/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { installMinimalOutputHook, loadToolPrototype, type MinimalOutputHook } from "./hook.ts";
+import type { SettingsControl } from "../settings/registry.ts";
 
 const ENTRY = "pi-better-harness-tool-output";
 
@@ -24,7 +25,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
     if (hook) return true;
     try {
-      hook = installMinimalOutputHook(await loadToolPrototype());
+      hook = installMinimalOutputHook(await loadToolPrototype(), () => ctx.ui.theme);
       return true;
     } catch (error) {
       ctx.ui.notify(`Minimal tool output is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -32,13 +33,13 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
   }
 
-  pi.on("session_start", async (_event, ctx) => {
+  async function restore(ctx: ExtensionContext): Promise<void> {
     if (ctx.mode !== "tui") return;
     enabled = false;
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom" && entry.customType === ENTRY) {
-        const data = entry.data as { enabled?: unknown } | undefined;
-        if (typeof data?.enabled === "boolean") enabled = data.enabled;
+        const data = entry.data as { version?: unknown; enabled?: unknown } | undefined;
+        if (data?.version === 1 && typeof data.enabled === "boolean") enabled = data.enabled;
       }
     }
     // Observe transcript components from startup, so the toggle also redraws existing rows.
@@ -47,9 +48,35 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
       hook!.setEnabled(enabled);
     } else enabled = false;
     status(ctx);
-  });
+  }
+
+  async function change(value: string, ctx: ExtensionContext): Promise<void> {
+    if (value !== "Normal" && value !== "Minimal") throw new Error("Invalid tool output mode.");
+    if (!await ensureHook(ctx)) throw new Error("Tool output settings are unavailable in this Pi runtime.");
+    const data = { version: 1, enabled: value === "Minimal" };
+    try { pi.appendEntry(ENTRY, data); }
+    catch (error) { data.version = 0; data.enabled = enabled; throw error; }
+    enabled = data.enabled;
+    if (enabled) collapseTools(ctx);
+    hook!.setEnabled(enabled);
+    status(ctx);
+  }
+
+  const setting: SettingsControl = {
+    id: "tool-output", label: "Tool output", values: ["Normal", "Minimal"],
+    get: () => enabled ? "Minimal" : "Normal", change,
+  };
+  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();
+  pi.on("session_start", async (_event, ctx) => { subscribe(); await restore(ctx); register(); });
+  pi.on("session_tree", async (_event, ctx) => { await restore(ctx); });
 
   pi.on("session_shutdown", () => {
+    stopSettings?.();
+    stopSettings = undefined;
     hook?.dispose();
     hook = undefined;
     enabled = false;
@@ -71,12 +98,8 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
         ctx.ui.notify("Usage: /tool-output [minimal|normal]", "warning");
         return;
       }
-      if (!await ensureHook(ctx)) return;
-      enabled = mode ? mode === "minimal" : !enabled;
-      if (enabled) collapseTools(ctx);
-      hook!.setEnabled(enabled);
-      pi.appendEntry(ENTRY, { version: 1, enabled });
-      status(ctx);
+      try { await change((mode ? mode === "minimal" : !enabled) ? "Minimal" : "Normal", ctx); }
+      catch (error) { ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning"); return; }
       ctx.ui.notify(enabled
         ? "Minimal tool output on. Compact call headers remain visible. Ctrl+O reveals results."
         : "Normal tool output restored.", "info");

package/extensions/settings/index.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { chooseHarnessSetting } from "./page.ts";
+import { createSettingsRegistry } from "./registry.ts";
+import { changeCallbackSetting, getCallbackSettings, saveCallbackDefault } from "pi-better-background-tasks/src/shared-callback-batcher.ts";
+
+export default function harnessSettingsExtension(pi: ExtensionAPI): void {
+  const registry = createSettingsRegistry(pi);
+  pi.on("session_start", () => registry.refresh());
+  pi.on("session_shutdown", () => registry.dispose());
+
+  pi.registerCommand("harness-settings", {
+    description: "Open loaded package settings",
+    handler: async (_args, ctx) => {
+      if (ctx.mode !== "tui") { ctx.ui.notify("Harness settings requires the interactive TUI.", "warning"); return; }
+      registry.refresh();
+      let selected: string | undefined;
+      const reported = new Set<string>();
+      const readSettings = (): ReturnType<typeof getCallbackSettings> => {
+        try { return getCallbackSettings(ctx); }
+        catch (error) {
+          const message = `Callback default unavailable; using Wait until idle: ${error instanceof Error ? error.message : String(error)}`;
+          if (!reported.has(message)) { ctx.ui.notify(message, "error"); reported.add(message); }
+          return { mode: "hold", source: "default" };
+        }
+      };
+      while (true) {
+        const links = registry.list();
+        try {
+          selected = await chooseHarnessSetting(ctx, links, selected, {
+            get: readSettings,
+            change: mode => changeCallbackSetting(pi, ctx, mode),
+            save: () => saveCallbackDefault(readSettings().mode),
+          }, registry.controls());
+        } catch (error) {
+          ctx.ui.notify(`Settings unavailable: ${error instanceof Error ? error.message : String(error)}`, "error");
+          return;
+        }
+        if (!selected) return;
+        const link = links.find(item => `link:${item.id}` === selected);
+        if (!link) continue;
+        try { await link.open(ctx); }
+        catch (error) { ctx.ui.notify(`Settings unavailable: ${error instanceof Error ? error.message : String(error)}`, "error"); }
+      }
+    },
+  });
+}

package/extensions/settings/page.ts

@@ -0,0 +1,96 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Text, getKeybindings, setKeybindings, KeybindingsManager, TUI_KEYBINDINGS, matchesKey, type SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsControl, SettingsLink } from "./registry.ts";
+
+export interface CallbackSettingsControl {
+  get(): { mode: "hold" | "steer"; source: "session" | "default" };
+  change(mode: "hold" | "steer"): void;
+  save(): void;
+}
+
+const CALLBACK_SETTING_ID = "callbacks:while-busy";
+const callbackLabel = (mode: "hold" | "steer") => mode === "steer" ? "Steer active run" : "Wait until idle";
+
+export async function chooseHarnessSetting(ctx: any, links: SettingsLink[], selected?: string, callbacks?: CallbackSettingsControl, controls: SettingsControl[] = []): Promise<string | undefined> {
+  return ctx.ui.custom((tui: any, theme: Theme, _kb: unknown, done: (id?: string) => void) => {
+    let callbackMode = callbacks?.get().mode ?? "hold";
+    const callbackSetting: SettingItem | undefined = callbacks ? {
+      id: CALLBACK_SETTING_ID,
+      label: "Completions while busy",
+      currentValue: callbackLabel(callbackMode),
+      description: callbacks.get().source === "session" ? "Session setting" : "User default",
+      values: ["Wait until idle", "Steer active run"],
+    } : undefined;
+    const items: SettingItem[] = [
+      ...(callbackSetting ? [callbackSetting] : []),
+      ...controls.map(control => ({ id: `setting:${control.id}`, label: control.label, currentValue: control.get(), description: "Session setting", values: control.values })),
+      ...links.map(link => ({ id: `link:${link.id}`, label: link.label, currentValue: link.command, description: "Open package settings", values: [link.command] })),
+    ];
+    const feedback = new Text("", 0, 0);
+    let changing = false;
+    const report = (message: string, error = false) => {
+      feedback.setText(theme.fg(error ? "error" : "muted", message));
+      tui.requestRender?.();
+    };
+    const list = new SettingsList(items, 10, {
+      label: (text, active) => theme.fg(active ? "accent" : "text", text),
+      value: (text, active) => active ? theme.inverse(text) : theme.fg("muted", text),
+      description: text => theme.fg("muted", text), cursor: "> ", hint: text => theme.fg("dim", text),
+    }, (id, value) => {
+      const control = controls.find(item => `setting:${item.id}` === id);
+      if (control) {
+        const previous = control.get();
+        changing = true;
+        report("Saving session setting...");
+        Promise.resolve().then(() => control.change(value, ctx)).then(() => {
+          list.updateValue(id, control.get());
+          report("Session setting saved.");
+        }).catch(error => {
+          list.updateValue(id, previous);
+          report(error instanceof Error ? error.message : String(error), true);
+        }).finally(() => { changing = false; tui.requestRender?.(); });
+        return;
+      }
+      if (id !== CALLBACK_SETTING_ID || !callbacks || !callbackSetting) { done(id); return; }
+      try {
+        const nextMode = value === "Steer active run" ? "steer" : "hold";
+        callbacks.change(nextMode);
+        callbackMode = nextMode;
+        callbackSetting.description = "Session setting";
+        report("Session setting saved.");
+      } catch (error) {
+        list.updateValue(CALLBACK_SETTING_ID, callbackLabel(callbackMode));
+        report(error instanceof Error ? error.message : String(error), true);
+      }
+    }, () => done(), { enableSearch: false });
+
+    const index = selected ? items.findIndex(item => item.id === selected) : 0;
+    if (index > 0) {
+      // SettingsList has no public selection setter. Restore synchronously using
+      // default navigation, then return the untouched user bindings before input.
+      const bindings = getKeybindings();
+      try {
+        setKeybindings(new KeybindingsManager(TUI_KEYBINDINGS));
+        for (let i = 0; i < index; i++) list.handleInput("\x1b[B");
+      } finally { setKeybindings(bindings); }
+    }
+    const page = new Container();
+    page.addChild(new Text(theme.fg("accent", theme.bold("Harness settings")), 0, 0));
+    page.addChild(list);
+    if (callbacks) page.addChild(new Text(theme.fg("dim", "Callbacks autosave to this session. Ctrl+S saves the default for future sessions."), 0, 0));
+    page.addChild(feedback);
+    return {
+      render: (width: number) => page.render(width),
+      invalidate: () => page.invalidate(),
+      handleInput(data: string) {
+        if (changing) return;
+        if (callbacks && matchesKey(data, "ctrl+s")) {
+          try { callbacks.save(); report("Callback default saved."); }
+          catch (error) { report(error instanceof Error ? error.message : String(error), true); }
+          return;
+        }
+        list.handleInput(data);
+      },
+    };
+  });
+}

package/extensions/settings/registry.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export interface SettingsLink {
+  id: string;
+  label: string;
+  command: string;
+  open(ctx: ExtensionCommandContext): Promise<void> | void;
+}
+
+export interface SettingsControl {
+  id: string;
+  label: string;
+  values: string[];
+  get(): string;
+  change(value: string, ctx: ExtensionCommandContext): Promise<void> | void;
+}
+
+export function createSettingsRegistry(pi: ExtensionAPI) {
+  const links = new Map<string, SettingsLink>();
+  const controls = new Map<string, SettingsControl>();
+  const conflicts = new Set<string>();
+  const stop = pi.events.on("harness-settings:register", (candidate: unknown) => {
+    const link = candidate as Partial<SettingsLink & SettingsControl> | null;
+    if (!link || !/^[a-z][a-z0-9-]*$/.test(link.id ?? "") || typeof link.label !== "string") return;
+    const control = Array.isArray(link.values) && link.values.length > 1 && link.values.every(value => typeof value === "string")
+      && typeof link.get === "function" && typeof link.change === "function";
+    if (!control && (typeof link.command !== "string" || !link.command.startsWith("/") || typeof link.open !== "function")) return;
+    if (conflicts.has(link.id!)) return;
+    const prior = links.get(link.id!);
+    const priorControl = controls.get(link.id!);
+    if ((prior && (control || prior.open !== link.open)) ||
+      (priorControl && (!control || priorControl.change !== link.change || priorControl.get !== link.get))) {
+      links.delete(link.id!); controls.delete(link.id!); conflicts.add(link.id!); return;
+    }
+    if (control) controls.set(link.id!, link as SettingsControl);
+    else links.set(link.id!, link as SettingsLink);
+  });
+  return {
+    refresh() { links.clear(); controls.clear(); conflicts.clear(); pi.events.emit("harness-settings:request", undefined); },
+    list() { return [...links.values()].sort((a, b) => a.label.localeCompare(b.label)); },
+    controls() { return [...controls.values()].sort((a, b) => a.label.localeCompare(b.label)); },
+    dispose() { stop(); links.clear(); controls.clear(); conflicts.clear(); },
+  };
+}

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",