pi-extensible-workflows 2.0.0 → 3.1.0

package/dist/src/doctor.js

@@ -2,7 +2,9 @@ import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { ModelRuntime, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_SETTINGS, loadSettings, resolveAgentResourcePolicy, resolveModelReference, parseRoleMarkdown, registeredWorkflowFunctions, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "./index.js";
+import { DEFAULT_SETTINGS, loadSettings, resolveAgentResourcePolicy, resolveWorkflowSettings, resolveModelReference, parseThinking, parseRoleMarkdown, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "./index.js";
+import { loadingRegistry } from "./registry.js";
+import { disabledResources, unmatchedResourcePatterns } from "./utils.js";
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
 function canonical(path) {
     const absolute = resolve(path);
@@ -13,6 +15,11 @@ function canonical(path) {
         return absolute;
     }
 }
+function isDynamicModelAlias(value, aliases) {
+    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) {
     const credentials = new InMemoryCredentialStore();
     try {
@@ -112,6 +119,30 @@ function roleFilesFrom(dirs) {
     const paths = dirs.flatMap((dir) => roleFiles(dir));
     return [...new Map(paths.map((path) => [basename(path, ".md"), path])).values()].sort();
 }
+function extensionLabel(extension) { return `Extension "${extension.headline}" (${extension.version})`; }
+function scanExtensionRoleFiles(registrations) {
+    const files = [];
+    const empty = [];
+    const errors = [];
+    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) {
+    return source ? `${extensionLabel(source.extension)} role directory "${source.directory}"` : "Role";
+}
 function diagnostic(severity, code, message, source, hint) {
     return { severity, code, message, ...(source ? { source } : {}), ...(hint ? { hint } : {}) };
 }
@@ -119,7 +150,9 @@ function emptyResourcePolicy(globalSettingsPath, cwd, projectTrusted) {
     const empty = { skills: [], extensions: [] };
     return { globalSettingsPath, projectSettingsPath: workflowProjectSettingsPath(cwd), projectTrusted, global: empty, project: empty, effective: empty, unmatchedSkills: [], unmatchedExtensions: [] };
 }
-function validateModel(value, known, available, source, diagnostics, aliases, settingsPath) {
+function validateModel(value, known, available, source, diagnostics, aliases, dynamicAliases, settingsPath) {
+    if (isDynamicModelAlias(value, dynamicAliases))
+        return;
     try {
         const parsed = resolveModelReference(value, aliases, known, settingsPath);
         const name = `${parsed.provider}/${parsed.model}`;
@@ -130,13 +163,14 @@ function validateModel(value, known, available, source, diagnostics, aliases, se
         diagnostics.push(diagnostic("error", "MODEL_INVALID", error.message, source, error.message.includes("thinking") ? THINKING_HINT : "Use provider/model or provider/model:thinking."));
     }
 }
-function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath) {
+function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, source) {
     let definition;
     try {
         definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
     }
     catch (error) {
-        diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", 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 ?? "";
@@ -147,20 +181,18 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
     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);
+        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, pi) {
-    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, kind, selector) {
-    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) { return settingsSource; }
 export async function doctor(options = {}) {
     const cwd = canonical(options.cwd ?? process.cwd());
     const agentDir = canonical(options.agentDir ?? getAgentDir());
@@ -173,6 +205,8 @@ export async function doctor(options = {}) {
     catch (error) {
         diagnostics.push(diagnostic("error", "SETTINGS_INVALID", error.message, settingsPath, "Fix or remove the invalid workflow settings file."));
     }
+    let settingsSources = { concurrency: settingsPath, modelAliases: settingsPath, disabledAgentResources: settingsPath };
+    const projectSettingsPath = workflowProjectSettingsPath(cwd);
     let pi;
     try {
         pi = await (options.discoverPi ?? discoverPi)(cwd, agentDir);
@@ -187,41 +221,98 @@ export async function doctor(options = {}) {
         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;
     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`));
+        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(resourcePolicy, "extensions", extension)}.disabledAgentResources.extensions`));
+        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 = [
+        ...Object.keys(aliases).map((name) => ({ name, kind: "static", provenance: settingsSources.modelAliases })),
+        ...registeredModelAliases.map(({ name, version, headline, extensionDescription }) => ({ name, kind: "dynamic", provenance: `extension: ${headline}`, version, headline, extensionDescription })),
+    ].sort((left, right) => left.name.localeCompare(right.name) || left.kind.localeCompare(right.kind));
     const roles = [];
     const definitions = new Map();
+    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();
+    for (const file of extensionScan.files)
+        extensionFilesByName.set(file.name, [...(extensionFilesByName.get(file.name) ?? []), file]);
+    const duplicateExtensionNames = new Set();
+    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();
+    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();
     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 (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) {
@@ -231,7 +322,14 @@ export async function doctor(options = {}) {
                 global.overriddenBy = path;
             }
         }
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
+        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, dynamicAliases, settingsPath);
         if (definition)
             definitions.set(name, definition);
         else
@@ -244,7 +342,7 @@ export async function doctor(options = {}) {
     const severityOrder = { 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, severity) { return report.diagnostics.filter((item) => item.severity === severity).length; }
 export function doctorExitCode(report) { return count(report, "error") > 0 ? 1 : 0; }
@@ -255,7 +353,9 @@ export function formatDoctorReport(report) {
         "## 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",
@@ -270,6 +370,8 @@ export function formatDoctorReport(report) {
         `- 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)"}`,
         "",
@@ -277,7 +379,10 @@ export function formatDoctorReport(report) {
         ...(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"]),

package/dist/src/execution.d.ts

@@ -0,0 +1,17 @@
+import { RunStore } from "./persistence.js";
+import type { AgentAttempt } from "./agent-execution.js";
+import type { AgentIdentity, JsonValue, ShellIdentity, ShellOptions, ShellResult, WorkflowBridge, WorkflowExecution } from "./types.js";
+export declare const RPC_LIMIT_BYTES: number;
+export declare const HEARTBEAT_TIMEOUT_MS = 5000;
+export declare function encoded(value: unknown): string;
+export declare function agentIdentityPath(identity: AgentIdentity): string;
+export declare function shellIdentityPath(identity: ShellIdentity): string;
+export declare function readShellResult(value: unknown): ShellResult;
+export declare function agentWorktree(identity: AgentIdentity): {
+    worktreeOwner?: string;
+};
+export declare function executeShellCommand(command: string, options: ShellOptions, signal: AbortSignal, cwd?: string): Promise<ShellResult>;
+export declare function runWorkflow(script: string, args?: JsonValue, bridge?: WorkflowBridge, signal?: AbortSignal): WorkflowExecution;
+export declare function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">): Promise<void>;
+export declare function persistAgentAttempts(store: RunStore, id: string, attempts: readonly AgentAttempt[]): Promise<void>;
+export type { AgentIdentity, ShellIdentity, WorkflowBridge, WorkflowExecution } from "./types.js";