pi-extensible-workflows 3.0.0 → 3.1.0

package/dist/src/index.d.ts

@@ -6,9 +6,11 @@ export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";
 export { default } from "./host.js";
-export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
+export { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PendingWorkflowDecision, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
-export type { AgentAttempt, AgentBudgetHooks, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentProviderFailure, AgentProviderRecovery, AgentToolCallProgress, SessionInput } from "./agent-execution.js";
+export type { AgentAttempt, AgentBudgetHooks, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentProviderFailure, AgentProviderRecovery, AgentToolCallProgress, AgentSetup, AgentSetupContext, AgentSetupHook, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 export type { DoctorDiagnostic, DoctorFunction, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust } from "./doctor.js";
+export { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";
+export type { CleanupFailure, CleanupRunResult, CleanupSessionReport, DoctorCleanupOptions, DoctorCleanupReport } from "./doctor-cleanup.js";

package/dist/src/index.js

@@ -6,6 +6,7 @@ export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";
 export { default } from "./host.js";
-export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
+export { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
+export { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";

package/dist/src/persistence.d.ts

@@ -39,7 +39,9 @@ export interface BorrowedWorktreeBinding {
     owner: string;
 }
 export declare function projectStorageKey(cwd: string): string;
+export declare function projectSessionsDirectory(cwd: string, home?: string): string;
 export declare function runsDirectory(cwd: string, sessionId: string, home?: string): string;
+export declare function hasLiveSessionLease(cwd: string, sessionId: string, home?: string): Promise<boolean>;
 export declare class SessionLease {
     #private;
     readonly path: string;
@@ -112,6 +114,7 @@ export declare class RunStore {
         sourceRunId: string;
         owner: string;
     }>;
+    validateDeletionWorktrees(): Promise<void>;
     validateBorrowedWorktrees(): Promise<void>;
     validateNamedWorktrees(): Promise<void>;
     ownsWorktree(owner: string): Promise<boolean>;

package/dist/src/persistence.js

@@ -18,8 +18,11 @@ export function projectStorageKey(cwd) {
     const slug = safePart(basename(exact)) || "root";
     return `${slug}-${createHash("sha256").update(exact).digest("hex").slice(0, 12)}`;
 }
+export function projectSessionsDirectory(cwd, home = homedir()) {
+    return join(home, ".pi", "workflows", "projects", projectStorageKey(cwd), "sessions");
+}
 export function runsDirectory(cwd, sessionId, home = homedir()) {
-    return join(home, ".pi", "workflows", "projects", projectStorageKey(cwd), "sessions", safePart(sessionId), "runs");
+    return join(projectSessionsDirectory(cwd, home), safePart(sessionId), "runs");
 }
 const SESSION_OWNER_FILE = "owner.json";
 const SESSION_OWNER_WRITE_GRACE_MS = 30_000;
@@ -43,6 +46,24 @@ async function processAlive(pid, startedAt) {
     }
     return true;
 }
+export async function hasLiveSessionLease(cwd, sessionId, home = homedir()) {
+    const path = join(runsDirectory(cwd, sessionId, home), SESSION_OWNER_FILE);
+    let owner;
+    try {
+        owner = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    if (!owner || typeof owner !== "object" || Array.isArray(owner))
+        throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} has an invalid ownership lease`);
+    const candidate = owner;
+    if (typeof candidate.pid !== "number" || !Number.isInteger(candidate.pid) || candidate.pid < 1 || typeof candidate.token !== "string" || !candidate.token || typeof candidate.startedAt !== "number" || !Number.isFinite(candidate.startedAt))
+        throw new WorkflowError("RUN_OWNED", `Pi session ${sessionId} has an invalid ownership lease`);
+    return processAlive(candidate.pid, candidate.startedAt);
+}
 function sameOwner(left, right) {
     if (!left || typeof left !== "object" || !right || typeof right !== "object")
         return false;
@@ -587,6 +608,33 @@ export class RunStore {
             throw new WorkflowError("WORKTREE_FAILED", `Missing named worktree ${name}`);
         return resolved;
     }
+    async validateDeletionWorktrees() {
+        try {
+            const records = await json(join(this.directory, "worktrees.json"));
+            if (!Array.isArray(records))
+                throw new Error("Worktree records are invalid");
+            const owners = new Set();
+            const paths = new Set();
+            records.forEach((record) => {
+                if (!record || typeof record !== "object" || typeof record.owner !== "string")
+                    throw new Error("Invalid worktree record");
+                const owner = record.owner;
+                if (owners.has(owner))
+                    throw new Error(`Duplicate worktree record for ${owner}`);
+                owners.add(owner);
+                const reference = this.structuralWorktree(owner, record);
+                paths.add(resolve(reference.path));
+            });
+            const entries = await readdir(join(this.directory, "worktrees"), { withFileTypes: true }).catch((error) => { if (error.code === "ENOENT")
+                return []; throw error; });
+            for (const entry of entries)
+                if (!entry.isDirectory() || entry.isSymbolicLink() || !paths.has(resolve(join(this.directory, "worktrees", entry.name))))
+                    throw new Error(`Unrecorded worktree artifact: ${join(this.directory, "worktrees", entry.name)}`);
+        }
+        catch (error) {
+            throw new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+        }
+    }
     async validateBorrowedWorktrees() {
         try {
             const loaded = await this.load();

package/dist/src/registry.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogVariable, WorkflowExtension, WorkflowFunction, WorkflowFunctionContext, WorkflowJournal, WorkflowVariable } from "./types.js";
+import type { JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogModelAlias, WorkflowCatalogVariable, WorkflowExtension, WorkflowFunction, WorkflowFunctionContext, WorkflowJournal, WorkflowModelAlias, WorkflowModelAliasResolverContext, WorkflowRoleDirectoryRegistration, WorkflowVariable } from "./types.js";
 export declare class WorkflowRegistry {
     #private;
     get frozen(): boolean;
@@ -6,9 +6,9 @@ export declare class WorkflowRegistry {
     register(extension: WorkflowExtension): void;
     function(name: string): WorkflowFunction;
     functions(): Readonly<Record<string, WorkflowFunction>>;
-    catalog(): WorkflowCatalog;
-    catalogIndex(): WorkflowCatalogIndex;
-    catalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError;
+    catalog(context?: WorkflowCatalogContext): WorkflowCatalog;
+    catalogIndex(context?: WorkflowCatalogContext): WorkflowCatalogIndex;
+    catalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogModelAlias | WorkflowCatalogError;
     globals(): Readonly<Record<string, {
         name: string;
     }>>;
@@ -18,14 +18,26 @@ export declare class WorkflowRegistry {
         variable: WorkflowVariable;
     }[];
     agentSetupHooks(): readonly RegisteredAgentSetupHook[];
+    roleDirectories(): readonly string[];
+    roleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[];
+    modelAliases(): readonly {
+        name: string;
+        version: string;
+        headline: string;
+        extensionDescription: string;
+        resolve: WorkflowModelAlias["resolve"];
+    }[];
+    resolveModelAliases(context: Readonly<WorkflowModelAliasResolverContext>, shadowed?: ReadonlySet<string>): Promise<Readonly<Record<string, string>>>;
 }
-export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "variables" | "modelAliases" | "resolveModelAliases" | "agentSetupHooks" | "roleDirectories" | "roleDirectoryRegistrations">;
 export declare function resetWorkflowRegistry(): void;
 export declare function beginWorkflowExtensionLoading(): void;
 export declare function loadingRegistry(): WorkflowRegistryApi;
 export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
-export declare function workflowCatalog(): WorkflowCatalog;
-export declare function workflowCatalogIndex(): WorkflowCatalogIndex;
-export declare function workflowCatalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError;
+export declare function workflowCatalog(context?: WorkflowCatalogContext): WorkflowCatalog;
+export declare function workflowCatalogIndex(context?: WorkflowCatalogContext): WorkflowCatalogIndex;
+export declare function workflowCatalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogModelAlias | WorkflowCatalogError;
 export declare function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>>;
-export type { WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogIndexVariable, WorkflowCatalogVariable } from "./types.js";
+export declare function registeredWorkflowRoleDirectories(): readonly string[];
+export declare function registeredWorkflowRoleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[];
+export type { WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogIndexVariable, WorkflowCatalogModelAlias, WorkflowCatalogSettings, WorkflowCatalogVariable, WorkflowRoleDirectoryRegistration } from "./types.js";

package/dist/src/registry.js

@@ -1,13 +1,36 @@
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Value } from "typebox/value";
 import { deepFreeze, fail, jsonValue, object } from "./utils.js";
-import { loadSettings, validateSchema } from "./validation.js";
+import { loadSettings, resolveWorkflowSettings, validateSchema } from "./validation.js";
 const RESERVED_GLOBALS = new Set(["agent", "shell", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function normalizeRoleDirectory(value) {
+    try {
+        if (value instanceof URL) {
+            if (value.protocol !== "file:")
+                fail("INVALID_METADATA", "Workflow role directories require file URLs or absolute filesystem paths");
+            return fileURLToPath(value);
+        }
+        if (typeof value === "string") {
+            if (value.startsWith("file:"))
+                return fileURLToPath(value);
+            if (isAbsolute(value))
+                return value;
+        }
+    }
+    catch (error) {
+        fail("INVALID_METADATA", `Invalid workflow role directory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    fail("INVALID_METADATA", "Workflow role directories require file URLs or absolute filesystem paths");
+}
 export class WorkflowRegistry {
     #extensions = new Set();
     #globals = new Map();
     #hooks = new Map();
+    #roleDirectories = new Map();
+    #modelAliases = new Map();
     #frozen = false;
     get frozen() { return this.#frozen; }
     freeze() { this.#frozen = true; }
@@ -16,13 +39,18 @@ export class WorkflowRegistry {
             fail("REGISTRY_FROZEN", "Workflow extension registration is closed after session_start");
         if (object(extension) && Object.prototype.hasOwnProperty.call(extension, "workflows"))
             fail("INVALID_METADATA", "Separate registered workflow definitions were removed; register a function with input and output schemas instead");
-        if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "agentSetupHooks"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim())
+        if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "modelAliases", "agentSetupHooks", "roleDirectories"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim())
             fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
         const functions = extension.functions ?? {};
         const variables = extension.variables ?? {};
+        const modelAliases = extension.modelAliases ?? {};
         const agentSetupHooks = extension.agentSetupHooks ?? {};
-        if (!object(functions) || !object(variables) || !object(agentSetupHooks) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(agentSetupHooks).length === 0))
-            fail("INVALID_METADATA", "Workflow extensions require functions, variables, or agent setup hooks");
+        const roleDirectoryValues = extension.roleDirectories === undefined ? [] : extension.roleDirectories;
+        if (!Array.isArray(roleDirectoryValues))
+            fail("INVALID_METADATA", "Workflow extension roleDirectories must be an array");
+        const roleDirectories = [...new Set(Array.from(roleDirectoryValues, (value) => normalizeRoleDirectory(value)))];
+        if (!object(functions) || !object(variables) || !object(modelAliases) || !object(agentSetupHooks) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(modelAliases).length === 0 && Object.keys(agentSetupHooks).length === 0 && roleDirectories.length === 0))
+            fail("INVALID_METADATA", "Workflow extensions require functions, variables, model aliases, agent setup hooks, or role directories");
         const names = [...Object.keys(functions), ...Object.keys(variables)];
         if (new Set(names).size !== names.length)
             fail("GLOBAL_COLLISION", "Global name collision inside extension");
@@ -47,16 +75,29 @@ export class WorkflowRegistry {
                 fail("INVALID_METADATA", `Invalid workflow variable: ${name}`);
             validateSchema(variable.schema, `${name} schema`);
         }
+        for (const [name, alias] of Object.entries(modelAliases)) {
+            if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name))
+                fail("INVALID_METADATA", `Invalid model alias name: ${name}`);
+            if (!object(alias) || Object.keys(alias).some((key) => key !== "resolve") || typeof alias.resolve !== "function")
+                fail("INVALID_METADATA", `Invalid model alias resolver: ${name}`);
+            if (this.#modelAliases.has(name))
+                fail("DUPLICATE_NAME", `Model alias already registered: ${name}`);
+        }
         for (const [name, hook] of Object.entries(agentSetupHooks)) {
             if (!IDENTIFIER.test(name) || !object(hook) || Object.keys(hook).some((key) => !["priority", "setup"].includes(key)) || typeof hook.setup !== "function" || hook.priority !== undefined && (typeof hook.priority !== "number" || !Number.isFinite(hook.priority)))
                 fail("INVALID_METADATA", `Invalid agent setup hook: ${name}`);
             if (this.#hooks.has(name))
                 fail("DUPLICATE_NAME", `Agent setup hook already registered: ${name}`);
         }
-        const stored = deepFreeze({ ...extension, functions, variables, agentSetupHooks });
+        const stored = deepFreeze({ ...extension, functions, variables, modelAliases, agentSetupHooks, ...(roleDirectories.length ? { roleDirectories } : {}) });
         this.#extensions.add(stored);
+        for (const directory of roleDirectories)
+            if (!this.#roleDirectories.has(directory))
+                this.#roleDirectories.set(directory, deepFreeze({ path: directory, extension: { version: extension.version, headline: extension.headline, description: extension.description } }));
         for (const name of names)
             this.#globals.set(name, name);
+        for (const [name, alias] of Object.entries(modelAliases))
+            this.#modelAliases.set(name, { name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, resolve: alias.resolve });
         for (const [name, hook] of Object.entries(agentSetupHooks))
             this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
     }
@@ -71,7 +112,7 @@ export class WorkflowRegistry {
     functions() {
         return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.entries(extension.functions ?? {}))));
     }
-    catalog() {
+    catalog(context) {
         const functions = [];
         const variables = [];
         for (const extension of this.#extensions) {
@@ -81,28 +122,53 @@ export class WorkflowRegistry {
                 variables.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: variable.description, schema: structuredClone(variable.schema) });
         }
         let aliases;
+        let settings;
+        let source = "global settings";
         try {
-            aliases = loadSettings().modelAliases;
+            const resolved = context ? resolveWorkflowSettings(context.cwd, context.projectTrusted, context.globalSettingsPath) : undefined;
+            aliases = resolved?.effective.modelAliases ?? loadSettings().modelAliases;
+            if (resolved) {
+                source = resolved.projectTrusted && resolved.sources.modelAliases === resolved.projectSettingsPath ? "trusted project settings" : "global settings";
+                settings = { concurrency: resolved.effective.concurrency, modelAliases: resolved.effective.modelAliases ?? {}, disabledAgentResources: resolved.effective.disabledAgentResources ?? { skills: [], extensions: [] }, globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted: resolved.projectTrusted, sources: resolved.sources };
+            }
         }
         catch {
             aliases = undefined;
         }
+        const staticEntries = Object.keys(aliases ?? {}).map((name) => ({ name, kind: "static", provenance: source }));
+        const dynamicEntries = [...this.#modelAliases.values()].map(({ name, version, headline, extensionDescription }) => ({ name, kind: "dynamic", provenance: `extension: ${headline}`, version, headline, extensionDescription }));
+        const modelAliasEntries = [...staticEntries, ...dynamicEntries].sort((left, right) => left.name.localeCompare(right.name) || left.kind.localeCompare(right.kind) || left.provenance.localeCompare(right.provenance));
         const sort = (left, right) => left.name.localeCompare(right.name);
-        return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), ...(aliases ? { modelAliases: structuredClone(aliases) } : {}) });
+        const catalog = { functions: functions.sort(sort), variables: variables.sort(sort), ...(modelAliasEntries.length ? { modelAliasEntries } : {}) };
+        if (aliases && Object.keys(aliases).length)
+            Object.defineProperty(catalog, "modelAliases", { value: Object.freeze(structuredClone(aliases)), enumerable: false });
+        if (settings) {
+            const publicSettings = { ...settings, modelAliases: Object.keys(aliases ?? {}).length ? {} : settings.modelAliases };
+            Object.defineProperty(catalog, "settings", { value: deepFreeze(publicSettings), enumerable: true });
+        }
+        return deepFreeze(catalog);
     }
-    catalogIndex() {
-        const catalog = this.catalog();
-        return deepFreeze({
+    catalogIndex(context) {
+        const catalog = this.catalog(context);
+        const index = {
             functions: catalog.functions.map(({ name, description, input }) => ({ name, description, input: structuredClone(input) })),
             variables: catalog.variables.map(({ name, description, schema }) => ({ name, description, schema: structuredClone(schema) })),
-            ...(catalog.modelAliases ? { modelAliases: structuredClone(catalog.modelAliases) } : {}),
-        });
+            ...(catalog.modelAliasEntries ? { modelAliasEntries: structuredClone(catalog.modelAliasEntries) } : {}),
+        };
+        if (catalog.modelAliases)
+            Object.defineProperty(index, "modelAliases", { value: Object.freeze(structuredClone(catalog.modelAliases)), enumerable: false });
+        if (catalog.settings)
+            Object.defineProperty(index, "settings", { value: deepFreeze(structuredClone(catalog.settings)), enumerable: true });
+        return deepFreeze(index);
     }
-    catalogDetail(name) {
-        const catalog = this.catalog();
+    catalogDetail(name, context) {
+        const catalog = this.catalog(context);
         const entry = catalog.functions.find((candidate) => candidate.name === name) ?? catalog.variables.find((candidate) => candidate.name === name);
         if (entry)
             return entry;
+        const alias = catalog.modelAliasEntries?.find((candidate) => candidate.name === name);
+        if (alias)
+            return alias;
         return deepFreeze({ error: { code: "NOT_FOUND", name, message: `No registered workflow function or variable is available: ${name}` } });
     }
     globals() {
@@ -131,6 +197,38 @@ export class WorkflowRegistry {
     agentSetupHooks() {
         return [...this.#hooks.values()].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
     }
+    roleDirectories() {
+        return [...this.#roleDirectories.keys()];
+    }
+    roleDirectoryRegistrations() {
+        return [...this.#roleDirectories.values()];
+    }
+    modelAliases() { return [...this.#modelAliases.values()].sort((left, right) => left.name.localeCompare(right.name)); }
+    async resolveModelAliases(context, shadowed = new Set()) {
+        const resolved = {};
+        const isAborted = () => context.signal.aborted;
+        for (const alias of this.modelAliases()) {
+            if (shadowed.has(alias.name))
+                continue;
+            if (isAborted())
+                fail("CANCELLED", `Model alias resolver cancelled: ${alias.name} (${alias.headline})`);
+            let target;
+            try {
+                target = await alias.resolve(Object.freeze({ cwd: context.cwd, projectTrusted: context.projectTrusted, rootModel: Object.freeze({ ...context.rootModel }), knownModels: new Set(context.knownModels), availableModels: new Set(context.availableModels), signal: context.signal }));
+            }
+            catch (error) {
+                if (isAborted() || error instanceof Error && error.name === "AbortError" || typeof error === "object" && error !== null && !Array.isArray(error) && error.code === "CANCELLED")
+                    fail("CANCELLED", `Model alias resolver cancelled: ${alias.name} (${alias.headline})`);
+                fail("CONFIG_ERROR", `Model alias resolver failed for ${alias.name} (${alias.headline}): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (isAborted())
+                fail("CANCELLED", `Model alias resolver cancelled: ${alias.name} (${alias.headline})`);
+            if (typeof target !== "string" || !target.trim())
+                fail("CONFIG_ERROR", `Model alias resolver returned an invalid target for ${alias.name} (${alias.headline})`);
+            resolved[alias.name] = target.trim();
+        }
+        return Object.freeze(resolved);
+    }
 }
 const WORKFLOW_REGISTRY_KEY = Symbol.for("pi-extensible-workflows.workflow-registry");
 const globalRegistry = globalThis;
@@ -141,12 +239,16 @@ function createWorkflowRegistryApi(registry) {
         register: (extension) => { registry.register(extension); },
         function: (name) => registry.function(name),
         functions: () => registry.functions(),
-        catalog: () => registry.catalog(),
-        catalogIndex: () => registry.catalogIndex(),
-        catalogDetail: (name) => registry.catalogDetail(name),
+        catalog: (context) => registry.catalog(context),
+        catalogIndex: (context) => registry.catalogIndex(context),
+        catalogDetail: (name, context) => registry.catalogDetail(name, context),
         globals: () => registry.globals(),
         invokeFunction: (...args) => registry.invokeFunction(...args),
         variables: () => registry.variables(),
+        modelAliases: () => registry.modelAliases(),
+        resolveModelAliases: (...args) => registry.resolveModelAliases(...args),
+        roleDirectories: () => registry.roleDirectories(),
+        roleDirectoryRegistrations: () => registry.roleDirectoryRegistrations(),
         agentSetupHooks: () => registry.agentSetupHooks(),
     };
 }
@@ -163,7 +265,15 @@ export function beginWorkflowExtensionLoading() {
 export function loadingRegistry() { return workflowRegistryHost().api; }
 beginWorkflowExtensionLoading();
 export function registerWorkflowExtension(extension) { loadingRegistry().register(extension); }
-export function workflowCatalog() { return loadingRegistry().catalog(); }
-export function workflowCatalogIndex() { return loadingRegistry().catalogIndex(); }
-export function workflowCatalogDetail(name) { return loadingRegistry().catalogDetail(name); }
+export function workflowCatalog(context) { return loadingRegistry().catalog(context); }
+export function workflowCatalogIndex(context) { return loadingRegistry().catalogIndex(context); }
+export function workflowCatalogDetail(name, context) { return loadingRegistry().catalogDetail(name, context); }
 export function registeredWorkflowFunctions() { return loadingRegistry().functions(); }
+export function registeredWorkflowRoleDirectories() {
+    const directories = loadingRegistry().roleDirectories;
+    return typeof directories === "function" ? directories() : [];
+}
+export function registeredWorkflowRoleDirectoryRegistrations() {
+    const registrations = loadingRegistry().roleDirectoryRegistrations;
+    return typeof registrations === "function" ? registrations() : [];
+}

package/dist/src/session-inspector.js

@@ -296,8 +296,10 @@ function detailLines(workflow) {
                 `Hooks: ${attempt.setup.hookNames.join(", ") || "(none)"}`,
                 `Effective: model=${attempt.setup.model.provider}/${attempt.setup.model.model}${attempt.setup.model.thinking ? `:${attempt.setup.model.thinking}` : ""} tools=${attempt.setup.tools.join(",") || "(none)"} cwd=${attempt.setup.cwd}`,
                 ...(attempt.setup.disabledAgentResources ? [
-                    `Disabled skills: ${attempt.setup.disabledAgentResources.skills.join(", ") || "(none)"}`,
-                    `Disabled extensions: ${attempt.setup.disabledAgentResources.extensions.join(", ") || "(none)"}`,
+                    `Configured skill patterns: ${attempt.setup.disabledAgentResources.skills.join(", ") || "(none)"}`,
+                    `Excluded skills: ${attempt.setup.disabledAgentResources.excludedSkills?.join(", ") || "(none)"}`,
+                    `Configured extension patterns: ${attempt.setup.disabledAgentResources.extensions.join(", ") || "(none)"}`,
+                    `Excluded extensions: ${attempt.setup.disabledAgentResources.excludedExtensions?.join(", ") || "(none)"}`,
                     `Unmatched skills: ${attempt.setup.disabledAgentResources.unmatchedSkills.join(", ") || "(none)"}`,
                     `Unmatched extensions: ${attempt.setup.disabledAgentResources.unmatchedExtensions.join(", ") || "(none)"}`,
                 ] : []),

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[];
     };
@@ -294,9 +329,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 +396,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 +475,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 +611,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 +654,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 +689,4 @@ export interface ValidatedWorkflowLaunch {
     roleNames: readonly string[];
     functionName?: string;
 }
+export {};