@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/agents/management-warnings.ts

@@ -0,0 +1,115 @@
+import type { AgentConfig, ChainStepConfig } from "../shared/types/config.ts";
+import { isClaudeCodeModel } from "../runs/shared/claude-code.ts";
+import { discoverAgentsAll } from "./agents.ts";
+import { discoverAvailableSkills } from "./skills.ts";
+import { allAgents, discoveryOptions, type ManagementContext } from "./management-targets.ts";
+
+export function unknownChainAgents(
+  ctx: ManagementContext,
+  steps: readonly ChainStepConfig[],
+): string[] {
+  const known = new Set(
+    allAgents(discoverAgentsAll(ctx.cwd, discoveryOptions(ctx))).map((agent) => agent.name),
+  );
+  return [
+    ...new Set(
+      steps
+        .map((step) => step.agent)
+        .filter((agent): agent is string => typeof agent === "string" && !known.has(agent)),
+    ),
+  ].sort((a, b) => a.localeCompare(b));
+}
+function modelWarning(ctx: ManagementContext, model: string | undefined): string | undefined {
+  if (model === undefined || model.length === 0 || isClaudeCodeModel(model)) {
+    return undefined;
+  }
+  const found = ctx.modelRegistry
+    .getAvailable()
+    .some((entry) => `${entry.provider}/${entry.id}` === model || entry.id === model);
+  return found ? undefined : `Warning: model '${model}' is not in the current model registry.`;
+}
+function fallbackModelsWarning(
+  ctx: ManagementContext,
+  models: readonly string[] | undefined,
+): string | undefined {
+  if (models === undefined || models.length === 0) {
+    return undefined;
+  }
+  const available = new Set(
+    ctx.modelRegistry
+      .getAvailable()
+      .flatMap((model) => [`${model.provider}/${model.id}`, model.id]),
+  );
+  const missing = models.filter((model) => !isClaudeCodeModel(model) && !available.has(model));
+  return missing.length > 0
+    ? `Warning: fallback models not in the current model registry: ${missing.join(", ")}.`
+    : undefined;
+}
+function skillsWarning(
+  ctx: ManagementContext,
+  skills: readonly string[] | undefined,
+): string | undefined {
+  if (skills === undefined || skills.length === 0) {
+    return undefined;
+  }
+  const available = new Set(
+    discoverAvailableSkills(ctx.cwd, discoveryOptions(ctx)).map((skill) => skill.name),
+  );
+  const missing = skills.filter((skill) => !available.has(skill));
+  return missing.length > 0 ? `Warning: skills not found: ${missing.join(", ")}.` : undefined;
+}
+export function agentWarnings(
+  ctx: ManagementContext,
+  agent: AgentConfig,
+  fields: Readonly<Record<string, unknown>>,
+): string[] {
+  const warnings = [
+    Object.hasOwn(fields, "model") ? modelWarning(ctx, agent.model) : undefined,
+    Object.hasOwn(fields, "fallbackModels")
+      ? fallbackModelsWarning(ctx, agent.fallbackModels)
+      : undefined,
+    Object.hasOwn(fields, "skills") ? skillsWarning(ctx, agent.skills) : undefined,
+  ];
+  return warnings.filter(
+    (warning): warning is string => warning !== undefined && warning.length > 0,
+  );
+}
+export function chainStepWarnings(
+  ctx: ManagementContext,
+  steps: readonly ChainStepConfig[],
+): string[] {
+  const warnings: string[] = [];
+  const available = new Set(
+    discoverAvailableSkills(ctx.cwd, discoveryOptions(ctx)).map((skill) => skill.name),
+  );
+  for (const [index, step] of steps.entries()) {
+    if (modelWarning(ctx, step.model) !== undefined) {
+      warnings.push(
+        `Warning: step ${index + 1} (${step.agent ?? "undefined"}): model '${step.model ?? "undefined"}' is not in the current model registry.`,
+      );
+    }
+    if (step.skills !== undefined && step.skills !== false && step.skills.length > 0) {
+      const missing = step.skills.filter((skill) => !available.has(skill));
+      if (missing.length > 0) {
+        warnings.push(
+          `Warning: step ${index + 1} (${step.agent ?? "undefined"}): skills not found: ${missing.join(", ")}.`,
+        );
+      }
+    }
+  }
+  return warnings;
+}
+export function chainWarnings(ctx: ManagementContext, steps: readonly ChainStepConfig[]): string[] {
+  const missing = unknownChainAgents(ctx, steps);
+  return [
+    ...(missing.length > 0
+      ? [`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`]
+      : []),
+    ...chainStepWarnings(ctx, steps),
+  ];
+}
+export function referencingChains(ctx: ManagementContext, name: string): string[] {
+  return discoverAgentsAll(ctx.cwd, discoveryOptions(ctx))
+    .chains.filter((chain) => chain.steps.some((step) => step.agent === name))
+    .map((chain) => `${chain.name} (${chain.source})`);
+}

