pi-context-view 0.2.0

package/src/index.ts

@@ -0,0 +1,119 @@
+/**
+ * pi-context-view — inspect what occupies the model context.
+ *
+ * Passively captures the first real turn, or runs one on-demand silent probe
+ * when a context view is opened before any real turn.
+ */
+import { buildSessionContext, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+	getContextArgumentCompletions,
+	parseContextCommand,
+	reportCommandMessage,
+	resolveInitialCapture,
+} from "./command.ts";
+import {
+	buildNativeSnapshot,
+	InitialCaptureState,
+	mergeContextOnlyMessages,
+	SilentProbeState,
+} from "./capture.ts";
+import { showInjectionsView } from "./ui/injections-view.ts";
+import { showUsageView } from "./ui/usage-view.ts";
+import { computeUsage, toReportedUsage } from "./usage.ts";
+
+export default function (pi: ExtensionAPI) {
+	const capture = new InitialCaptureState();
+	const probe = new SilentProbeState();
+
+	pi.on("input", (event) => {
+		probe.observeInput(event.source, event.text);
+	});
+
+	pi.on("before_agent_start", (event) => {
+		probe.beginRun(event.prompt);
+		capture.prepare(event.systemPromptOptions);
+	});
+
+	pi.on("turn_start", (_event, ctx) => {
+		if (probe.isCurrentRun) ctx.abort();
+	});
+
+	pi.on("message_start", (event) => {
+		probe.recordMessage(event.message);
+	});
+
+	pi.on("message_end", (event) => {
+		const message = probe.sanitizeAssistant(event.message);
+		return message === undefined ? undefined : { message };
+	});
+
+	pi.on("context", (event, ctx) => {
+		const messages = probe.filterMessages(event.messages);
+		const baselineMessages = probe.filterMessages(
+			buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages,
+		);
+		capture.finalize({
+			systemPrompt: ctx.getSystemPrompt(),
+			messages,
+			baselineMessages,
+			allTools: pi.getAllTools(),
+			activeToolNames: pi.getActiveTools(),
+			origin: probe.isCurrentRun ? "synthetic-probe" : "real-turn",
+		});
+		return messages === event.messages ? undefined : { messages };
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (!probe.isCurrentRun) return;
+		if (ctx.mode === "tui") ctx.ui.setWorkingVisible(true);
+		probe.settle(capture.snapshot !== undefined);
+	});
+
+	pi.on("session_shutdown", () => {
+		probe.fail("Session ended before the silent probe completed.");
+	});
+
+	pi.registerCommand("context", {
+		// RegisteredCommand has no argumentHint; mimic pi's `<hint> — <description>` style.
+		description: "[usage|injections] — Inspect context usage or injections",
+		getArgumentCompletions: getContextArgumentCompletions,
+		handler: async (args, ctx) => {
+			const command = parseContextCommand(args);
+			if (command.type === "invalid") {
+				reportCommandMessage(ctx, command.message, "error");
+				return;
+			}
+			if (ctx.mode !== "tui") {
+				reportCommandMessage(ctx, "/context requires TUI mode.", "warning");
+				return;
+			}
+			const initial = await resolveInitialCapture(pi, capture, probe, ctx);
+			if (command.view === "injections") {
+				await showInjectionsView(ctx, {
+					snapshot: initial.snapshot,
+					degradedReason: initial.degradedReason,
+				});
+				return;
+			}
+			const current = buildNativeSnapshot({
+				systemPrompt: ctx.getSystemPrompt(),
+				options: ctx.getSystemPromptOptions(),
+				allTools: pi.getAllTools(),
+				activeToolNames: pi.getActiveTools(),
+			});
+			await showUsageView(ctx, {
+				usage: computeUsage({
+					snapshot: mergeContextOnlyMessages(current, initial.snapshot),
+					// ReadonlySessionManager lacks buildSessionContext(); use pi's exported builder.
+					messages: probe.filterMessages(
+						buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages,
+					),
+					reported: toReportedUsage(ctx.getContextUsage()),
+					modelLabel: ctx.model?.id,
+				}),
+				degradedReason: initial.degradedReason,
+			});
+		},
+	});
+}

package/src/measure.ts

