pi-subagents 0.68.0 → 0.70.0

package/src/runs/shared/external-cli-contract.ts

@@ -1,177 +0,0 @@
-import type {
-	ExternalCliReceiptMetadata,
-	ExternalCliCapabilityNarrowing,
-	ExternalCliRunnerStatus,
-	ExternalCliMachineStatus,
-	ExternalProcessStatus,
-	HerdrMachineReference,
-} 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;
-	machine?: HerdrMachineReference;
-}): 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 } } : {}),
-		...(input.machine ? { machine: input.machine } : {}),
-		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 machine = input.machine && typeof input.machine === "object" && !Array.isArray(input.machine)
-		? input.machine as HerdrMachineReference
-		: 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,
-			...(machine ? { machine } : {}),
-			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 } : {}), ...(machine ? { machine } : {}) });
-}
-
-export function externalCliReceiptMetadata(input: {
-	runner: ExternalCliRunnerStatus;
-	externalProcess?: ExternalProcessStatus;
-	outputReference?: string;
-}): ExternalCliReceiptMetadata {
-	const { runner } = input;
-	const machine: ExternalCliMachineStatus | undefined = input.externalProcess?.machine ?? runner.machine;
-	return {
-		adapter: { ...runner.adapter },
-		capabilities: { ...runner.capabilities },
-		...(machine ? { machine: { ...machine, ...(machine.remoteGit ? { remoteGit: { ...machine.remoteGit } } : {}) } } : {}),
-		...(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

@@ -1,142 +0,0 @@
-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_REMOTE_PROBE_TIMEOUT_MS = 15_000;
-const MAX_CACHE_ENTRIES = 64;
-const MAX_AVAILABILITY_REASON_LENGTH = 256;
-
-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;
-	/** Remote probes include SSH handshakes; values may only narrow the code-owned remote ceiling. */
-	remote?: boolean;
-	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>();
-
-export type ExternalCliBinaryAvailability =
-	| { available: true }
-	| { available: false; unavailableReason: 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.`);
-}
-
-/** Resolve only the configured command; unlike preflight, this never starts a child process. */
-export function resolveExternalCliBinaryAvailability(command: string, env: NodeJS.ProcessEnv): ExternalCliBinaryAvailability {
-	try {
-		resolveBinary(command, env);
-		return { available: true };
-	} catch (error) {
-		const reason = error instanceof Error ? error.message : String(error);
-		return { available: false, unavailableReason: reason.slice(0, MAX_AVAILABILITY_REASON_LENGTH) };
-	}
-}
-
-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, spec.remote === true]);
-}
-
-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 ceiling = spec.remote === true ? MAX_REMOTE_PROBE_TIMEOUT_MS : MAX_PROBE_TIMEOUT_MS;
-	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, ceiling, "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();
-}