@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/src/agents/agent-defaults.ts

@@ -1,13 +0,0 @@
-import type { SystemPromptMode } from "../shared/types/config.ts";
-
-export function defaultSystemPromptMode(_name: string): SystemPromptMode {
-  return "append";
-}
-
-export function defaultInheritProjectContext(_name: string): boolean {
-  return true;
-}
-
-export function defaultInheritSkills(): boolean {
-  return true;
-}

package/src/agents/agent-definition.ts

@@ -1,253 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { AgentConfig, AgentSource } from "../shared/types/config.ts";
-import { KNOWN_FIELDS } from "./agent-serializer.ts";
-import { parseFrontmatter } from "./frontmatter.ts";
-import { buildRuntimeName, parsePackageName } from "./identity.ts";
-import {
-  listFilesRecursive,
-  pathIsInside,
-  type AgentDiscoveryDiagnostic,
-} from "./discovery-paths.ts";
-import { csvItems, splitToolList, errorMessage } from "./config-values.ts";
-import {
-  defaultSystemPromptMode,
-  defaultInheritProjectContext,
-  defaultInheritSkills,
-} from "./agent-defaults.ts";
-
-type Frontmatter = Readonly<Partial<Record<string, string>>>;
-const reportedDiagnostics = new Map<string, { filePath: string; error: string }>();
-const loggedDiagnostics = new Set<string>();
-const MAX_DIAGNOSTICS = 1_000;
-
-function reportDiagnostic(filePath: string, message: string): void {
-  const key = `${filePath}\0${message}`;
-  if (!reportedDiagnostics.has(key) && reportedDiagnostics.size >= MAX_DIAGNOSTICS) {
-    const oldest = reportedDiagnostics.keys().next().value;
-    if (oldest !== undefined) {
-      reportedDiagnostics.delete(oldest);
-    }
-  }
-  reportedDiagnostics.set(key, { filePath, error: message });
-  if (loggedDiagnostics.has(key)) {
-    return;
-  }
-  if (loggedDiagnostics.size >= MAX_DIAGNOSTICS) {
-    const oldest = loggedDiagnostics.values().next().value;
-    if (oldest !== undefined) {
-      loggedDiagnostics.delete(oldest);
-    }
-  }
-  loggedDiagnostics.add(key);
-  console.error(`Invalid agent definition '${filePath}: ${message}'`);
-}
-
-export function clearAgentDiagnosticsForDirs(dirs: readonly string[]): void {
-  for (const [key, entry] of reportedDiagnostics) {
-    if (dirs.some((dir) => pathIsInside(dir, entry.filePath))) {
-      reportedDiagnostics.delete(key);
-    }
-  }
-}
-
-export function agentDiagnosticsForDir(
-  dir: string,
-  source: AgentDiscoveryDiagnostic["source"],
-): AgentDiscoveryDiagnostic[] {
-  return [...reportedDiagnostics.values()]
-    .filter((entry) => pathIsInside(dir, entry.filePath))
-    .map((entry) => ({ filePath: entry.filePath, error: entry.error, source }));
-}
-
-function validateDefinition(frontmatter: Frontmatter): string | undefined {
-  const booleans = [
-    "allowSubagents",
-    "inheritProjectContext",
-    "inheritSkills",
-    "defaultProgress",
-    "interactive",
-    "completionGuard",
-  ];
-  const invalid = booleans.find(
-    (field) =>
-      frontmatter[field] !== undefined &&
-      frontmatter[field] !== "true" &&
-      frontmatter[field] !== "false",
-  );
-  if (invalid !== undefined) {
-    return `${invalid} must be true or false`;
-  }
-  if (
-    frontmatter.systemPromptMode !== undefined &&
-    frontmatter.systemPromptMode !== "append" &&
-    frontmatter.systemPromptMode !== "replace"
-  ) {
-    return "systemPromptMode must be append or replace";
-  }
-  if (
-    frontmatter.defaultContext !== undefined &&
-    frontmatter.defaultContext !== "fresh" &&
-    frontmatter.defaultContext !== "fork"
-  ) {
-    return "defaultContext must be fresh or fork";
-  }
-  return validateLimits(frontmatter);
-}
-
-function validateLimits(frontmatter: Frontmatter): string | undefined {
-  for (const [field, minimum] of [
-    ["maxSubagentDepth", 0],
-    ["maxExecutionTimeMs", 1],
-    ["maxTokens", 1],
-  ] as const) {
-    if (
-      frontmatter[field] !== undefined &&
-      (!Number.isInteger(Number(frontmatter[field])) || Number(frontmatter[field]) < minimum)
-    ) {
-      return `${field} must be an integer >= ${minimum}`;
-    }
-  }
-  return undefined;
-}
-
-function optionalList(value: string | undefined): string[] | undefined {
-  const items = value === undefined ? [] : csvItems(value);
-  return items.length > 0 ? items : undefined;
-}
-
-function optionalBoolean(value: string | undefined): boolean | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  return value === "true";
-}
-
-function contextFields(
-  frontmatter: Frontmatter,
-  name: string,
-): Pick<
-  AgentConfig,
-  | "systemPromptMode"
-  | "inheritProjectContext"
-  | "inheritSkills"
-  | "defaultContext"
-  | "completionGuard"
-> {
-  const defaultContext = frontmatter.defaultContext;
-  const systemPromptMode = frontmatter.systemPromptMode;
-  return {
-    systemPromptMode:
-      systemPromptMode === "append" || systemPromptMode === "replace"
-        ? systemPromptMode
-        : defaultSystemPromptMode(name),
-    inheritProjectContext:
-      optionalBoolean(frontmatter.inheritProjectContext) ?? defaultInheritProjectContext(name),
-    inheritSkills: optionalBoolean(frontmatter.inheritSkills) ?? defaultInheritSkills(),
-    defaultContext:
-      defaultContext === "fresh" || defaultContext === "fork" ? defaultContext : undefined,
-    completionGuard: optionalBoolean(frontmatter.completionGuard),
-  };
-}
-
-function extraFields(frontmatter: Frontmatter): Record<string, string> | undefined {
-  const fields: Record<string, string> = {};
-  for (const [key, value] of Object.entries(frontmatter)) {
-    if (!KNOWN_FIELDS.has(key) && value !== undefined) {
-      fields[key] = value;
-    }
-  }
-  return Object.keys(fields).length > 0 ? fields : undefined;
-}
-
-function definitionFields(frontmatter: Frontmatter): Partial<AgentConfig> {
-  return {
-    ...splitToolList(optionalList(frontmatter.tools)),
-    allowSubagents: frontmatter.allowSubagents === "true",
-    model: frontmatter.model,
-    fallbackModels: optionalList(frontmatter.fallbackModels),
-    thinking: frontmatter.thinking,
-    skills: optionalList(
-      frontmatter.skill === undefined || frontmatter.skill.length === 0
-        ? frontmatter.skills
-        : frontmatter.skill,
-    ),
-    extensions: frontmatter.extensions === undefined ? undefined : csvItems(frontmatter.extensions),
-    output: frontmatter.output,
-    defaultReads: optionalList(frontmatter.defaultReads),
-    defaultProgress: frontmatter.defaultProgress === "true",
-    interactive: frontmatter.interactive === "true",
-    maxSubagentDepth:
-      frontmatter.maxSubagentDepth === undefined ? 0 : Number(frontmatter.maxSubagentDepth),
-    maxExecutionTimeMs:
-      frontmatter.maxExecutionTimeMs === undefined
-        ? undefined
-        : Number(frontmatter.maxExecutionTimeMs),
-    maxTokens: frontmatter.maxTokens === undefined ? undefined : Number(frontmatter.maxTokens),
-    extraFields: extraFields(frontmatter),
-  };
-}
-
-function loadDefinition(filePath: string, source: AgentSource): AgentConfig | undefined {
-  let content: string;
-  try {
-    content = fs.readFileSync(filePath, "utf-8");
-  } catch (error) {
-    reportDiagnostic(filePath, `cannot read file: ${errorMessage(error)}`);
-    return undefined;
-  }
-  const { frontmatter, body } = parseFrontmatter(content);
-  if (
-    frontmatter.name === undefined ||
-    frontmatter.name.length === 0 ||
-    frontmatter.description === undefined ||
-    frontmatter.description.length === 0
-  ) {
-    reportDiagnostic(filePath, "frontmatter must include name and description");
-    return undefined;
-  }
-  const localName = frontmatter.name;
-  const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
-  if (parsedPackage.error !== undefined) {
-    reportDiagnostic(filePath, parsedPackage.error);
-    return undefined;
-  }
-  const error = validateDefinition(frontmatter);
-  if (error !== undefined) {
-    reportDiagnostic(filePath, error);
-    return undefined;
-  }
-  return {
-    ...definitionFields(frontmatter),
-    ...contextFields(frontmatter, localName),
-    name: buildRuntimeName(localName, parsedPackage.packageName),
-    localName,
-    packageName: parsedPackage.packageName,
-    description: frontmatter.description,
-    systemPrompt: body,
-    source,
-    filePath,
-  };
-}
-
-export function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
-  const files = listFilesRecursive(
-    dir,
-    (name) =>
-      name.endsWith(".md") &&
-      !name.endsWith(".chain.md") &&
-      name !== "SKILL.template.md" &&
-      name !== "AGENTS.md",
-  );
-  const agents: AgentConfig[] = [];
-  for (const filePath of files) {
-    if (path.relative(dir, filePath).split(path.sep)[0] === "skills") {
-      continue;
-    }
-    const agent = loadDefinition(filePath, source);
-    if (agent !== undefined) {
-      agents.push(agent);
-    }
-  }
-  return agents;
-}

