pi-compact-tools 0.9.2 → 0.10.0

package/extensions/compact-tools-hook.ts

@@ -0,0 +1,47 @@
+/**
+ * The replacement body. `original` is the unwrapped method itself, not bound, so
+ * nothing is allocated per call: behaviors invoke it as `original.apply(self, args)`.
+ */
+export type MethodBehavior = (self: any, args: any[], original: (...args: any[]) => any) => any;
+
+type HookRecord = { behavior: MethodBehavior };
+
+/**
+ * Wrap `target[method]` once per process and route every call through the
+ * behavior that the most recently loaded copy of this extension supplied.
+ *
+ * Pi's classes and TUI outlive a /reload, but this module does not. A wrapper
+ * that closed over its own code would keep running the first version until Pi
+ * restarts, so the wrapper only looks up the behavior, and each load replaces it.
+ * `legacy` names the markers under which older versions kept the unwrapped
+ * method; their wrappers are dropped in favor of that original rather than
+ * stacked beneath the new one.
+ */
+export function hookMethod(
+	target: object,
+	method: string,
+	name: string,
+	behavior: MethodBehavior,
+	legacy: readonly symbol[] = [],
+): boolean {
+	const holder = target as Record<PropertyKey, any>;
+	const key = Symbol.for(`pi-compact-tools.hook.${name}`);
+	if (Object.hasOwn(holder, key)) {
+		(holder[key] as HookRecord).behavior = behavior;
+		return true;
+	}
+	if (typeof holder[method] !== "function") return false;
+	let original: (...args: any[]) => any = holder[method];
+	for (const marker of legacy) {
+		if (Object.hasOwn(holder, marker) && typeof holder[marker] === "function") {
+			original = holder[marker];
+			break;
+		}
+	}
+	const record: HookRecord = { behavior };
+	holder[method] = function (this: unknown, ...args: any[]) {
+		return record.behavior(this, args, original);
+	};
+	Object.defineProperty(holder, key, { value: record });
+	return true;
+}

package/extensions/compact-tools-invocation.ts

@@ -1,4 +1,5 @@
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
 import { normalizeLineEndings } from "./compact-tools-core.ts";
 import type { ToolArgs } from "./compact-tools-types.ts";
 
@@ -32,6 +33,40 @@ export function getCallDetails(name: string, args: ToolArgs): string {
 	return name === "grep" ? `/${pattern}/ in ${path}` : `${pattern} in ${path}`;
 }
 
