@kr78/pi-coding-agent 17.2.10

package/src/utils/local-date.ts

@@ -0,0 +1,7 @@
+/** formatLocalCalendarDate formats a Date as YYYY-MM-DD in the host local timezone. */
+export function formatLocalCalendarDate(date: Date = new Date()): string {
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}

package/src/utils/mac-file-urls.applescript

@@ -0,0 +1,37 @@
+-- Returns the POSIX paths of every file URL currently on the macOS
+-- pasteboard, one path per line. `pbpaste(1)` only surfaces plain text,
+-- EPS, or RTF, so a Finder Cmd+C (which puts only a `public.file-url`
+-- representation on the pasteboard) makes `pbpaste` empty. The
+-- `«class furl»` coercion reaches the file-URL representation directly and
+-- works for both single-file and multi-file selections.
+--
+-- The coercion is guarded by `clipboard info for «class furl»`: AppleScript
+-- happily coerces plain *text* into a file URL by treating it as an HFS
+-- path, so an unguarded cast turns a copied `https://i.can.ac/x.png` string
+-- into the mangled `/https/::i.can.ac:x.png` (HFS `:`↔`/` swap) and the
+-- paste dead-ends with "Image not found" instead of falling back to pasting
+-- the text. `clipboard info for` inspects the actual pasteboard types, so
+-- it is `{}` unless a real `public.file-url` representation is present.
+--
+-- The `try` blocks suppress the `-1700` "can't make … into type" error
+-- AppleScript raises when the clipboard holds no file URLs, so the script's
+-- exit status only reflects `osascript` itself.
+on run
+	set output to ""
+	try
+		if (clipboard info for «class furl») is {} then return output
+		set theClip to the clipboard as «class furl»
+		if class of theClip is list then
+			repeat with anItem in theClip
+				try
+					set output to output & POSIX path of anItem & linefeed
+				end try
+			end repeat
+		else
+			try
+				set output to POSIX path of theClip & linefeed
+			end try
+		end if
+	end try
+	return output
+end run

package/src/utils/markit-cache.ts

