gentle-pi 2.2.0 → 2.4.0

package/lib/opaque-pi-reviewer-adapter.ts

@@ -0,0 +1,284 @@
+import { spawn } from "node:child_process";
+import { chmod, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, posix, win32 } from "node:path";
+
+export const OPAQUE_PI_REVIEWER_ARGV = Object.freeze([
+	"--print",
+	"--mode", "text",
+	"--no-session",
+	"--no-tools",
+	"--no-extensions",
+	"--no-skills",
+	"--no-prompt-templates",
+	"--no-themes",
+	"--no-context-files",
+	"--no-approve",
+] as const);
+
+export const OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE = {
+	SCRATCH_FAILED: "scratch-failed",
+	LAUNCH_FAILED: "launch-failed",
+	CANCELLED: "cancelled",
+	TIMED_OUT: "timed-out",
+	NONZERO_EXIT: "nonzero-exit",
+	EMPTY_OUTPUT: "empty-output",
+	CLEANUP_FAILED: "cleanup-failed",
+} as const;
+export type OpaquePiReviewerTransportFailureKind = (typeof OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE)[keyof typeof OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE];
+
+export interface OpaquePiReviewerOptions {
+	readonly piExecutable?: string;
+	readonly environment?: NodeJS.ProcessEnv;
+	readonly timeoutMs?: number;
+	readonly signal?: AbortSignal;
+}
+
+export interface OpaquePiReviewerResult {
+	readonly stdout: Buffer;
+	readonly promptByteLength: number;
+	readonly stdoutByteLength: number;
+}
+
+export interface OpaquePiReviewerTransportDetails {
+	readonly exitCode?: number | null;
+	readonly stderr?: Buffer;
+	readonly timedOut?: boolean;
+	readonly cancelled?: boolean;
+	/** Wall time for a launched Pi process; absent when no process was launched. */
+	readonly elapsedMs?: number;
+	/** The bound applied to a launched Pi process; absent when no process was launched. */
+	readonly timeoutMs?: number;
+}
+
+export class OpaquePiReviewerTransportError extends Error {
+	readonly kind: OpaquePiReviewerTransportFailureKind;
+	readonly exitCode: number | null;
+	readonly stderr: Buffer;
+	readonly timedOut: boolean;
+	readonly cancelled: boolean;
+	readonly elapsedMs: number | null;
+	readonly timeoutMs: number | null;
+
+	constructor(kind: OpaquePiReviewerTransportFailureKind, message: string, details: OpaquePiReviewerTransportDetails = {}) {
+		super(message);
+		this.name = "OpaquePiReviewerTransportError";
+		this.kind = kind;
+		this.exitCode = details.exitCode ?? null;
+		this.stderr = details.stderr ?? Buffer.alloc(0);
+		this.timedOut = details.timedOut ?? false;
+		this.cancelled = details.cancelled ?? false;
+		this.elapsedMs = details.elapsedMs ?? null;
+		this.timeoutMs = details.timeoutMs ?? null;
+	}
+}
+
+interface OpaquePiProcessResult {
+	readonly stdout: Buffer;
+	readonly stderr: Buffer;
+	readonly exitCode: number | null;
+	readonly timedOut: boolean;
+	readonly cancelled: boolean;
+	readonly elapsedMs: number;
+	readonly timeoutMs: number;
+}
+
+const DEFAULT_OPAQUE_PI_TIMEOUT_MS = 600_000;
+
+export interface PiLaunch {
+	readonly file: string;
+	readonly arguments: readonly string[];
+}
+
+interface PiHostProcess {
+	readonly execPath: string;
+	readonly entry: string | undefined;
+}
+
+/**
+ * The exact spawn shape for the fresh Pi process. A bare `pi` on Windows
+ * resolves to pi.cmd, pi.ps1, or a POSIX shim, none of which Node can spawn
+ * with shell:false (EINVAL or ENOENT). This adapter already runs inside Pi, so
+ * on win32 the host's own JavaScript entry is spawned through the host's
+ * process.execPath instead; a shell is never enabled. Every other platform,
+ * and every explicit launcher, keeps the exact shape it always had.
+ */
+export function resolvePiLaunch(
+	piExecutable: string | undefined,
+	platform: NodeJS.Platform = process.platform,
+	host: PiHostProcess = { execPath: process.execPath, entry: process.argv[1] },
+): PiLaunch {
+	if (piExecutable !== undefined) return { file: piExecutable, arguments: [...OPAQUE_PI_REVIEWER_ARGV] };
+	if (platform !== "win32") return { file: "pi", arguments: [...OPAQUE_PI_REVIEWER_ARGV] };
+	if (typeof host.entry !== "string" || host.entry.length === 0 || !(platform === "win32" ? win32 : posix).isAbsolute(host.entry)) {
+		throw new Error(`Pi host entry could not be resolved from the running process (received ${JSON.stringify(host.entry ?? null)}); a bare pi launcher cannot be spawned on Windows without a shell`);
+	}
+	return { file: host.execPath, arguments: [host.entry, ...OPAQUE_PI_REVIEWER_ARGV] };
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function runPiProcess(prompt: Buffer, scratchDirectory: string, options: OpaquePiReviewerOptions): Promise<OpaquePiProcessResult> {
+	return new Promise((resolve, reject) => {
+		const startedAt = Date.now();
+		let launch: PiLaunch;
+		try {
+			launch = resolvePiLaunch(options.piExecutable);
+		} catch (error) {
+			reject(error);
+			return;
+		}
+		const child = spawn(launch.file, [...launch.arguments], {
+			cwd: scratchDirectory,
+			env: options.environment ?? process.env,
+			stdio: ["pipe", "pipe", "pipe"],
+			shell: false,
+			windowsHide: true,
+		});
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+		const timeoutMs = options.timeoutMs ?? DEFAULT_OPAQUE_PI_TIMEOUT_MS;
+		let timedOut = false;
+		let cancelled = false;
+		let settled = false;
+		const timer = timeoutMs > 0
+			? setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGKILL");
+			}, timeoutMs)
+			: undefined;
+		timer?.unref();
+		const cancel = () => {
+			cancelled = true;
+			child.kill("SIGKILL");
+		};
+		const clear = () => {
+			if (timer !== undefined) clearTimeout(timer);
+			options.signal?.removeEventListener("abort", cancel);
+		};
+
+		child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+		child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+		child.on("error", (error) => {
+			if (settled) return;
+			settled = true;
+			clear();
+			reject(error);
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clear();
+			resolve({
+				stdout: Buffer.concat(stdout),
+				stderr: Buffer.concat(stderr),
+				exitCode: code,
+				timedOut,
+				cancelled,
+				elapsedMs: Date.now() - startedAt,
+				timeoutMs,
+			});
+		});
+		if (options.signal?.aborted) cancel();
+		else options.signal?.addEventListener("abort", cancel, { once: true });
+		child.stdin.on("error", () => undefined);
+		child.stdin.end(prompt);
+	});
+}
+
+/** Runs raw prompt bytes through one fixed, isolated Pi process. */
+export async function runOpaquePiReviewer(prompt: Buffer, options: OpaquePiReviewerOptions = {}): Promise<OpaquePiReviewerResult> {
+	if (options.signal?.aborted) {
+		throw new OpaquePiReviewerTransportError(
+			OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.CANCELLED,
+			"Pi process was cancelled before launch",
+			{ cancelled: true },
+		);
+	}
+
+	let scratchDirectory: string | undefined;
+	let primaryFailure = false;
+	try {
+		try {
+			scratchDirectory = await mkdtemp(join(tmpdir(), "gentle-pi-opaque-reviewer-"));
+			await chmod(scratchDirectory, 0o700);
+		} catch (error) {
+			throw new OpaquePiReviewerTransportError(
+				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.SCRATCH_FAILED,
+				`Pi scratch directory could not be prepared: ${errorMessage(error)}`,
+			);
+		}
+
+		let processResult: OpaquePiProcessResult;
+		try {
+			processResult = await runPiProcess(prompt, scratchDirectory, options);
+		} catch (error) {
+			if (options.signal?.aborted) {
+				throw new OpaquePiReviewerTransportError(
+					OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.CANCELLED,
+					"Pi process was cancelled",
+					{ cancelled: true },
+				);
+			}
+			throw new OpaquePiReviewerTransportError(
+				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.LAUNCH_FAILED,
+				`Pi process could not start: ${errorMessage(error)}`,
+			);
+		}
+		const timing = {
+			elapsedMs: processResult.elapsedMs,
+			timeoutMs: processResult.timeoutMs,
+		};
+		if (processResult.timedOut) {
+			throw new OpaquePiReviewerTransportError(
+				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.TIMED_OUT,
+				"Pi process timed out",
+				{ exitCode: processResult.exitCode, stderr: processResult.stderr, timedOut: true, ...timing },
+			);
+		}
+		if (processResult.cancelled) {
+			throw new OpaquePiReviewerTransportError(
+				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.CANCELLED,
+				"Pi process was cancelled",
+				{ exitCode: processResult.exitCode, stderr: processResult.stderr, cancelled: true, ...timing },
+			);
+		}
+		if (processResult.exitCode !== 0) {
+			throw new OpaquePiReviewerTransportError(
+				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.NONZERO_EXIT,
+				"Pi process failed",
+				{ exitCode: processResult.exitCode, stderr: processResult.stderr, ...timing },
+			);
+		}
+		if (processResult.stdout.length === 0) {
+			throw new OpaquePiReviewerTransportError(
+				OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT,
+				"Pi process produced no output bytes",
+				{ exitCode: 0, stderr: processResult.stderr, ...timing },
+			);
+		}
+		return {
+			stdout: processResult.stdout,
+			promptByteLength: prompt.length,
+			stdoutByteLength: processResult.stdout.length,
+		};
+	} catch (error) {
+		primaryFailure = true;
+		throw error;
+	} finally {
+		if (scratchDirectory !== undefined) {
+			try {
+				await rm(scratchDirectory, { recursive: true, force: true });
+			} catch (error) {
+				if (!primaryFailure) {
+					throw new OpaquePiReviewerTransportError(
+						OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.CLEANUP_FAILED,
+						`Pi scratch directory cleanup failed: ${errorMessage(error)}`,
+					);
+				}
+			}
+		}
+	}
+}

