pi-extensible-workflows 2.0.0 → 3.1.0

package/src/doctor.ts

@@ -14,22 +14,31 @@ import {
   DEFAULT_SETTINGS,
   loadSettings,
   resolveAgentResourcePolicy,
+  resolveWorkflowSettings,
   resolveModelReference,
+  parseThinking,
   parseRoleMarkdown,
   registeredWorkflowFunctions,
+  registeredWorkflowRoleDirectoryRegistrations,
   workflowRoleDirectories,
   workflowProjectSettingsPath,
   workflowSettingsPath,
   type AgentResourceExclusions,
   type AgentResourcePolicy,
+  type WorkflowCatalogModelAlias,
+  type WorkflowExtensionMetadata,
   type WorkflowFunction,
+  type WorkflowRoleDirectoryRegistration,
   type WorkflowSettings,
+  type WorkflowSettingsSources,
 } from "./index.js";
 import type { AgentDefinition } from "./agent-execution.js";
+import { loadingRegistry, type WorkflowRegistryApi } from "./registry.js";
+import { disabledResources, unmatchedResourcePatterns } from "./utils.js";
 
 export type DoctorSeverity = "error" | "warning";
 export interface DoctorDiagnostic { severity: DoctorSeverity; code: string; message: string; source?: string; hint?: string }
