pi-subagents 0.55.0 → 0.57.0

package/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/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/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();
+}