pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/runs/shared/single-output.ts

@@ -0,0 +1,304 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+import { hasMutationToolCapability } from "./completion-guard.ts";
+
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	size?: number;
+	error?: string;
+}
+
+function missingFileStatError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function snapshotFromStatError(error: unknown): SingleOutputSnapshot {
+	if (missingFileStatError(error)) return { exists: false };
+	return { exists: false, error: error instanceof Error ? error.message : String(error) };
+}
+
+/**
+ * Content the child itself sent to the configured output path, taken from its
+ * last `write` tool call whose tool result reports success. Unlike reading the
+ * path from disk, this cannot be polluted by a sibling run writing the same
+ * path (#420); requiring the successful tool result keeps failed, cancelled,
+ * or unanswered write calls from counting as authored output. Returns
+ * undefined when no such write exists (e.g. bash or edit-based construction),
+ * in which case callers must not assume file authorship.
+ */
+export function extractChildWrittenOutput(
+	messages: Message[] | undefined,
+	outputPath: string | undefined,
+	cwd?: string,
+): string | undefined {
+	if (!messages?.length || !outputPath) return undefined;
+	const resolvedTarget = path.resolve(cwd ?? ".", outputPath);
+	const comparableTarget = process.platform === "win32" ? resolvedTarget.toLowerCase() : resolvedTarget;
+	const successfulCallIds = new Set<string>();
+	for (const message of messages) {
+		if (message.role === "toolResult" && message.isError === false && typeof message.toolCallId === "string") {
+			successfulCallIds.add(message.toolCallId);
+		}
+	}
+	let content: string | undefined;
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		for (const part of message.content) {
+			if (part.type !== "toolCall" || part.name !== "write" || !successfulCallIds.has(part.id)) continue;
+			const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
+				? part.arguments as Record<string, unknown>
+				: {};
+			if (typeof args.path !== "string" || typeof args.content !== "string") continue;
+			const resolvedWritePath = path.resolve(cwd ?? ".", args.path);
+			const comparableWritePath = process.platform === "win32" ? resolvedWritePath.toLowerCase() : resolvedWritePath;
+			if (comparableWritePath !== comparableTarget) continue;
+			content = args.content;
+		}
+	}
+	return content;
+}
+
+export function normalizeSingleOutputOverride(
+	output: string | boolean | undefined,
+	defaultOutput: string | undefined,
+): string | false | undefined {
+	if (output === false || output === "false") return false;
+	if (output === true || output === "true") return defaultOutput;
+	if (typeof output === "string" && output.length > 0) return output;
+	return undefined;
+}
+
+export function resolveSingleOutputPath(
+	output: string | boolean | undefined,
+	runtimeCwd: string,
+	requestedCwd?: string,
+	relativeBaseDir?: string,
+): string | undefined {
+	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
+	if (path.isAbsolute(output)) return output;
+	if (relativeBaseDir) return path.resolve(relativeBaseDir, output);
+	const baseCwd = requestedCwd
+		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+		: runtimeCwd;
+	return path.resolve(baseCwd, output);
+}
+
+interface OutputInstructionCapabilities {
+	tools?: string[];
+	mcpDirectTools?: string[];
+}
+
+function formatOutputPathInstruction(outputPath: string, capabilities?: OutputInstructionCapabilities): string {
+	const delivery = !capabilities || hasMutationToolCapability(capabilities.tools, capabilities.mcpDirectTools)
+		? `Write your findings to exactly this path: ${outputPath}`
+		: [
+			"Return the complete artifact in your final response.",
+			`The runtime will persist it to exactly this path: ${outputPath}`,
+			"Do not call contact_supervisor merely because no write-capable tool is available.",
+		].join("\n");
+	return [
+		delivery,
+		"This path is authoritative for this run.",
+		"Ignore any other output filename or output path mentioned elsewhere, including output destinations in the base agent prompt, system prompt, or task instructions.",
+	].join("\n");
+}
+
+export function requestedOutputPathFromTask(task: string): string | undefined {
+	for (const line of task.split(/\r?\n/).reverse()) {
+		const match = line.match(/^\s*(?:Write your findings to(?: exactly this path)?:|The runtime will persist it to exactly this path:)\s*(.+?)\s*$/i);
+		if (!match?.[1]) continue;
+		const requested = match[1].trim();
+		return requested.startsWith("`") && requested.endsWith("`") ? requested.slice(1, -1) : requested;
+	}
+	return undefined;
+}
+
+export function outputPathMappingFromTask(task: string, savedPath: string | undefined): { requestedPath: string; savedPath: string } | undefined {
+	const requestedPath = requestedOutputPathFromTask(task);
+	if (!requestedPath || !savedPath) return undefined;
+	if (path.isAbsolute(requestedPath) && path.normalize(requestedPath) === path.normalize(savedPath)) return undefined;
+	return { requestedPath, savedPath };
+}
+
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined, capabilities?: OutputInstructionCapabilities): string {
+	if (!outputPath) return task;
+	return `${task}\n\n---\n**Output:**\n${formatOutputPathInstruction(outputPath, capabilities)}`;
+}
+
+export function injectOutputPathSystemPrompt(systemPrompt: string, outputPath: string | undefined, capabilities?: OutputInstructionCapabilities): string {
+	if (!outputPath) return systemPrompt;
+	const instruction = `Runtime output path override:\n${formatOutputPathInstruction(outputPath, capabilities)}`;
+	return systemPrompt ? `${systemPrompt}\n\n${instruction}` : instruction;
+}
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
+	if (outputMode === "file-only" && !outputPath) {
+		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+	}
+	return undefined;
+}
+
+export function resolveSingleOutputClaimPath(outputPath: string): string {
+	let existing = path.resolve(outputPath);
+	const missingSegments: string[] = [];
+	while (!fs.existsSync(existing)) {
+		missingSegments.unshift(path.basename(existing));
+		const parent = path.dirname(existing);
+		if (parent === existing) break;
+		existing = parent;
+	}
+	return path.join(fs.realpathSync(existing), ...missingSegments);
+}
+
+function outputClaimError(outputPath: string, expectedClaimPath: string | undefined): string | undefined {
+	if (expectedClaimPath && resolveSingleOutputClaimPath(outputPath) !== expectedClaimPath) return "Output path changed after it was claimed.";
+	return undefined;
+}
+
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch (error) {
+		return snapshotFromStatError(error);
+	}
+}
+
+function inspectSingleOutputChange(
+	outputPath: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { changed: boolean; error?: string } {
+	if (beforeRun?.error) return { changed: false, error: beforeRun.error };
+	try {
+		const stat = fs.statSync(outputPath);
+		return {
+			changed: !beforeRun?.exists || stat.mtimeMs !== beforeRun.mtimeMs || stat.size !== beforeRun.size,
+		};
+	} catch (error) {
+		if (missingFileStatError(error)) return { changed: false };
+		return { changed: false, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export function hasSingleOutputChangedSinceSnapshot(
+	outputPath: string | undefined,
+	beforeRun: SingleOutputSnapshot | undefined,
+): boolean | undefined {
+	if (!outputPath) return undefined;
+	const inspected = inspectSingleOutputChange(outputPath, beforeRun);
+	return inspected.error ? undefined : inspected.changed;
+}
+
+function persistSingleOutput(
+	outputPath: string | undefined,
+	fullOutput: string,
+	expectedClaimPath?: string,
+): { savedPath?: string; error?: string; fatalError?: boolean } {
+	if (!outputPath) return {};
+	try {
+		const claimError = outputClaimError(outputPath, expectedClaimPath);
+		if (claimError) return { error: claimError, fatalError: true };
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, fullOutput, "utf-8");
+		return { savedPath: outputPath };
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+	expectedClaimPath?: string,
+): { fullOutput: string; savedPath?: string; saveError?: string; fatalError?: boolean } {
+	if (!outputPath) return { fullOutput: fallbackOutput };
+	const claimError = outputClaimError(outputPath, expectedClaimPath);
+	if (claimError) return { fullOutput: fallbackOutput, saveError: claimError, fatalError: true };
+
+	const changedSinceStart = inspectSingleOutputChange(outputPath, beforeRun);
+	if (changedSinceStart.error) {
+		return {
+			fullOutput: fallbackOutput,
+			saveError: `Failed to inspect output file: ${changedSinceStart.error}`,
+		};
+	}
+
+	if (changedSinceStart.changed) {
+		try {
+			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+		} catch (error) {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput, expectedClaimPath);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
+	return { fullOutput: fallbackOutput, saveError: save.error, ...(save.fatalError ? { fatalError: true } : {}) };
+}
+
+export function finalizeSingleOutput(params: {
+	fullOutput: string;
+	truncatedOutput?: string;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	exitCode: number;
+	/** Keep the saved-output reference when a post-run acceptance gate rejects an otherwise completed child. */
+	preserveSavedOutput?: boolean;
+	savedPath?: string;
+	outputReference?: SavedOutputReference;
+	saveError?: string;
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
+	let displayOutput = params.truncatedOutput || params.fullOutput;
+	if ((params.exitCode === 0 || params.preserveSavedOutput) && params.savedPath) {
+		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
+		if (params.outputMode === "file-only") {
+			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+		}
+		if (!displayOutput.includes(outputReference.message)) displayOutput += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.savedPath, outputReference };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
+	}
+	return { displayOutput };
+}

package/node_modules/pi-subagents/src/runs/shared/spawn-budget.ts

@@ -0,0 +1,128 @@
+import {
+	resolveMaxSubagentSpawnsPerSession,
+	type ExtensionConfig,
+	type SpawnBudgetSnapshot,
+	type SubagentState,
+} from "../../shared/types.ts";
+
+const MAX_GRANT_HISTORY = 20;
+
+function sessionState(state: SubagentState, config: ExtensionConfig, sessionId: string | null) {
+	let counters = state.subagentSpawns;
+	if (!counters || counters.sessionId !== sessionId) {
+		counters = {
+			sessionId,
+			count: 0,
+			configuredLimit: resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null,
+			granted: 0,
+			grantHistory: [],
+		};
+		state.subagentSpawns = counters;
+	}
+	if (counters.configuredLimit === undefined) {
+		counters.configuredLimit = resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null;
+	}
+	counters.granted ??= 0;
+	counters.grantHistory ??= [];
+	return counters;
+}
+
+export function getSpawnBudgetSnapshot(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null = state.currentSessionId,
+): SpawnBudgetSnapshot {
+	const counters = sessionState(state, config, sessionId);
+	const configuredLimit = counters.configuredLimit ?? null;
+	const granted = configuredLimit === null ? 0 : counters.granted ?? 0;
+	const limit = configuredLimit === null ? null : configuredLimit + granted;
+	return {
+		used: counters.count,
+		configuredLimit,
+		granted,
+		limit,
+		remaining: limit === null ? null : Math.max(0, limit - counters.count),
+		grantRemaining: configuredLimit === null ? null : Math.max(0, configuredLimit - granted),
+		grantHistory: [...(counters.grantHistory ?? [])],
+	};
+}
+
+export function formatSpawnBudgetSummary(snapshot: SpawnBudgetSnapshot): string {
+	if (snapshot.limit === null) return "unlimited";
+	return `${snapshot.used}/${snapshot.limit} used, ${snapshot.remaining} remaining (configured ${snapshot.configuredLimit}; granted ${snapshot.granted}; grant allowance ${snapshot.grantRemaining})`;
+}
+
+export function formatSpawnBudget(snapshot: SpawnBudgetSnapshot): string {
+	return `Spawn budget: ${formatSpawnBudgetSummary(snapshot)}`;
+}
+
+export function preflightSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null,
+	requested: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
+	if (requested <= 0 || snapshot.limit === null || requested <= (snapshot.remaining ?? 0)) return { snapshot };
+	return {
+		snapshot,
+		error: `Subagent spawn limit reached for this session (${snapshot.used}/${snapshot.limit} used, ${requested} requested). ${snapshot.remaining} remaining; the declared run cannot fit, so no children were started. Grant budget explicitly from the root interactive session or start a new session.`,
+	};
+}
+
+export function reserveSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null,
+	requested: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const checked = preflightSpawnBudget(state, config, sessionId, requested);
+	if (checked.error || requested <= 0 || checked.snapshot.limit === null) return checked;
+	state.subagentSpawns!.count += requested;
+	return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
+}
+
+export function preflightSpawnBudgetGrant(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string,
+	additional: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
+	if (!Number.isInteger(additional) || additional <= 0) {
+		return { snapshot, error: "action='grant-spawn-budget' requires additional to be a positive integer." };
+	}
+	if (snapshot.configuredLimit === null || snapshot.limit === null) {
+		return { snapshot, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
+	}
+	if (additional > (snapshot.grantRemaining ?? 0)) {
+		return {
+			snapshot,
+			error: `Spawn budget grant rejected: ${additional} requested but only ${snapshot.grantRemaining} of the original configured limit remains grantable.`,
+		};
+	}
+	return { snapshot };
+}
+
+export function grantSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string,
+	additional: number,
+	now = Date.now(),
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const checked = preflightSpawnBudgetGrant(state, config, sessionId, additional);
+	if (checked.error) return checked;
+	const before = checked.snapshot;
+	if (before.limit === null) {
+		return { snapshot: before, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
+	}
+	const counters = state.subagentSpawns!;
+	counters.granted = (counters.granted ?? 0) + additional;
+	const limit = before.limit + additional;
+	counters.grantHistory = [
+		...(counters.grantHistory ?? []),
+		{ sessionId, amount: additional, grantedAt: now, previousLimit: before.limit, limit },
+	].slice(-MAX_GRANT_HISTORY);
+	return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
+}

package/node_modules/pi-subagents/src/runs/shared/structured-output.ts

@@ -0,0 +1,223 @@
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as os from "node:os";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
+import type { JsonSchemaObject } from "../../shared/types.ts";
+import type { ResolvedAcceptanceReportMode } from "./acceptance.ts";
+
+export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
+export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+export const STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE";
+export const STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED";
+export const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
+export const MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR = "Missing acceptanceReport in structured_output call; acceptance.report is \"on\".";
+
+export interface StructuredOutputRuntime {
+	schema: JsonSchemaObject;
+	schemaPath: string;
+	outputPath: string;
+	acceptanceReportPath?: string;
+	acceptanceReportRequired?: boolean;
+}
+
+const SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
+const SCHEMA_SINGLE_KEYWORDS = ["additionalItems", "additionalProperties", "contains", "not", "propertyNames", "if", "then", "else", "unevaluatedItems", "unevaluatedProperties", "contentSchema"] as const;
+const SCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
+
+function rewriteLocalJsonPointerRefs(schema: unknown, pointerPrefix: string, inheritsWrapperResource = true): unknown {
+	if (typeof schema === "boolean" || !schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
+	const source = schema as Record<string, unknown>;
+	const rewritten: Record<string, unknown> = { ...source };
+	const sharesWrapperResource = inheritsWrapperResource && typeof source.$id !== "string";
+	if (sharesWrapperResource) {
+		for (const keyword of ["$ref", "$dynamicRef", "$recursiveRef"] as const) {
+			const ref = source[keyword];
+			if (ref === "#") rewritten[keyword] = pointerPrefix;
+			else if (typeof ref === "string" && ref.startsWith("#/")) rewritten[keyword] = `${pointerPrefix}${ref.slice(1)}`;
+		}
+	}
+	for (const keyword of SCHEMA_MAP_KEYWORDS) {
+		const entries = source[keyword];
+		if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
+		rewritten[keyword] = Object.fromEntries(Object.entries(entries).map(([name, nested]) => [
+			name,
+			rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource),
+		]));
+	}
+	const items = source.items;
+	if (Array.isArray(items)) rewritten.items = items.map((nested) => rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource));
+	else if (items !== undefined) rewritten.items = rewriteLocalJsonPointerRefs(items, pointerPrefix, sharesWrapperResource);
+	for (const keyword of SCHEMA_SINGLE_KEYWORDS) {
+		if (source[keyword] !== undefined) rewritten[keyword] = rewriteLocalJsonPointerRefs(source[keyword], pointerPrefix, sharesWrapperResource);
+	}
+	for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+		if (Array.isArray(source[keyword])) rewritten[keyword] = source[keyword].map((nested) => rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource));
+	}
+	const dependencies = source.dependencies;
+	if (dependencies && typeof dependencies === "object" && !Array.isArray(dependencies)) {
+		rewritten.dependencies = Object.fromEntries(Object.entries(dependencies).map(([name, nested]) => [
+			name,
+			Array.isArray(nested) ? nested : rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource),
+		]));
+	}
+	return rewritten;
+}
+
+export function createStructuredOutputToolParameters(schema: JsonSchemaObject, options: { acceptanceReport?: "optional" | "required" } = {}): JsonSchemaObject {
+	return {
+		type: "object",
+		properties: {
+			value: rewriteLocalJsonPointerRefs(schema, "#/properties/value"),
+			...(options.acceptanceReport ? { acceptanceReport: { type: "object" } } : {}),
+		},
+		required: ["value", ...(options.acceptanceReport === "required" ? ["acceptanceReport"] : [])],
+		additionalProperties: false,
+	};
+}
+
+interface CompiledJsonSchema {
+	Check(value: unknown): boolean;
+	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
+}
+
+type CompileJsonSchema = (schema: unknown) => CompiledJsonSchema;
+
+let cachedCompile: Promise<CompileJsonSchema> | undefined;
+
+export async function resolveCompileFromPackageRoot(packageRoot: string): Promise<CompileJsonSchema | undefined> {
+	const requireFromRoot = createRequire(path.join(packageRoot, "package.json"));
+	const resolved = requireFromRoot.resolve("typebox/compile");
+	const mod = (await import(pathToFileURL(resolved).href)) as { Compile?: unknown };
+	return typeof mod.Compile === "function" ? (mod.Compile as CompileJsonSchema) : undefined;
+}
+
+async function importCompile(): Promise<CompileJsonSchema> {
+	const failures: string[] = [];
+	try {
+		const mod = (await import("typebox/compile")) as { Compile?: unknown };
+		if (typeof mod.Compile === "function") return mod.Compile as CompileJsonSchema;
+		failures.push("typebox/compile did not export a Compile function");
+	} catch (error) {
+		failures.push(`direct import failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const packageRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV];
+	if (packageRoot) {
+		try {
+			const compile = await resolveCompileFromPackageRoot(packageRoot);
+			if (compile) return compile;
+			failures.push("Pi package root typebox/compile did not export a Compile function");
+		} catch (error) {
+			failures.push(`Pi package root import failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	} else {
+		failures.push(`${PI_CODING_AGENT_PACKAGE_ROOT_ENV} is not set`);
+	}
+	throw new Error(`Cannot load typebox/compile for structured output validation (${failures.join("; ")})`);
+}
+
+function loadCompile(): Promise<CompileJsonSchema> {
+	if (!cachedCompile) {
+		cachedCompile = importCompile().catch((error) => {
+			cachedCompile = undefined;
+			throw error;
+		});
+	}
+	return cachedCompile;
+}
+
+export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
+	if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+		throw new Error(`${label} must be a JSON Schema object.`);
+	}
+}
+
+export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string, options: { acceptanceReport?: ResolvedAcceptanceReportMode } = {}): StructuredOutputRuntime {
+	assertJsonSchemaObject(schema);
+	const rootDir = baseDir ?? os.tmpdir();
+	fs.mkdirSync(rootDir, { recursive: true });
+	const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
+	const schemaPath = path.join(dir, "schema.json");
+	const outputPath = path.join(dir, "output.json");
+	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
+	return {
+		schema,
+		schemaPath,
+		outputPath,
+		...(options.acceptanceReport && options.acceptanceReport !== "off"
+			? { acceptanceReportPath: path.join(dir, "acceptance-report.json"), acceptanceReportRequired: options.acceptanceReport === "required" }
+			: {}),
+	};
+}
+
+export async function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): Promise<{ status: "valid" } | { status: "invalid"; message: string }> {
+	const compile = await loadCompile();
+	let validator: CompiledJsonSchema;
+	try {
+		validator = compile(schema);
+	} catch (error) {
+		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (validator.Check(value)) return { status: "valid" };
+	const errors = [...validator.Errors(value)]
+		.slice(0, 8)
+		.map((error) => {
+			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+			return `${pathText}: ${error.message}`;
+		});
+	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
+}
+
+export async function readStructuredOutput(runtime: StructuredOutputRuntime): Promise<{ value?: unknown; error?: string }> {
+	if (!fs.existsSync(runtime.outputPath)) {
+		return { error: MISSING_STRUCTURED_OUTPUT_CALL_ERROR };
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+	} catch (error) {
+		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	try {
+		const validation = await validateStructuredOutputValue(runtime.schema, value);
+		if (validation.status === "invalid") return { error: `Structured output validation failed: ${validation.message}` };
+	} catch (error) {
+		return { error: `Failed to validate structured output: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	return { value };
+}
+
+export function readStructuredOutputAcceptanceReport(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
+	if (!runtime.acceptanceReportPath) return {};
+	if (!fs.existsSync(runtime.acceptanceReportPath)) {
+		return runtime.acceptanceReportRequired ? { error: MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR } : {};
+	}
+	try {
+		return { value: JSON.parse(fs.readFileSync(runtime.acceptanceReportPath, "utf-8")) as unknown };
+	} catch (error) {
+		return { error: `Failed to read structured output acceptance report: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
+export function clearStructuredOutputCaptures(runtime: StructuredOutputRuntime): string | undefined {
+	let cleanupError: string | undefined;
+	for (const filePath of [runtime.outputPath, runtime.acceptanceReportPath]) {
+		if (!filePath) continue;
+		try {
+			if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+		} catch (error) {
+			cleanupError ??= `Failed to clear stale structured output capture ${filePath}: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+	return cleanupError;
+}
+
+export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {
+	if (!runtime) return;
+	try {
+		fs.rmSync(path.dirname(runtime.schemaPath), { recursive: true, force: true });
+	} catch {
+		// Best-effort temp cleanup.
+	}
+}