pi-ui-extend 1.0.42 → 1.0.45

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

@@ -4,6 +4,7 @@ import { parse as parseJsonc } from "jsonc-parser";
 
 import { getPiToolsSuiteUserConfigPath } from "../config.js";
 import type {
+	ContextGatewayAccountingLogConfig,
 	ContextGatewayBudgets,
 	ContextGatewayMode,
 	ContextGatewayResolvedConfig,
@@ -18,6 +19,12 @@ export const DEFAULT_CONTEXT_GATEWAY_BUDGETS: Readonly<ContextGatewayBudgets> =
 	maxSearchMatches: 12,
 });
 
+export const DEFAULT_CONTEXT_GATEWAY_ACCOUNTING_LOG: Readonly<ContextGatewayAccountingLogConfig> = Object.freeze({
+	enabled: true,
+	maxBytes: 5 * 1024 * 1024,
+	maxBackups: 3,
+});
+
 export function contextGatewayBudgetForClass(
 	toolClass: ContextGatewayToolClass,
 	budgets: ContextGatewayBudgets,
@@ -66,6 +73,24 @@ function parseMode(value: unknown): ContextGatewayMode | undefined {
 	return MODES.has(normalized) ? normalized : undefined;
 }
 
+function parseBoolean(value: unknown): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+
+function parseBooleanEnv(value: string): boolean | undefined {
+	const normalized = value.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(normalized)) return true;
+	if (["0", "false", "no", "off"].includes(normalized)) return false;
+	return undefined;
+}
+
+function parsePositiveIntegerEnv(value: string): number | undefined {
+	const normalized = value.trim();
+	if (!/^\d+$/.test(normalized)) return undefined;
+	const parsed = Number(normalized);
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 function mergeBudget(
 	budgets: ContextGatewayBudgets,
 	issues: string[],
@@ -88,6 +113,7 @@ export function loadContextGatewayConfig(
 ): ContextGatewayResolvedConfig {
 	let mode: ContextGatewayMode = "off";
 	const budgets: ContextGatewayBudgets = { ...DEFAULT_CONTEXT_GATEWAY_BUDGETS };
+	const accountingLog: ContextGatewayAccountingLogConfig = { ...DEFAULT_CONTEXT_GATEWAY_ACCOUNTING_LOG };
 	const issues: string[] = [];
 
 	const layers = [getPiToolsSuiteUserConfigPath(homeDir)];
@@ -108,6 +134,29 @@ export function loadContextGatewayConfig(
 				mergeBudget(budgets, issues, key, section.budgets[key]);
 			}
 		}
+		if (isRecord(section.accountingLog)) {
+			if (Object.prototype.hasOwnProperty.call(section.accountingLog, "enabled")) {
+				const enabled = parseBoolean(section.accountingLog.enabled);
+				if (enabled !== undefined) accountingLog.enabled = enabled;
+				else issues.push(`contextGateway.accountingLog.enabled must be boolean; keeping ${accountingLog.enabled}.`);
+			}
+			const maxBytes = section.accountingLog.maxBytes;
+			if (maxBytes !== undefined) {
+				if (typeof maxBytes === "number" && Number.isSafeInteger(maxBytes) && maxBytes > 0 && maxBytes <= MAX_BYTE_BUDGET) {
+					accountingLog.maxBytes = maxBytes;
+				} else {
+					issues.push(`contextGateway.accountingLog.maxBytes must be an integer in 1..${MAX_BYTE_BUDGET}; keeping ${accountingLog.maxBytes}.`);
+				}
+			}
+			const maxBackups = section.accountingLog.maxBackups;
+			if (maxBackups !== undefined) {
+				if (typeof maxBackups === "number" && Number.isSafeInteger(maxBackups) && maxBackups >= 1 && maxBackups <= 100) {
+					accountingLog.maxBackups = maxBackups;
+				} else {
+					issues.push(`contextGateway.accountingLog.maxBackups must be an integer in 1..100; keeping ${accountingLog.maxBackups}.`);
+				}
+			}
+		}
 	}
 
 	if (env.PI_CONTEXT_GATEWAY_MODE !== undefined) {
@@ -116,5 +165,21 @@ export function loadContextGatewayConfig(
 		else issues.push("PI_CONTEXT_GATEWAY_MODE must be off, observe, or enforce; ignoring it.");
 	}
 
-	return { mode, budgets, issues };
+	if (env.PI_CONTEXT_GATEWAY_ACCOUNTING_LOG_ENABLED !== undefined) {
+		const enabled = parseBooleanEnv(env.PI_CONTEXT_GATEWAY_ACCOUNTING_LOG_ENABLED);
+		if (enabled !== undefined) accountingLog.enabled = enabled;
+		else issues.push("PI_CONTEXT_GATEWAY_ACCOUNTING_LOG_ENABLED must be true or false; ignoring it.");
+	}
+	if (env.PI_CONTEXT_GATEWAY_ACCOUNTING_MAX_BYTES !== undefined) {
+		const maxBytes = parsePositiveIntegerEnv(env.PI_CONTEXT_GATEWAY_ACCOUNTING_MAX_BYTES);
+		if (maxBytes !== undefined && maxBytes <= MAX_BYTE_BUDGET) accountingLog.maxBytes = maxBytes;
+		else issues.push(`PI_CONTEXT_GATEWAY_ACCOUNTING_MAX_BYTES must be an integer in 1..${MAX_BYTE_BUDGET}; ignoring it.`);
+	}
+	if (env.PI_CONTEXT_GATEWAY_ACCOUNTING_MAX_BACKUPS !== undefined) {
+		const maxBackups = parsePositiveIntegerEnv(env.PI_CONTEXT_GATEWAY_ACCOUNTING_MAX_BACKUPS);
+		if (maxBackups !== undefined && maxBackups <= 100) accountingLog.maxBackups = maxBackups;
+		else issues.push("PI_CONTEXT_GATEWAY_ACCOUNTING_MAX_BACKUPS must be an integer in 1..100; ignoring it.");
+	}
+
+	return { mode, budgets, accountingLog, issues };
 }

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

@@ -0,0 +1,414 @@
+import { createRequire } from "node:module";
+
+import { contextGatewayReadIdentity } from "./telemetry.js";
+import type { ContextGatewayObservation } from "./types.js";
+
+type ToolCallLike = {
+	toolCallId?: unknown;
+	toolName?: unknown;
+	input?: unknown;
+};
+
+type ToolResultLike = {
+	toolCallId?: unknown;
+	toolName?: unknown;
+	content?: unknown;
+	details?: unknown;
+	isError?: unknown;
+};
+
+type AssistantMessageLike = {
+	provider?: unknown;
+	model?: unknown;
+	stopReason?: unknown;
+	usage?: unknown;
+};
+
+export type ContextGatewayRetrievalKind =
+	| "artifact"
+	| "session-recovery"
+	| "repeat-read"
+	| "read-continuation";
+
+export interface ContextGatewayEfficiencySnapshot {
+	toolCalls: number;
+	toolResults: number;
+	enforcedResults: number;
+	sourceContentBytes: number;
+	deliveredContentBytes: number;
+	grossBytesSaved: number;
+	grossEstimatedTokensSaved: number;
+	retrievalCalls: number;
+	retrievalResults: number;
+	retrievalBytes: number;
+	retrievalEstimatedTokens: number;
+	conservativeNetBytes: number;
+	conservativeNetEstimatedTokens: number;
+	providerAttempts: number;
+	providerCompletions: number;
+	providerInputTokens: number;
+	providerOutputTokens: number;
+	providerCacheReadTokens: number;
+	providerCacheWriteTokens: number;
+	providerTotalTokens: number;
+	providerCost: number;
+	byToolClass: Partial<Record<ContextGatewayObservation["toolClass"], {
+		results: number;
+		enforcedResults: number;
+		sourceContentBytes: number;
+		deliveredContentBytes: number;
+		grossBytesSaved: number;
+		grossEstimatedTokensSaved: number;
+	}>>;
+	byRetrievalKind: Partial<Record<ContextGatewayRetrievalKind, {
+		calls: number;
+		results: number;
+		bytes: number;
+		estimatedTokens: number;
+	}>>;
+}
+
+export interface ContextGatewayEfficiencyToolCall {
+	callRef: string;
+	toolName: string;
+	retrievalKind?: ContextGatewayRetrievalKind;
+}
+
+export interface ContextGatewayEfficiencyToolResult extends ContextGatewayEfficiencyToolCall {
+	toolClass: ContextGatewayObservation["toolClass"];
+	outcome: ContextGatewayObservation["outcome"];
+	representation: ContextGatewayObservation["delivery"]["representation"];
+	overBudget: boolean;
+	potentialBytesOverBudget: number;
+	sourceContentBytes: number;
+	deliveredContentBytes: number;
+	sourceEstimatedTokens: number;
+	deliveredEstimatedTokens: number;
+	grossBytesSaved: number;
+	grossEstimatedTokensSaved: number;
+	retrievalBytes: number;
+	retrievalEstimatedTokens: number;
+}
+
+export interface ContextGatewayProviderCompletion {
+	provider?: string;
+	model?: string;
+	stopReason?: string;
+	attemptsSincePreviousCompletion: number;
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		totalTokens: number;
+		cost: number;
+	};
+}
+
+type BoundCall = ContextGatewayEfficiencyToolCall;
+type TokenCounter = ((text: string) => number) | undefined;
+
+const MAX_TRACKED_BINDINGS = 4_096;
+const MAX_TRACKED_READ_IDENTITIES = 4_096;
+const MAX_TRACKED_ARTIFACT_SOURCES = 4_096;
+
+let optionalTokenCounter: TokenCounter | null = null;
+
+function loadOptionalTokenCounter(): TokenCounter {
+	if (optionalTokenCounter !== null) return optionalTokenCounter;
+	try {
+		const require = createRequire(import.meta.url);
+		const tokenizer = require("@anthropic-ai/tokenizer") as {
+			countTokens?: unknown;
+			default?: { countTokens?: unknown };
+		};
+		const counter = tokenizer.countTokens ?? tokenizer.default?.countTokens;
+		optionalTokenCounter = typeof counter === "function" ? counter as (text: string) => number : undefined;
+	} catch {
+		optionalTokenCounter = undefined;
+	}
+	return optionalTokenCounter;
+}
+
+export function estimateContextGatewayTokens(text: string): number {
+	if (!text) return 0;
+	const counter = loadOptionalTokenCounter();
+	if (counter) {
+		try {
+			const counted = counter(text);
+			if (Number.isFinite(counted)) return Math.max(0, Math.round(counted));
+		} catch {
+			// Fall through to the same cheap approximation used when no tokenizer is installed.
+		}
+	}
+	return Math.max(0, Math.round(text.length / 4));
+}
+
+function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	let text = "";
+	for (const part of content) {
+		if (!part || typeof part !== "object" || Array.isArray(part)) continue;
+		const block = part as Record<string, unknown>;
+		if (block.type === "text" && typeof block.text === "string") text += block.text;
+	}
+	return text;
+}
+
+function finiteNonNegative(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+function assistantUsage(message: AssistantMessageLike): ContextGatewayProviderCompletion["usage"] {
+	const usage = message.usage && typeof message.usage === "object" && !Array.isArray(message.usage)
+		? message.usage as Record<string, unknown>
+		: {};
+	const costValue = usage.cost && typeof usage.cost === "object" && !Array.isArray(usage.cost)
+		? finiteNonNegative((usage.cost as Record<string, unknown>).total)
+		: 0;
+	return {
+		input: finiteNonNegative(usage.input),
+		output: finiteNonNegative(usage.output),
+		cacheRead: finiteNonNegative(usage.cacheRead),
+		cacheWrite: finiteNonNegative(usage.cacheWrite),
+		totalTokens: finiteNonNegative(usage.totalTokens),
+		cost: costValue,
+	};
+}
+
+function retrievalKindForToolName(toolName: string): ContextGatewayRetrievalKind | undefined {
+	if (toolName === "artifact_read" || toolName === "artifact_search") return "artifact";
+	if (["session_overview", "session_read_section", "session_search", "session_recovery_context"].includes(toolName)) {
+		return "session-recovery";
+	}
+	return undefined;
+}
+
+function artifactHandlePaths(details: unknown): string[] {
+	if (!details || typeof details !== "object" || Array.isArray(details)) return [];
+	const record = details as Record<string, unknown>;
+	const paths: string[] = [];
+	for (const key of ["fullOutputPath", "artifactPath", "outputPath"]) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim()) paths.push(value);
+	}
+	const artifacts = record.artifacts;
+	if (artifacts && typeof artifacts === "object" && !Array.isArray(artifacts)) {
+		for (const value of Object.values(artifacts as Record<string, unknown>)) {
+			if (typeof value === "string" && value.trim()) paths.push(value);
+		}
+	}
+	return paths;
+}
+
+function rememberBounded(set: Set<string>, value: string, maximum: number): void {
+	if (set.delete(value)) {
+		set.add(value);
+		return;
+	}
+	if (set.size >= maximum) {
+		const oldest = set.values().next().value;
+		if (oldest !== undefined) set.delete(oldest);
+	}
+	set.add(value);
+}
+
+function bindBounded(map: Map<string, BoundCall>, key: string, value: BoundCall): void {
+	if (!map.has(key) && map.size >= MAX_TRACKED_BINDINGS) {
+		const oldest = map.keys().next().value;
+		if (oldest !== undefined) map.delete(oldest);
+	}
+	map.set(key, value);
+}
+
+function emptySnapshot(): ContextGatewayEfficiencySnapshot {
+	return {
+		toolCalls: 0,
+		toolResults: 0,
+		enforcedResults: 0,
+		sourceContentBytes: 0,
+		deliveredContentBytes: 0,
+		grossBytesSaved: 0,
+		grossEstimatedTokensSaved: 0,
+		retrievalCalls: 0,
+		retrievalResults: 0,
+		retrievalBytes: 0,
+		retrievalEstimatedTokens: 0,
+		conservativeNetBytes: 0,
+		conservativeNetEstimatedTokens: 0,
+		providerAttempts: 0,
+		providerCompletions: 0,
+		providerInputTokens: 0,
+		providerOutputTokens: 0,
+		providerCacheReadTokens: 0,
+		providerCacheWriteTokens: 0,
+		providerTotalTokens: 0,
+		providerCost: 0,
+		byToolClass: {},
+		byRetrievalKind: {},
+	};
+}
+
+export class ContextGatewayEfficiencyTracker {
+	private totals = emptySnapshot();
+	private bindings = new Map<string, BoundCall>();
+	private seenExactReads = new Set<string>();
+	private seenReadSources = new Set<string>();
+	private artifactReadSources = new Set<string>();
+	private callSequence = 0;
+	private attemptsAtPreviousCompletion = 0;
+
+	recordToolCall(event: ToolCallLike): ContextGatewayEfficiencyToolCall | undefined {
+		if (typeof event.toolCallId !== "string" || typeof event.toolName !== "string") return undefined;
+		const toolName = event.toolName.trim().toLowerCase();
+		let retrievalKind = retrievalKindForToolName(toolName);
+		if (toolName === "read") {
+			const identity = contextGatewayReadIdentity(event.input);
+			if (identity.source && this.artifactReadSources.has(identity.source)) {
+				retrievalKind = "artifact";
+				rememberBounded(this.artifactReadSources, identity.source, MAX_TRACKED_ARTIFACT_SOURCES);
+			}
+			else if (identity.exact && this.seenExactReads.has(identity.exact)) retrievalKind = "repeat-read";
+			else if (identity.source && this.seenReadSources.has(identity.source)) retrievalKind = "read-continuation";
+			if (identity.exact) rememberBounded(this.seenExactReads, identity.exact, MAX_TRACKED_READ_IDENTITIES);
+			if (identity.source) rememberBounded(this.seenReadSources, identity.source, MAX_TRACKED_READ_IDENTITIES);
+		}
+
+		const binding: BoundCall = {
+			callRef: `c${++this.callSequence}`,
+			toolName,
+			...(retrievalKind ? { retrievalKind } : {}),
+		};
+		bindBounded(this.bindings, event.toolCallId, binding);
+		this.totals.toolCalls += 1;
+		if (retrievalKind) {
+			this.totals.retrievalCalls += 1;
+			const counters = this.totals.byRetrievalKind[retrievalKind] ?? { calls: 0, results: 0, bytes: 0, estimatedTokens: 0 };
+			counters.calls += 1;
+			this.totals.byRetrievalKind[retrievalKind] = counters;
+		}
+		return { ...binding };
+	}
+
+	recordToolResult(
+		event: ToolResultLike,
+		observation: ContextGatewayObservation,
+		deliveredContent: unknown = event.content,
+	): ContextGatewayEfficiencyToolResult | undefined {
+		if (typeof event.toolCallId !== "string") return undefined;
+		const binding = this.bindings.get(event.toolCallId);
+		if (!binding) return undefined;
+		this.bindings.delete(event.toolCallId);
+
+		const sourceEstimatedTokens = estimateContextGatewayTokens(contentText(event.content));
+		const deliveredEstimatedTokens = estimateContextGatewayTokens(contentText(deliveredContent));
+		const grossEstimatedTokensSaved = Math.max(0, sourceEstimatedTokens - deliveredEstimatedTokens);
+		const grossBytesSaved = observation.actualBytesSaved;
+		const retrievalBytes = binding.retrievalKind ? observation.delivery.contentBytes : 0;
+		const retrievalEstimatedTokens = binding.retrievalKind ? deliveredEstimatedTokens : 0;
+
+		this.totals.toolResults += 1;
+		this.totals.sourceContentBytes += observation.source.contentBytes;
+		this.totals.deliveredContentBytes += observation.delivery.contentBytes;
+		if (observation.delivery.representation !== "passthrough") this.totals.enforcedResults += 1;
+		this.totals.grossBytesSaved += grossBytesSaved;
+		this.totals.grossEstimatedTokensSaved += grossEstimatedTokensSaved;
+		const classCounters = this.totals.byToolClass[observation.toolClass] ?? {
+			results: 0,
+			enforcedResults: 0,
+			sourceContentBytes: 0,
+			deliveredContentBytes: 0,
+			grossBytesSaved: 0,
+			grossEstimatedTokensSaved: 0,
+		};
+		classCounters.results += 1;
+		if (observation.delivery.representation !== "passthrough") classCounters.enforcedResults += 1;
+		classCounters.sourceContentBytes += observation.source.contentBytes;
+		classCounters.deliveredContentBytes += observation.delivery.contentBytes;
+		classCounters.grossBytesSaved += grossBytesSaved;
+		classCounters.grossEstimatedTokensSaved += grossEstimatedTokensSaved;
+		this.totals.byToolClass[observation.toolClass] = classCounters;
+		if (binding.retrievalKind) {
+			this.totals.retrievalResults += 1;
+			this.totals.retrievalBytes += retrievalBytes;
+			this.totals.retrievalEstimatedTokens += retrievalEstimatedTokens;
+			const counters = this.totals.byRetrievalKind[binding.retrievalKind]
+				?? { calls: 0, results: 0, bytes: 0, estimatedTokens: 0 };
+			counters.results += 1;
+			counters.bytes += retrievalBytes;
+			counters.estimatedTokens += retrievalEstimatedTokens;
+			this.totals.byRetrievalKind[binding.retrievalKind] = counters;
+		}
+		this.refreshNet();
+		for (const artifactPath of artifactHandlePaths(event.details)) {
+			const source = contextGatewayReadIdentity({ path: artifactPath }).source;
+			if (source) rememberBounded(this.artifactReadSources, source, MAX_TRACKED_ARTIFACT_SOURCES);
+		}
+
+		return {
+			...binding,
+			toolClass: observation.toolClass,
+			outcome: observation.outcome,
+			representation: observation.delivery.representation,
+			overBudget: observation.overBudget,
+			potentialBytesOverBudget: observation.potentialBytesOverBudget,
+			sourceContentBytes: observation.source.contentBytes,
+			deliveredContentBytes: observation.delivery.contentBytes,
+			sourceEstimatedTokens,
+			deliveredEstimatedTokens,
+			grossBytesSaved,
+			grossEstimatedTokensSaved,
+			retrievalBytes,
+			retrievalEstimatedTokens,
+		};
+	}
+
+	recordProviderAttempt(): number {
+		this.totals.providerAttempts += 1;
+		return this.totals.providerAttempts;
+	}
+
+	recordProviderCompletion(message: AssistantMessageLike): ContextGatewayProviderCompletion {
+		const usage = assistantUsage(message);
+		this.totals.providerCompletions += 1;
+		this.totals.providerInputTokens += usage.input;
+		this.totals.providerOutputTokens += usage.output;
+		this.totals.providerCacheReadTokens += usage.cacheRead;
+		this.totals.providerCacheWriteTokens += usage.cacheWrite;
+		this.totals.providerTotalTokens += usage.totalTokens;
+		this.totals.providerCost += usage.cost;
+		const attemptsSincePreviousCompletion = this.totals.providerAttempts - this.attemptsAtPreviousCompletion;
+		this.attemptsAtPreviousCompletion = this.totals.providerAttempts;
+		return {
+			...(typeof message.provider === "string" ? { provider: message.provider } : {}),
+			...(typeof message.model === "string" ? { model: message.model } : {}),
+			...(typeof message.stopReason === "string" ? { stopReason: message.stopReason } : {}),
+			attemptsSincePreviousCompletion,
+			usage,
+		};
+	}
+
+	clearTransientBindings(): void {
+		this.bindings.clear();
+	}
+
+	reset(): void {
+		this.totals = emptySnapshot();
+		this.bindings.clear();
+		this.seenExactReads.clear();
+		this.seenReadSources.clear();
+		this.artifactReadSources.clear();
+		this.callSequence = 0;
+		this.attemptsAtPreviousCompletion = 0;
+	}
+
+	snapshot(): ContextGatewayEfficiencySnapshot {
+		return structuredClone(this.totals);
+	}
+
+	private refreshNet(): void {
+		this.totals.conservativeNetBytes = this.totals.grossBytesSaved - this.totals.retrievalBytes;
+		this.totals.conservativeNetEstimatedTokens = this.totals.grossEstimatedTokensSaved - this.totals.retrievalEstimatedTokens;
+	}
+}

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

