pi-subagents 0.50.0 → 0.52.0

package/src/agents/agents.ts

@@ -137,6 +137,7 @@ export interface AgentConfig {
 	systemPrompt: string;
 	source: AgentSource;
 	filePath: string;
+	discoveryPriority?: number;
 	skills?: string[];
 	skillPath?: string[];
 	extensions?: string[];
@@ -212,8 +213,45 @@ export interface ChainDiscoveryDiagnostic {
 	error: string;
 }
 
+export interface AgentDiscoveryDiagnostic extends ChainDiscoveryDiagnostic {
+	name?: string;
+	runtimeName?: string;
+	packageSpecified?: boolean;
+	discoveryPriority?: number;
+}
+
+const AGENT_SOURCE_PRIORITY: Record<AgentSource, number> = {
+	builtin: 0,
+	package: 1,
+	user: 2,
+	project: 3,
+};
+
+function agentDefinitionPriority(definition: Pick<AgentConfig | AgentDiscoveryDiagnostic, "source" | "discoveryPriority">): number {
+	return AGENT_SOURCE_PRIORITY[definition.source] * 1_000_000
+		+ (definition.discoveryPriority ?? 0);
+}
+
+export function findBlockingAgentDiagnostic(name: string, agent: AgentConfig | readonly AgentConfig[] | undefined, diagnostics: AgentDiscoveryDiagnostic[] | undefined): AgentDiscoveryDiagnostic | undefined {
+	const normalizedName = name.trim();
+	const agents = Array.isArray(agent) ? agent : agent ? [agent] : [];
+	let match: AgentDiscoveryDiagnostic | undefined;
+	for (const diagnostic of diagnostics ?? []) {
+		if ((diagnostic.runtimeName === normalizedName
+			|| (diagnostic.name === normalizedName && (!diagnostic.packageSpecified
+				|| diagnostic.runtimeName === undefined
+				|| agents.some((agent) => agent.name === diagnostic.runtimeName && agent.localName === diagnostic.name))))
+			&& (!match || agentDefinitionPriority(diagnostic) > agentDefinitionPriority(match))) {
+			match = diagnostic;
+		}
+	}
+	const highestPriority = Math.max(...agents.map(agentDefinitionPriority), -Infinity);
+	return !agents.length || (match && agentDefinitionPriority(match) > highestPriority) ? match : undefined;
+}
+
 interface AgentDiscoveryResult {
 	agents: AgentConfig[];
+	agentDiagnostics?: AgentDiscoveryDiagnostic[];
 	projectAgentsDir: string | null;
 	modelScope?: ModelScopeConfig;
 }
@@ -345,7 +383,7 @@ function getGlobalNpmRoot(): string | null {
 	}
 
 	try {
-		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
+		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
 		return cachedGlobalNpmRoot;
 	} catch {
 		cachedGlobalNpmRoot = "";
@@ -1448,6 +1486,14 @@ function isLegacyAgentSkillPath(rootDir: string, filePath: string): boolean {
 	return parts.some((part, index) => part === ".agents" && parts[index + 1] === "skills");
 }
 
+function isJsonSerializable(value: unknown): boolean {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJsonSerializable);
+	if (value && typeof value === "object") return Object.values(value).every(isJsonSerializable);
+	return false;
+}
+
 function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string): AgentRunnerConfig | undefined {
 	if (raw === undefined || !raw.trim()) return undefined;
 	let parsed: unknown;
@@ -1464,8 +1510,24 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
 		if (Object.keys(runner).some((key) => key !== "type")) throw new Error(`Agent '${agentName}' has invalid Pi runner frontmatter; only 'type' is supported.`);
 		return { type: "pi" };
 	}
