@herbertgao/pi-extensions 2026.9.1 → 2026.9.3

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/action-fusion/then-run.ts

@@ -0,0 +1,128 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { type BashToolOptions, createBashToolDefinition, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { withFusedFileQueue } from "./file-queue.ts";
+
+export const THEN_RUN_SUCCEEDED = "[then_run:succeeded]";
+export const THEN_RUN_FAILED = "[then_run:failed]";
+export const THEN_RUN_SKIPPED = "[then_run:skipped]";
+
+export interface ThenRunInput {
+	command: string;
+	timeout?: number;
+}
+
+export function createThenRunSchema(description: string) {
+	return Type.Optional(
+		Type.Object(
+			{
+				command: Type.String({ description: "Bash command to run" }),
+				timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+			},
+			{ description },
+		),
+	);
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function resultText(result: AgentToolResult<unknown>): string {
+	return result.content
+		.filter((block) => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+function thenRunSkippedError(error: unknown): Error {
+	return new Error(
+		`${errorText(error)}\n\n${THEN_RUN_SKIPPED} The file mutation did not complete successfully; the command was not run.`,
+	);
+}
+
+async function fileSha256(path: string): Promise<string> {
+	return createHash("sha256").update(await readFile(path)).digest("hex");
+}
+
+export async function assertUnchangedBeforeCommand(
+	path: string,
+	yieldForInterference: () => Promise<void> = () => new Promise<void>((resolve) => setImmediate(resolve)),
+): Promise<void> {
+	try {
+		const mutationHash = await fileSha256(path);
+		await yieldForInterference();
+		const commandHash = await fileSha256(path);
+		if (mutationHash !== commandHash) {
+			throw new Error("target content changed after the fused mutation");
+		}
+	} catch (error) {
+		throw new Error(`${THEN_RUN_SKIPPED} ${errorText(error)}; the command was not run.`, { cause: error });
+	}
+}
+
+/**
+ * Apply a file mutation and, when the model asked for one, run its follow-up
+ * command before returning a single observation.
+ *
+ * Both steps run inside one SoL-Pi queue slot for `absolutePath`, so another
+ * fused mutation of the same file cannot interleave. Pi's built-in mutation
+ * tool keeps its own queue; the two queues are not nested.
+ */
+export async function executeMutationThenRun<TDetails>({
+	toolCallId,
+	absolutePath,
+	thenRun,
+	mutate,
+	bashOptions,
+	signal,
+	ctx,
+}: {
+	toolCallId: string;
+	absolutePath: string;
+	thenRun: ThenRunInput | undefined;
+	mutate: () => Promise<AgentToolResult<TDetails>>;
+	bashOptions: BashToolOptions | undefined;
+	signal: AbortSignal | undefined;
+	ctx: ExtensionContext;
+}): Promise<AgentToolResult<TDetails>> {
+	return withFusedFileQueue(absolutePath, async () => {
+		let mutationResult: AgentToolResult<TDetails>;
+		try {
+			mutationResult = await mutate();
+		} catch (error) {
+			if (thenRun !== undefined) {
+				throw thenRunSkippedError(error);
+			}
+			throw error;
+		}
+
+		if (thenRun === undefined) {
+			return mutationResult;
+		}
+
+		await assertUnchangedBeforeCommand(absolutePath);
+		const bash = createBashToolDefinition(ctx.cwd, bashOptions);
+		try {
+			// pi-lens-ignore: sql-injection
+			const bashResult = await bash.execute(`${toolCallId}:then_run`, thenRun, signal, undefined, ctx);
+			const output = resultText(bashResult);
+			return {
+				...mutationResult,
+				content: [
+					...mutationResult.content,
+					{ type: "text", text: output ? `${THEN_RUN_SUCCEEDED}\n${output}` : THEN_RUN_SUCCEEDED },
+				],
+			};
+		} catch (error) {
+			const mutationOutput = resultText(mutationResult);
+			throw new Error([mutationOutput, THEN_RUN_FAILED, errorText(error)].filter(Boolean).join("\n\n"), { cause: error });
+		}
+	});
+}

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/evidence-preserving-reducer/archive.ts

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isRecord, type ReducerConfig, sha256 } from "./config.ts";
+
+export interface ArchiveObject {
+	readonly hash: string;
+	readonly bytes: number;
+	readonly chars: number;
+	readonly lines: number;
+	readonly path: string;
+}
+
+/**
+ * Archived logs live under SoL-Pi's session-derived runtime directory.
+ */
+export function archiveRoot(config: ReducerConfig): string {
+	return config.storeRoot;
+}
+
+/**
+ * Store the raw log under its own content hash.
+ *
+ * Every quote in a receipt is checked against this archive, and the receipt
+ * points the frontier agent back at this path for exact readback. An existing
+ * object with the same name but different bytes is an integrity failure, not a
+ * cache hit.
+ */
+export async function archiveBody(root: string, body: string): Promise<ArchiveObject> {
+	const hash = sha256(body);
+	const objectDir = join(root, "objects", hash.slice(0, 2));
+	const path = join(objectDir, `${hash}.txt`);
+	await mkdir(objectDir, { recursive: true, mode: 0o700 });
+	try {
+		await writeFile(path, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+	} catch (error) {
+		if (!isRecord(error) || error.code !== "EEXIST") throw error;
+		const existing = await readFile(path, "utf8");
+		if (existing !== body || sha256(existing) !== hash) {
+			throw new Error(`Reducer archive integrity failure: ${path}`, { cause: error });
+		}
+	}
+	return {
+		hash,
+		bytes: Buffer.byteLength(body, "utf8"),
+		chars: body.length,
+		lines: body.length === 0 ? 0 : body.split("\n").length,
+		path,
+	};
+}

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/evidence-preserving-reducer/candidate.ts

@@ -0,0 +1,101 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname } from "node:path";
+import type { ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import { recordValue } from "./config.ts";
+
+/** Markers written by the action-fusion extension around a fused command's output. */
+const THEN_RUN_SUCCEEDED = "[then_run:succeeded]";
+const THEN_RUN_FAILED = "[then_run:failed]";
+
+export interface ReducibleToolResult {
+	readonly command: string;
+	readonly body: string;
+	/** Put the receipt back where the raw output was, leaving the rest of the result alone. */
+	readonly projectReceipt: (receipt: string) => ToolResultEvent["content"];
+}
+
+function textContent(event: ToolResultEvent): string {
+	return event.content
+		.filter((item): item is { type: "text"; text: string } => item.type === "text")
+		.map((item) => item.text)
+		.join("\n");
+}
+
+export function detailsFullOutputPath(details: unknown): string | undefined {
+	const value = recordValue(details, "fullOutputPath");
+	return typeof value === "string" ? value : undefined;
+}
+
+async function safePiBashTempPath(path: string | undefined): Promise<boolean> {
+	if (!path || !/^pi-bash-[^/\\]+\.log$/u.test(basename(path))) return false;
+	try {
+		const [candidate, root, status] = await Promise.all([realpath(path), realpath(tmpdir()), lstat(path)]);
+		return status.isFile() && !status.isSymbolicLink() && dirname(candidate) === root;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Prefer the untruncated file pi wrote for a large bash result, so evidence is
+ * checked against the exact bytes the command produced rather than a preview.
+ */
+async function exactBodyFromInline(inline: string, details: unknown): Promise<string> {
+	const detailsPath = detailsFullOutputPath(details);
+	const inlineMatch = inline.match(/Full output:\s*([^\]\r\n]+)/u);
+	const candidate = detailsPath ?? inlineMatch?.[1]?.trim();
+	if (!candidate || !(await safePiBashTempPath(candidate))) return inline;
+	try {
+		return await readFile(candidate, "utf8");
+	} catch {
+		return inline;
+	}
+}
+
+/**
+ * Identify the log inside a tool result: either a plain bash result, or the
+ * command output appended by a fused `edit`/`write` call.
+ */
+export async function reducibleToolResult(event: ToolResultEvent): Promise<ReducibleToolResult | undefined> {
+	if (event.toolName === "bash") {
+		const command = typeof event.input.command === "string" ? event.input.command : "";
+		if (!command) return undefined;
+		const inline = textContent(event);
+		return {
+			command,
+			body: await exactBodyFromInline(inline, event.details),
+			projectReceipt: (receipt) => [{ type: "text", text: receipt }],
+		};
+	}
+	if (event.toolName !== "write" && event.toolName !== "edit") return undefined;
+	const thenRun = recordValue(event.input, "then_run");
+	const commandValue = recordValue(thenRun, "command");
+	if (typeof commandValue !== "string" || !commandValue) return undefined;
+	const marker = event.isError ? THEN_RUN_FAILED : THEN_RUN_SUCCEEDED;
+	for (let index = 0; index < event.content.length; index++) {
+		const block = event.content[index];
+		if (!block || block.type !== "text") continue;
+		const markerIndex = block.text.indexOf(marker);
+		if (markerIndex < 0) continue;
+		const suffixStart = markerIndex + marker.length;
+		const suffix = block.text.slice(suffixStart);
+		const separator = suffix.match(/^(?:\r?\n)+/u)?.[0] ?? "\n";
+		const inline = suffix.slice(separator === "\n" && !suffix.startsWith("\n") ? 0 : separator.length);
+		return {
+			command: commandValue,
+			body: await exactBodyFromInline(inline, event.details),
+			projectReceipt: (receipt) =>
+				event.content.map((content, contentIndex) =>
+					contentIndex === index && content.type === "text"
+						? { ...content, text: `${content.text.slice(0, suffixStart)}${separator}${receipt}` }
+						: content,
+				),
+		};
+	}
+	return undefined;
+}

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/evidence-preserving-reducer/config.ts

@@ -0,0 +1,71 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+export const REDUCER_EVENT_TYPE = "sol-pi-evidence-preserving-reducer-v1" as const;
+export const REDUCER_EVENT_SCHEMA = "sol-pi-evidence-preserving-reducer/1" as const;
+export const REDUCER_RECEIPT_SCHEMA = "sol-pi-evidence-receipt/1" as const;
+export const REDUCER_RECEIPT_PREFIX = "sol_pi_evidence_receipt_v1" as const;
+
+export const MAX_EVIDENCE_ITEMS = 12;
+export const MAX_QUOTE_CHARS = 600;
+
+const DEFAULT_MIN_BYTES = 4_096;
+const DEFAULT_MAX_CHARS = 600_000;
+const DEFAULT_MAX_OUTPUT_TOKENS = 2_048;
+const DEFAULT_TIMEOUT_MS = 90_000;
+
+export const DEFAULT_REDUCER_PROVIDER = ["openai", "codex"].join("-");
+export const DEFAULT_REDUCER_MODEL = ["gpt-5.6", "luna"].join("-");
+
+export const DIAGNOSTIC_COMMAND =
+	/(?:^|[;&|()\s])(?:lake\s+build|lake\s+env\s+lean|lean|coq|cargo(?:\s+(?:build|test|check))?|zig\s+build|pytest|python(?:3)?\s+-m\s+(?:pytest|unittest|py_compile)|ctest|cmake\s+--build|ninja|make|npm\s+test|pnpm\s+test|yarn\s+test|go\s+test|bazel\s+test)(?:\s|$)/i;
+
+export const FAILURE_SIGNAL = /error|failed|failure|fatal|exception|panic|timeout|unsolved|type mismatch|assert/i;
+export const LIKELY_SECRET = /(?:api[_-]?key|authorization|bearer|access[_-]?token|secret)[^\n]{0,32}[=:][^\n]+/i;
+
+export interface ReducerConfig {
+	readonly maxChars: number;
+	readonly maxOutputTokens: number;
+	readonly minBytes: number;
+	readonly reducerModel: string;
+	readonly reducerProvider: string;
+	readonly runId: string;
+	readonly storeRoot: string;
+	readonly timeoutMs: number;
+}
+
+export interface ReducerConfigOptions {
+	readonly reducerModel?: string;
+	readonly reducerProvider?: string;
+}
+
+export function sha256(value: string): string {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// pi-lens-ignore: no-unknown-returns
+export function recordValue(value: unknown, key: string): unknown {
+	return isRecord(value) ? value[key] : undefined;
+}
+
+export function loadReducerConfig(runtimeDirectory: string, options: ReducerConfigOptions = {}): ReducerConfig {
+	return Object.freeze({
+		maxChars: DEFAULT_MAX_CHARS,
+		maxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+		minBytes: DEFAULT_MIN_BYTES,
+		reducerModel: options.reducerModel ?? DEFAULT_REDUCER_MODEL,
+		reducerProvider: options.reducerProvider ?? DEFAULT_REDUCER_PROVIDER,
+		runId: sha256(runtimeDirectory).slice(0, 16),
+		storeRoot: join(runtimeDirectory, "evidence-preserving-reducer"),
+		timeoutMs: DEFAULT_TIMEOUT_MS,
+	});
+}

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/evidence-preserving-reducer/index.ts

@@ -0,0 +1,220 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Evidence-Preserving Reducer - delegate the first read of a long build or test
+ * log to the configured reducer model, then verify what comes back.
+ *
+ * In build and test trajectories only a few lines of a long log change the next
+ * decision. This extension archives the raw log, sends it through the reducer
+ * provider/model selected by the top-level SoL-Pi config, and accepts the
+ * resulting receipt only when every quoted line is found byte for byte in the
+ * archive. A receipt that cannot be checked is discarded and the original
+ * output reaches the frontier agent untouched.
+ *
+ * Delegation therefore never requires trusting a fluent summary.
+ *
+ * The top-level SoL-Pi config enables this mechanism. Provider selection and
+ * authentication remain with Pi; storage and run identity come from the session.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ExtensionFactory,
+	ToolResultEvent,
+} from "@earendil-works/pi-coding-agent";
+import { runtimeRoot } from "../../runtime-paths.ts";
+import { formatSavingsBytes, showSolPiSavings } from "../../tui.ts";
+import { archiveBody, archiveRoot } from "./archive.ts";
+import { reducibleToolResult } from "./candidate.ts";
+import {
+	DIAGNOSTIC_COMMAND,
+	isRecord,
+	LIKELY_SECRET,
+	loadReducerConfig,
+	REDUCER_RECEIPT_SCHEMA,
+	type ReducerConfig,
+	type ReducerConfigOptions,
+	sha256,
+} from "./config.ts";
+import { createJournal, type Journal } from "./journal.ts";
+import { callReducer, type ProviderResult } from "./provider.ts";
+import { receiptText, validateReceipt } from "./receipt.ts";
+
+export interface ReducedToolResult {
+	readonly content: ToolResultEvent["content"];
+	readonly details: Record<string, unknown>;
+	readonly isError: boolean;
+}
+
+export type EvidencePreservingReducerOptions = ReducerConfigOptions;
+
+function errorName(error: unknown): string | undefined {
+	return isRecord(error) && typeof error.name === "string" ? error.name : undefined;
+}
+
+export async function reduceToolResult(
+	journal: Journal,
+	config: ReducerConfig,
+	event: ToolResultEvent,
+	context: ExtensionContext,
+): Promise<ReducedToolResult | undefined> {
+	const reducible = await reducibleToolResult(event);
+	if (!reducible || !DIAGNOSTIC_COMMAND.test(reducible.command)) return undefined;
+	const { body, command } = reducible;
+	if (Buffer.byteLength(body, "utf8") < config.minBytes) return undefined;
+	if (body.length > config.maxChars) {
+		journal("fallback", { reason: "source-over-max-chars", sourceChars: body.length, maxChars: config.maxChars });
+		return undefined;
+	}
+	if (LIKELY_SECRET.test(body)) {
+		journal("fallback", { reason: "likely-secret" });
+		return undefined;
+	}
+
+	const archive = await archiveBody(archiveRoot(config), body);
+	journal("candidate", {
+		toolCallId: event.toolCallId,
+		commandSha256: sha256(command),
+		isError: event.isError,
+		sourceSha256: archive.hash,
+		sourceBytes: archive.bytes,
+		sourceLines: archive.lines,
+		sourcePath: archive.path,
+	});
+
+	let provider: ProviderResult;
+	try {
+		provider = await callReducer(config, command, event.isError, archive, body, context);
+	} catch (error) {
+		const name = errorName(error);
+		journal("fallback", {
+			toolCallId: event.toolCallId,
+			sourceSha256: archive.hash,
+			reason:
+				name === "AbortError"
+					? "model-call-timeout"
+					: name === "ReducerModelUnavailableError"
+						? "reducer-model-unavailable"
+						: "model-call-exception",
+		});
+		return undefined;
+	}
+
+	journal("provider_response", {
+		toolCallId: event.toolCallId,
+		sourceSha256: archive.hash,
+		provider: provider.provider,
+		model: provider.model,
+		stopReason: provider.stopReason,
+		errorMessage: provider.errorMessage,
+		usage: provider.usage,
+	});
+	if (!provider.ok) {
+		journal("fallback", {
+			toolCallId: event.toolCallId,
+			sourceSha256: archive.hash,
+			reason: "model-response-error",
+			stopReason: provider.stopReason,
+			errorMessage: provider.errorMessage,
+		});
+		return undefined;
+	}
+
+	const checked = validateReceipt(provider.outputText, archive, body, event.isError);
+	if (!checked.ok) {
+		journal("fallback", {
+			toolCallId: event.toolCallId,
+			sourceSha256: archive.hash,
+			reason: checked.reason,
+			usage: provider.usage,
+		});
+		return undefined;
+	}
+	const receipt = receiptText(command, archive, checked.value, provider);
+	const receiptBytes = Buffer.byteLength(receipt, "utf8");
+	if (receiptBytes >= archive.bytes) {
+		journal("fallback", {
+			toolCallId: event.toolCallId,
+			sourceSha256: archive.hash,
+			reason: "receipt-not-smaller",
+			receiptBytes,
+			sourceBytes: archive.bytes,
+			usage: provider.usage,
+		});
+		return undefined;
+	}
+	journal("applied", {
+		toolCallId: event.toolCallId,
+		commandSha256: sha256(command),
+		sourceSha256: archive.hash,
+		sourceBytes: archive.bytes,
+		receiptSha256: sha256(receipt),
+		receiptBytes,
+		evidenceCount: checked.value.evidence.length,
+		uncertain: checked.value.uncertain,
+		usage: provider.usage,
+	});
+	showSolPiSavings(context, "Luna Delegating", formatSavingsBytes(archive.bytes - receiptBytes));
+	return {
+		content: reducible.projectReceipt(receipt),
+		isError: event.isError,
+		details: {
+			...(isRecord(event.details) ? event.details : {}),
+			evidencePreservingReducer: {
+				schema: REDUCER_RECEIPT_SCHEMA,
+				sourceSha256: archive.hash,
+				sourceBytes: archive.bytes,
+				receiptSha256: sha256(receipt),
+				receiptBytes,
+				evidenceCount: checked.value.evidence.length,
+				uncertain: checked.value.uncertain,
+			},
+		},
+	};
+}
+
+export function createEvidencePreservingReducerExtension(options: EvidencePreservingReducerOptions = {}): ExtensionFactory {
+	return (pi: ExtensionAPI) => {
+		const states = new Map<string, { config: ReducerConfig; journal: Journal }>();
+		pi.on("tool_result", (event, context) => {
+			let root: string;
+			try {
+				root = runtimeRoot(context);
+			} catch {
+				return undefined;
+			}
+			let state = states.get(root);
+			if (!state) {
+				const config = loadReducerConfig(root, options);
+				state = { config, journal: createJournal(pi, config) };
+				states.set(root, state);
+			}
+			return reduceToolResult(state.journal, state.config, event, context);
+		});
+	};
+}
+
+export type { ArchiveObject } from "./archive.ts";
+export {
+	DIAGNOSTIC_COMMAND,
+	loadReducerConfig,
+	REDUCER_EVENT_SCHEMA,
+	REDUCER_EVENT_TYPE,
+	REDUCER_RECEIPT_PREFIX,
+	REDUCER_RECEIPT_SCHEMA,
+	type ReducerConfigOptions,
+	type ReducerConfig,
+} from "./config.ts";
+export { validateReceipt } from "./receipt.ts";
+
+export function registerEvidencePreservingReducer(
+	pi: ExtensionAPI,
+	options: EvidencePreservingReducerOptions = {},
+): void {
+	createEvidencePreservingReducerExtension(options)(pi);
+}
+
+export default registerEvidencePreservingReducer;

package/node_modules/@herbertgao/sol-pi/src/sol-pi/extensions/evidence-preserving-reducer/journal.ts

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { REDUCER_EVENT_SCHEMA, REDUCER_EVENT_TYPE, type ReducerConfig } from "./config.ts";
+
+/**
+ * Append one non-context session entry per decision the reducer made.
+ *
+ * The entries never enter the LLM context. They record which results were
+ * candidates, which were delegated, and why each fallback happened.
+ */
+export type Journal = (kind: string, data?: Record<string, unknown>) => void;
+
+export function createJournal(pi: ExtensionAPI, config: ReducerConfig): Journal {
+	return (kind, data = {}) => {
+		pi.appendEntry(REDUCER_EVENT_TYPE, {
+			schema: REDUCER_EVENT_SCHEMA,
+			runId: config.runId,
+			kind,
+			...data,
+		});
+	};
+}