pi-subagents 0.56.0 → 0.58.0

package/src/runs/shared/cursor-agent-adapter.ts

@@ -0,0 +1,114 @@
+import * as path from "node:path";
+import { parseExternalCliJsonlEvent, type ExternalCliParser, type ExternalCliParserProgress, type ExternalCliParserTerminal } from "./external-cli-runner.ts";
+import type { ExternalCliPreflightSpec } from "./external-cli-preflight.ts";
+
+const MAX_EVENT_TYPE_LENGTH = 128;
+const MAX_ERROR_LENGTH = 4_096;
+const MAX_OVERSIZED_TOOL_CALL_BYTES = 1024 * 1024;
+
+export const CURSOR_AGENT_ADAPTER_ID = "cursor-agent" as const;
+export const CURSOR_AGENT_WRITER_ADAPTER_ID = "cursor-agent-writer" as const;
+export const CURSOR_AGENT_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"CURSOR_API_KEY",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+] as const;
+
+function terminalError(event: Record<string, unknown>): string {
+	for (const value of [event.result, event.error, event.message]) {
+		if (typeof value === "string" && value.trim()) return value.trim().slice(0, MAX_ERROR_LENGTH);
+	}
+	const subtype = typeof event.subtype === "string" && event.subtype ? event.subtype : "unknown";
+	return `Cursor Agent reported terminal result ${subtype}.`;
+}
+
+export function createCursorAgentJsonlParser(): ExternalCliParser {
+	let eventCount = 0;
+	let terminal: ExternalCliParserTerminal | undefined;
+	return {
+		parseLine(line): ExternalCliParserProgress {
+			const event = parseExternalCliJsonlEvent(line, "Cursor Agent", MAX_EVENT_TYPE_LENGTH);
+			if (terminal) throw new Error("Cursor Agent emitted an event after its terminal state.");
+			eventCount += 1;
+			if (event.type === "error") terminal = { state: "failed", error: terminalError(event) };
+			else if (event.type === "result") {
+				if (event.subtype === "success" && event.is_error === false && typeof event.result === "string" && event.result.trim()) {
+					terminal = { state: "completed", output: event.result.trim() };
+				} else terminal = { state: "failed", error: terminalError(event) };
+			}
+			return { phase: terminal ? terminal.state : "streaming", eventCount };
+		},
+		skipOversizedLine(prefix, byteLength): ExternalCliParserProgress | undefined {
+			if (terminal || byteLength > MAX_OVERSIZED_TOOL_CALL_BYTES || !/^\s*\{\s*"type"\s*:\s*"tool_call"\s*,/.test(prefix)) return undefined;
+			eventCount += 1;
+			return { phase: "streaming", eventCount };
+		},
+		finish(): ExternalCliParserTerminal | undefined {
+			return terminal;
+		},
+	};
+}
+
+export function resolveCursorAgentLaunch(input: {
+	adapter: typeof CURSOR_AGENT_ADAPTER_ID | typeof CURSOR_AGENT_WRITER_ADAPTER_ID;
+	command: string;
+	cwd: string;
+	asyncDir: string;
+	stepIndex: number;
+	/** Test-only executable prefix for a fake Cursor Agent process. */
+	commandPrefixArgs?: readonly string[];
+}): {
+	command: string;
+	args: string[];
+	finalOutputPath?: undefined;
+	promptFilePath: string;
+	temporaryDirectories: string[];
+	environment: { allowlist: readonly string[] };
+	preflight: ExternalCliPreflightSpec;
+	parser: ExternalCliParser;
+} {
+	const writer = input.adapter === CURSOR_AGENT_WRITER_ADAPTER_ID;
+	const promptDirectory = path.join(input.asyncDir, `external-${input.stepIndex}.cursor-prompt`);
+	const promptFilePath = path.join(promptDirectory, "handoff.txt");
+	const promptRelative = path.relative(input.cwd, promptDirectory);
+	const promptOutsideWorkspace = promptRelative.startsWith("..") || path.isAbsolute(promptRelative);
+	const prefix = [...(input.commandPrefixArgs ?? [])];
+	const args = [
+		...prefix,
+		"-p",
+		"--output-format", "stream-json",
+		...(writer ? [] : ["--mode", "ask"]),
+		"--sandbox", "enabled",
+		"--workspace", input.cwd,
+		...(promptOutsideWorkspace ? ["--add-dir", promptDirectory] : []),
+		`Read the complete handoff from the private file at ${promptFilePath}. Follow it and return only the final answer.`,
+	];
+	return {
+		command: input.command,
+		args,
+		promptFilePath,
+		temporaryDirectories: [promptDirectory],
+		environment: { allowlist: CURSOR_AGENT_ENV_ALLOWLIST },
+		preflight: {
+			id: input.adapter,
+			versionArgs: [...prefix, "--version"],
+			helpArgs: [...prefix, "--help"],
+			validate(result) {
+				if (!/^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/.test(result.version)) throw new Error(`Unsupported Cursor Agent version response: ${JSON.stringify(result.version)}.`);
+				for (const required of ["Start the Cursor Agent", "--print", "stream-json", "--sandbox <mode>", "enabled", "--workspace <path-or-name>", "--add-dir <path>", ...(writer ? ["all tools", "including write and shell"] : ["--mode <mode>", "ask:", "read-only"])]) {
+					if (!result.help.includes(required)) throw new Error(`Cursor Agent help does not document required option ${JSON.stringify(required)}.`);
+				}
+			},
+		},
+		parser: createCursorAgentJsonlParser(),
+	};
+}

package/src/runs/shared/dynamic-fanout.ts

@@ -49,9 +49,9 @@ 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", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",
-	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "capabilityCeiling", "completionGuard", "systemPrompt",
-	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions",
+	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",
+	"structuredOutput", "structuredOutputSchema", "tools", "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"]);
 

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