pi-ui-extend 1.0.41 → 1.0.42

package/external/pi-tools-suite/src/context-gateway/index.ts

@@ -1,15 +1,18 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { classifyShellCommand, type ShellCommandClassification } from "../shell-command-policy.js";
 
 import {
-	CONTEXT_GATEWAY_ENFORCE_UNAVAILABLE,
+	contextGatewayBudgetForClass,
 	loadContextGatewayConfig,
 } from "./config.js";
-import { ContextGatewayTelemetry } from "./telemetry.js";
+import { planContextGatewayEnforcement } from "./enforcement.js";
+import { classifyContextGatewayTool, ContextGatewayTelemetry } from "./telemetry.js";
 import type {
 	ContextGatewayEffectiveMode,
 	ContextGatewayMode,
 	ContextGatewayResolvedConfig,
 	ContextGatewayRuntimeState,
+	ContextGatewayToolClass,
 } from "./types.js";
 
 export interface RegisterContextGatewayOptions {
@@ -25,23 +28,23 @@ function formatStatus(runtime: RegisteredContextGateway): string {
 	const telemetry = runtime.telemetry.snapshot();
 	return [
 		`Context Gateway requested=${runtime.requestedMode}, effective=${runtime.effectiveMode}.`,
-		`Observed results=${telemetry.results}, errors=${telemetry.errors}, upstreamTruncated=${telemetry.upstreamTruncatedResults}, overBudget=${telemetry.overBudgetResults}, unbound results=${telemetry.unboundResults}.`,
-		`Repeat candidates=${telemetry.repeatCandidateCount}, retrieval calls=${telemetry.retrievalCalls}.`,
+		`Observed results=${telemetry.results}, errors=${telemetry.errors}, upstreamTruncated=${telemetry.upstreamTruncatedResults}, overBudget=${telemetry.overBudgetResults}, enforced=${telemetry.enforcedResults}, unbound results=${telemetry.unboundResults}.`,
+		`Repeat exact reads=${telemetry.repeatCandidateCount}, same-source different-range reads=${telemetry.sameSourceDifferentRangeCount}, retrieval calls=${telemetry.retrievalCalls}.`,
 		`Native policy results=${telemetry.nativePolicy.results}, refusals=${telemetry.nativePolicy.refusals}, full overrides=${telemetry.nativePolicy.fullOverrides}.`,
-		`Observed contentBytes=${telemetry.contentBytes}, textBytes=${telemetry.textBytes}, detailsBytes=${telemetry.detailsBytes}, potentialBytesOverBudget=${telemetry.potentialBytesOverBudget}.`,
+		`Source contentBytes=${telemetry.contentBytes}, deliveredContentBytes=${telemetry.deliveredContentBytes}, actualBytesSaved=${telemetry.actualBytesSaved}, potentialBytesOverBudget=${telemetry.potentialBytesOverBudget}, detailsBytes=${telemetry.detailsBytes}.`,
 	].join("\n");
 }
 
 function formatDoctor(runtime: RegisteredContextGateway): string {
 	const lines = [
 		`Context Gateway doctor: requested=${runtime.requestedMode}, effective=${runtime.effectiveMode}.`,
-		"Capture: read=limited; bash=limited+temp-output; repo_*=suite-adapter-not-wired; ast_grep=suite-adapter-not-wired.",
+		"Budgets: read=maxExactReadBytes; repo search/AST/structure=maxSearchBytes; other results=maxResultBytes; compact inline view=maxInlineBytes.",
+		"Enforce: recognised complete simple test/build output=bounded parser compact; partial/unknown/compound/upstream-truncated/non-text=passthrough.",
+		"Read: full passthrough even when over budget; exact recovery/archive is not wired, so irreversible read truncation is disabled.",
+		"Repo tools: producer-native compact is supported with repoDiscovery.profile=native-compact; Gateway never post-hoc slices repo output.",
 		"External paths: MCP=current Pix adapter unsupported; direct parent browser capture=unsupported.",
 		"Storage: disabled; no durable archive, index, quota reservation, or retrieval tools are active.",
 	];
-	if (runtime.requestedMode === "enforce") {
-		lines.push("BLOCKED: enforce is unavailable in P01; effective mode is off.");
-	}
 	for (const issue of runtime.config.issues) lines.push(`Config issue: ${issue}`);
 	return lines.join("\n");
 }
@@ -57,8 +60,9 @@ export function registerContextGateway(
 	const config = (options.loadConfig ?? (() => loadContextGatewayConfig()))();
 	const telemetry = options.telemetry ?? new ContextGatewayTelemetry();
 	let requestedMode = config.mode;
-	let effectiveMode: ContextGatewayEffectiveMode = requestedMode === "enforce" ? "off" : requestedMode;
-	const inFlightToolCalls = new Set<string>();
+	let effectiveMode: ContextGatewayEffectiveMode = requestedMode;
+	type InFlight = { toolClass: ContextGatewayToolClass; shell: ShellCommandClassification };
+	const inFlightToolCalls = new Map<string, InFlight>();
 
 	const resetRuntimeTelemetry = (): void => {
 		inFlightToolCalls.clear();
@@ -71,9 +75,6 @@ export function registerContextGateway(
 		config,
 		telemetry,
 		setRuntimeMode(mode) {
-			if (mode === "enforce") {
-				return { ok: false, message: CONTEXT_GATEWAY_ENFORCE_UNAVAILABLE };
-			}
 			if (mode !== effectiveMode && inFlightToolCalls.size > 0) {
 				return {
 					ok: false,
@@ -88,14 +89,67 @@ export function registerContextGateway(
 	};
 
 	pi.on("tool_call", async (event) => {
-		if (typeof event.toolCallId === "string") inFlightToolCalls.add(event.toolCallId);
-		if (effectiveMode === "observe") telemetry.recordToolCall(event);
+		if (typeof event.toolCallId === "string" && typeof event.toolName === "string") {
+			const toolClass = classifyContextGatewayTool(event.toolName);
+			inFlightToolCalls.set(event.toolCallId, {
+				toolClass,
+				shell: toolClass === "shell"
+					? classifyShellCommand(event.input)
+					: { scope: "unknown", kind: "unknown" },
+			});
+		}
+		if (effectiveMode === "observe" || effectiveMode === "enforce") telemetry.recordToolCall(event);
 		return undefined;
 	});
 
 	pi.on("tool_result", async (event) => {
 		try {
-			if (effectiveMode === "observe") telemetry.recordToolResult(event, config.budgets.maxResultBytes);
+			if (effectiveMode === "off") return undefined;
+			const binding = typeof event.toolCallId === "string"
+				? inFlightToolCalls.get(event.toolCallId)
+				: undefined;
+			const classBudget = binding
+				? contextGatewayBudgetForClass(binding.toolClass, config.budgets)
+				: config.budgets.maxResultBytes;
+			const enforcement = effectiveMode === "enforce" && binding
+				? planContextGatewayEnforcement({
+					event,
+					toolClass: binding.toolClass,
+					shell: binding.shell,
+					budgetBytes: classBudget,
+					maxInlineBytes: Math.min(
+						config.budgets.maxInlineBytes,
+						classBudget,
+					),
+				})
+				: undefined;
+			telemetry.recordToolResult(event, config.budgets, {
+				maxInlineBytes: config.budgets.maxInlineBytes,
+				...(enforcement ? {
+					delivery: {
+						representation: enforcement.representation,
+						contentBytes: enforcement.contentBytes,
+						textBytes: enforcement.textBytes,
+					},
+				} : {}),
+			});
+			if (enforcement?.representation === "test-build-compact") {
+				const originalDetails = event.details && typeof event.details === "object" && !Array.isArray(event.details)
+					? event.details as Record<string, unknown>
+					: {};
+				return {
+					content: enforcement.content as any,
+					details: {
+						...originalDetails,
+						contextGateway: {
+							version: 1,
+							representation: enforcement.representation,
+							sourceContentBytes: enforcement.sourceContentBytes,
+							deliveredContentBytes: enforcement.contentBytes,
+						},
+					},
+				};
+			}
 		} finally {
 			if (typeof event.toolCallId === "string") inFlightToolCalls.delete(event.toolCallId);
 		}
@@ -118,7 +172,7 @@ export function registerContextGateway(
 	});
 
 	pi.registerCommand("context-gateway", {
-		description: "Show Context Gateway status/doctor output or change the runtime-only off/observe mode.",
+		description: "Show Context Gateway status/doctor output or change runtime-only off/observe/enforce mode.",
 		handler: async (rawArgs, ctx) => {
 			const args = rawArgs.trim().split(/\s+/).filter(Boolean);
 			const action = (args[0] ?? "status").toLowerCase();
@@ -127,7 +181,7 @@ export function registerContextGateway(
 				return;
 			}
 			if (action === "doctor") {
-				notify(ctx, formatDoctor(runtime), runtime.requestedMode === "enforce" ? "warning" : "info");
+				notify(ctx, formatDoctor(runtime), runtime.config.issues.length > 0 ? "warning" : "info");
 				return;
 			}
 			if (action === "mode") {

package/external/pi-tools-suite/src/context-gateway/storeless-capabilities.ts

@@ -1,5 +1,5 @@
 export type StorelessCapabilityStatus = "supported" | "limited" | "unsupported";
-export type StorelessCapabilityStrategy = "native-passthrough" | "metadata-only" | "pure-parser-candidate" | "none";
+export type StorelessCapabilityStrategy = "native-passthrough" | "metadata-only" | "pure-parser-candidate" | "pure-parser-compact" | "none";
 
 export interface StorelessCapabilityEntry {
 	surface:
@@ -27,9 +27,9 @@ export const STORELESS_CAPABILITIES: readonly StorelessCapabilityEntry[] = Objec
 	{
 		surface: "test-build",
 		status: "limited",
-		strategy: "pure-parser-candidate",
+		strategy: "pure-parser-compact",
 		lifetime: "current-result",
-		reason: "Bun/TAP/bounded TypeScript parsing is observe-only; production delivery remains passthrough without a recovery/lifetime contract.",
+		reason: "Enforce compacts only recognised complete simple Bun/TAP/bounded TypeScript output; partial, compound, truncated, or unknown results remain passthrough.",
 	},
 	{
 		surface: "mutation-lsp",

package/external/pi-tools-suite/src/context-gateway/telemetry.ts

@@ -1,8 +1,11 @@
 import { createHash } from "node:crypto";
+import { classifyShellCommand } from "../shell-command-policy.js";
 
 import { accountContextGatewayParts } from "./accounting.js";
+import { contextGatewayBudgetForClass } from "./config.js";
 import { parseTestBuildOutput, planProspectiveTestOutputDelivery } from "./test-output-parser.js";
 import type {
+	ContextGatewayBudgets,
 	ContextGatewayClassTelemetry,
 	ContextGatewayNativePolicyReason,
 	ContextGatewayNativePolicyTelemetry,
@@ -40,6 +43,7 @@ const NATIVE_POLICY_REASONS = new Set<ContextGatewayNativePolicyReason>([
 type CallBinding = {
 	toolClass: ContextGatewayToolClass;
 	inputFingerprint?: string;
+	readSourceFingerprint?: string;
 	shellCommandScope?: "simple" | "compound" | "unknown";
 };
 
@@ -60,12 +64,15 @@ function emptyCounters(): ContextGatewayClassTelemetry {
 		results: 0,
 		errors: 0,
 		contentBytes: 0,
+		deliveredContentBytes: 0,
 		textBytes: 0,
 		imageBytes: 0,
 		detailsBytes: 0,
 		upstreamTruncatedResults: 0,
 		overBudgetResults: 0,
 		potentialBytesOverBudget: 0,
+		enforcedResults: 0,
+		actualBytesSaved: 0,
 	};
 }
 
@@ -92,13 +99,46 @@ function inputFingerprint(toolName: string, input: unknown): string {
 	return createHash("sha256").update(`${toolName}\u0000${encoded}`).digest("hex");
 }
 
-function shellCommandScope(input: unknown): "simple" | "compound" | "unknown" {
-	if (!input || typeof input !== "object" || Array.isArray(input)) return "unknown";
-	const command = (input as Record<string, unknown>).command;
-	if (typeof command !== "string" || command.trim().length === 0) return "unknown";
-	// Conservative only: false positives merely keep passthrough. This does not
-	// parse, rewrite, approve, or execute the shell command.
-	return /[\r\n;|`]|&&|\$\(/.test(command) ? "compound" : "simple";
+function normalizedReadPath(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const raw = value.trim().replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+	if (!raw) return undefined;
+	const prefix = raw.startsWith("/") ? "/" : /^[A-Za-z]:\//.test(raw) ? raw.slice(0, 3).toLowerCase() : "";
+	const body = prefix === "/" ? raw.slice(1) : prefix ? raw.slice(3) : raw;
+	const stack: string[] = [];
+	for (const part of body.split("/")) {
+		if (!part || part === ".") continue;
+		if (part === "..") {
+			if (stack.length > 0 && stack.at(-1) !== "..") stack.pop();
+			else if (!prefix) stack.push(part);
+			continue;
+		}
+		stack.push(part);
+	}
+	return `${prefix}${stack.join("/")}` || prefix || ".";
+}
+
+function normalizedReadRangeValue(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return value;
+	if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+		const parsed = Number(value);
+		if (Number.isSafeInteger(parsed)) return parsed;
+	}
+	return undefined;
+}
+
+export function contextGatewayReadIdentity(input: unknown): { exact?: string; source?: string } {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+	const record = input as Record<string, unknown>;
+	const path = normalizedReadPath(record.path ?? record.file ?? record.filePath);
+	if (!path) return {};
+	const source = inputFingerprint("read-source", { path });
+	const exact = inputFingerprint("read-exact", {
+		path,
+		offset: normalizedReadRangeValue(record.offset ?? record.start ?? record.line),
+		limit: normalizedReadRangeValue(record.limit ?? record.lines ?? record.count),
+	});
+	return { source, exact };
 }
 
 function byteLengthJson(value: unknown): number {
@@ -209,19 +249,31 @@ export function classifyContextGatewayTool(toolName: string): ContextGatewayTool
 
 export function observeToolResult(
 	event: ToolResultLike,
-	maxResultBytes: number,
-	options: { toolClass?: ContextGatewayToolClass; shellCommandScope?: "simple" | "compound" | "unknown" } = {},
+	budget: number | ContextGatewayBudgets,
+	options: {
+		toolClass?: ContextGatewayToolClass;
+		shellCommandScope?: "simple" | "compound" | "unknown";
+		maxInlineBytes?: number;
+		delivery?: { representation: "passthrough" | "test-build-compact"; contentBytes: number; textBytes: number };
+	} = {},
 ): ContextGatewayObservation {
 	const toolName = typeof event.toolName === "string" ? event.toolName : "unknown";
 	const sizes = contentSizes(event.content);
 	const detailsBytes = byteLengthJson(event.details);
-	const potentialBytesOverBudget = Math.max(0, sizes.contentBytes - maxResultBytes);
 	const toolClass = options.toolClass ?? classifyContextGatewayTool(toolName);
+	const budgetBytes = typeof budget === "number" ? budget : contextGatewayBudgetForClass(toolClass, budget);
+	const potentialBytesOverBudget = Math.max(0, sizes.contentBytes - budgetBytes);
 	const completeness = isTruncated(event.details) ? "upstream-truncated" : "unknown";
+	const delivery = options.delivery ?? {
+		representation: "passthrough" as const,
+		contentBytes: sizes.contentBytes,
+		textBytes: sizes.textBytes,
+	};
 	const observation: ContextGatewayObservation = {
 		version: 1,
 		toolClass,
 		outcome: event.isError === true ? "error" : "success",
+		budgetBytes,
 		source: {
 			kind: "tool-result-boundary",
 			completeness,
@@ -231,13 +283,10 @@ export function observeToolResult(
 			detailsBytes,
 		},
 		view: { kind: "text-content", textBytes: sizes.textBytes },
-		delivery: {
-			representation: "passthrough",
-			contentBytes: sizes.contentBytes,
-			textBytes: sizes.textBytes,
-		},
-		overBudget: sizes.contentBytes > maxResultBytes,
+		delivery,
+		overBudget: sizes.contentBytes > budgetBytes,
 		potentialBytesOverBudget,
+		actualBytesSaved: Math.max(0, sizes.contentBytes - delivery.contentBytes),
 	};
 	if (toolClass === "shell") {
 		const parsed = parseTestBuildOutput({
@@ -246,7 +295,11 @@ export function observeToolResult(
 			upstreamTruncated: completeness === "upstream-truncated",
 		});
 		const commandScope = options.shellCommandScope ?? "unknown";
-		const prospective = planProspectiveTestOutputDelivery(parsed, maxResultBytes, { commandScope });
+		const prospective = planProspectiveTestOutputDelivery(
+			parsed,
+			options.maxInlineBytes ?? budgetBytes,
+			{ commandScope },
+		);
 		observation.testOutput = {
 			parserVersion: 1,
 			classification: parsed.classification,
@@ -268,8 +321,10 @@ export class ContextGatewayTelemetry {
 	private byClass: Partial<Record<ContextGatewayToolClass, ContextGatewayClassTelemetry>> = {};
 	private bindings = new Map<string, CallBinding>();
 	private seenInputFingerprints = new Set<string>();
+	private seenReadSourceFingerprints = new Set<string>();
 	private unboundResults = 0;
 	private repeatCandidateCount = 0;
+	private sameSourceDifferentRangeCount = 0;
 	private retrievalCalls = 0;
 	private nativePolicy: ContextGatewayNativePolicyTelemetry = {
 		results: 0,
@@ -286,27 +341,39 @@ export class ContextGatewayTelemetry {
 		if (normalizedToolName === "artifact_read" || normalizedToolName === "artifact_search") {
 			this.retrievalCalls += 1;
 		}
-		const fingerprint = normalizedToolName === "read"
-			? inputFingerprint(event.toolName, event.input)
-			: undefined;
+		const readFingerprint = normalizedToolName === "read" ? contextGatewayReadIdentity(event.input) : {};
+		const fingerprint = readFingerprint.exact;
 		if (fingerprint) {
 			if (this.seenInputFingerprints.has(fingerprint)) this.repeatCandidateCount += 1;
-			else this.seenInputFingerprints.add(fingerprint);
+			else {
+				if (readFingerprint.source && this.seenReadSourceFingerprints.has(readFingerprint.source)) {
+					this.sameSourceDifferentRangeCount += 1;
+				}
+				this.seenInputFingerprints.add(fingerprint);
+			}
 		}
+		if (readFingerprint.source) this.seenReadSourceFingerprints.add(readFingerprint.source);
+		const toolClass = classifyContextGatewayTool(event.toolName);
 		this.bindings.set(event.toolCallId, {
-			toolClass: classifyContextGatewayTool(event.toolName),
+			toolClass,
 			inputFingerprint: fingerprint,
-			...(classifyContextGatewayTool(event.toolName) === "shell"
-				? { shellCommandScope: shellCommandScope(event.input) }
+			readSourceFingerprint: readFingerprint.source,
+			...(toolClass === "shell"
+				? { shellCommandScope: classifyShellCommand(event.input).scope }
 				: {}),
 		});
 	}
 
-	recordToolResult(event: ToolResultLike, maxResultBytes: number): ContextGatewayObservation {
+	recordToolResult(
+		event: ToolResultLike,
+		budget: number | ContextGatewayBudgets,
+		options: { delivery?: { representation: "passthrough" | "test-build-compact"; contentBytes: number; textBytes: number }; maxInlineBytes?: number } = {},
+	): ContextGatewayObservation {
 		const binding = typeof event.toolCallId === "string" ? this.bindings.get(event.toolCallId) : undefined;
-		const observation = observeToolResult(event, maxResultBytes, {
+		const observation = observeToolResult(event, budget, {
 			...(binding ? { toolClass: binding.toolClass } : {}),
 			...(binding?.shellCommandScope ? { shellCommandScope: binding.shellCommandScope } : {}),
+			...options,
 		});
 		if (typeof event.toolCallId !== "string" || !binding) {
 			this.unboundResults += 1;
@@ -357,8 +424,8 @@ export class ContextGatewayTelemetry {
 	}
 
 	/** Backward-compatible convenience for observation-only callers without a tool_call event. */
-	record(event: ToolResultLike, maxResultBytes: number): ContextGatewayObservation {
-		const observation = observeToolResult(event, maxResultBytes);
+	record(event: ToolResultLike, budget: number | ContextGatewayBudgets): ContextGatewayObservation {
+		const observation = observeToolResult(event, budget);
 		this.aggregateObservation(event, observation);
 		return observation;
 	}
@@ -368,8 +435,10 @@ export class ContextGatewayTelemetry {
 		this.byClass = {};
 		this.bindings.clear();
 		this.seenInputFingerprints.clear();
+		this.seenReadSourceFingerprints.clear();
 		this.unboundResults = 0;
 		this.repeatCandidateCount = 0;
+		this.sameSourceDifferentRangeCount = 0;
 		this.retrievalCalls = 0;
 		this.nativePolicy = { results: 0, refusals: 0, fullOverrides: 0, byReason: {} };
 		this.testOutput = emptyTestOutputTelemetry();
@@ -383,6 +452,7 @@ export class ContextGatewayTelemetry {
 			pendingCalls: this.bindings.size,
 			unboundResults: this.unboundResults,
 			repeatCandidateCount: this.repeatCandidateCount,
+			sameSourceDifferentRangeCount: this.sameSourceDifferentRangeCount,
 			retrievalCalls: this.retrievalCalls,
 			nativePolicy: {
 				...this.nativePolicy,
@@ -404,12 +474,15 @@ export class ContextGatewayTelemetry {
 		target.results += 1;
 		if (observation.outcome === "error") target.errors += 1;
 		target.contentBytes += observation.source.contentBytes;
+		target.deliveredContentBytes += observation.delivery.contentBytes;
 		target.textBytes += observation.source.textBytes;
 		target.imageBytes += observation.source.imageBytes;
 		target.detailsBytes += observation.source.detailsBytes;
 		if (observation.source.completeness === "upstream-truncated") target.upstreamTruncatedResults += 1;
 		if (observation.overBudget) target.overBudgetResults += 1;
 		target.potentialBytesOverBudget += observation.potentialBytesOverBudget;
+		if (observation.delivery.representation !== "passthrough") target.enforcedResults += 1;
+		target.actualBytesSaved += observation.actualBytesSaved;
 	}
 }
 

package/external/pi-tools-suite/src/context-gateway/types.ts

@@ -1,6 +1,6 @@
 export type ContextGatewayMode = "off" | "observe" | "enforce";
 
-export type ContextGatewayEffectiveMode = Exclude<ContextGatewayMode, "enforce">;
+export type ContextGatewayEffectiveMode = ContextGatewayMode;
 
 export interface ContextGatewayBudgets {
 	maxInlineBytes: number;
@@ -10,7 +10,7 @@ export interface ContextGatewayBudgets {
 	maxSearchMatches: number;
 }
 
-/** Parsed layered config. `enforce` remains a valid requested value so doctor can refuse it explicitly. */
+/** Parsed layered config. `enforce` is selective and fail-open for unsupported result classes. */
 export interface ContextGatewayResolvedConfig {
 	mode: ContextGatewayMode;
 	budgets: ContextGatewayBudgets;
@@ -48,7 +48,7 @@ export interface ContextGatewayObservedView {
 }
 
 export interface ContextGatewayObservedDelivery {
-	representation: "passthrough";
+	representation: "passthrough" | "test-build-compact";
 	contentBytes: number;
 	textBytes: number;
 }
@@ -81,11 +81,13 @@ export interface ContextGatewayObservation {
 	version: 1;
 	toolClass: ContextGatewayToolClass;
 	outcome: ContextGatewayExecutionOutcome;
+	budgetBytes: number;
 	source: ContextGatewayObservedSource;
 	view: ContextGatewayObservedView;
 	delivery: ContextGatewayObservedDelivery;
 	overBudget: boolean;
 	potentialBytesOverBudget: number;
+	actualBytesSaved: number;
 	testOutput?: ContextGatewayTestOutputObservation;
 }
 
@@ -93,12 +95,15 @@ export interface ContextGatewayClassTelemetry {
 	results: number;
 	errors: number;
 	contentBytes: number;
+	deliveredContentBytes: number;
 	textBytes: number;
 	imageBytes: number;
 	detailsBytes: number;
 	upstreamTruncatedResults: number;
 	overBudgetResults: number;
 	potentialBytesOverBudget: number;
+	enforcedResults: number;
+	actualBytesSaved: number;
 }
 
 export type ContextGatewayNativePolicyReason =
@@ -134,6 +139,7 @@ export interface ContextGatewayTelemetrySnapshot extends ContextGatewayClassTele
 	pendingCalls: number;
 	unboundResults: number;
 	repeatCandidateCount: number;
+	sameSourceDifferentRangeCount: number;
 	retrievalCalls: number;
 	nativePolicy: ContextGatewayNativePolicyTelemetry;
 	testOutput: ContextGatewayTestOutputTelemetry;

package/external/pi-tools-suite/src/context-inventory.ts

@@ -0,0 +1,99 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	currentModelRef,
+	filterSubagentConfigForParentModel,
+	loadSubagentConfig,
+} from "./async-subagents/lib.js";
+import { publishRpcSessionState } from "./lib/rpc-session-state.js";
+
+export const CONTEXT_INVENTORY_EVENT = "pi-tools-suite:context-inventory";
+
+export interface ContextInventoryState {
+	version: 1;
+	reason?: "startup" | "reload" | "new" | "resume" | "fork" | "model_select";
+	sessionId?: string;
+	sessionFile?: string;
+	model?: string;
+	thinking?: string;
+	tools: string[];
+	skills: string[];
+	agents?: string[];
+}
+
+export function createContextInventoryState(
+	pi: Pick<ExtensionAPI, "getActiveTools" | "getCommands">,
+	ctx: Pick<ExtensionContext, "cwd" | "model" | "sessionManager">,
+	reason?: ContextInventoryState["reason"],
+): ContextInventoryState {
+	const tools = unique(pi.getActiveTools());
+	const skillsReadable = tools.includes("read") || tools.includes("bash");
+	const skills = skillsReadable
+		? unique(pi.getCommands()
+			.filter((command) => command.source === "skill")
+			.map((command) => command.name.replace(/^skill:/u, "")))
+			.sort(compareText)
+		: [];
+	const model = currentModelRef(ctx.model);
+	const thinking = typeof (ctx as { thinkingLevel?: unknown }).thinkingLevel === "string"
+		? (ctx as { thinkingLevel?: string }).thinkingLevel?.trim() || undefined
+		: undefined;
+	const agents = tools.includes("subagents") ? effectiveAgentTypes(ctx.cwd, model) : [];
+	const sessionId = safeSessionId(ctx.sessionManager);
+	const sessionFile = safeSessionFile(ctx.sessionManager);
+	return {
+		version: 1,
+		...(reason ? { reason } : {}),
+		...(sessionId ? { sessionId } : {}),
+		...(sessionFile ? { sessionFile } : {}),
+		...(model ? { model } : {}),
+		...(thinking ? { thinking } : {}),
+		tools,
+		skills,
+		...(agents === undefined ? {} : { agents }),
+	};
+}
+
+export function publishContextInventoryState(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	reason?: ContextInventoryState["reason"],
+): void {
+	const state = createContextInventoryState(pi, ctx, reason);
+	pi.events?.emit?.(CONTEXT_INVENTORY_EVENT, state);
+	publishRpcSessionState(ctx, CONTEXT_INVENTORY_EVENT, state);
+}
+
+function effectiveAgentTypes(cwd: string, model: string | undefined): string[] | undefined {
+	try {
+		const config = filterSubagentConfigForParentModel(loadSubagentConfig(cwd), model);
+		return Object.keys(config.types).sort(compareText);
+	} catch {
+		return undefined;
+	}
+}
+
+function safeSessionId(sessionManager: ExtensionContext["sessionManager"]): string | undefined {
+	try {
+		const sessionId = sessionManager.getSessionId();
+		return sessionId?.trim() || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function safeSessionFile(sessionManager: ExtensionContext["sessionManager"]): string | undefined {
+	try {
+		const sessionFile = sessionManager.getSessionFile();
+		return sessionFile?.trim() || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function unique(values: readonly string[]): string[] {
+	return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+function compareText(left: string, right: string): number {
+	return left.localeCompare(right);
+}