@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/src/registry.ts

@@ -0,0 +1,321 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Value } from "typebox/value";
+import type { AgentAttemptAction, JsonSchema, JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogModelAlias, WorkflowExtension, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowFunction, WorkflowFunctionContext, WorkflowFunctionSource, WorkflowJournal, WorkflowModelAlias, WorkflowModelAliasResolverContext, WorkflowRoleDirectoryRegistration } from "./types.js";
+import type { SubagentRunRequest, SubagentStatus } from "../subagents/src/contracts.js";
+import { byPriorityThenName, deepFreeze, errorCode, errorText, fail, jsonValue, MODEL_ALIAS_NAME, object, validWorkflowExtensionNamespace } from "./utils.js";
+import { loadSettings, resolveWorkflowSettings, validateSchema } from "./validation.js";
+import { canonicalPath } from "./paths.js";
+import { isCorePackageName } from "./package-identity.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-]+)*)?$/;
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+export type SubagentStatusObserver = (status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void;
+
+function normalizeRoleDirectory(value: unknown): string {
+  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: ${errorText(error)}`);
+  }
+  fail("INVALID_METADATA", "Workflow role directories require file URLs or absolute filesystem paths");
+}
+function isBuiltinRoleDirectory(path: string): boolean {
+  const canonical = canonicalPath(path);
+  const starterDirectory = dirname(canonical);
+  if (basename(canonical) !== "roles" || basename(starterDirectory) !== "starter") return false;
+  const distributionDirectory = dirname(starterDirectory);
+  const packageRoot = basename(distributionDirectory) === "dist" ? dirname(distributionDirectory) : distributionDirectory;
+  try {
+    const metadata: unknown = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+    return object(metadata) && isCorePackageName(metadata.name);
+  } catch { return false; }
+}
+
+function catalogSchema(schema: unknown, at: string): JsonSchema {
+  validateSchema(schema, at);
+  return structuredClone(schema);
+}
+export class WorkflowRegistry {
+  readonly #extensions = new Set<Readonly<WorkflowExtension>>();
+  readonly #functionSources = new Map<string, WorkflowFunctionSource>();
+  readonly #globals = new Map<string, string>();
+  readonly #hooks = new Map<string, RegisteredAgentSetupHook>();
+  readonly #agentAttemptActions = new Map<string, AgentAttemptAction>();
+  readonly #roleDirectories = new Map<string, WorkflowRoleDirectoryRegistration>();
+  readonly #modelAliases = new Map<string, { name: string; version: string; headline: string; resolve: WorkflowModelAlias["resolve"] }>();
+  readonly #settingsValidators = new Set<{ headline: string; validate: NonNullable<WorkflowExtension["validateSettings"]> }>();
+  #frozen = false;
+  #subagentStatusObserver: SubagentStatusObserver | undefined;
+
+  get frozen(): boolean { return this.#frozen; }
+  freeze(): void { this.#frozen = true; }
+  setSubagentStatusObserver(observer: SubagentStatusObserver | undefined): void { this.#subagentStatusObserver = observer; }
+  observeSubagentStatus(status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>): void { this.#subagentStatusObserver?.(status, request); }
+
+  register(extension: WorkflowExtension): void {
+    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", "source", "dependencies", "validateSettings", "functions", "modelAliases", "agentSetupHooks", "agentAttemptActions", "roleDirectories"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version and non-empty headline");
+    const functions = extension.functions ?? {};
+    const modelAliases = extension.modelAliases ?? {};
+    const agentSetupHooks = extension.agentSetupHooks ?? {};
+    const agentAttemptActions = extension.agentAttemptActions ?? {};
+    const source = extension.source;
+    const dependencyValues = extension.dependencies;
+    const dependencies: readonly string[] = dependencyValues ?? [];
+    const validateSettings = extension.validateSettings;
+    if (validateSettings !== undefined && typeof validateSettings !== "function") fail("INVALID_METADATA", "Workflow extension validateSettings must be a function");
+    if (source !== undefined && (typeof source !== "string" || !source.trim())) fail("INVALID_METADATA", "Workflow extension source must be a non-empty module URL");
+    if (dependencyValues !== undefined && (!Array.isArray(dependencyValues) || dependencyValues.some((dependency) => typeof dependency !== "string" || dependency.trim() !== dependency || !PACKAGE_NAME.test(dependency)) || new Set(dependencyValues).size !== dependencyValues.length)) fail("INVALID_METADATA", "Workflow extension dependencies must be unique, non-empty package names");
+    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(modelAliases) || !object(agentSetupHooks) || !object(agentAttemptActions) || (Object.keys(functions).length === 0 && Object.keys(modelAliases).length === 0 && Object.keys(agentSetupHooks).length === 0 && Object.keys(agentAttemptActions).length === 0 && roleDirectories.length === 0 && validateSettings === undefined)) fail("INVALID_METADATA", "Workflow extensions require functions, model aliases, agent setup hooks, agent attempt actions, role directories, or a settings validator");
+    const names = Object.keys(functions);
+    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, alias] of Object.entries(modelAliases)) {
+      if (!MODEL_ALIAS_NAME.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}`);
+    }
+    for (const [name, action] of Object.entries(agentAttemptActions)) {
+      if (!IDENTIFIER.test(name) || !object(action) || Object.keys(action).some((key) => !["label", "visible", "run", "visibleStandalone", "runStandalone"].includes(key)) || typeof action.label !== "string" || !action.label.trim() || typeof action.visible !== "function" || typeof action.run !== "function" || action.visibleStandalone !== undefined && typeof action.visibleStandalone !== "function" || action.runStandalone !== undefined && typeof action.runStandalone !== "function") fail("INVALID_METADATA", `Invalid agent attempt action: ${name}`);
+      if ((action.visibleStandalone !== undefined) !== (action.runStandalone !== undefined)) fail("INVALID_METADATA", `Standalone agent attempt actions require visibleStandalone and runStandalone: ${name}`);
+      if (this.#agentAttemptActions.has(name)) fail("DUPLICATE_NAME", `Agent attempt action already registered: ${name}`);
+    }
+    const stored = deepFreeze({ ...extension, functions, modelAliases, agentSetupHooks, agentAttemptActions, ...(roleDirectories.length ? { roleDirectories } : {}) });
+    if (source !== undefined) for (const name of names) this.#functionSources.set(name, Object.freeze({ module: source, export: "default", dependencies: Object.freeze([...dependencies]) }));
+    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 }, ...(isBuiltinRoleDirectory(directory) ? { builtin: true as const } : {}) }));
+    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, resolve: alias.resolve });
+    for (const [name, hook] of Object.entries(agentSetupHooks)) this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
+    for (const [name, action] of Object.entries(agentAttemptActions)) this.#agentAttemptActions.set(name, action);
+    if (validateSettings !== undefined) this.#settingsValidators.add({ headline: extension.headline, validate: validateSettings });
+  }
+
+  function(name: string): WorkflowFunction {
+    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(): Readonly<Record<string, WorkflowFunction>> {
+    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.entries(extension.functions ?? {}))));
+  }
+  functionSources(): Readonly<Record<string, WorkflowFunctionSource>> {
+    return Object.freeze(Object.fromEntries(this.#functionSources));
+  }
+
+  catalog(context?: WorkflowCatalogContext): WorkflowCatalog {
+    const functions: WorkflowCatalogFunction[] = [];
+    for (const extension of this.#extensions) {
+      for (const [name, fn] of Object.entries(extension.functions ?? {})) functions.push({ name, version: extension.version, headline: extension.headline, description: fn.description, input: catalogSchema(fn.input, `${name} input`), output: catalogSchema(fn.output, `${name} output`) });
+    }
+    let aliases: Readonly<Record<string, string>> | undefined;
+    let settings: WorkflowCatalog["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.sources.skills, resolved.sources.extensions, resolved.sources.tools].some((path) => path === resolved.projectSettingsPath) ? "trusted project settings" : "global settings"; settings = { concurrency: resolved.effective.concurrency, backgroundWidget: resolved.effective.backgroundWidget ?? true, modelAliases: resolved.effective.modelAliases ?? {}, skills: resolved.effective.skills ?? [], extensions: Array.isArray(resolved.effective.extensions) ? resolved.effective.extensions : [], tools: resolved.effective.tools ?? [], ...(resolved.effective.extensionSettings === undefined ? {} : { extensionSettings: resolved.effective.extensionSettings }), ...(resolved.effective.worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand: resolved.effective.worktreePostCreateCommand }), globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted: resolved.projectTrusted, sources: resolved.sources }; }
+    } catch { aliases = undefined; }
+    const staticEntries: WorkflowCatalogModelAlias[] = Object.keys(aliases ?? {}).map((name) => ({ name, kind: "static", provenance: source }));
+    const dynamicEntries: WorkflowCatalogModelAlias[] = [...this.#modelAliases.values()].map(({ name, version, headline }) => ({ name, kind: "dynamic", provenance: `extension: ${headline}`, version, headline }));
+    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: { name: string }, right: { name: string }) => left.name.localeCompare(right.name);
+    const catalog: WorkflowCatalog = { functions: functions.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?: WorkflowCatalogContext): WorkflowCatalogIndex {
+    const catalog = this.catalog(context);
+    let modelAliasEntries: WorkflowCatalogModelAlias[] | undefined;
+    if (catalog.modelAliasEntries !== undefined) {
+      const winningEntries = new Map<string, WorkflowCatalogModelAlias>();
+      for (const entry of catalog.modelAliasEntries) {
+        if (!winningEntries.has(entry.name) || entry.kind === "static") winningEntries.set(entry.name, entry);
+      }
+      modelAliasEntries = [...winningEntries.values()];
+    }
+    const index: WorkflowCatalogIndex = {
+      functions: catalog.functions.map(({ name, description, input }) => ({ name, description, input: structuredClone(input) })),
+      ...(modelAliasEntries ? { modelAliasEntries: structuredClone(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: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogModelAlias | WorkflowCatalogError {
+    const catalog = this.catalog(context);
+    const entry = catalog.functions.find((candidate) => candidate.name === name);
+    if (entry) return entry;
+    const alias = catalog.modelAliasEntries?.find((candidate) => candidate.name === name && candidate.kind === "static")
+      ?? catalog.modelAliasEntries?.find((candidate) => candidate.name === name);
+    if (alias) return alias;
+    return deepFreeze({ error: { code: "NOT_FOUND", name, message: `No registered workflow function is available: ${name}` } });
+  }
+
+  globals(): Readonly<Record<string, { name: string }>> {
+    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.keys(extension.functions ?? {}).map((name) => [name, { name }]))));
+  }
+  validateExtensionSettings(settings: Readonly<WorkflowExtensionSettings> | undefined, context: WorkflowExtensionSettingsValidatorContext): void {
+    const effectiveSettings = settings ?? Object.freeze({});
+    if (!jsonValue(effectiveSettings) || !object(effectiveSettings)) fail("INVALID_SETTINGS", "Workflow extension settings must be a JSON object");
+    const unsafeNamespace = Object.keys(effectiveSettings).find((namespace) => !validWorkflowExtensionNamespace(namespace));
+    if (unsafeNamespace !== undefined) fail("INVALID_SETTINGS", `Workflow extension settings contains an invalid namespace: ${unsafeNamespace}`);
+    const frozenSettings = deepFreeze(structuredClone(effectiveSettings));
+    for (const { headline, validate } of this.#settingsValidators) {
+      try { validate(frozenSettings, Object.freeze({ ...context })); }
+      catch (error) {
+        const location = context.source === "role" && context.role ? `role ${context.role}` : context.source;
+        fail("INVALID_SETTINGS", `Invalid extension settings (${headline}; ${location}): ${errorText(error)}`);
+      }
+    }
+  }
+  async invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue> {
+    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: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, settings: deepFreeze(structuredClone(context.settings)), 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);
+  }
+
+  agentSetupHooks(): readonly RegisteredAgentSetupHook[] {
+    return [...this.#hooks.values()].sort(byPriorityThenName);
+  }
+  agentAttemptActions(): Readonly<Record<string, AgentAttemptAction>> { return Object.freeze(Object.fromEntries(this.#agentAttemptActions.entries())); }
+  roleDirectories(): readonly string[] {
+    return [...this.#roleDirectories.keys()];
+  }
+  roleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[] {
+    return [...this.#roleDirectories.values()];
+  }
+  modelAliases(): readonly { name: string; version: string; headline: string; resolve: WorkflowModelAlias["resolve"] }[] { return [...this.#modelAliases.values()].sort((left, right) => left.name.localeCompare(right.name)); }
+  async resolveModelAliases(context: Readonly<WorkflowModelAliasResolverContext>, shadowed: ReadonlySet<string> = new Set()): Promise<Readonly<Record<string, string>>> {
+    const resolved: Record<string, string> = {};
+    const isAborted = (): boolean => 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: unknown;
+      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" || errorCode(error) === "CANCELLED") fail("CANCELLED", `Model alias resolver cancelled: ${alias.name} (${alias.headline})`);
+        fail("CONFIG_ERROR", `Model alias resolver failed for ${alias.name} (${alias.headline}): ${errorText(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);
+  }
+}
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "functionSources" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "validateExtensionSettings" | "modelAliases" | "resolveModelAliases" | "agentSetupHooks" | "agentAttemptActions" | "roleDirectories" | "roleDirectoryRegistrations" | "setSubagentStatusObserver" | "observeSubagentStatus">;
+interface WorkflowRegistryHost { api: WorkflowRegistryApi; activeHosts: number }
+const WORKFLOW_REGISTRY_KEY = Symbol.for("pi-extensible-workflows.workflow-registry");
+const globalRegistry = globalThis as typeof globalThis & Record<symbol, WorkflowRegistryHost | undefined>;
+function createWorkflowRegistryApi(registry: WorkflowRegistry): WorkflowRegistryApi {
+  return {
+    get frozen() { return registry.frozen; },
+    freeze: () => { registry.freeze(); },
+    setSubagentStatusObserver: (observer) => { registry.setSubagentStatusObserver(observer); },
+    observeSubagentStatus: (status, request) => { registry.observeSubagentStatus(status, request); },
+    register: (extension) => { registry.register(extension); },
+    function: (name) => registry.function(name),
+    functions: () => registry.functions(),
+    functionSources: () => registry.functionSources(),
+    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),
+    validateExtensionSettings: (...args) => { registry.validateExtensionSettings(...args); },
+    modelAliases: () => registry.modelAliases(),
+    resolveModelAliases: (...args) => registry.resolveModelAliases(...args),
+    roleDirectories: () => registry.roleDirectories(),
+    roleDirectoryRegistrations: () => registry.roleDirectoryRegistrations(),
+    agentSetupHooks: () => registry.agentSetupHooks(),
+    agentAttemptActions: () => registry.agentAttemptActions(),
+  };
+}
+function workflowRegistryHost(): WorkflowRegistryHost {
+  return globalRegistry[WORKFLOW_REGISTRY_KEY] ??= { api: createWorkflowRegistryApi(new WorkflowRegistry()), activeHosts: 0 };
+}
+export function resetWorkflowRegistry(): void {
+  workflowRegistryHost().api = createWorkflowRegistryApi(new WorkflowRegistry());
+}
+export function resetWorkflowRegistryIfIdle(): void {
+  if (workflowRegistryHost().activeHosts === 0) resetWorkflowRegistry();
+}
+export function beginWorkflowExtensionLoading(): void {
+  const host = workflowRegistryHost();
+  if (host.api.frozen && host.activeHosts === 0) resetWorkflowRegistry();
+}
+export function retainWorkflowRegistry(): () => void {
+  const host = workflowRegistryHost();
+  host.activeHosts += 1;
+  let retained = true;
+  return () => {
+    if (!retained) return;
+    retained = false;
+    host.activeHosts -= 1;
+    if (host.activeHosts === 0) resetWorkflowRegistry();
+  };
+}
+export function loadingRegistry(): WorkflowRegistryApi { return workflowRegistryHost().api; }
+beginWorkflowExtensionLoading();
+export function registerWorkflowExtension(extension: WorkflowExtension): void { loadingRegistry().register(extension); }
+export function workflowCatalog(context?: WorkflowCatalogContext): WorkflowCatalog { return loadingRegistry().catalog(context); }
+export function workflowCatalogIndex(context?: WorkflowCatalogContext): WorkflowCatalogIndex { return loadingRegistry().catalogIndex(context); }
+export function workflowCatalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogModelAlias | WorkflowCatalogError { return loadingRegistry().catalogDetail(name, context); }
+export function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>> { return loadingRegistry().functions(); }
+export function registeredWorkflowFunctionSources(): Readonly<Record<string, WorkflowFunctionSource>> {
+  const sources = loadingRegistry().functionSources;
+  return typeof sources === "function" ? sources() : {};
+}
+export function registeredWorkflowRoleDirectories(): readonly string[] {
+  const directories = loadingRegistry().roleDirectories;
+  return typeof directories === "function" ? directories() : [];
+}
+export function registeredWorkflowRoleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[] {
+  const registrations = loadingRegistry().roleDirectoryRegistrations;
+  return typeof registrations === "function" ? registrations() : [];
+}
+
+export type { WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogModelAlias, WorkflowCatalogSettings, WorkflowRoleDirectoryRegistration } from "./types.js";

package/src/retention.ts

@@ -0,0 +1,178 @@
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { HARD_TERMINAL_RUN_STATES, WorkflowError, type LaunchSnapshot, type WorkflowRetentionSettings } from "./types.js";
+import { acquireSessionLease, listPersistedSessionIds, listRunIds, RunStore, type BorrowedWorktreeBinding, type PersistedRun, type SessionLease } from "./persistence.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REQUIRED_FILES = new Set(["workflow.js", "state.json", "snapshot.json", "journal.json", "ownership.json", "worktrees.json", "borrowed-worktrees.json", "system-prompts.json"]);
+const OPTIONAL_FILES = new Set(["result.json", "summary.json"]);
+const REQUIRED_DIRECTORIES = new Set(["worktrees", ".system-prompts"]);
+
+type StoredRun = { sessionId: string; runId: string; store: RunStore; run: PersistedRun; stateMtimeMs: number; dependencies: readonly string[] };
+
+export interface RetentionCleanupOptions {
+  cwd: string;
+  sessionId: string;
+  home?: string;
+  allSessions?: boolean;
+  retention: Readonly<WorkflowRetentionSettings>;
+  now?: number;
+}
+
+export interface RetentionCleanupReport {
+  candidates: readonly string[];
+  deleted: readonly string[];
+}
+
+async function validateInventory(store: RunStore, loaded: { run: PersistedRun; snapshot: Readonly<LaunchSnapshot> }): Promise<void> {
+  const entries = await readdir(store.directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (REQUIRED_DIRECTORIES.has(entry.name)) {
+      if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error(`Run artifact is not a regular directory: ${join(store.directory, entry.name)}`);
+      continue;
+    }
+    if (!REQUIRED_FILES.has(entry.name) && !OPTIONAL_FILES.has(entry.name)) throw new Error(`Run inventory contains an unrecognized artifact: ${join(store.directory, entry.name)}`);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error(`Run artifact is not a regular file: ${join(store.directory, entry.name)}`);
+  }
+  for (const name of REQUIRED_FILES) {
+    const entry = await lstat(join(store.directory, name));
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error(`Run artifact is not a regular file: ${join(store.directory, name)}`);
+  }
+  if (loaded.run.state === "completed") {
+    const result = await lstat(join(store.directory, "result.json"));
+    if (!result.isFile() || result.isSymbolicLink()) throw new Error(`Run artifact is not a regular file: ${join(store.directory, "result.json")}`);
+  }
+  if (await readFile(join(store.directory, "workflow.js"), "utf8") !== loaded.snapshot.script) throw new Error("Persisted workflow source does not match its launch snapshot");
+}
+
+/** The runs this run cannot outlive: its parent, its retry lineage, and every run it borrows a named worktree from. */
+export function runDependencyIds(run: Pick<PersistedRun, "parentRunId" | "retry">, borrowed: readonly BorrowedWorktreeBinding[]): string[] {
+  const dependencies = new Set<string>();
+  if (run.parentRunId !== undefined) dependencies.add(run.parentRunId);
+  if (run.retry) {
+    dependencies.add(run.retry.sourceRunId);
+    dependencies.add(run.retry.lineageRootRunId);
+  }
+  for (const binding of borrowed) dependencies.add(binding.sourceRunId);
+  return [...dependencies];
+}
+
+async function scanRun(cwd: string, sessionId: string, runId: string, home: string): Promise<StoredRun> {
+  const store = new RunStore(cwd, sessionId, runId, home);
+  const loaded = await store.load();
+  await validateInventory(store, loaded);
+  await store.loadSummary();
+  await store.loadOwnership();
+  await store.systemPrompts();
+  await store.validateDeletionWorktrees();
+  await store.validateBorrowedWorktrees();
+  if (loaded.run.retry) await store.validateRetrySource();
+  const stateMtimeMs = (await stat(join(store.directory, "state.json"))).mtimeMs;
+  const dependencies = runDependencyIds(loaded.run, await store.borrowedWorktrees());
+  if (dependencies.includes(runId)) throw new Error(`Run ${runId} depends on itself`);
+  return { sessionId, runId, store, run: loaded.run, stateMtimeMs, dependencies };
+}
+
+async function scanSession(cwd: string, sessionId: string, home: string): Promise<StoredRun[]> {
+  const runs: StoredRun[] = [];
+  for (const runId of await listRunIds(cwd, sessionId, home)) runs.push(await scanRun(cwd, sessionId, runId, home));
+  return runs;
+}
+
+function runKey(sessionId: string, runId: string): string { return `${sessionId}\0${runId}`; }
+
+function validateDependencies(runs: readonly StoredRun[]): void {
+  const byKey = new Map(runs.map((run) => [runKey(run.sessionId, run.runId), run]));
+  for (const run of runs) for (const dependency of run.dependencies) if (!byKey.has(runKey(run.sessionId, dependency))) throw new Error(`Run ${run.runId} depends on missing run ${dependency}`);
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (sessionId: string, runId: string): void => {
+    const key = runKey(sessionId, runId);
+    if (visiting.has(key)) throw new Error("Persisted run dependency cycle prevents safe cleanup");
+    if (visited.has(key)) return;
+    visiting.add(key);
+    for (const dependency of byKey.get(key)?.dependencies ?? []) visit(sessionId, dependency);
+    visiting.delete(key);
+    visited.add(key);
+  };
+  for (const run of runs) visit(run.sessionId, run.runId);
+}
+
+function eligibleRuns(runs: readonly StoredRun[], retention: Readonly<WorkflowRetentionSettings>, now: number): Set<string> {
+  const terminal = runs.filter(({ run }) => HARD_TERMINAL_RUN_STATES.has(run.state));
+  const eligible = new Set<string>();
+  if (retention.olderThanDays !== undefined) {
+    const cutoffMs = now - retention.olderThanDays * DAY_MS;
+    if (!Number.isFinite(cutoffMs)) throw new Error("Retention olderThanDays produces an unrepresentable cutoff");
+    for (const run of terminal) if (run.stateMtimeMs < cutoffMs) eligible.add(runKey(run.sessionId, run.runId));
+  }
+  if (retention.maxTerminalRuns !== undefined) {
+    const newest = [...terminal].sort((left, right) => right.stateMtimeMs - left.stateMtimeMs || right.runId.localeCompare(left.runId));
+    for (const run of newest.slice(retention.maxTerminalRuns)) eligible.add(runKey(run.sessionId, run.runId));
+  }
+  return eligible;
+}
+
+function cleanupOrder(runs: readonly StoredRun[], candidates: ReadonlySet<string>): readonly StoredRun[] {
+  const remaining = new Set(candidates);
+  const ordered: StoredRun[] = [];
+  while (remaining.size) {
+    const next = runs.find((run) => remaining.has(runKey(run.sessionId, run.runId)) && !runs.some((child) => remaining.has(runKey(child.sessionId, child.runId)) && child.sessionId === run.sessionId && child.dependencies.includes(run.runId)));
+    if (!next) throw new Error("Dependency cycle prevents safe cleanup");
+    ordered.push(next);
+    remaining.delete(runKey(next.sessionId, next.runId));
+  }
+  return ordered;
+}
+
+async function recheck(run: StoredRun): Promise<void> {
+  const before = await stat(join(run.store.directory, "state.json"));
+  const loaded = await run.store.load();
+  const after = await stat(join(run.store.directory, "state.json"));
+  if (loaded.run.id !== run.runId || !HARD_TERMINAL_RUN_STATES.has(loaded.run.state) || before.mtimeMs !== after.mtimeMs || after.mtimeMs !== run.stateMtimeMs) throw new Error(`Retention candidate ${run.runId} changed before deletion`);
+}
+async function releaseLeases(leases: SessionLease[]): Promise<void> {
+  const releases = await Promise.allSettled(leases.reverse().map((lease) => lease.release()));
+  for (const release of releases) if (release.status === "rejected") throw release.reason;
+}
+
+export async function retainTerminalRuns(options: RetentionCleanupOptions): Promise<RetentionCleanupReport> {
+  const home = resolve(options.home ?? homedir());
+  const cwd = resolve(options.cwd);
+  const now = options.now ?? Date.now();
+  if (!Number.isFinite(now)) throw new Error("Retention start time is invalid");
+  if (options.retention.olderThanDays === undefined && options.retention.maxTerminalRuns === undefined) return { candidates: [], deleted: [] };
+  const sessionIds = options.allSessions ? [...new Set([...(await listPersistedSessionIds(cwd, home)), options.sessionId])] : [options.sessionId];
+  const leases: SessionLease[] = [];
+  const cleanableSessions: string[] = [];
+  try {
+    for (const sessionId of sessionIds) {
+      if (sessionId === options.sessionId) { cleanableSessions.push(sessionId); continue; }
+      try { leases.push(await acquireSessionLease(cwd, sessionId, home)); cleanableSessions.push(sessionId); }
+      catch (error) { if (error instanceof WorkflowError && error.code === "RUN_OWNED") continue; throw error; }
+    }
+    const runs: StoredRun[] = [];
+    for (const sessionId of cleanableSessions) runs.push(...await scanSession(cwd, sessionId, home));
+    validateDependencies(runs);
+    const eligible = eligibleRuns(runs, options.retention, now);
+    const protectedRuns = new Set<string>();
+    const protect = (sessionId: string, runId: string): void => {
+      const key = runKey(sessionId, runId);
+      if (protectedRuns.has(key)) return;
+      protectedRuns.add(key);
+      for (const dependency of runs.find((run) => run.sessionId === sessionId && run.runId === runId)?.dependencies ?? []) protect(sessionId, dependency);
+    };
+    for (const run of runs) if (!eligible.has(runKey(run.sessionId, run.runId))) protect(run.sessionId, run.runId);
+    const candidates = new Set([...eligible].filter((key) => !protectedRuns.has(key)));
+    const deleted: string[] = [];
+    for (const run of cleanupOrder(runs, candidates)) {
+      await recheck(run);
+      await run.store.delete(true);
+      deleted.push(run.runId);
+    }
+    return { candidates: [...candidates].map((key) => key.slice(key.indexOf("\0") + 1)), deleted };
+  } finally {
+    await releaseLeases(leases);
+  }
+}