+/** Argument names that usually identify what a tool call is about, most specific first. */
+const CUSTOM_SUMMARY_KEYS = [
+	"command", "query", "queries", "q", "url", "urls", "path", "file_path", "paths",
+	"pattern", "prompt", "question", "claim", "name", "id", "tool",
+];
+const CUSTOM_SUMMARY_MAX_LENGTH = 160;
+
+function summaryValue(value: unknown): string | undefined {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) {
+		const parts = value.filter((item) => typeof item === "string" || typeof item === "number").map(String);
+		return parts.length > 0 ? parts.join(", ") : undefined;
+	}
+	return undefined;
+}
+
+/** One line describing a custom tool call; the full arguments stay available when expanded. */
+export function summarizeCustomArguments(args: ToolArgs): string {
+	const keys = [...CUSTOM_SUMMARY_KEYS.filter((key) => key in args), ...Object.keys(args)];
+	for (const key of keys) {
+		const value = summaryValue(args[key]);
+		if (!value?.trim()) continue;
+		const line = stripTerminalSequences(normalizeLineEndings(value))
+			.replace(/[\x00-\x1f\x7f]/gu, " ")
+			.replace(/\s+/gu, " ")
+			.trim();
+		return line.length > CUSTOM_SUMMARY_MAX_LENGTH
+			? `${line.slice(0, CUSTOM_SUMMARY_MAX_LENGTH - 1).trimEnd()}…`
+			: line;
+	}
+	return "";
+}
+
 export function getArgumentDetails(name: string, args: ToolArgs): ToolArgs {
 	if (name === "edit" || INLINE_ARGUMENT_TOOLS.has(name)) return {};
 	return collectArgumentDetails(name, args);
@@ -319,6 +354,30 @@ export function getTextResult(result: AgentToolResult<unknown>): string {
 	return normalizeLineEndings(parts.join("\n")).trimEnd();
 }
 
+const FAILURE_REASON_MAX_LENGTH = 140;
+
+/** Pull a useful diagnostic into a collapsed failed row without exposing raw control sequences. */
+export function summarizeFailure(name: string, output: string): string | undefined {
+	const lines = normalizeLineEndings(stripTerminalSequences(output))
+		.split("\n")
+		.map((line) => line.replace(/[\x00-\x1f\x7f]/gu, " ").trim())
+		.filter(Boolean);
+	if (lines.length === 0) return undefined;
+	const last = lines[lines.length - 1]!;
+	const shellStatus = (name === "bash" || name === "powershell")
+		&& /^Command (?:exited with code \d+|timed out.*|aborted|terminated.*)$/iu.test(last)
+		? last
+		: undefined;
+	const diagnostic = shellStatus
+		? lines.slice(0, -1).reverse().find((line) =>
+			/\b(?:error|failed|failure|fatal|exception|denied|not found|no such file)\b|ENOENT/iu.test(line))
+		: undefined;
+	const reason = diagnostic ? `${diagnostic} (${shellStatus})` : shellStatus ?? lines[0]!;
+	return reason.length > FAILURE_REASON_MAX_LENGTH
+		? `${reason.slice(0, FAILURE_REASON_MAX_LENGTH - 1).trimEnd()}…`
+		: reason;
+}
+
 type ResultDetails = {
 	diff?: unknown;
 	patch?: unknown;
@@ -361,6 +420,19 @@ export function getEditChanges(result: AgentToolResult<unknown>): string {
 		.trimEnd();
 }
 
+/** How many lines an edit added and removed, counted from the diff Pi attaches to its result. */
+export function countEditChanges(result: AgentToolResult<unknown>): { added: number; removed: number } | undefined {
+	const diff = getEditDiff(result);
+	if (!diff) return undefined;
+	let added = 0;
+	let removed = 0;
+	for (const line of diff.split("\n")) {
+		if (line.startsWith("+")) added++;
+		else if (line.startsWith("-")) removed++;
+	}
+	return { added, removed };
+}
+
 const READ_FOOTER = /\n\n(\[(?:Showing lines |\d+ more lines in file\.)[^\n]*\])$/u;
 
 /** Separate a read's file contents from the continuation notice Pi appends to them. */

package/extensions/compact-tools-layout.ts

@@ -399,6 +399,16 @@ export function limitComponentLines(component: Component, maximumLines: number,
 	}, () => component.invalidate?.());
 }
 
