@quandev104/pi-style 0.1.6 → 0.1.7

package/extension-src/pi-style/features/tools/boxed/turn-summary.ts

@@ -0,0 +1,368 @@
+// Turn tool summary registry (ADR 0007).
+//
+// When a turn completes, its finalized tool blocks collapse into a single
+// summary line (`➔ Read 2 files, ran 4 shell commands · 3.1s`) rendered by the
+// turn's leader (its first non-error tool call); every other non-error tool
+// item of the turn renders zero lines. Error results stay visible, interrupted
+// turns never collapse, and Pi's global tool-output toggle (Ctrl+O) expands
+// everything again (`options.expanded` is read, never written).
+//
+// Design notes:
+// - The registry is populated from **session content**, never from runtime
+//   event flags: the live path registers the final assistant message +
+//   toolResults at `turn_end`; the restore path rebuilds the registry from
+//   `sessionManager.getEntries()` at session start / `session_tree`, so
+//   scroll-back and session resume render identically.
+// - A turn is "ended" only when every tool call of its message has a matching
+//   tool result AND (live) turn_end fired / (restore) the message is
+//   finalized (`stopReason`) or a later user/assistant message exists.
+// - Elapsed per member is frozen from the renderer wall-clock state
+//   (STARTED_AT/ENDED_AT) at the first post-turn result pass; the summary
+//   totals the members' frozen elapsed. No render-time I/O.
+// - No new Pi-core patch identity: the dispatcher (boxed/index.ts) decides
+//   collapse before the per-tool renderers run, so every certified renderer
+//   surface stays untouched when the turn is not collapsed.
+
+import type { Component } from "@earendil-works/pi-tui";
+import type { BoxTheme } from "../../../shared/box.js";
+import { safeTruncateToWidth } from "../../../shared/render-budget.js";
+import { pluralForm } from "./output-tree.js";
+
+export interface TurnMemberInfo {
+	readonly toolCallId: string;
+	readonly toolName: string;
+	/** Whether a tool result was registered for this call (run completeness). */
+	readonly hasResult: boolean;
+	isError: boolean;
+	/** Frozen wall-clock elapsed (ms), recorded from the renderer context state. */
+	elapsedMs?: number;
+}
+
+export interface TurnState {
+	/** First non-error member; renders the summary line. Empty when every member errored. */
+	leaderId: string;
+	ended: boolean;
+	members: readonly TurnMemberInfo[];
+}
+
+interface TurnEntry {
+	readonly turn: TurnState;
+	readonly member: TurnMemberInfo;
+}
+
+const memberByCallId = new Map<string, TurnEntry>();
+
+/** Per-member component invalidate callbacks captured during render passes. */
+const invalidateByCallId = new Map<string, () => void>();
+
+/** Reset all turn state (session start/shutdown). */
+export function resetTurnRegistry(): void {
+	memberByCallId.clear();
+	invalidateByCallId.clear();
+}
+
+interface ToolCallLike {
+	readonly type?: unknown;
+	readonly id?: unknown;
+	readonly name?: unknown;
+}
+
+function toolCallsOf(message: unknown): ToolCallLike[] {
+	if (!message || typeof message !== "object") return [];
+	const content = (message as { readonly content?: unknown }).content;
+	if (!Array.isArray(content)) return [];
+	const calls: ToolCallLike[] = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const candidate = item as ToolCallLike;
+		if (candidate.type === "toolCall") calls.push(candidate);
+	}
+	return calls;
+}
+
+function registerTurn(
+	calls: readonly ToolCallLike[],
+	isErrorById: ReadonlyMap<string, boolean>,
+	ended: boolean,
+): TurnState | undefined {
+	if (calls.length === 0) return undefined;
+	const complete = calls.every((call) => typeof call.id === "string" && isErrorById.has(call.id));
+	const members: TurnMemberInfo[] = calls.map((call) => {
+		const toolCallId = String(call.id ?? "");
+		return {
+			toolCallId,
+			toolName: typeof call.name === "string" ? call.name : "tool",
+			hasResult: isErrorById.has(toolCallId),
+			isError: isErrorById.get(toolCallId) === true,
+		};
+	});
+	const leader = members.find((member) => !member.isError);
+	const turn: TurnState = {
+		leaderId: leader?.toolCallId ?? "",
+		ended: ended && complete,
+		members: Object.freeze(members),
+	};
+	for (const member of members) memberByCallId.set(member.toolCallId, { turn, member });
+	return turn;
+}
+
+export interface TurnResultLike {
+	readonly toolCallId: string;
+	readonly isError?: boolean;
+}
+
+/**
+ * One summary group = one agent run (user request → `agent_end`). Pi emits
+ * `turn_end` per assistant message, so tool batches of the same request are
+ * appended to the same run and collapse into ONE summary line at `agent_end`.
+ */
+let currentRun: TurnState | undefined;
+
+/** Live path: start a fresh run group (`agent_start`). */
+export function beginAgentRun(): void {
+	currentRun = undefined;
+}
+
+/**
+ * Live path: append the finalized assistant message's tool calls and results
+ * to the current run (`turn_end` event). The run stays expanded until
+ * `finishAgentRun`; a batch interrupted mid-tool never collapses.
+ */
+export function registerTurnFromMessage(message: unknown, toolResults: readonly TurnResultLike[]): void {
+	const calls = toolCallsOf(message);
+	if (calls.length === 0) return;
+	const isErrorById = new Map<string, boolean>();
+	for (const result of toolResults) {
+		if (typeof result?.toolCallId !== "string") continue;
+		isErrorById.set(result.toolCallId, result.isError === true);
+	}
+	const newMembers: TurnMemberInfo[] = calls.map((call) => {
+		const toolCallId = String(call.id ?? "");
+		return {
+			toolCallId,
+			toolName: typeof call.name === "string" ? call.name : "tool",
+			hasResult: isErrorById.has(toolCallId),
+			isError: isErrorById.get(toolCallId) === true,
+		};
+	});
+	const leader = newMembers.find((member) => !member.isError);
+	if (!currentRun) {
+		currentRun = {
+			leaderId: leader?.toolCallId ?? "",
+			ended: false,
+			members: Object.freeze(newMembers),
+		};
+	} else {
+		if (currentRun.leaderId === "" && leader) currentRun.leaderId = leader.toolCallId;
+		currentRun.members = Object.freeze([...currentRun.members, ...newMembers]);
+	}
+	for (const member of newMembers) memberByCallId.set(member.toolCallId, { turn: currentRun, member });
+}
+
+/**
+ * Live path: finalize the current run (`agent_end`). Returns the run so the
+ * caller can invalidate its blocks; undefined when the run had no tool calls
+ * or is interrupted (a call without a result stays expanded).
+ */
+export function finishAgentRun(): TurnState | undefined {
+	const run = currentRun;
+	currentRun = undefined;
+	if (!run) return undefined;
+	// A member without a result means the run was interrupted before every call
+	// settled; such a run never collapses.
+	if (run.members.every((member) => member.hasResult)) run.ended = true;
+	return run.ended ? run : undefined;
+}
+
+interface TurnEntryLike {
+	readonly type?: unknown;
+	readonly message?: {
+		readonly role?: unknown;
+		readonly content?: unknown;
+		readonly stopReason?: unknown;
+		readonly toolCallId?: unknown;
+		readonly isError?: unknown;
+	};
+}
+
+/**
+ * Restore path: rebuild the registry from session entries (session start /
+ * `session_tree`). Consecutive assistant messages between user messages form
+ * one run; a run is ended when every tool call has a result AND a later user
+ * message exists (historical) or its last assistant message is finalized
+ * (`stopReason`). The currently streaming run stays expanded.
+ */
+export function rebuildTurnRegistryFromEntries(entries: readonly TurnEntryLike[] | undefined): void {
+	memberByCallId.clear();
+	if (!Array.isArray(entries)) return;
+	const isErrorById = new Map<string, boolean>();
+	const resultById = new Set<string>();
+	const runs: Array<{
+		calls: ToolCallLike[];
+		lastStopReason: string | undefined;
+		followedByUser: boolean;
+	}> = [];
+	let current: (typeof runs)[number] | undefined;
+	const closeRun = () => {
+		if (current && current.calls.length > 0) runs.push(current);
+		current = undefined;
+	};
+	entries.forEach((entry) => {
+		if (entry?.type !== "message") return;
+		const message = entry.message;
+		if (message?.role === "toolResult" && typeof message.toolCallId === "string") {
+			resultById.add(message.toolCallId);
+			isErrorById.set(message.toolCallId, message.isError === true);
+		} else if (message?.role === "assistant") {
+			if (!current) current = { calls: [], lastStopReason: undefined, followedByUser: false };
+			const calls = toolCallsOf(message);
+			current.calls.push(...calls);
+			if (typeof message.stopReason === "string" && message.stopReason !== "")
+				current.lastStopReason = message.stopReason;
+		} else if (message?.role === "user") {
+			if (current) {
+				current.followedByUser = true;
+				closeRun();
+			} else {
+				// A user message with no preceding open run is a plain boundary.
+				closeRun();
+			}
+		}
+	});
+	closeRun();
+	for (const run of runs) {
+		const complete = run.calls.every((call) => typeof call.id === "string" && resultById.has(call.id));
+		const ended = complete && (run.followedByUser || run.lastStopReason !== undefined);
+		registerTurn(run.calls, isErrorById, ended);
+	}
+}
+
+/** Registry lookup for the render dispatcher. */
+export function getTurnEntry(toolCallId: string): TurnEntry | undefined {
+	return memberByCallId.get(toolCallId);
+}
+
+/**
+ * Capture a member's component invalidate callback during a render pass. Pi
+ * only re-invokes the tool renderer selectors from updateDisplay(); calling
+ * the captured callback after turn_end rebuilds the block with the collapsed
+ * summary. Idempotent per toolCallId (latest component wins).
+ */
+export function noteTurnMemberRender(toolCallId: string, invalidate: () => void): void {
+	if (typeof invalidate !== "function") return;
+	invalidateByCallId.set(toolCallId, invalidate);
+}
+
+/**
+ * Force the just-finished turn's tool blocks to re-render (updateDisplay).
+ * Components that never rendered (headless/print) have no captured callback.
+ */
+export function invalidateTurnMembers(turn: TurnState): void {
+	for (const member of turn.members) {
+		const invalidate = invalidateByCallId.get(member.toolCallId);
+		if (!invalidate) continue;
+		try {
+			invalidate();
+		} catch {
+			// A detached component must not break the turn-end path.
+			invalidateByCallId.delete(member.toolCallId);
+		}
+	}
+}
+
+/**
+ * Freeze a member's wall-clock elapsed into the registry (idempotent; the
+ * value is frozen by the renderer state once the terminal result rendered).
+ */
+export function noteTurnMemberElapsed(toolCallId: string, elapsedMs: number | undefined): void {
+	if (elapsedMs === undefined) return;
+	const entry = memberByCallId.get(toolCallId);
+	if (!entry || entry.member.elapsedMs !== undefined) return;
+	entry.member.elapsedMs = elapsedMs;
+}
+
+/** Per-tool summary phrasing: `Read 2 files` / `ran 4 shell commands`. */
+const TURN_SUMMARY_STYLE: Readonly<Record<string, { readonly verb: string; readonly unit: string }>> = Object.freeze({
+	read: { verb: "Read", unit: "file" },
+	bash: { verb: "ran", unit: "shell command" },
+	ls: { verb: "Listed", unit: "path" },
+	find: { verb: "Found", unit: "file" },
+	grep: { verb: "Grepped", unit: "pattern" },
+	edit: { verb: "Edited", unit: "file" },
+	write: { verb: "Wrote", unit: "file" },
+	quick_edit: { verb: "Edited", unit: "file" },
+	substitute_edit: { verb: "Edited", unit: "file" },
+	target_edit: { verb: "Edited", unit: "file" },
+});
+
+export interface TurnSummaryParts {
+	/** `Read 2 files`, `ran 4 shell commands`, ... in first-use order. */
+	readonly parts: readonly string[];
+	readonly failedCount: number;
+	/** Sum of members' frozen elapsed; undefined when nothing was recorded. */
+	readonly elapsedMs: number | undefined;
+}
+
+/** Aggregate a turn's non-error members into summary parts (pure). */
+export function turnSummaryParts(turn: TurnState): TurnSummaryParts {
+	const counts = new Map<string, number>();
+	const order: string[] = [];
+	let failedCount = 0;
+	let elapsedMs: number | undefined;
+	for (const member of turn.members) {
+		if (member.isError) {
+			failedCount++;
+			continue;
+		}
+		if (member.elapsedMs !== undefined) elapsedMs = (elapsedMs ?? 0) + member.elapsedMs;
+		const existing = counts.get(member.toolName);
+		if (existing === undefined) {
+			counts.set(member.toolName, 1);
+			order.push(member.toolName);
+		} else counts.set(member.toolName, existing + 1);
+	}
+	const parts = order.map((toolName) => {
+		const count = counts.get(toolName) ?? 0;
+		const style = TURN_SUMMARY_STYLE[toolName] ?? { verb: "ran", unit: `${toolName} call` };
+		return `${style.verb} ${count} ${pluralForm(style.unit, count)}`;
+	});
+	return { parts, failedCount, elapsedMs };
+}
+
+function formatTurnSummaryLine(theme: BoxTheme, turn: TurnState): string {
+	const summary = turnSummaryParts(turn);
+	// The summary is deliberately quiet: the whole line renders dim so completed
+	// tool work recedes behind the assistant's answer. Only the failed marker
+	// stays error-colored (errors must remain visible).
+	const parts = summary.parts.join(", ");
+	let line = `${theme.fg("dim", `➔ ${parts}`)}`;
+	if (summary.failedCount > 0)
+		line += theme.fg("error", ` · ${summary.failedCount} ${pluralForm("failed", summary.failedCount)}`);
+	if (summary.elapsedMs !== undefined) line += theme.fg("dim", ` · ${(summary.elapsedMs / 1000).toFixed(2)}s`);
+	return line;
+}
+
+/** Leader call component: renders the live turn summary line on every pass. */
+export function renderTurnSummaryCall(theme: BoxTheme, turn: TurnState): Component {
+	return {
+		invalidate() {},
+		render(width: number): string[] {
+			return [safeTruncateToWidth(formatTurnSummaryLine(theme, turn), Math.max(1, width), "…")];
+		},
+	};
+}
+
+/**
+ * Empty result component for the turn-summary leader. The summary lives in the
+ * call component; the result adds nothing. Deliberately NOT the shared
+ * EMPTY_BATCH_COMPONENT singleton, so the decoration's hideBatchMember
+ * (identity-compared) never hides the leader.
+ */
+export function emptyTurnResult(): Component {
+	return {
+		invalidate() {},
+		render() {
+			return [];
+		},
+	};
+}