@@ -0,0 +1,356 @@
+/**
+ * Pure measurement logic: split a captured system prompt into semantic items
+ * and estimate token sizes. No pi API access — unit-testable.
+ *
+ * Splitting relies on structural markers that pi's buildSystemPrompt() emits
+ * deterministically (verified against pi 0.80.6 dist/core/system-prompt.js):
+ *
+ * - context files: <project_instructions path="...">...</project_instructions>
+ * - skills block: "The following skills provide..." through </available_skills>
+ * - base prompt ends before the "Current date/Current working directory" footer
+ *   → anything after that footer was appended by before_agent_start handlers.
+ */
+import {
+	AGGREGATE_SOURCE_ID,
+	type InjectionItem,
+	type InjectionKind,
+	type InjectionSource,
+	PI_SOURCE_ID,
+} from "./model.ts";
+
+const PI_SOURCE: InjectionSource = { id: PI_SOURCE_ID, label: "pi", native: true };
+const AGGREGATE_SOURCE: InjectionSource = {
+	id: AGGREGATE_SOURCE_ID,
+	label: "extensions (aggregate)",
+	native: false,
+};
+
+/** One visible skill before pi adds XML transport framing. */
+export interface SkillSlice {
+	name: string;
+	description: string;
+	filePath: string;
+}
+
+/** Minimal slice of BuildSystemPromptOptions that measurement needs. */
+export interface PromptOptionsSlice {
+	cwd: string;
+	/** Home directory used to abbreviate context-file paths; omitted disables it. */
+	homeDir?: string;
+	customPrompt?: string;
+	appendSystemPrompt?: string;
+	contextFilePaths?: string[];
+	skills?: SkillSlice[];
+}
+
+/** One active tool as it contributes to the initial context. */
+export interface ToolSlice {
+	name: string;
+	/** Sent to the provider with every request. */
+	description: string;
+	/** JSON-serialized parameter schema; sent to the provider with every request. */
+	parametersJson: string;
+	/** One-line snippet rendered into the prompt's Available tools list. */
+	snippet?: string;
+	/** Guideline bullets rendered into the prompt's Guidelines section. */
+	guidelines: string[];
+	/** Provenance, e.g. "builtin" or "npm:pi-web-providers". */
+	source: string;
+}
+
+/**
+ * Split a captured system prompt into semantic items: pi base prompt,
+ * appended prompt, context files, skills, active tool contributions, and the
+ * aggregate appended by extensions.
+ */
+export function analyzeSystemPrompt(
+	systemPrompt: string,
+	options: PromptOptionsSlice,
+	tools: ToolSlice[] = [],
+): InjectionItem[] {
+	const items: InjectionItem[] = [];
+	const carvedSpans: Span[] = [];
+
+	const footer = findBasePromptFooter(systemPrompt, options.cwd);
+	const base = footer === undefined ? systemPrompt : systemPrompt.slice(0, footer.start);
+
+	const usesCustomPrompt = options.customPrompt !== undefined && options.customPrompt.length > 0;
+	measureTools(usesCustomPrompt ? "" : base, tools, items, carvedSpans);
+	measureContextFiles(base, options, items, carvedSpans);
+	measureSkills(base, options, items, carvedSpans);
+	measureAppendedPrompt(base, options, items, carvedSpans);
+
+	const baseLabel = usesCustomPrompt ? "Custom Prompt (--system-prompt)" : "Base Prompt";
+	items.unshift(createItem("base-prompt", "base-prompt", PI_SOURCE, baseLabel, carve(base, carvedSpans)));
+
+	if (footer !== undefined && footer.end < systemPrompt.length) {
+		const added = systemPrompt.slice(footer.end);
+		if (added.trim().length > 0) {
+			items.push(
+				createItem(
+					"prompt-addition:aggregate",
+					"prompt-addition",
+					AGGREGATE_SOURCE,
+					"system prompt additions",
+					added,
+				),
+			);
+		}
+	}
+
+	return items;
+}
+
+/** Same chars/4 heuristic pi's estimateTokens uses for text content. */
+export function textTokens(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+/**
+ * Measure active tool contributions: per-tool definition payloads plus the
+ * prompt snippet/guideline lines carved out of the base prompt. Built-in
+ * tools collapse into one aggregate pi-native item.
+ */
+function measureTools(base: string, tools: ToolSlice[], items: InjectionItem[], carvedSpans: Span[]): void {
+	const builtinChildren: InjectionItem[] = [];
+	for (const tool of tools) {
+		const definition = `${tool.name}: ${tool.description}\n${tool.parametersJson}`;
+		if (tool.source === "builtin") {
+			builtinChildren.push(createItem(`tool:builtin:${tool.name}`, "tool", PI_SOURCE, tool.name, definition));
+			continue;
+		}
+		let promptText = "";
+		if (tool.snippet !== undefined) {
+			const span = findExactSpan(base, `\n- ${tool.name}: ${tool.snippet}`);
+			if (span !== undefined) {
+				promptText += base.slice(span.start, span.end);
+				carvedSpans.push(span);
+			}
+		}
+		for (const guideline of tool.guidelines) {
+			const span = findExactSpan(base, `\n- ${guideline.trim()}`);
+			if (span !== undefined) {
+				promptText += base.slice(span.start, span.end);
+				carvedSpans.push(span);
+			}
+		}
+		const source = extensionSource(tool.source);
+		items.push(createItem(`tool:${tool.source}:${tool.name}`, "tool", source, tool.name, promptText + definition));
+	}
+	if (builtinChildren.length > 0) {
+		builtinChildren.sort((a, b) => b.tokens - a.tokens);
+		const label = `Built-in Tools (${builtinChildren.length})`;
+		const text = builtinChildren.map((child) => child.text).join("\n");
+		items.push({
+			...createItem("tool:builtin", "tool", PI_SOURCE, label, text),
+			chars: builtinChildren.reduce((sum, child) => sum + child.chars, 0),
+			tokens: builtinChildren.reduce((sum, child) => sum + child.tokens, 0),
+			children: builtinChildren,
+		});
+	}
+}
+
+/** Measure context-file contents without counting pi's XML transport scaffolding. */
+function measureContextFiles(
+	base: string,
+	options: PromptOptionsSlice,
+	items: InjectionItem[],
+	carvedSpans: Span[],
+): void {
+	const sectionSpan = findContextSectionSpan(base);
+	if (sectionSpan === undefined) return;
+	for (const filePath of options.contextFilePaths ?? []) {
+		const content = findContextFileContent(base, filePath);
+		if (content === undefined) continue;
+		items.push(
+			createItem(
+				`context-file:${filePath}`,
+				"context-file",
+				PI_SOURCE,
+				abbreviateHome(filePath, options.homeDir),
+				content,
+			),
+		);
+	}
+	carvedSpans.push(expandLineBreaks(base, sectionSpan));
+}
+
+/** Carve the skills section and expose each semantic skill record as a child item. */
+function measureSkills(
+	base: string,
+	options: PromptOptionsSlice,
+	items: InjectionItem[],
+	carvedSpans: Span[],
+): void {
+	const sectionSpan = findSkillsSpan(base);
+	if (sectionSpan === undefined) return;
+	const children = (options.skills ?? [])
+		.map((skill) => createItem(
+			`skill:${skill.name}`,
+			"skills",
+			PI_SOURCE,
+			skill.name,
+			[skill.name, skill.description, skill.filePath].join("\n"),
+		))
+		.sort((a, b) => b.tokens - a.tokens);
+	carvedSpans.push(expandLineBreaks(base, sectionSpan));
+	if (children.length === 0) return;
+
+	items.push(createAggregateItem("skills", "skills", PI_SOURCE, `Skills (${children.length})`, children));
+}
+
+/** Carve the --append-system-prompt text out of the base prompt when present. */
+function measureAppendedPrompt(
+	base: string,
+	options: PromptOptionsSlice,
+	items: InjectionItem[],
+	carvedSpans: Span[],
+): void {
+	const append = options.appendSystemPrompt;
+	if (append === undefined || append.length === 0) return;
+	const generatedStarts = [findContextSectionSpan(base)?.start, findSkillsSpan(base)?.start]
+		.filter((start): start is number => start !== undefined);
+	const generatedStart = generatedStarts.length === 0 ? base.length : Math.min(...generatedStarts);
+	const beforeGeneratedSections = Math.max(0, generatedStart - append.length);
+	const expectedStart = base.lastIndexOf(append, beforeGeneratedSections);
+	const start = expectedStart === -1 ? base.lastIndexOf(append) : expectedStart;
+	if (start === -1) return;
+	items.push(createItem("append-prompt", "append-prompt", PI_SOURCE, "appended system prompt", append));
+	carvedSpans.push({ start, end: start + append.length });
+}
+
+/** Build an initial-phase InjectionItem with derived char/token sizes. */
+function createItem(
+	id: string,
+	kind: InjectionKind,
+	source: InjectionSource,
+	label: string,
+	text: string,
+): InjectionItem {
+	return {
+		id,
+		phase: "initial",
+		kind,
+		source,
+		label,
+		chars: text.length,
+		tokens: textTokens(text),
+		text,
+	};
+}
+
+/** Build an aggregate whose totals exactly reconcile with its child items. */
+function createAggregateItem(
+	id: string,
+	kind: InjectionKind,
+	source: InjectionSource,
+	label: string,
+	children: InjectionItem[],
+): InjectionItem {
+	return {
+		...createItem(id, kind, source, label, children.map((child) => child.text).join("\n")),
+		chars: children.reduce((sum, child) => sum + child.chars, 0),
+		tokens: children.reduce((sum, child) => sum + child.tokens, 0),
+		children,
+	};
+}
+
+/** Injection source for a non-builtin tool provenance string. */
+function extensionSource(source: string): InjectionSource {
+	return { id: `tool-source:${source}`, label: source, native: false };
+}
+
+/** Replace a leading home-directory prefix with `~` for compact path labels. */
+function abbreviateHome(path: string, homeDir: string | undefined): string {
+	if (homeDir === undefined || homeDir.length === 0) return path;
+	if (path === homeDir) return "~";
+	if (path.startsWith(`${homeDir}/`)) return `~${path.slice(homeDir.length)}`;
+	return path;
+}
+
+/** Remove the given spans from text, tolerating overlaps, and return the remainder. */
+function carve(text: string, spans: Span[]): string {
+	spans.sort((a, b) => a.start - b.start);
+	let remainder = "";
+	let cursor = 0;
+	for (const span of spans) {
+		if (span.start > cursor) remainder += text.slice(cursor, span.start);
+		cursor = Math.max(cursor, span.end);
+	}
+	return remainder + text.slice(cursor);
+}
+
+/** Half-open [start, end) character range within the base prompt. */
+interface Span {
+	start: number;
+	end: number;
+}
+
+/** Locate pi's dynamic date/CWD footer so it can be excluded from Base Prompt and extension additions. */
+function findBasePromptFooter(systemPrompt: string, cwd: string): Span | undefined {
+	const promptCwd = cwd.replace(/\\/g, "/");
+	const cwdLine = `\nCurrent working directory: ${promptCwd}`;
+	let cwdStart = systemPrompt.lastIndexOf(cwdLine);
+	while (cwdStart !== -1) {
+		const dateStart = systemPrompt.lastIndexOf("\nCurrent date: ", cwdStart);
+		const dateLine = dateStart === -1 ? "" : systemPrompt.slice(dateStart, cwdStart);
+		if (/^\nCurrent date: \d{4}-\d{2}-\d{2}$/.test(dateLine)) {
+			return { start: dateStart, end: cwdStart + cwdLine.length };
+		}
+		cwdStart = systemPrompt.lastIndexOf(cwdLine, cwdStart - 1);
+	}
+	return undefined;
+}
+
+/** Span of the first exact occurrence of needle, or undefined. */
+function findExactSpan(haystack: string, needle: string): Span | undefined {
+	const start = haystack.indexOf(needle);
+	return start === -1 ? undefined : { start, end: start + needle.length };
+}
+
+/** Span of pi's complete project-context transport section. */
+function findContextSectionSpan(systemPrompt: string): Span | undefined {
+	return findDelimitedSpan(systemPrompt, "<project_context>", "</project_context>");
+}
+
+/** Extract one context file's final content without its project-instructions wrapper. */
+function findContextFileContent(systemPrompt: string, filePath: string): string | undefined {
+	const open = `<project_instructions path="${filePath}">`;
+	const close = "</project_instructions>";
+	const wrapper = findDelimitedSpan(systemPrompt, open, close);
+	if (wrapper === undefined) return undefined;
+	let start = wrapper.start + open.length;
+	let end = wrapper.end - close.length;
+	if (systemPrompt.startsWith("\r\n", start)) start += 2;
+	else if (systemPrompt[start] === "\n") start++;
+	if (systemPrompt.slice(Math.max(start, end - 2), end) === "\r\n") end -= 2;
+	else if (systemPrompt[end - 1] === "\n") end--;
+	return systemPrompt.slice(start, end);
+}
+
+/** Span of the skills intro sentence through </available_skills>. */
+function findSkillsSpan(systemPrompt: string): Span | undefined {
+	const open = "The following skills provide specialized instructions";
+	const close = "</available_skills>";
+	const start = systemPrompt.lastIndexOf(open);
+	if (start === -1) return undefined;
+	const end = systemPrompt.indexOf(close, start);
+	return end === -1 ? undefined : { start, end: end + close.length };
+}
+
+/** Locate a complete delimited transport wrapper. */
+function findDelimitedSpan(text: string, open: string, close: string): Span | undefined {
+	const start = text.indexOf(open);
+	if (start === -1) return undefined;
+	const closeStart = text.indexOf(close, start + open.length);
+	return closeStart === -1 ? undefined : { start, end: closeStart + close.length };
+}
+
+/** Include surrounding transport-only line breaks when carving a generated section. */
+function expandLineBreaks(text: string, span: Span): Span {
+	let start = span.start;
+	let end = span.end;
+	while (start > 0 && (text[start - 1] === "\n" || text[start - 1] === "\r")) start--;
+	while (end < text.length && (text[end] === "\n" || text[end] === "\r")) end++;
+	return { start, end };
+}

package/src/model.ts

@@ -0,0 +1,201 @@
+/**
+ * Semantic data model shared by capture, measurement, and UI. Pure types —
+ * no pi access. Hierarchy and provenance live in typed fields; UI code must
+ * never parse labels to recover source, kind, or parent/child relationships.
+ */
+
+export const PI_SOURCE_ID = "pi";
+export const AGGREGATE_SOURCE_ID = "aggregate:extensions";
+
+/** What produced the captured snapshot. */
+export type CaptureOrigin = "real-turn" | "synthetic-probe";
+
+/** The frozen lifecycle phase represented by the v0.2.0 injection model. */
+export type InjectionPhase = "initial";
+
+/** What kind of context data an injection item is. */
+export type InjectionKind =
+	| "base-prompt"
+	| "append-prompt"
+	| "context-file"
+	| "skills"
+	| "tool"
+	| "prompt-addition"
+	| "message";
+
+/** Who contributed one or more injection items. */
+export interface InjectionSource {
+	/** Stable internal id, namespaced by source kind. */
+	readonly id: string;
+	/** Human-readable group label. */
+	readonly label: string;
+	/** True for pi-native components. */
+	readonly native: boolean;
+}
+
+/** One measured context injection. */
+export interface InjectionItem {
+	/** Stable id, unique within a snapshot. */
+	readonly id: string;
+	readonly phase: InjectionPhase;
+	readonly kind: InjectionKind;
+	readonly source: InjectionSource;
+	/** Human-readable item label without embedded hierarchy or source. */
+	readonly label: string;
+	readonly chars: number;
+	/** Estimated tokens (chars/4 heuristic unless measured as a message). */
+	readonly tokens: number;
+	/** Raw injected text for preview. Process-local; never log or persist. */
+	readonly text: string;
+	/** True when a message exists only in the transformed provider context, not the session branch. */
+	readonly contextOnly?: boolean;
+	/** Constituent sub-items (e.g. individual built-in tools or skills), largest first. */
+	readonly children?: readonly InjectionItem[];
+}
+
+/** Items of one source, with a precomputed total. */
+export interface InjectionGroup {
+	readonly source: InjectionSource;
+	readonly items: readonly InjectionItem[];
+	readonly totalTokens: number;
+}
+
+/** The frozen Initial snapshot presented by the Injections view. */
+export interface InitialSnapshot {
+	readonly origin: CaptureOrigin;
+	readonly capturedAt: Date;
+	readonly groups: readonly InjectionGroup[];
+	readonly totalTokens: number;
+}
+
+/** One estimated usage category, optionally with a constituent breakdown. */
+export interface UsageCategory {
+	/** Stable id, unique within a usage snapshot level. */
+	readonly id: string;
+	readonly label: string;
+	/** Estimated tokens (chars/4 heuristic). */
+	readonly tokens: number;
+	/** Breakdown of the parent (e.g. per tool or per customType), not additional totals. */
+	readonly children?: readonly UsageCategory[];
+	/** Content entries backing the category preview; leaves only. */
+	readonly entries?: readonly UsagePreviewEntry[];
+}
+
+/** One content entry shown in a Usage category preview. */
+export interface UsagePreviewEntry {
+	/** Message time (epoch ms); absent for Initial-snapshot components. */
+	readonly timestamp?: number;
+	/** Bracket header cells, e.g. ["assistant", "read"] or ["code-style"]. */
+	readonly breadcrumb: readonly string[];
+	/** Estimated tokens for this entry alone. */
+	readonly tokens: number;
+	/** Raw content for preview. Process-local; never log or persist. */
+	readonly text: string;
+}
+
+/** Pi-reported usage; tokens/percent are omitted when unknown (e.g. right after compaction). */
+export interface ReportedContextUsage {
+	readonly tokens?: number;
+	readonly contextWindow: number;
+	readonly percent?: number;
+}
+
+/** On-demand estimated context composition presented by the Usage view. */
+export interface ContextUsageSnapshot {
+	readonly computedAt: Date;
+	readonly modelLabel?: string;
+	readonly reported?: ReportedContextUsage;
+	readonly categories: readonly UsageCategory[];
+	/** Sum of the top-level category estimates. */
+	readonly estimatedTokens: number;
+}
+
+/**
+ * Group measured items by source. Pi-native components come first, extension
+ * sources follow by total size, and the unattributable aggregate comes last.
+ * Items inside each group follow a fixed semantic order (base prompt, tools,
+ * skills, then everything else by size). Returned objects own all nested data;
+ * later mutation of the input cannot change the groups.
+ */
+export function groupInjections(items: readonly InjectionItem[]): InjectionGroup[] {
+	const groups = new Map<string, MutableGroup>();
+	for (const input of items) {
+		const item = copyItem(input);
+		let group = groups.get(item.source.id);
+		if (group === undefined) {
+			group = { source: item.source, items: [], totalTokens: 0 };
+			groups.set(item.source.id, group);
+		}
+		group.items.push(item);
+		group.totalTokens += item.tokens;
+	}
+	for (const group of groups.values()) {
+		group.items.sort(compareItems);
+	}
+	return [...groups.values()].sort(compareGroups);
+}
+
+/** Build an owned Initial snapshot from measured items. */
+export function buildSnapshot(
+	items: readonly InjectionItem[],
+	origin: CaptureOrigin,
+	capturedAt: Date,
+): InitialSnapshot {
+	const groups = groupInjections(items);
+	return {
+		origin,
+		capturedAt: new Date(capturedAt),
+		groups,
+		totalTokens: groups.reduce((sum, group) => sum + group.totalTokens, 0),
+	};
+}
+
+/** Internal accumulator for groupInjections before freezing into InjectionGroup. */
+interface MutableGroup {
+	source: InjectionSource;
+	items: InjectionItem[];
+	totalTokens: number;
+}
+
+/** Owned copy of an item, including its nested source and children. */
+function copyItem(item: InjectionItem): InjectionItem {
+	return {
+		...item,
+		source: { ...item.source },
+		children: item.children?.map((child) => copyItem(child)),
+	};
+}
+
+/**
+ * Order items within a group: base/appended prompt first, then built-in tools,
+ * other tools, skills, and finally everything else by size descending.
+ */
+function compareItems(a: InjectionItem, b: InjectionItem): number {
+	const rankDelta = itemRank(a) - itemRank(b);
+	if (rankDelta !== 0) return rankDelta;
+	return b.tokens - a.tokens;
+}
+
+/** Fixed display rank by kind; built-in tools precede other tools. */
+function itemRank(item: InjectionItem): number {
+	switch (item.kind) {
+		case "base-prompt":
+		case "append-prompt":
+			return 0;
+		case "tool":
+			return item.id === "tool:builtin" ? 1 : 2;
+		case "skills":
+			return 3;
+		default:
+			return 4;
+	}
+}
+
+/** Order groups: pi-native first, then extensions by size, aggregate last. */
+function compareGroups(a: InjectionGroup, b: InjectionGroup): number {
+	if (a.source.native !== b.source.native) return a.source.native ? -1 : 1;
+	const aAggregate = a.source.id === AGGREGATE_SOURCE_ID;
+	const bAggregate = b.source.id === AGGREGATE_SOURCE_ID;
+	if (aAggregate !== bAggregate) return aAggregate ? 1 : -1;
+	return b.totalTokens - a.totalTokens;
+}