@xprnvd/pi-context-view 0.0.0-stage → 0.7.2

package/src/compaction.ts

@@ -0,0 +1,57 @@
+/**
+ * Compaction lifecycle tracking for the silent-probe preconditions and the
+ * `/context` refusal: a probe must not start while an observed compaction can
+ * still reject prompts, and no view opens on a projection about to be replaced.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Tracks the observable compaction lifecycle that makes a silent probe unsafe. */
+export class CompactionState {
+	private currentSignal: AbortSignal | undefined;
+
+	/** Whether a compaction observed through `session_before_compact` is still active. */
+	public get isActive(): boolean {
+		return this.currentSignal !== undefined && !this.currentSignal.aborted;
+	}
+
+	/** Track the current compaction until Pi reports its end or its signal aborts. */
+	public begin(signal: AbortSignal): void {
+		if (signal.aborted) {
+			this.currentSignal = undefined;
+			return;
+		}
+		this.currentSignal = signal;
+		signal.addEventListener("abort", () => {
+			if (this.currentSignal === signal) this.currentSignal = undefined;
+		}, { once: true });
+	}
+
+	/** Clear the current lifecycle after compaction can no longer reject prompts. */
+	public finish(): void {
+		this.currentSignal = undefined;
+	}
+}
+
+/** Follow compaction through Pi's session events; a new or ending session clears it. */
+export function registerCompactionTracking(pi: ExtensionAPI, compaction: CompactionState): void {
+	pi.on("session_start", () => {
+		compaction.finish();
+	});
+
+	pi.on("session_before_compact", (event) => {
+		compaction.begin(event.signal);
+	});
+
+	// Pi ends every observed compaction with exactly one of these two events.
+	pi.on("session_compact", () => {
+		compaction.finish();
+	});
+
+	pi.on("session_compact_failed", () => {
+		compaction.finish();
+	});
+
+	pi.on("session_shutdown", () => {
+		compaction.finish();
+	});
+}

package/src/config.ts

