@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/dist/agents/management-config.js

@@ -0,0 +1,332 @@
+import { csvItems, isConfigObject, errorMessage } from "./config-values.js";
+class ConfigValidationError extends Error {
+}
+export function configObject(config) {
+    let value = config;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch (error) {
+            return { error: `config must be valid JSON: ${errorMessage(error)}` };
+        }
+    }
+    return isConfigObject(value) ? { value } : {};
+}
+export function hasKey(object, key) {
+    return Object.hasOwn(object, key);
+}
+export function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function parseCsv(value) {
+    return [...new Set(csvItems(value))];
+}
+function invalid(field, expected) {
+    throw new ConfigValidationError(`config.${field} must be ${expected} when provided.`);
+}
+function stringField(value, field, trim = false) {
+    if (value === false || value === "") {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        return invalid(field, "a string or false");
+    }
+    const parsed = trim ? value.trim() : value;
+    return parsed.length === 0 ? undefined : parsed;
+}
+function csvField(value, field) {
+    if (value === false || value === "") {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        return invalid(field, "a comma-separated string or false");
+    }
+    const parsed = parseCsv(value);
+    return parsed.length > 0 ? parsed : undefined;
+}
+function booleanField(value, field) {
+    return typeof value === "boolean" ? value : invalid(field, "a boolean");
+}
+function limitField(value, field, minimum) {
+    if (value === false || value === "") {
+        return undefined;
+    }
+    if (typeof value === "number" && Number.isInteger(value) && value >= minimum) {
+        return value;
+    }
+    return invalid(field, `an integer >= ${minimum} or false`);
+}
+function fallbackModels(value) {
+    if (value === false || value === "") {
+        return undefined;
+    }
+    let models;
+    if (typeof value === "string") {
+        models = parseCsv(value);
+    }
+    else if (Array.isArray(value)) {
+        models = [
+            ...new Set(value
+                .filter((item) => typeof item === "string")
+                .map((item) => item.trim())
+                .filter((item) => item.length > 0)),
+        ];
+    }
+    else {
+        return invalid("fallbackModels", "a comma-separated string, string array, or false");
+    }
+    return models.length > 0 ? models : undefined;
+}
+function tools(value) {
+    const parsed = csvField(value, "tools") ?? [];
+    const direct = parsed
+        .filter((item) => item.startsWith("mcp:"))
+        .map((item) => item.slice(4).trim())
+        .filter((item) => item.length > 0);
+    const native = parsed.filter((item) => !item.startsWith("mcp:"));
+    return {
+        tools: native.length > 0 ? native : undefined,
+        mcpDirectTools: direct.length > 0 ? direct : undefined,
+    };
+}
+function extensions(value) {
+    if (value === false) {
+        return undefined;
+    }
+    if (typeof value === "string") {
+        return parseCsv(value);
+    }
+    return invalid("extensions", "a comma-separated string, empty string, or false");
+}
+function promptMode(value) {
+    return value === "append" || value === "replace"
+        ? value
+        : invalid("systemPromptMode", "'append' or 'replace'");
+}
+function defaultContext(value) {
+    if (value === false || value === "") {
+        return undefined;
+    }
+    return value === "fresh" || value === "fork"
+        ? value
+        : invalid("defaultContext", "'fresh', 'fork', or false");
+}
+const AGENT_FIELD_ORDER = [
+    "systemPrompt",
+    "model",
+    "fallbackModels",
+    "tools",
+    "skills",
+    "extensions",
+    "thinking",
+    "systemPromptMode",
+    "inheritProjectContext",
+    "inheritSkills",
+    "defaultContext",
+    "output",
+    "reads",
+    "progress",
+    "allowSubagents",
+    "maxSubagentDepth",
+    "maxExecutionTimeMs",
+    "maxTokens",
+    "completionGuard",
+];
+function agentFieldPatch(field, value) {
+    switch (field) {
+        case "systemPrompt":
+            return { systemPrompt: stringField(value, field) ?? "" };
+        case "model":
+            return { model: stringField(value, field, true) };
+        case "fallbackModels":
+            return { fallbackModels: fallbackModels(value) };
+        case "tools":
+            return tools(value);
+        case "skills":
+            return { skills: csvField(value, field) };
+        case "extensions":
+            return { extensions: extensions(value) };
+        case "thinking":
+            return { thinking: stringField(value, field, true) };
+        case "systemPromptMode":
+            return { systemPromptMode: promptMode(value) };
+        case "inheritProjectContext":
+            return { inheritProjectContext: booleanField(value, field) };
+        case "inheritSkills":
+            return { inheritSkills: booleanField(value, field) };
+        case "defaultContext":
+            return { defaultContext: defaultContext(value) };
+        case "output":
+            return { output: stringField(value, field) };
+        case "reads":
+            return { defaultReads: csvField(value, field) };
+        case "progress":
+            return { defaultProgress: booleanField(value, field) };
+        case "allowSubagents":
+            return { allowSubagents: booleanField(value, field) };
+        case "maxSubagentDepth":
+            return { maxSubagentDepth: limitField(value, field, 0) };
+        case "maxExecutionTimeMs":
+            return { maxExecutionTimeMs: limitField(value, field, 1) };
+        case "maxTokens":
+            return { maxTokens: limitField(value, field, 1) };
+        case "completionGuard":
+            return { completionGuard: booleanField(value, field) };
+    }
+}
+const AGENT_KEYS = new Set(["name", "package", "description", "scope", ...AGENT_FIELD_ORDER]);
+const CHAIN_KEYS = new Set(["name", "package", "description", "scope", "steps"]);
+function unknownKeys(cfg, keys) {
+    const unknown = Object.keys(cfg).filter((key) => !keys.includes(key));
+    return unknown.length > 0
+        ? `config has unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`
+        : undefined;
+}
+export function validateChainConfigKeys(cfg) {
+    return unknownKeys(cfg, [...CHAIN_KEYS]);
+}
+export function parseAgentPatch(cfg) {
+    const error = unknownKeys(cfg, [...AGENT_KEYS]);
+    if (error !== undefined) {
+        return { error };
+    }
+    try {
+        const patch = {};
+        for (const field of AGENT_FIELD_ORDER) {
+            if (hasKey(cfg, field)) {
+                Object.assign(patch, agentFieldPatch(field, cfg[field]));
+            }
+        }
+        return { value: patch };
+    }
+    catch (caught) {
+        if (caught instanceof ConfigValidationError) {
+            return { error: caught.message };
+        }
+        throw caught;
+    }
+}
+const STEP_KEYS = new Set([
+    "agent",
+    "task",
+    "phase",
+    "label",
+    "as",
+    "outputSchema",
+    "output",
+    "outputMode",
+    "reads",
+    "model",
+    "skills",
+    "progress",
+]);
+function stepError(index, field, expected) {
+    throw new ConfigValidationError(`config.steps[${index}].${field} must be ${expected}.`);
+}
+function stepString(step, field, index) {
+    if (!hasKey(step, field)) {
+        return undefined;
+    }
+    const value = step[field];
+    return typeof value === "string" ? value : stepError(index, field, "a string");
+}
+function stepList(step, field, index) {
+    if (!hasKey(step, field)) {
+        return undefined;
+    }
+    const value = step[field];
+    if (value === false) {
+        return false;
+    }
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        return value.map((item) => item.trim()).filter((item) => item.length > 0);
+    }
+    return stepError(index, field, "a string array or false");
+}
+function stepOutput(step, index) {
+    if (!hasKey(step, "output")) {
+        return undefined;
+    }
+    const value = step.output;
+    return typeof value === "string" || value === false
+        ? value
+        : stepError(index, "output", "a string or false");
+}
+function stepOutputMode(step, index) {
+    if (!hasKey(step, "outputMode")) {
+        return undefined;
+    }
+    const value = step.outputMode;
+    return value === "inline" || value === "file-only"
+        ? value
+        : stepError(index, "outputMode", "'inline' or 'file-only'");
+}
+function stepProgress(step, index) {
+    if (!hasKey(step, "progress")) {
+        return undefined;
+    }
+    return typeof step.progress === "boolean"
+        ? step.progress
+        : stepError(index, "progress", "a boolean");
+}
+function stepSchema(step, index) {
+    if (!hasKey(step, "outputSchema")) {
+        return undefined;
+    }
+    return typeof step.outputSchema === "string"
+        ? step.outputSchema
+        : stepError(index, "outputSchema", "a schema file path string for saved chains");
+}
+function parseStep(item, index) {
+    if (!isConfigObject(item)) {
+        throw new ConfigValidationError(`config.steps[${index}] must be an object.`);
+    }
+    if (hasKey(item, "skill")) {
+        throw new ConfigValidationError(`config.steps[${index}].skill is not supported; use skills.`);
+    }
+    const unknown = Object.keys(item).filter((key) => !STEP_KEYS.has(key));
+    if (unknown.length > 0) {
+        throw new ConfigValidationError(`config.steps[${index}] has unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`);
+    }
+    if (typeof item.agent !== "string" || item.agent.trim().length === 0) {
+        return stepError(index, "agent", "a non-empty string");
+    }
+    return {
+        agent: item.agent.trim(),
+        task: typeof item.task === "string" ? item.task : "",
+        phase: stepString(item, "phase", index),
+        label: stepString(item, "label", index),
+        as: stepString(item, "as", index),
+        outputSchema: stepSchema(item, index),
+        output: stepOutput(item, index),
+        outputMode: stepOutputMode(item, index),
+        reads: stepList(item, "reads", index),
+        model: stepString(item, "model", index),
+        skills: stepList(item, "skills", index),
+        progress: stepProgress(item, index),
+    };
+}
+export 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." };
+    }
+    try {
+        return { value: raw.map((item, index) => parseStep(item, index)) };
+    }
+    catch (caught) {
+        if (caught instanceof ConfigValidationError) {
+            return { error: caught.message };
+        }
+        throw caught;
+    }
+}

