pi-extensible-workflows 3.0.0 → 3.2.0

package/dist/src/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSessionEvent, CreateAgentSessionOptions, InlineExtension, SessionStats, ToolDefinition } from "@earendil-works/pi-coding-agent";
 export declare const RUN_STATES: readonly ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
 export declare const AGENT_STATES: readonly ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
 export declare const WORKFLOW_CALL_KINDS: readonly ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"];
@@ -141,6 +142,17 @@ export interface ModelSpec {
     model: string;
     thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 }
+export interface WorkflowModelAliasResolverContext {
+    cwd: string;
+    projectTrusted: boolean;
+    rootModel: ModelSpec;
+    knownModels: ReadonlySet<string>;
+    availableModels: ReadonlySet<string>;
+    signal: AbortSignal;
+}
+export interface WorkflowModelAlias {
+    resolve: (context: Readonly<WorkflowModelAliasResolverContext>) => string | Promise<string>;
+}
 export interface WorkflowMetadata {
     name: string;
     description?: string;
@@ -150,6 +162,25 @@ export interface WorkflowSettings {
     modelAliases?: Readonly<Record<string, string>>;
     disabledAgentResources?: Readonly<AgentResourceExclusions>;
 }
+export interface WorkflowSettingsOverrides {
+    concurrency?: number;
+    modelAliases?: Readonly<Record<string, string>>;
+    disabledAgentResources?: Readonly<AgentResourceExclusions>;
+}
+export interface WorkflowSettingsSources {
+    concurrency: string;
+    modelAliases: string;
+    disabledAgentResources: string;
+}
+export interface WorkflowSettingsResolution {
+    globalSettingsPath: string;
+    projectSettingsPath: string;
+    projectTrusted: boolean;
+    global: Readonly<WorkflowSettings>;
+    project: Readonly<WorkflowSettingsOverrides>;
+    effective: Readonly<WorkflowSettings>;
+    sources: Readonly<WorkflowSettingsSources>;
+}
 export interface AgentResourceExclusions {
     skills: readonly string[];
     extensions: readonly string[];
@@ -163,6 +194,8 @@ export interface AgentResourcePolicy {
     effective: AgentResourceExclusions;
     unmatchedSkills: string[];
     unmatchedExtensions: string[];
+    excludedSkills?: string[];
+    excludedExtensions?: string[];
 }
 export interface AgentActivity {
     kind: "reasoning" | "tool" | "text";
@@ -183,6 +216,8 @@ export interface AgentSetupSummary {
     disabledAgentResources?: {
         skills: readonly string[];
         extensions: readonly string[];
+        excludedSkills?: readonly string[];
+        excludedExtensions?: readonly string[];
         unmatchedSkills: readonly string[];
         unmatchedExtensions: readonly string[];
     };
@@ -222,6 +257,7 @@ export interface AgentRecord {
     state: AgentState;
     parentId?: string;
     structuralPath?: readonly string[];
+    resultPath?: string;
     parentBreadcrumb?: string;
     worktreeOwner?: string;
     role?: string;
@@ -294,9 +330,11 @@ export interface LaunchSnapshot {
     args: JsonValue;
     metadata: WorkflowMetadata;
     settings: WorkflowSettings;
+    settingsSources?: WorkflowSettingsSources;
     budget?: WorkflowBudget;
     settingsPath?: string;
     modelAliases?: Readonly<Record<string, string>>;
+    phases?: readonly string[];
     models: readonly string[];
     tools: readonly string[];
     agentTypes: readonly string[];
@@ -359,14 +397,69 @@ export interface WorkflowVariable {
     schema: JsonSchema;
     resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue;
 }
+type NativeAgentMessage = {
+    role: string;
+    content?: unknown;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: {
+            total: number;
+        };
+    };
+};
+type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
+export interface NativeSession {
+    readonly sessionId: string;
+    readonly sessionFile: string | undefined;
+    readonly messages: readonly NativeAgentMessage[];
+    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;
+}
+type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
+type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
+export interface SessionInput {
+    cwd: string;
+    model: ModelSpec;
+    tools: SessionTools;
+    sessionLabel: string;
+    agentDir?: string;
+    customTools?: SessionCustomTools;
+    resultTool?: ToolDefinition;
+    systemPromptAppend?: string;
+    extensionFactories?: InlineExtension[];
+    resourcePolicy?: AgentResourcePolicy;
+    options?: AgentOptions;
+}
+export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 export interface AgentSetup {
     prompt: string;
-    options: Record<string, JsonValue>;
-    sessionInput: {
-        extensionFactories?: unknown[];
-        [key: string]: unknown;
-    };
-    createSession: unknown;
+    options: AgentOptions;
+    sessionInput: SessionInput;
+    createSession: SessionFactory;
 }
 export interface AgentSetupContext {
     readonly run: Readonly<WorkflowRunContext>;
@@ -383,13 +476,21 @@ export interface RegisteredAgentSetupHook {
     priority: number;
     setup: AgentSetupHook["setup"];
 }
-export interface WorkflowExtension {
+export interface WorkflowExtensionMetadata {
     version: string;
     headline: string;
     description: string;
+}
+export interface WorkflowRoleDirectoryRegistration {
+    path: string;
+    extension: WorkflowExtensionMetadata;
+}
+export interface WorkflowExtension extends WorkflowExtensionMetadata {
     functions?: Readonly<Record<string, WorkflowFunction>>;
     variables?: Readonly<Record<string, WorkflowVariable>>;
+    modelAliases?: Readonly<Record<string, WorkflowModelAlias>>;
     agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
+    roleDirectories?: readonly (string | URL)[];
 }
 export interface WorkflowJournal {
     get(path: string): JsonValue | undefined;
@@ -511,10 +612,34 @@ export interface WorkflowCatalogVariable {
     description: string;
     schema: JsonSchema;
 }
+export interface WorkflowCatalogModelAlias {
+    name: string;
+    kind: "static" | "dynamic";
+    provenance: string;
+    version?: string;
+    headline?: string;
+    extensionDescription?: string;
+}
+export interface WorkflowCatalogSettings {
+    concurrency: number;
+    modelAliases: Readonly<Record<string, string>>;
+    disabledAgentResources: AgentResourceExclusions;
+    globalSettingsPath: string;
+    projectSettingsPath: string;
+    projectTrusted: boolean;
+    sources: WorkflowSettingsSources;
+}
+export interface WorkflowCatalogContext {
+    cwd: string;
+    projectTrusted: boolean;
+    globalSettingsPath?: string;
+}
 export interface WorkflowCatalog {
     functions: readonly WorkflowCatalogFunction[];
     variables: readonly WorkflowCatalogVariable[];
     modelAliases?: Readonly<Record<string, string>>;
+    modelAliasEntries?: readonly WorkflowCatalogModelAlias[];
+    settings?: WorkflowCatalogSettings;
 }
 export interface WorkflowCatalogIndexFunction {
     name: string;
@@ -530,6 +655,8 @@ export interface WorkflowCatalogIndex {
     functions: readonly WorkflowCatalogIndexFunction[];
     variables: readonly WorkflowCatalogIndexVariable[];
     modelAliases?: Readonly<Record<string, string>>;
+    modelAliasEntries?: readonly WorkflowCatalogModelAlias[];
+    settings?: WorkflowCatalogSettings;
 }
 export interface WorkflowCatalogError {
     error: {
@@ -563,3 +690,4 @@ export interface ValidatedWorkflowLaunch {
     roleNames: readonly string[];
     functionName?: string;
 }
+export {};

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) {
@@ -309,6 +401,39 @@ function workflowCallsWithStructure(program) {
     visit(program, { execution: "sequential", structure: [] });
     return calls.sort((left, right) => left.call.start - right.call.start);
 }
+function memberCall(node, objectName, propertyName) {
+    if (node?.type !== "CallExpression" || node.callee.type !== "MemberExpression" || node.callee.computed || node.callee.object.type !== "Identifier" || node.callee.object.name !== objectName || node.callee.property.type !== "Identifier")
+        return false;
+    return node.callee.property.name === propertyName;
+}
+function mapCallback(node) {
+    if (!memberCall(node, "Promise", "all") && !memberCall(node, "Promise", "allSettled"))
+        return undefined;
+    if (node.type !== "CallExpression")
+        return undefined;
+    const source = node.arguments[0];
+    if (source?.type !== "CallExpression" || source.callee.type !== "MemberExpression" || source.callee.computed || source.callee.property.type !== "Identifier" || !["map", "flatMap"].includes(source.callee.property.name))
+        return undefined;
+    const callback = source.arguments[0];
+    return callback?.type === "ArrowFunctionExpression" || callback?.type === "FunctionExpression" ? callback : undefined;
+}
+function hasUnscopedAgent(node, scoped = false) {
+    const operation = workflowCallKind(node);
+    if (operation === "agent")
+        return !scoped;
+    const nestedScope = scoped || operation === "parallel" || operation === "pipeline";
+    return astChildren(node).some((child) => hasUnscopedAgent(child, nestedScope));
+}
+function validateObviousConcurrentAgentCalls(program) {
+    const visit = (node) => {
+        const callback = mapCallback(node);
+        if (callback && hasUnscopedAgent(callback))
+            fail("INVALID_METADATA", "Promise.all/map agent fan-out cannot prove stable call-site identity; use parallel(...) or pipeline(...)");
+        for (const child of astChildren(node))
+            visit(child);
+    };
+    visit(program);
+}
 function validateDirectPrimitiveReferences(program, name) {
     const visit = (node, parent) => {
         if (node.type === "Identifier" && node.name === name) {
@@ -639,6 +764,7 @@ export function preflight(script, capabilities, schemas = [], metadata = { name:
     for (const [index, schema] of schemas.entries())
         validateSchema(schema, `schema[${String(index)}]`);
     const calls = workflowCalls(program);
+    validateObviousConcurrentAgentCalls(program);
     const phases = calls.filter((call) => call.callee.name === "phase").map((call) => literalString(call.arguments[0])).filter((phase) => phase !== undefined);
     for (const call of calls) {
         const operation = call.callee.name;
@@ -709,7 +835,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/dist/src/workflow-artifacts.d.ts

@@ -0,0 +1,13 @@
+import type { JsonValue } from "./types.js";
+export interface WorkflowArtifact {
+    extension: ".js" | ".json" | ".md";
+    content: string;
+}
+export type WorkflowTui = {
+    stop(): void;
+    start(): void;
+    requestRender(force?: boolean): void;
+};
+export declare function workflowScriptArtifact(script: string): WorkflowArtifact;
+export declare function workflowResultArtifact(value: JsonValue): WorkflowArtifact;
+export declare function openWorkflowArtifact(tui: WorkflowTui, command: string, artifact: WorkflowArtifact): Promise<number | null>;