pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/runs/shared/dynamic-fanout.ts

@@ -0,0 +1,297 @@
+import type { DynamicParallelStep, ParallelTaskItem } from "../../shared/settings.ts";
+import type { ArtifactPaths, ChainOutputMap, JsonSchemaObject, SingleResult } from "../../shared/types.ts";
+import { getSingleResultOutput } from "../../shared/utils.ts";
+import { validateStructuredOutputValue } from "./structured-output.ts";
+
+export class DynamicFanoutError extends Error {}
+
+export interface DynamicFanoutConfig {
+	maxItems?: number;
+	allowRunnerFields?: boolean;
+}
+
+export interface DynamicMaterializedItem {
+	index: number;
+	key: string;
+	idKey: string;
+	item: unknown;
+}
+
+export interface DynamicCollectedResult {
+	key: string;
+	index: number;
+	item: unknown;
+	agent: string;
+	exitCode: number | null;
+	text: string;
+	structured?: unknown;
+	error?: string;
+	timedOut?: boolean;
+	stopped?: boolean;
+	outputPath?: string;
+	artifactPaths?: ArtifactPaths;
+}
+
+export interface DynamicMaterializedGroup {
+	items: DynamicMaterializedItem[];
+	parallel: ParallelTaskItem[];
+	collectedOnEmpty?: DynamicCollectedResult[];
+}
+
+const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ITEM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ITEM_REF_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)(?:\.([^{}]+))?\}/g;
+const RESERVED_TEMPLATE_NAMES = new Set(["task", "previous", "chain_dir", "outputs"]);
+const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance", "agentContract", "gateOn"]);
+const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
+const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
+const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
+const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
+	...DYNAMIC_PARALLEL_KEYS,
+	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
+	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
+	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
+]);
+const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
+
+export function isSafeOutputName(name: string): boolean {
+	return SAFE_OUTPUT_NAME_PATTERN.test(name);
+}
+
+export function assertJsonPointer(pointer: string, label: string): void {
+	if (pointer === "") return;
+	if (!pointer.startsWith("/")) {
+		throw new DynamicFanoutError(`${label} must be a JSON Pointer starting with '/'.`);
+	}
+	for (const segment of pointer.slice(1).split("/")) {
+		if (/~(?![01])/.test(segment)) {
+			throw new DynamicFanoutError(`${label} contains invalid JSON Pointer escape.`);
+		}
+	}
+}
+
+function decodePointerSegment(segment: string): string {
+	return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+export function resolveJsonPointer(value: unknown, pointer: string, label: string): unknown {
+	assertJsonPointer(pointer, label);
+	if (pointer === "") return value;
+	let current = value;
+	for (const rawSegment of pointer.slice(1).split("/")) {
+		const segment = decodePointerSegment(rawSegment);
+		if (Array.isArray(current)) {
+			if (!/^(0|[1-9][0-9]*)$/.test(segment)) {
+				throw new DynamicFanoutError(`${label} segment '${segment}' does not address an array index.`);
+			}
+			const index = Number(segment);
+			if (index >= current.length) throw new DynamicFanoutError(`${label} does not exist.`);
+			current = current[index];
+			continue;
+		}
+		if (!current || typeof current !== "object") {
+			throw new DynamicFanoutError(`${label} does not exist.`);
+		}
+		const record = current as Record<string, unknown>;
+		if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+			throw new DynamicFanoutError(`${label} does not exist.`);
+		}
+		current = record[segment];
+	}
+	return current;
+}
+
+function scalarToKey(value: unknown, label: string): string {
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+		const key = String(value);
+		if (!key.trim()) throw new DynamicFanoutError(`${label} resolved to an empty key.`);
+		if (/[\u0000-\u001F\u007F]/.test(key)) throw new DynamicFanoutError(`${label} resolved to an unsafe key.`);
+		if (key.length > 200) throw new DynamicFanoutError(`${label} resolved to a key longer than 200 characters.`);
+		return key;
+	}
+	throw new DynamicFanoutError(`${label} must resolve to a string, number, or boolean.`);
+}
+
+export function normalizeItemKeyForId(key: string): string {
+	const normalized = key
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 80);
+	return normalized || "item";
+}
+
+function valueToTemplateText(value: unknown, reference: string): string {
+	if (value === undefined) throw new DynamicFanoutError(`Unresolved item reference '${reference}'.`);
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	return JSON.stringify(value);
+}
+
+function resolveItemPath(item: unknown, pathText: string | undefined, reference: string): unknown {
+	if (!pathText) return item;
+	const pointer = `/${pathText.split(".").map((segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+	return resolveJsonPointer(item, pointer, reference);
+}
+
+export function resolveItemTemplate(template: string, itemName: string, item: unknown): string {
+	return template.replace(ITEM_REF_PATTERN, (raw, name: string, pathText: string | undefined) => {
+		if (name !== itemName) return raw;
+		if (pathText !== undefined && (!pathText.trim() || pathText.includes(".."))) {
+			throw new DynamicFanoutError(`Invalid item reference '${raw}'.`);
+		}
+		return valueToTemplateText(resolveItemPath(item, pathText, raw), raw);
+	});
+}
+
+function assertOnlyKeys(value: unknown, allowed: Set<string>, label: string): void {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new DynamicFanoutError(`${label} must be an object.`);
+	for (const key of Object.keys(value)) {
+		if (!allowed.has(key)) throw new DynamicFanoutError(`${label} does not support field '${key}'.`);
+	}
+}
+
+export function assertNoUnresolvedItemReferences(template: string, itemName: string, label: string): void {
+	for (const match of template.matchAll(/\{([^{}]*)\}/g)) {
+		const raw = match[0]!;
+		const reference = match[1]!;
+		if (reference === itemName || reference.startsWith(`${itemName}.`)) {
+			if (!ITEM_REF_PATTERN.test(raw) || reference === `${itemName}.` || reference.includes("..")) {
+				throw new DynamicFanoutError(`Invalid item reference '${raw}' in ${label}.`);
+			}
+			ITEM_REF_PATTERN.lastIndex = 0;
+			continue;
+		}
+		ITEM_REF_PATTERN.lastIndex = 0;
+		const name = reference.match(/^[A-Za-z_][A-Za-z0-9_]*/)?.[0];
+		if (name === itemName) throw new DynamicFanoutError(`Invalid item reference '${raw}' in ${label}.`);
+		if (name && RESERVED_TEMPLATE_NAMES.has(name)) continue;
+		if (name) throw new DynamicFanoutError(`Unsupported template reference '${raw}' in ${label}.`);
+	}
+	ITEM_REF_PATTERN.lastIndex = 0;
+	if (template.includes(`{${itemName}.}`) || new RegExp(`\\{${itemName}(?:\\.|$)[^}]*$`).test(template)) {
+		throw new DynamicFanoutError(`Invalid item reference in ${label}.`);
+	}
+}
+
+export function hasDynamicFanoutFields(step: unknown): boolean {
+	return !!step && typeof step === "object" && !Array.isArray(step)
+		&& (Object.prototype.hasOwnProperty.call(step, "expand") || Object.prototype.hasOwnProperty.call(step, "collect"));
+}
+
+export function validateDynamicStepShape(step: DynamicParallelStep, stepIndex: number, config: DynamicFanoutConfig = {}): void {
+	const prefix = `Dynamic chain step ${stepIndex + 1}`;
+	assertOnlyKeys(step, config.allowRunnerFields ? RUNNER_DYNAMIC_STEP_KEYS : DYNAMIC_STEP_KEYS, prefix);
+	if (!step.expand || !step.expand.from) throw new DynamicFanoutError(`${prefix} requires expand.from.`);
+	assertOnlyKeys(step.expand, DYNAMIC_EXPAND_KEYS, `${prefix} expand`);
+	assertOnlyKeys(step.expand.from, DYNAMIC_EXPAND_FROM_KEYS, `${prefix} expand.from`);
+	if (!isSafeOutputName(step.expand.from.output)) throw new DynamicFanoutError(`${prefix} has invalid expand.from.output '${step.expand.from.output}'.`);
+	assertJsonPointer(step.expand.from.path, `${prefix} expand.from.path`);
+	if (step.expand.key !== undefined) assertJsonPointer(step.expand.key, `${prefix} expand.key`);
+	const itemName = step.expand.item ?? "item";
+	if (!ITEM_NAME_PATTERN.test(itemName)) throw new DynamicFanoutError(`${prefix} has invalid expand.item '${itemName}'.`);
+	if (step.expand.maxItems === undefined && config.maxItems === undefined) {
+		throw new DynamicFanoutError(`${prefix} requires expand.maxItems or config.chain.dynamicFanout.maxItems.`);
+	}
+	if (step.expand.maxItems !== undefined && (!Number.isInteger(step.expand.maxItems) || step.expand.maxItems < 0)) {
+		throw new DynamicFanoutError(`${prefix} expand.maxItems must be an integer >= 0.`);
+	}
+	if (config.maxItems !== undefined && (!Number.isInteger(config.maxItems) || config.maxItems < 0)) {
+		throw new DynamicFanoutError("config.chain.dynamicFanout.maxItems must be an integer >= 0.");
+	}
+	if (!step.parallel || Array.isArray(step.parallel)) throw new DynamicFanoutError(`${prefix} requires a single parallel template object and cannot mix dynamic expand/collect with static parallel arrays.`);
+	assertOnlyKeys(step.parallel, config.allowRunnerFields ? RUNNER_DYNAMIC_PARALLEL_KEYS : DYNAMIC_PARALLEL_KEYS, `${prefix} parallel`);
+	if ("expand" in (step.parallel as object)) throw new DynamicFanoutError(`${prefix} does not support nested dynamic fanout.`);
+	if (!step.parallel.agent) throw new DynamicFanoutError(`${prefix} parallel.agent is required.`);
+	if (!step.collect?.as || !isSafeOutputName(step.collect.as)) throw new DynamicFanoutError(`${prefix} requires collect.as with a safe output name.`);
+	assertOnlyKeys(step.collect, DYNAMIC_COLLECT_KEYS, `${prefix} collect`);
+	for (const [label, template] of [
+		["parallel.task", step.parallel.task],
+		["parallel.label", step.parallel.label],
+	] as const) {
+		if (template) assertNoUnresolvedItemReferences(template, itemName, `${prefix} ${label}`);
+	}
+}
+
+export function resolveDynamicFanoutItems(step: DynamicParallelStep, outputs: ChainOutputMap, stepIndex: number, config: DynamicFanoutConfig = {}): DynamicMaterializedItem[] {
+	validateDynamicStepShape(step, stepIndex, config);
+	const sourceName = step.expand.from.output;
+	const source = outputs[sourceName];
+	if (!source) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} references unknown output '${sourceName}'.`);
+	if (source.structured === undefined) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} requires structured output '${sourceName}'.`);
+	const value = resolveJsonPointer(source.structured, step.expand.from.path, `Dynamic chain step ${stepIndex + 1} expand.from.path`);
+	if (!Array.isArray(value)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} expand.from.path must resolve to an array.`);
+	const maxItems = step.expand.maxItems ?? config.maxItems;
+	if (maxItems === undefined) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} requires an effective maxItems.`);
+	if (value.length > maxItems) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} resolved ${value.length} items, exceeding maxItems ${maxItems}.`);
+	const seen = new Set<string>();
+	const seenIds = new Set<string>();
+	return value.map((item, index) => {
+		const key = step.expand.key === undefined
+			? String(index)
+			: scalarToKey(resolveJsonPointer(item, step.expand.key, `Dynamic chain step ${stepIndex + 1} expand.key`), `Dynamic chain step ${stepIndex + 1} expand.key`);
+		if (seen.has(key)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} produced duplicate item key '${key}'.`);
+		seen.add(key);
+		const idKey = normalizeItemKeyForId(key);
+		if (seenIds.has(idKey)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} produced colliding item id '${idKey}'.`);
+		seenIds.add(idKey);
+		return { index, key, idKey, item };
+	});
+}
+
+export function materializeDynamicParallelStep(step: DynamicParallelStep, outputs: ChainOutputMap, stepIndex: number, config: DynamicFanoutConfig = {}): DynamicMaterializedGroup {
+	const items = resolveDynamicFanoutItems(step, outputs, stepIndex, config);
+	if (items.length === 0) {
+		if ((step.expand.onEmpty ?? "skip") === "fail") {
+			throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} source array is empty.`);
+		}
+		return { items, parallel: [], collectedOnEmpty: [] };
+	}
+	const itemName = step.expand.item ?? "item";
+	const parallel = items.map((entry) => {
+		const task = resolveItemTemplate(step.parallel.task ?? "{previous}", itemName, entry.item);
+		const label = step.parallel.label ? resolveItemTemplate(step.parallel.label, itemName, entry.item) : undefined;
+		return {
+			...step.parallel,
+			task,
+			...(label !== undefined ? { label } : {}),
+		};
+	});
+	return { items, parallel };
+}
+
+export function collectDynamicResults(
+	step: DynamicParallelStep,
+	items: DynamicMaterializedItem[],
+	results: Array<Pick<SingleResult, "agent" | "error" | "timedOut" | "stopped" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { exitCode: number | null; output?: string; finalOutput?: string }>,
+): DynamicCollectedResult[] {
+	return items.map((entry, index) => {
+		const result = results[index];
+		const text = result
+			? ("output" in result && typeof result.output === "string" ? result.output : getSingleResultOutput(result as SingleResult))
+			: "";
+		return {
+			key: entry.key,
+			index: entry.index,
+			item: entry.item,
+			agent: result?.agent ?? step.parallel.agent,
+			exitCode: result?.exitCode ?? null,
+			text,
+			...(result?.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+			...(result?.error ? { error: result.error } : {}),
+			...(result?.timedOut ? { timedOut: true } : {}),
+			...(result?.stopped ? { stopped: true } : {}),
+			...(result?.savedOutputPath ? { outputPath: result.savedOutputPath } : {}),
+			...(result?.artifactPaths ? { artifactPaths: result.artifactPaths } : {}),
+		};
+	});
+}
+
+export async function validateDynamicCollection(schema: JsonSchemaObject | undefined, value: DynamicCollectedResult[]): Promise<void> {
+	if (!schema) return;
+	const validation = await validateStructuredOutputValue(schema, value);
+	if (validation.status === "invalid") {
+		throw new DynamicFanoutError(`Collected output validation failed: ${validation.message}`);
+	}
+}

package/node_modules/pi-subagents/src/runs/shared/extension-bindings.ts

@@ -0,0 +1,78 @@
+export const PI_SUBAGENT_EXTENSION_BINDINGS_ENV = "PI_SUBAGENT_EXTENSION_BINDINGS";
+export const MAX_EXTENSION_BINDING_NAMESPACES = 16;
+export const MAX_EXTENSION_BINDINGS_BYTES = 16 * 1024;
+export const MAX_EXTENSION_BINDINGS_DEPTH = 16;
+export const MAX_EXTENSION_BINDINGS_PROPERTIES = 256;
+
+const EXTENSION_BINDING_NAMESPACE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62})\/[1-9][0-9]{0,8}$/;
+
+export type ExtensionBindingJson = null | boolean | number | string | ReadonlyArray<ExtensionBindingJson> | { readonly [key: string]: ExtensionBindingJson };
+export type ExtensionBindings = Readonly<Record<string, ExtensionBindingJson>>;
+
+export interface NormalizedExtensionBindings {
+	value: ExtensionBindings;
+	json: string;
+}
+
+function canonicalizeJson(value: unknown, path: string, depth: number, seen: Set<object>, propertyCount: { value: number }): ExtensionBindingJson {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${path} must contain only finite JSON numbers.`);
+		return value;
+	}
+	if (typeof value !== "object") throw new Error(`${path} must contain only plain JSON values.`);
+	if (depth > MAX_EXTENSION_BINDINGS_DEPTH) throw new Error(`${path} exceeds the maximum nesting depth of ${MAX_EXTENSION_BINDINGS_DEPTH}.`);
+	if (seen.has(value)) throw new Error(`${path} must not contain cycles.`);
+	seen.add(value);
+	try {
+		if (Array.isArray(value)) {
+			const output: ExtensionBindingJson[] = [];
+			for (let index = 0; index < value.length; index++) {
+				if (!Object.prototype.hasOwnProperty.call(value, index)) throw new Error(`${path} must not contain sparse arrays.`);
+				output.push(canonicalizeJson(value[index], `${path}[${index}]`, depth + 1, seen, propertyCount));
+			}
+			return Object.freeze(output);
+		}
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw new Error(`${path} must contain only plain JSON objects.`);
+		if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(`${path} must not contain symbol keys.`);
+		const descriptors = Object.getOwnPropertyDescriptors(value);
+		const output: Record<string, ExtensionBindingJson> = {};
+		for (const key of Object.keys(descriptors).sort()) {
+			const descriptor = descriptors[key]!;
+			if (!descriptor.enumerable || !("value" in descriptor)) throw new Error(`${path}.${key} must be an enumerable data property.`);
+			propertyCount.value += 1;
+			if (propertyCount.value > MAX_EXTENSION_BINDINGS_PROPERTIES) throw new Error(`extensionBindings exceeds ${MAX_EXTENSION_BINDINGS_PROPERTIES} total properties.`);
+			Object.defineProperty(output, key, { value: canonicalizeJson(descriptor.value, `${path}.${key}`, depth + 1, seen, propertyCount), enumerable: true, writable: false, configurable: false });
+		}
+		return Object.freeze(output);
+	} finally {
+		seen.delete(value);
+	}
+}
+
+export function normalizeExtensionBindings(input: unknown): NormalizedExtensionBindings | undefined {
+	if (input === undefined) return undefined;
+	if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("extensionBindings must be a plain JSON object.");
+	const prototype = Object.getPrototypeOf(input);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error("extensionBindings must be a plain JSON object.");
+	const keys = Object.keys(input);
+	if (keys.length > MAX_EXTENSION_BINDING_NAMESPACES) throw new Error(`extensionBindings supports at most ${MAX_EXTENSION_BINDING_NAMESPACES} namespaces.`);
+	for (const key of keys) {
+		if (!EXTENSION_BINDING_NAMESPACE.test(key)) throw new Error(`extensionBindings namespace '${key}' must use a package-like name followed by '/<positive-version>'.`);
+	}
+	const value = canonicalizeJson(input, "extensionBindings", 0, new Set(), { value: 0 }) as ExtensionBindings;
+	const json = JSON.stringify(value);
+	const bytes = Buffer.byteLength(json, "utf8");
+	if (bytes > MAX_EXTENSION_BINDINGS_BYTES) throw new Error(`extensionBindings canonical JSON is ${bytes} bytes; maximum is ${MAX_EXTENSION_BINDINGS_BYTES}.`);
+	return { value, json };
+}
+
+export function encodeExtensionBindings(input: ExtensionBindings | undefined): string | undefined {
+	return input === undefined ? undefined : normalizeExtensionBindings(input)!.json;
+}
+
+export function omitExtensionBindingsEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const { [PI_SUBAGENT_EXTENSION_BINDINGS_ENV]: _extensionBindings, ...sanitized } = env;
+	return sanitized;
+}