package/extension-src/pi-style/features/tools/index.ts

@@ -113,6 +113,19 @@ const DEFAULT_SNAPSHOT: ToolDecorationSnapshot = Object.freeze({
 });
 let ownerGeneration = 0;
 const piStyleWrappers = new WeakSet<RenderFunction>();
+
+/**
+ * The real Tui instance captured from decorated tool components (`instance.ui`),
+ * used to request a repaint after the turn registry flips a turn to collapsed
+ * (pi only re-paints after its own events; the renderer selectors re-run on
+ * updateDisplay, but the screen refresh still needs a requestRender).
+ */
+let capturedToolUi: { requestRender?: (force?: boolean) => void } | undefined;
+
+/** Request a screen repaint through the captured tool Tui (no-op headless). */
+export function requestToolPresentationRender(): void {
+	capturedToolUi?.requestRender?.();
+}
 let toolTestHooks: { defineProperty?: typeof Reflect.defineProperty; deleteProperty?: typeof Reflect.deleteProperty } =
 	{};
 export function __setToolDecorationTestHooks(hooks: typeof toolTestHooks): () => void {
@@ -392,12 +405,14 @@ export function createToolDecorationOwner(snapshot: Partial<ToolDecorationSnapsh
 			} else if (outcome === "later-owner") state.active.delete(record);
 			else state.failed++;
 		}