+	if (runner.type === "external-job") {
+		if (typeof runner.provider !== "string" || !runner.provider.trim() || runner.provider.trim() !== runner.provider) {
+			throw new Error(`Agent '${agentName}' external-job runner requires a non-empty trimmed provider string.`);
+		}
+		if (runner.options !== undefined && (!runner.options || typeof runner.options !== "object" || Array.isArray(runner.options) || !isJsonSerializable(runner.options))) {
+			throw new Error(`Agent '${agentName}' external-job runner options must be a JSON-serializable object.`);
+		}
+		const supported = new Set(["type", "provider", "options"]);
+		const unknown = Object.keys(runner).filter((key) => !supported.has(key));
+		if (unknown.length > 0) throw new Error(`Agent '${agentName}' external-job runner has unsupported fields: ${unknown.join(", ")}.`);
+		return {
+			type: "external-job",
+			provider: runner.provider,
+			...(runner.options ? { options: runner.options as Record<string, unknown> } : {}),
+		};
+	}
 	if (runner.type !== "external-cli") {
-		throw new Error(`Agent '${agentName}' has invalid runner.type; expected 'pi' or 'external-cli'.`);
+		throw new Error(`Agent '${agentName}' has invalid runner.type; expected 'pi', 'external-cli', or 'external-job'.`);
 	}
 	if (typeof runner.command !== "string" || !runner.command.trim()) {
 		throw new Error(`Agent '${agentName}' external-cli runner requires a non-empty command string.`);
@@ -1489,11 +1551,11 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
 }
 
 function validateExternalRunnerProfile(frontmatter: Record<string, string>, agentName: string, runner: AgentRunnerConfig | undefined): void {
-	if (runner?.type !== "external-cli") return;
+	if (runner?.type !== "external-cli" && runner?.type !== "external-job") return;
 	const unsupported = ["tools", "model", "fallbackModels", "thinking", "extensions", "subagentOnlyExtensions", "maxSubagentDepth", "completionGuard", "skills", "skill", "skillPath", "toolBudget", "permission", "permissions"]
 		.filter((field) => frontmatter[field] !== undefined);
 	if (unsupported.length > 0) {
-		throw new Error(`Agent '${agentName}' uses runner.type='external-cli' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
+		throw new Error(`Agent '${agentName}' uses runner.type='${runner.type}' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
 	}
 }
 
@@ -1510,21 +1572,48 @@ function parseAgentAcceptanceFrontmatter(raw: string | undefined, agentName: str
 	return parsed as AcceptanceInput;
 }
 
-function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
-	const agents: AgentConfig[] = [];
+interface AgentDefinitionFile {
+	filePath: string;
+	content: string;
+}
 
+function readAgentDefinitionFiles(dir: string): AgentDefinitionFile[] {
+	const files: AgentDefinitionFile[] = [];
 	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
 		if (isLegacyAgentSkillPath(dir, filePath)) {
 			continue;
 		}
 
-		let content: string;
 		try {
-			content = fs.readFileSync(filePath, "utf-8");
+			files.push({ filePath, content: fs.readFileSync(filePath, "utf-8") });
 		} catch {
 			continue;
 		}
+	}
+	return files;
+}
 
