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

package/src/capture/register.ts

@@ -0,0 +1,129 @@
+/**
+ * Capture layer wiring: reads Pi's hidden tools in `before_agent_start`,
+ * observes every agent request in `context_with_system`, pairs it with its
+ * provider payload in `before_provider_request`, and confirms
+ * the dispatch from assistant message events. Observe only:
+ * handlers return nothing and never change provider-bound data. Runs in every
+ * run mode, without any consumer, and imports no trigger or consumer code.
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { ProbeView } from "../probe/view.ts";
+import type { SnapshotBuilder } from "./builder.ts";
+import { DispatchConfirmer } from "./dispatch.ts";
+import { PayloadGuard } from "./guard.ts";
+import { type CapturedRequest, captureRequest } from "./request.ts";
+import { NO_PAYLOAD_REASON, RequestTracker } from "./tracker.ts";
+
+/**
+ * Register RequestTracker, ProjectionReader, TranscriptCapture, PayloadGuard,
+ * and DispatchConfirmer. Register after ProbeFilter: its `context_with_system`
+ * handler must remove probe messages before this one compares and copies the
+ * transcript.
+ */
+export function registerCapture(pi: ExtensionAPI, probe: ProbeView, builder: SnapshotBuilder): void {
+	const tracker = new RequestTracker<CapturedRequest>();
+	const confirmer = new DispatchConfirmer<number>();
+	const guard = new PayloadGuard({
+		publisher: builder,
+		blockImages: () => readBlockImages(pi),
+	});
+	/**
+	 * Pi's hidden declarations, as every run's `before_agent_start` reports them.
+	 * Only a later handler or a mid-run tool change can make this copy stale.
+	 */
+	let hiddenTools: readonly string[] = [];
+
+	/** Settle the latest unpaired capture: no payload reached the monitor for it. */
+	function settleUnpaired(): void {
+		const capture = tracker.takeUnpaired();
+		if (capture === undefined) return;
+		builder.settleGuard(capture.id, { status: "incomplete", reason: NO_PAYLOAD_REASON });
+		builder.release(capture.id);
+	}
+
+	/** Hand the first assistant dispatch identity of the waiting request to the guard. */
+	function confirmDispatch(message: AgentMessage, ctx: ExtensionContext): void {
+		if (message.role !== "assistant") return;
+		const request = confirmer.take();
+		if (request === undefined) return;
+		const dispatch = { provider: message.provider, api: message.api, model: message.model };
+		guard.confirm(request, dispatch, (provider, modelId) => ctx.modelRegistry.find(provider, modelId));
+	}
+
+	pi.on("before_agent_start", (event) => {
+		// Pi before 1.0.4 leaves `hiddenTools` out of the options
+		hiddenTools = [...(event.systemPromptOptions.hiddenTools ?? [])];
+	});
+
+	pi.on("context_with_system", (event, ctx) => {
+		settleUnpaired();
+		let request: CapturedRequest;
+		try {
+			request = captureRequest({
+				id: tracker.nextId(),
+				origin: probe.isCurrentRun ? "synthetic-probe" : "real-turn",
+				messages: event.messages,
+				sessionManager: ctx.sessionManager,
+				effectivePrompt: ctx.getSystemPrompt(),
+				probe,
+				requestModel: ctx.model,
+				hiddenTools,
+			});
+		} catch {
+			// A request whose changes cannot be cloned is not captured; the request itself proceeds unchanged
+			return;
+		}
+		tracker.track(request);
+		builder.build(request);
+	});
+
+	pi.on("cache_warming_decision", () => {
+		tracker.noteWarmDecision();
+	});
+
+	pi.on("before_provider_request", (event) => {
+		const pairing = tracker.pair(event.payload);
+		if (pairing.type !== "paired") return;
+		// Later handlers can edit the payload in place, so copy it now
+		guard.accept(pairing.capture, event.payload);
+		const previous = confirmer.expect(pairing.capture.id);
+		if (previous !== undefined) guard.finishUnconfirmed(previous);
+	});
+
+	// No provider_stream_event handler: Pi emits that event, with an awaited emit per chunk, only when one exists
+	pi.on("message_start", (event, ctx) => {
+		confirmDispatch(event.message, ctx);
+	});
+
+	pi.on("message_end", (event, ctx) => {
+		confirmDispatch(event.message, ctx);
+	});
+
+	pi.on("agent_settled", () => {
+		settleUnpaired();
+		const unconfirmed = confirmer.take();
+		if (unconfirmed !== undefined) guard.finishUnconfirmed(unconfirmed);
+	});
+
+	pi.on("session_shutdown", () => {
+		hiddenTools = [];
+		tracker.clear();
+		confirmer.clear();
+		guard.clear();
+		builder.clear();
+	});
+}
+
+/**
+ * Pi's live `images.blockImages` setting: the evidence for its blocked-image
+ * text in a payload. Unreadable settings count as off, so that text is reported.
+ */
+function readBlockImages(pi: ExtensionAPI): boolean {
+	try {
+		return pi.getSettings().images?.blockImages === true;
+	} catch {
+		return false;
+	}
+}