+		capturedToolUi = undefined;
 		const archive = state.active.size === 0 ? finalize(state) : undefined;
 		return { restored: state.restored, failed: state.failed, diagnostics: new Map(state.diagnostics), archive };
 	};
 	return Object.freeze({
 		decorateToolRendererSelection(subtype: RendererSubtype, original: unknown, instance: object, args: unknown[]) {
 			if (typeof original !== "function") return undefined;
+			capturedToolUi = (instance as { ui?: { requestRender?: (force?: boolean) => void } }).ui ?? capturedToolUi;
 			const renderer = Reflect.apply(original, instance, args);
 			if (state.snapshot.style === "compact-box") {
 				const toolName = (instance as { toolName?: unknown }).toolName;

package/extension-src/pi-style/pi/compatibility-coordinator.ts

@@ -168,6 +168,7 @@ export function createCompatibilityCoordinator(dispose = disposePiCompatibilityP
 					assistantPrefix: authorization.ascii ? "[assistant] " : "│ ",
 					assistantEnabled,
 					collapseHiddenThinking: thinkingCollapseEnabled,
+					hideInterimText: config.messages.hideInterimText && messagesEnabled,
 				},
 				toolSnapshot: {
 					callMarker: authorization.ascii ? "[tool] " : "[tool] ",

package/extension-src/pi-style/pi/compatibility-probe.ts

@@ -369,7 +369,13 @@ function shape(spec: TargetSpec): boolean {
 export interface CompatibilityProbeOptions {
 	markers?: Set<string>;
 	config?: Readonly<{
-		messages: { enabled: boolean; assistantPrefix: boolean; specialBlocks: boolean; hideThinkingLabel: boolean };
+		messages: {
+			enabled: boolean;
+			assistantPrefix: boolean;
+			specialBlocks: boolean;
+			hideThinkingLabel: boolean;
+			hideInterimText: boolean;
+		};
 		tools: { enabled: boolean; style: string; maxCollapsedLines: number; maxExpandedLines: number; dimOutput: boolean };
 		preset: string;
 	}>;
@@ -417,7 +423,7 @@ function surfaceDisabled(spec: TargetSpec, config: CompatibilityProbeOptions["co
 	if (!config.messages.enabled) return true;
 	if (spec.subtype === "native-assistant-message" && spec.method === "render") return !config.messages.assistantPrefix;
 	if (spec.subtype === "native-assistant-message" && spec.method === "updateContent")
-		return !config.messages.hideThinkingLabel;
+		return !config.messages.hideThinkingLabel && !config.messages.hideInterimText;
 	if (isSpecialBlock(spec)) return !config.messages.specialBlocks;
 	return true;
 }

package/extension-src/pi-style/pi/index.ts

@@ -1,6 +1,14 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { StatusSnapshot } from "../domain/status.js";
 import { closeActiveBatch } from "../features/tools/boxed/batch.js";
+import {
+	beginAgentRun,
+	finishAgentRun,
+	invalidateTurnMembers,
+	rebuildTurnRegistryFromEntries,
+	registerTurnFromMessage,
+} from "../features/tools/boxed/turn-summary.js";
+import { requestToolPresentationRender } from "../features/tools/index.js";
 import { registerPiStyleCommand } from "./commands.js";
 import { type CompatibilityTestHooks, createPiStyleSessionCoordinator } from "./session-coordinator.js";
 import { usageFromSession } from "./session-usage.js";
@@ -66,7 +74,12 @@ export default function piStyleExtension(pi: ExtensionAPI): void {
 		}
 		await coordinator.start(event, ctx);
 	});
-	pi.on("agent_start", () => coordinator.app.runtime.current?.dismissStartup());
+	pi.on("agent_start", () => {
+		coordinator.app.runtime.current?.dismissStartup();
+		// Turn summary (ADR 0007): a summary group spans the whole agent run
+		// (user request → agent_end), not pi's per-message turn_end.
+		beginAgentRun();
+	});
 	pi.on("input", (event, _ctx) => {
 		coordinator.app.runtime.current?.dismissStartup();
 		// Bare `!`/`!!` submit guard: Pi treats `!`-prefixed input as a direct bash
@@ -111,9 +124,30 @@ export default function piStyleExtension(pi: ExtensionAPI): void {
 	// message/turn boundaries, mirroring Pi's native footer; per-chunk updates
 	// stay usage-free to keep streaming cheap.
 	pi.on("message_end", (_event, ctx) => coordinator.app.update({ ...usagePatch(ctx) }, "coalesced"));
-	pi.on("turn_end", (_event, ctx) => coordinator.app.update({ ...usagePatch(ctx) }, "deferred"));
+	pi.on("turn_end", (event, ctx) => {
+		// Append the finalized assistant message's tool batch to the current run.
+		registerTurnFromMessage(event.message, event.toolResults);
+		coordinator.app.update({ ...usagePatch(ctx) }, "deferred");
+	});
+	pi.on("agent_end", () => {
+		// The run is complete: collapse its tool blocks into one summary line.
+		// Pi only re-invokes the tool renderer selectors from updateDisplay(), so
+		// the captured per-block invalidate callbacks force the collapse and the
+		// captured Tui repaints. Interrupted runs (a call without a result) stay
+		// expanded.
+		const run = finishAgentRun();
+		if (run) {
+			invalidateTurnMembers(run);
+			requestToolPresentationRender();
+		}
+	});
 	pi.on("agent_settled", (_event, ctx) => coordinator.app.update({ ...usagePatch(ctx) }, "coalesced"));
-	pi.on("session_tree", (_event, ctx) => coordinator.app.update({ ...usagePatch(ctx) }, "deferred"));
+	pi.on("session_tree", (_event, ctx) => {
+		// Rebuild the turn registry from session content so restored/branched
+		// history renders collapsed consistently (no in-process turn_end events).
+		rebuildTurnRegistryFromEntries(ctx.sessionManager.getEntries());
+		coordinator.app.update({ ...usagePatch(ctx) }, "deferred");
+	});
 	pi.on("session_compact", (_event, ctx) => coordinator.app.update({ ...usagePatch(ctx) }, "deferred"));
 	pi.on("tool_result", (event, ctx) => {
 		if (["write", "edit", "bash"].includes(event.toolName)) {

package/extension-src/pi-style/pi/session-coordinator.ts

@@ -13,6 +13,7 @@ import {
 	stopAllElapsedTickers,
 	type ToolsRenderConfig,
 } from "../features/tools/boxed/session-config.js";
+import { rebuildTurnRegistryFromEntries, resetTurnRegistry } from "../features/tools/boxed/turn-summary.js";
 import { createCompatibilityCoordinator } from "./compatibility-coordinator.js";
 import {
 	type CompatibilityCleanupResult,
@@ -175,6 +176,11 @@ export function createPiStyleSessionCoordinator(pi: ExtensionAPI, hooks: Compati
 			resetBatchRegistry();
 			resetGrepRegistry();
 			resetBashTreeRegistry();
+			// Turn summaries (ADR 0007): rebuild the registry from session content so
+			// restored/forked history renders collapsed before the first render pass
+			// (deterministic; no in-process turn_end events needed).
+			resetTurnRegistry();
+			rebuildTurnRegistryFromEntries(ctx.sessionManager.getEntries());
 			// Stop any 1s elapsed re-render ticker left by a tool that was still
 			// running when the session ended.
 			stopAllElapsedTickers();
@@ -247,6 +253,7 @@ export function createPiStyleSessionCoordinator(pi: ExtensionAPI, hooks: Compati
 			resetBatchRegistry();
 			resetGrepRegistry();
 			resetBashTreeRegistry();
+			resetTurnRegistry();
 			stopAllElapsedTickers();
 			app.sessionShutdown();
 			// Tier C prototype patches stay installed across session switches. Pi renders

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quandev104/pi-style",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A native-layout, cohesive visual style package for Pi.",
   "license": "MIT",
   "type": "module",