+function resolveAgentRelativeExtensionPaths(paths: string[] | undefined, agentFilePath: string): string[] | undefined {
+	if (paths === undefined) return undefined;
+	const baseDir = path.dirname(agentFilePath);
+	return paths.map((entry) => {
+		const trimmed = entry.trim();
+		if (trimmed === "." || trimmed === ".." || trimmed.startsWith("./") || trimmed.startsWith("../")) {
+			return path.resolve(baseDir, trimmed);
+		}
+		return entry;
+	});
+}
+
+function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: AgentSource, discoveryPriority?: number): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
+	const agents: AgentConfig[] = [];
+	const diagnostics: AgentDiscoveryDiagnostic[] = [];
+
+	for (const { filePath, content } of files) {
+		let name: string | undefined;
+		let runtimeName: string | undefined;
+		let packageSpecified = false;
+		try {
 		const { frontmatter, body } = parseFrontmatter(content);
 
 		if (!frontmatter.name || !frontmatter.description) {
@@ -1532,10 +1621,12 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		}
 
 		const localName = frontmatter.name;
+		name = localName;
 		const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
-		if (parsedPackage.error) continue;
+		packageSpecified = parsedPackage.packageName !== undefined || parsedPackage.error !== undefined;
+		if (parsedPackage.error) throw new Error(parsedPackage.error);
 		const packageName = parsedPackage.packageName;
-		const runtimeName = buildRuntimeName(localName, packageName);
+		runtimeName = buildRuntimeName(localName, packageName);
 
 		const runner = parseAgentRunnerFrontmatter(frontmatter.runner, localName);
 		validateExternalRunnerProfile(frontmatter, localName, runner);
@@ -1605,8 +1696,8 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			else throw new Error(`Agent '${localName}' has invalid acceptanceRole frontmatter; expected 'read-only' or 'writer'.`);
 		}
 
-		const extensions = parseFrontmatterList(frontmatter.extensions);
-		const subagentOnlyExtensions = parseFrontmatterList(frontmatter.subagentOnlyExtensions);
+		const extensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.extensions), filePath);
+		const subagentOnlyExtensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.subagentOnlyExtensions), filePath);
 
 		const extraFields: Record<string, string> = {};
 		for (const [key, value] of Object.entries(frontmatter)) {
@@ -1664,6 +1755,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			systemPrompt: body,
 			source,
 			filePath,
+			...(discoveryPriority !== undefined ? { discoveryPriority } : {}),
 			...(skills?.length ? { skills } : {}),
 			...(skillPath?.length ? { skillPath } : {}),
 			...(extensions !== undefined ? { extensions } : {}),
@@ -1681,9 +1773,16 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		};
 		agentFrontmatterFields.set(agent, new Set(Object.keys(frontmatter)));
 		agents.push(agent);
+		} catch (error) {
+			diagnostics.push({ source, filePath, ...(name ? { name } : {}), ...(runtimeName && runtimeName !== name ? { runtimeName } : {}), ...(packageSpecified ? { packageSpecified: true } : {}), ...(discoveryPriority !== undefined ? { discoveryPriority } : {}), error: error instanceof Error ? error.message : String(error) });
+		}
 	}
 
-	return agents;
+	return { agents, diagnostics };
+}
+
+function loadAgentsFromDir(dir: string, source: AgentSource, discoveryPriority?: number): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
+	return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir), source, discoveryPriority);
 }
 
 function loadChainsFromDir(dir: string, source: AgentSource): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
@@ -1747,6 +1846,7 @@ function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; pref
 	};
 }
 const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
+const BUILTIN_AGENT_DEFINITION_FILES = readAgentDefinitionFiles(BUILTIN_AGENTS_DIR);
 
 export const EXTRA_AGENT_DIRS_ENV = "PI_SUBAGENT_EXTRA_AGENT_DIRS";
 
@@ -1781,34 +1881,42 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 		includeProject: scope !== "user",
 	});
 
