@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/agents/management-config.ts

@@ -0,0 +1,342 @@
+import type { Writable } from "type-fest";
+import type { AgentConfig, ChainStepConfig } from "../shared/types/config.ts";
+import { csvItems, isConfigObject, errorMessage, type ConfigObject } from "./config-values.ts";
+
+export type ConfigParse<T> =
+  | { readonly value: T; readonly error?: never }
+  | { readonly error: string; readonly value?: never };
+class ConfigValidationError extends Error {}
+type AgentPatch = Partial<Writable<AgentConfig>>;
+
+export function configObject(config: unknown): { value?: ConfigObject; error?: string } {
+  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: ConfigObject, key: string): boolean {
+  return Object.hasOwn(object, key);
+}
+export function sanitizeName(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+function parseCsv(value: string): string[] {
+  return [...new Set(csvItems(value))];
+}
+function invalid(field: string, expected: string): never {
+  throw new ConfigValidationError(`config.${field} must be ${expected} when provided.`);
+}
+
+function stringField(value: unknown, field: string, trim = false): string | undefined {
+  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: unknown, field: string): string[] | undefined {
+  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: unknown, field: string): boolean {
+  return typeof value === "boolean" ? value : invalid(field, "a boolean");
+}
+function limitField(value: unknown, field: string, minimum: number): number | undefined {
+  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: unknown): string[] | undefined {
+  if (value === false || value === "") {
+    return undefined;
+  }
+  let models: string[];
+  if (typeof value === "string") {
+    models = parseCsv(value);
+  } else if (Array.isArray(value)) {
+    models = [
+      ...new Set(
+        value
+          .filter((item: unknown): item is string => 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: unknown): Pick<AgentConfig, "tools" | "mcpDirectTools"> {
+  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: unknown): readonly string[] | undefined {
+  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: unknown): "append" | "replace" {
+  return value === "append" || value === "replace"
+    ? value
+    : invalid("systemPromptMode", "'append' or 'replace'");
+}
+function defaultContext(value: unknown): "fresh" | "fork" | undefined {
+  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",
+] as const;
+function agentFieldPatch(field: (typeof AGENT_FIELD_ORDER)[number], value: unknown): AgentPatch {
+  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: ConfigObject, keys: readonly string[]): string | undefined {
+  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: ConfigObject): string | undefined {
+  return unknownKeys(cfg, [...CHAIN_KEYS]);
+}
+export function parseAgentPatch(cfg: ConfigObject): ConfigParse<AgentPatch> {
+  const error = unknownKeys(cfg, [...AGENT_KEYS]);
+  if (error !== undefined) {
+    return { error };
+  }
+  try {
+    const patch: AgentPatch = {};
+    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: number, field: string, expected: string): never {
+  throw new ConfigValidationError(`config.steps[${index}].${field} must be ${expected}.`);
+}
+function stepString(step: ConfigObject, field: string, index: number): string | undefined {
+  if (!hasKey(step, field)) {
+    return undefined;
+  }
+  const value = step[field];
+  return typeof value === "string" ? value : stepError(index, field, "a string");
+}
+function stepList(step: ConfigObject, field: string, index: number): string[] | false | undefined {
+  if (!hasKey(step, field)) {
+    return undefined;
+  }
+  const value = step[field];
+  if (value === false) {
+    return false;
+  }
+  if (Array.isArray(value) && value.every((item: unknown) => 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: ConfigObject, index: number): string | false | undefined {
+  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: ConfigObject, index: number): "inline" | "file-only" | undefined {
+  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: ConfigObject, index: number): boolean | undefined {
+  if (!hasKey(step, "progress")) {
+    return undefined;
+  }
+  return typeof step.progress === "boolean"
+    ? step.progress
+    : stepError(index, "progress", "a boolean");
+}
+function stepSchema(step: ConfigObject, index: number): string | undefined {
+  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: unknown, index: number): ChainStepConfig {
+  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: unknown): ConfigParse<ChainStepConfig[]> {
+  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: unknown, index) => parseStep(item, index)) };
+  } catch (caught) {
+    if (caught instanceof ConfigValidationError) {
+      return { error: caught.message };
+    }
+    throw caught;
+  }
+}

package/src/agents/management-format.ts

@@ -0,0 +1,243 @@
+import type { AgentConfig, ChainConfig, ChainStepConfig } from "../shared/types/config.ts";
+import { resolveEffectiveThinking } from "../shared/model-info.ts";
+import { frontmatterNameForConfig } from "./identity.ts";
+import { isConfigObject } from "./config-values.ts";
+
+export function formatModelDefaults(agent: AgentConfig): string[] {
+  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: string, value: string | undefined): string[] {
+  return value !== undefined && value.length > 0 ? [`${label}: ${value}`] : [];
+}
+function listLine(label: string, value: readonly string[] | undefined): string[] {
+  return value !== undefined && value.length > 0 ? [`${label}: ${value.join(", ")}`] : [];
+}
+function packageLines(config: AgentConfig | ChainConfig): string[] {
+  return config.packageName !== undefined && config.packageName.length > 0
+    ? [`Local name: ${frontmatterNameForConfig(config)}`, `Package: ${config.packageName}`]
+    : [];
+}
+function executionLines(agent: AgentConfig): string[] {
+  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: AgentConfig): string {
+  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: unknown): boolean {
+  return Boolean(value);
+}
+
+function displayUnknown(value: unknown): string {
+  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: unknown) => (item === null || item === undefined ? "" : displayUnknown(item)))
+      .join(",");
+  }
+  return Object.prototype.toString.call(value);
+}
+function dynamicExpansionLines(value: unknown): string[] {
+  if (!isConfigObject(value)) {
+    return [];
+  }
+  const lines: string[] = [];
+  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: unknown): string[] {
+  if (!isConfigObject(value)) {
+    return [];
+  }
+  const lines: string[] = [];
+  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: ChainStepConfig, index: number): string[] {
+  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: string, value: readonly string[] | false | undefined): string[] {
+  return value === false ? [`   ${label}: false`] : listLine(`   ${label}`, value);
+}
+function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
+  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: ChainConfig): string {
+  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.",
+};
+type AgentListRole = keyof typeof AGENT_ROLE_HINTS;
+function agentListRole(agent: AgentConfig): AgentListRole {
+  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: AgentConfig): string {
+  return `- ${agent.name} (${agent.source}${agent.defaultContext === undefined ? "" : `, context: ${agent.defaultContext}`}): ${agent.description}\n  ${formatModelDefaults(agent).join("; ")}`;
+}
+export function formatAgentGroups(agents: readonly AgentConfig[]): string[] {
+  const lines = ["Executable agents (grouped by role):"];
+  if (agents.length === 0) {
+    return [...lines, "- (none)"];
+  }
+  const roles: AgentListRole[] = [
+    "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;
+}