pi-subagents 0.29.0 → 0.31.0

package/src/agents/agent-management.ts

@@ -8,6 +8,7 @@ import {
 	type AgentSource,
 	type ChainConfig,
 	type ChainStepConfig,
+	BUILTIN_AGENT_NAMES,
 	defaultInheritProjectContext,
 	defaultInheritSkills,
 	defaultSystemPromptMode,
@@ -19,11 +20,18 @@ import {
 import { serializeAgent } from "./agent-serializer.ts";
 import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
 import { discoverAvailableSkills } from "./skills.ts";
-import type { Details } from "../shared/types.ts";
-
-type ManagementAction = "list" | "get" | "create" | "update" | "delete";
+import {
+	buildProactiveSkillSubagentRecommendationLines,
+} from "./proactive-skills.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { toModelInfo } from "../shared/model-info.ts";
+import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
+import type { Details, ExtensionConfig } from "../shared/types.ts";
+import { getProjectConfigDir } from "../shared/utils.ts";
+
+type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete";
 type ManagementScope = "user" | "project";
-type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry">;
+type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig };
 
 interface ManagementParams {
 	action?: string;
@@ -163,6 +171,84 @@ function skillsWarning(cwd: string, skills: string[] | undefined): string | unde
 	return missing.length ? `Warning: skills not found: ${missing.join(", ")}.` : undefined;
 }
 
+function editableAgentConfig(agent: AgentConfig): AgentConfig {
+	const base = agent.override?.base;
+	if (!base) return { ...agent };
+
+	return {
+		...agent,
+		model: base.model,
+		fallbackModels: base.fallbackModels ? [...base.fallbackModels] : undefined,
+		thinking: base.thinking,
+		systemPromptMode: base.systemPromptMode,
+		inheritProjectContext: base.inheritProjectContext,
+		inheritSkills: base.inheritSkills,
+		defaultContext: base.defaultContext,
+		disabled: base.disabled,
+		systemPrompt: base.systemPrompt,
+		skills: base.skills ? [...base.skills] : undefined,
+		tools: base.tools ? [...base.tools] : undefined,
+		mcpDirectTools: base.mcpDirectTools ? [...base.mcpDirectTools] : undefined,
+		subagentOnlyExtensions: base.subagentOnlyExtensions ? [...base.subagentOnlyExtensions] : undefined,
+		completionGuard: base.completionGuard,
+		override: undefined,
+	};
+}
+
+function readAgentFrontmatterFields(filePath: string): Set<string> {
+	try {
+		const { frontmatter } = parseFrontmatter(fs.readFileSync(filePath, "utf-8"));
+		return new Set(Object.keys(frontmatter));
+	} catch {
+		return new Set();
+	}
+}
+
+function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string, unknown>): Set<string> {
+	const fields = readAgentFrontmatterFields(agent.filePath);
+	const changed = (...names: string[]) => {
+		for (const name of names) fields.delete(name);
+	};
+
+	if (hasKey(cfg, "name")) changed("name");
+	if (hasKey(cfg, "package")) changed("package");
+	if (hasKey(cfg, "description")) changed("description");
+	if (hasKey(cfg, "systemPrompt")) changed("systemPrompt");
+	if (hasKey(cfg, "model")) changed("model");
+	if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
+	if (hasKey(cfg, "tools")) changed("tools");
+	if (hasKey(cfg, "skills")) changed("skill", "skills");
+	if (hasKey(cfg, "extensions")) changed("extensions");
+	if (hasKey(cfg, "subagentOnlyExtensions")) changed("subagentOnlyExtensions");
+	if (hasKey(cfg, "thinking")) {
+		changed("thinking");
+		if (cfg.thinking === "off") fields.add("thinking");
+	}
+	if (hasKey(cfg, "systemPromptMode")) {
+		changed("systemPromptMode");
+		fields.add("systemPromptMode");
+	}
+	if (hasKey(cfg, "inheritProjectContext")) {
+		changed("inheritProjectContext");
+		fields.add("inheritProjectContext");
+	}
+	if (hasKey(cfg, "inheritSkills")) {
+		changed("inheritSkills");
+		fields.add("inheritSkills");
+	}
+	if (hasKey(cfg, "defaultContext")) changed("defaultContext");
+	if (hasKey(cfg, "output")) changed("output");
+	if (hasKey(cfg, "reads")) changed("defaultReads");
+	if (hasKey(cfg, "progress")) changed("defaultProgress");
+	if (hasKey(cfg, "maxSubagentDepth")) changed("maxSubagentDepth");
+	if (hasKey(cfg, "completionGuard")) {
+		changed("completionGuard");
+		if (cfg.completionGuard === true) fields.add("completionGuard");
+	}
+
+	return fields;
+}
+
 function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: string } {
 	if (!Array.isArray(raw)) return { error: "config.steps must be an array." };
 	if (raw.length === 0) return { error: "config.steps must include at least one step." };
@@ -273,6 +359,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.extensions === "string") target.extensions = parseCsv(cfg.extensions);
 		else return "config.extensions must be a comma-separated string, empty string, or false when provided.";
 	}