@@ -5,7 +5,7 @@ import type { ContextGatewayToolClass } from "./types.js";
 type ResultContent = unknown;
 
 export interface ContextGatewayEnforcementPlan {
-	representation: "passthrough" | "test-build-compact";
+	representation: "passthrough" | "test-build-compact" | "web-recoverable-compact";
 	content: ResultContent;
 	sourceContentBytes: number;
 	contentBytes: number;
@@ -40,6 +40,109 @@ function textOnlyContent(content: unknown): boolean {
 			&& typeof (part as Record<string, unknown>).text === "string");
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function boundedTextBytes(text: string, maximumBytes: number): string {
+	const encoder = new TextEncoder();
+	if (encoder.encode(text).byteLength <= maximumBytes) return text;
+	const suffix = "\n… [compact view truncated; full structured result is recoverable from raw session details]";
+	const suffixBytes = encoder.encode(suffix).byteLength;
+	if (maximumBytes <= suffixBytes) {
+		let low = 0;
+		let high = text.length;
+		while (low < high) {
+			const mid = Math.ceil((low + high) / 2);
+			if (encoder.encode(text.slice(0, mid)).byteLength <= maximumBytes) low = mid;
+			else high = mid - 1;
+		}
+		return text.slice(0, low);
+	}
+	const target = Math.max(0, maximumBytes - suffixBytes);
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (encoder.encode(text.slice(0, mid)).byteLength <= target) low = mid;
+		else high = mid - 1;
+	}
+	return `${text.slice(0, low).trimEnd()}${suffix}`;
+}
+
+function boundedProviderTextContent(text: string, maximumBytes: number): {
+	content: Array<{ type: "text"; text: string }>;
+	contentBytes: number;
+	textBytes: number;
+} {
+	const limit = Math.max(1, Math.floor(maximumBytes));
+	let low = 1;
+	let high = limit;
+	let bestText = boundedTextBytes(text, 1);
+	let bestContent = [{ type: "text" as const, text: bestText }];
+	let bestContentBytes = byteLengthJson(bestContent);
+
+	while (low <= high) {
+		const textBudget = Math.floor((low + high) / 2);
+		const candidateText = boundedTextBytes(text, textBudget);
+		const candidateContent = [{ type: "text" as const, text: candidateText }];
+		const candidateBytes = byteLengthJson(candidateContent);
+		if (candidateBytes <= limit) {
+			bestText = candidateText;
+			bestContent = candidateContent;
+			bestContentBytes = candidateBytes;
+			low = textBudget + 1;
+		} else {
+			high = textBudget - 1;
+		}
+	}
+
+	return {
+		content: bestContent,
+		contentBytes: bestContentBytes,
+		textBytes: new TextEncoder().encode(bestText).byteLength,
+	};
+}
+
+function planRecoverableWebCompact(details: unknown, toolCallId: string | undefined, maximumBytes: number): string | undefined {
+	if (!isRecord(details)) return undefined;
+	const recovery = [
+		"[Context Gateway: over-budget web result compacted for provider context.]",
+		"Full structured source is retained in the raw session toolResult.details and can be recovered with session-recovery.",
+		toolCallId ? `Recovery key: toolCallId=${toolCallId}` : undefined,
+	].filter((line): line is string => Boolean(line));
+
+	if (Array.isArray(details.results)) {
+		const results = details.results.filter(isRecord);
+		if (results.length === 0) return undefined;
+		const lines = [...recovery, `Search results: ${results.length}`];
+		for (let index = 0; index < results.length; index++) {
+			const result = results[index]!;
+			const title = typeof result.title === "string" ? result.title : `Result ${index + 1}`;
+			const url = typeof result.url === "string" ? result.url : "";
+			const content = typeof result.content === "string" ? result.content.replace(/\s+/g, " ").trim() : "";
+			lines.push(`${index + 1}. ${title}`);
+			if (url) lines.push(`   URL: ${url}`);
+			if (content) lines.push(`   ${content.slice(0, 900)}${content.length > 900 ? "…" : ""}`);
+		}
+		return boundedTextBytes(lines.join("\n"), maximumBytes);
+	}
+
+	if (typeof details.content === "string") {
+		const title = typeof details.title === "string" ? details.title : "Fetched document";
+		const links = Array.isArray(details.links) ? details.links.filter((link): link is string => typeof link === "string") : [];
+		const lines = [
+			...recovery,
+			`Title: ${title}`,
+			`Content preview: ${details.content.slice(0, Math.max(1_000, maximumBytes))}`,
+			...(links.length > 0 ? ["Links:", ...links.slice(0, 8).map((link) => `  - ${link}`)] : []),
+		];
+		return boundedTextBytes(lines.join("\n"), maximumBytes);
+	}
+
+	return undefined;
+}
+
 function upstreamTruncated(details: unknown): boolean {
 	if (!details || typeof details !== "object" || Array.isArray(details)) return false;
 	const record = details as Record<string, unknown>;
@@ -51,11 +154,12 @@ function upstreamTruncated(details: unknown): boolean {
 
 /**
  * Selective storeless enforcement. It never performs generic truncation.
- * Only recognised, complete, simple test/build output is compacted; every
- * other result stays byte-for-byte passthrough until a recovery contract exists.
+ * Recognised complete test/build output and structured recoverable web results
+ * have explicit compact contracts; other results remain passthrough.
  */
 export function planContextGatewayEnforcement(input: {
 	event: { content?: unknown; details?: unknown; isError?: boolean };
+	toolCallId?: string;
 	toolClass: ContextGatewayToolClass;
 	shell: ShellCommandClassification;
 	budgetBytes: number;
@@ -72,6 +176,22 @@ export function planContextGatewayEnforcement(input: {
 		reason,
 	});
 
+	if (input.toolClass === "web") {
+		if (!textOnlyContent(input.event.content)) return passthrough("non-text-content");
+		if (sourceContentBytes <= input.budgetBytes) return passthrough("within-class-budget");
+		const compactText = planRecoverableWebCompact(input.event.details, input.toolCallId, input.maxInlineBytes);
+		if (!compactText) return passthrough("web-recovery-source-unavailable");
+		const bounded = boundedProviderTextContent(compactText, input.maxInlineBytes);
+		return {
+			representation: "web-recoverable-compact",
+			content: bounded.content,
+			sourceContentBytes,
+			contentBytes: bounded.contentBytes,
+			textBytes: bounded.textBytes,
+			reason: "recoverable-structured-web-details",
+		};
+	}
+
 	if (input.toolClass !== "shell") return passthrough("class-not-enforced");
 	if (input.shell.scope !== "simple" || input.shell.kind !== "test-build") {
 		return passthrough("shell-not-proven-test-build");