package/node_modules/pi-subagents/src/runs/shared/external-cli-contract.ts

@@ -0,0 +1,167 @@
+import type {
+	ExternalCliReceiptMetadata,
+	ExternalCliCapabilityNarrowing,
+	ExternalCliRunnerStatus,
+	ExternalProcessStatus,
+} from "../../shared/types.ts";
+
+const UNSUPPORTED = {
+	steer: "The one-shot stdin adapter closes input after launch and cannot accept live steer messages.",
+	resume: "The one-shot stdin adapter has no durable external session identity.",
+	structuredOutput: "The generic external CLI adapter does not parse a trusted structured result.",
+	toolEvents: "The generic external CLI adapter treats stdout as untrusted text, not native Pi tool events.",
+	supervisor: "The generic external CLI adapter has no trusted supervisor event transport.",
+	forkContext: "Native Pi fork context is not available without an adapter-owned handoff artifact.",
+	extensionBindings: "Native Pi extension bindings are never passed to external runners.",
+} as const;
+
+const CAPABILITY_KEYS = new Set(Object.keys(UNSUPPORTED));
+const PROMPT_FILE_UNSUPPORTED = {
+	...UNSUPPORTED,
+	steer: "The one-shot prompt-file adapter closes input after launch and cannot accept live steer messages.",
+	resume: "The one-shot prompt-file adapter does not retain a durable external session identity.",
+} as const;
+
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS = [
+	"codex-exec",
+	"codex-exec-writer",
+	"claude-code",
+	"claude-code-writer",
+	"cursor-agent",
+	"cursor-agent-writer",
+] as const;
+export type CodeOwnedExternalCliAdapterId = typeof CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS[number];
+
+const CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET = new Set<string>(CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS);
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL = CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS.map((id) => `'${id}'`).join(", ");
+
+export function isCodeOwnedExternalCliAdapterId(value: unknown): value is CodeOwnedExternalCliAdapterId {
+	return typeof value === "string" && CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET.has(value);
+}
+
+const RESERVED_READ_ONLY_ADAPTERS = [
+	{ name: "claude-code", writer: "claude-code-writer", access: "file-write" },
+	{ name: "codex-exec", writer: "codex-exec-writer", access: "workspace-write" },
+	{ name: "cursor-agent", writer: "cursor-agent-writer", access: "workspace-write" },
+] as const;
+
+export function validateCodeOwnedProfileRunner(
+	agent: {
+		name: string;
+		localName?: string;
+		aliases?: readonly string[];
+		runner?: { type: string; adapter?: string };
+	},
+): string | undefined {
+	const selectionNames = [agent.name, ...(agent.localName ? [agent.localName] : []), ...(agent.aliases ?? [])];
+	for (const adapter of RESERVED_READ_ONLY_ADAPTERS) {
+		if (selectionNames.includes(adapter.name) && !(agent.runner?.type === "external-cli" && agent.runner.adapter === adapter.name)) {
+			return `Selection name '${adapter.name}' is reserved for the read-only '${adapter.name}' adapter. Use '${adapter.writer}' for explicit ${adapter.access} access.`;
+		}
+	}
+	return undefined;
+}
+
+export function parseExternalCliCapabilityNarrowing(value: unknown, label: string): ExternalCliCapabilityNarrowing | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const input = value as Record<string, unknown>;
+	const unknown = Object.keys(input).filter((key) => !CAPABILITY_KEYS.has(key));
+	if (unknown.length > 0) throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+	for (const [key, setting] of Object.entries(input)) {
+		if (setting !== false) throw new Error(`${label}.${key} may only be false; user config cannot widen code-owned external adapter capabilities.`);
+	}
+	return input as ExternalCliCapabilityNarrowing;
+}
+
+export function resolveExternalCliRunnerStatus(input: {
+	adapter?: CodeOwnedExternalCliAdapterId;
+	command: string;
+	args?: string[];
+	promptDelivery?: "stdin";
+	capabilities?: ExternalCliCapabilityNarrowing;
+}): ExternalCliRunnerStatus {
+	const codexExec = input.adapter === "codex-exec";
+	const codexExecWriter = input.adapter === "codex-exec-writer";
+	const claudeCode = input.adapter === "claude-code";
+	const claudeCodeWriter = input.adapter === "claude-code-writer";
+	const cursorAgent = input.adapter === "cursor-agent";
+	const cursorAgentWriter = input.adapter === "cursor-agent-writer";
+	const cursor = cursorAgent || cursorAgentWriter;
+	const unsupported = cursor ? PROMPT_FILE_UNSUPPORTED : UNSUPPORTED;
+	return {
+		type: "external-cli",
+		command: input.command,
+		args: input.args ?? [],
+		promptDelivery: cursor ? "prompt-file" : input.promptDelivery ?? "stdin",
+		adapter: { id: input.adapter ?? "external-cli", version: 1, executionMode: cursor ? "one-shot-prompt-file" : "one-shot-stdin" },
+		...(codexExec ? { safety: { sandbox: "read-only" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
+		...(codexExecWriter ? { safety: { access: "workspace-write" as const, sandbox: "workspace-write" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
+		...(claudeCode ? { safety: { access: "read-only" as const, authentication: "existing-cli-required" as const, permissionMode: "plan" as const, tools: "none" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
+		...(claudeCodeWriter ? { safety: { access: "workspace-write" as const, authentication: "existing-cli-required" as const, permissionMode: "acceptEdits" as const, tools: "Read,Write,Edit,Glob,Grep" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
+		...(cursorAgent ? { safety: { access: "read-only" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "ask" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
+		...(cursorAgentWriter ? { safety: { access: "workspace-write" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "print" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
+		capabilities: {
+			stop: true,
+			steer: false,
+			resume: false,
+			structuredOutput: false,
+			toolEvents: false,
+			supervisor: "unsupported",
+			forkContext: false,
+			extensionBindings: false,
+		},
+		unsupportedReasons: unsupported,
+		nonResumableReason: unsupported.resume,
+	};
+}
+
+export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRunnerStatus | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	if (input.type !== "external-cli" || typeof input.command !== "string" || !input.command.trim()) return undefined;
+	const args = Array.isArray(input.args) && input.args.every((arg) => typeof arg === "string")
+		? input.args
+		: undefined;
+	const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
+	const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
+		? (input.adapter as Record<string, unknown>).id
+		: undefined;
+	if (adapterId === "grok-build") {
+		return {
+			type: "external-cli",
+			command: input.command,
+			args: args ?? [],
+			promptDelivery: "prompt-file",
+			adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
+			capabilities: { stop: true, steer: false, resume: false, structuredOutput: false, toolEvents: false, supervisor: "unsupported", forkContext: false, extensionBindings: false },
+			unsupportedReasons: PROMPT_FILE_UNSUPPORTED,
+			nonResumableReason: PROMPT_FILE_UNSUPPORTED.resume,
+		};
+	}
+	const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
+	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
+}
+
+export function externalCliReceiptMetadata(input: {
+	runner: ExternalCliRunnerStatus;
+	externalProcess?: ExternalProcessStatus;
+	outputReference?: string;
+}): ExternalCliReceiptMetadata {
+	const { runner } = input;
+	return {
+		adapter: { ...runner.adapter },
+		capabilities: { ...runner.capabilities },
+		...(runner.safety ? { safety: { ...runner.safety } } : {}),
+		...(input.externalProcess ? {
+			outputArtifacts: {
+				stdoutPath: input.externalProcess.stdoutPath,
+				stderrPath: input.externalProcess.stderrPath,
+				...(input.outputReference || input.externalProcess.finalOutputPath ? { finalOutputPath: input.outputReference ?? input.externalProcess.finalOutputPath } : {}),
+			},
+		} : input.outputReference ? { outputArtifacts: { finalOutputPath: input.outputReference } } : {}),
+		handoff: { mode: "fresh" },
+		supervisor: { mode: "unsupported", reason: runner.unsupportedReasons.supervisor },
+		nonResumableReason: runner.nonResumableReason,
+	};
+}

package/node_modules/pi-subagents/src/runs/shared/external-cli-preflight.ts

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
+const MAX_PROBE_TIMEOUT_MS = 5_000;
+const MAX_CACHE_ENTRIES = 64;
+
+export type ExternalCliPreflightInvalidationReason = "launch" | "auth" | "parser" | "permission";
+
+export interface ExternalCliPreflightSpec {
+	id: string;
+	versionArgs: readonly string[];
+	helpArgs: readonly string[];
+	evidenceArgs?: readonly string[];
+	evidenceLabel?: string;
+	probeTimeoutMs?: number;
+	validate?: (result: ExternalCliPreflightResult) => void;
+}
+
+export interface ExternalCliPreflightResult {
+	binaryPath: string;
+	binaryMtimeMs: number;
+	version: string;
+	help: string;
+	evidence?: string;
+	cacheHit: boolean;
+}
+
+type CachedPreflight = Omit<ExternalCliPreflightResult, "cacheHit">;
+
+const cache = new Map<string, CachedPreflight>();
+const lookup = new Map<string, string>();
+
+function resolveBinary(command: string, env: NodeJS.ProcessEnv): string {
+	if (path.isAbsolute(command) || command.includes(path.sep)) {
+		const resolved = path.resolve(command);
+		fs.accessSync(resolved, fs.constants.X_OK);
+		return resolved;
+	}
+	const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+	for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+		if (!directory) continue;
+		for (const extension of extensions) {
+			const candidate = path.join(directory, `${command}${extension}`);
+			try {
+				fs.accessSync(candidate, fs.constants.X_OK);
+				return fs.realpathSync(candidate);
+			} catch {}
+		}
+	}
+	throw new Error(`External CLI binary '${command}' was not found on PATH.`);
+}
+
+function probeWithTimeout(binaryPath: string, args: readonly string[], env: NodeJS.ProcessEnv, label: string, timeoutMs: number, cwd?: string): string {
+	const result = spawnSync(binaryPath, [...args], {
+		cwd,
+		env,
+		encoding: "utf-8",
+		killSignal: "SIGKILL",
+		maxBuffer: MAX_PROBE_OUTPUT_BYTES,
+		timeout: timeoutMs,
+		windowsHide: true,
+	});
+	if (result.error) throw new Error(`External CLI ${label} preflight failed: ${result.error.message}`, { cause: result.error });
+	if (result.status !== 0) throw new Error(`External CLI ${label} preflight exited with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
+	return result.stdout.trim();
+}
+
+function narrowPositiveInteger(value: number | undefined, ceiling: number, label: string): number {
+	if (value === undefined) return ceiling;
+	if (!Number.isSafeInteger(value) || value <= 0 || value > ceiling) throw new Error(`${label} may only narrow the code-owned ceiling of ${ceiling}.`);
+	return value;
+}
+
+function specKey(spec: ExternalCliPreflightSpec): string {
+	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
+}
+
+export function preflightExternalCli(command: string, spec: ExternalCliPreflightSpec, env: NodeJS.ProcessEnv, cwd?: string): ExternalCliPreflightResult {
+	const binaryPath = resolveBinary(command, env);
+	const binaryMtimeMs = fs.statSync(binaryPath).mtimeMs;
+	const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
+	const cachedKey = lookup.get(lookupKey);
+	const cached = cachedKey ? cache.get(cachedKey) : undefined;
+	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
+	const base = cached ?? {
+		binaryPath,
+		binaryMtimeMs,
+		version: probeWithTimeout(binaryPath, spec.versionArgs, env, "version", probeTimeoutMs, cwd),
+		help: probeWithTimeout(binaryPath, spec.helpArgs, env, "help", probeTimeoutMs, cwd),
+	};
+	const evidence = spec.evidenceArgs
+		? probeWithTimeout(binaryPath, spec.evidenceArgs, env, spec.evidenceLabel ?? "evidence", probeTimeoutMs, cwd)
+		: undefined;
+	const result = { ...base, ...(evidence !== undefined ? { evidence } : {}), cacheHit: Boolean(cached) };
+	spec.validate?.(result);
+	if (!cached) {
+		const cacheKey = JSON.stringify([binaryPath, base.version, binaryMtimeMs, specKey(spec)]);
+		cache.set(cacheKey, base);
+		lookup.set(lookupKey, cacheKey);
+		while (cache.size > MAX_CACHE_ENTRIES) {
+			const oldest = cache.keys().next().value as string;
+			cache.delete(oldest);
+			for (const [candidateLookup, candidateCache] of lookup) if (candidateCache === oldest) lookup.delete(candidateLookup);
+		}
+	}
+	return result;
+}
+
+export function invalidateExternalCliPreflight(command: string, spec: ExternalCliPreflightSpec, _reason: ExternalCliPreflightInvalidationReason): void {
+	const key = specKey(spec);
+	for (const [cacheKey, entry] of cache) {
+		if (entry.binaryPath === command || entry.binaryPath.endsWith(`${path.sep}${command}`) || cacheKey.includes(key)) cache.delete(cacheKey);
+	}
+	for (const [lookupKey, cacheKey] of lookup) if (!cache.has(cacheKey)) lookup.delete(lookupKey);
+}
+
+export function clearExternalCliPreflightCacheForTests(): void {
+	cache.clear();
+	lookup.clear();
+}