+	if (hasKey(cfg, "subagentOnlyExtensions")) {
+		if (cfg.subagentOnlyExtensions === false) target.subagentOnlyExtensions = undefined;
+		else if (cfg.subagentOnlyExtensions === "") target.subagentOnlyExtensions = [];
+		else if (typeof cfg.subagentOnlyExtensions === "string") target.subagentOnlyExtensions = parseCsv(cfg.subagentOnlyExtensions);
+		else return "config.subagentOnlyExtensions must be a comma-separated string, empty string, or false when provided.";
+	}
 	if (hasKey(cfg, "thinking")) {
 		if (cfg.thinking === false || cfg.thinking === "") target.thinking = undefined;
 		else if (typeof cfg.thinking === "string") target.thinking = cfg.thinking.trim() || undefined;
@@ -385,6 +477,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
 	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
+	if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
@@ -450,6 +543,12 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const agents = scopedAgents.filter((a) => !a.disabled);
 	const chains = d.chains.filter((c) => scope === "both" || c.source === "package" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const diagnostics = d.chainDiagnostics.filter((entry) => scope === "both" || entry.source === scope);
+	const proactiveSuggestions = buildProactiveSkillSubagentRecommendationLines({
+		agents,
+		chains,
+		config: ctx.config?.proactiveSkillSubagents,
+		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
+	});
 	const lines = [
 		"Executable agents:",
 		...(agents.length
@@ -458,11 +557,90 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
+		...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
 		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
 	];
 	return result(lines.join("\n"));
 }
 
+function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {
+	if (agent.override && agent.model !== agent.override.base.model) {
+		return `${agent.override.scope} override`;
+	}
+	if (agent.model) return "builtin agent config";
+	if (currentModel) return "inherits current session model";
+	return "inherit requested, but no current session model is available";
+}
+
+function handleModels(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+	const requestedAgent = params.agent?.trim();
+	if (requestedAgent && !(BUILTIN_AGENT_NAMES as readonly string[]).includes(requestedAgent)) {
+		return result(`Builtin agent '${requestedAgent}' not found. Available: ${BUILTIN_AGENT_NAMES.join(", ")}.`, true);
+	}
+
+	const discovered = discoverAgentsAll(ctx.cwd);
+	const builtinByName = new Map(discovered.builtin.map((agent) => [agent.name, agent]));
+	const availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
+	const currentModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
+	const preferredProvider = ctx.model?.provider;
+	const names = requestedAgent ? [requestedAgent] : [...BUILTIN_AGENT_NAMES];
+
+	if (requestedAgent) {
+		const agent = builtinByName.get(requestedAgent);
+		if (!agent) return result(`Builtin agent '${requestedAgent}' not found.`, true);
+		const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
+		const lines = [
+			"Builtin subagent model",
+			"",
+			`Agent: ${requestedAgent}`,
+			"Effective model:",
+			`  ${resolvedModel ?? "(unresolved)"}`,
+			`Source: ${formatModelSource(agent, currentModel)}`,
+		];
+		if (agent.override) {
+			lines.push("Override file:");
+			lines.push(`  ${agent.override.path}`);
+		}
+		if (agent.model && resolvedModel && agent.model !== resolvedModel) {
+			lines.push("Requested model setting:");
+			lines.push(`  ${agent.model}`);
+		}
+		if (agent.disabled) lines.push("Disabled: true");
+		lines.push("Current session model:");
+		lines.push(`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`);
+		return result(lines.join("\n"));
+	}
+
+	const lines = [
+		"Builtin subagent models",
+		"",
+		"Current session model:",
+		`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
+		"",
+	];
+
+	for (const name of names) {
+		const agent = builtinByName.get(name);
+		if (!agent) {
+			lines.push(name);
+			lines.push("  model:");
+			lines.push("    (builtin definition not found)");
+			lines.push("  source: missing");
+			lines.push("");
+			continue;
+		}
+		const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
+		const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}`;
+		lines.push(name);
+		lines.push("  model:");
+		lines.push(`    ${resolvedModel ?? "(unresolved)"}`);
+		lines.push(`  source: ${source}`);
+		lines.push("");
+	}
+
+	return result(lines.join("\n"));
+}
+
 function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for get.", true);
 	const hasBoth = Boolean(params.agent && params.chainName);
@@ -510,9 +688,10 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const scope = scopeRaw as ManagementScope;
 	const isChain = hasKey(cfg, "steps");
 	const d = discoverAgentsAll(ctx.cwd);
+	const projectConfigDir = getProjectConfigDir(ctx.cwd);
 	const targetDir = isChain
-		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(ctx.cwd, ".pi", "chains")
-		: scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
+		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(projectConfigDir, "chains")
+		: scope === "user" ? d.userDir : d.projectDir ?? path.join(projectConfigDir, "agents");
 	fs.mkdirSync(targetDir, { recursive: true });
 	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
 	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);
@@ -566,7 +745,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
 		if ("content" in targetOrError) return targetOrError;
 		const target = targetOrError;
-		const updated: AgentConfig = { ...target };
+		const updated = editableAgentConfig(target);
 		const oldName = target.name;
 		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
 		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
@@ -583,6 +762,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		}
 		const applyError = applyAgentConfig(updated, cfg);
 		if (applyError) return result(applyError, true);