package/dist/agents/management-format.js

@@ -0,0 +1,231 @@
+import { resolveEffectiveThinking } from "../shared/model-info.js";
+import { frontmatterNameForConfig } from "./identity.js";
+import { isConfigObject } from "./config-values.js";
+export 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 !== undefined && fallbacks.length > 0 ? fallbacks.join(", ") : "none configured"}`,
+    ];
+}
+function optionalLine(label, value) {
+    return value !== undefined && value.length > 0 ? [`${label}: ${value}`] : [];
+}
+function listLine(label, value) {
+    return value !== undefined && value.length > 0 ? [`${label}: ${value.join(", ")}`] : [];
+}
+function packageLines(config) {
+    return config.packageName !== undefined && config.packageName.length > 0
+        ? [`Local name: ${frontmatterNameForConfig(config)}`, `Package: ${config.packageName}`]
+        : [];
+}
+function executionLines(agent) {
+    return [
+        ...optionalLine("Output", agent.output),
+        ...listLine("Reads", agent.defaultReads),
+        ...(agent.defaultProgress === true ? ["Progress: true"] : []),
+        ...(agent.allowSubagents === true ? ["Allow subagents: true"] : []),
+        ...(agent.maxSubagentDepth === undefined
+            ? []
+            : [`Max subagent depth: ${agent.maxSubagentDepth}`]),
+        ...(agent.maxExecutionTimeMs === undefined
+            ? []
+            : [`Max execution time: ${agent.maxExecutionTimeMs}ms`]),
+        ...(agent.maxTokens === undefined ? [] : [`Max tokens: ${agent.maxTokens}`]),
+        ...(agent.completionGuard === undefined ? [] : [`Completion guard: ${agent.completionGuard}`]),
+    ];
+}
+export function formatAgentDetail(agent) {
+    const tools = [
+        ...(agent.tools ?? []),
+        ...(agent.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
+    ];
+    const lines = [
+        `Agent: ${agent.name} (${agent.source})`,
+        `Path: ${agent.filePath}`,
+        `Description: ${agent.description}`,
+        ...packageLines(agent),
+        ...formatModelDefaults(agent),
+        ...listLine("Tools", tools),
+        ...listLine("Skills", agent.skills),
+        `System prompt mode: ${agent.systemPromptMode}`,
+        `Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`,
+        `Inherit skills: ${agent.inheritSkills ? "true" : "false"}`,
+        ...optionalLine("Default context", agent.defaultContext),
+        ...(agent.source === "builtin"
+            ? [`Disabled: ${agent.disabled === true ? "true" : "false"}`]
+            : []),
+        ...(agent.extensions === undefined
+            ? []
+            : [`Extensions: ${agent.extensions.length > 0 ? agent.extensions.join(", ") : "(none)"}`]),
+        ...executionLines(agent),
+    ];
+    if (agent.systemPrompt.trim().length > 0) {
+        lines.push("", "System Prompt:", agent.systemPrompt);
+    }
+    return lines.join("\n");
+}
+function hasDisplayValue(value) {
+    return Boolean(value);
+}
+function displayUnknown(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (value === undefined) {
+        return "undefined";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" ||
+        typeof value === "bigint" ||
+        typeof value === "boolean" ||
+        typeof value === "symbol") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => (item === null || item === undefined ? "" : displayUnknown(item)))
+            .join(",");
+    }
+    return Object.prototype.toString.call(value);
+}
+function dynamicExpansionLines(value) {
+    if (!isConfigObject(value)) {
+        return [];
+    }
+    const lines = [];
+    if (isConfigObject(value.from)) {
+        lines.push(`   Expand: ${displayUnknown(value.from.output ?? "?")}${displayUnknown(value.from.path ?? "")}`);
+    }
+    if (typeof value.item === "string") {
+        lines.push(`   Item variable: ${value.item}`);
+    }
+    if (typeof value.key === "string") {
+        lines.push(`   Key: ${value.key}`);
+    }
+    if (typeof value.maxItems === "number") {
+        lines.push(`   Max items: ${value.maxItems}`);
+    }
+    if (typeof value.onEmpty === "string") {
+        lines.push(`   On empty: ${value.onEmpty}`);
+    }
+    return lines;
+}
+function dynamicTemplateLines(value) {
+    if (!isConfigObject(value)) {
+        return [];
+    }
+    const lines = [];
+    if (hasDisplayValue(value.agent)) {
+        lines.push(`   Agent: ${displayUnknown(value.agent)}`);
+    }
+    if (typeof value.label === "string") {
+        lines.push(`   Label: ${value.label}`);
+    }
+    if (typeof value.task === "string" && value.task.trim().length > 0) {
+        lines.push(`   Task: ${value.task}`);
+    }
+    if (hasDisplayValue(value.outputSchema)) {
+        lines.push("   Structured output: true");
+    }
+    return lines;
+}
+function formatDynamicStep(step, index) {
+    const collect = isConfigObject(step.collect) ? step.collect : undefined;
+    return [
+        `${index + 1}. Dynamic fanout${typeof collect?.as === "string" ? ` -> ${collect.as}` : ""}`,
+        ...dynamicExpansionLines(step.expand),
+        ...dynamicTemplateLines(step.parallel),
+        ...(hasDisplayValue(collect?.outputSchema) ? ["   Collect schema: true"] : []),
+        ...(step.concurrency === undefined ? [] : [`   Concurrency: ${step.concurrency}`]),
+        ...(step.failFast === undefined ? [] : [`   Fail fast: ${step.failFast ? "true" : "false"}`]),
+    ];
+}
+function stepListLine(label, value) {
+    return value === false ? [`   ${label}: false`] : listLine(`   ${label}`, value);
+}
+function formatChainStepDetail(step, index) {
+    if (step.expand !== undefined || step.collect !== undefined) {
+        return formatDynamicStep(step, index);
+    }
+    const lines = [
+        `${index + 1}. ${step.agent ?? "undefined"}`,
+        ...optionalLine("   Task", step.task?.trim().length === 0 ? undefined : step.task),
+        ...(step.output === false ? ["   Output: false"] : optionalLine("   Output", step.output)),
+        ...optionalLine("   Output mode", step.outputMode),
+        ...stepListLine("Reads", step.reads),
+        ...optionalLine("   Model", step.model),
+        ...stepListLine("Skills", step.skills),
+        ...(step.progress === undefined ? [] : [`   Progress: ${step.progress ? "true" : "false"}`]),
+    ];
+    return lines;
+}
+export function formatChainDetail(chain) {
+    return [
+        `Chain: ${chain.name} (${chain.source})`,
+        `Path: ${chain.filePath}`,
+        `Description: ${chain.description}`,
+        ...packageLines(chain),
+        "",
+        "Steps:",
+        ...chain.steps.flatMap((step, index) => formatChainStepDetail(step, index)),
+    ].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";
+    }
+    return agent.source === "builtin" ? "Specialized" : "Custom/other";
+}
+function formatAgentListLine(agent) {
+    return `- ${agent.name} (${agent.source}${agent.defaultContext === undefined ? "" : `, context: ${agent.defaultContext}`}): ${agent.description}\n  ${formatModelDefaults(agent).join("; ")}`;
+}
+export function formatAgentGroups(agents) {
+    const lines = ["Executable agents (grouped by role):"];
+    if (agents.length === 0) {
+        return [...lines, "- (none)"];
+    }
+    const roles = [
+        "Recon",
+        "Planning",
+        "Implementation",
+        "Review",
+        "Coordination",
+        "Specialized",
+        "Custom/other",
+    ];
+    for (const role of roles) {
+        const group = agents.filter((agent) => agentListRole(agent) === role);
+        if (group.length > 0) {
+            lines.push("", `**${role}** — ${AGENT_ROLE_HINTS[role]}`, ...group.map(formatAgentListLine));
+        }
+    }
+    return lines;
+}