@@ -0,0 +1,166 @@
+import type { Stats } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getDocumentConversionCacheDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import packageJson from "../../package.json" with { type: "json" };
+
+/**
+ * Cache schema/format revision. Bumping it changes the on-disk key prefix
+ * (`v<N>-...`), so old entries become unreachable and are pruned naturally.
+ * Bump when the cache *file* shape changes (entry JSON layout, key scheme).
+ *
+ * Converter *output* changes are handled separately: the package version is
+ * folded into the key (see {@link markitConversionCacheKey}), so any release
+ * that ships new markdown from `src/markit/converters/*` auto-invalidates the
+ * cache without a manual bump here.
+ */
+export const MARKIT_CONVERSION_CACHE_VERSION = 1;
+export const MAX_MARKIT_CONVERSION_CACHE_BYTES = 256 * 1024 * 1024;
+/** `.tmp` files older than this are treated as orphaned writes and swept. */
+const TMP_ORPHAN_MAX_AGE_MS = 5 * 60 * 1000;
+export type MarkitConversionCacheStatus = "hit" | "miss" | "skipped";
+
+export type MarkitConversionCacheReadResult = { status: "hit"; content: string } | { status: "miss" };
+
+interface MarkitConversionCacheEntry {
+	version: number;
+	content: string;
+}
+
+export function markitConversionCacheKey(bytes: Uint8Array, extension: string): string {
+	const normalizedExtension = extension.trim().toLowerCase().replace(/^\.+/, "") || "bin";
+	const safeExtension = normalizedExtension.replace(/[^a-z0-9]+/g, "_") || "bin";
+	const safeVersion = packageJson.version.replace(/[^a-z0-9]+/gi, "_");
+	const digest = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+	return `v${MARKIT_CONVERSION_CACHE_VERSION}-${safeVersion}-${safeExtension}-${digest}`;
+}
+
+function cacheEntryPath(key: string): string {
+	return path.join(getDocumentConversionCacheDir(), `${key}.json`);
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function parseCacheEntry(raw: string): MarkitConversionCacheEntry | null {
+	const parsed: unknown = JSON.parse(raw);
+	if (typeof parsed !== "object" || parsed === null) return null;
+	if (!("version" in parsed) || parsed.version !== MARKIT_CONVERSION_CACHE_VERSION) return null;
+	if (!("content" in parsed) || typeof parsed.content !== "string" || parsed.content.length === 0) return null;
+	return { version: MARKIT_CONVERSION_CACHE_VERSION, content: parsed.content };
+}
+
+export async function readMarkitConversionCache(key: string): Promise<MarkitConversionCacheReadResult> {
+	const target = cacheEntryPath(key);
+	let raw: string;
+	try {
+		raw = await Bun.file(target).text();
+	} catch (error) {
+		if (!isEnoent(error)) {
+			logger.debug("document conversion cache read failed", { error: errorMessage(error) });
+		}
+		return { status: "miss" };
+	}
+
+	let entry: MarkitConversionCacheEntry | null;
+	try {
+		entry = parseCacheEntry(raw);
+	} catch (error) {
+		logger.debug("document conversion cache read failed", { error: errorMessage(error) });
+		entry = null;
+	}
+
+	if (!entry) {
+		await fs.rm(target, { force: true }).catch(() => undefined);
+		return { status: "miss" };
+	}
+
+	return { status: "hit", content: entry.content };
+}
+
+export async function pruneMarkitConversionCache(cacheDir: string): Promise<void> {
+	let names: string[];
+	try {
+		names = await fs.readdir(cacheDir);
+	} catch (error) {
+		if (!isEnoent(error)) {
+			logger.debug("document conversion cache prune failed", { error: errorMessage(error) });
+		}
+		return;
+	}
+
+	const now = Date.now();
+	// Eviction is FIFO by mtime (not LRU): reads do not bump mtime, so a hot
+	// entry written long ago is evicted before a cold recent miss. The cap is a
+	// coarse disk-footprint safety valve, so the cheaper policy is intentional.
+	const entries: { path: string; size: number; mtimeMs: number }[] = [];
+	let totalBytes = 0;
+	for (const name of names) {
+		const entryPath = path.join(cacheDir, name);
+		let stat: Stats;
+		try {
+			stat = await fs.stat(entryPath);
+		} catch (error) {
+			if (!isEnoent(error)) {
+				logger.debug("document conversion cache prune failed", { error: errorMessage(error) });
+			}
+			continue;
+		}
+		if (!stat.isFile()) continue;
+
+		// Sweep orphaned `.tmp` files left by a crash/SIGKILL between writeFile
+		// and rename; they never become `.json` entries, so the size cap would
+		// otherwise never see them.
+		if (name.endsWith(".tmp")) {
+			if (now - stat.mtimeMs > TMP_ORPHAN_MAX_AGE_MS) {
+				await fs.rm(entryPath, { force: true }).catch(() => undefined);
+			}
+			continue;
+		}
+
+		if (!name.endsWith(".json")) continue;
+		entries.push({ path: entryPath, size: stat.size, mtimeMs: stat.mtimeMs });
+		totalBytes += stat.size;
+	}
+
+	if (totalBytes <= MAX_MARKIT_CONVERSION_CACHE_BYTES) return;
+
+	entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+	for (const entry of entries) {
+		if (totalBytes <= MAX_MARKIT_CONVERSION_CACHE_BYTES) break;
+		try {
+			await fs.rm(entry.path, { force: true });
+			totalBytes -= entry.size;
+		} catch (error) {
+			if (!isEnoent(error)) {
+				logger.debug("document conversion cache prune failed", { error: errorMessage(error) });
+			}
+		}
+	}
+}
+
+export async function writeMarkitConversionCache(key: string, content: string): Promise<void> {
+	const cacheDir = getDocumentConversionCacheDir();
+	const target = path.join(cacheDir, `${key}.json`);
+	// The random suffix keeps concurrent writers (same pid + same ms) from
+	// colliding on one temp path before the atomic rename.
+	const tempPath = path.join(cacheDir, `${key}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`);
+	const payload = JSON.stringify({ version: MARKIT_CONVERSION_CACHE_VERSION, content });
+	try {
+		await fs.mkdir(cacheDir, { recursive: true });
+		await Bun.write(tempPath, payload);
+		await fs.rename(tempPath, target);
+	} catch (error) {
+		await fs.rm(tempPath, { force: true }).catch(() => undefined);
+		logger.debug("document conversion cache write failed", { error: errorMessage(error) });
+		return;
+	}
+
+	// Prune is just GC: the entry is already on disk under its final name, so
+	// fire-and-forget rather than make the caller wait on a readdir + N×stat
+	// sweep on every miss (the slow path the cache exists to amortise).
+	void pruneMarkitConversionCache(cacheDir).catch(error => {
+		logger.debug("document conversion cache prune failed", { error: errorMessage(error) });
+	});
+}

package/src/utils/markit.ts

@@ -0,0 +1,223 @@
+import * as path from "node:path";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import type { ConversionResult, Markit, StreamInfo } from "../markit";
+import { ToolAbortError } from "../tools/tool-errors";
+import {
+	type MarkitConversionCacheStatus,
+	markitConversionCacheKey,
+	readMarkitConversionCache,
+	writeMarkitConversionCache,
+} from "./markit-cache";
+import { loadEmbeddedMupdfWasm } from "./mupdf-wasm-embed";
+
+/**
+ * File extensions markit can actually convert to markdown — one per registered
+ * converter in `src/markit/registry.ts` (pdf, docx, pptx, xlsx, epub). This is
+ * the single source of truth shared by the read, fetch, and CLI file tools so
+ * the advertised set never drifts from the converters that back it. Legacy
+ * binary formats (`.doc`, `.ppt`, `.xls`, `.rtf`) are intentionally absent:
+ * markit has no converter for them, so routing them here only produced an
+ * `Unsupported format` error instead of letting them fall through to the
+ * binary-file handling.
+ */
+export const CONVERTIBLE_EXTENSIONS: ReadonlySet<string> = new Set([".pdf", ".docx", ".pptx", ".xlsx", ".epub"]);
+
+export interface MarkitConversionResult {
+	content: string;
+	ok: boolean;
+	error?: string;
+	cache?: MarkitConversionCacheStatus;
+}
+
+export interface MarkitFileConversionOptions {
+	/**
+	 * Directory the PDF converter writes extracted images/diagrams into. When
+	 * set, each embedded image is rendered to `<id>.png` and referenced by path
+	 * in the markdown; when unset, markit emits an `<!-- image: <id> ... -->`
+	 * placeholder comment instead.
+	 */
+	imageDir?: string;
+}
+
+interface MuPdfWasmModuleConfig {
+	print?: (...values: unknown[]) => void;
+	printErr?: (...values: unknown[]) => void;
+	wasmBinary?: Uint8Array;
+}
+
+function logMuPdfWasmOutput(stream: "stdout" | "stderr", values: unknown[]): void {
+	const message = values.length === 1 && typeof values[0] === "string" ? values[0] : values.map(String).join(" ");
+	logger.debug("mupdf wasm output", { stream, message });
+}
+
+// `$libmupdf_wasm_Module` is declared globally (as `any`) by the mupdf package.
+// Install print hooks before the WASM module initializes so its stdout/stderr
+// route to the file logger instead of corrupting the TUI.
+function installMuPdfWasmLogger(): void {
+	const moduleConfig: MuPdfWasmModuleConfig = globalThis.$libmupdf_wasm_Module ?? {};
+	moduleConfig.print = (...values: unknown[]) => logMuPdfWasmOutput("stdout", values);
+	moduleConfig.printErr = (...values: unknown[]) => logMuPdfWasmOutput("stderr", values);
+	globalThis.$libmupdf_wasm_Module = moduleConfig;
+}
+
+// Hand the WASM module its bytes directly when the compiled binary embedded them
+// (scripts/embed-mupdf-wasm.ts); a single-file binary has no node_modules for
+// mupdf to read `mupdf-wasm.wasm` from. Source/npm builds get undefined here and
+// mupdf loads its own wasm. Must run before the mupdf module evaluates.
+function installEmbeddedMupdfWasm(): void {
+	const wasmBinary = loadEmbeddedMupdfWasm();
+	if (!wasmBinary) return;
+	const moduleConfig: MuPdfWasmModuleConfig = globalThis.$libmupdf_wasm_Module ?? {};
+	moduleConfig.wasmBinary = wasmBinary;
+	globalThis.$libmupdf_wasm_Module = moduleConfig;
+}
+
+installMuPdfWasmLogger();
+
+let markit: () => Markit | Promise<Markit> = async () => {
+	// Lazy: keep the document engine (mammoth/mupdf) off the startup
+	// import graph — it loads only when a document is first converted.
+	installEmbeddedMupdfWasm();
+	const promise = import("../markit").then(({ Markit }) => {
+		const instance = new Markit();
+		markit = () => instance;
+		return instance;
+	});
+	markit = () => promise;
+	return promise;
+};
+
+function normalizeExtension(extension: string): string {
+	const trimmed = extension.trim().toLowerCase();
+	if (!trimmed) return ".bin";
+	return trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+}
+
+function normalizeError(error: unknown): string {
+	if (error instanceof Error && error.message.trim().length > 0) {
+		return error.message.trim();
+	}
+	return "Conversion failed";
+}
+
+async function runMarkitConversion<T>(task: (markit: Markit) => Promise<T>, signal?: AbortSignal): Promise<T> {
+	try {
+		const instance = await markit();
+		return signal ? await untilAborted(signal, () => task(instance)) : await task(instance);
+	} catch (error) {
+		if (error instanceof ToolAbortError) {
+			throw error;
+		}
+		if (error instanceof Error && error.name === "AbortError") {
+			throw new ToolAbortError();
+		}
+		throw error;
+	}
+}
+
+function finalizeConversion(markdown?: string): MarkitConversionResult {
+	if (typeof markdown === "string" && markdown.length > 0) {
+		return { content: markdown, ok: true };
+	}
+
+	return { content: "", ok: false, error: "Conversion produced no output" };
+}
+
+function toBuffer(bytes: Uint8Array): Buffer {
+	return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) throw new ToolAbortError();
+}
+
+async function runCachedBufferConversion(
+	bytes: Uint8Array,
+	streamInfo: StreamInfo,
+	signal?: AbortSignal,
+	cacheEnabled = true,
+): Promise<MarkitConversionResult> {
+	const cacheKey = cacheEnabled
+		? markitConversionCacheKey(bytes, streamInfo.extension ?? streamInfo.mimetype ?? ".bin")
+		: undefined;
+
+	if (cacheKey) {
+		throwIfAborted(signal);
+		const cached = await readMarkitConversionCache(cacheKey);
+		throwIfAborted(signal);
+		if (cached.status === "hit") {
+			return { content: cached.content, ok: true, cache: "hit" };
+		}
+	}
+
+	throwIfAborted(signal);
+	let result: ConversionResult;
+	try {
+		result = await runMarkitConversion(markit => markit.convert(toBuffer(bytes), streamInfo), signal);
+	} catch (error) {
+		if (error instanceof ToolAbortError) {
+			throw error;
+		}
+		return { content: "", ok: false, error: normalizeError(error), cache: cacheEnabled ? "miss" : "skipped" };
+	}
+
+	const finalized = finalizeConversion(result.markdown);
+	if (finalized.ok && cacheKey) {
+		await writeMarkitConversionCache(cacheKey, finalized.content);
+	}
+	return { ...finalized, cache: cacheEnabled ? "miss" : "skipped" };
+}
+
+export async function convertFileWithMarkit(
+	filePath: string,
+	signal?: AbortSignal,
+	options?: MarkitFileConversionOptions,
+): Promise<MarkitConversionResult> {
+	if (options?.imageDir) {
+		// Image extraction writes files into imageDir as a side effect; a
+		// markdown-only cache hit would leave the directory missing members, so
+		// this path stays uncached.
+		try {
+			const result = await runMarkitConversion(
+				markit => markit.convertFile(filePath, { imageDir: options.imageDir }),
+				signal,
+			);
+			return { ...finalizeConversion(result.markdown), cache: "skipped" };
+		} catch (error) {
+			if (error instanceof ToolAbortError) {
+				throw error;
+			}
+			return { content: "", ok: false, error: normalizeError(error), cache: "skipped" };
+		}
+	}
+
+	throwIfAborted(signal);
+	let bytes: Uint8Array;
+	try {
+		bytes = await untilAborted(signal, () => Bun.file(filePath).bytes());
+	} catch (error) {
+		if (error instanceof ToolAbortError) throw error;
+		if (error instanceof Error && error.name === "AbortError") throw new ToolAbortError();
+		return { content: "", ok: false, error: normalizeError(error), cache: "miss" };
+	}
+	const streamInfo: StreamInfo = {
+		localPath: filePath,
+		extension: path.extname(filePath).toLowerCase(),
+		filename: path.basename(filePath),
+	};
+	return runCachedBufferConversion(bytes, streamInfo, signal, true);
+}
+
+export async function convertBufferWithMarkit(
+	buffer: Uint8Array,
+	extension: string,
+	signal?: AbortSignal,
+	options?: { useCache?: boolean },
+): Promise<MarkitConversionResult> {
+	const normalizedExtension = normalizeExtension(extension);
+	const streamInfo: StreamInfo = {
+		extension: normalizedExtension,
+		filename: `input${normalizedExtension}`,
+	};
+	return runCachedBufferConversion(buffer, streamInfo, signal, options?.useCache ?? true);
+}