@@ -0,0 +1,408 @@
+/**
+ * Override-only user configuration.
+ *
+ * Defaults live in this module; the global
+ * `<agent dir>/extensions/pi-context-view.json` carries overrides only. The
+ * file is never auto-created and never backfilled with missing defaults, so
+ * later default changes still reach users who did not override them. An
+ * absent file or omitted value is silent; unreadable, unparseable, and invalid
+ * configuration warns and degrades to defaults instead of failing a view.
+ */
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getAgentDir, type ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** Global override file; project-local configuration is intentionally unsupported. */
+export const CONFIG_FILE_NAME = "pi-context-view.json";
+
+/** Category id of the legend and map rows tracking the auto-compaction reserve. */
+export const AUTO_COMPACT_BUFFER_CATEGORY_ID = "auto-compact-buffer";
+/** Category id of the legend and map rows tracking unoccupied context. */
+export const FREE_SPACE_CATEGORY_ID = "free-space";
+
+/** Color of a usage category without its own configurable entry, such as a tool-output child. */
+const FALLBACK_CATEGORY_COLOR: ThemeColor = "muted";
+
+/** Literal color values, accepted as `#rgb` or `#rrggbb` in either case. */
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/** Pi foreground theme color keys a configured category may name. */
+export const THEME_COLOR_NAMES = [
+	"accent", "border", "borderAccent", "borderMuted", "success",
+	"error", "warning", "muted", "dim", "text", "thinkingText",
+	"scrollbarTrack", "scrollbarThumb",
+	"searchMatchText", "userMessageText", "customMessageText",
+	"customMessageLabel", "toolTitle", "toolOutput", "mdHeading",
+	"mdLink", "mdLinkUrl", "mdCode", "mdCodeBlock", "mdCodeBlockBorder",
+	"mdQuote", "mdQuoteBorder", "mdHr", "mdListBullet", "toolDiffAdded",
+	"toolDiffRemoved", "toolDiffContext", "syntaxComment", "syntaxKeyword",
+	"syntaxFunction", "syntaxVariable", "syntaxString", "syntaxNumber",
+	"syntaxType", "syntaxOperator", "syntaxPunctuation", "thinkingOff",
+	"thinkingMinimal", "thinkingLow", "thinkingMedium", "thinkingHigh",
+	"thinkingXhigh", "thinkingMax", "bashMode",
+] as const satisfies readonly ThemeColor[];
+
+/** Resolves to its argument only for `never`, turning a non-empty type into a compile error. */
+type AssertNever<T extends never> = T;
+
+/**
+ * Compile-time proof that the list above stays complete. `satisfies` alone
+ * rejects only removed or renamed keys; this fails the build when pi adds a
+ * theme color, which would otherwise be silently rejected as unconfigurable.
+ */
+type _EveryThemeColorIsListed = AssertNever<Exclude<ThemeColor, (typeof THEME_COLOR_NAMES)[number]>>;
+
+/**
+ * Every configurable usage color: the category id the view resolves, the flat
+ * config key overriding it, and the built-in default. Listed in legend order,
+ * which a created override file reproduces.
+ */
+const CATEGORY_COLOR_SPECS = {
+	"system-prompt": { key: "systemPromptColor", color: "mdHeading" },
+	"context-files": { key: "instructionFilesColor", color: "mdCodeBlock" },
+	"skills": { key: "skillsColor", color: "customMessageLabel" },
+	"built-in-tools": { key: "builtInToolsColor", color: "mdHeading" },
+	"custom-tools": { key: "customToolsColor", color: "accent" },
+	"mcp-tools": { key: "mcpToolsColor", color: "mdLink" },
+	"user-messages": { key: "userMessagesColor", color: "syntaxString" },
+	"assistant-messages": { key: "assistantMessagesColor", color: "syntaxFunction" },
+	"assistant-thinking": { key: "assistantThinkingColor", color: "thinkingXhigh" },
+	"tool-calls": { key: "toolCallsColor", color: "syntaxKeyword" },
+	"tool-output": { key: "toolOutputColor", color: "toolOutput" },
+	"extensions": { key: "extensionsColor", color: "syntaxType" },
+	"compacted-data": { key: "compactedDataColor", color: "thinkingHigh" },
+	[AUTO_COMPACT_BUFFER_CATEGORY_ID]: { key: "autoCompactBufferColor", color: "dim" },
+	[FREE_SPACE_CATEGORY_ID]: { key: "freeSpaceColor", color: "dim" },
+} as const satisfies Record<string, { readonly key: string; readonly color: ThemeColor }>;
+
+/** Flat config key of one configurable category color. */
+type ConfigKey = (typeof CATEGORY_COLOR_SPECS)[keyof typeof CATEGORY_COLOR_SPECS]["key"];
+
+/** Config keys mapped to the category they color. */
+const CONFIG_KEY_CATEGORIES: ReadonlyMap<string, string> = new Map(
+	Object.entries(CATEGORY_COLOR_SPECS).map(([categoryId, spec]) => [spec.key, categoryId]),
+);
+
+/** Cell counts a configured map dimension may request; the viewport clamps further at render time. */
+const MINIMUM_MAP_CELLS = 4;
+const MAXIMUM_MAP_CELLS = 64;
+
+/**
+ * Both configurable map dimensions: the geometry field, the flat config key
+ * overriding it, and the built-in default a created override file reproduces.
+ */
+const MAP_SIZE_SPECS = {
+	columns: { key: "mapCols", cells: 16 },
+	rows: { key: "mapRows", cells: 16 },
+} as const satisfies Record<string, { readonly key: string; readonly cells: number }>;
+
+/** Geometry field of one configurable map dimension. */
+type MapSizeField = keyof typeof MAP_SIZE_SPECS;
+
+/** Config keys mapped to the map dimension they size. */
+const CONFIG_KEY_MAP_FIELDS: ReadonlyMap<string, MapSizeField> = new Map(
+	Object.entries(MAP_SIZE_SPECS).map(([field, spec]) => [spec.key, field as MapSizeField]),
+);
+
+/** Config key of the switch that lets a view start the silent probe on its own. */
+const AUTO_PROBING_KEY = "autoProbing";
+
+/** Built-in probing switch: enabled, so a view opened before any request can still capture one. */
+const DEFAULT_AUTO_PROBING = true;
+
+/**
+ * Renamed keys still honored, mapped to their current name, so a rename never
+ * silently drops an override an existing file already carries. The value type
+ * fails the build when a rename points at a key no category declares.
+ */
+const RENAMED_CONFIG_KEYS: ReadonlyMap<string, ConfigKey> = new Map([
+	["memoryColor", "instructionFilesColor"],
+	["systemToolsColor", "builtInToolsColor"],
+	["agentTextMessagesColor", "assistantMessagesColor"],
+	["agentThinkingMessagesColor", "assistantThinkingColor"],
+	["agentToolCallMessagesColor", "toolCallsColor"],
+	["extensionMessagesColor", "extensionsColor"],
+]);
+
+/** Fast runtime membership check for configured Pi foreground color names. */
+const THEME_COLORS: ReadonlySet<string> = new Set(THEME_COLOR_NAMES);
+
+/** Theme-independent color, always stored expanded to a lowercase `#rrggbb`. */
+export type HexColor = `#${string}`;
+
+/**
+ * One configured color: a pi theme color key, which follows theme changes, or
+ * a literal hex value, which stays fixed across themes.
+ */
+export type CategoryColor = ThemeColor | HexColor;
+
+/** Resolved color of each configurable usage category, keyed by category id. */
+export type CategoryColors = ReadonlyMap<string, CategoryColor>;
+
+/** Requested context-map geometry in cells, before the viewport clamps it. */
+export interface MapSize {
+	readonly columns: number;
+	readonly rows: number;
+}
+
+/** All user-configurable state of one runtime. */
+export interface ContextViewConfig {
+	readonly categoryColors: CategoryColors;
+	readonly mapSize: MapSize;
+	/** Whether a view opened before any captured request may start the silent probe. */
+	readonly autoProbing: boolean;
+}
+
+/** Configuration for one view open, with the problems that degraded it to defaults. */
+export interface ConfigLoadResult {
+	readonly config: ContextViewConfig;
+	/** Empty when the file is absent or fully valid; reported once per file revision. */
+	readonly warnings: readonly string[];
+}
+
+/** Outcome of explicitly creating the defaults-populated override file. */
+export type ConfigCreationResult =
+	| { readonly type: "created"; readonly filePath: string }
+	| { readonly type: "exists"; readonly filePath: string }
+	| { readonly type: "failed"; readonly filePath: string; readonly reason: string };
+
+/** Built-in colors, used whenever the file omits or misconfigures a category. */
+export const DEFAULT_CATEGORY_COLORS: CategoryColors = new Map(
+	Object.entries(CATEGORY_COLOR_SPECS).map(([categoryId, spec]) => [categoryId, spec.color] as const),
+);
+
+/** Built-in map geometry, used whenever the file omits or misconfigures a dimension. */
+export const DEFAULT_MAP_SIZE: MapSize = {
+	columns: MAP_SIZE_SPECS.columns.cells,
+	rows: MAP_SIZE_SPECS.rows.cells,
+};
+
+/** Configuration used when no override file exists. */
+export const DEFAULT_CONFIG: ContextViewConfig = {
+	categoryColors: DEFAULT_CATEGORY_COLORS,
+	mapSize: DEFAULT_MAP_SIZE,
+	autoProbing: DEFAULT_AUTO_PROBING,
+};
+
+/** Absolute path of the global override file. */
+export function getConfigFilePath(): string {
+	return join(getAgentDir(), "extensions", CONFIG_FILE_NAME);
+}
+
+/**
+ * Create the global override file populated with every built-in default. The
+ * single `O_EXCL` write is atomic and never overwrites or modifies an existing
+ * path, so a concurrent creator loses the race instead of the file's content.
+ */
+export function createDefaultConfigFile(filePath: string = getConfigFilePath()): ConfigCreationResult {
+	try {
+		// Separate from the write below: mkdir also reports EEXIST, for a parent that is a file.
+		mkdirSync(dirname(filePath), { recursive: true });
+	} catch (error) {
+		return { type: "failed", filePath, reason: describeError(error) };
+	}
+	try {
+		writeFileSync(filePath, serializeDefaultConfig(), { encoding: "utf8", flag: "wx" });
+		return { type: "created", filePath };
+	} catch (error) {
+		if (hasErrorCode(error, "EEXIST")) return { type: "exists", filePath };
+		return { type: "failed", filePath, reason: describeError(error) };
+	}
+}
+
+/**
+ * Per-runtime configuration cache.
+ *
+ * The file is read lazily on the first view open, then re-read only after its
+ * modification time changes, so edits apply without restarting pi.
+ */
+export class ConfigStore {
+	private readonly filePath: string;
+	private cached: ContextViewConfig = DEFAULT_CONFIG;
+	private cachedModifiedTime: number | undefined;
+	private pendingWarnings: readonly string[] = [];
+	private loaded = false;
+
+	/** Create a store over the global override file, or an explicit path in tests. */
+	public constructor(filePath: string = getConfigFilePath()) {
+		this.filePath = filePath;
+	}
+
+	/**
+	 * Configuration for one view open. Warnings are returned once per file
+	 * revision, so reopening a view never repeats a report for an unchanged file.
+	 */
+	public load(): ConfigLoadResult {
+		const modifiedTime = readModifiedTime(this.filePath);
+		if (!this.loaded || modifiedTime !== this.cachedModifiedTime) {
+			const result = loadConfigFile(this.filePath);
+			this.cached = result.config;
+			this.pendingWarnings = result.warnings;
+			this.cachedModifiedTime = modifiedTime;
+			this.loaded = true;
+		}
+		const warnings = this.pendingWarnings;
+		this.pendingWarnings = [];
+		return { config: this.cached, warnings };
+	}
+}
+
+/** Read and validate one override file; a missing file yields defaults without warnings. */
+export function loadConfigFile(filePath: string): ConfigLoadResult {
+	let text: string;
+	try {
+		text = readFileSync(filePath, "utf8");
+	} catch (error) {
+		// An absent file is the expected state for users who never configured anything.
+		if (hasErrorCode(error, "ENOENT")) return { config: DEFAULT_CONFIG, warnings: [] };
+		return degraded(`Cannot read ${filePath}: ${describeError(error)}.`);
+	}
+	try {
+		return applyOverrides(JSON.parse(text));
+	} catch (error) {
+		return degraded(`Cannot parse ${filePath}: ${describeError(error)}.`);
+	}
+}
+
+/** Color of one usage category, falling back for categories without a configurable entry. */
+export function resolveCategoryColor(colors: CategoryColors, categoryId: string | undefined): CategoryColor {
+	if (categoryId === undefined) return FALLBACK_CATEGORY_COLOR;
+	return colors.get(categoryId) ?? FALLBACK_CATEGORY_COLOR;
+}
+
+/** Whether a resolved color is a literal value rather than a theme color key. */
+export function isHexColor(color: CategoryColor): color is HexColor {
+	return color.startsWith("#");
+}
+
+/** Serialize every built-in default as an editable, flat override file. */
+function serializeDefaultConfig(): string {
+	const groups: Array<ReadonlyArray<readonly [string, CategoryColor | number | boolean]>> = [
+		Object.values(CATEGORY_COLOR_SPECS).map((spec) => [spec.key, spec.color]),
+		Object.values(MAP_SIZE_SPECS).map((spec) => [spec.key, spec.cells]),
+		[[AUTO_PROBING_KEY, DEFAULT_AUTO_PROBING]],
+	];
+	// Written by hand: JSON.stringify cannot leave the blank lines that separate the groups
+	const body = groups
+		.map((entries) => entries.map(([key, value]) => `  ${JSON.stringify(key)}: ${JSON.stringify(value)}`).join(",\n"))
+		.join(",\n\n");
+	return `{\n${body}\n}\n`;
+}
+
+/** Merge valid overrides onto the built-in defaults, reporting every ignored entry. */
+function applyOverrides(raw: unknown): ConfigLoadResult {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return degraded(`${CONFIG_FILE_NAME} must contain a JSON object.`);
+	}
+	const config: ConfigDraft = {
+		categoryColors: new Map(DEFAULT_CATEGORY_COLORS),
+		mapSize: { ...DEFAULT_MAP_SIZE },
+		autoProbing: DEFAULT_AUTO_PROBING,
+	};
+	const warnings: string[] = [];
+	for (const [key, value] of Object.entries(raw)) {
+		const currentKey = RENAMED_CONFIG_KEYS.get(key);
+		// The current name always wins, so a file carrying both names loads order-independently.
+		if (currentKey !== undefined && currentKey in raw) continue;
+		const warning = applyOverride(currentKey ?? key, key, value, config);
+		if (warning !== undefined) warnings.push(warning);
+	}
+	return { config, warnings };
+}
+
+/** Configuration being assembled from the defaults, before it is returned read-only. */
+interface ConfigDraft {
+	categoryColors: Map<string, CategoryColor>;
+	mapSize: Record<MapSizeField, number>;
+	autoProbing: boolean;
+}
+
+/**
+ * Apply one entry onto the mutable defaults, returning the reason it was
+ * ignored. Reports name `configuredKey`, the name the file carries, which an
+ * accepted alias makes differ from the `resolvedKey` the entry configures.
+ */
+function applyOverride(
+	resolvedKey: string,
+	configuredKey: string,
+	value: unknown,
+	config: ConfigDraft,
+): string | undefined {
+	const categoryId = CONFIG_KEY_CATEGORIES.get(resolvedKey);
+	if (categoryId !== undefined) {
+		const color = parseColor(value);
+		if (color === undefined) {
+			return `Ignoring invalid color for "${configuredKey}"; expected a theme color name or a hex value.`;
+		}
+		config.categoryColors.set(categoryId, color);
+		return undefined;
+	}
+	const field = CONFIG_KEY_MAP_FIELDS.get(resolvedKey);
+	if (field !== undefined) {
+		const cells = parseMapDimension(value);
+		if (cells === undefined) {
+			return `Ignoring invalid size for "${configuredKey}"; ` +
+				`expected an integer between ${MINIMUM_MAP_CELLS} and ${MAXIMUM_MAP_CELLS}.`;
+		}
+		config.mapSize[field] = cells;
+		return undefined;
+	}
+	if (resolvedKey === AUTO_PROBING_KEY) {
+		if (typeof value !== "boolean") return `Ignoring invalid value for "${configuredKey}"; expected true or false.`;
+		config.autoProbing = value;
+		return undefined;
+	}
+	return `Ignoring unknown ${CONFIG_FILE_NAME} key "${configuredKey}".`;
+}
+
+/** Whole-file failure: built-in defaults plus one explanatory warning. */
+function degraded(reason: string): ConfigLoadResult {
+	return { config: DEFAULT_CONFIG, warnings: [`${reason} Using default configuration.`] };
+}
+
+/** Normalize one configured color value, or reject it as unusable. */
+function parseColor(value: unknown): CategoryColor | undefined {
+	if (typeof value !== "string") return undefined;
+	if (isThemeColor(value)) return value;
+	return parseHexColor(value);
+}
+
+/** Accept only whole in-range cell counts; the viewport still clamps what it cannot render. */
+function parseMapDimension(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isInteger(value)) return undefined;
+	if (value < MINIMUM_MAP_CELLS || value > MAXIMUM_MAP_CELLS) return undefined;
+	return value;
+}
+
+/** Accept only theme color keys the active theme is guaranteed to define. */
+function isThemeColor(value: unknown): value is ThemeColor {
+	return typeof value === "string" && THEME_COLORS.has(value);
+}
+
+/** Expand shorthand and lowercase, so rendering always resolves six hex digits. */
+function parseHexColor(value: string): HexColor | undefined {
+	if (!HEX_COLOR_PATTERN.test(value)) return undefined;
+	const digits = value.slice(1).toLowerCase();
+	if (digits.length === 6) return `#${digits}`;
+	return `#${[...digits].map((digit) => `${digit}${digit}`).join("")}`;
+}
+
+/** Modification time in milliseconds, or undefined while the file is absent or unreadable. */
+function readModifiedTime(filePath: string): number | undefined {
+	try {
+		return statSync(filePath).mtimeMs;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Recognize one errno code: an absent file to read, or a create-only write refusing to clobber. */
+function hasErrorCode(error: unknown, code: "ENOENT" | "EEXIST"): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+/** Normalize an unknown throw into a short reportable reason. */
+function describeError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * pi-context-view - inspect what occupies the model context.
+ *
+ * Structured capture publishes a snapshot of every request to SnapshotStore,
+ * which keeps the latest one. Injections shows that request as it was sent;
+ * Usage applies it to the current branch. Either view runs one on-demand
+ * silent probe when opened before any request, unless configuration disables it. On a Pi version older than the
+ * supported one, it registers no lifecycle handlers, captures nothing, and
+ * `/context` only reports the
+ * required version.
+ */
+import { type ExtensionAPI, type ExtensionCommandContext, VERSION } from "@earendil-works/pi-coding-agent";
+
+import { type ConfigLoadResult, ConfigStore, createDefaultConfigFile } from "./config.ts";
+import {
+	CONTEXT_COMMAND_DESCRIPTION,
+	getContextArgumentCompletions,
+	parseContextCommand,
+	reportCommandMessage,
+	reportCompactionInProgress,
+	reportConfigCreation,
+	reportTuiOnly,
+	reportUnsupportedPi,
+	type RequestSnapshotResult,
+	resolveRequestSnapshot,
+} from "./command.ts";
+import { SnapshotBuilder } from "./capture/builder.ts";
+import { registerCapture } from "./capture/register.ts";
+import { CompactionState, registerCompactionTracking } from "./compaction.ts";
+import { buildFallbackInjectionsSnapshot, buildInjectionsSnapshot } from "./injections.ts";
+import { resolveNextRequestModel } from "./model-identity.ts";
+import { isSupportedPiVersion } from "./pi-version.ts";
+import { ProbeFilter, registerProbeFilter } from "./probe/filter.ts";
+import { registerSilentProbe, SilentProbe } from "./probe/silent-probe.ts";
+import { ProbeTrigger } from "./probe/trigger.ts";
+import { createProbeView } from "./probe/view.ts";
+import { applyRequestSnapshot } from "./projection.ts";
+import { collectPromptSources } from "./prompt-additions.ts";
+import { buildUsageSnapshot } from "./replay.ts";
+import { readAutoCompactReserveTokens } from "./settings.ts";
+import { SnapshotStore } from "./snapshot.ts";
+import { showInjectionsView } from "./ui/injections-view.ts";
+import { showUsageView } from "./ui/usage-view.ts";
+import { computeUsage, toReportedUsage } from "./usage.ts";
+
+/**
+ * Extension factory. Pi passes only `pi`; in-process tests pass `snapshots` to
+ * read what capture publishes, and `configStore` to stay independent of the
+ * developer's configuration file.
+ */
+export default function (pi: ExtensionAPI, snapshots = new SnapshotStore(), configStore = new ConfigStore()) {
+	const probeFilter = new ProbeFilter();
+	const probe = new SilentProbe(probeFilter);
+	const probeView = createProbeView(probeFilter, probe);
+	const compaction = new CompactionState();
+	const trigger = new ProbeTrigger({ pi, probe, snapshots, compaction });
+	const supported = isSupportedPiVersion(VERSION);
+
+	/** Open Injections on the latest request snapshot, or on the pi-native fallback without one. */
+	async function openInjections(
+		ctx: ExtensionCommandContext,
+		latest: RequestSnapshotResult,
+		loadedConfig: ConfigLoadResult,
+	): Promise<void> {
+		if (latest.type !== "snapshot") {
+			await showInjectionsView(ctx, {
+				snapshot: buildFallbackInjectionsSnapshot({
+					systemPrompt: ctx.getSystemPrompt(),
+					options: ctx.getSystemPromptOptions(),
+					allTools: pi.getAllTools(),
+					activeToolNames: pi.getActiveTools(),
+					promptSources: collectPromptSources(pi.getAllTools(), pi.getCommands()),
+				}),
+				degradedReason: latest.type === "missing" ? latest.degradedReason : undefined,
+				probingDisabled: latest.type === "unprobed",
+				notices: loadedConfig.warnings,
+			});
+			return;
+		}
+		const snapshot = latest.snapshot;
+		await showInjectionsView(ctx, {
+			snapshot: buildInjectionsSnapshot({
+				snapshot,
+				entries: ctx.sessionManager.getEntries(),
+				filterMessages: (messages) => probeView.filterMessages(messages),
+				options: ctx.getSystemPromptOptions(),
+				allTools: pi.getAllTools(),
+				promptSources: collectPromptSources(pi.getAllTools(), pi.getCommands()),
+				systemPrompt: ctx.getSystemPrompt(),
+				activeToolNames: pi.getActiveTools(),
+			}),
+			probe: snapshot.origin === "synthetic-probe",
+			guard: snapshot.guard,
+			notices: loadedConfig.warnings,
+		});
+	}
+
+	/** Open Usage on the current branch with the latest request snapshot's changes applied. */
+	async function openUsage(
+		ctx: ExtensionCommandContext,
+		latest: RequestSnapshotResult,
+		loadedConfig: ConfigLoadResult,
+	): Promise<void> {
+		const { messages, branchMessages, systemChanges, forcedPrompt } = applyRequestSnapshot({
+			snapshot: latest.type === "snapshot" ? latest.snapshot : undefined,
+			entries: ctx.sessionManager.getEntries(),
+			leafId: ctx.sessionManager.getLeafId(),
+			filterMessages: (projected) => probeView.filterMessages(projected),
+		});
+		const current = buildUsageSnapshot({
+			messages,
+			systemChanges,
+			forcedPrompt,
+			systemPrompt: ctx.getSystemPrompt(),
+			options: ctx.getSystemPromptOptions(),
+			allTools: pi.getAllTools(),
+			activeToolNames: pi.getActiveTools(),
+			promptSources: collectPromptSources(pi.getAllTools(), pi.getCommands()),
+		});
+		await showUsageView(ctx, {
+			usage: computeUsage({
+				snapshot: current,
+				messages,
+				reported: toReportedUsage(ctx.getContextUsage()),
+				modelLabel: ctx.model?.id,
+				// Pi's routed-model lookup reads its session messages, not the request's changes
+				nextRequestModel: resolveNextRequestModel(ctx.model, branchMessages),
+				autoCompactReserveTokens: readAutoCompactReserveTokens(pi, ctx.model),
+			}),
+			degradedReason: latest.type === "missing" ? latest.degradedReason : undefined,
+			probingDisabled: latest.type === "unprobed",
+			// Reported inside the view: a notification would stay hidden behind the fullscreen overlay.
+			notices: loadedConfig.warnings,
+			categoryColors: loadedConfig.config.categoryColors,
+			mapSize: loadedConfig.config.mapSize,
+		});
+	}
+
+	pi.registerCommand("context", {
+		description: CONTEXT_COMMAND_DESCRIPTION,
+		getArgumentCompletions: getContextArgumentCompletions,
+		handler: async (args, ctx) => {
+			// Every form, config included, would describe a lifecycle this Pi does not have
+			if (!supported) {
+				reportUnsupportedPi(ctx, VERSION);
+				return;
+			}
+			const command = parseContextCommand(args);
+			if (command.type === "invalid") {
+				reportCommandMessage(ctx, command.message, "error");
+				return;
+			}
+			// Creating the file needs no UI, so it stays available in every run mode.
+			if (command.type === "config") {
+				reportConfigCreation(ctx, createDefaultConfigFile());
+				return;
+			}
+			if (ctx.mode !== "tui") {
+				reportTuiOnly(ctx, command.view);
+				return;
+			}
+			if (compaction.isActive) {
+				reportCompactionInProgress(ctx, command.view);
+				return;
+			}
+			// Loaded only when a view opens: the factory also runs where no view can
+			const loadedConfig = configStore.load();
+			const latest = await resolveRequestSnapshot(snapshots, trigger, ctx, loadedConfig.config.autoProbing);
+			// Compaction can start while waiting for idle; refuse instead of showing its fallback
+			if (compaction.isActive) {
+				reportCompactionInProgress(ctx, command.view);
+				return;
+			}
+			if (command.view === "injections") await openInjections(ctx, latest, loadedConfig);
+			else await openUsage(ctx, latest, loadedConfig);
+		},
+	});
+
+	// Older Pi lacks events the capture and the probe rely on, so observe nothing there
+	if (!supported) return;
+
+	// Probe layer first: ProbeFilter's context_with_system handler must run before capture's
+	registerProbeFilter(pi, probeFilter);
+	registerSilentProbe(pi, probe);
+	registerCapture(pi, probeView, new SnapshotBuilder(snapshots));
+	registerCompactionTracking(pi, compaction);
+
+	pi.on("session_shutdown", () => {
+		snapshots.clear();
+	});
+}