pi-subagents 0.40.0 → 0.41.0

package/src/agents/agents.ts

@@ -8,7 +8,7 @@ import { parse as parseYaml } from "yaml";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AcceptanceInput, AcceptanceRole, OutputMode, ToolBudgetConfig, TurnBudgetConfig } from "../shared/types.ts";
+import type { AcceptanceInput, AcceptanceRole, AgentRunnerConfig, OutputMode, ToolBudgetConfig, TurnBudgetConfig } from "../shared/types.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain, parseJsonChain } from "./chain-serializer.ts";
@@ -20,6 +20,7 @@ export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./
 import { parseMemoryFrontmatter } from "./agent-memory.ts";
 import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
+import { validatePermissionRules, type PermissionRules } from "../runs/shared/permissions.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -115,6 +116,7 @@ export interface AgentModelSourceInfo {
 
 export interface AgentConfig {
 	name: string;
+	runner?: AgentRunnerConfig;
 	localName?: string;
 	packageName?: string;
 	description: string;
@@ -148,6 +150,7 @@ export interface AgentConfig {
 	maxSubagentDepth?: number;
 	completionGuard?: boolean;
 	toolBudget?: ToolBudgetConfig;
+	permissions?: PermissionRules;
 	memory?: AgentMemoryConfig;
 	disabled?: boolean;
 	extraFields?: Record<string, string>;
@@ -327,6 +330,21 @@ function getGlobalNpmRoot(): string | null {
 	const offline = process.env.PI_OFFLINE?.toLowerCase();
 	if (offline === "1" || offline === "true" || offline === "yes") return null;
 	if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
+
+	const windowsGlobalRoot = process.platform === "win32" && process.env.APPDATA
+		? path.join(process.env.APPDATA, "npm", "node_modules")
+		: undefined;
+	if (windowsGlobalRoot) {
+		try {
+			if (fs.statSync(windowsGlobalRoot).isDirectory()) {
+				cachedGlobalNpmRoot = fs.realpathSync(windowsGlobalRoot);
+				return cachedGlobalNpmRoot;
+			}
+		} catch {
+			// Fall through if the directory disappears while resolving it.
+		}
+	}
+
 	try {
 		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
 		return cachedGlobalNpmRoot;
@@ -486,7 +504,8 @@ function effectiveAgentMatch(matches: AgentConfig[]): { agent?: AgentConfig; err
 	const distinctNames = [...new Set(matches.map((agent) => agent.name))];
 	if (distinctNames.length === 1) {
 		const sourceRank = new Map<AgentConfig["source"], number>([["builtin", 0], ["package", 1], ["user", 2], ["project", 3]]);
-		return { agent: [...matches].sort((a, b) => (sourceRank.get(b.source) ?? 0) - (sourceRank.get(a.source) ?? 0))[0] };
+		const agent = [...matches].sort((a, b) => (sourceRank.get(b.source) ?? 0) - (sourceRank.get(a.source) ?? 0))[0];
+		return agent ? { agent } : {};
 	}
 	return {};
 }
@@ -494,7 +513,7 @@ function effectiveAgentMatch(matches: AgentConfig[]): { agent?: AgentConfig; err
 export function resolveAgentName(name: string, agents: AgentConfig[]): { agent?: AgentConfig; error?: string } {
 	const raw = name.trim();
 	const exact = agents.filter((agent) => agent.name === raw || agent.localName === raw);
-	if (exact.length === 1) return { agent: exact[0] };
+	if (exact.length === 1) return exact[0] ? { agent: exact[0] } : {};
 	if (exact.length > 1) {
 		const effective = effectiveAgentMatch(exact);
 		if (effective.agent) return effective;
@@ -502,7 +521,7 @@ export function resolveAgentName(name: string, agents: AgentConfig[]): { agent?:
 	}
 
 	const aliases = agents.filter((agent) => agent.aliases?.includes(raw));
-	if (aliases.length === 1) return { agent: aliases[0] };
+	if (aliases.length === 1) return aliases[0] ? { agent: aliases[0] } : {};
 	if (aliases.length > 1) {
 		const effective = effectiveAgentMatch(aliases);
 		if (effective.agent) return effective;
@@ -548,24 +567,24 @@ function arraysEqual(a: string[] | undefined, b: string[] | undefined): boolean
 function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 	return {
 		description: agent.description,
-		model: agent.model,
-		fallbackModels: agent.fallbackModels ? [...agent.fallbackModels] : undefined,
-		thinking: agent.thinking,
+		...(agent.model !== undefined ? { model: agent.model } : {}),
+		...(agent.fallbackModels ? { fallbackModels: [...agent.fallbackModels] } : {}),
+		...(agent.thinking !== undefined ? { thinking: agent.thinking } : {}),
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
 		inheritSkills: agent.inheritSkills,
-		defaultContext: agent.defaultContext,
-		acceptanceRole: agent.acceptanceRole,
-		disabled: agent.disabled,
+		...(agent.defaultContext !== undefined ? { defaultContext: agent.defaultContext } : {}),
+		...(agent.acceptanceRole !== undefined ? { acceptanceRole: agent.acceptanceRole } : {}),
+		...(agent.disabled !== undefined ? { disabled: agent.disabled } : {}),
 		systemPrompt: agent.systemPrompt,
-		skills: agent.skills ? [...agent.skills] : undefined,
-		skillPath: agent.skillPath ? [...agent.skillPath] : undefined,
-		tools: agent.tools ? [...agent.tools] : undefined,
-		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
-		extensions: agent.extensionsFromDefault ? undefined : agent.extensions ? [...agent.extensions] : undefined,
-		subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : undefined,
-		completionGuard: agent.completionGuard,
-		toolBudget: agent.toolBudget,
+		...(agent.skills ? { skills: [...agent.skills] } : {}),
+		...(agent.skillPath ? { skillPath: [...agent.skillPath] } : {}),
+		...(agent.tools ? { tools: [...agent.tools] } : {}),
+		...(agent.mcpDirectTools ? { mcpDirectTools: [...agent.mcpDirectTools] } : {}),
+		...(!agent.extensionsFromDefault && agent.extensions ? { extensions: [...agent.extensions] } : {}),
+		...(agent.subagentOnlyExtensions ? { subagentOnlyExtensions: [...agent.subagentOnlyExtensions] } : {}),
+		...(agent.completionGuard !== undefined ? { completionGuard: agent.completionGuard } : {}),
+		...(agent.toolBudget !== undefined ? { toolBudget: agent.toolBudget } : {}),
 	};
 }
 
@@ -882,14 +901,23 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
 	const agentOverrides = subagentsObject.agentOverrides;
+	const parsedSettings: SubagentSettings = {
+		overrides: parsed,
+		...(defaultModel !== undefined ? { defaultModel } : {}),
+		...(defaultThinking !== undefined ? { defaultThinking } : {}),
+		...(defaultExtensions !== undefined ? { defaultExtensions } : {}),
+		...(disableBuiltins !== undefined ? { disableBuiltins } : {}),
+		...(disableThinking !== undefined ? { disableThinking } : {}),
+		...(modelScope !== undefined ? { modelScope } : {}),
+	};
 	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
-		return { overrides: parsed, defaultModel, defaultThinking, defaultExtensions, disableBuiltins, disableThinking, modelScope };
+		return parsedSettings;
 	}
 	for (const [name, value] of Object.entries(agentOverrides)) {
 		const override = parseBuiltinOverrideEntry(name, value, filePath);
 		if (override) parsed[name] = override;
 	}
-	return { overrides: parsed, defaultModel, defaultThinking, defaultExtensions, disableBuiltins, disableThinking, modelScope };
+	return parsedSettings;
 }
 
 function resolveSubagentDefaultModel(
@@ -980,41 +1008,34 @@ function applyBuiltinOverride(
 	};
 
 	if (override.description !== undefined) next.description = override.description;
-	if (override.model !== undefined) next.model = override.model === false ? undefined : override.model;
-	if (override.fallbackModels !== undefined) {
-		next.fallbackModels = override.fallbackModels === false ? undefined : [...override.fallbackModels];
-	}
-	if (override.thinking !== undefined) next.thinking = override.thinking === false ? undefined : override.thinking;
+	if (override.model !== undefined) { if (override.model === false) delete next.model; else next.model = override.model; }
+	if (override.fallbackModels !== undefined) { if (override.fallbackModels === false) delete next.fallbackModels; else next.fallbackModels = [...override.fallbackModels]; }
+	if (override.thinking !== undefined) { if (override.thinking === false) delete next.thinking; else next.thinking = override.thinking; }
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
 	if (override.inheritProjectContext !== undefined) next.inheritProjectContext = override.inheritProjectContext;
 	if (override.inheritSkills !== undefined) next.inheritSkills = override.inheritSkills;
-	if (override.defaultContext !== undefined) next.defaultContext = override.defaultContext === false ? undefined : override.defaultContext;
-	if (override.acceptanceRole !== undefined) next.acceptanceRole = override.acceptanceRole === false ? undefined : override.acceptanceRole;
+	if (override.defaultContext !== undefined) { if (override.defaultContext === false) delete next.defaultContext; else next.defaultContext = override.defaultContext; }
+	if (override.acceptanceRole !== undefined) { if (override.acceptanceRole === false) delete next.acceptanceRole; else next.acceptanceRole = override.acceptanceRole; }
 	if (override.disabled !== undefined) next.disabled = override.disabled;
 	if (override.systemPrompt !== undefined) next.systemPrompt = override.systemPrompt;
-	if (override.skills !== undefined) next.skills = override.skills === false ? undefined : [...override.skills];
+	if (override.skills !== undefined) { if (override.skills === false) delete next.skills; else next.skills = [...override.skills]; }
 	if (override.tools !== undefined) {
 		const { tools, mcpDirectTools } = splitToolList(override.tools === false ? [] : override.tools);
-		next.tools = tools;
-		next.mcpDirectTools = mcpDirectTools;
-	}
-	if (override.extensions !== undefined) next.extensions = override.extensions === false ? undefined : [...override.extensions];
-	if (override.subagentOnlyExtensions !== undefined) {
-		next.subagentOnlyExtensions = override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions];
+		if (tools === undefined) delete next.tools; else next.tools = tools;
+		if (mcpDirectTools === undefined) delete next.mcpDirectTools; else next.mcpDirectTools = mcpDirectTools;
 	}
+	if (override.extensions !== undefined) { if (override.extensions === false) delete next.extensions; else next.extensions = [...override.extensions]; }
+	if (override.subagentOnlyExtensions !== undefined) { if (override.subagentOnlyExtensions === false) delete next.subagentOnlyExtensions; else next.subagentOnlyExtensions = [...override.subagentOnlyExtensions]; }
 	if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
-	if (override.toolBudget !== undefined) next.toolBudget = override.toolBudget === false ? undefined : override.toolBudget;
+	if (override.toolBudget !== undefined) { if (override.toolBudget === false) delete next.toolBudget; else next.toolBudget = override.toolBudget; }
 
 	return next;
 }
 
 function clearBuiltinThinking(agent: AgentConfig, meta: { scope: "user" | "project"; path: string }): AgentConfig {
 	if (agent.thinking === undefined) return agent;
-	return {
-		...agent,
-		thinking: undefined,
-		override: agent.override ?? { ...meta, base: cloneOverrideBase(agent) },
-	};
+	const { thinking: _thinking, ...next } = agent;
+	return { ...next, override: agent.override ?? { ...meta, base: cloneOverrideBase(agent) } };
 }
 
 function applyBuiltinOverrides(
@@ -1096,7 +1117,8 @@ function applyCustomAgentOverride(
 		value: AgentConfig[K],
 	): void => {
 		if (agentHasFrontmatterField(agent, ...frontmatterFields)) return;
-		mutable()[field] = value;
+		const target = mutable();
+		if (value === undefined) delete target[field]; else target[field] = value;
 		anyFilled = true;
 	};
 
@@ -1142,8 +1164,8 @@ function applyCustomAgentOverride(
 	if (override.tools !== undefined && !agentHasFrontmatterField(agent, "tools")) {
 		const { tools, mcpDirectTools } = splitToolList(override.tools === false ? [] : override.tools);
 		const target = mutable();
-		target.tools = tools;
-		target.mcpDirectTools = mcpDirectTools;
+		if (tools === undefined) delete target.tools; else target.tools = tools;
+		if (mcpDirectTools === undefined) delete target.mcpDirectTools; else target.mcpDirectTools = mcpDirectTools;
 		anyFilled = true;
 	}
 	if (override.extensions !== undefined) {
@@ -1397,6 +1419,55 @@ function isLegacyAgentSkillPath(rootDir: string, filePath: string): boolean {
 	return parts.some((part, index) => part === ".agents" && parts[index + 1] === "skills");
 }
 
+function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string): AgentRunnerConfig | undefined {
+	if (raw === undefined || !raw.trim()) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(raw);
+	} catch (error) {
+		throw new Error(`Agent '${agentName}' has invalid runner frontmatter: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Agent '${agentName}' has invalid runner frontmatter; expected an object.`);
+	}
+	const runner = parsed as Record<string, unknown>;
+	if (runner.type === "pi") {
+		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-cli") {
+		throw new Error(`Agent '${agentName}' has invalid runner.type; expected 'pi' or 'external-cli'.`);
+	}
+	if (typeof runner.command !== "string" || !runner.command.trim()) {
+		throw new Error(`Agent '${agentName}' external-cli runner requires a non-empty command string.`);
+	}
+	if (runner.args !== undefined && (!Array.isArray(runner.args) || runner.args.some((arg) => typeof arg !== "string"))) {
+		throw new Error(`Agent '${agentName}' external-cli runner args must be an array of strings.`);
+	}
+	if (runner.promptDelivery !== undefined && runner.promptDelivery !== "stdin") {
+		throw new Error(`Agent '${agentName}' external-cli runner promptDelivery must be 'stdin'.`);
+	}
+	const supported = new Set(["type", "command", "args", "promptDelivery"]);
+	const unknown = Object.keys(runner).filter((key) => !supported.has(key));
+	if (unknown.length > 0) throw new Error(`Agent '${agentName}' external-cli runner has unsupported fields: ${unknown.join(", ")}.`);
+	const runnerArgs = Array.isArray(runner.args) ? runner.args.filter((arg): arg is string => typeof arg === "string") : undefined;
+	return {
+		type: "external-cli",
+		command: runner.command.trim(),
+		...(runnerArgs?.length ? { args: runnerArgs } : {}),
+		...(runner.promptDelivery ? { promptDelivery: "stdin" as const } : {}),
+	};
+}
+
+function validateExternalRunnerProfile(frontmatter: Record<string, string>, agentName: string, runner: AgentRunnerConfig | undefined): void {
+	if (runner?.type !== "external-cli") 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(", ")}.`);
+	}
+}
+
 function parseAgentAcceptanceFrontmatter(raw: string | undefined, agentName: string): AcceptanceInput | undefined {
 	if (raw === undefined || !raw.trim()) return undefined;
 	let parsed: unknown;
@@ -1437,6 +1508,8 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		const packageName = parsedPackage.packageName;
 		const runtimeName = buildRuntimeName(localName, packageName);
 
+		const runner = parseAgentRunnerFrontmatter(frontmatter.runner, localName);
+		validateExternalRunnerProfile(frontmatter, localName, runner);
 		const rawTools = parseFrontmatterList(frontmatter.tools);
 		const parsedTools = splitToolList(rawTools);
 		const tools = parsedTools.tools ?? [];
@@ -1504,6 +1577,13 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		}
 
 		const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+		if (frontmatter.permission !== undefined && frontmatter.permissions !== undefined) {
+			throw new Error(`Agent '${localName}' cannot declare both permission and permissions frontmatter.`);
+		}
+		const permissionSource = frontmatter.permissions ?? frontmatter.permission;
+		const permissions = permissionSource?.trim()
+			? validatePermissionRules(parseYaml(permissionSource), `Agent '${localName}' permissions`)
+			: undefined;
 		let toolBudget: ToolBudgetConfig | undefined;
 		if (frontmatter.toolBudget !== undefined && frontmatter.toolBudget.trim()) {
 			const parsed = JSON.parse(frontmatter.toolBudget) as unknown;
@@ -1518,45 +1598,48 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 				? true
 				: undefined;
 
+		const maxSubagentDepth = Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0
+			? parsedMaxSubagentDepth
+			: undefined;
+		const memory = parseMemoryFrontmatter(frontmatter.memory);
 		const agent: AgentConfig = {
 			name: runtimeName,
+			...(runner !== undefined ? { runner } : {}),
 			localName,
-			packageName,
+			...(packageName !== undefined ? { packageName } : {}),
 			description: frontmatter.description,
-			aliases,
-			tools: rawTools !== undefined ? tools : undefined,
-			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
-			model: frontmatter.model,
-			fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : undefined,
-			thinking: frontmatter.thinking === "false" ? false : frontmatter.thinking,
+			...(aliases !== undefined ? { aliases } : {}),
+			...(rawTools !== undefined ? { tools } : {}),
+			...(mcpDirectTools.length > 0 ? { mcpDirectTools } : {}),
+			...(frontmatter.model !== undefined ? { model: frontmatter.model } : {}),
+			...(fallbackModels?.length ? { fallbackModels } : {}),
+			...(frontmatter.thinking !== undefined ? { thinking: frontmatter.thinking === "false" ? false : frontmatter.thinking } : {}),
 			systemPromptMode,
 			inheritProjectContext,
 			inheritSkills,
-			defaultContext,
-			defaultAsync,
-			defaultTimeoutMs,
-			defaultTurnBudget,
-			defaultAcceptance,
-			acceptanceRole,
+			...(defaultContext !== undefined ? { defaultContext } : {}),
+			...(defaultAsync !== undefined ? { defaultAsync } : {}),
+			...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
+			...(defaultTurnBudget !== undefined ? { defaultTurnBudget } : {}),
+			...(defaultAcceptance !== undefined ? { defaultAcceptance } : {}),
+			...(acceptanceRole !== undefined ? { acceptanceRole } : {}),
 			systemPrompt: body,
 			source,
 			filePath,
-			skills: skills && skills.length > 0 ? skills : undefined,
-			skillPath: skillPath && skillPath.length > 0 ? skillPath : undefined,
-			extensions,
-			subagentOnlyExtensions,
-			output: frontmatter.output,
-			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,
+			...(skills?.length ? { skills } : {}),
+			...(skillPath?.length ? { skillPath } : {}),
+			...(extensions !== undefined ? { extensions } : {}),
+			...(subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions } : {}),
+			...(frontmatter.output !== undefined ? { output: frontmatter.output } : {}),
+			...(defaultReads?.length ? { defaultReads } : {}),
 			defaultProgress: frontmatter.defaultProgress === "true",
 			interactive: frontmatter.interactive === "true",
-			maxSubagentDepth:
-				Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0
-					? parsedMaxSubagentDepth
-					: undefined,
-			completionGuard,
-			toolBudget,
-			memory: parseMemoryFrontmatter(frontmatter.memory),
-			extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
+			...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
+			...(completionGuard !== undefined ? { completionGuard } : {}),
+			...(toolBudget !== undefined ? { toolBudget } : {}),
+			...(permissions !== undefined ? { permissions } : {}),
+			...(memory !== undefined ? { memory } : {}),
+			...(Object.keys(extraFields).length > 0 ? { extraFields } : {}),
 		};
 		agentFrontmatterFields.set(agent, new Set(Object.keys(frontmatter)));
 		agents.push(agent);
@@ -1696,7 +1779,7 @@ 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 };
+	return { agents, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}) };
 }
 
 export function discoverAgentsAll(cwd: string): {

package/src/agents/chain-serializer.ts

@@ -17,8 +17,10 @@ function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 	for (const line of configLines) {
 		const match = line.match(/^([\w-]+):\s*(.*)$/);
 		if (!match) continue;
-		const key = match[1].trim().toLowerCase();
-		const rawValue = match[2].trim();
+		const [keyValue, rawValueValue] = match.slice(1);
+		if (keyValue === undefined || rawValueValue === undefined) continue;
+		const key = keyValue.trim().toLowerCase();
+		const rawValue = rawValueValue.trim();
 
 		if (key === "output") {
 			if (rawValue === "false") step.output = false;
@@ -91,7 +93,8 @@ function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 			}
 			const validation = validateToolBudgetConfig(parsed, `toolBudget for step '${agent}'`);
 			if (validation.error) throw new Error(validation.error);
-			step.toolBudget = parsed as ChainStepConfig["toolBudget"];
+			const toolBudget = parsed as ChainStepConfig["toolBudget"];
+			if (toolBudget !== undefined) step.toolBudget = toolBudget;
 		}
 	}
 
@@ -130,12 +133,12 @@ export function parseChain(content: string, source: AgentSource, filePath: strin
 	return {
 		name: buildRuntimeName(localName, packageName),
 		localName,
-		packageName,
+		...(packageName !== undefined ? { packageName } : {}),
 		description: frontmatter.description,
 		source,
 		filePath,
 		steps,
-		extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
+		...(Object.keys(extraFields).length > 0 ? { extraFields } : {}),
 	};
 }
 
@@ -213,12 +216,12 @@ export function parseJsonChain(content: string, source: AgentSource, filePath: s
 	return {
 		name: buildRuntimeName(input.name.trim(), parsedPackage.packageName),
 		localName: input.name.trim(),
-		packageName: parsedPackage.packageName,
+		...(parsedPackage.packageName !== undefined ? { packageName: parsedPackage.packageName } : {}),
 		description: input.description.trim(),
 		source,
 		filePath,
 		steps: input.chain as ChainStepConfig[],
-		extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
+		...(Object.keys(extraFields).length > 0 ? { extraFields } : {}),
 	};
 }
 

package/src/agents/frontmatter.ts

@@ -113,20 +113,22 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 
 		const match = line.match(/^([\w-]+):\s*(.*)$/);
 		if (match) {
-			const rawValue = match[2].trim();
+			const [key, rawValueValue] = match.slice(1);
+			if (key === undefined || rawValueValue === undefined) continue;
+			const rawValue = rawValueValue.trim();
 			const isQuoted = (rawValue.startsWith('"') && rawValue.endsWith('"')) || (rawValue.startsWith("'") && rawValue.endsWith("'"));
 			const value = isQuoted ? rawValue.slice(1, -1) : rawValue;
 			const isFolded = !isQuoted && (rawValue === ">" || rawValue === ">-");
 
 			if (value === "" || isFolded) {
 				// Key with empty value or folded block indicator — defer storing until we see indent
-				currentKey = match[1];
+				currentKey = key;
 				currentBlockLines = [];
 				currentIndent = indent;
 				currentFolded = isFolded;
 			} else {
 				// Simple key: value
-				frontmatter[match[1]] = value;
+				frontmatter[key] = value;
 			}
 		}
 		// Lines that don't match a key pattern (e.g., comments, empty lines) are ignored

package/src/agents/identity.ts

@@ -9,7 +9,7 @@ function normalizePackageName(value: string | undefined): string | undefined {
 }
 
 export function parsePackageName(value: unknown, label = "package"): { packageName?: string; error?: string } {
-	if (value === undefined || value === false || value === "") return { packageName: undefined };
+	if (value === undefined || value === false || value === "") return {};
 	if (typeof value !== "string") return { error: `${label} must be a string or false when provided.` };
 	const packageName = normalizePackageName(value);
 	if (!packageName || !IDENTIFIER_PATTERN.test(packageName)) return { error: `${label} is invalid after sanitization.` };

package/src/agents/proactive-skills.ts

@@ -141,14 +141,17 @@ export function recommendProactiveSkillSubagents(input: {
 
 	return [...counts.entries()]
 		.filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)))
-		.map(([skill, sources]) => ({
-			skill,
-			agent,
-			references: sources.size,
-			sources: [...sources].sort((a, b) => a.localeCompare(b)),
-			description: availableByName?.get(skill)?.description,
-			reason: `referenced by ${sources.size} configured agents/chains`,
-		}))
+		.map(([skill, sources]) => {
+			const description = availableByName?.get(skill)?.description;
+			return {
+				skill,
+				agent,
+				references: sources.size,
+				sources: [...sources].sort((a, b) => a.localeCompare(b)),
+				...(description !== undefined ? { description } : {}),
+				reason: `referenced by ${sources.size} configured agents/chains`,
+			};
+		})
 		.sort((a, b) => b.references - a.references || a.skill.localeCompare(b.skill))
 		.slice(0, config.maxRecommendations);
 }
@@ -184,8 +187,8 @@ export function buildProactiveSkillSubagentRecommendationLines(input: {
 	}
 	return formatProactiveSkillSubagentRecommendations(recommendProactiveSkillSubagents({
 		agents: input.agents,
-		chains: input.chains,
+		...(input.chains !== undefined ? { chains: input.chains } : {}),
 		availableSkills,
-		config: input.config,
+		...(input.config !== undefined ? { config: input.config } : {}),
 	}));
 }

package/src/agents/skills.ts

@@ -125,8 +125,23 @@ function getGlobalNpmRoot(): string | null {
 	const offline = process.env.PI_OFFLINE?.toLowerCase();
 	if (offline === "1" || offline === "true" || offline === "yes") return null;
 	if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
+
+	const windowsGlobalRoot = process.platform === "win32" && process.env.APPDATA
+		? path.join(process.env.APPDATA, "npm", "node_modules")
+		: undefined;
+	if (windowsGlobalRoot) {
+		try {
+			if (fs.statSync(windowsGlobalRoot).isDirectory()) {
+				cachedGlobalNpmRoot = fs.realpathSync(windowsGlobalRoot);
+				return cachedGlobalNpmRoot;
+			}
+		} catch {
+			// Fall through if the directory disappears while resolving it.
+		}
+	}
+
 	try {
-		cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
 		return cachedGlobalNpmRoot;
 	} catch {
 		// Global npm root is optional in constrained environments.
@@ -410,15 +425,17 @@ function collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: Skil
 		const resolvedFile = path.resolve(filePath);
 		if (!fs.existsSync(resolvedFile)) return;
 		const source = inferSkillSource(resolvedFile, cwd, agentDir, sourceHint);
+		const description = maybeReadSkillDescription(resolvedFile);
 		const existingIndex = seen.get(resolvedFile);
 		if (existingIndex !== undefined) {
 			const existing = entries[existingIndex];
 			if (existing && (SOURCE_PRIORITY[source] ?? 0) > (SOURCE_PRIORITY[existing.source] ?? 0)) {
+				const { description: _description, ...existingWithoutDescription } = existing;
 				entries[existingIndex] = {
-					...existing,
+					...existingWithoutDescription,
 					name,
 					source,
-					description: maybeReadSkillDescription(resolvedFile),
+					...(description !== undefined ? { description } : {}),
 				};
 			}
 			return;
@@ -428,7 +445,7 @@ function collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: Skil
 			name,
 			filePath: resolvedFile,
 			source,
-			description: maybeReadSkillDescription(resolvedFile),
+			...(description !== undefined ? { description } : {}),
 			order: order++,
 		});
 	};
@@ -592,7 +609,7 @@ function readSkill(
 			name: skillName,
 			path: skillPath,
 			content,
-			description,
+			...(description !== undefined ? { description } : {}),
 			source,
 		};
 
@@ -733,7 +750,7 @@ export function discoverAvailableSkills(cwd: string): Array<{
 		.map((s) => ({
 			name: s.name,
 			source: s.source,
-			description: s.description,
+			...(s.description !== undefined ? { description: s.description } : {}),
 		}))
 		.sort((a, b) => a.name.localeCompare(b.name));
 }

package/src/api/control-channel.ts

@@ -0,0 +1,4 @@
+export {
+	requestAsyncStop,
+	type StopRequest,
+} from "../runs/background/control-channel.ts";