package/lib/provider-contract-bundle.ts

@@ -31,6 +31,8 @@ export const PI_RUNTIME_IDENTITY = "pi";
 export const SUPPORTED_PROVIDER_CONTRACT_MAJOR = 1;
 // `runtimes` became part of the manifest in contract 1.1.0.
 export const RUNTIMES_REQUIRED_SINCE_MINOR = 1;
+// `orchestration` became part of the manifest in contract 1.2.0.
+export const ORCHESTRATION_REQUIRED_SINCE_MINOR = 2;
 // Exactly the provider roles gentle-pi supports, in the manifest's strict order.
 export const PROVIDER_CONTRACT_ROLE_IDS = ["lens", "refuter", "targeted-validator"] as const;
 // Every mandatory capability a role may declare. An unknown mandatory
@@ -42,6 +44,13 @@ const MAX_FILE_BYTES = 4 * 1024 * 1024;
 const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
 const MAX_MANIFEST_BYTES = 64 * 1024;
 const BUNDLE_ENTRY_COUNT = 8;
+// Generous fixed safety bound on raw archive/tree entries read BEFORE the
+// manifest itself is parsed (the exact expected count, base entries plus one
+// per `orchestration` runtime, is known only after manifest decode). Real
+// contracts register a handful of runtimes; this bound only rules out an
+// absurd smuggled inventory, it is not the exact-count check.
+const MAX_ORCHESTRATION_ENTRIES = 64;
+const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + MAX_ORCHESTRATION_ENTRIES;
 // setuid/setgid/sticky, any execute bit, or world-writable content is never
 // acceptable for a data-only contract bundle.
 const FORBIDDEN_MODE_BITS = 0o7113;