-export interface DoctorRole { name: string; path: string; scope: "global" | "project"; active: boolean; overrides?: string; overriddenBy?: string }
+export interface DoctorRole { name: string; path: string; scope: "extension" | "global" | "project"; active: boolean; overrides?: string; overriddenBy?: string; extension?: WorkflowExtensionMetadata }
 export interface DoctorFunction { name: string; description: string; valid: boolean }
 export interface DoctorTrust { required: boolean; trusted: boolean; source: string }
 export interface DoctorPiState {
@@ -47,11 +56,13 @@ export interface DoctorReport {
   agentDir: string;
   settingsPath: string;
   settings: Readonly<WorkflowSettings>;
+  settingsSources: WorkflowSettingsSources;
   trust: DoctorTrust;
   activeTools: readonly string[];
   roles: readonly DoctorRole[];
   functions: readonly DoctorFunction[];
   resourcePolicy: AgentResourcePolicy;
+  modelAliases: readonly WorkflowCatalogModelAlias[];
   diagnostics: readonly DoctorDiagnostic[];
 }
 export interface DoctorOptions {
@@ -60,6 +71,7 @@ export interface DoctorOptions {
   settingsPath?: string;
   discoverPi?: (cwd: string, agentDir: string) => Promise<DoctorPiState>;
   activeTools?: readonly string[];
+  registry?: WorkflowRegistryApi;
 }
 
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
@@ -68,7 +80,11 @@ function canonical(path: string): string {
   const absolute = resolve(path);
   try { return realpathSync(absolute); } catch { return absolute; }
 }
-
+function isDynamicModelAlias(value: string, aliases: ReadonlySet<string>): boolean {
+  const match = /^([^/\s:]+)(?::([^\s]+))?$/.exec(value);
+  const name = match?.[1];
+  return Boolean(name && (match[2] === undefined || parseThinking(match[2]) !== undefined) && aliases.has(name));
+}
 async function readCredentials(agentDir: string): Promise<InMemoryCredentialStore> {
   const credentials = new InMemoryCredentialStore();
   try {
@@ -151,7 +167,27 @@ function roleFilesFrom(dirs: readonly string[]): string[] {
   const paths = dirs.flatMap((dir) => roleFiles(dir));
   return [...new Map(paths.map((path) => [basename(path, ".md"), path])).values()].sort();
 }
-
+type ExtensionRoleFile = { name: string; path: string; directory: string; extension: WorkflowExtensionMetadata };
+type ExtensionRoleScan = { files: ExtensionRoleFile[]; empty: WorkflowRoleDirectoryRegistration[]; errors: Array<{ registration: WorkflowRoleDirectoryRegistration; error: unknown }> };
+function extensionLabel(extension: WorkflowExtensionMetadata): string { return `Extension "${extension.headline}" (${extension.version})`; }
+function scanExtensionRoleFiles(registrations: readonly WorkflowRoleDirectoryRegistration[]): ExtensionRoleScan {
+  const files: ExtensionRoleFile[] = [];
+  const empty: WorkflowRoleDirectoryRegistration[] = [];
+  const errors: Array<{ registration: WorkflowRoleDirectoryRegistration; error: unknown }> = [];
+  for (const registration of registrations) {
+    try {
+      const entries = readdirSync(registration.path, { withFileTypes: true });
+      const roleFiles = entries.filter((entry) => entry.isFile() && extname(entry.name) === ".md");
+      if (!roleFiles.length) empty.push(registration);
+      for (const entry of roleFiles) files.push({ name: basename(entry.name, ".md"), path: join(registration.path, entry.name), directory: registration.path, extension: registration.extension });
+    } catch (error) { errors.push({ registration, error }); }
+  }
+  files.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
+  return { files, empty, errors };
+}
+function roleProvenance(source?: { directory: string; extension: WorkflowExtensionMetadata }): string {
+  return source ? `${extensionLabel(source.extension)} role directory "${source.directory}"` : "Role";
+}
 function diagnostic(severity: DoctorSeverity, code: string, message: string, source?: string, hint?: string): DoctorDiagnostic {
   return { severity, code, message, ...(source ? { source } : {}), ...(hint ? { hint } : {}) };
 }
@@ -159,7 +195,8 @@ function emptyResourcePolicy(globalSettingsPath: string, cwd: string, projectTru
   const empty: AgentResourceExclusions = { skills: [], extensions: [] };
   return { globalSettingsPath, projectSettingsPath: workflowProjectSettingsPath(cwd), projectTrusted, global: empty, project: empty, effective: empty, unmatchedSkills: [], unmatchedExtensions: [] };
 }
-function validateModel(value: string, known: ReadonlySet<string>, available: ReadonlySet<string>, source: string, diagnostics: DoctorDiagnostic[], aliases: Readonly<Record<string, string>>, settingsPath: string): void {
+function validateModel(value: string, known: ReadonlySet<string>, available: ReadonlySet<string>, source: string, diagnostics: DoctorDiagnostic[], aliases: Readonly<Record<string, string>>, dynamicAliases: ReadonlySet<string>, settingsPath: string): void {
+  if (isDynamicModelAlias(value, dynamicAliases)) return;
   try {
     const parsed = resolveModelReference(value, aliases, known, settingsPath);
     const name = `${parsed.provider}/${parsed.model}`;
@@ -169,30 +206,29 @@ function validateModel(value: string, known: ReadonlySet<string>, available: Rea
   }
 }
 
-function inspectRole(path: string, activeTools: ReadonlySet<string>, knownModels: ReadonlySet<string>, availableModels: ReadonlySet<string>, diagnostics: DoctorDiagnostic[], aliases: Readonly<Record<string, string>>, settingsPath: string): AgentDefinition | undefined {
+function inspectRole(path: string, activeTools: ReadonlySet<string>, knownModels: ReadonlySet<string>, availableModels: ReadonlySet<string>, diagnostics: DoctorDiagnostic[], aliases: Readonly<Record<string, string>>, dynamicAliases: ReadonlySet<string>, settingsPath: string, source?: { directory: string; extension: WorkflowExtensionMetadata }): AgentDefinition | undefined {
   let definition: AgentDefinition;
   try { definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path); }
   catch (error) {
-    diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", (error as Error).message, path, "Fix the role YAML frontmatter."));
+    const message = error instanceof Error ? error.message : String(error);
+    diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", source ? `${roleProvenance(source)} contains invalid role at "${path}": ${message}` : message, path, "Fix the role YAML frontmatter."));
     return undefined;
   }
   const body = definition.prompt ?? "";
   if (body.trim() === "") diagnostics.push(diagnostic("warning", "ROLE_BODY_EMPTY", "Role body is empty", path));
   if (Buffer.byteLength(body) > 50 * 1024) diagnostics.push(diagnostic("warning", "ROLE_BODY_LARGE", "Role body exceeds 50KB", path));
   if (/{{\s*[^{}]+\s*}}/.test(body)) diagnostics.push(diagnostic("warning", "ROLE_PLACEHOLDER", "Role body contains an unsupported placeholder-looking token", path));
-  if (definition.model) validateModel(definition.model, knownModels, availableModels, path, diagnostics, aliases, settingsPath);
+  if (definition.model) validateModel(definition.model, knownModels, availableModels, path, diagnostics, aliases, dynamicAliases, settingsPath);
   for (const tool of definition.tools ?? []) if (!activeTools.has(tool)) diagnostics.push(diagnostic("error", "ROLE_TOOL_INACTIVE", `Tool is unknown or inactive: ${tool}`, path, "Use a tool listed under Active tools or enable its Pi extension."));
   return definition;
 }
 
 function matchResourcePolicy(policy: AgentResourcePolicy, pi: DoctorPiState): AgentResourcePolicy {
-  const extensions = new Set((pi.extensions ?? []).map(canonical));
-  const skills = new Set(pi.skills ?? []);
-  return { ...policy, unmatchedSkills: policy.effective.skills.filter((name) => !skills.has(name)), unmatchedExtensions: policy.effective.extensions.filter((path) => !extensions.has(canonical(path))) };
-}
-function resourcePolicySource(policy: AgentResourcePolicy, kind: keyof AgentResourceExclusions, selector: string): string {
-  return policy.project[kind].includes(selector) && !policy.global[kind].includes(selector) ? policy.projectSettingsPath : policy.globalSettingsPath;
+  const extensions = [...new Set((pi.extensions ?? []).map(canonical))];
+  const skills = [...new Set(pi.skills ?? [])];
+  return { ...policy, excludedSkills: disabledResources(policy.effective.skills, skills), excludedExtensions: disabledResources(policy.effective.extensions, extensions), unmatchedSkills: unmatchedResourcePatterns(policy.effective.skills, skills), unmatchedExtensions: unmatchedResourcePatterns(policy.effective.extensions, extensions) };
 }
+function resourcePolicySource(settingsSource: string): string { return settingsSource; }
 export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport> {
   const cwd = canonical(options.cwd ?? process.cwd());
   const agentDir = canonical(options.agentDir ?? getAgentDir());
@@ -201,6 +237,8 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
   let settings = DEFAULT_SETTINGS;
   try { settings = loadSettings(settingsPath); }
   catch (error) { diagnostics.push(diagnostic("error", "SETTINGS_INVALID", (error as Error).message, settingsPath, "Fix or remove the invalid workflow settings file.")); }
+  let settingsSources: WorkflowSettingsSources = { concurrency: settingsPath, modelAliases: settingsPath, disabledAgentResources: settingsPath };
+  const projectSettingsPath = workflowProjectSettingsPath(cwd);
 
   let pi: DoctorPiState;
   try { pi = await (options.discoverPi ?? discoverPi)(cwd, agentDir); }
@@ -211,43 +249,91 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
   if (options.activeTools) pi = { ...pi, activeTools: options.activeTools.filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_catalog") };
   if (pi.trust.required && !pi.trust.trusted) diagnostics.push(diagnostic("warning", "PROJECT_UNTRUSTED", "Pi project resources are inactive because the project is not trusted", cwd, "Open this project in Pi, choose Trust, then rerun doctor."));
   for (const error of pi.extensionErrors) diagnostics.push(diagnostic("error", "EXTENSION_LOAD", error.message, error.path, "Fix or disable the failing Pi extension."));
+  try {
+    const resolved = resolveWorkflowSettings(cwd, pi.trust.trusted, settingsPath);
+    settings = resolved.effective;
+    settingsSources = resolved.sources;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const source = message.includes(projectSettingsPath) ? projectSettingsPath : settingsPath;
+    if (!diagnostics.some(({ code, source: itemSource }) => code === "SETTINGS_INVALID" && itemSource === source)) diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, source, "Fix or remove the invalid workflow settings file."));
+  }
   let resourcePolicy: AgentResourcePolicy;
   try {
     resourcePolicy = matchResourcePolicy(resolveAgentResourcePolicy(cwd, pi.trust.trusted, settingsPath), pi);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    if (!diagnostics.some(({ code, source }) => code === "SETTINGS_INVALID" && source === settingsPath)) diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, message.includes(".json") ? message.match(/(?:settings: )?([^ )]+\.json)/)?.[1] : undefined, "Fix or remove the invalid workflow settings file."));
+    const source = message.includes(projectSettingsPath) ? projectSettingsPath : settingsPath;
+    if (!diagnostics.some(({ code, source: itemSource }) => code === "SETTINGS_INVALID" && itemSource === source)) diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, source, "Fix or remove the invalid workflow settings file."));
     resourcePolicy = emptyResourcePolicy(settingsPath, cwd, pi.trust.trusted);
   }
-  for (const skill of resourcePolicy.unmatchedSkills) diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled skill selector currently matches no discovered skill: ${skill}`, `${resourcePolicySource(resourcePolicy, "skills", skill)}.disabledAgentResources.skills`));
-  for (const extension of resourcePolicy.unmatchedExtensions) diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled extension selector currently matches no discovered extension source: ${extension}`, `${resourcePolicySource(resourcePolicy, "extensions", extension)}.disabledAgentResources.extensions`));
+  for (const skill of resourcePolicy.unmatchedSkills) diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled skill selector currently matches no discovered skill: ${skill}`, `${resourcePolicySource(settingsSources.disabledAgentResources)}.disabledAgentResources.skills`));
+  for (const extension of resourcePolicy.unmatchedExtensions) diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled extension selector currently matches no discovered extension source: ${extension}`, `${resourcePolicySource(settingsSources.disabledAgentResources)}.disabledAgentResources.extensions`));
 
   const activeTools = new Set(pi.activeTools);
   const knownModels = new Set(pi.knownModels);
   const availableModels = new Set(pi.availableModels);
   const aliases = settings.modelAliases ?? {};