package/src/utils/mupdf-wasm-embed.ts

@@ -0,0 +1,12 @@
+// AUTOGENERATED -- managed by scripts/embed-mupdf-wasm.ts. Do not edit by hand.
+//
+// Compiled single-file binaries cannot let mupdf resolve its `mupdf-wasm.wasm`
+// sibling from the read-only bunfs, so the binary build (scripts/build-binary.ts
+// and scripts/ci-release-build-binaries.ts) regenerates this module to embed the
+// wasm bytes via `with { type: "file" }` and copies the wasm next to it. Source
+// checkouts, `bun test`, and the npm `dist/cli.js` bundle keep mupdf external and
+// load the wasm from node_modules, so this placeholder returns undefined and the
+// build resets back to it afterward.
+export function loadEmbeddedMupdfWasm(): Uint8Array | undefined {
+	return undefined;
+}

package/src/utils/open.ts

@@ -0,0 +1,126 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as url from "node:url";
+import { $which, logger } from "@oh-my-pi/pi-utils";
+
+const URL_SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
+
+function getExistingWslLocalPath(urlOrPath: string): string | undefined {
+	if (
+		process.platform !== "linux" ||
+		!(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) ||
+		!$which("wslview")
+	) {
+		return undefined;
+	}
+
+	try {
+		const localPath = urlOrPath.startsWith("file://")
+			? url.fileURLToPath(urlOrPath)
+			: URL_SCHEME_PATTERN.test(urlOrPath)
+				? undefined
+				: path.resolve(urlOrPath);
+		if (!localPath || !fs.existsSync(localPath)) return undefined;
+
+		const result = Bun.spawnSync(["wslpath", "-w", localPath], { stdout: "pipe", stderr: "ignore" });
+		if (result.exitCode !== 0) return undefined;
+
+		return result.stdout.toString().trim() || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Resolve the Windows opener used to hand a URL/path to the user's registered
+ * protocol handler. PowerShell's `Start-Process` goes through ShellExecute
+ * like the previous `rundll32 url.dll,FileProtocolHandler`, with two
+ * advantages that make the delayed-failure telemetry in {@link openPath}
+ * actually observable on Windows:
+ *
+ * - `rundll32` exits 0 unconditionally, so no launch failure ever reaches the
+ *   non-zero-exit logging below. `Start-Process` surfaces the failures
+ *   ShellExecute itself reports — missing target file, no handler executable,
+ *   access denied — as exit code 1 (verified live: a nonexistent file path
+ *   exits 1; `$ErrorActionPreference='Stop'` additionally promotes any
+ *   non-terminating error classes). Known limitation shared by every opener:
+ *   an unregistered URL scheme exits 0 because Windows "handles" it by
+ *   offering the app-picker.
+ * - `-EncodedCommand` carries the target as a UTF-16LE/base64 payload, so no
+ *   cmd/PowerShell metacharacter parsing ever sees it (OAuth authorize URLs
+ *   carry `&`); inside the decoded script the target is a single-quoted
+ *   literal (no `$` expansion) with embedded quotes doubled.
+ *
+ * PowerShell is anchored to `%SystemRoot%\System32` for the same reason the
+ * previous revision anchored `rundll32`: machine PATHs that dropped
+ * `System32` are a real-world occurrence, and bare names throw
+ * `Executable not found in $PATH` from `Bun.spawn`. A bare-name fallback
+ * remains for exotic SystemRoot layouts.
+ */
+function windowsOpenerCommand(target: string): string[] {
+	const systemRoot = process.env.SystemRoot?.trim() || process.env.SYSTEMROOT?.trim() || "C:\\Windows";
+	// `path.win32` (not the platform-adaptive `path.join`) keeps Windows path
+	// separators when tests run under a POSIX host and matches Windows call
+	// conventions on the real target.
+	const absolute = path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+	const powershell = fs.existsSync(absolute) ? absolute : "powershell.exe";
+	const script = `$ErrorActionPreference='Stop';Start-Process '${target.replaceAll("'", "''")}'`;
+	return [
+		powershell,
+		"-NoProfile",
+		"-NonInteractive",
+		"-WindowStyle",
+		"Hidden",
+		"-EncodedCommand",
+		Buffer.from(script, "utf16le").toString("base64"),
+	];
+}
+/** Open a URL or file path in the default browser/application. Best-effort, never throws. */
+export function openPath(urlOrPath: string): void {
+	let cmd: string[];
+	switch (process.platform) {
+		case "darwin":
+			cmd = ["open", urlOrPath];
+			break;
+		case "win32":
+			cmd = windowsOpenerCommand(urlOrPath);
+			break;
+		default: {
+			const wslPath = getExistingWslLocalPath(urlOrPath);
+			cmd = wslPath ? ["wslview", wslPath] : ["xdg-open", urlOrPath];
+			break;
+		}
+	}
+	let child: Bun.Subprocess | undefined;
+	try {
+		child = Bun.spawn(cmd, { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+	} catch (error) {
+		// Spawn threw synchronously (missing binary, denied exec, sandbox
+		// restriction, …). Best-effort: log so the failure isn't invisible while
+		// still letting the caller advertise a copy-URL fallback.
+		logger.warn("Failed to open external URL/path", {
+			command: cmd[0],
+			target: urlOrPath,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return;
+	}
+	// Detect delayed failures (exec succeeded but the opener exited non-zero)
+	// without blocking the caller. Recording them makes silent misconfigurations
+	// (e.g. `xdg-open` present but no MIME handler for `https`) diagnosable from
+	// `~/.omp/logs/omp.*.log`.
+	child.exited.then(
+		exitCode => {
+			if (typeof exitCode === "number" && exitCode !== 0) {
+				logger.warn("External opener exited with non-zero status", {
+					command: cmd[0],
+					target: urlOrPath,
+					exitCode,
+				});
+			}
+		},
+		() => {
+			// Ignore — awaiting the subprocess is best-effort telemetry.
+		},
+	);
+}

package/src/utils/profile-tree.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared display-tree machinery for profile summaries (macOS `sample` reports,
+ * V8 `.cpuprofile` files). Callers build {@link ProfileNode} trees with a
+ * domain-specific metric (on-CPU samples, self microseconds, …); this module
+ * merges same-key siblings, flattens direct recursion, collapses pass-through
+ * chains, and renders the pruned hot-path tree.
+ */
+
+/** Display node: merged, recursion-flattened mirror of a profile subtree. */
+export interface ProfileNode {
+	/** Merge/recursion identity (demangled symbol, function@call-site, …). */
+	key: string;
+	/** Human-readable label; recursion and truncation decorations are applied at render time. */
+	label: string;
+	/** Inclusive metric for this subtree (on-CPU samples, self µs, …); drives pruning and display. */
+	value: number;
+	/** Levels of direct recursion flattened into this node. */
+	recursion: number;
+	children: ProfileNode[];
+}
+
+/** Labels longer than this are head-truncated (huge C++ templates, data URLs). */
+const MAX_LABEL_CHARS = 160;
+
+/** Merge `b` into `a` (same key), combining values and child lists. */
+export function mergeInto(a: ProfileNode, b: ProfileNode): void {
+	a.value += b.value;
+	a.recursion = Math.max(a.recursion, b.recursion);
+	for (const child of b.children) {
+		const existing = a.children.find(c => c.key === child.key);
+		if (existing) mergeInto(existing, child);
+		else a.children.push(child);
+	}
+}
+
+/**
+ * Flatten direct recursion: children carrying the node's own key are dissolved
+ * into it (their children promoted and merged), so a 15-deep recursive spine
+ * renders as one annotated node.
+ */
+export function flattenRecursion(node: ProfileNode): void {
+	while (node.children.some(child => child.key === node.key)) {
+		node.recursion++;
+		const next: ProfileNode[] = [];
+		for (const child of node.children) {
+			const promoted = child.key === node.key ? child.children : [child];
+			for (const item of promoted) {
+				const existing = next.find(c => c.key === item.key);
+				if (existing) mergeInto(existing, item);
+				else next.push(item);
+			}
+		}
+		node.children = next;
+	}
+}
+
+/** `n` as a percentage of `total`, one decimal (`"12.3%"`); `"0%"` when total is empty. */
+export function formatPct(n: number, total: number): string {
+	if (total <= 0) return "0%";
+	return `${((100 * n) / total).toFixed(1)}%`;
+}
+
+/** Options for {@link renderProfileNode}. */
+export interface RenderTreeContext {
+	out: string[];
+	/** Denominator for percentage annotations. */
+	total: number;
+	/** Minimum subtree value a child needs to stay visible. */
+	minValue: number;
+	/** Format a metric value for the left column. */
+	formatValue: (value: number) => string;
+	/** Left-column width (characters) for formatted values. */
+	valueWidth: number;
+}
+
+function decoratedLabel(node: ProfileNode): string {
+	let label = node.label.length > MAX_LABEL_CHARS ? `${node.label.slice(0, MAX_LABEL_CHARS - 1)}…` : node.label;
+	if (node.recursion > 0) label += ` [recursive ×${node.recursion + 1}]`;
+	return label;
+}
+
+/**
+ * Render one hot-path subtree: pass-through chains (single kept child, no own
+ * contribution above `minValue`) collapse into a single `a › b › c` line, and
+ * children below `minValue` are pruned.
+ */
+export function renderProfileNode(node: ProfileNode, indent: number, ctx: RenderTreeContext): void {
+	const chain: ProfileNode[] = [node];
+	let cur = node;
+	for (;;) {
+		flattenRecursion(cur);
+		if (cur.recursion > 0) break;
+		const kept = cur.children.filter(child => child.value >= ctx.minValue);
+		if (kept.length !== 1 || cur.value - kept[0].value >= ctx.minValue) break;
+		cur = kept[0];
+		chain.push(cur);
+	}
+	flattenRecursion(cur);
+
+	const labels = chain.map(decoratedLabel);
+	const path =
+		labels.length <= 4
+			? labels.join(" › ")
+			: `${labels[0]} › ⋯${labels.length - 2} frames⋯ › ${labels[labels.length - 1]}`;
+	const value = ctx.formatValue(chain[0].value).padStart(ctx.valueWidth);
+	const pct = formatPct(chain[0].value, ctx.total).padStart(6);
+	ctx.out.push(`${value} ${pct}  ${"  ".repeat(indent)}${path}`);
+
+	const kept = cur.children.filter(child => child.value >= ctx.minValue).sort((a, b) => b.value - a.value);
+	for (const child of kept) renderProfileNode(child, indent + 1, ctx);
+}

package/src/utils/prompt-path.ts

@@ -0,0 +1,3 @@
+export function normalizePromptPath(value: string): string {
+	return value.replace(/\\/g, "/");
+}