package/src/agents/markdown-chain.ts

@@ -0,0 +1,237 @@
+import type { Writable } from "type-fest";
+import type { ChainConfig, ChainStepConfig } from "../shared/types/config.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
+import { csvItems } from "./config-values.ts";
+
+type StepPatch = Partial<Writable<ChainStepConfig>>;
+function outputMode(value: string, agent: string): "inline" | "file-only" {
+  if (value !== "inline" && value !== "file-only") {
+    throw new Error(`Invalid outputMode '${value}' for step '${agent}'.`);
+  }
+  return value;
+}
+function progress(value: string, agent: string): boolean {
+  if (value !== "true" && value !== "false") {
+    throw new Error(`Invalid progress '${value}' for step '${agent}'; use true or false.`);
+  }
+  return value === "true";
+}
+function outputSchema(value: string): StepPatch {
+  if (value.startsWith("{") || value.startsWith("[")) {
+    throw new Error(
+      "Inline outputSchema values are not supported in .chain.md files; use a schema file path.",
+    );
+  }
+  return value.length === 0 ? {} : { outputSchema: value };
+}
+function listValue(value: string): string[] | false {
+  if (value === "false") {
+    return false;
+  }
+  const items = csvItems(value);
+  return items.length > 0 ? items : false;
+}
+function outputValue(value: string): StepPatch {
+  if (value === "false") {
+    return { output: false };
+  }
+  return value.length > 0 ? { output: value } : {};
+}
+function metadata(key: string, value: string, agent: string): StepPatch | null {
+  switch (key) {
+    case "output":
+      return outputValue(value);
+    case "phase":
+      return value.length > 0 ? { phase: value } : {};
+    case "label":
+      return value.length > 0 ? { label: value } : {};
+    case "as":
+      return value.length > 0 ? { as: value } : {};
+    case "model":
+      return value.length > 0 ? { model: value } : {};
+    case "outputschema":
+      return outputSchema(value);
+    case "outputmode":
+      return { outputMode: outputMode(value, agent) };
+    case "reads":
+      return { reads: listValue(value) };
+    case "skills":
+      return { skills: listValue(value) };
+    case "progress":
+      return { progress: progress(value, agent) };
+    default:
+      return null;
+  }
+}
+function encodedTask(raw: string, agent: string, previous: string | undefined): string {
+  if (previous !== undefined) {
+    throw new Error(`Duplicate task-json for step '${agent}'.`);
+  }
+  const value: unknown = JSON.parse(raw);
+  if (typeof value !== "string") {
+    throw new Error(`task-json for step '${agent}' must be a JSON string.`);
+  }
+  return value;
+}
+function parseStepHeaderLines(
+  lines: readonly string[],
+  agent: string,
+): { patch: StepPatch; leading: string[]; taskJson?: string } {
+  const leading: string[] = [];
+  const patch: StepPatch = {};
+  let taskJson: string | undefined;
+  for (const line of lines) {
+    const match = line.match(/^([\w-]+):\s*(.*)$/);
+    if (match === null) {
+      leading.push(line);
+      continue;
+    }
+    const key = (match.at(1) ?? "").trim().toLowerCase();
+    const value = (match.at(2) ?? "").trim();
+    if (key === "task-json") {
+      taskJson = encodedTask(value, agent, taskJson);
+      continue;
+    }
+    const field = metadata(key, value, agent);
+    if (field === null) {
+      leading.push(line);
+    } else {
+      Object.assign(patch, field);
+    }
+  }
+  return { patch, leading, taskJson };
+}
+function parseStepBody(agent: string, body: string): ChainStepConfig {
+  const lines = body.split("\n");
+  const blankIndex = lines.findIndex((line) => line.trim() === "");
+  const configLines = blankIndex === -1 ? lines : lines.slice(0, blankIndex);
+  const proseLines = blankIndex === -1 ? [] : lines.slice(blankIndex + 1);
+  const { patch, leading, taskJson } = parseStepHeaderLines(configLines, agent);
+  const prose = [...leading, ...proseLines].join("\n").trim();
+  if (taskJson !== undefined && prose.length > 0) {
+    throw new Error(`Step '${agent}' cannot combine task-json with task prose.`);
+  }
+  return { agent, ...patch, task: taskJson ?? prose };
+}
+function markdownSteps(body: string): ChainStepConfig[] {
+  const matches = [...body.matchAll(/^##\s+(.+)[^\S\n]*$/gm)];
+  return matches.map((match, index) => {
+    const agent = (match.at(1) ?? "").trim();
+    const end = match.index + match[0].length;
+    const start = end + (body[end] === "\n" ? 1 : 0);
+    return parseStepBody(
+      agent,
+      body.slice(start, matches.at(index + 1)?.index ?? body.length).trimEnd(),
+    );
+  });
+}
+function chainExtraFields(
+  frontmatter: Readonly<Partial<Record<string, string>>>,
+): Record<string, string> | undefined {
+  const extraFields: Record<string, string> = {};
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (key !== "name" && key !== "package" && key !== "description" && value !== undefined) {
+      extraFields[key] = value;
+    }
+  }
+  return Object.keys(extraFields).length > 0 ? extraFields : undefined;
+}
+
+export function parseChain(
+  content: string,
+  source: "user" | "project",
+  filePath: string,
+): ChainConfig {
+  const { frontmatter, body } = parseFrontmatter(content);
+  const name = frontmatter.name;
+  const description = frontmatter.description;
+  if (
+    name === undefined ||
+    name.length === 0 ||
+    description === undefined ||
+    description.length === 0
+  ) {
+    throw new Error("Chain frontmatter must include name and description");
+  }
+  const steps = markdownSteps(body);
+  if (steps.length === 0) {
+    throw new Error("Chain must include at least one ## agent step.");
+  }
+  const parsedPackage = parsePackageName(frontmatter.package, `Chain '${name}' package`);
+  if (parsedPackage.error !== undefined) {
+    throw new Error(parsedPackage.error);
+  }
+  return {
+    name: buildRuntimeName(name, parsedPackage.packageName),
+    localName: name,
+    packageName: parsedPackage.packageName,
+    description,
+    source,
+    filePath,
+    steps,
+    extraFields: chainExtraFields(frontmatter),
+  };
+}
+function stringLine(field: string, value: string | undefined): string[] {
+  return value !== undefined && value.length > 0 ? [`${field}: ${value}`] : [];
+}
+function listLine(field: string, value: readonly string[] | false | undefined): string[] {
+  if (value === false) {
+    return [`${field}: false`];
+  }
+  return value !== undefined && value.length > 0 ? [`${field}: ${value.join(", ")}`] : [];
+}
+function stepOutputLines(step: ChainStepConfig): string[] {
+  return [
+    ...(step.output === false ? ["output: false"] : stringLine("output", step.output)),
+    ...stringLine("phase", step.phase),
+    ...stringLine("label", step.label),
+    ...stringLine("as", step.as),
+    ...(step.outputSchema === undefined
+      ? []
+      : stringLine(
+          "outputSchema",
+          typeof step.outputSchema === "string"
+            ? step.outputSchema
+            : Object.prototype.toString.call(step.outputSchema),
+        )),
+    ...stringLine("outputMode", step.outputMode),
+    ...listLine("reads", step.reads),
+    ...stringLine("model", step.model),
+    ...listLine("skills", step.skills),
+    ...(step.progress === undefined ? [] : [`progress: ${step.progress ? "true" : "false"}`]),
+  ];
+}
+function taskLines(task: string): string[] {
+  if (!/^##\s+/m.test(task)) {
+    return ["", task];
+  }
+  // Preserve separators verbatim inside encoded prose, not as Markdown headers.
+  const encoded = JSON.stringify(task)
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  return [`task-json: ${encoded}`];
+}
+export function serializeChain(config: ChainConfig): string {
+  const lines = [
+    "---",
+    `name: ${frontmatterNameForConfig(config)}`,
+    ...stringLine("package", config.packageName),
+    `description: ${config.description}`,
+    ...Object.entries(config.extraFields ?? {}).map(([key, value]) => `${key}: ${value}`),
+    "---",
+    "",
+  ];
+  for (const [index, step] of config.steps.entries()) {
+    lines.push(
+      `## ${step.agent ?? "undefined"}`,
+      ...stepOutputLines(step),
+      ...taskLines(step.task ?? ""),
+    );
+    if (index < config.steps.length - 1) {
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/agents/package-agents.ts

@@ -0,0 +1,231 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { AgentConfig, AgentScope } from "../shared/types/config.ts";
+import { getAgentDir } from "../shared/agent-dir.ts";
+import { readSettingsFileStrict, isConfigObject } from "./config-values.ts";
+import {
+  findNearestProjectRoot,
+  pathIsInside,
+  isDirectory,
+  type DiscoveryOptions,
+} from "./discovery-paths.ts";
+import { clearAgentDiagnosticsForDirs, loadAgentsFromDir } from "./agent-definition.ts";
+
+type ConfiguredPackage = ReturnType<DefaultPackageManager["listConfiguredPackages"]>[number];
+type PackageInput = Readonly<ConfiguredPackage>;
+interface PackageIdentity {
+  user?: PackageInput;
+  project?: PackageInput;
+}
+
+let lastPackageManager:
+  | { key: string; manager: DefaultPackageManager; settingsManager: SettingsManager }
+  | undefined;
+
+function packageManagerFor(
+  cwd: string,
+  scope: AgentScope,
+  options: DiscoveryOptions,
+): {
+  manager: DefaultPackageManager;
+  settingsManager: SettingsManager;
+  projectRoot: string;
+  agentDir: string;
+} {
+  const projectRoot = findNearestProjectRoot(cwd) ?? cwd;
+  const agentDir = getAgentDir();
+  const projectTrusted = options.projectTrusted !== false;
+  const settings = {
+    global:
+      scope === "project"
+        ? undefined
+        : JSON.stringify(readSettingsFileStrict(path.join(agentDir, "settings.json"))),
+    project:
+      scope === "user" || !projectTrusted
+        ? undefined
+        : JSON.stringify(readSettingsFileStrict(path.join(projectRoot, ".pi", "settings.json"))),
+  };
+  const key = JSON.stringify([agentDir, projectRoot, scope, projectTrusted, settings]);
+  if (lastPackageManager?.key !== key) {
+    const settingsManager = SettingsManager.fromStorage(
+      {
+        withLock(settingsScope, read) {
+          read(settings[settingsScope]);
+        },
+      },
+      { projectTrusted },
+    );
+    const error = settingsManager.drainErrors().at(0);
+    if (error !== undefined) {
+      throw error.error;
+    }
+    lastPackageManager = {
+      key,
+      manager: new DefaultPackageManager({ cwd: projectRoot, agentDir, settingsManager }),
+      settingsManager,
+    };
+  }
+  return { ...lastPackageManager, projectRoot, agentDir };
+}
+
+interface PackageContext {
+  readonly scope: AgentScope;
+  readonly agentDir: string;
+  readonly projectRoot: string;
+}
+function isRemotePackage(source: string): boolean {
+  return source.startsWith("npm:") || /^(?:git:|https?:\/\/|ssh:\/\/)/.test(source.trim());
+}
+function packageKind(
+  configured: PackageInput,
+  userRoot: string | undefined,
+  context: PackageContext,
+): "npm" | "git" | "local" {
+  if (configured.source.startsWith("npm:")) {
+    return "npm";
+  }
+  if (!/^(?:git:|https?:\/\/|ssh:\/\/)/.test(configured.source.trim())) {
+    return "local";
+  }
+  const gitBase =
+    configured.scope === "user"
+      ? path.join(context.agentDir, "git")
+      : path.join(context.projectRoot, ".pi", "git");
+  const managed =
+    (configured.installedPath !== undefined && pathIsInside(gitBase, configured.installedPath)) ||
+    (userRoot !== undefined && pathIsInside(path.join(context.agentDir, "git"), userRoot));
+  return managed ? "git" : "local";
+}
+function packageIdentity(
+  configured: PackageInput,
+  manager: DefaultPackageManager,
+  context: PackageContext,
+): string | undefined {
+  const userRoot =
+    context.scope === "both" && configured.scope === "project" && isRemotePackage(configured.source)
+      ? manager.getInstalledPath(configured.source, "user")
+      : undefined;
+  const kind = packageKind(configured, userRoot, context);
+  // Pi's remote identities ignore refs; unparseable Git-like strings remain local paths.
+  const root = kind === "local" ? configured.installedPath : (userRoot ?? configured.installedPath);
+  return root === undefined || root.length === 0 ? undefined : `${kind}:${fs.realpathSync(root)}`;
+}
+
+function effectivePackage(
+  identity: Readonly<PackageIdentity>,
+  settingsManager: SettingsManager,
+): PackageInput | undefined {
+  const { user, project } = identity;
+  const declaration = settingsManager
+    .getProjectSettings()
+    .packages?.findLast((pkg) => (typeof pkg === "string" ? pkg : pkg.source) === project?.source);
+  const delta = typeof declaration === "object" && declaration.autoload === false;
+  return delta && user !== undefined ? user : (project ?? user);
+}
+function selectedPackages(
+  manager: DefaultPackageManager,
+  settingsManager: SettingsManager,
+  context: PackageContext,
+): PackageInput[] {
+  const configuredPackages = manager.listConfiguredPackages();
+  const identities = new Map<string, PackageIdentity>();
+  for (const configured of configuredPackages) {
+    const identity = packageIdentity(configured, manager, context);
+    if (identity === undefined) {
+      continue;
+    }
+    const entries = identities.get(identity) ?? {};
+    if (configured.scope === "project") {
+      entries.project = configured;
+    } else {
+      entries.user ??= configured;
+    }
+    identities.set(identity, entries);
+  }
+  const selected = new Set<PackageInput>();
+  for (const identity of identities.values()) {
+    const entry = effectivePackage(identity, settingsManager);
+    if (entry !== undefined) {
+      selected.add(entry);
+    }
+  }
+  return configuredPackages.filter((entry) => selected.has(entry));
+}
+
+function manifestAgentDirs(root: string): string[] {
+  const subagents = readSettingsFileStrict(path.join(root, "package.json")).subagents;
+  if (subagents === undefined) {
+    return [];
+  }
+  if (!isConfigObject(subagents) || !Array.isArray(subagents.agents)) {
+    throw new Error(`Package '${root}' subagents.agents must be an array of relative directories.`);
+  }
+  const realRoot = fs.realpathSync(root);
+  return subagents.agents.map((entry: unknown) => {
+    if (
+      typeof entry !== "string" ||
+      entry.length === 0 ||
+      path.isAbsolute(entry) ||
+      entry.split(/[\\/]/).includes("..")
+    ) {
+      throw new Error(
+        `Package '${root}' subagents.agents must contain relative directories inside the package.`,
+      );
+    }
+    const dir = path.resolve(root, entry);
+    const realDir = isDirectory(dir) ? fs.realpathSync(dir) : undefined;
+    if (realDir === undefined || !pathIsInside(realRoot, realDir)) {
+      throw new Error(
+        `Package '${root}' subagents.agents directory is missing or outside the package: ${entry}`,
+      );
+    }
+    return dir;
+  });
+}
+
+function eligiblePackageRoot(
+  configured: PackageInput,
+  scope: AgentScope,
+  options: DiscoveryOptions,
+): string | undefined {
+  if (
+    (scope !== "both" && configured.scope !== scope) ||
+    (configured.scope === "project" && options.projectTrusted === false)
+  ) {
+    return undefined;
+  }
+  const root = configured.installedPath;
+  return root !== undefined && root.length > 0 && fs.existsSync(path.join(root, "package.json"))
+    ? root
+    : undefined;
+}
+export function loadConfiguredPackageAgents(
+  cwd: string,
+  scope: AgentScope,
+  options: DiscoveryOptions,
+): { dirs: string[]; agents: AgentConfig[] } {
+  const { manager, settingsManager, agentDir, projectRoot } = packageManagerFor(
+    cwd,
+    scope,
+    options,
+  );
+  const selected = selectedPackages(manager, settingsManager, { scope, agentDir, projectRoot });
+  const dirs: string[] = [];
+  const seenDirs = new Set<string>();
+  for (const configured of selected) {
+    const root = eligiblePackageRoot(configured, scope, options);
+    if (root === undefined) {
+      continue;
+    }
+    for (const dir of manifestAgentDirs(root)) {
+      const realDir = fs.realpathSync(dir);
+      if (!seenDirs.has(realDir)) {
+        dirs.push(dir);
+      }
+      seenDirs.add(realDir);
+    }
+  }
+  clearAgentDiagnosticsForDirs(dirs);
+  return { dirs, agents: dirs.flatMap((dir) => loadAgentsFromDir(dir, "package")) };
+}