+  const registry = options.registry ?? loadingRegistry();
+  const registeredModelAliases = registry.modelAliases();
+  const dynamicAliases = new Set(registeredModelAliases.map(({ name }) => name).filter((name) => !Object.prototype.hasOwnProperty.call(aliases, name)));
+  const modelAliases: WorkflowCatalogModelAlias[] = [
+    ...Object.keys(aliases).map((name) => ({ name, kind: "static" as const, provenance: settingsSources.modelAliases })),
+    ...registeredModelAliases.map(({ name, version, headline, extensionDescription }) => ({ name, kind: "dynamic" as const, provenance: `extension: ${headline}`, version, headline, extensionDescription })),
+  ].sort((left, right) => left.name.localeCompare(right.name) || left.kind.localeCompare(right.kind));
   const roles: DoctorRole[] = [];
   const definitions = new Map<string, AgentDefinition>();
+  const extensionScan = scanExtensionRoleFiles(registeredWorkflowRoleDirectoryRegistrations());
+  for (const { registration, error } of extensionScan.errors) {
+    const message = error instanceof Error ? error.message : String(error);
+    diagnostics.push(diagnostic("error", "ROLE_DIRECTORY", `${extensionLabel(registration.extension)} role directory "${registration.path}" could not be scanned: ${message}`, registration.path, "Fix or remove the registered role directory."));
+  }
+  for (const registration of extensionScan.empty) diagnostics.push(diagnostic("warning", "ROLE_DIRECTORY_EMPTY", `${extensionLabel(registration.extension)} role directory "${registration.path}" contains no .md role files`, registration.path, "Add packaged role files or remove the directory registration."));
+  const extensionFilesByName = new Map<string, ExtensionRoleFile[]>();
+  for (const file of extensionScan.files) extensionFilesByName.set(file.name, [...(extensionFilesByName.get(file.name) ?? []), file]);
+  const duplicateExtensionNames = new Set<string>();
+  for (const [name, matches] of extensionFilesByName) if (matches.length > 1) {
+    duplicateExtensionNames.add(name);
+    diagnostics.push(diagnostic("error", "ROLE_DUPLICATE", `Duplicate extension role "${name}": ${matches.map(({ path, directory, extension }) => `${extensionLabel(extension)} role directory "${directory}" (${path})`).join("; ")}`, matches[0]?.path, "Keep one extension role with this name; global and project roles may override packaged defaults."));
+  }
+  const extensionPaths = new Map<string, string>();
+  for (const file of extensionScan.files) {
+    roles.push({ name: file.name, path: file.path, scope: "extension", active: true, extension: file.extension });
+    const definition = inspectRole(file.path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, { directory: file.directory, extension: file.extension });
+    if (duplicateExtensionNames.has(file.name)) continue;
+    extensionPaths.set(file.name, file.path);
+    if (definition) definitions.set(file.name, definition);
+  }
   const globalPaths = new Map<string, string>();
   const globalRoleDirs = workflowRoleDirectories(agentDir);
   for (const path of roleFilesFrom(globalRoleDirs)) {
     const name = basename(path, ".md");
-    roles.push({ name, path, scope: "global", active: true });
+    const extensionPath = extensionPaths.get(name);
+    roles.push({ name, path, scope: "global", active: true, ...(extensionPath ? { overrides: extensionPath } : {}) });
     globalPaths.set(name, path);
-    const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
-    if (definition) definitions.set(name, definition);
+    if (extensionPath) {
+      const extension = roles.find((role) => role.path === extensionPath);
+      if (extension) { extension.active = false; extension.overriddenBy = path; }
+    }
+    const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
+    if (definition) definitions.set(name, definition); else definitions.delete(name);
   }
   for (const path of roleFilesFrom([join(cwd, ".pi", "pi-extensible-workflows", "roles")])) {
     const name = basename(path, ".md");
     const globalPath = globalPaths.get(name);
+    const extensionPath = extensionPaths.get(name);
+    const overriddenPath = globalPath ?? extensionPath;
     const active = pi.trust.trusted;
-    roles.push({ name, path, scope: "project", active, ...(active && globalPath ? { overrides: globalPath } : {}) });
+    roles.push({ name, path, scope: "project", active, ...(active && overriddenPath ? { overrides: overriddenPath } : {}) });
     if (!active) continue;
     if (globalPath) {
       const global = roles.find((role) => role.path === globalPath);
       if (global) { global.active = false; global.overriddenBy = path; }
+    } else if (extensionPath) {
+      const extension = roles.find((role) => role.path === extensionPath);
+      if (extension) { extension.active = false; extension.overriddenBy = path; }
     }
-    const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
+    const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
     if (definition) definitions.set(name, definition); else definitions.delete(name);
   }
 
