pi-compact-tools 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dong Hyeong Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# pi-compact-tools
+
+Compact, expandable rendering for all of Pi's built-in tools, bundled with a polished GitHub Dark theme.
+
+> Formerly published as `@nedleeds/pi-compact-ui`. New installations should use `pi-compact-tools`.
+
+Designed for a focused, low-noise terminal workflow.
+
+![Built-in tool support](https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/assets/built-in-tool-support.png)
+
+## Demo
+
+**Spinner and status** – track active execution and see duration-aware completion indicators.
+
+![Spinner and duration indicators](https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/assets/spinner-status.gif)
+
+**Keyboard expansion** – press `Ctrl+O` to cycle through detail levels.
+
+![Ctrl+O expansion](https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/assets/keyboard-expand.gif)
+
+**Edit diffs** – click a finished `edit` row to reveal the diff, click again to collapse.
+
+![Edit diff expansion](https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/assets/edit-diff.gif)
+
+## Features
+
+- Compact one-line rendering for configurable built-in tools
+- Supports `read`, `write`, `edit`, `bash`, `powershell`, `grep`, `find`, and `ls`
+- Click or `Ctrl+O` to cycle through available detail levels
+- Skips argument and output levels that contain no additional information
+- Animated, configurable tool spinner with a bright → dark → bright frame tone cycle
+- Millisecond-precision execution duration with configurable indicators
+- Short and full output previews with dark `│` / `└─` visual grouping
+- Clean edit diffs without duplicate JSON arguments or leading blank lines
+- GitHub Dark theme with distinct tool, output, success, and error colors
+- No Nerd Font requirement
+
+## Supported tools
+
+| Tool | Purpose | Compact by default |
+| --- | --- | :---: |
+| `read` | Read files and images | Yes |
+| `write` | Create or overwrite files | Yes |
+| `edit` | Apply exact text replacements with clean diffs | Yes |
+| `bash` | Run shell commands | Yes |
+| `grep` | Search file contents | Opt-in |
+| `find` | Find files by glob pattern | Opt-in |
+| `ls` | List directory contents | Opt-in |
+| `powershell` | Run PowerShell commands | Opt-in |
+
+Enable opt-in tools with the [`tools` configuration](#configuration). PowerShell is intended for Windows; the other seven tools are demonstrated above on macOS.
+
+## Requirements
+
+- pi `0.85.1` or newer is recommended
+- Node.js 20 or newer
+- Fullscreen TUI mode is required for spinner animation and mouse-click expansion; `Ctrl+O` works without it
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:pi-compact-tools
+```
+
+Or directly from GitHub:
+
+```bash
+pi install git:github.com/nedleeds/pi-compact-ui
+```
+
+Restart pi or run `/reload` after installation.
+
+To migrate from the previous package name without loading both copies:
+
+```bash
+pi remove npm:@nedleeds/pi-compact-ui
+pi install npm:pi-compact-tools
+```
+
+The GitHub repository retains its original URL, so existing Git installation links and raw Schema URLs continue to work.
+
+## Theme
+
+The package includes the `github-dark-pro` theme. Select it from pi's settings UI or set it in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "theme": "github-dark-pro"
+}
+```
+
+## Configuration
+
+The extension works without a configuration file. Its defaults are defined in the source code.
+
+To customize it globally, create `~/.pi/agent/compact-tools.json` using the example below. The included JSON Schema provides completion and validation in compatible editors.
+
+For project-specific settings, create:
+
+```text
+<project>/.pi/compact-tools.json
+```
+
+Project configuration is loaded only for trusted projects. Values are merged in this order:
+
+```text
+built-in defaults
+→ ~/.pi/agent/compact-tools.json
+→ <project>/.pi/compact-tools.json
+```
+
+Default configuration:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/schemas/compact-tools.schema.json",
+  "tools": ["read", "write", "edit", "bash"],
+  "previewLines": 10,
+  "spinner": {
+    "frames": ["◐", "◓", "◑", "◒"],
+    "intervalMs": 120
+  },
+  "durationIndicators": [
+    { "underMs": 1000, "icon": "⚡️", "color": "warning" },
+    { "underMs": 10000, "icon": "🔥", "color": "#D95C3F" },
+    { "underMs": 30000, "icon": "○", "color": "#79C0FF" },
+    { "icon": "⏳", "color": "#D2A8FF" }
+  ]
+}
+```
+
+`tools` selects which built-in definitions receive compact rendering. Omitted tools retain Pi's default renderer. The array replaces, rather than extends, the previous configuration layer. To enable every Unix-compatible tool:
+
+```json
+{
+  "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"]
+}
+```
+
+`powershell` is also supported and can be selected explicitly on Windows. Unsupported names are ignored with a warning.
+
+Spinner frames automatically use a bright → dark → bright tone cycle (`muted` → `dim` → `border` → `dim` → `muted`). Fast tools are never delayed artificially: they transition directly to their success or failure state.
+
+`durationIndicators` must use ascending `underMs` values. The final entry must omit `underMs` and acts as the fallback. Durations are displayed with millisecond precision, for example `Done in 0.023s`. The optional `color` field applies color to the icon only; when omitted, it defaults to `dim`. Existing icon-only configurations remain fully compatible, including configurations copied from older releases of this README:
+
+```json
+{ "underMs": 1000, "icon": "⚡️" }
+```
+
+Icons are arbitrary strings and do not require Nerd Font glyphs. Emoji, ASCII text, or terminal-safe Unicode symbols can be used instead. `color` accepts semantic theme colors such as `warning`, `accent`, `success`, `error`, `muted`, `dim`, `border`, and `text`, as well as six-digit hex colors such as `#800020` or `#FFFFFF`. Hex colors use truecolor when available and fall back to the nearest ANSI-256 color.
+
+### Recommended Nerd Font preset
+
+If your terminal uses a [Nerd Font](https://www.nerdfonts.com/), the following configuration is recommended. It enables compact rendering for all eight built-in tools and uses single-width Nerd Font duration icons:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/schemas/compact-tools.schema.json",
+  "tools": ["read", "write", "edit", "bash", "powershell", "grep", "find", "ls"],
+  "previewLines": 10,
+  "spinner": {
+    "frames": ["✽", "✻", "✲", "✢", "✲", "✻"],
+    "intervalMs": 80
+  },
+  "durationIndicators": [
+    { "underMs": 1000, "icon": "\uf0e7", "color": "warning" },
+    { "underMs": 10000, "icon": "\uf490", "color": "#D95C3F" },
+    { "underMs": 30000, "icon": "\udb81\udde3", "color": "#79C0FF" },
+    { "icon": "\udb81\udd1f", "color": "#D2A8FF" }
+  ]
+}
+```
+
+The escaped code points keep the preset readable on GitHub, whose web-font stack does not include Nerd Font glyphs. JSON automatically decodes them to the intended icons when the configuration is loaded. On systems without PowerShell, remove `"powershell"` from `tools`. The default Unicode configuration remains the most portable option and does not require a Nerd Font.
+
+## Expansion levels
+
+Only levels with meaningful content are included. Depending on the tool call, the cycle may be:
+
+```text
+summary → arguments → output preview → full output → summary
+summary → output → summary
+summary only
+```
+
+`edit` uses:
+
+```text
+summary → diff → summary
+```
+
+## Compatibility and limitations
+
+- The package overrides only the built-in definitions selected by `tools`, while preserving their execution behavior and metadata.
+- Another extension overriding the same tool names may conflict depending on extension load order.
+- Tools registered by other extensions are not modified.
+- Duration is measured from the first rendered tool call through completion of the built-in tool's `execute()` call. This includes streamed arguments for large `write` and `edit` calls. Timing survives `/reload` within the same process, but is unavailable after a full process restart.
+- `timeout` tool arguments are execution limits, not measured durations, and are intentionally omitted from the compact shell summary.
+- Windows (`CRLF`), Unix/macOS (`LF`), and classic Mac (`CR`) output is normalized before line counting and preview rendering.
+- Spinner animation is disabled in regular TUI mode to avoid unsafe redraws of transcript rows above the viewport.
+- Separator glyphs use the theme's `border` color; actual darkness depends on the selected theme.
+- Emoji appearance depends on terminal and system font support. All default duration icons use Unicode 6.0 or earlier.
+
+## Development
+
+```bash
+npm install
+npm run check
+pi -e .
+```
+
+When testing with `pi -e .`, disable any local copy of `compact-tools.ts` to avoid duplicate tool overrides.
+
+## Security
+
+Pi extensions execute with full system access. Review extension source before installing third-party packages.
+
+## License
+
+MIT

package/examples/compact-tools.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/schemas/compact-tools.schema.json",
+  "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"],
+  "previewLines": 10,
+  "spinner": {
+    "frames": ["◐", "◓", "◑", "◒"],
+    "intervalMs": 120
+  },
+  "durationIndicators": [
+    { "underMs": 1000, "icon": "⚡️", "color": "warning" },
+    { "underMs": 10000, "icon": "🔥", "color": "#D95C3F" },
+    { "underMs": 30000, "icon": "○", "color": "#79C0FF" },
+    { "icon": "⏳", "color": "#D2A8FF" }
+  ]
+}

package/extensions/compact-tools-core.ts

@@ -0,0 +1,89 @@
+/** Pure configuration, timing, text, and color helpers for compact tool rendering. */
+
+const DURATION_INDICATOR_COLORS = [
+	"accent", "border", "borderAccent", "borderMuted", "success", "error", "warning", "muted", "dim", "text",
+	"thinkingText", "toolTitle", "toolOutput", "toolDiffAdded", "toolDiffRemoved", "toolDiffContext", "bashMode",
+] as const;
+
+export type ThemeDurationIndicatorColor = (typeof DURATION_INDICATOR_COLORS)[number];
+export type DurationIndicatorColor = ThemeDurationIndicatorColor | `#${string}`;
+export type DurationIndicatorConfig = {
+	underMs?: number;
+	icon: string;
+	color?: DurationIndicatorColor;
+};
+export type RowStatus = "pending" | "running" | "success" | "error";
+
+const DURATION_INDICATOR_COLOR_SET = new Set<string>(DURATION_INDICATOR_COLORS);
+export const HEX_COLOR_PATTERN = /^#[0-9a-f]{6}$/i;
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPositiveInteger(value: unknown, minimum: number): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= minimum;
+}
+
+export function parseDurationIndicators(value: unknown): DurationIndicatorConfig[] | undefined {
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	const rules: DurationIndicatorConfig[] = [];
+	let previousLimit = 0;
+	for (const [index, item] of value.entries()) {
+		if (!isObject(item) || typeof item.icon !== "string" || item.icon.length === 0) return undefined;
+		if (
+			item.color !== undefined &&
+			(typeof item.color !== "string" ||
+				(!DURATION_INDICATOR_COLOR_SET.has(item.color) && !HEX_COLOR_PATTERN.test(item.color)))
+		) return undefined;
+		const color = item.color as DurationIndicatorColor | undefined;
+		const isLast = index === value.length - 1;
+		if (isLast && item.underMs === undefined) rules.push({ icon: item.icon, color });
+		else if (isPositiveInteger(item.underMs, previousLimit + 1)) {
+			previousLimit = item.underMs;
+			rules.push({ underMs: item.underMs, icon: item.icon, color });
+		} else return undefined;
+	}
+	return rules.at(-1)?.underMs === undefined ? rules : undefined;
+}
+
+export function normalizeLineEndings(value: string): string {
+	return value.replace(/\r\n?|\n/g, "\n");
+}
+
+export function classifyCallStatus(isError: boolean, executionStarted: boolean, completed: boolean): RowStatus {
+	if (isError) return "error";
+	if (completed) return "success";
+	return executionStarted ? "running" : "pending";
+}
+
+export function formatDurationMs(elapsedMs: number): string {
+	return `${(elapsedMs / 1000).toFixed(3)}s`;
+}
+
+export function selectDurationIndicator(
+	rules: readonly DurationIndicatorConfig[],
+	elapsedMs: number | undefined,
+): DurationIndicatorConfig | undefined {
+	if (elapsedMs === undefined) return rules[0];
+	return rules.find((rule) => rule.underMs === undefined || elapsedMs < rule.underMs);
+}
+
+function colorDistanceSquared(red: number, green: number, blue: number, candidate: readonly number[]): number {
+	return (red - candidate[0]!) ** 2 + (green - candidate[1]!) ** 2 + (blue - candidate[2]!) ** 2;
+}
+
+export function rgbToAnsi256(red: number, green: number, blue: number): number {
+	const cube = [red, green, blue].map((channel) => Math.round(channel / 51));
+	const cubeRgb = cube.map((channel) => channel * 51);
+	const cubeIndex = 16 + 36 * cube[0]! + 6 * cube[1]! + cube[2]!;
+	const average = (red + green + blue) / 3;
+	const grayStep = Math.max(0, Math.min(23, Math.round((average - 8) / 10)));
+	const grayLevel = 8 + grayStep * 10;
+	const grayRgb = [grayLevel, grayLevel, grayLevel];
+	return colorDistanceSquared(red, green, blue, grayRgb) < colorDistanceSquared(red, green, blue, cubeRgb)
+		? 232 + grayStep
+		: cubeIndex;
+}