package/src/capture/request.ts

@@ -0,0 +1,218 @@
+/**
+ * ProjectionReader and TranscriptCapture: the synchronous part of a structured
+ * capture in `context_with_system`. Everything here runs inside the
+ * handler, before later handlers can mutate the shared request messages.
+ */
+import {
+	contentText, getCurrentSystemMessage, getCurrentSystemPrompt, getDeclaredTools, type SystemMessage, type Tool,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { ProbeView } from "../probe/view.ts";
+import type { CaptureOrigin, RequestMessage } from "../snapshot.ts";
+import { trimMatchedEnds, type UnmatchedMessages } from "./diff.ts";
+import type { GuardModel } from "./guard.ts";
+
+/**
+ * Forced prompt per capture, resolved by whichever deferred job asks first.
+ * Weak keys release an entry with its capture.
+ */
+const FORCED_PROMPTS = new WeakMap<ForcedPromptInput, string | undefined>();
+
+/** A baseline message with the session entry that owns it. */
+export interface BaselineMessage {
+	readonly entryId: string;
+	readonly message: RequestMessage;
+}
+
+/** Filtered session projection at capture time. */
+export interface Baseline {
+	/** Session leaf; `buildSessionProjection(entries, leafId)` rebuilds these messages. */
+	readonly leafId: string | null;
+	readonly messages: readonly BaselineMessage[];
+}
+
+/**
+ * Text of one request system message, without its tool changes. The payload
+ * guard renders it as Pi does, at its position, for models that keep later
+ * system messages in place.
+ */
+export interface SystemText {
+	/** Number of non-system request messages before this one. */
+	readonly position: number;
+	/** Plain content; text blocks are joined as Pi renders them. */
+	readonly content: string;
+	readonly sections?: Readonly<Record<string, string | null>>;
+}
+
+/**
+ * The parts of a request the deferred diff and the payload guard need, as this
+ * extension's handler saw them. Request-side values are owned copies.
+ */
+export interface RequestCopy {
+	/** The request's replayed system state; undefined when it has none. */
+	readonly system?: SystemMessage;
+	/** Every request system message's text, in order. */
+	readonly systemTexts: readonly SystemText[];
+	/** Every definition declared in the request, latest per name, including tools removed later. */
+	readonly declarations: readonly Tool[];
+	/**
+	 * Non-system messages left after removing the ends both sides share: session
+	 * originals on the baseline side, copies on the request side.
+	 */
+	readonly conversation: UnmatchedMessages;
+}
+
+/**
+ * Everything the deferred diff needs from one request. Process-local: it holds
+ * raw content and is released once its snapshot is built.
+ */
+export interface CapturedRequest extends RequestCopy {
+	readonly id: number;
+	readonly origin: CaptureOrigin;
+	readonly baseline: Baseline;
+	/**
+	 * `ctx.getSystemPrompt()` at capture. Deferred jobs compare it with the
+	 * baseline replay to detect a forced prompt ({@link resolveForcedPrompt}).
+	 */
+	readonly effectivePrompt: string;
+	/** `ctx.model` at capture: the dispatched model on a physical selection, the virtual one otherwise. */
+	readonly requestModel?: GuardModel;
+	/** Tools Pi left out of the request; absent when it hid none. */
+	readonly hiddenTools?: readonly string[];
+}
+
+/** What forced-prompt detection reads from a capture. */
+export interface ForcedPromptInput {
+	readonly effectivePrompt: string;
+	readonly baseline: { readonly messages: readonly BaselineMessage[] };
+}
+
+/** Inputs of one capture, read from the `context_with_system` event and its context. */
+export interface CaptureInput {
+	readonly id: number;
+	readonly origin: CaptureOrigin;
+	readonly messages: readonly RequestMessage[];
+	readonly sessionManager: Pick<ExtensionContext["sessionManager"], "buildSessionProjection" | "getLeafId">;
+	/** `ctx.getSystemPrompt()`: Pi's effective prompt for the current run. */
+	readonly effectivePrompt: string;
+	readonly probe: Pick<ProbeView, "filterMessages">;
+	/** `ctx.model`; its identity is copied before later handlers can change it. */
+	readonly requestModel?: GuardModel;
+	/** Pi's hidden declarations for the current run, from its `before_agent_start` options. */
+	readonly hiddenTools?: readonly string[];
+}
+
+/**
+ * Read the baseline, copy what differs from it, and keep the effective prompt
+ * for deferred forced-prompt detection. Throws when a differing message cannot
+ * be cloned, for example when a handler added a function value to it.
+ */
+export function captureRequest(input: CaptureInput): CapturedRequest {
+	const baseline = readBaseline(input.sessionManager, input.probe);
+	return {
+		id: input.id,
+		origin: input.origin,
+		baseline,
+		...copyRequest(baseline.messages, input.messages),
+		effectivePrompt: input.effectivePrompt,
+		...(input.requestModel === undefined ? {} : { requestModel: copyGuardModel(input.requestModel) }),
+		...(input.hiddenTools === undefined || input.hiddenTools.length === 0
+			? {}
+			: { hiddenTools: [...input.hiddenTools] }),
+	};
+}
+
+/**
+ * Copy the request's replayed system state and the messages that differ from
+ * the baseline. Messages equal to the baseline at both ends are compared in
+ * place and never copied. System text positions and historical declarations
+ * also belong to the copy: serializers may keep them instead of collapsing.
+ */
+export function copyRequest(baseline: readonly BaselineMessage[], messages: readonly RequestMessage[]): RequestCopy {
+	const unmatched = trimMatchedEnds(baseline, messages);
+	// Later handlers share these objects, tool schemas included, and may edit them in place
+	const copy = structuredClone({
+		system: getCurrentSystemMessage(messages), declarations: getDeclaredTools(messages), request: unmatched.request,
+	});
+	return {
+		...(copy.system === undefined ? {} : { system: copy.system }),
+		systemTexts: copySystemTexts(messages),
+		declarations: copy.declarations,
+		conversation: { prefix: unmatched.prefix, baseline: unmatched.baseline, request: copy.request },
+	};
+}
+
+/**
+ * Read the canonical session projection Pi rebuilt this request from, without
+ * recorded probe messages, keeping each message's source entry. The projection
+ * returns stored session objects; they are only read, never changed.
+ */
+export function readBaseline(
+	sessionManager: CaptureInput["sessionManager"],
+	probe: CaptureInput["probe"],
+): Baseline {
+	const projection = sessionManager.buildSessionProjection();
+	const messages = projection.entries.flatMap(({ sourceEntry, messages: entryMessages }) =>
+		probe.filterMessages(entryMessages).map((message) => ({ entryId: sourceEntry.id, message })));
+	return { leafId: sessionManager.getLeafId(), messages };
+}
+
+/**
+ * The capture's forced prompt, replaying its baseline at most once: the
+ * snapshot builder and the payload guard both read it, in either order.
+ */
+export function resolveForcedPrompt(capture: ForcedPromptInput): string | undefined {
+	if (FORCED_PROMPTS.has(capture)) return FORCED_PROMPTS.get(capture);
+	const forced = detectForcedPrompt(capture.effectivePrompt, capture.baseline.messages);
+	FORCED_PROMPTS.set(capture, forced);
+	return forced;
+}
+
+/**
+ * The forced prompt of the current run, or undefined when the effective prompt
+ * is the one the baseline replays. Pi records structured sections even for a
+ * forced prompt and projects the forced text onto the request afterwards.
+ * Runs off the request's critical path: baseline messages are append-only
+ * session objects, so the replay matches the one at capture.
+ */
+export function detectForcedPrompt(effectivePrompt: string, baseline: readonly BaselineMessage[]): string | undefined {
+	const replayed = getCurrentSystemPrompt(baseline.map(({ message }) => message));
+	return effectivePrompt === replayed ? undefined : effectivePrompt;
+}
+
+/**
+ * Copy the text of every system message with its position. Strings are
+ * immutable, so a shallow copy of the sections suffices; tool changes are
+ * left out because the replayed system state already holds them.
+ */
+function copySystemTexts(messages: readonly RequestMessage[]): SystemText[] {
+	const texts: SystemText[] = [];
+	let position = 0;
+	for (const message of messages) {
+		if (message.role !== "system") {
+			position++;
+			continue;
+		}
+		const content = contentText(message.content);
+		texts.push(message.sections === undefined
+			? { position, content }
+			: { position, content, sections: { ...message.sections } });
+	}
+	return texts;
+}
+
+/**
+ * Copy the identity and the capabilities message normalization reads, before
+ * later handlers can change the model object. Only top-level `compat` flags
+ * are read, so a shallow copy suffices.
+ */
+function copyGuardModel(model: GuardModel): GuardModel {
+	return {
+		provider: model.provider,
+		api: model.api,
+		id: model.id,
+		input: [...model.input],
+		...(model.compat === undefined ? {} : { compat: { ...model.compat } }),
+	};
+}

package/src/capture/tools.ts

@@ -0,0 +1,69 @@
+/**
+ * PayloadGuard's tool-declaration channel: compare the declarations a
+ * payload carries with the tools the structured capture replayed, less the ones
+ * Pi hid. Pure functions over process-local data.
+ */
+import type { GuardFinding } from "../snapshot.ts";
+import { diffLines, normalizeText } from "./messages.ts";
+import type { PayloadDeclaration } from "./payload.ts";
+
+/** Inputs of one tool-channel comparison. */
+export interface ToolComparisonInput {
+	/** Tools replayed from the request at the monitor's handler, without the ones Pi hid. */
+	readonly expected: readonly PayloadDeclaration[];
+	/** Declarations of the payload after its inline changes were replayed. */
+	readonly declarations: readonly PayloadDeclaration[];
+	/**
+	 * Match payload names to expected ones without case, as Pi does for Claude
+	 * Code tool names with an Anthropic OAuth token.
+	 */
+	readonly ignoreNameCase: boolean;
+}
+
+/**
+ * Compare the declarations; each difference is edited after monitor:
+ *   missing from the payload    deleted, with the captured description lines
+ *   added by the payload        added, with the payload's description lines
+ *   description differs         modified, with the changed lines
+ * Descriptions are compared without whitespace, as message text is. Schemas
+ * are not compared: Pi adapts them per provider, such as for strict mode.
+ */
+export function compareToolDeclarations(input: ToolComparisonInput): GuardFinding[] {
+	const expectedByName = new Map(input.expected.map((tool) => [tool.name, tool]));
+	const declared = input.declarations.map((declaration) => ({
+		...declaration,
+		name: resolveName(declaration.name, expectedByName, input.ignoreNameCase),
+	}));
+	const declaredNames = new Set(declared.map((declaration) => declaration.name));
+	const findings: GuardFinding[] = [];
+
+	for (const tool of input.expected) {
+		if (declaredNames.has(tool.name)) continue;
+		findings.push({
+			type: "payload-tool-change",
+			change: "deleted",
+			name: tool.name,
+			lines: diffLines(tool.description ?? "", ""),
+		});
+	}
+	for (const declaration of declared) {
+		const tool = expectedByName.get(declaration.name);
+		const before = tool?.description ?? "";
+		const after = declaration.description ?? "";
+		if (tool !== undefined && normalizeText(before) === normalizeText(after)) continue;
+		findings.push({
+			type: "payload-tool-change",
+			change: tool === undefined ? "added" : "modified",
+			name: declaration.name,
+			lines: diffLines(before, after),
+		});
+	}
+	return findings;
+}
+
+/** The expected name a payload name stands for; itself when it matches exactly or nothing matches. */
+function resolveName(name: string, expected: ReadonlyMap<string, unknown>, ignoreCase: boolean): string {
+	if (!ignoreCase || expected.has(name)) return name;
+	const lower = name.toLowerCase();
+	return [...expected.keys()].find((candidate) => candidate.toLowerCase() === lower) ?? name;
+}

package/src/capture/tracker.ts

@@ -0,0 +1,71 @@
+/**
+ * RequestTracker: numbers captures and pairs each agent payload with the
+ * latest capture still waiting for one. `turnIndex` restarts with every agent
+ * run, so only a local number identifies a request.
+ */
+import { hasWarmOutputLimit } from "./payload.ts";
+
+/** Guard reason of a capture that ended without a paired provider payload. */
+export const NO_PAYLOAD_REASON = "No provider payload was observed for this request.";
+
+/**
+ * How a payload relates to the captures:
+ *   paired         the payload of the latest unpaired capture
+ *   warm-refresh   a cache-warm refresh repeating an earlier request; not compared
+ *   unpaired       no capture is waiting, as for a refresh after its run or a nonstandard host
+ */
+export type PayloadPairing<Capture> =
+	| { readonly type: "paired"; readonly capture: Capture }
+	| { readonly type: "warm-refresh" }
+	| { readonly type: "unpaired" };
+
+/**
+ * Capture numbering and payload pairing state. Agent-level retries start a
+ * new run with a new capture; provider-level retries resend a payload without
+ * another `before_provider_request`, so neither needs special pairing.
+ */
+export class RequestTracker<Capture> {
+	private captureCount = 0;
+	private unpaired: Capture | undefined;
+	private warmDecisionSinceCapture = false;
+
+	/** Number the next capture; later captures have larger numbers. */
+	public nextId(): number {
+		return ++this.captureCount;
+	}
+
+	/** Make `capture` the latest unpaired capture; earlier warm decisions no longer apply. */
+	public track(capture: Capture): void {
+		this.unpaired = capture;
+		this.warmDecisionSinceCapture = false;
+	}
+
+	/** Take the unpaired capture, if any, so its guard can settle without a payload. */
+	public takeUnpaired(): Capture | undefined {
+		const capture = this.unpaired;
+		this.unpaired = undefined;
+		return capture;
+	}
+
+	/** Note a `cache_warming_decision`: a refresh may follow before the next capture. */
+	public noteWarmDecision(): void {
+		this.warmDecisionSinceCapture = true;
+	}
+
+	/**
+	 * Pair a payload. A warm decision alone is not enough: handler results do
+	 * not update the decision event, so a later handler may have stopped the
+	 * refresh. The refresh's one-token output limit confirms it.
+	 */
+	public pair(payload: unknown): PayloadPairing<Capture> {
+		if (this.warmDecisionSinceCapture && hasWarmOutputLimit(payload)) return { type: "warm-refresh" };
+		const capture = this.takeUnpaired();
+		return capture === undefined ? { type: "unpaired" } : { type: "paired", capture };
+	}
+
+	/** Forget the unpaired capture and warm decisions, as at session shutdown. */
+	public clear(): void {
+		this.unpaired = undefined;
+		this.warmDecisionSinceCapture = false;
+	}
+}

package/src/command.ts

@@ -0,0 +1,164 @@
+/**
+ * `/context` command grammar, argument completions, and resolution of the
+ * latest request snapshot that both views read.
+ */
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+import type { ConfigCreationResult } from "./config.ts";
+import { MIN_PI_VERSION } from "./pi-version.ts";
+import type { ProbeTrigger } from "./probe/trigger.ts";
+import type { RequestSnapshot, SnapshotReader } from "./snapshot.ts";
+import { normalizePreviewText } from "./text.ts";
+
+const COMMAND_USAGE = "Usage: /context [usage|injections|config]";
+/**
+ * Slash-command palette text, kept beside the grammar it describes.
+ * RegisteredCommand has no argumentHint; mimic pi's `<hint> — <description>` style.
+ */
+export const CONTEXT_COMMAND_DESCRIPTION =
+	"[usage|injections|config] - Inspect context usage, injections";
+/** Cap for reported messages, which may quote configuration files and OS error text. */
+const MAX_REPORTED_MESSAGE_LENGTH = 500;
+const DEFAULT_VIEW: ContextView = "usage";
+const ARGUMENT_OPTIONS = [
+	{ value: "usage", label: "usage", description: "Show estimated context usage" },
+	{ value: "injections", label: "injections", description: "Explore the latest request's injections" },
+	{ value: "config", label: "config", description: "Create config file populated with defaults" },
+] satisfies AutocompleteItem[];
+
+/** The focused view a `/context` invocation requests. */
+export type ContextView = "usage" | "injections";
+
+/** Parsed `/context` argument grammar. */
+export type ContextCommand =
+	| { readonly type: "view"; readonly view: ContextView }
+	| { readonly type: "config" }
+	| { readonly type: "invalid"; readonly message: string };
+
+/**
+ * The latest request snapshot, or why the view opens without one:
+ *   missing    a probe was skipped or failed; the view must explain why it degraded
+ *   unprobed   none was captured yet and `autoProbing` is off, an expected state
+ */
+export type RequestSnapshotResult =
+	| { readonly type: "snapshot"; readonly snapshot: RequestSnapshot }
+	| { readonly type: "missing"; readonly degradedReason: string }
+	| { readonly type: "unprobed" };
+
+/** Parse the complete, intentionally small `/context` argument grammar. */
+export function parseContextCommand(argumentsText: string): ContextCommand {
+	const words = argumentsText.trim().toLowerCase().split(/\s+/).filter(Boolean);
+	if (words.length === 0) {
+		return { type: "view", view: DEFAULT_VIEW };
+	}
+	if (words.length === 1 && words[0] === "usage") {
+		return { type: "view", view: "usage" };
+	}
+	if (words.length === 1 && words[0] === "injections") {
+		return { type: "view", view: "injections" };
+	}
+	if (words.length === 1 && words[0] === "config") {
+		return { type: "config" };
+	}
+	return { type: "invalid", message: COMMAND_USAGE };
+}
+
+/** Complete full argument values for the supported `/context` grammar. */
+export function getContextArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+	const normalizedPrefix = argumentPrefix.trimStart().toLowerCase();
+	const matches = ARGUMENT_OPTIONS.filter((option) => option.value.startsWith(normalizedPrefix));
+	return matches.length > 0 ? matches.map((option) => ({ ...option })) : null;
+}
+
+/**
+ * Obtain the latest request snapshot of this runtime, asking ProbeTrigger
+ * only when the store has none after the agent is idle: a real turn that was
+ * running publishes one without a probe. A probe's snapshot is read from the
+ * store, not from the probe result. With `autoProbing` off, an empty store
+ * resolves to `unprobed` without asking ProbeTrigger.
+ */
+export async function resolveRequestSnapshot(
+	snapshots: SnapshotReader,
+	trigger: ProbeTrigger,
+	context: ExtensionCommandContext,
+	autoProbing: boolean,
+): Promise<RequestSnapshotResult> {
+	const existing = snapshots.latest();
+	if (existing !== undefined) return { type: "snapshot", snapshot: existing };
+	await context.waitForIdle();
+	const afterIdle = snapshots.latest();
+	if (afterIdle !== undefined) return { type: "snapshot", snapshot: afterIdle };
+
+	if (!autoProbing) return { type: "unprobed" };
+
+	const result = await trigger.request(context);
+	const probed = snapshots.latest();
+	if (probed !== undefined) return { type: "snapshot", snapshot: probed };
+	const reason = result.status === "failed" ? result.reason : "Silent probe did not capture a request.";
+	return { type: "missing", degradedReason: `${reason} Extension additions were not observed.` };
+}
+
+/**
+ * Report command errors in both interactive and headless modes. Messages can
+ * quote untrusted text such as configuration keys, so they are sanitized and
+ * capped before reaching the terminal.
+ */
+export function reportCommandMessage(
+	context: ExtensionCommandContext,
+	message: string,
+	type: "info" | "warning" | "error",
+): void {
+	const safeMessage = truncate(normalizePreviewText(message), MAX_REPORTED_MESSAGE_LENGTH);
+	if (context.hasUI) {
+		context.ui.notify(safeMessage, type);
+		return;
+	}
+	process.stderr.write(`${safeMessage}\n`);
+}
+
+/** Refuse a view outside TUI mode, naming the form the user typed. */
+export function reportTuiOnly(context: ExtensionCommandContext, view: ContextView): void {
+	reportCommandMessage(context, `/context ${view} is available in TUI mode only.`, "warning");
+}
+
+/**
+ * Refuse a view while compaction is active: the session projection both views
+ * read is about to be replaced, and a probe could not run safely anyway.
+ */
+export function reportCompactionInProgress(context: ExtensionCommandContext, view: ContextView): void {
+	reportCommandMessage(context, `/context ${view} is unavailable while compaction is in progress.`, "warning");
+}
+
+/** Refuse any `/context` form on a Pi version whose lifecycle this extension does not capture. */
+export function reportUnsupportedPi(context: ExtensionCommandContext, version: string): void {
+	reportCommandMessage(context,
+		`/context requires Pi ${MIN_PI_VERSION} or newer; this is Pi ${version}. Nothing was captured.`,
+		"error",
+	);
+}
+
+/** Report the outcome of the explicit create-only configuration command. */
+export function reportConfigCreation(context: ExtensionCommandContext, result: ConfigCreationResult): void {
+	switch (result.type) {
+		case "created":
+			reportCommandMessage(context, `Created default configuration: ${result.filePath}`, "info");
+			break;
+		case "exists":
+			reportCommandMessage(context, `Configuration already exists; left unchanged: ${result.filePath}`, "warning");
+			break;
+		case "failed":
+			reportCommandMessage(context, `Cannot create configuration at ${result.filePath}: ${result.reason}`, "error");
+			break;
+		default: {
+			// Compile-time proof that every result variant is reported.
+			const _exhaustive: never = result;
+			return _exhaustive;
+		}
+	}
+}
+
+/** Shorten over-long text with an ellipsis marker. */
+function truncate(text: string, maxLength: number): string {
+	return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}