pi-extensible-workflows 3.0.0 → 3.1.0

package/dist/src/utils.d.ts

@@ -13,12 +13,18 @@ export declare function asWorkflowError(error: unknown): WorkflowError;
 export declare function fail(code: WorkflowErrorCode, message: string): never;
 export declare function parseThinking(value: unknown): ModelSpec["thinking"] | undefined;
 export declare function parseModelReference(value: string): ModelSpec;
+export declare function annotateModelAliasError(error: unknown, name: string): unknown;
+export declare function modelAliasErrorName(error: unknown): string | undefined;
 export declare function modelAliasName(value: string, aliases: Readonly<Record<string, string>>): string | undefined;
 export declare function validateModelAliases(value: unknown, settingsPath?: string): Readonly<Record<string, string>>;
 export declare function unknownModel(value: string, target: string | undefined, settingsPath?: string): never;
 export declare function resolveModelReference(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
 export declare function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string;
 export declare function aliasDrift(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): string[];
+export declare function validateResourcePattern(pattern: string): void;
+export declare function resourcePatternMatches(resource: string, pattern: string): boolean;
+export declare function disabledResources(patterns: readonly string[], resources: readonly string[]): string[];
+export declare function unmatchedResourcePatterns(patterns: readonly string[], resources: readonly string[]): string[];
 export declare function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions;
 export declare function createLaunchSnapshot(input: Omit<import("./types.js").LaunchSnapshot, "identityVersion"> & {
     identityVersion?: number;

package/dist/src/utils.js

@@ -1,4 +1,5 @@
 import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError } from "./types.js";
+import { Minimatch } from "minimatch";
 export function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
 export { object as isObject };
 export function jsonValue(value, seen = new Set()) {
@@ -61,7 +62,21 @@ export function parseModelReference(value) {
         fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
     return { provider: match[1], model: match[2], ...(thinking ? { thinking: thinking } : {}) };
 }
-function aliasError(message, settingsPath) { fail("CONFIG_ERROR", `${message} (settings: ${settingsPath})`); }
+const MODEL_ALIAS_ERROR_NAME = Symbol("modelAliasErrorName");
+function aliasError(message, settingsPath, name) {
+    const error = new WorkflowError("CONFIG_ERROR", `${message} (settings: ${settingsPath})`);
+    if (name)
+        Object.defineProperty(error, MODEL_ALIAS_ERROR_NAME, { value: name, configurable: true });
+    throw error;
+}
+export function annotateModelAliasError(error, name) {
+    if (error instanceof WorkflowError)
+        Object.defineProperty(error, MODEL_ALIAS_ERROR_NAME, { value: name, configurable: true });
+    return error;
+}
+export function modelAliasErrorName(error) {
+    return error instanceof WorkflowError ? error[MODEL_ALIAS_ERROR_NAME] : undefined;
+}
 export function modelAliasName(value, aliases) {
     const name = /^([^/:\s]+)(?::[^:\s]+)?$/.exec(value)?.[1];
     return name && Object.prototype.hasOwnProperty.call(aliases, name) ? name : undefined;
@@ -72,9 +87,9 @@ export function validateModelAliases(value, settingsPath = "workflow settings")
     const aliases = {};
     for (const [name, target] of Object.entries(value)) {
         if (!MODEL_ALIAS_NAME.test(name))
-            aliasError(`Invalid model alias name: ${name}`, settingsPath);
+            aliasError(`Invalid model alias name: ${name}`, settingsPath, name);
         if (typeof target !== "string" || !target.trim())
-            aliasError(`Invalid model alias target for ${name}`, settingsPath);
+            aliasError(`Invalid model alias target for ${name}`, settingsPath, name);
         aliases[name] = target;
     }
     for (const name of Object.keys(aliases)) {
@@ -82,7 +97,7 @@ export function validateModelAliases(value, settingsPath = "workflow settings")
             resolveModelReference(name, aliases);
         }
         catch (error) {
-            aliasError(`Invalid model alias target for ${name}: ${errorText(error)}`, settingsPath);
+            aliasError(`Invalid model alias target for ${name}: ${errorText(error)}`, settingsPath, name);
         }
     }
     return Object.freeze(aliases);
@@ -123,6 +138,31 @@ export function modelCapability(value, aliases, knownModels, settingsPath) {
 export function aliasDrift(previous, current) {
     return [...new Set([...Object.keys(previous), ...Object.keys(current)])].sort().flatMap((name) => previous[name] === current[name] ? [] : [`${name}: ${previous[name] ?? "(missing)"} -> ${current[name] ?? "(missing)"}`]);
 }
-export function mergeAgentResourceExclusions(...values) { return { skills: [...new Set(values.flatMap((value) => value?.skills ?? []))], extensions: [...new Set(values.flatMap((value) => value?.extensions ?? []))] }; }
+const RESOURCE_PATTERN_OPTIONS = { dot: true, nonegate: true, nocomment: true };
+function resourcePatternBody(pattern) { return pattern.startsWith("!") ? pattern.slice(1) : pattern; }
+function resourcePatternPath(value) { return value.replaceAll("\\", "/"); }
+export function validateResourcePattern(pattern) {
+    const body = resourcePatternBody(pattern);
+    if (!body)
+        throw new Error(`Empty minimatch pattern ${JSON.stringify(pattern)}`);
+    const matcher = new Minimatch(resourcePatternPath(body), RESOURCE_PATTERN_OPTIONS);
+    if (matcher.makeRe() === false)
+        throw new Error(`Invalid minimatch pattern ${JSON.stringify(pattern)}`);
+}
+export function resourcePatternMatches(resource, pattern) { return new Minimatch(resourcePatternPath(resourcePatternBody(pattern)), RESOURCE_PATTERN_OPTIONS).match(resourcePatternPath(resource)); }
+export function disabledResources(patterns, resources) {
+    const disabled = new Set();
+    for (const resource of resources) {
+        let excluded = false;
+        for (const pattern of patterns)
+            if (resourcePatternMatches(resource, pattern))
+                excluded = !pattern.startsWith("!");
+        if (excluded)
+            disabled.add(resource);
+    }
+    return [...disabled];
+}
+export function unmatchedResourcePatterns(patterns, resources) { return patterns.filter((pattern) => !resources.some((resource) => resourcePatternMatches(resource, pattern))); }
+export function mergeAgentResourceExclusions(...values) { return { skills: values.flatMap((value) => value?.skills ?? []), extensions: values.flatMap((value) => value?.extensions ?? []) }; }
 export function createLaunchSnapshot(input) { return deepFreeze(structuredClone({ ...input, launchKind: input.launchKind ?? (input.functionName ? "function" : "inline"), identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION })); }
 export function loadLaunchSnapshot(input) { return deepFreeze(structuredClone(input)); }

package/dist/src/validation.d.ts

@@ -1,15 +1,19 @@
-import type { AgentDefinition, AgentResourcePolicy, CheckpointInput, JsonSchema, JsonValue, LaunchSnapshot, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, ValidatedWorkflowLaunch, WorkflowMetadata, WorkflowSettings, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
+import type { AgentDefinition, AgentResourcePolicy, CheckpointInput, JsonSchema, JsonValue, LaunchSnapshot, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, ValidatedWorkflowLaunch, WorkflowMetadata, WorkflowRoleDirectoryRegistration, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
 import type { WorkflowRegistryApi } from "./registry.js";
 export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
 export declare function validateCheckpoint(value: unknown): CheckpointInput;
 export declare function workflowSettingsPath(agentDir?: string): string;
 export declare function workflowProjectSettingsPath(cwd: string): string;
 export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
+export declare function loadSettingsOverrides(path: string): Readonly<WorkflowSettingsOverrides>;
+export declare function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): WorkflowSettingsResolution;
+export declare function validateModelAliasAvailability(aliases: Readonly<Record<string, string>>, names: readonly string[], availableModels: ReadonlySet<string>, knownModels: ReadonlySet<string>, settingsPath?: string): void;
 export declare function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): AgentResourcePolicy;
 export declare function saveModelAliases(path?: string, aliases?: Readonly<Record<string, string>>): void;
 export declare function parseRoleMarkdown(content: string, strict?: boolean, rolePath?: string): AgentDefinition;
 export declare function workflowRoleDirectories(agentDir?: string): readonly string[];
-export declare function loadAgentDefinitions(cwd: string, agentDir?: string, projectTrusted?: boolean): Readonly<Record<string, AgentDefinition>>;
+export type WorkflowRoleDirectoryInput = string | WorkflowRoleDirectoryRegistration;
+export declare function loadAgentDefinitions(cwd: string, agentDir?: string, projectTrusted?: boolean, extensionRoleDirectories?: readonly WorkflowRoleDirectoryInput[]): Readonly<Record<string, AgentDefinition>>;
 export declare function instrumentWorkflow(script: string): string;
 export declare function workflowPrompt(template: string, values: Readonly<Record<string, JsonValue>>): string;
 export declare function validateSchema(schema: unknown, at?: string): asserts schema is JsonSchema;

package/dist/src/validation.js

@@ -8,7 +8,8 @@ import { Script } from "node:vm";
 import { Value } from "typebox/value";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { WorkflowError } from "./types.js";
-import { deepFreeze, errorText, fail, jsonValue, mergeAgentResourceExclusions, modelAliasName, modelCapability, object, parseThinking, positiveInteger, resolveModelReference, unknownModel, validateModelAliases } from "./utils.js";
+import { registeredWorkflowRoleDirectoryRegistrations } from "./registry.js";
+import { annotateModelAliasError, deepFreeze, errorText, fail, jsonValue, modelAliasName, modelCapability, object, parseThinking, positiveInteger, resolveModelReference, unknownModel, validateModelAliases, validateResourcePattern } from "./utils.js";
 import { WORKFLOW_CALL_KINDS } from "./types.js";
 export const DEFAULT_SETTINGS = Object.freeze({ concurrency: 8 });
 export function validateCheckpoint(value) {
@@ -23,11 +24,27 @@ export function validateCheckpoint(value) {
 export function workflowSettingsPath(agentDir = getAgentDir()) { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
 export function workflowProjectSettingsPath(cwd) { return join(cwd, ".pi", ROLE_DIRECTORY, "settings.json"); }
 const EMPTY_AGENT_RESOURCE_EXCLUSIONS = Object.freeze({ skills: [], extensions: [] });
+function resourcePatternHasMagic(value) { return /[*?\x5b\x5d{}()]/.test(value); }
 function normalizedResourcePath(value, settingsPath) {
     let expanded = value === "~" ? homedir() : value.startsWith("~/") || value.startsWith("~\\") ? join(homedir(), value.slice(2)) : value;
     if (expanded.startsWith("file://"))
         expanded = fileURLToPath(expanded);
     const resolved = resolve(dirname(settingsPath), expanded);
+    if (expanded === "**" || expanded.startsWith("**/") || expanded.startsWith("**\\"))
+        return expanded;
+    if (resourcePatternHasMagic(expanded)) {
+        const magicIndex = resolved.search(/[*?\x5b\x5d{}()]/);
+        const separatorIndex = Math.max(resolved.lastIndexOf("/", magicIndex), resolved.lastIndexOf("\\", magicIndex));
+        const rootBoundary = separatorIndex === 0 || (separatorIndex === 2 && /^[A-Za-z]:[\\/]/.test(resolved));
+        const prefix = rootBoundary ? resolved.slice(0, separatorIndex + 1) : separatorIndex >= 0 ? resolved.slice(0, separatorIndex) : resolved;
+        const suffix = rootBoundary ? resolved.slice(separatorIndex + 1) : separatorIndex >= 0 ? resolved.slice(separatorIndex) : "";
+        try {
+            return `${realpathSync(prefix)}${suffix}`;
+        }
+        catch {
+            return resolved;
+        }
+    }
     try {
         return realpathSync(resolved);
     }
@@ -51,35 +68,41 @@ function validateAgentResourceExclusions(value, settingsPath, errorCode = "INVAL
             continue;
         if (!Array.isArray(entries))
             fail(errorCode, `${base}.${kind} must be an array`);
-        const seen = new Set();
         for (const [index, entry] of entries.entries()) {
             if (typeof entry !== "string" || !entry.trim())
                 fail(errorCode, `${base}.${kind}[${String(index)}] must be a non-empty string`);
             let selector = entry.trim();
             if (kind === "extensions") {
+                const negated = selector.startsWith("!");
+                const body = negated ? selector.slice(1) : selector;
+                if (!body)
+                    fail(errorCode, `${base}.${kind}[${String(index)}] must be a valid minimatch pattern: Empty minimatch pattern ${JSON.stringify(selector)}`);
                 try {
-                    selector = normalizedResourcePath(selector, settingsPath);
+                    selector = `${negated ? "!" : ""}${normalizedResourcePath(body, settingsPath)}`;
                 }
                 catch (error) {
                     fail(errorCode, `${base}.${kind}[${String(index)}] must be a valid path: ${errorText(error)}`);
                 }
             }
-            if (!seen.has(selector)) {
-                seen.add(selector);
-                normalized[kind].push(selector);
+            try {
+                validateResourcePattern(selector);
             }
+            catch (error) {
+                fail(errorCode, `${base}.${kind}[${String(index)}] must be a valid minimatch pattern: ${errorText(error)}`);
+            }
+            normalized[kind].push(selector);
         }
     }
     return Object.freeze({ skills: Object.freeze(normalized.skills), extensions: Object.freeze(normalized.extensions) });
 }
-export function loadSettings(path = workflowSettingsPath()) {
+function parseSettings(path, partial) {
     let parsed;
     try {
         parsed = JSON.parse(readFileSync(path, "utf8"));
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return DEFAULT_SETTINGS;
+            return partial ? Object.freeze({}) : DEFAULT_SETTINGS;
         fail("CONFIG_ERROR", `Invalid workflow settings JSON at ${path}: ${errorText(error)}`);
     }
     if (!object(parsed))
@@ -88,19 +111,51 @@ export function loadSettings(path = workflowSettingsPath()) {
     const unknown = Object.keys(parsed).find((key) => !allowed.has(key));
     if (unknown)
         fail("INVALID_SETTINGS", `Unknown workflow setting at ${path}: ${unknown}`);
-    const concurrency = parsed.concurrency === undefined ? DEFAULT_SETTINGS.concurrency : parsed.concurrency;
-    if (!positiveInteger(concurrency) || concurrency > 16)
+    const concurrency = parsed.concurrency === undefined ? (partial ? undefined : DEFAULT_SETTINGS.concurrency) : parsed.concurrency;
+    if (concurrency !== undefined && (!positiveInteger(concurrency) || concurrency > 16))
         fail("INVALID_SETTINGS", `${path}.concurrency must be an integer from 1 to 16`);
     const modelAliases = parsed.modelAliases === undefined ? undefined : validateModelAliases(parsed.modelAliases, path);
     const disabledAgentResources = validateAgentResourceExclusions(parsed.disabledAgentResources, path);
-    return Object.freeze({ concurrency, ...(modelAliases ? { modelAliases } : {}), ...(disabledAgentResources ? { disabledAgentResources } : {}) });
+    return Object.freeze({ ...(concurrency === undefined ? {} : { concurrency }), ...(modelAliases === undefined ? {} : { modelAliases }), ...(disabledAgentResources === undefined ? {} : { disabledAgentResources }) });
 }
-export function resolveAgentResourcePolicy(cwd, projectTrusted, globalSettingsPath = workflowSettingsPath()) {
+export function loadSettings(path = workflowSettingsPath()) { return parseSettings(path, false); }
+export function loadSettingsOverrides(path) { return parseSettings(path, true); }
+export function resolveWorkflowSettings(cwd, projectTrusted, globalSettingsPath = workflowSettingsPath()) {
     const projectSettingsPath = workflowProjectSettingsPath(cwd);
-    const global = loadSettings(globalSettingsPath).disabledAgentResources ?? EMPTY_AGENT_RESOURCE_EXCLUSIONS;
-    const project = projectTrusted ? loadSettings(projectSettingsPath).disabledAgentResources ?? EMPTY_AGENT_RESOURCE_EXCLUSIONS : EMPTY_AGENT_RESOURCE_EXCLUSIONS;
-    const effective = mergeAgentResourceExclusions(global, project);
-    return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [] };
+    const global = loadSettings(globalSettingsPath);
+    const project = projectTrusted ? loadSettingsOverrides(projectSettingsPath) : Object.freeze({});
+    const projectHas = (key) => Object.prototype.hasOwnProperty.call(project, key);
+    const sources = {
+        concurrency: projectHas("concurrency") ? projectSettingsPath : globalSettingsPath,
+        modelAliases: projectHas("modelAliases") ? projectSettingsPath : globalSettingsPath,
+        disabledAgentResources: projectHas("disabledAgentResources") ? projectSettingsPath : globalSettingsPath,
+    };
+    const effective = Object.freeze({
+        concurrency: project.concurrency ?? global.concurrency,
+        ...(projectHas("modelAliases") ? { modelAliases: project.modelAliases } : global.modelAliases === undefined ? {} : { modelAliases: global.modelAliases }),
+        ...(projectHas("disabledAgentResources") ? { disabledAgentResources: project.disabledAgentResources } : global.disabledAgentResources === undefined ? {} : { disabledAgentResources: global.disabledAgentResources }),
+    });
+    return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, sources };
+}
+export function validateModelAliasAvailability(aliases, names, availableModels, knownModels, settingsPath) {
+    for (const name of names) {
+        try {
+            const target = modelCapability(name, aliases, knownModels, settingsPath);
+            if (!availableModels.has(target))
+                unknownModel(name, target, settingsPath);
+        }
+        catch (error) {
+            throw annotateModelAliasError(error, name);
+        }
+    }
+}
+export function resolveAgentResourcePolicy(cwd, projectTrusted, globalSettingsPath = workflowSettingsPath()) {
+    const resolved = resolveWorkflowSettings(cwd, projectTrusted, globalSettingsPath);
+    const empty = EMPTY_AGENT_RESOURCE_EXCLUSIONS;
+    const global = resolved.global.disabledAgentResources ?? empty;
+    const project = resolved.project.disabledAgentResources ?? empty;
+    const effective = resolved.effective.disabledAgentResources ?? empty;
+    return { globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [] };
 }
 export function saveModelAliases(path = workflowSettingsPath(), aliases = {}) {
     const normalized = validateModelAliases(aliases, path);
@@ -175,23 +230,60 @@ export function workflowRoleDirectories(agentDir = getAgentDir()) {
 function projectRoleDirectories(root) {
     return [join(root, ROLE_DIRECTORY, "roles")];
 }
-function readAgentDefinitions(dir) {
-    try {
-        return Object.fromEntries(readdirSync(dir, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && extname(entry.name) === ".md")
-            .map((entry) => { const path = join(dir, entry.name); return [basename(entry.name, ".md"), parseRoleMarkdown(readFileSync(path, "utf8"), true, path)]; }));
+function roleDirectorySources(dirs) {
+    const seen = new Set();
+    return dirs.flatMap((value) => {
+        const source = typeof value === "string" ? { path: value } : { path: value.path, extension: value.extension };
+        if (seen.has(source.path))
+            return [];
+        seen.add(source.path);
+        return [source];
+    });
+}
+function roleDirectoryLabel(source, extension = true) {
+    return source.extension ? `Extension "${source.extension.headline}" (${source.extension.version})` : extension ? "Registered workflow extension" : "Standard workflow";
+}
+function scanRoleFiles(dirs, extension) {
+    const files = [];
+    for (const source of roleDirectorySources(dirs)) {
+        let entries;
+        try {
+            entries = readdirSync(source.path, { withFileTypes: true });
+        }
+        catch (error) {
+            if (!extension && error.code === "ENOENT")
+                continue;
+            fail("INVALID_METADATA", `${roleDirectoryLabel(source, extension)} role directory "${source.path}" could not be scanned: ${errorText(error)}`);
+        }
+        for (const entry of entries)
+            if (entry.isFile() && extname(entry.name) === ".md")
+                files.push({ name: basename(entry.name, ".md"), path: join(source.path, entry.name), source });
     }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return {};
-        throw error;
+    return files.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
+}
+function readRoleDefinitions(dirs, extension = false) {
+    const files = scanRoleFiles(dirs, extension);
+    if (extension) {
+        const byName = new Map();
+        for (const file of files)
+            byName.set(file.name, [...(byName.get(file.name) ?? []), file]);
+        for (const [name, matches] of byName)
+            if (matches.length > 1)
+                fail("INVALID_METADATA", `Duplicate extension role "${name}": ${matches.map(({ path, source }) => `${roleDirectoryLabel(source)} role directory "${source.path}" (${path})`).join("; ")}`);
     }
+    return Object.fromEntries(files.map(({ name, path, source }) => {
+        try {
+            return [name, parseRoleMarkdown(readFileSync(path, "utf8"), true, path)];
+        }
+        catch (error) {
+            if (extension)
+                fail("INVALID_METADATA", `${roleDirectoryLabel(source)} role directory "${source.path}" contains invalid role "${name}" at "${path}": ${errorText(error)}`);
+            throw error;
+        }
+    }));
 }
-function readRoleDefinitions(dirs) {
-    return Object.fromEntries(dirs.flatMap((dir) => Object.entries(readAgentDefinitions(dir))));
-}
-export function loadAgentDefinitions(cwd, agentDir = getAgentDir(), projectTrusted = true) {
-    return deepFreeze({ ...readRoleDefinitions(workflowRoleDirectories(agentDir)), ...(projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(cwd, ".pi"))) : {}) });
+export function loadAgentDefinitions(cwd, agentDir = getAgentDir(), projectTrusted = true, extensionRoleDirectories = registeredWorkflowRoleDirectoryRegistrations()) {
+    return deepFreeze({ ...readRoleDefinitions(extensionRoleDirectories, true), ...readRoleDefinitions(workflowRoleDirectories(agentDir)), ...(projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(cwd, ".pi"))) : {}) });
 }
 function validateRolePolicies(definitions, roles, availableModels, rootTools, aliases = {}, knownModels = availableModels, settingsPath) {
     for (const role of roles) {
@@ -709,7 +801,7 @@ export function validateWorkflowLaunchWithRegistry(params, context, registry) {
     if (!script)
         fail("INVALID_SYNTAX", "Provide script or registered function");
     const metadata = validateWorkflowMetadata({ name: workflowName, ...(typeof params.description === "string" ? { description: params.description } : fn?.description ? { description: fn.description } : {}) });
-    const globalAgentDefinitions = loadAgentDefinitions(context.cwd, context.agentDir, false);
+    const globalAgentDefinitions = loadAgentDefinitions(context.cwd, context.agentDir, false, registry && typeof registry.roleDirectoryRegistrations === "function" ? registry.roleDirectoryRegistrations() : registry && typeof registry.roleDirectories === "function" ? registry.roleDirectories() : undefined);
     const projectAgentDefinitions = context.projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(context.cwd, ".pi"))) : {};
     const agentDefinitions = deepFreeze({ ...globalAgentDefinitions, ...projectAgentDefinitions });
     const aliases = context.modelAliases ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -64,6 +64,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "acorn": "^8.17.0"
+    "acorn": "^8.17.0",
+    "minimatch": "^10.2.5"
   }
 }

package/skills/pi-extensible-workflows/SKILL.md

@@ -4,30 +4,49 @@ description: Use when the task is complex enough to require multiple subagents o
 ---
 
 # pi-extensible-workflows
+
 Use `workflow` only for genuinely multi-agent orchestration; one agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
 
 ## Example
-```js
-const reportSchema = { type: "object", properties: { summary: { type: "string" }, findings: { type: "array", items: { type: "string" } } }, required: ["summary", "findings"], additionalProperties: false };
 
+```js
+const reportSchema = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    findings: { type: "array", items: { type: "string" } },
+  },
+  required: ["summary", "findings"],
+  additionalProperties: false,
+};
 
 const reports = await parallel("research", {
-  first: () => agent("Research the first target.", { role: "scout", outputSchema: reportSchema }),
-  second: () => agent("Research the second target.", { role: "scout", outputSchema: reportSchema }),
+  first: () =>
+    agent("Research the first target.", {
+      role: "scout",
+      outputSchema: reportSchema,
+    }),
+  second: () =>
+    agent("Research the second target.", {
+      role: "scout",
+      outputSchema: reportSchema,
+    }),
 });
 
-return agent(
-  prompt("Review these reports:\n\n{reports}", { reports }),
-  { role: "reviewer", outputSchema: reportSchema },
-);
+return agent(prompt("Review these reports:\n\n{reports}", { reports }), {
+  role: "reviewer",
+  outputSchema: reportSchema,
+});
 ```
 
 Inline launches require a non-empty `name`. Registered function launches must omit `name`; they use `workflow` as the run name:
+
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
+
 Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. A terminal `parentRunId` reuses matching named `withWorktree` scopes but does not replay journal results. For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. Retry versus per-agent `retries` and `workflow_resume` is always explicit; external side effects before failure are not guaranteed exactly once.
-Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task. 
+Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task.
 
 Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.
 
@@ -37,20 +56,24 @@ Example use of `shell`:
 // ... other code
 const testRes = await shell("yarn test", { env: { CI: "1" } });
 if (testRes.exitCode === 0) {
-   // success path
-   return {...}
+  // success path
+  return { ok: true };
 }
 ```
 
 Most of the times using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
 
 ## `agent()` options
+
 ```typescript
 export interface AgentOptions {
-  label?: string; model?: string; role?: string; tools?: string[];
-  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; 
-  outputSchema?: JsonSchema; 
-  retries?: number; 
+  label?: string;
+  model?: string;
+  role?: string;
+  tools?: string[];
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+  outputSchema?: JsonSchema;
+  retries?: number;
   timeoutMs?: number | null;
   [key: string]: JsonValue;
 }
@@ -61,24 +84,34 @@ Extensions may add JSON-compatible agent options such as `advisor: true`; core k
 Agent calls are unnamed. Direct calls receive hidden source call-site identity; aliases are unsupported, and calls from one source site must not race outside `parallel` or `pipeline`, whose structural keys make replay deterministic.
 
 ## Passing agent results
+
 Use independent `agent(prompt, options)` calls and pass each completed result explicitly to the next prompt. This keeps workflow execution deterministic and makes replay state local to each call:
+
 ```js
 const findings = await agent("Inspect the implementation.");
-const fix = await agent(prompt("Propose the smallest fix from these findings:\n\n{findings}", { findings }));
+const fix = await agent(
+  prompt("Propose the smallest fix from these findings:\n\n{findings}", {
+    findings,
+  }),
+);
 return { findings, fix };
 ```
 
 ## Worktrees
+
 Use `withWorktree(name, callback)` for top-level agents that collaborate in one explicitly named worktree scope:
+
 ```js
 const result = await withWorktree("issue", async ({ path, branch }) => {
   const report = await agent("Implement the issue");
   return { path, branch, report };
 });
 ```
+
 Entering the scope materializes its worktree before the callback. The callback receives a frozen reference containing only the real string `path` and `branch`; callbacks may ignore the argument, and their bare return value is preserved. Concurrent agents share mutable files, so assign non-conflicting work or coordinate explicitly.
 
 Branches may call any workflow function, not only `agent()`. Use separate named scopes when parallel branches need isolated worktrees:
+
 ```js
 const results = await parallel("implementation", {
   api: () => withWorktree("api", () => agent("Implement the API")),
@@ -89,6 +122,7 @@ const results = await parallel("implementation", {
 Registered extension functions receive `withWorktree` in context and can compose other registered functions with `context.invoke("reviewRepository", { focus: "security" })`. Their public inputs and outputs remain JSON; callbacks cannot cross the extension boundary.
 
 ## Rules
+
 - Use `log(messageString)` for brief operator status.
 - A role owns execution policy: with `role`, do not set `model`, `thinking`, or `tools`; only task options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
 - Use `parallel()` for independent tasks with different flows and `pipeline()` when every keyed item follows the same ordered stages; do not duplicate identical chains in `parallel()`. Signatures are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; keys are stable task, item, and stage names.

package/src/agent-execution.ts

@@ -2,13 +2,14 @@ import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
-import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, type AgentSessionEvent, type InlineExtension, type SessionStats, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 type AgentMessage = { role: string; content?: unknown; stopReason?: string; errorMessage?: string; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { total: number } } };
-import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, WorkflowRunContext } from "./types.js";
-import { jsonObject, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference } from "./utils.js";
+import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetup, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput, WorkflowRunContext } from "./types.js";
+import { jsonObject, disabledResources, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference, unmatchedResourcePatterns } from "./utils.js";
 import { WorkflowError } from "./types.js";
 import type { RunStore } from "./persistence.js";
+export type { AgentSetup, AgentSetupContext, AgentSetupHook, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput } from "./types.js";
 export interface AgentBudgetHooks {
   beforeAttempt(): void;
   beforeTurn(): void;
@@ -66,29 +67,6 @@ export interface AgentActivity { kind: "reasoning" | "tool" | "text"; text: stri
 export interface AgentProgress { accounting: AgentAccounting; toolCalls: readonly AgentToolCallProgress[]; activity?: AgentActivity; persist: boolean }
 export interface AgentAttempt { attempt: number; sessionId: string; sessionFile: string; result?: JsonValue; error?: { code: string; message: string }; accounting: AgentAccounting; setup?: AgentSetupSummary }
 export interface AgentExecutionResult { value: JsonValue; attempts: readonly AgentAttempt[]; cwd: string }
-export interface AgentSetup { prompt: string; options: Record<string, JsonValue>; sessionInput: SessionInput; createSession: SessionFactory }
-export interface AgentSetupContext { readonly run: Readonly<WorkflowRunContext>; readonly identity: Readonly<AgentIdentity>; readonly attempt: number; readonly signal: AbortSignal }
-export interface AgentSetupHook { priority?: number; setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void> }
-export interface RegisteredAgentSetupHook { name: string; priority: number; setup: AgentSetupHook["setup"] }
-type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
-export interface NativeSession {
-  readonly sessionId: string;
-  readonly sessionFile: string | undefined;
-  readonly messages: readonly AgentMessage[];
-  getSessionStats(): NativeSessionStats;
-  readonly systemPrompt?: string;
-  readonly model?: { provider: string; model?: string; id?: string };
-  readonly agent?: { state: { tools: readonly { name: string }[] } };
-  getLeafId?: () => string | null;
-  getToolDefinitions?: () => unknown;
-  subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
-  prompt(text: string): Promise<void>;
-  steer?(text: string): Promise<void>;
-  abort?(): Promise<void>;
-  dispose(): void;
-}
-export interface SessionInput { cwd: string; model: ModelSpec; tools: string[]; sessionLabel: string; agentDir?: string; customTools?: ToolDefinition[]; resultTool?: ToolDefinition; systemPromptAppend?: string; extensionFactories?: InlineExtension[]; resourcePolicy?: AgentResourcePolicy; options?: Record<string, JsonValue> }
-export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 
 function parseModel(value: string | undefined, fallback: ModelSpec, thinking?: ThinkingLevel, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec {
   if (!value) return { ...fallback, ...(thinking ? { thinking } : {}) };
@@ -129,7 +107,7 @@ function terminalProviderError(error: WorkflowError): TerminalProviderError | un
   return typeof candidate.provider === "string" && typeof candidate.model === "string" && typeof candidate.error === "string" ? { provider: candidate.provider, model: candidate.model, error: candidate.error } : undefined;
 }
 
-function accounting(stats: NativeSessionStats): AgentAccounting {
+function accounting(stats: ReturnType<NativeSession["getSessionStats"]>): AgentAccounting {
   return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
 }
 function canonicalSourcePath(path: string): string { try { return realpathSync(path); } catch { return resolve(path); } }
@@ -151,14 +129,17 @@ export async function createNativeAgentSession(input: SessionInput): Promise<Nat
     settingsManager.setProjectTrusted(policy.projectTrusted);
     const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
     const resolved = await packageManager.resolve();
-    const disabledExtensions = new Set(policy.effective.extensions);
-    const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)).filter((path) => !disabledExtensions.has(canonicalSourcePath(path))))];
+    const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)))];
+    const excludedExtensions = new Set(disabledResources(policy.effective.extensions, discoveredExtensions));
+    const extensionPaths = discoveredExtensions.filter((path) => !excludedExtensions.has(path));
+    Object.assign(policy, { excludedExtensions: [...excludedExtensions], unmatchedExtensions: unmatchedResourcePatterns(policy.effective.extensions, discoveredExtensions) });
     const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
-    const updateSkillMatches = (skills: readonly { name: string }[]) => {
-      const names = new Set(skills.map(({ name }) => name));
-      Object.assign(policy, { unmatchedSkills: policy.effective.skills.filter((name) => !names.has(name)) });
+    const updateSkillMatches = (skills: readonly { name: string }[]): Set<string> => {
+      const names = [...new Set(skills.map(({ name }) => name))];
+      const excludedSkills = disabledResources(policy.effective.skills, names);
+      Object.assign(policy, { excludedSkills, unmatchedSkills: unmatchedResourcePatterns(policy.effective.skills, names) });
+      return new Set(excludedSkills);
     };
-    const disabledSkills = new Set(policy.effective.skills);
     resourceLoader = new DefaultResourceLoader({
       cwd: input.cwd,
       agentDir,
@@ -169,14 +150,12 @@ export async function createNativeAgentSession(input: SessionInput): Promise<Nat
       additionalSkillPaths: skillPaths,
       ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
       skillsOverride: (base) => {
-        updateSkillMatches(base.skills);
+        const disabledSkills = updateSkillMatches(base.skills);
         return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
       },
       ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
     });
     await resourceLoader.reload();
-    const discoveredExtensions = new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)));
-    Object.assign(policy, { unmatchedExtensions: policy.effective.extensions.filter((path) => !discoveredExtensions.has(canonicalSourcePath(path))) });
   } else if (input.systemPromptAppend || input.extensionFactories?.length) {
     resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
     await resourceLoader.reload();
@@ -218,7 +197,7 @@ function fallbackSetupContext(root: AgentExecutionRoot, options: AgentExecutionO
   return { run, identity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) };
 }
 function resourcePolicySummary(policy: AgentResourcePolicy): NonNullable<AgentSetupSummary["disabledAgentResources"]> {
-  return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
+  return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], excludedSkills: [...(policy.excludedSkills ?? [])], excludedExtensions: [...(policy.excludedExtensions ?? [])], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
 }
 async function prepareAgentSetup(root: AgentExecutionRoot, createSession: SessionFactory, task: string, options: AgentExecutionOptions, resolved: { model: ModelSpec; tools: readonly string[]; systemPromptAppend: string }, cwd: string, attempt: number, signal: AbortSignal | undefined, customTools: readonly ToolDefinition[], resultTool: ToolDefinition | undefined): Promise<{ setup: AgentSetup; summary: AgentSetupSummary }> {
   const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
@@ -518,6 +497,13 @@ export class FairAgentScheduler {
     this.#runs.set(runId, { limit, ...(beforeLaunch ? { beforeLaunch } : {}), logical: 0, active: 0, queue: [] });
     this.#runOrder.push(runId);
   }
+  updateRunLimit(runId: string, limit: number): void {
+    const run = this.#runs.get(runId);
+    if (!run) throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
+    if (!Number.isInteger(limit) || limit < 1 || limit > this.sessionLimit) throw new WorkflowError("INVALID_SETTINGS", "Invalid run concurrency");
+    run.limit = limit;
+    this.#dispatch();
+  }
 
   spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): { id: string; result: Promise<ScheduledAgentResult> } {
     const run = this.#runs.get(runId);