package/extensions/compact-tools.ts

@@ -0,0 +1,704 @@
+/** Compact rendering and shared status indicators for built-in tools. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+	AgentToolResult,
+	BashToolDetails,
+	BashToolInput,
+	ExtensionAPI,
+	Theme,
+	ToolDefinition,
+	ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import {
+	CONFIG_DIR_NAME,
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+	createPowerShellToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+	getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { Container, Text, visibleWidth } from "@earendil-works/pi-tui";
+import {
+	classifyCallStatus,
+	formatDurationMs,
+	HEX_COLOR_PATTERN,
+	normalizeLineEndings,
+	parseDurationIndicators,
+	rgbToAnsi256,
+	selectDurationIndicator,
+	type DurationIndicatorConfig,
+	type RowStatus,
+	type ThemeDurationIndicatorColor,
+} from "./compact-tools-core.ts";
+
+const MAX_LEVEL = 3;
+const CONFIG_FILE = "compact-tools.json";
+const SUPPORTED_TOOLS = ["read", "write", "edit", "bash", "powershell", "grep", "find", "ls"] as const;
+const SUPPORTED_TOOL_SET = new Set<string>(SUPPORTED_TOOLS);
+
+type CompactToolName = (typeof SUPPORTED_TOOLS)[number];
+
+export interface CompactToolsConfig {
+	tools: CompactToolName[];
+	previewLines: number;
+	spinner: {
+		frames: string[];
+		intervalMs: number;
+	};
+	durationIndicators: DurationIndicatorConfig[];
+}
+
+export const DEFAULT_CONFIG: CompactToolsConfig = {
+	tools: ["read", "write", "edit", "bash"],
+	previewLines: 10,
+	spinner: {
+		frames: ["◐", "◓", "◑", "◒"],
+		intervalMs: 120,
+	},
+	durationIndicators: [
+		{ underMs: 1_000, icon: "⚡️", color: "warning" },
+		{ underMs: 10_000, icon: "🔥", color: "#D95C3F" },
+		{ underMs: 30_000, icon: "○", color: "#79C0FF" },
+		{ icon: "⏳", color: "#D2A8FF" },
+	],
+};
+
+let config = DEFAULT_CONFIG;
+let animateRows = false;
+const registeredCompactTools = new Set<CompactToolName>();
+
+interface RowState {
+	level?: number;
+	availableLevels?: number[];
+	lastExpanded?: boolean;
+	frame?: number;
+	startedAt?: number;
+	endedAt?: number;
+	timer?: ReturnType<typeof setInterval>;
+	originalResultComponent?: Component;
+}
+
+type ToolArgs = Record<string, unknown>;
+type BuiltInDefinition = ToolDefinition<any, any, any>;
+type BaseRenderContext = Parameters<NonNullable<BuiltInDefinition["renderCall"]>>[2];
+type RenderContext<TArgs = ToolArgs> = Omit<BaseRenderContext, "args" | "state"> & {
+	args: TArgs;
+	state: RowState;
+};
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function warnConfig(path: string, message: string): void {
+	console.error(`[compact-tools] ${path}: ${message}`);
+}
+
+function isIntegerInRange(value: unknown, minimum: number, maximum: number): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= minimum && value <= maximum;
+}
+
+function isNonEmptyStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.length > 0);
+}
+
+function parseTools(value: unknown, path: string): CompactToolName[] | undefined {
+	if (!Array.isArray(value)) {
+		warnConfig(path, "tools must be an array; using previous values");
+		return undefined;
+	}
+	const valid = value.filter((item): item is CompactToolName => typeof item === "string" && SUPPORTED_TOOL_SET.has(item));
+	const invalid = value.filter((item) => typeof item !== "string" || !SUPPORTED_TOOL_SET.has(item));
+	if (invalid.length > 0) warnConfig(path, `ignoring unsupported tools: ${invalid.map(String).join(", ")}`);
+	return [...new Set(valid)];
+}
+
+function mergeConfig(base: CompactToolsConfig, value: unknown, path: string): CompactToolsConfig {
+	if (value === undefined) return base;
+	if (!isObject(value)) {
+		warnConfig(path, "expected a JSON object; using previous values");
+		return base;
+	}
+	const tools = value.tools === undefined ? base.tools : (parseTools(value.tools, path) ?? base.tools);
+	const previewValue = value.previewLines;
+	const validPreviewLines = isIntegerInRange(previewValue, 1, 1_000);
+	const previewLines = validPreviewLines ? previewValue : base.previewLines;
+	if (previewValue !== undefined && !validPreviewLines) {
+		warnConfig(path, "previewLines must be an integer from 1 to 1000; using previous value");
+	}
+	const spinner = parseSpinnerConfig(base.spinner, value.spinner, path);
+	const durationIndicators = parseDurationIndicators(value.durationIndicators) ?? base.durationIndicators;
+	if (value.durationIndicators !== undefined && durationIndicators === base.durationIndicators) {
+		warnConfig(path, "invalid durationIndicators; using previous values");
+	}
+	return { tools, previewLines, spinner, durationIndicators };
+}
+
+function parseSpinnerConfig(
+	base: CompactToolsConfig["spinner"],
+	value: unknown,
+	path: string,
+): CompactToolsConfig["spinner"] {
+	if (value === undefined) return base;
+	if (!isObject(value)) {
+		warnConfig(path, "spinner must be an object; using previous values");
+		return base;
+	}
+	const framesValue = value.frames;
+	const intervalValue = value.intervalMs;
+	const validFrames = isNonEmptyStringArray(framesValue);
+	const validInterval = isIntegerInRange(intervalValue, 40, 5_000);
+	if (framesValue !== undefined && !validFrames) warnConfig(path, "spinner.frames must be a non-empty string array");
+	if (intervalValue !== undefined && !validInterval) warnConfig(path, "spinner.intervalMs must be 40–5000");
+	return {
+		frames: validFrames ? framesValue : base.frames,
+		intervalMs: validInterval ? intervalValue : base.intervalMs,
+	};
+}
+
+function readConfig(path: string): unknown {
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		warnConfig(path, error instanceof Error ? error.message : String(error));
+		return undefined;
+	}
+}
+
+function getConfiguredTuiMode(): "regular" | "fullscreen" {
+	for (let index = 0; index < process.argv.length; index++) {
+		const argument = process.argv[index];
+		if (argument === "--tui-mode") {
+			const value = process.argv[index + 1];
+			if (value === "regular" || value === "fullscreen") return value;
+		}
+		if (argument?.startsWith("--tui-mode=")) {
+			const value = argument.slice("--tui-mode=".length);
+			if (value === "regular" || value === "fullscreen") return value;
+		}
+	}
+
+	const settings = readConfig(join(getAgentDir(), "settings.json"));
+	return isObject(settings) && settings.tuiMode === "fullscreen" ? "fullscreen" : "regular";
+}
+
+export function loadConfig(cwd?: string, projectTrusted = false): CompactToolsConfig {
+	const globalPath = join(getAgentDir(), CONFIG_FILE);
+	let loaded = mergeConfig(DEFAULT_CONFIG, readConfig(globalPath), globalPath);
+	if (!cwd || !projectTrusted) return loaded;
+	const projectPath = join(cwd, CONFIG_DIR_NAME, CONFIG_FILE);
+	loaded = mergeConfig(loaded, readConfig(projectPath), projectPath);
+	return loaded;
+}
+
+const SPINNING_ROWS_KEY = Symbol.for("pi.compact-tools.spinning-rows");
+const EXECUTION_TIMINGS_KEY = Symbol.for("pi.compact-tools.execution-timings");
+type ExecutionTiming = { startedAt: number; endedAt?: number };
+const globalState = globalThis as typeof globalThis & {
+	[SPINNING_ROWS_KEY]?: Set<RowState>;
+	[EXECUTION_TIMINGS_KEY]?: Map<string, ExecutionTiming>;
+};
+for (const staleState of globalState[SPINNING_ROWS_KEY] ?? []) {
+	if (staleState.timer) clearInterval(staleState.timer);
+}
+const spinningRows = new Set<RowState>();
+const executionTimings = globalState[EXECUTION_TIMINGS_KEY] ?? new Map<string, ExecutionTiming>();
+globalState[SPINNING_ROWS_KEY] = spinningRows;
+globalState[EXECUTION_TIMINGS_KEY] = executionTimings;
+
+function advanceLevel(state: RowState, expanded: boolean): number {
+	state.level ??= 0;
+	if (state.lastExpanded === undefined) {
+		state.lastExpanded = expanded;
+		return state.level;
+	}
+	if (state.lastExpanded !== expanded) {
+		state.lastExpanded = expanded;
+		const levels = state.availableLevels ?? [0, 1];
+		const index = levels.indexOf(state.level);
+		state.level = levels[(index + 1) % levels.length] ?? 0;
+	}
+	return state.level;
+}
+
+function setAvailableLevels(state: RowState, levels: number[]): void {
+	state.availableLevels = levels;
+	if (!levels.includes(state.level ?? 0)) state.level = 0;
+}
+
+function getOutputLevels(output: string): number[] {
+	const normalized = normalizeLineEndings(output).trimEnd();
+	if (!normalized) return [];
+	return normalized.split("\n").length > config.previewLines ? [2, 3] : [2];
+}
+
+function stopSpinner(state: RowState): void {
+	if (state.timer) clearInterval(state.timer);
+	state.timer = undefined;
+	spinningRows.delete(state);
+}
+
+function syncSpinner(state: RowState, running: boolean, invalidate: () => void): void {
+	// Regular mode cannot safely redraw a transcript row after it has scrolled
+	// above the viewport. Keep active rows static there to avoid full transcript
+	// redraws and duplicated-looking terminal output.
+	if (!running || !animateRows || config.spinner.frames.length < 2) {
+		stopSpinner(state);
+		return;
+	}
+	if (state.timer) return;
+
+	state.frame ??= 0;
+	state.timer = setInterval(() => {
+		state.frame = ((state.frame ?? 0) + 1) % config.spinner.frames.length;
+		try {
+			invalidate();
+		} catch {
+			stopSpinner(state);
+		}
+	}, config.spinner.intervalMs);
+	state.timer.unref?.();
+	spinningRows.add(state);
+}
+
+function syncTiming(state: RowState, callStarted: boolean, finished: boolean): void {
+	if (callStarted && state.startedAt === undefined) state.startedAt = Date.now();
+	if (finished && state.startedAt !== undefined && state.endedAt === undefined) {
+		state.endedAt = Date.now();
+	}
+}
+
+function restoreExecutionTiming(state: RowState, toolCallId: string): boolean {
+	const timing = executionTimings.get(toolCallId);
+	if (!timing) return false;
+	state.startedAt = timing.startedAt;
+	state.endedAt = timing.endedAt;
+	return timing.endedAt !== undefined;
+}
+
+function persistExecutionTiming(state: RowState, toolCallId: string): void {
+	if (state.startedAt === undefined) return;
+	const timing = executionTimings.get(toolCallId) ?? { startedAt: state.startedAt };
+	timing.startedAt = state.startedAt;
+	if (state.endedAt !== undefined) timing.endedAt = state.endedAt;
+	executionTimings.set(toolCallId, timing);
+	if (executionTimings.size <= 2_000) return;
+	const oldestToolCallId = executionTimings.keys().next().value;
+	if (oldestToolCallId !== undefined) executionTimings.delete(oldestToolCallId);
+}
+
+function syncRow(
+	ctx: RenderContext,
+	running = ctx.executionStarted && ctx.state.endedAt === undefined,
+	finished = false,
+): RowState {
+	const state = ctx.state;
+	if (restoreExecutionTiming(state, ctx.toolCallId)) running = false;
+	const callStarted = !ctx.argsComplete || ctx.executionStarted || running;
+	syncTiming(state, callStarted, finished);
+	persistExecutionTiming(state, ctx.toolCallId);
+	syncSpinner(state, running, ctx.invalidate);
+	return state;
+}
+
+function resetUiState(clearTimings = false): void {
+	for (const state of [...spinningRows]) stopSpinner(state);
+	if (clearTimings) executionTimings.clear();
+}
+
+function spinnerTone(frameIndex: number, frameCount: number): "muted" | "dim" | "border" {
+	if (frameCount < 3) return "muted";
+	const position = frameIndex / (frameCount - 1);
+	const distanceFromCenter = Math.abs(position - 0.5) * 2;
+	if (distanceFromCenter < 0.34) return "border";
+	if (distanceFromCenter < 0.75) return "dim";
+	return "muted";
+}
+
+function resolveCallStatus(ctx: RenderContext, state: RowState): RowStatus {
+	return classifyCallStatus(ctx.isError, ctx.executionStarted, state.endedAt !== undefined);
+}
+
+function renderIndicator(theme: Theme, state: RowState, status: RowStatus): string {
+	if (status === "error") return theme.fg("error", "⊗");
+	if (status === "success") return theme.fg("success", "●");
+	// A new pending or running row starts at frame zero, then shares the same animation.
+	const frameIndex = state.frame ?? 0;
+	const frame = config.spinner.frames[frameIndex] ?? config.spinner.frames[0] ?? "◐";
+	return theme.fg(spinnerTone(frameIndex, config.spinner.frames.length), frame);
+}
+
+function formatDuration(state: RowState): string | undefined {
+	if (state.startedAt === undefined) return undefined;
+	return formatDurationMs((state.endedAt ?? Date.now()) - state.startedAt);
+}
+
+function durationIndicator(state: RowState): DurationIndicatorConfig | undefined {
+	// Reloading extensions recreates row state, so already-completed rows no longer
+	// have timing data. Keep their configured indicator visible using the first rule.
+	const elapsedMs = state.startedAt !== undefined && state.endedAt !== undefined
+		? state.endedAt - state.startedAt
+		: undefined;
+	return selectDurationIndicator(config.durationIndicators, elapsedMs);
+}
+
+function parseHexColor(color: string): [number, number, number] {
+	return [
+		Number.parseInt(color.slice(1, 3), 16),
+		Number.parseInt(color.slice(3, 5), 16),
+		Number.parseInt(color.slice(5, 7), 16),
+	];
+}
+
+function styleDurationIcon(theme: Theme, indicator: DurationIndicatorConfig): string {
+	const color = indicator.color ?? "dim";
+	if (!HEX_COLOR_PATTERN.test(color)) {
+		return theme.fg(color as ThemeDurationIndicatorColor, indicator.icon);
+	}
+	const [red, green, blue] = parseHexColor(color);
+	const ansi = theme.getColorMode() === "truecolor"
+		? `\x1b[38;2;${red};${green};${blue}m`
+		: `\x1b[38;5;${rgbToAnsi256(red, green, blue)}m`;
+	return `${ansi}${indicator.icon}\x1b[39m`;
+}
+
+function renderControls(theme: Theme, state: RowState, running: boolean, isError: boolean): Text {
+	const duration = running && !animateRows ? undefined : formatDuration(state);
+	const levels = state.availableLevels ?? [0, 1];
+	const expandable = levels.length > 1;
+	const atLastLevel = state.level === levels.at(-1);
+	const action = expandable
+		? `${theme.italic("ctrl+o")} ${atLastLevel ? "to collapse" : "for more"}`
+		: undefined;
+	const indicator = !running && !isError ? durationIndicator(state) : undefined;
+	const status = running
+		? (duration ?? "Running")
+		: `${isError ? "Failed" : "Done"}${duration ? ` in ${duration}` : ""}`;
+	let details = indicator
+		? `${styleDurationIcon(theme, indicator)} ${theme.fg("borderAccent", status)}`
+		: theme.fg("borderAccent", status);
+	if (action) details += theme.fg("borderAccent", `, ${action}`);
+	return new Text(`${theme.fg("border", " └─ ")}${details}`, 0, 0);
+}
+
+function firstLine(value: string, maxLength = 100): string {
+	const line = normalizeLineEndings(value).split("\n")[0] ?? "";
+	return line.length > maxLength ? `${line.slice(0, maxLength - 1)}…` : line;
+}
+
+function getTextResult(result: AgentToolResult<unknown>): string {
+	const text = result.content
+		.filter((item) => item.type === "text")
+		.map((item) => item.text)
+		.join("\n");
+	return normalizeLineEndings(text).trimEnd();
+}
+
+function withoutLeadingBlankLines(component: Component, theme: Theme): Component {
+	return {
+		render(width: number) {
+			const lines = component.render(Math.max(1, width - 4));
+			const firstContentLine = lines.findIndex((line) => visibleWidth(line.trim()) > 0);
+			const prefix = theme.fg("border", " │  ");
+			return firstContentLine < 0 ? [] : lines.slice(firstContentLine).map((line) => `${prefix}${line}`);
+		},
+		invalidate() {
+			component.invalidate?.();
+		},
+	};
+}
+
+function styleToolOutput(text: string, theme: Theme, isError: boolean): string {
+	const color = isError ? "error" : "toolOutput";
+	return text
+		.split(/(⚡️?)/u)
+		.map((part) => theme.fg(!isError && part.startsWith("⚡") ? "warning" : color, part))
+		.join("");
+}
+
+function renderPreview(output: string, level: number, theme: Theme, isError: boolean): Text | undefined {
+	const normalized = normalizeLineEndings(output).trimEnd();
+	if (!normalized) return undefined;
+
+	const lines = normalized.split("\n");
+	const shown = level >= MAX_LEVEL ? lines : lines.slice(0, config.previewLines);
+	const prefix = theme.fg("border", " │  ");
+	let text = shown.map((line) => `${prefix}${styleToolOutput(line, theme, isError)}`).join("\n");
+	if (shown.length < lines.length) {
+		text += `\n${prefix}${theme.fg("dim", `… ${lines.length - shown.length} more lines`)}`;
+	}
+	return new Text(text, 0, 0);
+}
+
+function getPathArg(args: ToolArgs): string {
+	const value = args.path ?? args.file_path;
+	return typeof value === "string" ? firstLine(value) : "";
+}
+
+function getCallDetails(name: string, args: ToolArgs): string {
+	const path = getPathArg(args) || (name === "grep" || name === "find" || name === "ls" ? "." : "");
+	const pattern = typeof args.pattern === "string" ? firstLine(args.pattern) : "…";
+	if (name === "grep") return `/${pattern}/ in ${path}`;
+	if (name === "find") return `${pattern} in ${path}`;
+	return path;
+}
+
+function getFileArgumentDetails(name: string, args: ToolArgs): ToolArgs {
+	if (name === "edit") return {};
+	const omitted = new Set(["path", "file_path"]);
+	if (name === "write") omitted.add("content");
+	if (name === "grep" || name === "find") omitted.add("pattern");
+	return Object.fromEntries(Object.entries(args).filter(([key, value]) => !omitted.has(key) && value !== undefined));
+}
+
+function renderArguments(args: ToolArgs, theme: Theme): Text {
+	const json = JSON.stringify(args, null, 2) ?? "{}";
+	const prefix = theme.fg("border", " │  ");
+	const text = json
+		.split("\n")
+		.map((line) => `${prefix}${theme.fg("toolOutput", line)}`)
+		.join("\n");
+	return new Text(text, 0, 0);
+}
+
+function callOriginalEditResult(
+	definition: BuiltInDefinition,
+	result: AgentToolResult<unknown>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	ctx: RenderContext,
+	state: RowState,
+	level: number,
+): void {
+	if (definition.name !== "edit" || !definition.renderResult) return;
+	state.originalResultComponent = definition.renderResult(
+		result,
+		{ ...options, expanded: level >= MAX_LEVEL },
+		theme,
+		{ ...ctx, state: {}, lastComponent: state.originalResultComponent },
+	);
+}
+
+function getFileOutput(name: string, args: ToolArgs, result: AgentToolResult<unknown>, isError: boolean): string {
+	if (isError || name === "read" || name === "grep" || name === "find" || name === "ls") {
+		return getTextResult(result);
+	}
+	if (name === "write") return String(args.content ?? "");
+	return "";
+}
+
+function renderFileCall(
+	definition: BuiltInDefinition,
+	args: ToolArgs,
+	theme: Theme,
+	ctx: RenderContext,
+): Container {
+	// Animate and time from the first rendered call so large write/edit calls
+	// represent the full lifecycle, including streamed arguments and filesystem work.
+	const state = syncRow(ctx, ctx.state.endedAt === undefined);
+	// syncRow may restore a completed timing after /reload. Recompute from the
+	// synchronized state so a stale local value cannot leave the spinner visible.
+	const status = resolveCallStatus(ctx, state);
+	const level = advanceLevel(state, ctx.expanded);
+	const callDetails = getCallDetails(definition.name, args);
+	const argumentDetails = getFileArgumentDetails(definition.name, args);
+	let text = `${renderIndicator(theme, state, status)} `;
+	text += theme.fg("toolTitle", theme.bold(definition.name));
+	if (callDetails) text += ` ${theme.fg("toolOutput", callDetails)}`;
+
+	const container = new Container();
+	container.addChild(new Text(text, 1, 0));
+	if (level >= 1 && Object.keys(argumentDetails).length > 0) {
+		container.addChild(renderArguments(argumentDetails, theme));
+	}
+	return container;
+}
+
+function addFileResultPreview(
+	container: Container,
+	definition: BuiltInDefinition,
+	state: RowState,
+	output: string,
+	level: number,
+	theme: Theme,
+	isError: boolean,
+): void {
+	if (level < 2) return;
+	if (definition.name === "edit") {
+		if (state.originalResultComponent) {
+			container.addChild(withoutLeadingBlankLines(state.originalResultComponent, theme));
+		}
+		return;
+	}
+	const preview = renderPreview(output, level, theme, isError);
+	if (preview) container.addChild(preview);
+}
+
+function renderFileResult(
+	definition: BuiltInDefinition,
+	result: AgentToolResult<unknown>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	ctx: RenderContext,
+): Container {
+	const state = syncRow(ctx, options.isPartial, !options.isPartial);
+	const output = getFileOutput(definition.name, ctx.args, result, ctx.isError);
+	const hasArguments = Object.keys(getFileArgumentDetails(definition.name, ctx.args)).length > 0;
+	const levels = definition.name === "edit" ? [0, 2] : [0, ...(hasArguments ? [1] : []), ...getOutputLevels(output)];
+	setAvailableLevels(state, levels);
+
+	const level = state.level ?? 0;
+	callOriginalEditResult(definition, result, options, theme, ctx, state, level);
+	const container = new Container();
+	addFileResultPreview(container, definition, state, output, level, theme, ctx.isError);
+	container.addChild(renderControls(theme, state, options.isPartial, ctx.isError));
+	return container;
+}
+
+function createFileCallRenderer(definition: BuiltInDefinition) {
+	return (args: ToolArgs, theme: Theme, ctx: RenderContext) => renderFileCall(definition, args, theme, ctx);
+}
+
+function createFileResultRenderer(definition: BuiltInDefinition) {
+	return (result: AgentToolResult<unknown>, options: ToolRenderResultOptions, theme: Theme, ctx: RenderContext) =>
+		renderFileResult(definition, result, options, theme, ctx);
+}
+
+type TimedExecute = (...args: any[]) => Promise<AgentToolResult<unknown>>;
+
+function createTimedExecute(definition: BuiltInDefinition): TimedExecute {
+	const execute = definition.execute as TimedExecute;
+	return async (...args: any[]) => {
+		const toolCallId = typeof args[0] === "string" ? args[0] : undefined;
+		const startedAt = (toolCallId ? executionTimings.get(toolCallId)?.startedAt : undefined) ?? Date.now();
+		if (toolCallId && !executionTimings.has(toolCallId)) executionTimings.set(toolCallId, { startedAt });
+		try {
+			return await execute.apply(definition, args);
+		} finally {
+			const endedAt = Date.now();
+			const timing = toolCallId ? executionTimings.get(toolCallId) : undefined;
+			if (timing) timing.endedAt = endedAt;
+		}
+	};
+}
+
+function registerFileTool(pi: ExtensionAPI, definition: BuiltInDefinition): void {
+	const tool = {
+		...definition,
+		execute: createTimedExecute(definition),
+		renderShell: "self" as const,
+		renderCall: createFileCallRenderer(definition),
+		renderResult: createFileResultRenderer(definition),
+	};
+	// Built-in file schemas are intentionally erased at this shared renderer boundary.
+	pi.registerTool(tool as ToolDefinition<any, any, RowState>);
+}
+
+function renderShellCall(
+	name: "bash" | "powershell",
+	args: BashToolInput,
+	theme: Theme,
+	ctx: RenderContext<BashToolInput>,
+): Text {
+	const state = syncRow(ctx, ctx.state.endedAt === undefined);
+	// A completed timing can be restored inside syncRow. Derive the rendered
+	// status afterward so completion immediately replaces the spinner.
+	const status = resolveCallStatus(ctx, state);
+	const level = advanceLevel(state, ctx.expanded);
+	const command = normalizeLineEndings(args.command ?? "");
+	const displayedCommand = (level >= 1 ? command : firstLine(command)) || "…";
+	let text = `${renderIndicator(theme, state, status)} `;
+	text += `${theme.fg("toolTitle", theme.bold(name))} ${theme.fg("toolOutput", displayedCommand)}`;
+	return new Text(text, 1, 0);
+}
+
+function renderShellResult(
+	result: AgentToolResult<BashToolDetails | undefined>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	ctx: RenderContext<BashToolInput>,
+): Component {
+	const state = syncRow(ctx, options.isPartial, !options.isPartial);
+	const output = getTextResult(result);
+	const hasDetailedCall = /\r\n?|\n/.test(ctx.args.command ?? "");
+	setAvailableLevels(state, [0, ...(hasDetailedCall ? [1] : []), ...getOutputLevels(output)]);
+	const level = state.level ?? 0;
+	if (level < 2) return renderControls(theme, state, options.isPartial, ctx.isError);
+
+	const container = new Container();
+	const preview = renderPreview(output, level, theme, ctx.isError);
+	if (preview) container.addChild(preview);
+	else {
+		const prefix = theme.fg("border", " │  ");
+		const message = theme.fg("dim", options.isPartial ? "…" : "(no output)");
+		container.addChild(new Text(`${prefix}${message}`, 0, 0));
+	}
+	container.addChild(renderControls(theme, state, options.isPartial, ctx.isError));
+	return container;
+}
+
+function createBuiltInDefinition(name: CompactToolName, cwd: string): BuiltInDefinition {
+	switch (name) {
+		case "read": return createReadToolDefinition(cwd);
+		case "write": return createWriteToolDefinition(cwd);
+		case "edit": return createEditToolDefinition(cwd);
+		case "bash": return createBashToolDefinition(cwd);
+		case "powershell": return createPowerShellToolDefinition(cwd);
+		case "grep": return createGrepToolDefinition(cwd);
+		case "find": return createFindToolDefinition(cwd);
+		case "ls": return createLsToolDefinition(cwd);
+	}
+}
+
+function registerShellTool(pi: ExtensionAPI, definition: BuiltInDefinition): void {
+	pi.registerTool({
+		...definition,
+		execute: createTimedExecute(definition),
+		renderShell: "self",
+		renderCall: (args: BashToolInput, theme: Theme, ctx: RenderContext<BashToolInput>) =>
+			renderShellCall(definition.name as "bash" | "powershell", args, theme, ctx),
+		renderResult: renderShellResult,
+	} as ToolDefinition<any, BashToolDetails | undefined, RowState>);
+}
+
+function registerBuiltInTools(pi: ExtensionAPI, cwd: string): void {
+	for (const name of registeredCompactTools) {
+		if (!config.tools.includes(name)) pi.registerTool(createBuiltInDefinition(name, cwd));
+	}
+	registeredCompactTools.clear();
+	for (const name of config.tools) {
+		const definition = createBuiltInDefinition(name, cwd);
+		if (name === "bash" || name === "powershell") registerShellTool(pi, definition);
+		else registerFileTool(pi, definition);
+		registeredCompactTools.add(name);
+	}
+}
+
+function applyConfig(pi: ExtensionAPI, cwd: string, projectTrusted: boolean): void {
+	resetUiState();
+	animateRows = getConfiguredTuiMode() === "fullscreen";
+	config = loadConfig(cwd, projectTrusted);
+	registerBuiltInTools(pi, cwd);
+}
+
+export default function (pi: ExtensionAPI): void {
+	animateRows = getConfiguredTuiMode() === "fullscreen";
+	config = loadConfig();
+	registerBuiltInTools(pi, process.cwd());
+	pi.on("session_start", (event, ctx) => {
+		if (event.reason !== "reload") executionTimings.clear();
+		applyConfig(pi, ctx.cwd, ctx.isProjectTrusted());
+	});
+	pi.on("resources_discover", (_event, ctx) => applyConfig(pi, ctx.cwd, ctx.isProjectTrusted()));
+	pi.on("session_shutdown", (event) => resetUiState(event.reason !== "reload"));
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "pi-compact-tools",
+  "version": "0.3.1",
+  "description": "Compact, expandable UI for pi's built-in tools, bundled with a polished GitHub Dark theme.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Dong Hyeong Lee",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nedleeds/pi-compact-ui.git"
+  },
+  "homepage": "https://github.com/nedleeds/pi-compact-ui#readme",
+  "bugs": {
+    "url": "https://github.com/nedleeds/pi-compact-ui/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "pi-extension",
+    "terminal-ui",
+    "theme"
+  ],
+  "files": [
+    "extensions",
+    "themes",
+    "examples",
+    "scripts",
+    "schemas",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "check": "tsc --noEmit && npm test && npm run check:resources",
+    "check:resources": "node scripts/check-resources.mjs",
+    "prepublishOnly": "npm run check"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/compact-tools.ts"
+    ],
+    "themes": [
+      "./themes/github-dark-pro.json"
+    ],
+    "image": "https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/assets/built-in-tool-support.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/compact-tools.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/nedleeds/pi-compact-ui/main/schemas/compact-tools.schema.json",
+  "title": "pi-compact-tools configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "tools": {
+      "description": "Built-in tools that use compact rendering. Omitted tools keep Pi's default renderer.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["read", "write", "edit", "bash", "powershell", "grep", "find", "ls"]
+      },
+      "default": ["read", "write", "edit", "bash"]
+    },
+    "previewLines": {
+      "description": "Number of output lines shown before the full-output expansion level.",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1000,
+      "default": 10
+    },
+    "spinner": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "frames": {
+          "description": "Animation frames. Use terminal-safe single-width characters for consistent alignment.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "default": ["◐", "◓", "◑", "◒"]
+        },
+        "intervalMs": {
+          "description": "Milliseconds between spinner frames.",
+          "type": "integer",
+          "minimum": 40,
+          "maximum": 5000,
+          "default": 120
+        }
+      }
+    },
+    "durationIndicators": {
+      "description": "Ordered duration thresholds. The final item must omit underMs and acts as the fallback.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["icon"],
+        "properties": {
+          "underMs": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "icon": {
+            "type": "string",
+            "minLength": 1
+          },
+          "color": {
+            "description": "Optional semantic theme color or six-digit hex color used only for this duration icon.",
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "accent", "border", "borderAccent", "borderMuted", "success", "error", "warning",
+                  "muted", "dim", "text", "thinkingText", "toolTitle", "toolOutput", "toolDiffAdded",
+                  "toolDiffRemoved", "toolDiffContext", "bashMode"
+                ]
+              },
+              {
+                "type": "string",
+                "pattern": "^#[0-9A-Fa-f]{6}$"
+              }
+            ],
+            "default": "dim"
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/check-resources.mjs

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+
+const resources = [
+  "themes/github-dark-pro.json",
+  "examples/compact-tools.json",
+  "schemas/compact-tools.schema.json",
+];
+
+for (const path of resources) {
+  const value = JSON.parse(await readFile(new URL(`../${path}`, import.meta.url), "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${path} must contain a JSON object`);
+  }
+}
+
+const theme = JSON.parse(
+  await readFile(new URL("../themes/github-dark-pro.json", import.meta.url), "utf8"),
+);
+if (theme.name !== "github-dark-pro" || !theme.colors || typeof theme.colors !== "object") {
+  throw new Error("themes/github-dark-pro.json is not a valid pi theme document");
+}
+if (!theme.colors.border || !theme.colors.dim || !theme.colors.muted) {
+  throw new Error("github-dark-pro must define spinner and separator colors");
+}
+
+const example = JSON.parse(
+  await readFile(new URL("../examples/compact-tools.json", import.meta.url), "utf8"),
+);
+if (!Array.isArray(example.spinner?.frames) || example.spinner.frames.length === 0) {
+  throw new Error("example spinner.frames must be a non-empty array");
+}
+if (!Number.isInteger(example.spinner.intervalMs)) {
+  throw new Error("example spinner.intervalMs must be an integer");
+}
+const indicators = example.durationIndicators;
+if (!Array.isArray(indicators) || indicators.length === 0 || indicators.at(-1)?.underMs !== undefined) {
+  throw new Error("example durationIndicators must end with a fallback rule");
+}
+for (let index = 0; index < indicators.length - 1; index++) {
+  if (!(indicators[index].underMs > (indicators[index - 1]?.underMs ?? 0))) {
+    throw new Error("example durationIndicators thresholds must be ascending");
+  }
+}
+if (indicators.some((indicator) => indicator.color !== undefined && typeof indicator.color !== "string")) {
+  throw new Error("example duration indicator colors must be strings");
+}
+
+const schema = JSON.parse(
+  await readFile(new URL("../schemas/compact-tools.schema.json", import.meta.url), "utf8"),
+);
+if (!schema.properties?.durationIndicators?.items?.properties?.color) {
+  throw new Error("schema must describe durationIndicators.color");
+}
+
+console.log("Resource checks passed");

package/themes/github-dark-pro.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "github-dark-pro",
+  "vars": {
+    "surfaceMuted": "#21262D",
+    "border": "#30363D",
+    "borderSubtle": "#21262D",
+    "text": "#C9D1D9",
+    "textBright": "#E6EDF3",
+    "muted": "#8B949E",
+    "dim": "#6E7681",
+    "toolStatus": "#59616B",
+    "blue": "#58A6FF",
+    "blueSoft": "#79C0FF",
+    "green": "#3FB950",
+    "red": "#F85149",
+    "yellow": "#E0A052",
+    "orange": "#FFA657",
+    "purple": "#D2A8FF",
+    "toolAccent": "#95A7FF",
+    "toolName": "#8B85D6",
+    "toolText": "#98A1AC",
+    "pink": "#FF7B72"
+  },
+  "colors": {
+    "accent": "toolAccent",
+    "border": "border",
+    "borderAccent": "toolStatus",
+    "borderMuted": "borderSubtle",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "muted",
+    "dim": "dim",
+    "text": "text",
+    "thinkingText": "muted",
+
+    "selectedBg": "surfaceMuted",
+    "searchMatchBg": "#3B2E10",
+    "searchMatchText": "textBright",
+    "userMessageBg": "#16181C",
+    "userMessageText": "textBright",
+    "customMessageBg": "",
+    "customMessageText": "text",
+    "customMessageLabel": "muted",
+    "toolPendingBg": "",
+    "toolSuccessBg": "",
+    "toolErrorBg": "#211414",
+    "toolTitle": "toolName",
+    "toolOutput": "toolText",
+    "scrollbarTrack": "borderSubtle",
+    "scrollbarThumb": "border",
+
+    "mdHeading": "textBright",
+    "mdLink": "blue",
+    "mdLinkUrl": "dim",
+    "mdCode": "blueSoft",
+    "mdCodeBlock": "text",
+    "mdCodeBlockBorder": "#484F58",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "border",
+    "mdHr": "borderSubtle",
+    "mdListBullet": "muted",
+
+    "toolDiffAdded": "#45B85A",
+    "toolDiffRemoved": "#E45D57",
+    "toolDiffContext": "dim",
+
+    "syntaxComment": "dim",
+    "syntaxKeyword": "pink",
+    "syntaxFunction": "purple",
+    "syntaxVariable": "text",
+    "syntaxString": "blueSoft",
+    "syntaxNumber": "orange",
+    "syntaxType": "orange",
+    "syntaxOperator": "muted",
+    "syntaxPunctuation": "muted",
+
+    "thinkingOff": "borderSubtle",
+    "thinkingMinimal": "border",
+    "thinkingLow": "dim",
+    "thinkingMedium": "muted",
+    "thinkingHigh": "blue",
+    "thinkingXhigh": "blueSoft",
+    "thinkingMax": "blueSoft",
+    "bashMode": "green"
+  },
+  "export": {
+    "pageBg": "#0D1117",
+    "cardBg": "#161B22",
+    "infoBg": "#1C2128"
+  }
+}