+	const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
 	const builtinAgents = applyBuiltinOverrides(
-		applySubagentDefaults(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
 
-	const userAgentsExtra = scope === "project" ? [] : extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user"));
-	const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
-	const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
+	const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), userDirOld, userDirNew]
+		.map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
 	const userAgents = applyCustomAgentOverrides(
-		applySubagentDefaults([...userAgentsExtra, ...userAgentsOld, ...userAgentsNew], defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
 
+	const projectLoaded = scope === "user" ? [] : projectAgentDirs.map((dir) => loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0));
 	const projectAgents = applyCustomAgentOverrides(
-		applySubagentDefaults(scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
+	const packageLoaded = packageSubagentPaths.agents.map((dir, index) => loadAgentsFromDir(dir, "package", packageSubagentPaths.agents.length - index));
+	const packageMap = new Map<string, AgentConfig>();
+	for (const loaded of packageLoaded) {
+		for (const agent of loaded.agents) {
+			if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
+		}
+	}
 	const packageAgents = applyCustomAgentOverrides(
-		applySubagentDefaults(packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package")), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1817,7 +1925,13 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
 		.filter((agent) => agent.disabled !== true);
 
-	return { agents, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}) };
+	const agentDiagnostics = [
+		...builtinLoaded.diagnostics,
+		...userLoaded.flatMap((loaded) => loaded.diagnostics),
+		...projectLoaded.flatMap((loaded) => loaded.diagnostics),
+		...packageLoaded.flatMap((loaded) => loaded.diagnostics),
+	];
+	return { agents, agentDiagnostics, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}) };
 }
 
 export function discoverAgentsAll(cwd: string): {
@@ -1825,6 +1939,7 @@ export function discoverAgentsAll(cwd: string): {
 	package: AgentConfig[];
 	user: AgentConfig[];
 	project: AgentConfig[];
+	agentDiagnostics?: AgentDiscoveryDiagnostic[];
 	chains: ChainConfig[];
 	chainDiagnostics: ChainDiscoveryDiagnostic[];
 	userDir: string;
@@ -1848,27 +1963,29 @@ export function discoverAgentsAll(cwd: string): {
 	const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd);
 
+	const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
 	const builtin = applyBuiltinOverrides(
-		applySubagentDefaults(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
+	const userLoaded = [...extraUserAgentDirs(), userDirOld, userDirNew]
+		.map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
 	const user = applyCustomAgentOverrides(
-		applySubagentDefaults([
-			...extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user")),
-			...loadAgentsFromDir(userDirOld, "user"),
-			...loadAgentsFromDir(userDirNew, "user"),
-		], defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
 	const packageMap = new Map<string, AgentConfig>();
-	for (const dir of packageSubagentPaths.agents) {
-		for (const agent of loadAgentsFromDir(dir, "package")) {
+	const packageAgentDiagnostics: AgentDiscoveryDiagnostic[] = [];
+	for (const [index, dir] of packageSubagentPaths.agents.entries()) {
+		const loaded = loadAgentsFromDir(dir, "package", packageSubagentPaths.agents.length - index);
+		packageAgentDiagnostics.push(...loaded.diagnostics);
+		for (const agent of loaded.agents) {
 			if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
 		}
 	}
@@ -1880,8 +1997,11 @@ export function discoverAgentsAll(cwd: string): {
 		projectSettingsPath,
 	);
 	const projectMap = new Map<string, AgentConfig>();
+	const projectAgentDiagnostics: AgentDiscoveryDiagnostic[] = [];
 	for (const dir of projectDirs) {
-		for (const agent of loadAgentsFromDir(dir, "project")) {
+		const loaded = loadAgentsFromDir(dir, "project", dir === projectDir ? 1 : 0);
+		projectAgentDiagnostics.push(...loaded.diagnostics);
+		for (const agent of loaded.agents) {
 			projectMap.set(agent.name, agent);
 		}
 	}
@@ -1922,8 +2042,14 @@ export function discoverAgentsAll(cwd: string): {
 		...userChains.diagnostics,
 		...projectChainDiagnostics,
 	];
+	const agentDiagnostics = [
+		...builtinLoaded.diagnostics,
+		...userLoaded.flatMap((loaded) => loaded.diagnostics),
+		...packageAgentDiagnostics,
+		...projectAgentDiagnostics,
+	];
 
 	const userDir = process.env.PI_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
 
-	return { builtin, package: packageAgents, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
+	return { builtin, package: packageAgents, user, project, agentDiagnostics, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
 }

package/src/agents/skills.ts

@@ -142,7 +142,7 @@ function getGlobalNpmRoot(): string | null {
 	}
 
 	try {
-		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
+		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
 		return cachedGlobalNpmRoot;
 	} catch {
 		// Global npm root is optional in constrained environments.

package/src/api/external-job-provider.ts

@@ -0,0 +1,185 @@
+export const EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION = 1;
+export const EXTERNAL_JOB_PROVIDER_REGISTRY_KEY = "pi-subagents.external-job-providers.v1";
+
+const MAX_PROVIDER_NAME_LENGTH = 128;
+const MAX_PROVIDERS = 100;
+const MAX_JOB_ID_LENGTH = 256;
+const MAX_FAILURE_CODE_LENGTH = 128;
+const MAX_FAILURE_MESSAGE_LENGTH = 4_096;
+const MAX_URL_LENGTH = 4_096;
+
+export type ExternalJobState = "queued" | "running" | "completed" | "failed" | "stopped" | "blocked";
+export type ExternalJobOperation = "start" | "status" | "result" | "reattach";
+
+export type ExternalJobOptions = Record<string, unknown>;
+
+export interface ExternalJobStartInput {
+	prompt: string;
+	promptDigest: string;
+	cwd: string;
+	runId: string;
+	stepIndex: number;
+	agent: string;
+	options: ExternalJobOptions;
+	sessionId?: string;
+}
+
+export interface ExternalJobHandle {
+	providerJobId: string;
+	state: ExternalJobState;
+	handleUrl?: string;
+	conversationUrl?: string;
+	failureCode?: string;
+	failureMessage?: string;
+	blockingJobId?: string;
+}
+
+export interface ExternalJobResult extends ExternalJobHandle {
+	output?: string;
+	artifactPath?: string;
+}
+
+export interface ExternalJobProvider {
+	name: string;
+	start(input: ExternalJobStartInput): Promise<ExternalJobHandle> | ExternalJobHandle;
+	status(providerJobId: string): Promise<ExternalJobHandle> | ExternalJobHandle;
+	result(providerJobId: string): Promise<ExternalJobResult> | ExternalJobResult;
+	reattach(providerJobId: string): Promise<ExternalJobHandle> | ExternalJobHandle;
+}
+
+export class ExternalJobProviderError extends Error {
+	readonly code: string;
+	readonly blockingJobId?: string;
+
+	constructor(message: string, options: { code: string; blockingJobId?: string; cause?: unknown }) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ExternalJobProviderError";
+		this.code = options.code;
+		this.blockingJobId = options.blockingJobId;
+	}
+}
+
+interface ExternalJobProviderRegistry {
+	version: typeof EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION;
+	providers: Map<string, ExternalJobProvider>;
+}
+
+function registry(): ExternalJobProviderRegistry {
+	const key = Symbol.for(EXTERNAL_JOB_PROVIDER_REGISTRY_KEY);
+	const globalObject = globalThis as Record<PropertyKey, unknown>;
+	const existing = globalObject[key];
+	if (existing === undefined) {
+		const created: ExternalJobProviderRegistry = {
+			version: EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION,
+			providers: new Map(),
+		};
+		globalObject[key] = created;
+		return created;
+	}
+	if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+		throw new Error(`Malformed external-job provider registry at Symbol.for("${EXTERNAL_JOB_PROVIDER_REGISTRY_KEY}").`);
+	}
+	const candidate = existing as Partial<ExternalJobProviderRegistry>;
+	if (candidate.version !== EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION || !(candidate.providers instanceof Map)) {
+		throw new Error(`Unsupported external-job provider registry at Symbol.for("${EXTERNAL_JOB_PROVIDER_REGISTRY_KEY}").`);
+	}
+	return candidate as ExternalJobProviderRegistry;
+}
+
+function validateString(value: unknown, field: string, maxLength: number): string {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+		throw new Error(`${field} must be a non-empty string without leading or trailing whitespace.`);
+	}
+	if (value.length > maxLength) throw new Error(`${field} must be at most ${maxLength} characters.`);
+	if (value.includes("\0")) throw new Error(`${field} must not contain NUL characters.`);
+	return value;
+}
+
+function validateOptionalString(value: unknown, field: string, maxLength: number): string | undefined {
+	if (value === undefined) return undefined;
+	return validateString(value, field, maxLength);
+}
+
+function validateState(value: unknown, field: string): ExternalJobState {
+	if (value === "queued" || value === "running" || value === "completed" || value === "failed" || value === "stopped" || value === "blocked") return value;
+	throw new Error(`${field} must be queued, running, completed, failed, stopped, or blocked.`);
+}
+
+function validateHandle(provider: string, value: unknown, field: string, extraFields: readonly string[] = []): ExternalJobHandle {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${field} from external-job provider '${provider}' must be an object.`);
+	const handle = value as Record<string, unknown>;
+	const supported = new Set(["providerJobId", "state", "handleUrl", "conversationUrl", "failureCode", "failureMessage", "blockingJobId", ...extraFields]);
+	const unknown = Object.keys(handle).filter((key) => !supported.has(key));
+	if (unknown.length > 0) throw new Error(`${field} from external-job provider '${provider}' has unknown fields: ${unknown.join(", ")}.`);
+	const handleUrl = validateOptionalString(handle.handleUrl, `${field}.handleUrl`, MAX_URL_LENGTH);
+	const conversationUrl = validateOptionalString(handle.conversationUrl, `${field}.conversationUrl`, MAX_URL_LENGTH);
+	const failureCode = validateOptionalString(handle.failureCode, `${field}.failureCode`, MAX_FAILURE_CODE_LENGTH);
+	const failureMessage = validateOptionalString(handle.failureMessage, `${field}.failureMessage`, MAX_FAILURE_MESSAGE_LENGTH);
+	const blockingJobId = validateOptionalString(handle.blockingJobId, `${field}.blockingJobId`, MAX_JOB_ID_LENGTH);
+	return {
+		providerJobId: validateString(handle.providerJobId, `${field}.providerJobId`, MAX_JOB_ID_LENGTH),
+		state: validateState(handle.state, `${field}.state`),
+		...(handleUrl ? { handleUrl } : {}),
+		...(conversationUrl ? { conversationUrl } : {}),
+		...(failureCode ? { failureCode } : {}),
+		...(failureMessage ? { failureMessage } : {}),
+		...(blockingJobId ? { blockingJobId } : {}),
+	};
+}
+
+export function validateExternalJobHandle(provider: string, value: unknown, field = "External-job handle"): ExternalJobHandle {
+	return validateHandle(provider, value, field);
+}
+
+export function validateExternalJobResult(provider: string, value: unknown, field = "External-job result"): ExternalJobResult {
+	const result = validateHandle(provider, value, field, ["output", "artifactPath"]) as ExternalJobResult;
+	const record = value as Record<string, unknown>;
+	const output = validateOptionalString(record.output, `${field}.output`, 1024 * 1024);
+	const artifactPath = validateOptionalString(record.artifactPath, `${field}.artifactPath`, MAX_URL_LENGTH);
+	return {
+		...result,
+		...(output !== undefined ? { output } : {}),
+		...(artifactPath !== undefined ? { artifactPath } : {}),
+	};
+}
+
+function validateProvider(value: unknown): ExternalJobProvider {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("External-job provider must be an object.");
+	const provider = value as Record<string, unknown>;
+	const unknownFields = Object.keys(provider).filter((key) => !["name", "start", "status", "result", "reattach"].includes(key));
+	if (unknownFields.length > 0) throw new Error(`External-job provider has unknown fields: ${unknownFields.join(", ")}.`);
+	const name = validateString(provider.name, "External-job provider name", MAX_PROVIDER_NAME_LENGTH);
+	for (const op of ["start", "status", "result", "reattach"] as const) {
+		if (typeof provider[op] !== "function") throw new Error(`External-job provider '${name}' must expose ${op}().`);
+	}
+	return value as ExternalJobProvider;
+}
+
+export function registerExternalJobProvider(provider: ExternalJobProvider): () => void {
+	const validated = validateProvider(provider);
+	const current = registry();
+	if (!current.providers.has(validated.name) && current.providers.size >= MAX_PROVIDERS) {
+		throw new Error(`External-job provider registry supports at most ${MAX_PROVIDERS} providers.`);
+	}
+	current.providers.set(validated.name, validated);
+	return () => {
+		if (current.providers.get(validated.name) === validated) current.providers.delete(validated.name);
+	};
+}
+
+export function listExternalJobProviders(): readonly ExternalJobProvider[] {
+	const current = registry();
+	if (current.providers.size > MAX_PROVIDERS) throw new Error(`External-job provider registry contains more than ${MAX_PROVIDERS} providers.`);
+	const providers: ExternalJobProvider[] = [];
+	for (const [key, value] of current.providers) {
+		const provider = validateProvider(value);
+		if (key !== provider.name) throw new Error(`External-job provider registry key '${key}' does not match provider name '${provider.name}'.`);
+		providers.push(provider);
+	}
+	return providers;
+}
+
+export function getExternalJobProvider(name: string): ExternalJobProvider | undefined {
+	const safeName = validateString(name, "External-job provider name", MAX_PROVIDER_NAME_LENGTH);
+	return listExternalJobProviders().find((provider) => provider.name === safeName);
+}