@oh-my-pi/pi-coding-agent 17.1.6 → 17.1.8

package/src/utils/cpuprofile.ts

@@ -0,0 +1,235 @@
+/**
+ * Parser and renderer for V8 `.cpuprofile` files (emitted by `node --cpu-prof`,
+ * `bun --cpu-prof`, Chrome DevTools, and the CDP `Profiler` domain).
+ *
+ * The raw file is a JSON blob with a flat node table and up to millions of
+ * sample/timestamp entries — useless to read directly. `renderCpuProfile`
+ * converts it into a compact bottleneck summary:
+ *
+ * - the hot-path call tree, pruned to frames with meaningful self time,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - `(idle)` time excluded from on-CPU totals
+ * - a profile-wide "top functions by self time" table
+ *
+ * Consumed by the read tool: `*.cpuprofile` reads show the summary, `:raw`
+ * returns the original JSON.
+ */
+
+import { formatPct, mergeInto, type ProfileNode, type RenderTreeContext, renderProfileNode } from "./profile-tree";
+
+/** Matches paths the read tool should treat as V8 CPU profiles. */
+export function isCpuProfilePath(filePath: string): boolean {
+	return /\.cpuprofile$/i.test(filePath);
+}
+
+/** Call-site metadata of one profile node. `lineNumber` is 0-based. */
+export interface CpuProfileCallFrame {
+	functionName: string;
+	url?: string;
+	lineNumber?: number;
+}
+
+/** One node in the flat profile tree; `children` are node ids. */
+export interface CpuProfileNode {
+	id: number;
+	callFrame: CpuProfileCallFrame;
+	hitCount?: number;
+	children?: number[];
+}
+
+/** Parsed V8 CPU profile. `startTime`/`endTime`/`timeDeltas` are microseconds. */
+export interface CpuProfile {
+	nodes: CpuProfileNode[];
+	startTime: number;
+	endTime: number;
+	samples?: number[];
+	timeDeltas?: number[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * Parse a `.cpuprofile` JSON blob. Accepts both the bare profile and the CDP
+ * `Profiler.stop` result shape (`{ profile: {...} }`). Returns null when the
+ * text is not a structurally valid V8 CPU profile.
+ */
+export function parseCpuProfile(text: string): CpuProfile | null {
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (isRecord(data) && !("nodes" in data) && isRecord(data.profile)) data = data.profile;
+	if (!isRecord(data)) return null;
+	const { nodes, startTime, endTime, samples, timeDeltas } = data;
+	if (!Array.isArray(nodes) || nodes.length === 0) return null;
+	if (typeof startTime !== "number" || typeof endTime !== "number") return null;
+	for (const node of nodes) {
+		if (!isRecord(node) || typeof node.id !== "number") return null;
+		if (!isRecord(node.callFrame) || typeof node.callFrame.functionName !== "string") return null;
+	}
+	return {
+		nodes: nodes as unknown as CpuProfileNode[],
+		startTime,
+		endTime,
+		samples: Array.isArray(samples) ? (samples as number[]) : undefined,
+		timeDeltas: Array.isArray(timeDeltas) ? (timeDeltas as number[]) : undefined,
+	};
+}
+
+/** Fraction of total on-CPU time a subtree needs to stay visible. */
+const PRUNE_FRACTION = 0.02;
+const TOP_FUNCTIONS = 20;
+
+/** Trim a call-frame URL for display: drop `file://`, keep the tail. */
+function shortUrl(url: string): string {
+	let u = url.startsWith("file://") ? url.slice("file://".length) : url;
+	const nm = u.lastIndexOf("node_modules/");
+	if (nm > 0) return u.slice(nm);
+	const parts = u.split("/");
+	if (parts.length > 4) u = `…/${parts.slice(-3).join("/")}`;
+	return u;
+}
+
+function frameLabel(frame: CpuProfileCallFrame): string {
+	const name = frame.functionName || "(anonymous)";
+	if (!frame.url) return name;
+	const line = typeof frame.lineNumber === "number" && frame.lineNumber >= 0 ? `:${frame.lineNumber + 1}` : "";
+	return `${name} (${shortUrl(frame.url)}${line})`;
+}
+
+/**
+ * Self time per node id in microseconds. Prefers the sample/delta streams
+ * (each delta is attributed to the sample that closes its interval); falls
+ * back to `hitCount × average interval` for profiles without samples.
+ */
+function selfMicros(profile: CpuProfile): Map<number, number> {
+	const self = new Map<number, number>();
+	const { samples, timeDeltas } = profile;
+	if (samples && timeDeltas && samples.length > 0) {
+		const n = Math.min(samples.length, timeDeltas.length);
+		for (let i = 0; i < n; i++) {
+			const delta = timeDeltas[i];
+			// V8 occasionally emits negative/zero deltas around timer adjustments.
+			if (typeof delta !== "number" || delta <= 0) continue;
+			const id = samples[i];
+			self.set(id, (self.get(id) ?? 0) + delta);
+		}
+		return self;
+	}
+	let totalHits = 0;
+	for (const node of profile.nodes) totalHits += node.hitCount ?? 0;
+	if (totalHits === 0) return self;
+	const interval = (profile.endTime - profile.startTime) / totalHits;
+	for (const node of profile.nodes) {
+		if (node.hitCount) self.set(node.id, node.hitCount * interval);
+	}
+	return self;
+}
+
+/** Meta-frames that represent time off the JS stack rather than user code. */
+const IDLE_FRAME = "(idle)";
+const ROOT_FRAME = "(root)";
+
+function formatMs(micros: number): string {
+	return (micros / 1000).toFixed(1);
+}
+
+/**
+ * Render a V8 CPU profile as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not a CPU profile (caller falls back to the
+ * plain-text path).
+ */
+export function renderCpuProfile(text: string): string | null {
+	const profile = parseCpuProfile(text);
+	if (!profile) return null;
+
+	const byId = new Map<number, CpuProfileNode>();
+	const referenced = new Set<number>();
+	for (const node of profile.nodes) {
+		byId.set(node.id, node);
+		for (const child of node.children ?? []) referenced.add(child);
+	}
+	const self = selfMicros(profile);
+
+	// Guard against malformed child cycles; V8 output is a proper tree.
+	const visited = new Set<number>();
+	const build = (node: CpuProfileNode): ProfileNode => {
+		visited.add(node.id);
+		const children: ProfileNode[] = [];
+		for (const childId of node.children ?? []) {
+			const rawChild = byId.get(childId);
+			if (!rawChild || visited.has(childId)) continue;
+			const child = build(rawChild);
+			const existing = children.find(c => c.key === child.key);
+			if (existing) mergeInto(existing, child);
+			else children.push(child);
+		}
+		const isIdle = node.callFrame.functionName === IDLE_FRAME;
+		let value = isIdle ? 0 : (self.get(node.id) ?? 0);
+		for (const child of children) value += child.value;
+		const label = frameLabel(node.callFrame);
+		return { key: label, label, value, recursion: 0, children };
+	};
+
+	// Promote past the synthetic "(root)" frame so hot paths start at real code.
+	const roots: ProfileNode[] = [];
+	for (const node of profile.nodes) {
+		if (referenced.has(node.id) || visited.has(node.id)) continue;
+		const built = build(node);
+		if (node.callFrame.functionName === ROOT_FRAME) roots.push(...built.children);
+		else roots.push(built);
+	}
+
+	const totalCpu = roots.reduce((sum, root) => sum + root.value, 0);
+	if (totalCpu <= 0) return null;
+	const duration = Math.max(0, profile.endTime - profile.startTime);
+	const sampleCount = profile.samples?.length ?? 0;
+	const avgInterval = sampleCount > 0 ? duration / sampleCount : 0;
+
+	const out: string[] = [];
+	let header = `V8 CPU profile: ${(duration / 1e6).toFixed(2)} s wall clock`;
+	if (sampleCount > 0) header += `, ${sampleCount} samples (avg interval ${Math.round(avgInterval)} µs)`;
+	out.push(header);
+	out.push(
+		`On-CPU total: ${(totalCpu / 1e6).toFixed(2)} s (${formatPct(totalCpu, duration)} of wall clock). Values below are on-CPU milliseconds (idle time excluded).`,
+	);
+
+	const ctx: RenderTreeContext = {
+		out,
+		total: totalCpu,
+		minValue: Math.max(3 * avgInterval, totalCpu * PRUNE_FRACTION),
+		formatValue: formatMs,
+		valueWidth: Math.max(8, formatMs(totalCpu).length),
+	};
+	out.push("");
+	out.push("## Hot paths");
+	const kept = roots.filter(root => root.value >= ctx.minValue).sort((a, b) => b.value - a.value);
+	for (const root of kept) renderProfileNode(root, 0, ctx);
+	if (kept.length === 0) out.push(`  (no call path above ${formatMs(ctx.minValue)} ms on-CPU)`);
+
+	const totals = new Map<string, number>();
+	for (const node of profile.nodes) {
+		const micros = self.get(node.id) ?? 0;
+		if (micros <= 0) continue;
+		const name = node.callFrame.functionName;
+		if (name === IDLE_FRAME || name === ROOT_FRAME) continue;
+		const label = frameLabel(node.callFrame);
+		totals.set(label, (totals.get(label) ?? 0) + micros);
+	}
+	const ranked = [...totals.entries()].sort((a, b) => b[1] - a[1]);
+	if (ranked.length > 0) {
+		out.push("");
+		out.push("## Top functions by self time (idle time excluded)");
+		for (const [label, micros] of ranked.slice(0, TOP_FUNCTIONS)) {
+			out.push(`${formatMs(micros).padStart(ctx.valueWidth)} ${formatPct(micros, totalCpu).padStart(6)}  ${label}`);
+		}
+	}
+
+	out.push("");
+	out.push("[Summarized view of a V8 .cpuprofile. Use ':raw' to read the original JSON.]");
+	return out.join("\n");
+}

package/src/utils/inspect-image-mode.ts

@@ -0,0 +1,39 @@
+/**
+ * Effective-state resolution for the `inspect_image` tool.
+ *
+ * The tool delegates image understanding to a (possibly different)
+ * vision-capable model. That indirection is only useful when the active model
+ * cannot consume images itself; when it can (`model.input` includes
+ * `"image"`), the tool is redundant and its presence actively degrades the
+ * `read` tool, which reduces image reads to metadata-only plus an
+ * inspect_image suggestion. `auto` mode therefore exposes the tool only for
+ * models without native image input. `on`/`off` force registration regardless
+ * of model capability. A session-scoped override (the `/vision` command)
+ * takes precedence over the persisted setting for the current session only.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { Settings } from "../config/settings";
+
+export type InspectImageMode = "auto" | "on" | "off";
+
+export const INSPECT_IMAGE_MODES = ["auto", "on", "off"] as const;
+
+/** Minimal session surface needed to resolve the effective inspect_image state. */
+export interface InspectImageModeContext {
+	settings: Pick<Settings, "get">;
+	getActiveModel?: () => Model | undefined;
+	getInspectImageModeOverride?: () => InspectImageMode | undefined;
+}
+
+/**
+ * Whether the `inspect_image` tool should be registered/active right now.
+ * `auto` registers it only when the active model lacks native image input;
+ * an unresolved model is treated as text-only so the tool stays available.
+ */
+export function isInspectImageToolActive(session: InspectImageModeContext): boolean {
+	const mode = session.getInspectImageModeOverride?.() ?? session.settings.get("inspect_image.mode");
+	if (mode === "on") return true;
+	if (mode === "off") return false;
+	const model = session.getActiveModel?.();
+	return !(model?.input?.includes("image") ?? false);
+}

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);
+}