+/** Indent another renderer's component under the result rail so it reads as part of the row. */
+export function railComponent(component: Component, theme: Theme): Component {
+	const rail = paintChrome(theme, " │ ");
+	const railWidth = visibleWidth(rail);
+	return new CachedComponent(
+		(width) => component.render(Math.max(1, width - railWidth)).map((line) => rail + line),
+		() => component.invalidate?.(),
+	);
+}
+
 export function renderArguments(args: ToolArgs, theme: Theme): Component {
 	const json = JSON.stringify(args, null, 2) ?? "{}";
 	const styled = styleMultiline(json, (line) => theme.fg("toolOutput", line));

package/extensions/compact-tools-palette.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import {
 	colorizeRgb,
+	interpolateRgb,
 	liftContrast,
 	neutralizeRgb,
 	themeColorRgb,
@@ -107,6 +108,23 @@ export function indicatorPulse(theme: Theme): ColorRamp | undefined {
 	return ramp(theme, PULSE_LOW, PULSE_HIGH);
 }
 
+/** How far the brightest activity dot moves from the level's color toward the label's crest. */
+const ACTIVITY_CREST_MIX = 0.3;
+/** Contrast against the background of an unlit dot: the level's hue, barely there. */
+const ACTIVITY_UNLIT = 0.05;
+
+/**
+ * Silent-mode activity dots: an unlit dot is the thinking level's own hue faded
+ * almost into the background, and a lit one shows that hue lifted a little. The
+ * label's full crest washes every level toward the same near-white.
+ */
+export function activityGlow(theme: Theme, level: ThinkingLevel): ColorRamp | undefined {
+	const glow = progressGlow(theme, level);
+	if (!glow) return undefined;
+	const lit = interpolateRgb(glow.from, glow.to, ACTIVITY_CREST_MIX);
+	return { from: withContrast(theme, lit, ACTIVITY_UNLIT, ACTIVITY_UNLIT), to: lit };
+}
+
 /** Sweep endpoints for the working label at a thinking level, resting color to crest. */
 export function progressGlow(theme: Theme, level: ThinkingLevel): ColorRamp | undefined {
 	const raw = themeColorRgb(theme, thinkingLevelColor(level));

package/extensions/compact-tools-progress.ts

@@ -1,10 +1,10 @@
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { stripTerminalSequences, truncateToWidth } from "@earendil-works/pi-tui";
+import { onTick } from "./compact-tools-clock.ts";
 import { colorizeRgb, interpolateRgb } from "./compact-tools-color.ts";
 import { progressGlow, type ColorRamp, type ThinkingLevel } from "./compact-tools-palette.ts";
 import type { ToolArgs } from "./compact-tools-types.ts";
 
-const GLOW_INTERVAL_MS = 80;
 
 const TOOL_PROGRESS_MESSAGES: Readonly<Record<string, string>> = {
 	read: "Reading file…",
@@ -89,7 +89,8 @@ export class ProgressController {
 	private message: string | undefined;
 	private frames: string[] = [];
 	private frame = 0;
-	private timer: ReturnType<typeof setInterval> | undefined;
+	/** Stops this label's share of the animation clock. */
+	private stopTicking: (() => void) | undefined;
 	private level: ThinkingLevel = "medium";
 
 	constructor(private readonly pi: ExtensionAPI) {
@@ -119,7 +120,12 @@ export class ProgressController {
 			const remaining = [...this.activeTools.values()].at(-1);
 			this.setMessage(remaining ?? "Processing results…");
 		});
-		pi.on("agent_end", () => {
+		// agent_end closes one low-level run, after which Pi may still retry, compact,
+		// or continue from a settlement boundary. Pi hides its own working row at that
+		// point and rebuilds it at the next turn_start from the message last set here,
+		// so releasing the label at agent_end makes a retried turn reappear under Pi's
+		// default label. Release it at the final settlement instead.
+		pi.on("agent_settled", () => {
 			if (!this.context) return;
 			this.activeTools.clear();
 			this.clearMessage();
@@ -161,17 +167,16 @@ export class ProgressController {
 	}
 
 	private setMessage(message: string): void {
-		if (!this.context || (this.message === message && this.timer)) return;
+		if (!this.context || (this.message === message && this.stopTicking)) return;
 		this.message = message;
 		this.frames = createGlowFrames(message, this.context.ui.theme, this.level);
 		this.frame = 0;
 		this.renderMessage();
-		if (this.timer) return;
-		this.timer = setInterval(() => {
+		if (this.stopTicking) return;
+		this.stopTicking = onTick(() => {
 			this.frame++;
 			this.renderMessage();
-		}, GLOW_INTERVAL_MS);
-		this.timer.unref?.();
+		});
 	}
 
 	private renderMessage(): void {
@@ -188,7 +193,7 @@ export class ProgressController {
 	}
 
 	private stopAnimation(): void {
-		if (this.timer) clearInterval(this.timer);
-		this.timer = undefined;
+		this.stopTicking?.();
+		this.stopTicking = undefined;
 	}
 }

package/extensions/compact-tools-release.ts

@@ -0,0 +1,136 @@
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DynamicBorder, getAgentDir, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import { Spacer, Text } from "@earendil-works/pi-tui";
+
+/** One marker file per version shown, so two Pi processes can't both show it. */
+const NOTICE_DIRECTORY = "compact-tools-notices";
+const WIDGET_KEY = "compact-tools-release-notes";
+const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+
+export type ReleaseNotes = Record<string, readonly string[]>;
+
+type Chat = { children: unknown[]; addChild(component: unknown): void };
+
+function readReleaseNotes(): ReleaseNotes | undefined {
+	try {
+		return JSON.parse(readFileSync(new URL("../release-notes.json", import.meta.url), "utf8")) as ReleaseNotes;
+	} catch {
+		return undefined;
+	}
+}
+
+export function installedVersion(): string {
+	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string };
+	return manifest.version;
+}
+
+/** Order two plain x.y.z versions; anything else sorts first. */
+export function compareVersions(left: string, right: string): number {
+	const a = VERSION.exec(left);
+	const b = VERSION.exec(right);
+	if (!a || !b) return a ? 1 : b ? -1 : 0;
+	for (let part = 1; part <= 3; part++) {
+		const difference = Number(a[part]) - Number(b[part]);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+
+/**
+ * The notes to show, newest first: every version with notes after the last one
+ * shown, up to the installed one. With nothing shown before, only the installed
+ * version's notes appear: that is either a new install or an update from a
+ * version that predates these notices, and there is no telling which.
+ */
+export function releasesToShow(
+	installed: string,
+	notes: ReleaseNotes,
+	lastShown: string | undefined,
+): Array<{ version: string; notes: readonly string[] }> {
+	const versions = lastShown === undefined
+		? (notes[installed]?.length ? [installed] : [])
+		: Object.keys(notes).filter((version) =>
+			VERSION.test(version)
+			&& compareVersions(version, lastShown) > 0
+			&& compareVersions(version, installed) <= 0
+			&& notes[version]!.length > 0);
+	return versions
+		.sort((left, right) => compareVersions(right, left))
+		.map((version) => ({ version, notes: notes[version]! }));
+}
+
+function lastShownVersion(directory: string): string | undefined {
+	try {
+		return readdirSync(directory)
+			.filter((name) => VERSION.test(name))
+			.sort(compareVersions)
+			.at(-1);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Pi's chat, the transcript document's last child, reached the same way in regular and fullscreen mode. */
+function chatOf(tui: unknown): Chat | undefined {
+	const chat = (tui as { children?: Array<{ children?: unknown[] }> }).children?.[0]?.children?.at(-1) as Chat | undefined;
+	return Array.isArray(chat?.children) && typeof chat.addChild === "function" ? chat : undefined;
+}
+
+/** Drawn like Pi's own "What's New": a bordered block in the chat, never saved to the session or sent to the model. */
+function addReleaseBlock(chat: Chat, theme: Theme, releases: ReturnType<typeof releasesToShow>): void {
+	const border = (line: string) => theme.fg("border", line);
+	if (chat.children.length > 0) chat.addChild(new Spacer(1));
+	chat.addChild(new DynamicBorder(border));
+	releases.forEach(({ version, notes }, index) => {
+		if (index > 0) chat.addChild(new Spacer(1));
+		chat.addChild(new Text(theme.bold(theme.fg("accent", `What's new in pi-compact-tools v${version}`)), 1, 0));
+		chat.addChild(new Spacer(1));
+		chat.addChild(new Text(notes.map((note) => theme.fg("dim", `• ${note}`)).join("\n"), 1, 0));
+	});
+	chat.addChild(new DynamicBorder(border));
+}
+
+/**
+ * Show what changed since the version last shown, once, the way Pi shows its own
+ * changelog: only when a conversation starts, as a bordered block in the chat.
+ * A resumed session keeps the notes for the next new one.
+ */
+export function showReleaseNotice(
+	ctx: ExtensionContext,
+	version = installedVersion(),
+	agentDir = getAgentDir(),
+	notes: ReleaseNotes | undefined = readReleaseNotes(),
+): boolean {
+	if (ctx.mode !== "tui" || !VERSION.test(version) || !notes) return false;
+	const resumed = ctx.sessionManager?.getEntries?.().some((entry) => entry.type === "message") ?? false;
+	if (resumed) return false;
+	const directory = join(agentDir, NOTICE_DIRECTORY);
+	const releases = releasesToShow(version, notes, lastShownVersion(directory));
+	if (releases.length === 0) return false;
+	try {
+		mkdirSync(directory, { recursive: true });
+		// Exclusive creation: of two Pi processes starting together, only one shows it.
+		closeSync(openSync(join(directory, version), "wx"));
+	} catch {
+		return false;
+	}
+	let shown = false;
+	// An invisible widget is the extension API's way to reach Pi's TUI and its chat.
+	// Pi builds the widget at once, so it can be removed right after.
+	ctx.ui.setWidget(WIDGET_KEY, (tui) => {
+		const chat = chatOf(tui);
+		if (chat) {
+			addReleaseBlock(chat, ctx.ui.theme, releases);
+			shown = true;
+		}
+		return { render: () => [], invalidate() {} };
+	}, { placement: "belowEditor" });
+	ctx.ui.setWidget(WIDGET_KEY, undefined, { placement: "belowEditor" });
+	if (!shown) {
+		const text = releases.map(({ version: shownVersion, notes: shownNotes }) =>
+			`pi-compact-tools v${shownVersion}\n${shownNotes.map((note) => `  • ${note}`).join("\n")}`).join("\n");
+		ctx.ui.notify(text, "info");
+	}
+	return true;
+}

package/extensions/compact-tools-runtime.ts

@@ -1,11 +1,13 @@
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_CONFIG } from "./compact-tools-config.ts";
-import type {
-	BuiltInDefinition,
-	CompactToolName,
-	CompactToolsConfig,
-	RenderContext,
-	RowState,
+import { isSilent } from "./compact-tools-silent.ts";
+import {
+	SUPPORTED_TOOL_SET,
+	type BuiltInDefinition,
+	type CompactToolName,
+	type CompactToolsConfig,
+	type RenderContext,
+	type RowState,
 } from "./compact-tools-types.ts";
 
 const MAX_TRACKED_ROWS = 2_000;
@@ -59,6 +61,8 @@ export class ToolRuntime {
 		if (!this.indicatorTimer) {
 			this.indicatorTimer = setInterval(() => {
 				this.indicatorFrame++;
+				// Silent mode hides tool rows; repainting the screen for them would be pure cost.
+				if (isSilent()) return;
 				for (const requestRender of this.indicatorInvalidators.values()) requestRender();
 			}, INDICATOR_INTERVAL_MS);
 			this.indicatorTimer.unref?.();
@@ -66,7 +70,7 @@ export class ToolRuntime {
 		return this.indicatorFrame;
 	}
 
-	syncExpansion(state: RowState, hostExpanded: boolean, name: CompactToolName): boolean {
+	syncExpansion(state: RowState, hostExpanded: boolean, name: string): boolean {
 		const initialized = this.initializeExpansion(state, name, hostExpanded);
 		if (!initialized && state.lastHostExpanded !== hostExpanded) {
 			state.lastHostExpanded = hostExpanded;
@@ -74,12 +78,12 @@ export class ToolRuntime {
 			// A non-auto-compacted row collapses back to its bounded preview. Hiding it
 			// here removes the clicked row from under the pointer, so the next click can
 			// accidentally hit the Thinking block that moved into the same coordinates.
-			state.preview = !hostExpanded && !this.configValue.auto_compact[name];
+			state.preview = !hostExpanded && !this.autoCompact(name);
 		}
 		return state.expanded ?? false;
 	}
 
-	setResultAvailable(state: RowState, name: CompactToolName, available: boolean): void {
+	setResultAvailable(state: RowState, name: string, available: boolean): void {
 		this.initializeExpansion(state, name);
 		state.hasResult = available;
 	}
@@ -99,6 +103,22 @@ export class ToolRuntime {
 		return state;
 	}
 
+	/**
+	 * Record when a tool this extension does not wrap starts and ends. Pi reports
+	 * both to extensions before it redraws the row, and the row draws its status
+	 * dot before its result, so without this a finished custom tool kept the
+	 * running dot. Wrapped built-ins already have timings, which are kept.
+	 */
+	noteExecutionStart(toolCallId: string): void {
+		if (!this.executionTimings.has(toolCallId)) this.executionTimings.set(toolCallId, { startedAt: Date.now() });
+	}
+
+	noteExecutionEnd(toolCallId: string): void {
+		const timing = this.executionTimings.get(toolCallId) ?? { startedAt: Date.now() };
+		timing.endedAt ??= Date.now();
+		this.executionTimings.set(toolCallId, timing);
+	}
+
 	createTimedExecute(definition: BuiltInDefinition): TimedExecute {
 		const execute = definition.execute as TimedExecute;
 		return async (...args: any[]) => {
@@ -131,12 +151,19 @@ export class ToolRuntime {
 		this.indicatorFrame = 0;
 	}
 
-	private initializeExpansion(state: RowState, name: CompactToolName, hostExpanded = false): boolean {
+	/** Built-ins follow their own auto_compact entry; a custom tool its own entry if it has one, else the custom_tools policy. */
+	private autoCompact(name: string): boolean {
+		return SUPPORTED_TOOL_SET.has(name)
+			? this.configValue.auto_compact[name as CompactToolName]
+			: this.configValue.auto_compact[name] ?? this.configValue.custom_tools.auto_compact;
+	}
+
+	private initializeExpansion(state: RowState, name: string, hostExpanded = false): boolean {
 		if (state.configRevision === this.configRevision) return false;
 		state.configRevision = this.configRevision;
 		state.lastHostExpanded = hostExpanded;
 		state.expanded = hostExpanded;
-		state.preview = !hostExpanded && !this.configValue.auto_compact[name];
+		state.preview = !hostExpanded && !this.autoCompact(name);
 		return true;
 	}