package/src/agents/agent-management.ts

@@ -1,120 +0,0 @@
-import { discoverAgentsAll } from "./agents.ts";
-import { mergeAgents } from "./agent-selection.ts";
-import { formatAgentGroups, formatAgentDetail, formatChainDetail } from "./management-format.ts";
-import { handleCreate, handleUpdate, handleDelete } from "./management-persistence.ts";
-import {
-  result,
-  normalizeListScope,
-  discoveryOptions,
-  findEffectiveAgents,
-  findChains,
-  availableNamesText,
-  type ManagementContext,
-  type ManagementParams,
-} from "./management-targets.ts";
-import type { AgentScope } from "../shared/types/config.ts";
-import type { SubagentExecutionResult } from "../shared/types.ts";
-export { handleCreate, handleUpdate } from "./management-persistence.ts";
-
-export function handleList(
-  params: ManagementParams,
-  ctx: ManagementContext,
-): SubagentExecutionResult {
-  const scope = normalizeListScope(params.agentScope);
-  if (scope === undefined) {
-    return result("agentScope must be 'user', 'project', or 'both'.", true);
-  }
-  const discovery = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
-  const agents = mergeAgents(discovery.user, discovery.project, [
-    ...discovery.builtin,
-    ...discovery.package,
-  ])
-    .filter((agent) => agent.disabled !== true)
-    .sort((a, b) => a.name.localeCompare(b.name));
-  const chains = discovery.chains
-    .filter((chain) => scope === "both" || chain.source === scope)
-    .sort((a, b) => a.name.localeCompare(b.name));
-  const diagnostics = [...discovery.agentDiagnostics, ...discovery.chainDiagnostics];
-  return result(
-    [
-      ...formatAgentGroups(agents),
-      "",
-      "Chains:",
-      ...(chains.length > 0
-        ? chains.map((chain) => `- ${chain.name} (${chain.source}): ${chain.description}`)
-        : ["- (none)"]),
-      ...(diagnostics.length > 0
-        ? [
-            "",
-            "Discovery diagnostics:",
-            ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`),
-          ]
-        : []),
-    ].join("\n"),
-  );
-}
-function getBlocks(
-  kind: "agent" | "chain",
-  name: string,
-  ctx: ManagementContext,
-  scope: AgentScope,
-): { found: boolean; blocks: string[] } {
-  const matches =
-    kind === "agent" ? findEffectiveAgents(name, ctx, scope) : findChains(name, ctx, scope);
-  if (matches.length === 0) {
-    return {
-      found: false,
-      blocks: [
-        `${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${availableNamesText(ctx, kind, scope)}.`,
-      ],
-    };
-  }
-  return {
-    found: true,
-    blocks: matches.map((match) =>
-      "steps" in match ? formatChainDetail(match) : formatAgentDetail(match),
-    ),
-  };
-}
-function handleGet(params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-  const agent = params.agent ?? "";
-  const chain = params.chainName ?? "";
-  if (agent.length === 0 && chain.length === 0) {
-    return result("Specify 'agent' or 'chainName' for get.", true);
-  }
-  const scope = normalizeListScope(params.agentScope);
-  if (scope === undefined) {
-    return result("agentScope must be 'user', 'project', or 'both'.", true);
-  }
-  const blocks = [
-    ...(agent.length > 0 ? [getBlocks("agent", agent, ctx, scope)] : []),
-    ...(chain.length > 0 ? [getBlocks("chain", chain, ctx, scope)] : []),
-  ];
-  return result(
-    blocks.flatMap((block) => block.blocks).join("\n\n"),
-    !blocks.some((block) => block.found),
-  );
-}
-export function handleManagementAction(
-  action: string,
-  params: ManagementParams,
-  ctx: ManagementContext,
-): SubagentExecutionResult {
-  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);
-  }
-}

package/src/agents/agent-scope.ts

@@ -1,11 +0,0 @@
-import type { AgentScope } from "./agents.ts";
-
-export function resolveExecutionAgentScope(scope: unknown): AgentScope {
-  if (scope === undefined) {
-    return "both";
-  }
-  if (scope === "user" || scope === "project" || scope === "both") {
-    return scope;
-  }
-  throw new Error("agentScope must be 'user', 'project', or 'both'.");
-}

package/src/agents/agent-selection.ts

@@ -1,22 +0,0 @@
-import type { AgentConfig } from "../shared/types/config.ts";
-
-export function mergeAgents(
-  userAgents: readonly AgentConfig[],
-  projectAgents: readonly AgentConfig[],
-  builtinAgents: readonly AgentConfig[],
-): AgentConfig[] {
-  const agentMap = new Map<string, AgentConfig>();
-
-  for (const agent of builtinAgents) {
-    agentMap.set(agent.name, agent);
-  }
-
-  for (const agent of userAgents) {
-    agentMap.set(agent.name, agent);
-  }
-  for (const agent of projectAgents) {
-    agentMap.set(agent.name, agent);
-  }
-
-  return Array.from(agentMap.values());
-}

package/src/agents/agent-serializer.ts

@@ -1,90 +0,0 @@
-import type { AgentConfig } from "../shared/types/config.ts";
-import { frontmatterNameForConfig } from "./identity.ts";
-
-export const KNOWN_FIELDS: ReadonlySet<string> = new Set([
-  "name",
-  "package",
-  "description",
-  "tools",
-  "allowSubagents",
-  "model",
-  "fallbackModels",
-  "thinking",
-  "systemPromptMode",
-  "inheritProjectContext",
-  "inheritSkills",
-  "defaultContext",
-  "skill",
-  "skills",
-  "extensions",
-  "output",
-  "defaultReads",
-  "defaultProgress",
-  "interactive",
-  "maxSubagentDepth",
-  "maxExecutionTimeMs",
-  "maxTokens",
-  "completionGuard",
-]);
-function stringLine(field: string, value: string | undefined): string[] {
-  return value !== undefined && value.length > 0 ? [`${field}: ${value}`] : [];
-}
-function listLine(field: string, values: readonly string[] | undefined): string[] {
-  return values !== undefined && values.length > 0 ? [`${field}: ${values.join(", ")}`] : [];
-}
-function limitLine(field: string, value: number | undefined, minimum: number): string[] {
-  return value !== undefined && Number.isInteger(value) && value >= minimum
-    ? [`${field}: ${value}`]
-    : [];
-}
-function identityLines(config: AgentConfig): string[] {
-  return [
-    `name: ${frontmatterNameForConfig(config)}`,
-    ...stringLine("package", config.packageName),
-    `description: ${config.description}`,
-  ];
-}
-function modelAndContextLines(config: AgentConfig): string[] {
-  return [
-    ...stringLine("model", config.model),
-    ...listLine("fallbackModels", config.fallbackModels),
-    ...stringLine("thinking", config.thinking === "off" ? undefined : config.thinking),
-    `systemPromptMode: ${config.systemPromptMode}`,
-    `inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`,
-    `inheritSkills: ${config.inheritSkills ? "true" : "false"}`,
-    ...stringLine("defaultContext", config.defaultContext),
-  ];
-}
-function resourceLines(config: AgentConfig): string[] {
-  return [
-    ...listLine("skills", config.skills),
-    ...(config.extensions === undefined ? [] : [`extensions: ${config.extensions.join(", ")}`]),
-    ...stringLine("output", config.output),
-    ...listLine("defaultReads", config.defaultReads),
-    ...(config.defaultProgress === true ? ["defaultProgress: true"] : []),
-    ...(config.interactive === true ? ["interactive: true"] : []),
-    ...limitLine("maxSubagentDepth", config.maxSubagentDepth, 0),
-    ...limitLine("maxExecutionTimeMs", config.maxExecutionTimeMs, 1),
-    ...limitLine("maxTokens", config.maxTokens, 1),
-    ...(config.completionGuard === undefined ? [] : [`completionGuard: ${config.completionGuard}`]),
-  ];
-}
-export function serializeAgent(config: AgentConfig): string {
-  const tools = [
-    ...(config.tools ?? []),
-    ...(config.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
-  ];
-  const lines = [
-    "---",
-    ...identityLines(config),
-    ...listLine("tools", tools),
-    ...(config.allowSubagents === true ? ["allowSubagents: true"] : []),
-    ...modelAndContextLines(config),
-    ...resourceLines(config),
-    ...Object.entries(config.extraFields ?? {})
-      .filter(([key]) => !KNOWN_FIELDS.has(key))
-      .map(([key, value]) => `${key}: ${value}`),
-    "---",
-  ];
-  return `${lines.join("\n")}\n\n${config.systemPrompt}\n`;
-}