pi-ui-extend 1.0.41 → 1.0.45

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

@@ -1,47 +1,63 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { classifyShellCommand, type ShellCommandClassification } from "../shell-command-policy.js";
 
 import {
-	CONTEXT_GATEWAY_ENFORCE_UNAVAILABLE,
+	contextGatewayAccountingLogDrain,
+	contextGatewayAccountingLogEnabled,
+	writeContextGatewayAccountingLog,
+} from "./accounting-log.js";
+import {
+	contextGatewayBudgetForClass,
 	loadContextGatewayConfig,
 } from "./config.js";
-import { ContextGatewayTelemetry } from "./telemetry.js";
+import { ContextGatewayEfficiencyTracker } from "./efficiency.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 {
 	loadConfig?: () => ContextGatewayResolvedConfig;
 	telemetry?: ContextGatewayTelemetry;
+	efficiency?: ContextGatewayEfficiencyTracker;
 }
 
 export interface RegisteredContextGateway extends ContextGatewayRuntimeState {
+	readonly efficiency: ContextGatewayEfficiencyTracker;
 	setRuntimeMode(mode: ContextGatewayMode): { ok: boolean; message: string };
 }
 
 function formatStatus(runtime: RegisteredContextGateway): string {
 	const telemetry = runtime.telemetry.snapshot();
+	const efficiency = runtime.efficiency.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}.`,
+		`Efficiency gross≈${efficiency.grossEstimatedTokensSaved} tokens/${efficiency.grossBytesSaved} bytes, retrieval tax≈${efficiency.retrievalEstimatedTokens} tokens/${efficiency.retrievalBytes} bytes, conservative net≈${efficiency.conservativeNetEstimatedTokens} tokens/${efficiency.conservativeNetBytes} bytes.`,
+		`Provider attempts=${efficiency.providerAttempts}, completions=${efficiency.providerCompletions}, input=${efficiency.providerInputTokens}, cacheRead=${efficiency.providerCacheReadTokens}, cacheWrite=${efficiency.providerCacheWriteTokens}, output=${efficiency.providerOutputTokens}, total=${efficiency.providerTotalTokens}.`,
 	].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; over-budget web_search/web_fetch with structured raw details=bounded recoverable compact; unsupported/unsafe results remain 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.",
+		`Accounting log: ${contextGatewayAccountingLogEnabled(runtime.config) ? "enabled" : "disabled"}; scalar-only JSONL with bounded rotation, no result bodies, paths, or tool arguments.`,
 	];
-	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");
 }
@@ -56,13 +72,48 @@ export function registerContextGateway(
 ): RegisteredContextGateway {
 	const config = (options.loadConfig ?? (() => loadContextGatewayConfig()))();
 	const telemetry = options.telemetry ?? new ContextGatewayTelemetry();
+	const efficiency = options.efficiency ?? new ContextGatewayEfficiencyTracker();
 	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 runtimeId = randomUUID();
+	let accountingEpoch = 0;
+	let accountingEpochStartedAt = Date.now();
+	let accountingEpochActive = false;
+
+	const writeAccounting = (event: string, details: Record<string, unknown> = {}): void => {
+		writeContextGatewayAccountingLog(config, event, {
+			runtimeId,
+			sessionEpoch: accountingEpoch,
+			mode: effectiveMode,
+			...details,
+		});
+	};
+
+	const accountingSummary = (): Record<string, unknown> => ({
+		durationMs: Math.max(0, Date.now() - accountingEpochStartedAt),
+		totals: efficiency.snapshot(),
+	});
+
+	const finalizeAccountingEpoch = (reason: string): void => {
+		if (!accountingEpochActive || effectiveMode === "off") return;
+		writeAccounting("session.summary", { reason, ...accountingSummary() });
+		accountingEpochActive = false;
+	};
+
+	const beginAccountingEpoch = (reason: string): void => {
+		efficiency.reset();
+		accountingEpoch += 1;
+		accountingEpochStartedAt = Date.now();
+		accountingEpochActive = effectiveMode !== "off";
+		if (accountingEpochActive) writeAccounting("session.start", { reason });
+	};
 
 	const resetRuntimeTelemetry = (): void => {
 		inFlightToolCalls.clear();
 		telemetry.reset();
+		efficiency.clearTransientBindings();
 	};
 
 	const runtime: RegisteredContextGateway = {
@@ -70,55 +121,182 @@ export function registerContextGateway(
 		get effectiveMode() { return effectiveMode; },
 		config,
 		telemetry,
+		efficiency,
 		setRuntimeMode(mode) {
-			if (mode === "enforce") {
-				return { ok: false, message: CONTEXT_GATEWAY_ENFORCE_UNAVAILABLE };
-			}
 			if (mode !== effectiveMode && inFlightToolCalls.size > 0) {
 				return {
 					ok: false,
 					message: `Context Gateway mode change requires a safe boundary; ${inFlightToolCalls.size} tool call(s) are still in flight.`,
 				};
 			}
+			const previousMode = effectiveMode;
+			if (previousMode !== mode) finalizeAccountingEpoch("mode-change");
 			requestedMode = mode;
 			effectiveMode = mode;
 			telemetry.clearTransientBindings();
+			efficiency.clearTransientBindings();
+			if (previousMode !== mode) {
+				writeContextGatewayAccountingLog(config, "mode.change", {
+					runtimeId,
+					sessionEpoch: accountingEpoch,
+					from: previousMode,
+					to: mode,
+				});
+				beginAccountingEpoch("mode-change");
+			}
 			return { ok: true, message: `Context Gateway runtime mode set to ${mode}; config was not changed.` };
 		},
 	};
 
 	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);
+			const accountingCall = efficiency.recordToolCall(event);
+			if (accountingCall) writeAccounting("tool.call", { ...accountingCall });
+		}
 		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,
+					toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : undefined,
+					toolClass: binding.toolClass,
+					shell: binding.shell,
+					budgetBytes: classBudget,
+					maxInlineBytes: Math.min(
+						config.budgets.maxInlineBytes,
+						classBudget,
+					),
+				})
+				: undefined;
+			const observation = telemetry.recordToolResult(event, config.budgets, {
+				maxInlineBytes: config.budgets.maxInlineBytes,
+				...(enforcement ? {
+					delivery: {
+						representation: enforcement.representation,
+						contentBytes: enforcement.contentBytes,
+						textBytes: enforcement.textBytes,
+					},
+				} : {}),
+			});
+			const accountingResult = efficiency.recordToolResult(
+				event,
+				observation,
+				enforcement?.content ?? event.content,
+			);
+			if (accountingResult) {
+				const efficiencySnapshot = efficiency.snapshot();
+				writeAccounting("tool.result", {
+					...accountingResult,
+					cumulative: {
+						grossBytesSaved: efficiencySnapshot.grossBytesSaved,
+						grossEstimatedTokensSaved: efficiencySnapshot.grossEstimatedTokensSaved,
+						retrievalBytes: efficiencySnapshot.retrievalBytes,
+						retrievalEstimatedTokens: efficiencySnapshot.retrievalEstimatedTokens,
+						conservativeNetBytes: efficiencySnapshot.conservativeNetBytes,
+						conservativeNetEstimatedTokens: efficiencySnapshot.conservativeNetEstimatedTokens,
+					},
+				});
+			}
+			if (enforcement && enforcement.representation !== "passthrough") {
+				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);
 		}
 		return undefined;
 	});
 
+	pi.on("before_provider_request", async (_event, ctx) => {
+		if (effectiveMode === "off") return undefined;
+		const attempt = efficiency.recordProviderAttempt();
+		const model = (ctx as any)?.model;
+		writeAccounting("provider.request", {
+			attempt,
+			provider: typeof model?.provider === "string" ? model.provider : undefined,
+			model: typeof model?.id === "string" ? model.id : undefined,
+		});
+		return undefined;
+	});
+
+	pi.on("message_end", async (event) => {
+		if (effectiveMode === "off" || event.message?.role !== "assistant") return;
+		const completion = efficiency.recordProviderCompletion(event.message as any);
+		const snapshot = efficiency.snapshot();
+		writeAccounting("provider.completion", {
+			...completion,
+			cumulative: {
+				providerInputTokens: snapshot.providerInputTokens,
+				providerOutputTokens: snapshot.providerOutputTokens,
+				providerCacheReadTokens: snapshot.providerCacheReadTokens,
+				providerCacheWriteTokens: snapshot.providerCacheWriteTokens,
+				providerTotalTokens: snapshot.providerTotalTokens,
+				providerCost: snapshot.providerCost,
+				grossEstimatedTokensSaved: snapshot.grossEstimatedTokensSaved,
+				retrievalEstimatedTokens: snapshot.retrievalEstimatedTokens,
+				conservativeNetEstimatedTokens: snapshot.conservativeNetEstimatedTokens,
+			},
+		});
+	});
+
 	pi.on("session_start", async () => {
+		finalizeAccountingEpoch("session-start-reset");
 		resetRuntimeTelemetry();
+		beginAccountingEpoch("session-start");
 		return undefined;
 	});
 
 	pi.on("session_tree", async () => {
+		finalizeAccountingEpoch("session-tree");
 		resetRuntimeTelemetry();
+		beginAccountingEpoch("session-tree");
 		return undefined;
 	});
 
 	pi.on("session_shutdown", async () => {
+		finalizeAccountingEpoch("session-shutdown");
 		resetRuntimeTelemetry();
+		efficiency.reset();
+		accountingEpochActive = false;
+		await contextGatewayAccountingLogDrain();
 		return undefined;
 	});
 
 	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 +305,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") {
@@ -152,7 +330,16 @@ export default function contextGatewayExtension(pi: ExtensionAPI): void {
 }
 
 export { accountContextGatewayParts } from "./accounting.js";
+export {
+	contextGatewayAccountingLogDrain,
+	contextGatewayAccountingLogEnabled,
+	contextGatewayAccountingLogMaxBackups,
+	contextGatewayAccountingLogMaxBytes,
+	contextGatewayAccountingLogPath,
+	writeContextGatewayAccountingLog,
+} from "./accounting-log.js";
 export { loadContextGatewayConfig } from "./config.js";
+export { ContextGatewayEfficiencyTracker, estimateContextGatewayTokens } from "./efficiency.js";
 export { normalizeRedundantTruncationMetadata } from "./metadata-normalization.js";
 export { STORELESS_CAPABILITIES, storelessCapability } from "./storeless-capabilities.js";
 export { parseTestBuildOutput, planProspectiveTestOutputDelivery } from "./test-output-parser.js";

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" | "raw-session-recoverable-compact" | "none";
 
 export interface StorelessCapabilityEntry {
 	surface:
@@ -13,7 +13,7 @@ export interface StorelessCapabilityEntry {
 		| "mcp-direct";
 	status: StorelessCapabilityStatus;
 	strategy: StorelessCapabilityStrategy;
-	lifetime: "current-result" | "producer-managed" | "visual-message" | "none";
+	lifetime: "current-result" | "producer-managed" | "raw-session" | "visual-message" | "none";
 	reason: string;
 }
 
@@ -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",
@@ -41,9 +41,9 @@ export const STORELESS_CAPABILITIES: readonly StorelessCapabilityEntry[] = Objec
 	{
 		surface: "web-document",
 		status: "limited",
-		strategy: "native-passthrough",
-		lifetime: "current-result",
-		reason: "Existing web tools own fetch, URL/provider metadata and truncation. Storeless Gateway does not refetch, archive, or claim stable pagination of omitted content.",
+		strategy: "raw-session-recoverable-compact",
+		lifetime: "raw-session",
+		reason: "In enforce mode, over-budget web_search/web_fetch results are compacted only when the producer supplied full structured details. Those raw details remain in the session toolResult and are recoverable by toolCallId through session-recovery; unsupported web shapes remain passthrough.",
 	},
 	{
 		surface: "structured-json",

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" | "web-recoverable-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" | "web-recoverable-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;
 	}
 }