@herbertgao/pi-extensions 2026.9.2 → 2026.9.3

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/observation-pack/observation.ts

@@ -0,0 +1,252 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { type FileHandle, lstat, mkdir, open } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { TextContent, ToolResultMessage } from "@earendil-works/pi-ai";
+
+/** Only tool results larger than this participate. */
+export const THRESHOLD_BYTES = 10 * 1024;
+/** Provider requests that still carry the full payload before the placeholder takes over. */
+export const FULL_SENDS = 2;
+/** Placeholder excerpt budget, split evenly between head and tail, whole lines only. */
+export const PLACEHOLDER_EXCERPT_BYTES = 1024;
+
+const CHARS_PER_TOKEN = 4;
+const OBSERVATION_ID_PATTERN = /^obs_[a-f0-9]{24}$/u;
+const READ_OBJECT_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW;
+const CREATE_OBJECT_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+
+/**
+ * Receipts from the evidence-preserving reducer are already a reduction of a
+ * long log. Packing them again would replace verified evidence with an excerpt.
+ */
+const EVIDENCE_REDUCER_RECEIPT_PREFIX = "sol_pi_evidence_receipt_v1";
+
+export interface Observation {
+	readonly id: string;
+	readonly contentHash: string;
+	readonly filePath: string;
+	readonly toolName: string;
+	readonly text: string;
+	readonly bytes: number;
+	readonly lines: number;
+	readonly tokens: number;
+}
+
+export function hash(value: string | Buffer): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+export function estimateTokens(text: string): number {
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export function countLines(text: string): number {
+	if (text.length === 0) return 0;
+	let lines = text.endsWith("\n") ? 0 : 1;
+	for (const character of text) {
+		if (character === "\n") lines += 1;
+	}
+	return lines;
+}
+
+function countBufferLines(buffer: Buffer): number {
+	if (buffer.length === 0) return 0;
+	let lines = buffer[buffer.length - 1] === 0x0a ? 0 : 1;
+	for (const byte of buffer) {
+		if (byte === 0x0a) lines += 1;
+	}
+	return lines;
+}
+
+export function isPureTextResult(message: AgentMessage): message is ToolResultMessage {
+	return (
+		message.role === "toolResult" &&
+		!message.isError &&
+		message.content.length > 0 &&
+		message.content.every((block) => block.type === "text")
+	);
+}
+
+function textFromResult(message: ToolResultMessage): string {
+	return (message.content as TextContent[]).map((block) => block.text).join("\n");
+}
+
+function containsReducerReceipt(text: string): boolean {
+	return text.split("\n").some((line) => line === EVIDENCE_REDUCER_RECEIPT_PREFIX);
+}
+
+/**
+ * Archived payloads live under SoL-Pi's session-derived runtime root.
+ *
+ * They are content addressed inside one session. A resume reuses the same
+ * directory; a fork rebuilds its own object from the unmodified session history.
+ */
+export function observationPath(runtimeRoot: string, id: string): string {
+	return join(runtimeRoot, "observation-pack", "objects", `${id}.txt`);
+}
+
+export function isObservationId(id: string): boolean {
+	return OBSERVATION_ID_PATTERN.test(id);
+}
+
+export function createObservation(message: ToolResultMessage, runtimeRoot: string): Observation | undefined {
+	const text = textFromResult(message);
+	if (containsReducerReceipt(text)) return undefined;
+	const bytes = Buffer.byteLength(text, "utf8");
+	if (bytes <= THRESHOLD_BYTES) return undefined;
+	if (!runtimeRoot) throw new Error("Persistent SoL-Pi runtime directory is unavailable");
+
+	const contentHash = hash(text);
+	const id = `obs_${hash(`${message.toolName}\0${message.toolCallId}\0${contentHash}`).slice(0, 24)}`;
+	return {
+		id,
+		contentHash,
+		filePath: observationPath(runtimeRoot, id),
+		toolName: message.toolName,
+		text,
+		bytes,
+		lines: countLines(text),
+		tokens: estimateTokens(text),
+	};
+}
+
+/**
+ * Write the payload to its content-addressed path, refusing symlinks and
+ * verifying an existing object byte for byte before reusing it.
+ */
+export async function ensureStored(observation: Observation): Promise<void> {
+	const directoryPath = dirname(observation.filePath);
+	await mkdir(directoryPath, { recursive: true, mode: 0o700 });
+	const directoryStats = await lstat(directoryPath);
+	if (!directoryStats.isDirectory() || directoryStats.isSymbolicLink()) {
+		throw new Error(`Observation directory is not a regular directory for ${observation.id}`);
+	}
+
+	let handle: FileHandle | undefined;
+	try {
+		handle = await open(observation.filePath, CREATE_OBJECT_FLAGS, 0o600);
+		await handle.writeFile(observation.text, { encoding: "utf8" });
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") throw error;
+		const existingHandle = await open(observation.filePath, READ_OBJECT_FLAGS);
+		try {
+			const existing = await existingHandle.stat();
+			if (!existing.isFile()) {
+				throw new Error(`Content-addressed observation is not a regular file for ${observation.id}`, { cause: error });
+			}
+			if (existing.size !== observation.bytes) {
+				throw new Error(`Content-addressed observation size mismatch for ${observation.id}`, { cause: error });
+			}
+			const existingContent = await existingHandle.readFile();
+			if (hash(existingContent) !== observation.contentHash) {
+				throw new Error(`Content-addressed observation hash mismatch for ${observation.id}`, { cause: error });
+			}
+		} finally {
+			await existingHandle.close();
+		}
+	} finally {
+		await handle?.close();
+	}
+}
+
+function completeLineExcerpt(text: string, budgetBytes: number, fromEnd: boolean): string {
+	const lines = text.split(/(?<=\n)/);
+	const selected: string[] = [];
+	let selectedBytes = 0;
+	let index = fromEnd ? lines.length - 1 : 0;
+
+	while (index >= 0 && index < lines.length) {
+		const line = lines[index];
+		if (line === undefined) break;
+		const lineBytes = Buffer.byteLength(line, "utf8");
+		if (selectedBytes + lineBytes > budgetBytes) break;
+		if (fromEnd) selected.unshift(line);
+		else selected.push(line);
+		selectedBytes += lineBytes;
+		index += fromEnd ? -1 : 1;
+	}
+
+	return selected.join("");
+}
+
+export function placeholderFor(observation: Observation): string {
+	const headBudget = Math.floor(PLACEHOLDER_EXCERPT_BYTES / 2);
+	const tailBudget = PLACEHOLDER_EXCERPT_BYTES - headBudget;
+	const head = completeLineExcerpt(observation.text, headBudget, false);
+	const tail = completeLineExcerpt(observation.text, tailBudget, true);
+	return [
+		`[large tool result replaced after its first ${FULL_SENDS} provider requests]`,
+		`id: ${observation.id}`,
+		`tool: ${observation.toolName}`,
+		`original_bytes: ${observation.bytes}`,
+		`original_lines: ${observation.lines}`,
+		`estimated_tokens: ${observation.tokens}`,
+		`retrieve: call obs_recall with {"id":"${observation.id}","offset":0}; continue with returned next_offset`,
+		`[first complete lines, up to ${headBudget} bytes]`,
+		head,
+		`[middle omitted; last complete lines, up to ${tailBudget} bytes]`,
+		tail,
+		`[${observation.bytes} original bytes omitted]`,
+	].join("\n");
+}
+
+export interface RecallChunk {
+	readonly text: string;
+	readonly bytes: number;
+	readonly lines: number;
+	readonly nextOffset: number;
+	readonly eof: boolean;
+}
+
+function trimUtf8End(buffer: Buffer, limit: number): number {
+	let end = limit;
+	while (end > 0 && end < buffer.length && ((buffer[end] ?? 0) & 0xc0) === 0x80) end -= 1;
+	return end;
+}
+
+export async function readRecallChunk(
+	path: string,
+	offset: number,
+	limits: { readonly maxBytes: number; readonly maxLines: number },
+): Promise<RecallChunk> {
+	const handle = await open(path, READ_OBJECT_FLAGS);
+	try {
+		const fileStats = await handle.stat();
+		if (!fileStats.isFile()) throw new Error("Stored observation is not a regular file");
+		if (offset > fileStats.size) throw new Error(`Offset ${offset} exceeds observation size ${fileStats.size}`);
+
+		const available = Math.max(0, fileStats.size - offset);
+		const buffer = Buffer.alloc(Math.min(available, limits.maxBytes + 4));
+		const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+		let end = Math.min(bytesRead, limits.maxBytes);
+		let newlineCount = 0;
+
+		for (let index = 0; index < end; index += 1) {
+			if (buffer[index] !== 0x0a) continue;
+			newlineCount += 1;
+			if (newlineCount === limits.maxLines) {
+				end = index + 1;
+				break;
+			}
+		}
+
+		end = trimUtf8End(buffer, end);
+		const chunk = buffer.subarray(0, end);
+		const nextOffset = offset + chunk.length;
+		return {
+			text: chunk.toString("utf8"),
+			bytes: chunk.length,
+			lines: countBufferLines(chunk),
+			nextOffset,
+			eof: nextOffset >= fileStats.size,
+		};
+	} finally {
+		await handle.close();
+	}
+}

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/online-context-compact/economics.ts

@@ -0,0 +1,237 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+export type CompactionEconomics = {
+	readonly remainingRequestScale: number;
+	readonly remainingRequestStddevK: number;
+	readonly windowReserveTokens: number;
+	readonly firstCompactionRequestScale: number;
+	readonly subsequentCompactionMargin: number;
+};
+
+export const DEFAULT_COMPACTION_ECONOMICS: CompactionEconomics = Object.freeze({
+	remainingRequestScale: 1,
+	remainingRequestStddevK: 0,
+	windowReserveTokens: 16_384,
+	firstCompactionRequestScale: 2,
+	subsequentCompactionMargin: 1.5,
+});
+
+export type CompactionReason =
+	| "economic"
+	| "window_protection"
+	| "deferred_economic"
+	| "deferred_subsequent_margin"
+	| "deferred_carried_debt"
+	| "horizon_unavailable"
+	| "cache_ratio_unavailable"
+	| "native_not_compactable"
+	| "non_positive_saving";
+
+export type RequestHorizonEstimate = {
+	readonly completedBoundaryRequestCounts: readonly number[];
+	readonly requestsPerBoundaryMean: number;
+	readonly requestsPerBoundaryLowerBound: number;
+	readonly unboundedExpectedRemainingRequests: number;
+	readonly averageContextTokenIncrement: number | null;
+	readonly windowRequestUpperBound: number | null;
+	readonly expectedRemainingRequests: number;
+};
+
+export type CompactionDecision = {
+	readonly writeTokens: number;
+	readonly archiveTokens: number;
+	readonly memoTokens: number;
+	readonly contextTokens: number;
+	readonly completedBoundaryRequestCounts: readonly number[] | null;
+	readonly requestsPerBoundaryMean: number | null;
+	readonly requestsPerBoundaryLowerBound: number | null;
+	readonly unboundedExpectedRemainingRequests: number | null;
+	readonly averageContextTokenIncrement: number | null;
+	readonly windowRequestUpperBound: number | null;
+	readonly expectedRemainingRequests: number | null;
+	readonly breakevenRequests: number | null;
+	readonly combinedBreakevenRequests: number | null;
+	readonly effectiveHorizonRequests: number | null;
+	readonly cacheWriteReadRatio: number | null;
+	readonly incrementalCacheCostRatio: number | null;
+	readonly priorCompactionCount: number;
+	readonly carriedDebtTokens: number;
+	readonly cacheDebtRepaymentTokens: number;
+	readonly compact: boolean;
+	readonly reason: CompactionReason;
+};
+
+const MINIMUM_VARIANCE_SAMPLES = 3;
+const SMALL_SAMPLE_SCALE = 0.5;
+
+export function estimateRemainingRequests(input: {
+	readonly completedBoundaryRequestCounts: readonly number[];
+	readonly remainingBoundaries: number;
+	readonly scale: number;
+	readonly standardDeviationK: number;
+	readonly contextTokens: number;
+	readonly contextWindowTokens: number | null;
+	readonly averageContextTokenIncrement: number | null;
+}): RequestHorizonEstimate {
+	const mean =
+		input.completedBoundaryRequestCounts.reduce((total, count) => total + count, 0) /
+		Math.max(1, input.completedBoundaryRequestCounts.length);
+	let lowerBound = mean;
+	if (input.standardDeviationK !== 0) {
+		if (input.completedBoundaryRequestCounts.length < MINIMUM_VARIANCE_SAMPLES) {
+			lowerBound *= SMALL_SAMPLE_SCALE;
+		} else {
+			const variance = input.completedBoundaryRequestCounts.reduce(
+				(total, count) => total + (count - mean) ** 2,
+				0,
+			);
+			const deviation = Math.sqrt(variance / (input.completedBoundaryRequestCounts.length - 1));
+			lowerBound = Math.max(0, mean - input.standardDeviationK * deviation);
+		}
+	}
+
+	const unboundedExpectedRemainingRequests =
+		1 + Math.floor(lowerBound * Math.max(0, input.remainingBoundaries) * input.scale);
+	const windowRequestUpperBound =
+		input.contextWindowTokens === null ||
+		input.averageContextTokenIncrement === null ||
+		input.averageContextTokenIncrement <= 0
+			? null
+			: Math.max(
+					0,
+					Math.floor((input.contextWindowTokens - input.contextTokens) / input.averageContextTokenIncrement),
+				);
+
+	return {
+		completedBoundaryRequestCounts: [...input.completedBoundaryRequestCounts],
+		requestsPerBoundaryMean: mean,
+		requestsPerBoundaryLowerBound: lowerBound,
+		unboundedExpectedRemainingRequests,
+		averageContextTokenIncrement: input.averageContextTokenIncrement,
+		windowRequestUpperBound,
+		expectedRemainingRequests:
+			windowRequestUpperBound === null
+				? unboundedExpectedRemainingRequests
+				: Math.min(unboundedExpectedRemainingRequests, windowRequestUpperBound),
+	};
+}
+
+export function decideCompaction(input: {
+	readonly writeTokens: number;
+	readonly archiveTokens: number;
+	readonly memoTokens: number;
+	readonly contextTokens: number;
+	readonly completedBoundaryRequestCounts: readonly number[] | null;
+	readonly remainingBoundaries: number;
+	readonly averageContextTokenIncrement: number | null;
+	readonly contextWindowTokens: number | null;
+	readonly priorCompactionCount: number;
+	readonly carriedDebtTokens: number;
+	readonly cacheDebtRepaymentTokens: number;
+	readonly cacheWriteReadRatio: number | null;
+	readonly economics: CompactionEconomics;
+}): CompactionDecision {
+	const horizon =
+		input.completedBoundaryRequestCounts === null
+			? null
+			: estimateRemainingRequests({
+					completedBoundaryRequestCounts: input.completedBoundaryRequestCounts,
+					remainingBoundaries: input.remainingBoundaries,
+					scale: input.economics.remainingRequestScale,
+					standardDeviationK: input.economics.remainingRequestStddevK,
+					contextTokens: input.contextTokens,
+					contextWindowTokens: input.contextWindowTokens,
+					averageContextTokenIncrement: input.averageContextTokenIncrement,
+				});
+	const savingTokens = input.archiveTokens - input.memoTokens;
+	const incrementalCacheCostRatio =
+		input.cacheWriteReadRatio === null ? null : Math.max(0, input.cacheWriteReadRatio - 1);
+	const breakevenRequests =
+		savingTokens > 0 && incrementalCacheCostRatio !== null
+			? (input.writeTokens * incrementalCacheCostRatio) / savingTokens
+			: null;
+	const combinedBreakevenRequests =
+		savingTokens > 0 && incrementalCacheCostRatio !== null
+			? (input.carriedDebtTokens + input.writeTokens * incrementalCacheCostRatio) / savingTokens
+			: null;
+	const firstCompaction = input.priorCompactionCount === 0;
+	const effectiveHorizonRequests =
+		horizon === null
+			? null
+			: firstCompaction
+				? Math.min(
+						horizon.expectedRemainingRequests * input.economics.firstCompactionRequestScale,
+						horizon.windowRequestUpperBound ?? Number.POSITIVE_INFINITY,
+					)
+				: horizon.expectedRemainingRequests;
+	const windowProtection =
+		input.contextWindowTokens !== null &&
+		input.contextTokens >= input.contextWindowTokens - input.economics.windowReserveTokens;
+	const baseEconomic =
+		horizon !== null &&
+		horizon.expectedRemainingRequests > 0 &&
+		breakevenRequests !== null &&
+		breakevenRequests <= horizon.expectedRemainingRequests;
+	const firstEconomic =
+		firstCompaction &&
+		effectiveHorizonRequests !== null &&
+		effectiveHorizonRequests > 0 &&
+		breakevenRequests !== null &&
+		breakevenRequests <= effectiveHorizonRequests;
+	const subsequentMarginOpen =
+		!firstCompaction &&
+		horizon !== null &&
+		breakevenRequests !== null &&
+		breakevenRequests * input.economics.subsequentCompactionMargin <= horizon.expectedRemainingRequests;
+	const carriedDebtGateOpen =
+		!firstCompaction &&
+		horizon !== null &&
+		combinedBreakevenRequests !== null &&
+		combinedBreakevenRequests <= horizon.expectedRemainingRequests;
+	const economic = firstCompaction ? firstEconomic : baseEconomic && subsequentMarginOpen && carriedDebtGateOpen;
+	const compressible = savingTokens > 0;
+	const compact = compressible && (windowProtection || economic);
+
+	return {
+		writeTokens: input.writeTokens,
+		archiveTokens: input.archiveTokens,
+		memoTokens: input.memoTokens,
+		contextTokens: input.contextTokens,
+		...(horizon ?? {
+			completedBoundaryRequestCounts: null,
+			requestsPerBoundaryMean: null,
+			requestsPerBoundaryLowerBound: null,
+			unboundedExpectedRemainingRequests: null,
+			averageContextTokenIncrement: input.averageContextTokenIncrement,
+			windowRequestUpperBound: null,
+			expectedRemainingRequests: null,
+		}),
+		breakevenRequests,
+		combinedBreakevenRequests,
+		effectiveHorizonRequests,
+		cacheWriteReadRatio: input.cacheWriteReadRatio,
+		incrementalCacheCostRatio,
+		priorCompactionCount: input.priorCompactionCount,
+		carriedDebtTokens: input.carriedDebtTokens,
+		cacheDebtRepaymentTokens: input.cacheDebtRepaymentTokens,
+		compact,
+		reason: !compressible
+			? "non_positive_saving"
+			: windowProtection
+				? "window_protection"
+				: economic
+					? "economic"
+					: horizon === null
+						? "horizon_unavailable"
+						: breakevenRequests === null
+							? "cache_ratio_unavailable"
+							: !firstCompaction && baseEconomic && !subsequentMarginOpen
+								? "deferred_subsequent_margin"
+								: !firstCompaction && baseEconomic && !carriedDebtGateOpen
+									? "deferred_carried_debt"
+									: "deferred_economic",
+	};
+}