@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/dist/agents/agent-management.js

@@ -0,0 +1,923 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { defaultInheritProjectContext, defaultInheritSkills, defaultSystemPromptMode, discoverAgents, discoverAgentsAll, buildRuntimeName, frontmatterNameForConfig, parsePackageName, } from "./agents.js";
+import { serializeAgent } from "./agent-serializer.js";
+import { serializeChain, serializeJsonChain } from "./chain-serializer.js";
+import { discoverAvailableSkills } from "./skills.js";
+import { isClaudeCodeModel } from "../runs/shared/claude-code.js";
+import { resolveEffectiveThinking } from "../shared/model-info.js";
+function result(text, isError = false) {
+    return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
+}
+function parseCsv(value) {
+    return [...new Set(value.split(",").map((v) => v.trim()).filter(Boolean))];
+}
+function configObject(config) {
+    let val = config;
+    if (typeof val === "string") {
+        try {
+            val = JSON.parse(val);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { error: `config must be valid JSON: ${message}` };
+        }
+    }
+    if (!val || typeof val !== "object" || Array.isArray(val))
+        return {};
+    return { value: val };
+}
+function hasKey(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function asDisambiguationScope(scope) {
+    if (scope === "user" || scope === "project")
+        return scope;
+    return undefined;
+}
+function normalizeListScope(scope) {
+    if (scope === undefined)
+        return "both";
+    if (scope === "user" || scope === "project" || scope === "both")
+        return scope;
+    return undefined;
+}
+function sanitizeName(name) {
+    return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+}
+function parsePackageConfig(value) {
+    return parsePackageName(value, "config.package");
+}
+function allAgents(d) {
+    return [...d.builtin, ...d.package, ...d.user, ...d.project];
+}
+function discoveryOptions(ctx) {
+    return { projectTrusted: ctx.isProjectTrusted() };
+}
+function availableNames(ctx, kind, scope = "both") {
+    const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
+    const items = kind === "agent" ? allAgents(d) : d.chains;
+    return [...new Set(items.map((x) => x.name))].sort((a, b) => a.localeCompare(b));
+}
+function findAgents(name, ctx, scope = "both") {
+    const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
+    const raw = name.trim();
+    const sanitized = sanitizeName(raw);
+    return allAgents(d)
+        .filter((a) => (scope === "both" || a.source === scope) && (a.name === raw || a.name === sanitized))
+        .sort((a, b) => a.source.localeCompare(b.source));
+}
+function findChains(name, ctx, scope = "both") {
+    const raw = name.trim();
+    const sanitized = sanitizeName(raw);
+    return discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope).chains
+        .filter((c) => (scope === "both" || c.source === scope) && (c.name === raw || c.name === sanitized))
+        .sort((a, b) => a.source.localeCompare(b.source));
+}
+function findEffectiveAgents(name, ctx, scope = "both") {
+    const raw = name.trim();
+    const sanitized = sanitizeName(raw);
+    return discoverAgents(ctx.cwd, scope, discoveryOptions(ctx)).agents
+        .filter((a) => a.name === raw || a.name === sanitized);
+}
+function nameExistsInScope(ctx, scope, name, excludePath) {
+    const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
+    for (const a of scope === "user" ? d.user : d.project) {
+        if (a.name === name && a.filePath !== excludePath)
+            return true;
+    }
+    for (const c of d.chains) {
+        if (c.source === scope && c.name === name && c.filePath !== excludePath)
+            return true;
+    }
+    return false;
+}
+function unknownChainAgents(ctx, steps) {
+    const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx));
+    const known = new Set(allAgents(d).map((a) => a.name));
+    return [...new Set(steps.map((s) => s.agent).filter((agent) => typeof agent === "string" && !known.has(agent)))].sort((a, b) => a.localeCompare(b));
+}
+function chainStepWarnings(ctx, steps) {
+    const warnings = [];
+    const available = new Set(discoverAvailableSkills(ctx.cwd, discoveryOptions(ctx)).map((s) => s.name));
+    for (let i = 0; i < steps.length; i++) {
+        const s = steps[i];
+        if (s.model && !isClaudeCodeModel(s.model)) {
+            const found = ctx.modelRegistry.getAvailable().some((m) => `${m.provider}/${m.id}` === s.model || m.id === s.model);
+            if (!found)
+                warnings.push(`Warning: step ${i + 1} (${s.agent}): model '${s.model}' is not in the current model registry.`);
+        }
+        if (Array.isArray(s.skills) && s.skills.length > 0) {
+            const missing = s.skills.filter((sk) => !available.has(sk));
+            if (missing.length)
+                warnings.push(`Warning: step ${i + 1} (${s.agent}): skills not found: ${missing.join(", ")}.`);
+        }
+    }
+    return warnings;
+}
+function modelWarning(ctx, model) {
+    if (!model || isClaudeCodeModel(model))
+        return undefined;
+    const found = ctx.modelRegistry.getAvailable().some((m) => `${m.provider}/${m.id}` === model || m.id === model);
+    return found ? undefined : `Warning: model '${model}' is not in the current model registry.`;
+}
+function fallbackModelsWarning(ctx, fallbackModels) {
+    if (!fallbackModels || fallbackModels.length === 0)
+        return undefined;
+    const available = new Set(ctx.modelRegistry.getAvailable().flatMap((m) => [`${m.provider}/${m.id}`, m.id]));
+    const missing = fallbackModels.filter((model) => !isClaudeCodeModel(model) && !available.has(model));
+    return missing.length ? `Warning: fallback models not in the current model registry: ${missing.join(", ")}.` : undefined;
+}
+function skillsWarning(ctx, skills) {
+    if (!skills || skills.length === 0)
+        return undefined;
+    const available = new Set(discoverAvailableSkills(ctx.cwd, discoveryOptions(ctx)).map((s) => s.name));
+    const missing = skills.filter((s) => !available.has(s));
+    return missing.length ? `Warning: skills not found: ${missing.join(", ")}.` : undefined;
+}
+const SAVED_CHAIN_STEP_KEYS = new Set(["agent", "task", "phase", "label", "as", "outputSchema", "output", "outputMode", "reads", "model", "skills", "progress"]);
+function parseStepList(raw) {
+    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." };
+    const steps = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return { error: `config.steps[${i}] must be an object.` };
+        const s = item;
+        if (hasKey(s, "skill"))
+            return { error: `config.steps[${i}].skill is not supported; use skills.` };
+        const unknownKeys = Object.keys(s).filter((key) => !SAVED_CHAIN_STEP_KEYS.has(key));
+        if (unknownKeys.length)
+            return { error: `config.steps[${i}] has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.` };
+        if (typeof s.agent !== "string" || !s.agent.trim())
+            return { error: `config.steps[${i}].agent must be a non-empty string.` };
+        const step = { agent: s.agent.trim(), task: typeof s.task === "string" ? s.task : "" };
+        if (hasKey(s, "phase")) {
+            if (typeof s.phase === "string")
+                step.phase = s.phase;
+            else
+                return { error: `config.steps[${i}].phase must be a string.` };
+        }
+        if (hasKey(s, "label")) {
+            if (typeof s.label === "string")
+                step.label = s.label;
+            else
+                return { error: `config.steps[${i}].label must be a string.` };
+        }
+        if (hasKey(s, "as")) {
+            if (typeof s.as === "string")
+                step.as = s.as;
+            else
+                return { error: `config.steps[${i}].as must be a string.` };
+        }
+        if (hasKey(s, "outputSchema")) {
+            if (typeof s.outputSchema === "string")
+                step.outputSchema = s.outputSchema;
+            else
+                return { error: `config.steps[${i}].outputSchema must be a schema file path string for saved chains.` };
+        }
+        if (hasKey(s, "output")) {
+            if (s.output === false)
+                step.output = false;
+            else if (typeof s.output === "string")
+                step.output = s.output;
+            else
+                return { error: `config.steps[${i}].output must be a string or false.` };
+        }
+        if (hasKey(s, "outputMode")) {
+            if (s.outputMode === "inline" || s.outputMode === "file-only")
+                step.outputMode = s.outputMode;
+            else
+                return { error: `config.steps[${i}].outputMode must be 'inline' or 'file-only'.` };
+        }
+        if (hasKey(s, "reads")) {
+            if (s.reads === false)
+                step.reads = false;
+            else if (Array.isArray(s.reads) && s.reads.every((value) => typeof value === "string"))
+                step.reads = s.reads.map((value) => value.trim()).filter(Boolean);
+            else
+                return { error: `config.steps[${i}].reads must be a string array or false.` };
+        }
+        if (hasKey(s, "model")) {
+            if (typeof s.model === "string")
+                step.model = s.model;
+            else
+                return { error: `config.steps[${i}].model must be a string.` };
+        }
+        if (hasKey(s, "skill")) {
+            return { error: `config.steps[${i}].skill is not supported for saved chains; use skills (array or false).` };
+        }
+        if (hasKey(s, "skills")) {
+            if (s.skills === false)
+                step.skills = false;
+            else if (Array.isArray(s.skills) && s.skills.every((value) => typeof value === "string"))
+                step.skills = s.skills.map((value) => value.trim()).filter(Boolean);
+            else
+                return { error: `config.steps[${i}].skills must be a string array or false.` };
+        }
+        if (hasKey(s, "progress")) {
+            if (typeof s.progress === "boolean")
+                step.progress = s.progress;
+            else
+                return { error: `config.steps[${i}].progress must be a boolean.` };
+        }
+        steps.push(step);
+    }
+    return { steps };
+}
+function parseTools(raw) {
+    const tools = [];
+    const mcpDirectTools = [];
+    for (const item of parseCsv(raw)) {
+        if (item.startsWith("mcp:")) {
+            const direct = item.slice(4).trim();
+            if (direct)
+                mcpDirectTools.push(direct);
+        }
+        else
+            tools.push(item);
+    }
+    return { tools: tools.length ? tools : undefined, mcpDirectTools: mcpDirectTools.length ? mcpDirectTools : undefined };
+}
+const CHAIN_CONFIG_KEYS = new Set(["name", "package", "description", "scope", "steps"]);
+function validateChainConfigKeys(cfg) {
+    const unknownKeys = Object.keys(cfg).filter((key) => !CHAIN_CONFIG_KEYS.has(key));
+    return unknownKeys.length ? `config has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.` : undefined;
+}
+const AGENT_CONFIG_KEYS = new Set([
+    "name", "package", "description", "scope", "systemPrompt", "model", "fallbackModels", "tools", "skills", "extensions", "thinking",
+    "systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "output", "reads", "progress", "allowSubagents",
+    "maxSubagentDepth", "maxExecutionTimeMs", "maxTokens", "completionGuard",
+]);
+function applyAgentConfig(target, cfg) {
+    const unknownKeys = Object.keys(cfg).filter((key) => !AGENT_CONFIG_KEYS.has(key));
+    if (unknownKeys.length)
+        return `config has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.`;
+    if (hasKey(cfg, "systemPrompt")) {
+        if (cfg.systemPrompt === false || cfg.systemPrompt === "")
+            target.systemPrompt = "";
+        else if (typeof cfg.systemPrompt === "string")
+            target.systemPrompt = cfg.systemPrompt;
+        else
+            return "config.systemPrompt must be a string or false when provided.";
+    }
+    if (hasKey(cfg, "model")) {
+        if (cfg.model === false || cfg.model === "")
+            target.model = undefined;
+        else if (typeof cfg.model === "string")
+            target.model = cfg.model.trim() || undefined;
+        else
+            return "config.model must be a string or false when provided.";
+    }
+    if (hasKey(cfg, "fallbackModels")) {
+        if (cfg.fallbackModels === false || cfg.fallbackModels === "")
+            target.fallbackModels = undefined;
+        else if (typeof cfg.fallbackModels === "string") {
+            const models = parseCsv(cfg.fallbackModels);
+            target.fallbackModels = models.length ? models : undefined;
+        }
+        else if (Array.isArray(cfg.fallbackModels)) {
+            const models = cfg.fallbackModels
+                .filter((value) => typeof value === "string")
+                .map((value) => value.trim())
+                .filter(Boolean);
+            target.fallbackModels = models.length ? [...new Set(models)] : undefined;
+        }
+        else
+            return "config.fallbackModels must be a comma-separated string, string array, or false when provided.";
+    }
+    if (hasKey(cfg, "tools")) {
+        if (cfg.tools === false || cfg.tools === "") {
+            target.tools = undefined;
+            target.mcpDirectTools = undefined;
+        }
+        else if (typeof cfg.tools === "string") {
+            const parsed = parseTools(cfg.tools);
+            target.tools = parsed.tools;
+            target.mcpDirectTools = parsed.mcpDirectTools;
+        }
+        else
+            return "config.tools must be a comma-separated string or false when provided.";
+    }
+    if (hasKey(cfg, "skills")) {
+        if (cfg.skills === false || cfg.skills === "")
+            target.skills = undefined;
+        else if (typeof cfg.skills === "string") {
+            const skills = parseCsv(cfg.skills);
+            target.skills = skills.length ? skills : undefined;
+        }
+        else
+            return "config.skills must be a comma-separated string or false when provided.";
+    }
+    if (hasKey(cfg, "extensions")) {
+        if (cfg.extensions === false)
+            target.extensions = undefined;
+        else if (cfg.extensions === "")
+            target.extensions = [];
+        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, "thinking")) {
+        if (cfg.thinking === false || cfg.thinking === "")
+            target.thinking = undefined;
+        else if (typeof cfg.thinking === "string")
+            target.thinking = cfg.thinking.trim() || undefined;
+        else
+            return "config.thinking must be a string or false when provided.";
+    }
+    if (hasKey(cfg, "systemPromptMode")) {
+        if (cfg.systemPromptMode === "append" || cfg.systemPromptMode === "replace")
+            target.systemPromptMode = cfg.systemPromptMode;
+        else
+            return "config.systemPromptMode must be 'append' or 'replace' when provided.";
+    }
+    if (hasKey(cfg, "inheritProjectContext")) {
+        if (typeof cfg.inheritProjectContext !== "boolean")
+            return "config.inheritProjectContext must be a boolean when provided.";
+        target.inheritProjectContext = cfg.inheritProjectContext;
+    }
+    if (hasKey(cfg, "inheritSkills")) {
+        if (typeof cfg.inheritSkills !== "boolean")
+            return "config.inheritSkills must be a boolean when provided.";
+        target.inheritSkills = cfg.inheritSkills;
+    }
+    if (hasKey(cfg, "defaultContext")) {
+        if (cfg.defaultContext === false || cfg.defaultContext === "")
+            target.defaultContext = undefined;
+        else if (cfg.defaultContext === "fresh" || cfg.defaultContext === "fork")
+            target.defaultContext = cfg.defaultContext;
+        else
+            return "config.defaultContext must be 'fresh', 'fork', or false when provided.";
+    }
+    if (hasKey(cfg, "output")) {
+        if (cfg.output === false || cfg.output === "")
+            target.output = undefined;
+        else if (typeof cfg.output === "string")
+            target.output = cfg.output;
+        else
+            return "config.output must be a string or false when provided.";
+    }
+    if (hasKey(cfg, "reads")) {
+        if (cfg.reads === false || cfg.reads === "")
+            target.defaultReads = undefined;
+        else if (typeof cfg.reads === "string") {
+            const reads = parseCsv(cfg.reads);
+            target.defaultReads = reads.length ? reads : undefined;
+        }
+        else
+            return "config.reads must be a comma-separated string or false when provided.";
+    }
+    if (hasKey(cfg, "progress")) {
+        if (typeof cfg.progress !== "boolean")
+            return "config.progress must be a boolean when provided.";
+        target.defaultProgress = cfg.progress;
+    }
+    if (hasKey(cfg, "allowSubagents")) {
+        if (typeof cfg.allowSubagents !== "boolean")
+            return "config.allowSubagents must be a boolean when provided.";
+        target.allowSubagents = cfg.allowSubagents;
+    }
+    if (hasKey(cfg, "maxSubagentDepth")) {
+        if (cfg.maxSubagentDepth === false || cfg.maxSubagentDepth === "")
+            target.maxSubagentDepth = undefined;
+        else if (typeof cfg.maxSubagentDepth === "number" && Number.isInteger(cfg.maxSubagentDepth) && cfg.maxSubagentDepth >= 0) {
+            target.maxSubagentDepth = cfg.maxSubagentDepth;
+        }
+        else
+            return "config.maxSubagentDepth must be an integer >= 0 or false when provided.";
+    }
+    if (hasKey(cfg, "maxExecutionTimeMs")) {
+        if (cfg.maxExecutionTimeMs === false || cfg.maxExecutionTimeMs === "")
+            target.maxExecutionTimeMs = undefined;
+        else if (typeof cfg.maxExecutionTimeMs === "number" && Number.isInteger(cfg.maxExecutionTimeMs) && cfg.maxExecutionTimeMs >= 1) {
+            target.maxExecutionTimeMs = cfg.maxExecutionTimeMs;
+        }
+        else
+            return "config.maxExecutionTimeMs must be an integer >= 1 or false when provided.";
+    }
+    if (hasKey(cfg, "maxTokens")) {
+        if (cfg.maxTokens === false || cfg.maxTokens === "")
+            target.maxTokens = undefined;
+        else if (typeof cfg.maxTokens === "number" && Number.isInteger(cfg.maxTokens) && cfg.maxTokens >= 1) {
+            target.maxTokens = cfg.maxTokens;
+        }
+        else
+            return "config.maxTokens must be an integer >= 1 or false when provided.";
+    }
+    if (hasKey(cfg, "completionGuard")) {
+        if (typeof cfg.completionGuard !== "boolean")
+            return "config.completionGuard must be a boolean when provided.";
+        target.completionGuard = cfg.completionGuard;
+    }
+    return undefined;
+}
+function isMutableTarget(target) {
+    return target.source === "user" || target.source === "project";
+}
+function resolveTarget(kind, name, matches, ctx, scopeHint) {
+    const mutable = matches.filter(isMutableTarget);
+    if (mutable.length === 0) {
+        if (matches.length > 0) {
+            return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' is ${matches[0].source} and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`, true);
+        }
+        const available = availableNames(ctx, kind);
+        return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${available.join(", ") || "none"}.`, true);
+    }
+    if (mutable.length === 1)
+        return mutable[0];
+    const scope = asDisambiguationScope(scopeHint);
+    if (!scope) {
+        const paths = mutable.map((m) => `${m.source}: ${m.filePath}`).join("\n");
+        const sources = new Set(mutable.map((entry) => entry.source));
+        return sources.size === 1
+            ? result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' has multiple definitions in ${mutable[0].source} scope and cannot be modified safely. Remove or rename one definition first.\n${paths}`, true)
+            : result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' exists in both scopes. Specify agentScope: 'user' or 'project'.\n${paths}`, true);
+    }
+    const scoped = mutable.filter((m) => m.source === scope);
+    if (scoped.length === 0)
+        return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found in scope '${scope}'.`, true);
+    if (scoped.length > 1) {
+        return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' has multiple definitions in scope '${scope}' and cannot be modified safely. Remove or rename one definition first:\n${scoped.map((entry) => entry.filePath).join("\n")}`, true);
+    }
+    return scoped[0];
+}
+function renamePath(kind, currentPath, newName, scope, ctx) {
+    if (nameExistsInScope(ctx, scope, newName, currentPath))
+        return { error: `Name '${newName}' already exists in ${scope} scope.` };
+    const ext = kind === "agent" ? ".md" : currentPath.endsWith(".chain.json") ? ".chain.json" : ".chain.md";
+    const filePath = path.join(path.dirname(currentPath), `${newName}${ext}`);
+    if (fs.existsSync(filePath) && filePath !== currentPath) {
+        return { error: `File already exists at ${filePath} but is not a valid ${kind} definition. Remove or rename it first.` };
+    }
+    fs.renameSync(currentPath, filePath);
+    return { filePath };
+}
+function formatModelDefaults(agent) {
+    const thinking = resolveEffectiveThinking(agent.model, agent.thinking) ?? agent.thinking;
+    const inherited = "inherited runtime default (unset)";
+    const fallbacks = agent.fallbackModels?.map((model) => `${model} (thinking: ${resolveEffectiveThinking(model, agent.thinking ?? thinking) ?? inherited})`);
+    return [
+        `Model: ${agent.model ?? "inherited from parent (resolved at launch)"}`,
+        `Thinking: ${thinking ?? inherited}`,
+        `Fallback models: ${fallbacks?.length ? fallbacks.join(", ") : "none configured"}`,
+    ];
+}
+function formatAgentDetail(agent) {
+    const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
+    const lines = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
+    if (agent.packageName) {
+        lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
+        lines.push(`Package: ${agent.packageName}`);
+    }
+    lines.push(...formatModelDefaults(agent));
+    if (tools.length)
+        lines.push(`Tools: ${tools.join(", ")}`);
+    if (agent.skills?.length)
+        lines.push(`Skills: ${agent.skills.join(", ")}`);
+    lines.push(`System prompt mode: ${agent.systemPromptMode}`);
+    lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
+    lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
+    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.output)
+        lines.push(`Output: ${agent.output}`);
+    if (agent.defaultReads?.length)
+        lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
+    if (agent.defaultProgress)
+        lines.push("Progress: true");
+    if (agent.allowSubagents)
+        lines.push("Allow subagents: true");
+    if (agent.maxSubagentDepth !== undefined)
+        lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
+    if (agent.maxExecutionTimeMs !== undefined)
+        lines.push(`Max execution time: ${agent.maxExecutionTimeMs}ms`);
+    if (agent.maxTokens !== undefined)
+        lines.push(`Max tokens: ${agent.maxTokens}`);
+    if (agent.completionGuard !== undefined)
+        lines.push(`Completion guard: ${agent.completionGuard}`);
+    if (agent.systemPrompt.trim())
+        lines.push("", "System Prompt:", agent.systemPrompt);
+    return lines.join("\n");
+}
+function formatChainStepDetail(step, index) {
+    const lines = [];
+    if (step.expand || step.collect) {
+        const parallel = step.parallel && !Array.isArray(step.parallel) && typeof step.parallel === "object" ? step.parallel : undefined;
+        const expand = step.expand && typeof step.expand === "object" ? step.expand : undefined;
+        const collect = step.collect && typeof step.collect === "object" ? step.collect : undefined;
+        lines.push(`${index + 1}. Dynamic fanout${typeof collect?.as === "string" ? ` -> ${collect.as}` : ""}`);
+        if (expand?.from)
+            lines.push(`   Expand: ${String(expand.from.output ?? "?")}${String(expand.from.path ?? "")}`);
+        if (typeof expand?.item === "string")
+            lines.push(`   Item variable: ${expand.item}`);
+        if (typeof expand?.key === "string")
+            lines.push(`   Key: ${expand.key}`);
+        if (typeof expand?.maxItems === "number")
+            lines.push(`   Max items: ${expand.maxItems}`);
+        if (typeof expand?.onEmpty === "string")
+            lines.push(`   On empty: ${expand.onEmpty}`);
+        if (parallel?.agent)
+            lines.push(`   Agent: ${String(parallel.agent)}`);
+        if (typeof parallel?.label === "string")
+            lines.push(`   Label: ${parallel.label}`);
+        if (typeof parallel?.task === "string" && parallel.task.trim())
+            lines.push(`   Task: ${parallel.task}`);
+        if (parallel?.outputSchema)
+            lines.push("   Structured output: true");
+        if (collect?.outputSchema)
+            lines.push("   Collect schema: true");
+        if (step.concurrency !== undefined)
+            lines.push(`   Concurrency: ${step.concurrency}`);
+        if (step.failFast !== undefined)
+            lines.push(`   Fail fast: ${step.failFast ? "true" : "false"}`);
+        return lines;
+    }
+    lines.push(`${index + 1}. ${step.agent}`);
+    if (step.task?.trim())
+        lines.push(`   Task: ${step.task}`);
+    if (step.output === false)
+        lines.push("   Output: false");
+    else if (step.output)
+        lines.push(`   Output: ${step.output}`);
+    if (step.outputMode)
+        lines.push(`   Output mode: ${step.outputMode}`);
+    if (step.reads === false)
+        lines.push("   Reads: false");
+    else if (Array.isArray(step.reads) && step.reads.length > 0)
+        lines.push(`   Reads: ${step.reads.join(", ")}`);
+    if (step.model)
+        lines.push(`   Model: ${step.model}`);
+    if (step.skills === false)
+        lines.push("   Skills: false");
+    else if (Array.isArray(step.skills) && step.skills.length > 0)
+        lines.push(`   Skills: ${step.skills.join(", ")}`);
+    if (step.progress !== undefined)
+        lines.push(`   Progress: ${step.progress ? "true" : "false"}`);
+    return lines;
+}
+function formatChainDetail(chain) {
+    const lines = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`];
+    if (chain.packageName) {
+        lines.push(`Local name: ${frontmatterNameForConfig(chain)}`);
+        lines.push(`Package: ${chain.packageName}`);
+    }
+    lines.push("", "Steps:");
+    for (let i = 0; i < chain.steps.length; i++) {
+        lines.push(...formatChainStepDetail(chain.steps[i], i));
+    }
+    return lines.join("\n");
+}
+const AGENT_ROLE_HINTS = {
+    Recon: "Use for read-only codebase mapping, grep/delta sweeps, and external facts.",
+    Planning: "Use when decomposition or an implementation handoff matters.",
+    Implementation: "Use for bounded code/doc changes after scope is clear.",
+    Review: "Use for independent validation, regressions, and drift checks.",
+    Coordination: "Use for generic delegation or high-context decision checks.",
+    Specialized: "Use only when the task matches the skill description.",
+    "Custom/other": "Project/user agents not classified by the builtins.",
+};
+function agentListRole(agent) {
+    const name = agent.name.split(".").at(-1) ?? agent.name;
+    if (["scout", "context-builder", "researcher"].includes(name))
+        return "Recon";
+    if (name === "planner")
+        return "Planning";
+    if (["worker", "fixer"].includes(name))
+        return "Implementation";
+    if (name === "reviewer" || name.includes("review"))
+        return "Review";
+    if (["delegate", "oracle"].includes(name))
+        return "Coordination";
+    if (agent.source === "builtin")
+        return "Specialized";
+    return "Custom/other";
+}
+function formatAgentListLine(a) {
+    return `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}): ${a.description}\n  ${formatModelDefaults(a).join("; ")}`;
+}
+export function handleList(params, ctx) {
+    const scope = normalizeListScope(params.agentScope);
+    if (!scope)
+        return result("agentScope must be 'user', 'project', or 'both'.", true);
+    const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
+    const agents = discoverAgents(ctx.cwd, scope, discoveryOptions(ctx)).agents
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+    const diagnostics = [...d.agentDiagnostics, ...d.chainDiagnostics];
+    const roleOrder = ["Recon", "Planning", "Implementation", "Review", "Coordination", "Specialized", "Custom/other"];
+    const lines = ["Executable agents (grouped by role):"];
+    if (!agents.length) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const role of roleOrder) {
+            const group = agents.filter((agent) => agentListRole(agent) === role);
+            if (!group.length)
+                continue;
+            lines.push(``, `**${role}** — ${AGENT_ROLE_HINTS[role]}`, ...group.map(formatAgentListLine));
+        }
+    }
+    lines.push("", "Chains:", ...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]), ...(diagnostics.length ? ["", "Discovery diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []));
+    return result(lines.join("\n"));
+}
+function handleGet(params, ctx) {
+    if (!params.agent && !params.chainName)
+        return result("Specify 'agent' or 'chainName' for get.", true);
+    const hasBoth = Boolean(params.agent && params.chainName);
+    const blocks = [];
+    let anyFound = false;
+    const scope = normalizeListScope(params.agentScope);
+    if (!scope)
+        return result("agentScope must be 'user', 'project', or 'both'.", true);
+    if (params.agent) {
+        const matches = findEffectiveAgents(params.agent, ctx, scope);
+        if (!matches.length) {
+            const msg = `Agent '${params.agent}' not found. Available: ${availableNames(ctx, "agent", scope).join(", ") || "none"}.`;
+            if (!hasBoth)
+                return result(msg, true);
+            blocks.push(msg);
+        }
+        else {
+            anyFound = true;
+            blocks.push(...matches.map(formatAgentDetail));
+        }
+    }
+    if (params.chainName) {
+        const matches = findChains(params.chainName, ctx, scope);
+        if (!matches.length) {
+            const msg = `Chain '${params.chainName}' not found. Available: ${availableNames(ctx, "chain", scope).join(", ") || "none"}.`;
+            if (!hasBoth)
+                return result(msg, true);
+            blocks.push(msg);
+        }
+        else {
+            anyFound = true;
+            blocks.push(...matches.map(formatChainDetail));
+        }
+    }
+    return result(blocks.join("\n\n"), !anyFound);
+}
+export function handleCreate(params, ctx) {
+    const parsedConfig = configObject(params.config);
+    if (parsedConfig.error)
+        return result(parsedConfig.error, true);
+    const cfg = parsedConfig.value;
+    if (!cfg)
+        return result("config required for create.", true);
+    if (typeof cfg.name !== "string" || !cfg.name.trim())
+        return result("config.name is required and must be a non-empty string.", true);
+    if (typeof cfg.description !== "string" || !cfg.description.trim())
+        return result("config.description is required and must be a non-empty string.", true);
+    const name = sanitizeName(cfg.name);
+    if (!name)
+        return result("config.name is invalid after sanitization. Use letters, numbers, spaces, or hyphens.", true);
+    const parsedPackage = parsePackageConfig(cfg.package);
+    if (parsedPackage.error)
+        return result(parsedPackage.error, true);
+    const runtimeName = buildRuntimeName(name, parsedPackage.packageName);
+    const scopeRaw = cfg.scope ?? "user";
+    if (scopeRaw !== "user" && scopeRaw !== "project")
+        return result("config.scope must be 'user' or 'project'.", true);
+    const scope = scopeRaw;
+    const isChain = hasKey(cfg, "steps");
+    const options = discoveryOptions(ctx);
+    if (scope === "project" && options.projectTrusted === false)
+        return result("Project scope is not available because this project is untrusted. Run from a trusted project or use scope: 'user'.", true);
+    const d = discoverAgentsAll(ctx.cwd, options);
+    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");
+    fs.mkdirSync(targetDir, { recursive: true });
+    if (nameExistsInScope(ctx, 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`);
+    if (fs.existsSync(targetPath))
+        return result(`File already exists at ${targetPath} but is not a valid ${isChain ? "chain" : "agent"} definition. Remove or rename it first.`, true);
+    const warnings = [];
+    if (!isChain && d.builtin.some((a) => a.name === runtimeName))
+        warnings.push(`Note: this shadows the builtin agent '${runtimeName}'.`);
+    if (isChain) {
+        const keyError = validateChainConfigKeys(cfg);
+        if (keyError)
+            return result(keyError, true);
+        const parsed = parseStepList(cfg.steps);
+        if (parsed.error)
+            return result(parsed.error, true);
+        const chain = { name: runtimeName, localName: name, packageName: parsedPackage.packageName, description: cfg.description.trim(), source: scope, filePath: targetPath, steps: parsed.steps };
+        fs.writeFileSync(targetPath, serializeChain(chain), "utf-8");
+        const missing = unknownChainAgents(ctx, chain.steps);
+        if (missing.length)
+            warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
+        warnings.push(...chainStepWarnings(ctx, chain.steps));
+        return result([`Created chain '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
+    }
+    const agent = {
+        name: runtimeName,
+        localName: name,
+        packageName: parsedPackage.packageName,
+        description: cfg.description.trim(),
+        source: scope,
+        filePath: targetPath,
+        systemPrompt: "",
+        systemPromptMode: defaultSystemPromptMode(name),
+        inheritProjectContext: defaultInheritProjectContext(name),
+        inheritSkills: defaultInheritSkills(),
+        maxSubagentDepth: 0,
+    };
+    const applyError = applyAgentConfig(agent, cfg);
+    if (applyError)
+        return result(applyError, true);
+    const mw = modelWarning(ctx, agent.model);
+    if (mw)
+        warnings.push(mw);
+    const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
+    if (fmw)
+        warnings.push(fmw);
+    const sw = skillsWarning(ctx, agent.skills);
+    if (sw)
+        warnings.push(sw);
+    fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
+    return result([`Created agent '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
+}
+export function handleUpdate(params, ctx) {
+    if (!params.agent && !params.chainName)
+        return result("Specify 'agent' or 'chainName' for update.", true);
+    if (params.agent && params.chainName)
+        return result("Specify either 'agent' or 'chainName', not both.", true);
+    const parsedConfig = configObject(params.config);
+    if (parsedConfig.error)
+        return result(parsedConfig.error, true);
+    const cfg = parsedConfig.value;
+    if (!cfg)
+        return result("config required for update.", true);
+    const warnings = [];
+    if (params.agent) {
+        const scopeHint = asDisambiguationScope(params.agentScope);
+        const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx, params.agentScope);
+        if ("content" in targetOrError)
+            return targetOrError;
+        const target = targetOrError;
+        const updated = { ...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);
+        let newLocalName = target.localName ?? frontmatterNameForConfig(target);
+        if (hasKey(cfg, "name")) {
+            newLocalName = sanitizeName(cfg.name);
+            if (!newLocalName)
+                return result("config.name is invalid after sanitization.", true);
+        }
+        let newPackageName = target.packageName;
+        if (hasKey(cfg, "package")) {
+            const parsedPackage = parsePackageConfig(cfg.package);
+            if (parsedPackage.error)
+                return result(parsedPackage.error, true);
+            newPackageName = parsedPackage.packageName;
+        }
+        const applyError = applyAgentConfig(updated, cfg);
+        if (applyError)
+            return result(applyError, true);
+        updated.localName = newLocalName;
+        updated.packageName = newPackageName;
+        updated.name = buildRuntimeName(newLocalName, newPackageName);
+        if (hasKey(cfg, "description"))
+            updated.description = cfg.description.trim();
+        if (hasKey(cfg, "model")) {
+            const mw = modelWarning(ctx, updated.model);
+            if (mw)
+                warnings.push(mw);
+        }
+        if (hasKey(cfg, "fallbackModels")) {
+            const fmw = fallbackModelsWarning(ctx, updated.fallbackModels);
+            if (fmw)
+                warnings.push(fmw);
+        }
+        if (hasKey(cfg, "skills")) {
+            const sw = skillsWarning(ctx, updated.skills);
+            if (sw)
+                warnings.push(sw);
+        }
+        if (updated.name !== oldName) {
+            const renamed = renamePath("agent", target.filePath, updated.name, target.source, ctx);
+            if (renamed.error)
+                return result(renamed.error, true);
+            updated.filePath = renamed.filePath;
+        }
+        fs.writeFileSync(updated.filePath, serializeAgent(updated), "utf-8");
+        if (updated.name !== oldName) {
+            const refs = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx)).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(", ")}.`);
+        }
+        const headline = updated.name === oldName
+            ? `Updated agent '${updated.name}' at ${updated.filePath}.`
+            : `Updated agent '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
+        return result([headline, ...warnings].join("\n"));
+    }
+    const scopeHint = asDisambiguationScope(params.agentScope);
+    const targetOrError = resolveTarget("chain", params.chainName, findChains(params.chainName, ctx, scopeHint ?? "both"), ctx, params.agentScope);
+    if ("content" in targetOrError)
+        return targetOrError;
+    const target = targetOrError;
+    const keyError = validateChainConfigKeys(cfg);
+    if (keyError)
+        return result(keyError, true);
+    const updated = { ...target, steps: [...target.steps] };
+    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);
+    let newLocalName = target.localName ?? frontmatterNameForConfig(target);
+    if (hasKey(cfg, "name")) {
+        newLocalName = sanitizeName(cfg.name);
+        if (!newLocalName)
+            return result("config.name is invalid after sanitization.", true);
+    }
+    let newPackageName = target.packageName;
+    if (hasKey(cfg, "package")) {
+        const parsedPackage = parsePackageConfig(cfg.package);
+        if (parsedPackage.error)
+            return result(parsedPackage.error, true);
+        newPackageName = parsedPackage.packageName;
+    }
+    let parsedSteps;
+    if (hasKey(cfg, "steps")) {
+        const parsed = parseStepList(cfg.steps);
+        if (parsed.error)
+            return result(parsed.error, true);
+        parsedSteps = parsed.steps;
+    }
+    updated.localName = newLocalName;
+    updated.packageName = newPackageName;
+    updated.name = buildRuntimeName(newLocalName, newPackageName);
+    if (hasKey(cfg, "description"))
+        updated.description = cfg.description.trim();
+    if (parsedSteps) {
+        updated.steps = parsedSteps;
+        const missing = unknownChainAgents(ctx, updated.steps);
+        if (missing.length)
+            warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
+        warnings.push(...chainStepWarnings(ctx, updated.steps));
+    }
+    if (updated.name !== oldName) {
+        const renamed = renamePath("chain", target.filePath, updated.name, target.source, ctx);
+        if (renamed.error)
+            return result(renamed.error, true);
+        updated.filePath = renamed.filePath;
+    }
+    fs.writeFileSync(updated.filePath, updated.filePath.endsWith(".chain.json") ? serializeJsonChain(updated) : serializeChain(updated), "utf-8");
+    const headline = updated.name === oldName
+        ? `Updated chain '${updated.name}' at ${updated.filePath}.`
+        : `Updated chain '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
+    return result([headline, ...warnings].join("\n"));
+}
+function handleDelete(params, ctx) {
+    if (!params.agent && !params.chainName)
+        return result("Specify 'agent' or 'chainName' for delete.", true);
+    if (params.agent && params.chainName)
+        return result("Specify either 'agent' or 'chainName', not both.", true);
+    const scopeHint = asDisambiguationScope(params.agentScope);
+    if (params.agent) {
+        const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx, params.agentScope);
+        if ("content" in targetOrError)
+            return targetOrError;
+        const target = targetOrError;
+        fs.unlinkSync(target.filePath);
+        const refs = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx)).chains.filter((c) => c.steps.some((s) => s.agent === target.name)).map((c) => `${c.name} (${c.source})`);
+        const lines = [`Deleted agent '${target.name}' at ${target.filePath}.`];
+        if (refs.length)
+            lines.push(`Warning: chains reference deleted agent '${target.name}': ${refs.join(", ")}.`);
+        return result(lines.join("\n"));
+    }
+    const targetOrError = resolveTarget("chain", params.chainName, findChains(params.chainName, ctx, scopeHint ?? "both"), ctx, params.agentScope);
+    if ("content" in targetOrError)
+        return targetOrError;
+    const target = targetOrError;
+    fs.unlinkSync(target.filePath);
+    return result(`Deleted chain '${target.name}' at ${target.filePath}.`);
+}
+export function handleManagementAction(action, params, ctx) {
+    if (params.agentScope !== undefined && normalizeListScope(params.agentScope) === undefined) {
+        return result("agentScope must be 'user', 'project', or 'both'.", true);
+    }
+    switch (action) {
+        case "list": return handleList(params, ctx);
+        case "get": return handleGet(params, ctx);
+        case "create": return handleCreate(params, ctx);
+        case "update": return handleUpdate(params, ctx);
+        case "delete": return handleDelete(params, ctx);
+        default: return result(`Unknown action: ${action}`, true);
+    }
+}