@@ -259,7 +345,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
   const severityOrder: Record<DoctorSeverity, number> = { error: 0, warning: 1 };
   diagnostics.sort((left, right) => severityOrder[left.severity] - severityOrder[right.severity] || (left.source ?? "").localeCompare(right.source ?? "") || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
   roles.sort((left, right) => left.name.localeCompare(right.name) || left.scope.localeCompare(right.scope));
-  return { cwd, agentDir, settingsPath, settings, trust: pi.trust, activeTools: [...activeTools].sort(), roles, functions, resourcePolicy, diagnostics };
+  return { cwd, agentDir, settingsPath, settings, settingsSources, trust: pi.trust, activeTools: [...activeTools].sort(), roles, functions, modelAliases, resourcePolicy, diagnostics };
 }
 
 function count(report: DoctorReport, severity: DoctorSeverity): number { return report.diagnostics.filter((item) => item.severity === severity).length; }
@@ -273,7 +359,9 @@ export function formatDoctorReport(report: DoctorReport): string {
     "## Environment",
     `- CWD: \`${report.cwd}\``,
     `- Agent dir: \`${report.agentDir}\``,
-    `- Workflow settings: \`${report.settingsPath}\``,
+    `- Global workflow settings: \`${report.settingsPath}\``,
+    `- Project workflow settings: \`${report.resourcePolicy.projectSettingsPath}\` (${report.resourcePolicy.projectTrusted ? "trusted" : "ignored: project untrusted"})`,
+    `- Effective setting sources: concurrency=\`${report.settingsSources.concurrency}\`, modelAliases=\`${report.settingsSources.modelAliases}\`, disabledAgentResources=\`${report.settingsSources.disabledAgentResources}\``,
     `- Limits: concurrency=${String(report.settings.concurrency)}`,
     "",
     "## Trust/resources",
@@ -288,6 +376,8 @@ export function formatDoctorReport(report: DoctorReport): string {
     `- Project extensions: ${report.resourcePolicy.project.extensions.join(", ") || "(none)"}`,
     `- Effective skills: ${report.resourcePolicy.effective.skills.join(", ") || "(none)"}`,
     `- Effective extensions: ${report.resourcePolicy.effective.extensions.join(", ") || "(none)"}`,
+    `- Excluded skills: ${report.resourcePolicy.excludedSkills?.join(", ") || "(none)"}`,
+    `- Excluded extensions: ${report.resourcePolicy.excludedExtensions?.join(", ") || "(none)"}`,
     `- Unmatched skills: ${report.resourcePolicy.unmatchedSkills.join(", ") || "(none)"}`,
     `- Unmatched extensions: ${report.resourcePolicy.unmatchedExtensions.join(", ") || "(none)"}`,
     "",
@@ -295,7 +385,10 @@ export function formatDoctorReport(report: DoctorReport): string {
     ...(report.activeTools.length ? report.activeTools.map((tool) => `- \`${tool}\``) : ["- None resolved"]),
     "",
     "## Roles",
-    ...(report.roles.length ? report.roles.map((role) => `- \`${role.name}\` (${role.scope}, ${role.active ? "active" : role.overriddenBy ? `overridden by ${role.overriddenBy}` : "inactive: project untrusted"}) - \`${role.path}\`${role.overrides ? `; overrides \`${role.overrides}\`` : ""}`) : ["- None found"]),
+    ...(report.roles.length ? report.roles.map((role) => `- \`${role.name}\` (${role.scope}, ${role.active ? "active" : role.overriddenBy ? `overridden by ${role.overriddenBy}` : "inactive: project untrusted"}) - \`${role.path}\`${role.extension ? `; ${extensionLabel(role.extension)} role directory "${dirname(role.path)}"` : ""}${role.overrides ? `; overrides \`${role.overrides}\`` : ""}`) : ["- None found"]),
+    "",
+    "## Model aliases",
+    ...(report.modelAliases.length ? report.modelAliases.map((alias) => `- [${alias.kind}] \`${alias.name}\`${alias.kind === "static" ? ` -> ${report.settings.modelAliases?.[alias.name] ?? "(unresolved)"}` : ""} (${alias.provenance})`) : ["- None registered"]),
     "",
     "## Reusable functions",
     ...(report.functions.length ? report.functions.map((fn) => `- [${fn.valid ? "ok" : "error"}] \`${fn.name}\` - ${fn.description}`) : ["- None registered"]),