pi-extensible-workflows 2.0.0 → 3.1.0

package/dist/src/registry.js

@@ -0,0 +1,279 @@
+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, 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; }
+    register(extension) {
+        if (this.#frozen)
+            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", "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 ?? {};
+        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");
+        for (const name of names) {
+            if (!IDENTIFIER.test(name) || name.startsWith("__pi_extensible_workflows_"))
+                fail("INVALID_METADATA", `Invalid global name: ${name}`);
+            if (RESERVED_GLOBALS.has(name))
+                fail("GLOBAL_COLLISION", `Global name is reserved: ${name}`);
+            if (this.#globals.has(name))
+                fail("GLOBAL_COLLISION", `Global name is already registered: ${name}`);
+        }
+        for (const [name, fn] of Object.entries(functions)) {
+            if (!object(fn) || Object.keys(fn).some((key) => !["description", "input", "output", "run"].includes(key)) || typeof fn.description !== "string" || !fn.description.trim() || typeof fn.run !== "function")
+                fail("INVALID_METADATA", `Invalid workflow function: ${name}`);
+            validateSchema(fn.input, `${name} input`);
+            validateSchema(fn.output, `${name} output`);
+            if (fn.input.type !== "object")
+                fail("INVALID_SCHEMA", `${name} input must describe one object`);
+        }
+        for (const [name, variable] of Object.entries(variables)) {
+            if (!object(variable) || Object.keys(variable).some((key) => !["description", "schema", "resolve"].includes(key)) || typeof variable.description !== "string" || !variable.description.trim() || typeof variable.resolve !== "function")
+                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, 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 });
+    }
+    function(name) {
+        if (!IDENTIFIER.test(name))
+            fail("MISSING_WORKFLOW", `Registered functions require an unqualified name: ${name}`);
+        const fn = [...this.#extensions].find((extension) => extension.functions?.[name])?.functions?.[name];
+        if (!fn)
+            fail("MISSING_WORKFLOW", `Registered function is unavailable: ${name}; the separate registered-workflow format was removed`);
+        return fn;
+    }
+    functions() {
+        return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.entries(extension.functions ?? {}))));
+    }
+    catalog(context) {
+        const functions = [];
+        const variables = [];
+        for (const extension of this.#extensions) {
+            for (const [name, fn] of Object.entries(extension.functions ?? {}))
+                functions.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: fn.description, input: structuredClone(fn.input), output: structuredClone(fn.output) });
+            for (const [name, variable] of Object.entries(extension.variables ?? {}))
+                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 {
+            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);
+        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(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.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, 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() {
+        return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.keys(extension.functions ?? {}).map((name) => [name, { name }]))));
+    }
+    async invokeFunction(name, input, context, path, journal) {
+        const fn = this.function(name);
+        if (!object(input) || !jsonValue(input) || !Value.Check(fn.input, input))
+            fail("RESULT_INVALID", `Invalid input for ${name}`);
+        const replayed = journal.get(path);
+        if (replayed !== undefined) {
+            if (!jsonValue(replayed) || !Value.Check(fn.output, replayed))
+                fail("RESULT_INVALID", `Invalid replay for ${name}`);
+            return structuredClone(replayed);
+        }
+        const result = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, invoke: context.invoke, agent: context.agent, shell: context.shell, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
+        if (!jsonValue(result) || !Value.Check(fn.output, result))
+            fail("RESULT_INVALID", `Invalid output from ${name}`);
+        const stored = structuredClone(result);
+        journal.put(path, stored);
+        return structuredClone(stored);
+    }
+    variables() {
+        return [...this.#extensions].flatMap((extension) => Object.entries(extension.variables ?? {}).map(([name, variable]) => ({ name, variable })));
+    }
+    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;
+function createWorkflowRegistryApi(registry) {
+    return {
+        get frozen() { return registry.frozen; },
+        freeze: () => { registry.freeze(); },
+        register: (extension) => { registry.register(extension); },
+        function: (name) => registry.function(name),
+        functions: () => registry.functions(),
+        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(),
+    };
+}
+function workflowRegistryHost() {
+    return globalRegistry[WORKFLOW_REGISTRY_KEY] ??= { api: createWorkflowRegistryApi(new WorkflowRegistry()) };
+}
+export function resetWorkflowRegistry() {
+    workflowRegistryHost().api = createWorkflowRegistryApi(new WorkflowRegistry());
+}
+export function beginWorkflowExtensionLoading() {
+    if (workflowRegistryHost().api.frozen)
+        resetWorkflowRegistry();
+}
+export function loadingRegistry() { return workflowRegistryHost().api; }
+beginWorkflowExtensionLoading();
+export function registerWorkflowExtension(extension) { loadingRegistry().register(extension); }
+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

@@ -223,7 +223,7 @@ export async function loadSessionReport(path, home = homedir()) {
         const args = call.arguments;
         const agents = loaded ? await Promise.all(loaded.run.agents.map(agentReport)) : [];
         const models = mergedModels(agents.flatMap(({ attempts }) => attempts.map(({ models: attemptModels }) => attemptModels)));
-        const name = typeof args.name === "string" ? args.name : typeof args.workflow === "string" ? args.workflow : loaded?.run.workflowName ?? "workflow";
+        const name = loaded?.run.workflowName ?? (typeof args.workflow === "string" ? args.workflow : typeof args.name === "string" ? args.name : "workflow");
         const description = typeof args.description === "string" ? args.description : loaded?.snapshot.metadata.description;
         const script = typeof args.script === "string" && args.script.trim() ? args.script : loaded?.snapshot.script;
         let staticCalls = [];
@@ -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)"}`,
                 ] : []),