@@ -84,7 +93,13 @@ export interface VerifiedProviderContractBundle {
 	/** Present exactly when the manifest declares the runtime registry (>= 1.1.0). */
 	readonly runtimes: readonly string[] | undefined;
 	readonly roles: readonly VerifiedProviderRole[];
-	/** Canonical path -> exact verified bytes for all eight entries. */
+	/**
+	 * Verified runtime-bound review execution contract text, runtime identity
+	 * -> UTF-8 `orchestration/<runtime>.md` contents. Empty before contract
+	 * 1.2.0, where `orchestration` does not exist in the manifest.
+	 */
+	readonly orchestration: ReadonlyMap<string, string>;
+	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration runtime). */
 	readonly entries: ReadonlyMap<string, Buffer>;
 	/** Canonical path -> SHA-256 of the exact verified bytes. */
 	readonly entrySha256: ReadonlyMap<string, string>;
@@ -306,6 +321,23 @@ function parseManifestRole(value: unknown, index: number): ManifestRole {
 	};
 }
 
+interface ManifestOrchestrationEntry {
+	readonly runtime: string;
+	readonly file: ManifestFileReference;
+}
+
+function parseOrchestrationEntry(value: unknown, index: number): ManifestOrchestrationEntry {
+	const where = `manifest.orchestration[${index}]`;
+	const object = requireObject(value, where);
+	requireExactKeys(object, ["runtime", "file"], ["runtime", "file"], where);
+	const runtime = requireString(object.runtime, `${where}.runtime`);
+	if (!RUNTIME_IDENTITY_PATTERN.test(runtime)) invalid(`${where}.runtime ${JSON.stringify(runtime)} is not a runtime identity`);
+	const file = parseFileReference(object.file, `${where}.file`);
+	const expectedPath = `orchestration/${runtime}.md`;
+	if (file.path !== expectedPath) invalid(`${where}.file.path must be ${JSON.stringify(expectedPath)}`);
+	return { runtime, file };
+}
+
 interface ParsedManifest {
 	readonly contractSemver: string;
 	readonly major: number;
@@ -315,13 +347,14 @@ interface ParsedManifest {
 	readonly runtimes: readonly string[] | undefined;
 	readonly readme: ManifestFileReference;
 	readonly roles: readonly ManifestRole[];
+	readonly orchestration: readonly ManifestOrchestrationEntry[];
 }
 
 function parseManifest(payload: Buffer): ParsedManifest {
 	const object = decodeStrictManifestObject(payload);
 	requireExactKeys(
 		object,
-		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles"],
+		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration"],
 		["schema", "contract_semver", "transport_capability", "readme", "roles"],
 		"manifest",
 	);
@@ -365,6 +398,33 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		invalid(`manifest.runtimes does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
 	}
 
+	const orchestrationRequired = minor >= ORCHESTRATION_REQUIRED_SINCE_MINOR;
+	let orchestration: readonly ManifestOrchestrationEntry[] = [];
+	if (Object.prototype.hasOwnProperty.call(object, "orchestration")) {
+		if (!orchestrationRequired) {
+			invalid(`manifest.orchestration is not part of contract ${contractSemver}; it exists from 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0`);
+		}
+		if (!Array.isArray(object.orchestration) || object.orchestration.length === 0) {
+			invalid("manifest.orchestration must be a non-empty array");
+		}
+		const parsedOrchestration = object.orchestration.map((entry, index) => parseOrchestrationEntry(entry, index));
+		for (let position = 0; position < parsedOrchestration.length; position += 1) {
+			const entry = parsedOrchestration[position] as ManifestOrchestrationEntry;
+			if (position > 0 && (parsedOrchestration[position - 1] as ManifestOrchestrationEntry).runtime >= entry.runtime) {
+				invalid("manifest.orchestration must be strictly sorted by runtime and unique");
+			}
+			if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
+				invalid(`manifest.orchestration[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
+			}
+		}
+		if (!parsedOrchestration.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
+			invalid(`manifest.orchestration does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
+		}
+		orchestration = parsedOrchestration;
+	} else if (orchestrationRequired) {
+		invalid(`manifest.orchestration is required from contract 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0 (got ${contractSemver} without it)`);
+	}
+
 	if (!Array.isArray(object.roles)) invalid("manifest.roles must be an array");
 	const roles = object.roles.map((role, index) => parseManifestRole(role, index));
 	if (roles.length !== PROVIDER_CONTRACT_ROLE_IDS.length) {
@@ -385,6 +445,7 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		runtimes,
 		readme: parseFileReference(object.readme, "manifest.readme"),
 		roles,
+		orchestration,
 	};
 }
 
@@ -467,8 +528,8 @@ export function bundleTreeSha256(entrySha256: ReadonlyMap<string, string>): stri
 
 /** Verifies a complete in-memory bundle inventory. The single trust anchor. */
 export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<string, Buffer>): VerifiedProviderContractBundle {
-	if (rawEntries.size !== BUNDLE_ENTRY_COUNT) {
-		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${BUNDLE_ENTRY_COUNT} are expected`);
+	if (rawEntries.size > MAX_RAW_BUNDLE_ENTRIES) {
+		invalid(`bundle inventory has ${rawEntries.size} files; at most ${MAX_RAW_BUNDLE_ENTRIES} are ever expected`);
 	}
 	for (const [name, payload] of rawEntries) {
 		if (!isCanonicalBundlePath(name)) invalid(`bundle path ${JSON.stringify(name)} is unsafe`);
@@ -478,6 +539,14 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 	if (manifestPayload === undefined) invalid("bundle is missing manifest.json");
 	const manifest = parseManifest(manifestPayload);
 
+	// The exact expected inventory size is only known once the manifest is
+	// decoded: base entries plus exactly one `orchestration/<runtime>.md` per
+	// registered orchestration runtime.
+	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length;
+	if (rawEntries.size !== expectedEntryCount) {
+		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${expectedEntryCount} are expected`);
+	}
+
 	verifyFileReference(rawEntries, manifest.readme, "README.md");
 	const expected = new Set(["README.md", "manifest.json"]);
 	for (const role of manifest.roles) {
@@ -485,6 +554,13 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 		expected.add(`schemas/${role.id}.schema.json`);
 		expected.add(`vectors/${role.id}.json`);
 	}
+	const orchestration = new Map<string, string>();
+	for (const entry of manifest.orchestration) {
+		const path = `orchestration/${entry.runtime}.md`;
+		const payload = verifyFileReference(rawEntries, entry.file, path);
+		orchestration.set(entry.runtime, payload.toString("utf8"));
+		expected.add(path);
+	}
 	for (const name of rawEntries.keys()) {
 		if (!expected.has(name)) invalid(`bundle has unexpected file ${JSON.stringify(name)}`);
 	}
@@ -514,6 +590,7 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 			vectorPath: role.vector.path,
 			vectorSha256: role.vector.sha256,
 		})),
+		orchestration,
 		entries,
 		entrySha256,
 		treeSha256: bundleTreeSha256(entrySha256),
@@ -566,7 +643,7 @@ export function verifyProviderContractBundleTree(directory: string): VerifiedPro
 			}
 			if (!isCanonicalBundlePath(relativeName)) invalid(`bundle tree path ${JSON.stringify(relativeName)} is unsafe`);
 			if (details.size > MAX_FILE_BYTES) invalid(`bundle tree entry ${JSON.stringify(relativeName)} exceeds its size limit`);
-			if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`bundle tree has more than ${BUNDLE_ENTRY_COUNT} files`);
+			if (entries.size >= MAX_RAW_BUNDLE_ENTRIES) invalid(`bundle tree has more than ${MAX_RAW_BUNDLE_ENTRIES} files`);
 			entries.set(relativeName, readFileSync(absolute));
 		}
 	};
@@ -628,7 +705,7 @@ function readTarEntries(expanded: Buffer): Map<string, Buffer> {
 		if (size > MAX_FILE_BYTES) invalid(`tar entry ${JSON.stringify(name)} exceeds its size limit`);
 		totalBytes += size;
 		if (totalBytes > MAX_BUNDLE_BYTES) invalid("tar entries exceed the bundle size limit");
-		if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`tar has more than ${BUNDLE_ENTRY_COUNT} entries`);
+		if (entries.size >= MAX_RAW_BUNDLE_ENTRIES) invalid(`tar has more than ${MAX_RAW_BUNDLE_ENTRIES} entries`);
 		const padding = (TAR_BLOCK_SIZE - (size % TAR_BLOCK_SIZE)) % TAR_BLOCK_SIZE;
 		if (expanded.length - offset < size + padding) invalid("tar stream ends before a complete entry");
 		entries.set(name, Buffer.from(expanded.subarray(offset, offset + size)));
@@ -696,6 +773,11 @@ export function generateProviderContractBaselines(bundle: VerifiedProviderContra
 		mandatory_capabilities: mandatory,
 		runtimes: bundle.runtimes === undefined ? null : [...bundle.runtimes],
 		pi_registered: piRuntimeRegistration(bundle).registered,
+		orchestration: [...bundle.orchestration.keys()].sort().map((runtime) => ({
+			runtime,
+			path: `orchestration/${runtime}.md`,
+			sha256: bundle.entrySha256.get(`orchestration/${runtime}.md`),
+		})),
 	};
 	return new Map([
 		[PROVIDER_ROLES_BASELINE_FILE, `${JSON.stringify(roles, null, 2)}\n`],