+		const preserveFrontmatterFields = preservedAgentFrontmatterFields(target, cfg);
 		updated.localName = newLocalName;
 		updated.packageName = newPackageName;
 		updated.name = buildRuntimeName(newLocalName, newPackageName);
@@ -604,7 +784,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 			if (renamed.error) return result(renamed.error, true);
 			updated.filePath = renamed.filePath!;
 		}
-		fs.writeFileSync(updated.filePath, serializeAgent(updated), "utf-8");
+		fs.writeFileSync(updated.filePath, serializeAgent(updated, { preserveFrontmatterFields }), "utf-8");
 		if (updated.name !== oldName) {
 			const refs = discoverAgentsAll(ctx.cwd).chains.filter((c) => c.steps.some((s) => s.agent === oldName)).map((c) => `${c.name} (${c.source})`);
 			if (refs.length) warnings.push(`Warning: chains still reference '${oldName}': ${refs.join(", ")}.`);
@@ -686,6 +866,7 @@ export function handleManagementAction(action: string, params: ManagementParams,
 	switch (action as ManagementAction) {
 		case "list": return handleList(params, ctx);
 		case "get": return handleGet(params, ctx);
+		case "models": return handleModels(params, ctx);
 		case "create": return handleCreate(params, ctx);
 		case "update": return handleUpdate(params, ctx);
 		case "delete": return handleDelete(params, ctx);

package/src/agents/agent-serializer.ts

@@ -16,6 +16,7 @@ export const KNOWN_FIELDS = new Set([
 	"skill",
 	"skills",
 	"extensions",
+	"subagentOnlyExtensions",
 	"output",
 	"defaultReads",
 	"defaultProgress",
@@ -29,8 +30,14 @@ function joinComma(values: string[] | undefined): string | undefined {
 	return values.join(", ");
 }
 
-export function serializeAgent(config: AgentConfig): string {
+interface SerializeAgentOptions {
+	preserveFrontmatterFields?: ReadonlySet<string>;
+}
+
+export function serializeAgent(config: AgentConfig, options: SerializeAgentOptions = {}): string {
 	const lines: string[] = [];
+	const preserve = (...fields: string[]) => fields.some((field) => options.preserveFrontmatterFields?.has(field));
+	const preservingExistingFrontmatter = options.preserveFrontmatterFields !== undefined;
 	lines.push("---");
 	lines.push(`name: ${frontmatterNameForConfig(config)}`);
 	if (config.packageName) lines.push(`package: ${config.packageName}`);
@@ -41,24 +48,30 @@ export function serializeAgent(config: AgentConfig): string {
 		...(config.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
 	];
 	const toolsValue = joinComma(tools);
-	if (toolsValue) lines.push(`tools: ${toolsValue}`);
+	if (toolsValue || preserve("tools")) lines.push(`tools: ${toolsValue ?? ""}`);
 
-	if (config.model) lines.push(`model: ${config.model}`);
+	if (config.model || preserve("model")) lines.push(`model: ${config.model ?? ""}`);
 	const fallbackModelsValue = joinComma(config.fallbackModels);
-	if (fallbackModelsValue) lines.push(`fallbackModels: ${fallbackModelsValue}`);
-	if (config.thinking && config.thinking !== "off") lines.push(`thinking: ${config.thinking}`);
-	lines.push(`systemPromptMode: ${config.systemPromptMode}`);
-	lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
-	lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
-	if (config.defaultContext) lines.push(`defaultContext: ${config.defaultContext}`);
+	if (fallbackModelsValue || preserve("fallbackModels")) lines.push(`fallbackModels: ${fallbackModelsValue ?? ""}`);
+	if ((config.thinking && (config.thinking !== "off" || preserve("thinking"))) || (!config.thinking && preserve("thinking"))) {
+		lines.push(`thinking: ${config.thinking ?? ""}`);
+	}
+	if (!preservingExistingFrontmatter || preserve("systemPromptMode")) lines.push(`systemPromptMode: ${config.systemPromptMode}`);
+	if (!preservingExistingFrontmatter || preserve("inheritProjectContext")) lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
+	if (!preservingExistingFrontmatter || preserve("inheritSkills")) lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
+	if (config.defaultContext || preserve("defaultContext")) lines.push(`defaultContext: ${config.defaultContext ?? ""}`);
 
 	const skillsValue = joinComma(config.skills);
-	if (skillsValue) lines.push(`skills: ${skillsValue}`);
+	if (skillsValue || preserve("skill", "skills")) lines.push(`skills: ${skillsValue ?? ""}`);
 
 	if (config.extensions !== undefined) {
 		const extensionsValue = joinComma(config.extensions);
 		lines.push(`extensions: ${extensionsValue ?? ""}`);
 	}
+	if (config.subagentOnlyExtensions !== undefined || preserve("subagentOnlyExtensions")) {
+		const subagentOnlyExtensionsValue = joinComma(config.subagentOnlyExtensions);
+		lines.push(`subagentOnlyExtensions: ${subagentOnlyExtensionsValue ?? ""}`);
+	}
 
 	if (config.output) lines.push(`output: ${config.output}`);
 
@@ -71,12 +84,22 @@ export function serializeAgent(config: AgentConfig): string {
 	if (typeof maxSubagentDepth === "number" && Number.isInteger(maxSubagentDepth) && maxSubagentDepth >= 0) {
 		lines.push(`maxSubagentDepth: ${maxSubagentDepth}`);
 	}
-	if (config.completionGuard === false) lines.push("completionGuard: false");
+	if (config.completionGuard === false || preserve("completionGuard")) {
+		lines.push(`completionGuard: ${config.completionGuard === undefined ? "" : config.completionGuard ? "true" : "false"}`);
+	}
 
 	if (config.extraFields) {
 		for (const [key, value] of Object.entries(config.extraFields)) {
 			if (KNOWN_FIELDS.has(key)) continue;
-			lines.push(`${key}: ${value}`);
+			if (typeof value === "string" && value.includes("\n")) {
+				// Multi-line block value (e.g. permission: nested YAML)
+				lines.push(`${key}:`);
+				for (const blockLine of value.split("\n")) {
+					lines.push(`  ${blockLine}`);
+				}
+			} else {
+				lines.push(`${key}: ${value}`);
+			}
 		}
 	}