pi-extensible-workflows 2.0.0 → 3.0.0

package/src/persistence.ts

@@ -5,20 +5,13 @@ import { access, link, mkdir, open, readFile, readdir, rename, rm, stat, writeFi
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
-import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./index.js";
+import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./types.js";
 import type { OwnershipRecord } from "./agent-execution.js";
-import { loadLaunchSnapshot, WorkflowError } from "./index.js";
+import { WorkflowError } from "./types.js";
+import { loadLaunchSnapshot } from "./utils.js";
 
 export interface NativeSessionReference { sessionId: string; sessionFile: string }
 export interface EffectiveSystemPrompt { sessionId: string; attempt: number; turn: number; sha256: string; prompt: string }
-export interface ConversationHead { turn: number; sessionId: string; sessionFile: string; leafId: string; systemPrompt: string; systemPromptSha256: string; toolDefinitionsSha256: string }
-export interface PersistedConversation { id: string; policy: JsonValue; head: ConversationHead }
-type ConversationArtifact = { version: 1; conversations: Record<string, PersistedConversation> };
-function isConversationArtifact(value: unknown): value is ConversationArtifact {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const artifact = value as { version?: unknown; conversations?: unknown };
-  return artifact.version === 1 && Boolean(artifact.conversations) && typeof artifact.conversations === "object" && !Array.isArray(artifact.conversations);
-}
 export interface PersistedRun extends RunRecord { nativeSessions: readonly NativeSessionReference[] }
 export interface CompletedOperation { path: string; value: JsonValue }
 export interface AwaitingCheckpoint { path: string; name: string; prompt: string; context: JsonValue }
@@ -197,7 +190,6 @@ export class RunStore {
   private launchSnapshotWrite: Promise<void> = Promise.resolve();
   // ponytail: the session lease prevents concurrent RunStore writers for one run.
   private systemPromptWrite: Promise<void> = Promise.resolve();
-  private conversationWrite: Promise<void> = Promise.resolve();
   constructor(readonly cwd: string, readonly sessionId: string, readonly runId: string, readonly home = homedir()) {
     this.cwd = resolve(cwd);
     this.directory = join(runsDirectory(this.cwd, sessionId, home), safePart(runId));
@@ -217,7 +209,6 @@ export class RunStore {
       await atomicJson(join(temporary, "borrowed-worktrees.json"), []);
       await atomicJson(join(temporary, "state.json"), run);
       await atomicJson(join(temporary, "system-prompts.json"), { version: 1, entries: [] });
-      await atomicJson(join(temporary, "conversations.json"), { version: 1, conversations: {} });
       await rename(temporary, this.directory);
     } catch (error) {
       await rm(temporary, { recursive: true, force: true });
@@ -296,27 +287,6 @@ export class RunStore {
     return (await json<{ version: 1; entries: EffectiveSystemPrompt[] }>(this.systemPromptPath()).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1 as const, entries: [] }; throw error; })).entries;
   }
 
-  conversationPath(): string { return join(this.directory, "conversations.json"); }
-  async conversation(id: string): Promise<PersistedConversation | undefined> {
-    await this.conversationWrite;
-    let artifact: ConversationArtifact;
-    try { const raw = await json<unknown>(this.conversationPath()); if (!isConversationArtifact(raw)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt"); artifact = raw; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; if (error instanceof WorkflowError) throw error; throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
-    return artifact.conversations[id];
-  }
-  async saveConversation(conversation: PersistedConversation): Promise<void> {
-    const write = this.conversationWrite.then(async () => {
-      const path = this.conversationPath();
-      let artifact: ConversationArtifact;
-      try { const raw = await json<unknown>(path); if (!isConversationArtifact(raw)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation state is corrupt"); artifact = raw; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") artifact = { version: 1, conversations: {} }; else if (error instanceof WorkflowError) throw error; else throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
-      const previous = artifact.conversations[conversation.id];
-      if (previous && previous.head.turn + 1 !== conversation.head.turn) throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation head is not the previous turn: ${conversation.id}`);
-      if (!previous && conversation.head.turn !== 1) throw new WorkflowError("RESUME_INCOMPATIBLE", `Conversation must start at turn one: ${conversation.id}`);
-      artifact.conversations[conversation.id] = structuredClone(conversation);
-      await atomicJson(path, artifact);
-    });
-    this.conversationWrite = write.catch(() => undefined);
-    await write;
-  }
   private async updateJournal<T>(update: (journal: Journal) => T | Promise<T>): Promise<T> {
     let result!: T;
     const write = this.journalWrite.then(async () => {
@@ -339,11 +309,33 @@ export class RunStore {
   }
 
   async replay(path: string): Promise<CompletedOperation | undefined> {
+    const operations = await this.replayableOperations();
+    return operations.find((operation) => operation.path === path);
+  }
+
+  async replayableOperations(): Promise<readonly CompletedOperation[]> {
+    return this.replayableOperationsFrom(new Set());
+  }
+
+  private async replayableOperationsFrom(seen: Set<string>): Promise<readonly CompletedOperation[]> {
+    if (seen.has(this.runId)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry provenance contains a cycle");
+    const nextSeen = new Set(seen);
+    nextSeen.add(this.runId);
     await this.journalWrite;
-    return (await json<Journal>(join(this.directory, "journal.json"))).completed[path];
+    const loaded = await this.load();
+    const operations = new Map<string, CompletedOperation>();
+    if (loaded.run.retry?.sourceRunId) {
+      const source = await this.sourceRun(loaded.run.retry.sourceRunId);
+      for (const operation of await source.replayableOperationsFrom(nextSeen)) operations.set(operation.path, operation);
+    }
+    const journal = await json<Journal>(join(this.directory, "journal.json"));
+    for (const operation of Object.values(journal.completed)) operations.set(operation.path, operation);
+    return [...operations.values()].map((operation) => structuredClone(operation));
   }
 
   async awaitCheckpoint(checkpoint: AwaitingCheckpoint): Promise<boolean | undefined> {
+    const replayed = await this.replay(checkpoint.path);
+    if (replayed) return replayed.value as boolean;
     return this.updateJournal((journal) => {
       const completed = journal.completed[checkpoint.path];
       if (completed) return completed.value as boolean;
@@ -458,6 +450,26 @@ export class RunStore {
   }
 
   async validateParentRun(parentRunId: string): Promise<void> { await this.sourceRun(parentRunId); }
+  async validateRetrySource(): Promise<void> {
+    const validate = async (current: RunStore, seen: Set<string>): Promise<void> => {
+      if (seen.has(current.runId)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry provenance contains a cycle");
+      const nextSeen = new Set(seen);
+      nextSeen.add(current.runId);
+      const loaded = await current.load();
+      const retry = loaded.run.retry;
+      if (!retry) return;
+      if (typeof retry.sourceRunId !== "string" || !retry.sourceRunId || retry.sourceRunId === current.runId || typeof retry.lineageRootRunId !== "string" || !retry.lineageRootRunId || !Array.isArray(retry.completedPaths) || retry.completedPaths.some((path) => typeof path !== "string") || !Array.isArray(retry.incompletePaths) || retry.incompletePaths.some((path) => typeof path !== "string") || !Array.isArray(retry.namedWorktrees) || retry.namedWorktrees.some((name) => typeof name !== "string")) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry provenance is incomplete");
+      const source = await current.sourceRun(retry.sourceRunId);
+      const sourceRun = (await source.load()).run;
+      if (loaded.run.parentRunId !== retry.sourceRunId) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry parent run does not match its source run");
+      if (sourceRun.state !== "failed") throw new WorkflowError("RESUME_INCOMPATIBLE", `Retry source run ${retry.sourceRunId} is not failed`);
+      const expectedLineageRoot = sourceRun.retry?.lineageRootRunId ?? sourceRun.id;
+      if (retry.lineageRootRunId !== expectedLineageRoot) throw new WorkflowError("RESUME_INCOMPATIBLE", "Retry lineage root does not match its source run");
+      await validate(source, nextSeen);
+    };
+    try { await validate(this, new Set()); }
+    catch (error) { throw error instanceof WorkflowError && error.code === "RESUME_INCOMPATIBLE" ? error : new WorkflowError("RESUME_INCOMPATIBLE", error instanceof Error ? error.message : String(error)); }
+  }
 
   private async ownedWorktree(owner: string, cwd?: string): Promise<WorktreeReference> {
     const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
@@ -497,7 +509,12 @@ export class RunStore {
     }
     const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
     const matches = records.filter((candidate) => candidate && typeof candidate === "object" && (candidate as Partial<WorktreeReference>).owner === owner);
-    if (matches.length === 0) return undefined;
+    if (matches.length === 0) {
+      const loaded = await this.load();
+      if (loaded.run.parentRunId === undefined) return undefined;
+      const parent = await this.sourceRun(loaded.run.parentRunId);
+      return parent.findNamedWorktree(name, nextSeen);
+    }
     try {
       const reference = await this.ownedWorktree(owner);
       return { reference, sourceRunId: this.runId, owner };
@@ -521,6 +538,17 @@ export class RunStore {
       throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
     }
   }
+  async validateNamedWorktrees(): Promise<void> {
+    try {
+      const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
+      for (const record of records) {
+        const owner = record && typeof record === "object" && typeof (record as Partial<WorktreeReference>).owner === "string" ? (record as Partial<WorktreeReference>).owner : undefined;
+        if (owner && this.worktreeName(owner)) await this.validateWorktree(owner);
+      }
+    } catch (error) {
+      throw error instanceof WorkflowError && error.code === "WORKTREE_FAILED" ? error : new WorkflowError("WORKTREE_FAILED", error instanceof Error ? error.message : String(error));
+    }
+  }
 
   async ownsWorktree(owner: string): Promise<boolean> {
     const records = await json<unknown[]>(join(this.directory, "worktrees.json"));
@@ -579,6 +607,7 @@ export class RunStore {
           return resolved.reference;
         }
       }
+      if (name && Array.isArray(loaded.run.retry?.namedWorktrees) && loaded.run.retry.namedWorktrees.includes(name)) throw new WorkflowError("WORKTREE_FAILED", `Missing inherited named worktree ${name}`);
       const existing = records.find((record) => record.owner === owner);
       if (existing) return this.validateWorktree(owner);
       const { path, branch } = this.expectedWorktree(owner);
@@ -673,7 +702,29 @@ export class RunStore {
     const borrowed = await Promise.all(bindings.map(async (binding) => (await this.resolveBorrowedWorktree(binding, new Set([this.runId]))).reference));
     return [...owned.filter((record): record is WorktreeReference => record !== undefined), ...borrowed];
   }
-
+  async validNamedWorktrees(): Promise<readonly string[]> {
+    const load = async (path: string): Promise<unknown> => {
+      try { return await json<unknown>(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    };
+    const names = new Set<string>();
+    const rawRecords = await load(join(this.directory, "worktrees.json"));
+    let bindings: readonly BorrowedWorktreeBinding[];
+    try { bindings = await this.borrowedWorktreeRecords(); }
+    catch (error) { if (error instanceof WorkflowError && error.code === "WORKTREE_FAILED") return []; throw error; }
+    const boundOwners = new Set(bindings.map((binding) => binding.owner));
+    for (const record of Array.isArray(rawRecords) ? rawRecords : []) {
+      if (!record || typeof record !== "object") continue;
+      const owner = (record as Partial<WorktreeReference>).owner;
+      if (typeof owner !== "string") continue;
+      const name = this.worktreeName(owner);
+      if (!name || owner !== this.namedWorktreeOwner(name) || boundOwners.has(owner)) continue;
+      try { await this.ownedWorktree(owner); names.add(name); } catch { /* Do not advertise stale or invalid records. */ }
+    }
+    for (const binding of bindings) {
+      try { await this.resolveBorrowedWorktree(binding, new Set([this.runId])); names.add(binding.name); } catch { /* Do not advertise stale inherited records. */ }
+    }
+    return [...names];
+  }
   async changedWorktrees(): Promise<readonly WorktreeReference[]> {
     const changed: WorktreeReference[] = [];
     for (const valid of await this.worktrees()) {

package/src/registry.ts

@@ -0,0 +1,157 @@
+import { Value } from "typebox/value";
+import type { JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogVariable, WorkflowExtension, WorkflowFunction, WorkflowFunctionContext, WorkflowJournal, WorkflowVariable } from "./types.js";
+import { deepFreeze, fail, jsonValue, object } from "./utils.js";
+import { loadSettings, 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-]+)*)?$/;
+
+export class WorkflowRegistry {
+  readonly #extensions = new Set<Readonly<WorkflowExtension>>();
+  readonly #globals = new Map<string, string>();
+  readonly #hooks = new Map<string, RegisteredAgentSetupHook>();
+  #frozen = false;
+
+  get frozen(): boolean { return this.#frozen; }
+  freeze(): void { this.#frozen = true; }
+
+  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", "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()) fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
+    const functions = extension.functions ?? {};
+    const variables = extension.variables ?? {};
+    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 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, 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 });
+    this.#extensions.add(stored);
+    for (const name of names) this.#globals.set(name, name);
+    for (const [name, hook] of Object.entries(agentSetupHooks)) this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
+  }
+
+  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 ?? {}))));
+  }
+
+  catalog(): WorkflowCatalog {
+    const functions: WorkflowCatalogFunction[] = [];
+    const variables: WorkflowCatalogVariable[] = [];
+    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: Readonly<Record<string, string>> | undefined;
+    try { aliases = loadSettings().modelAliases; } catch { aliases = undefined; }
+    const sort = (left: { name: string }, right: { name: string }) => left.name.localeCompare(right.name);
+    return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), ...(aliases ? { modelAliases: structuredClone(aliases) } : {}) });
+  }
+
+  catalogIndex(): WorkflowCatalogIndex {
+    const catalog = this.catalog();
+    return deepFreeze({
+      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) } : {}),
+    });
+  }
+
+  catalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError {
+    const catalog = this.catalog();
+    const entry = catalog.functions.find((candidate) => candidate.name === name) ?? catalog.variables.find((candidate) => candidate.name === name);
+    if (entry) return entry;
+    return deepFreeze({ error: { code: "NOT_FOUND", name, message: `No registered workflow function or variable 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 }]))));
+  }
+
+  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, 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(): readonly { name: string; variable: WorkflowVariable }[] {
+    return [...this.#extensions].flatMap((extension) => Object.entries(extension.variables ?? {}).map(([name, variable]) => ({ name, variable })));
+  }
+  agentSetupHooks(): readonly RegisteredAgentSetupHook[] {
+    return [...this.#hooks.values()].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  }
+}
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
+interface WorkflowRegistryHost { api: WorkflowRegistryApi }
+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(); },
+    register: (extension) => { registry.register(extension); },
+    function: (name) => registry.function(name),
+    functions: () => registry.functions(),
+    catalog: () => registry.catalog(),
+    catalogIndex: () => registry.catalogIndex(),
+    catalogDetail: (name) => registry.catalogDetail(name),
+    globals: () => registry.globals(),
+    invokeFunction: (...args) => registry.invokeFunction(...args),
+    variables: () => registry.variables(),
+    agentSetupHooks: () => registry.agentSetupHooks(),
+  };
+}
+function workflowRegistryHost(): WorkflowRegistryHost {
+  return globalRegistry[WORKFLOW_REGISTRY_KEY] ??= { api: createWorkflowRegistryApi(new WorkflowRegistry()) };
+}
+export function resetWorkflowRegistry(): void {
+  workflowRegistryHost().api = createWorkflowRegistryApi(new WorkflowRegistry());
+}
+export function beginWorkflowExtensionLoading(): void {
+  if (workflowRegistryHost().api.frozen) resetWorkflowRegistry();
+}
+export function loadingRegistry(): WorkflowRegistryApi { return workflowRegistryHost().api; }
+beginWorkflowExtensionLoading();
+export function registerWorkflowExtension(extension: WorkflowExtension): void { loadingRegistry().register(extension); }
+export function workflowCatalog(): WorkflowCatalog { return loadingRegistry().catalog(); }
+export function workflowCatalogIndex(): WorkflowCatalogIndex { return loadingRegistry().catalogIndex(); }
+export function workflowCatalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError { return loadingRegistry().catalogDetail(name); }
+export function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>> { return loadingRegistry().functions(); }
+
+export type { WorkflowCatalog, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogIndexVariable, WorkflowCatalogVariable } from "./types.js";

package/src/session-inspector.ts

@@ -215,7 +215,7 @@ export async function loadSessionReport(path: string, home = homedir()): Promise
     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: StaticWorkflowCall[] = [];

package/src/types.ts

@@ -0,0 +1,113 @@
+export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"] as const;
+export const AGENT_STATES = ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"] as const;
+export const WORKFLOW_CALL_KINDS = ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"] as const;
+export type WorkflowCallKind = (typeof WORKFLOW_CALL_KINDS)[number];
+export const WORKFLOW_RUN_STARTED_EVENT = "workflow:run-started";
+export const WORKFLOW_RUN_RESUMED_EVENT = "workflow:run-resumed";
+export const WORKFLOW_RUN_STATE_CHANGED_EVENT = "workflow:run-state-changed";
+export const WORKFLOW_RUN_COMPLETED_EVENT = "workflow:run-completed";
+export const WORKFLOW_RUN_FAILED_EVENT = "workflow:run-failed";
+export const WORKFLOW_AGENT_STATE_CHANGED_EVENT = "workflow:agent-state-changed";
+export const WORKFLOW_PHASE_CHANGED_EVENT = "workflow:phase-changed";
+export const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpoint-state-changed";
+export const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
+export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
+export const ERROR_CODES = [
+  "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
+  "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID",
+  "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+  ] as const;
+
+export type RunState = (typeof RUN_STATES)[number];
+export type AgentState = (typeof AGENT_STATES)[number];
+export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export type JsonSchema = { [key: string]: JsonValue };
+export interface AgentOptions {
+  label?: string;
+  model?: string;
+  thinking?: NonNullable<ModelSpec["thinking"]>;
+  tools?: string[];
+  role?: string;
+  outputSchema?: JsonSchema;
+  retries?: number;
+  timeoutMs?: number | null;
+  [key: string]: JsonValue;
+}
+export interface ShellOptions { timeoutMs?: number; env?: Record<string, string> }
+export interface ShellResult { exitCode: number | null; stdout: string; stderr: string }
+export type BudgetDimension = "tokens" | "costUsd" | "durationMs" | "agentLaunches";
+export interface BudgetLimits { soft?: number; hard?: number }
+export type WorkflowBudget = Partial<Record<BudgetDimension, BudgetLimits>>;
+export type WorkflowBudgetPatch = Partial<Record<BudgetDimension, BudgetLimits | { soft?: number | null; hard?: number | null } | null>>;
+export interface WorkflowBudgetUsage { tokens: number; costUsd: number; durationMs: number; agentLaunches: number }
+export type BudgetEventType = "soft_crossed" | "hard_overrun" | "hard_exhausted" | "adjustment_requested" | "adjustment_approved" | "adjustment_rejected";
+export interface BudgetEvent { type: BudgetEventType; budgetVersion: number; dimensions: readonly BudgetDimension[]; usage: WorkflowBudgetUsage; limits: WorkflowBudget; at: number; proposalId?: string; previous?: WorkflowBudget; proposed?: WorkflowBudget }
+export interface BudgetApprovalRequest { kind: "budget"; proposalId: string; runId: string; consumed: WorkflowBudgetUsage; previous: WorkflowBudget; proposed: WorkflowBudget; budgetVersion: number }
+export interface WorkflowErrorShape { code: WorkflowErrorCode; message: string }
+export interface WorkflowEventBase { runId: string; sessionId: string; workflowName: string; cwd: string; runDirectory: string; timestamp: number }
+export type WorkflowRunStartedEvent = WorkflowEventBase;
+export type WorkflowRunResumedEvent = WorkflowEventBase;
+export interface WorkflowRunStateChangedEvent extends WorkflowEventBase { previousState: RunState; state: RunState; reason?: string; errorCode?: WorkflowErrorCode }
+export interface WorkflowRunCompletedEvent extends WorkflowEventBase { resultPath: string }
+export interface WorkflowRunFailedEvent extends WorkflowEventBase { error: WorkflowErrorShape }
+export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase { agentId: string; displayLabel: string; role?: string; structuralPath: readonly string[]; parentId?: string; parentBreadcrumb?: string; worktreeOwner?: string; previousState?: AgentState; state: AgentState; attempt: number }
+export interface WorkflowPhaseChangedEvent extends WorkflowEventBase { previousPhase?: string; phase: string }
+export type WorkflowCheckpointState = "awaiting" | "approved" | "rejected";
+export interface WorkflowCheckpointStateChangedEvent extends WorkflowEventBase { name: string; state: WorkflowCheckpointState }
+export interface WorkflowBudgetEvent extends WorkflowEventBase { type: BudgetEventType; budgetVersion: number; dimensions: readonly BudgetDimension[]; usage: WorkflowBudgetUsage; limits: WorkflowBudget; proposalId?: string; previous?: WorkflowBudget; proposed?: WorkflowBudget }
+export interface ModelSpec { provider: string; model: string; thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" }
+export interface WorkflowMetadata { name: string; description?: string }
+export interface WorkflowSettings { concurrency: number; modelAliases?: Readonly<Record<string, string>>; disabledAgentResources?: Readonly<AgentResourceExclusions> }
+export interface AgentResourceExclusions { skills: readonly string[]; extensions: readonly string[] }
+export interface AgentResourcePolicy { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: AgentResourceExclusions; project: AgentResourceExclusions; effective: AgentResourceExclusions; unmatchedSkills: string[]; unmatchedExtensions: string[] }
+export interface AgentActivity { kind: "reasoning" | "tool" | "text"; text: string }
+export interface AgentAccounting { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }
+export interface AgentSetupSummary { hookNames: readonly string[]; model: ModelSpec; tools: readonly string[]; cwd: string; disabledAgentResources?: { skills: readonly string[]; extensions: readonly string[]; unmatchedSkills: readonly string[]; unmatchedExtensions: readonly string[] } }
+export interface AgentAttemptSummary { attempt: number; sessionId: string; sessionFile: string; error?: { code: string; message: string }; accounting: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; setup?: AgentSetupSummary }
+export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase { owner: string; branch: string; path: string; base: string }
+export interface WorkflowWorktreeReference { readonly path: string; readonly branch: string }
+export interface AgentRecord { id: string; name: string; label?: string; path: string; state: AgentState; parentId?: string; structuralPath?: readonly string[]; parentBreadcrumb?: string; worktreeOwner?: string; role?: string; requestedModel?: string; model: ModelSpec; tools: readonly string[]; attempts: number; attemptDetails?: readonly AgentAttemptSummary[]; accounting?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; toolCalls?: readonly { id: string; name: string; state: "running" | "completed" | "failed" }[]; activity?: AgentActivity | undefined }
+export interface WorkflowRunEvent { type: string; message: string }
+export interface WorkflowRetryProvenance { sourceRunId: string; lineageRootRunId: string; completedPaths: readonly string[]; incompletePaths: readonly string[]; namedWorktrees: readonly string[] }
+export interface WorkflowPhaseRecord { phase: string; afterAgent: number }
+export interface RunRecord { id: string; workflowName: string; cwd: string; sessionId: string; state: RunState; parentRunId?: string; retry?: WorkflowRetryProvenance; phase?: string; phaseHistory?: readonly WorkflowPhaseRecord[]; agents: readonly AgentRecord[]; error?: WorkflowErrorShape; budget?: WorkflowBudget; budgetVersion?: number; usage?: WorkflowBudgetUsage; budgetEvents?: readonly BudgetEvent[]; events?: readonly WorkflowRunEvent[] }
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export interface AgentDefinition { prompt?: string; description?: string; model?: string; thinking?: NonNullable<ModelSpec["thinking"]>; tools?: readonly string[]; disabledAgentResources?: AgentResourceExclusions }
+export interface LaunchSnapshot { identityVersion?: number; launchKind?: "inline" | "function"; functionName?: string; script: string; args: JsonValue; metadata: WorkflowMetadata; settings: WorkflowSettings; budget?: WorkflowBudget; settingsPath?: string; modelAliases?: Readonly<Record<string, string>>; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[]; roles?: Readonly<Record<string, AgentDefinition>>; projectRoles?: readonly string[]; schemas: readonly JsonSchema[] }
+export interface PreflightCapabilities { models: ReadonlySet<string>; tools: ReadonlySet<string>; agentTypes: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; skipModelAvailability?: boolean }
+export interface PreflightResult { metadata: WorkflowMetadata; referenced: { phases: readonly string[]; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[] }; schemas: readonly JsonSchema[]; dynamicAgentRoles: boolean }
+export interface WorkflowOrchestrationContext { agent: (prompt: string, options?: Readonly<AgentOptions>) => Promise<JsonValue>; shell: (command: string, options?: ShellOptions) => Promise<ShellResult>; prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string; parallel: (...args: readonly unknown[]) => Promise<JsonValue>; pipeline: (...args: readonly unknown[]) => Promise<JsonValue>; withWorktree: (name: string, callback: WorkflowWorktreeCallback) => Promise<JsonValue>; checkpoint: (...args: readonly unknown[]) => Promise<boolean>; phase: (name: string) => void; log: (message: string) => void }
+export interface WorkflowRunContext { cwd: string; sessionId: string; runId: string; workflow: Readonly<WorkflowMetadata>; args: JsonValue; signal: AbortSignal }
+export interface WorkflowFunctionContext extends WorkflowOrchestrationContext { run: Readonly<WorkflowRunContext>; invoke: (name: string, input: Readonly<Record<string, JsonValue>>) => Promise<JsonValue> }
+export type WorkflowWorktreeCallback = (reference: Readonly<WorkflowWorktreeReference>) => JsonValue | Promise<JsonValue>;
+export interface WorkflowFunction { description: string; input: JsonSchema; output: JsonSchema; run: (input: Readonly<Record<string, JsonValue>>, context: Readonly<WorkflowFunctionContext>) => Promise<JsonValue> | JsonValue }
+export interface WorkflowVariable { description: string; schema: JsonSchema; resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue }
+export interface AgentSetup { prompt: string; options: Record<string, JsonValue>; sessionInput: { extensionFactories?: unknown[]; [key: string]: unknown }; createSession: unknown }
+export interface AgentSetupContext { readonly run: Readonly<WorkflowRunContext>; readonly identity: Readonly<AgentIdentity>; readonly attempt: number; readonly signal: AbortSignal }
+export interface AgentSetupHook { priority?: number; setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void> }
+export interface RegisteredAgentSetupHook { name: string; priority: number; setup: AgentSetupHook["setup"] }
+export interface WorkflowExtension { version: string; headline: string; description: string; functions?: Readonly<Record<string, WorkflowFunction>>; variables?: Readonly<Record<string, WorkflowVariable>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>> }
+export interface WorkflowJournal { get(path: string): JsonValue | undefined; put(path: string, value: JsonValue): void }
+export class WorkflowError extends Error { constructor(public readonly code: WorkflowErrorCode, message: string) { super(message); this.name = "WorkflowError"; } }
+export interface WorkflowFailureAgent { id: string; label?: string; role?: string; structuralPath: readonly string[]; attempt: number; sessionId?: string; sessionFile?: string }
+export interface WorkflowSiblingAgent { id: string; label?: string; role?: string; structuralPath: readonly string[] }
+export interface WorkflowFailureDiagnostics { runId: string; workflowName: string; state: RunState; failedAt: string | null; error: WorkflowErrorShape; failedAgent?: WorkflowFailureAgent; completedSiblingAgents?: readonly WorkflowSiblingAgent[]; completedSiblingPaths: readonly (readonly string[])[]; retry?: { sourceRunId: string; action: string; completedPaths: readonly string[]; incompletePaths: readonly string[]; namedWorktrees: readonly string[]; warning: string }; artifacts: { runDirectory: string; statePath: string; journalPath: string } }
+export interface CheckpointInput { name: string; prompt: string; context: JsonValue }
+export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string }
+export interface ShellIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; worktreeOwner?: string }
+export interface WorkflowBridge { agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>; shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>; checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>; function?: (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath?: readonly string[]) => Promise<JsonValue>; worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>; functions?: Readonly<Record<string, { name: string }>>; variables?: Readonly<Record<string, JsonValue>>; phase?: (name: string) => void | Promise<void>; log?: (message: string) => void | Promise<void> }
+export interface WorkflowExecution { result: Promise<JsonValue>; cancel: () => void }
+export interface StaticWorkflowScope { kind: "parallel" | "pipeline"; name: string | null; key: string | null }
+export type StaticWorkflowExecution = "parallel" | "sequential";
+export interface StaticWorkflowCall { kind: WorkflowCallKind; start: number; end: number; name: string | null; prompt: string | null; model: string | null; label?: string | null; role: string | null; retries?: number | null; outputSchema?: JsonSchema | null; options?: Readonly<Record<string, JsonValue>> | null; optionKeys?: readonly string[]; execution?: StaticWorkflowExecution; structure?: readonly StaticWorkflowScope[] }
+export interface WorkflowCatalogFunction { name: string; version: string; headline: string; extensionDescription: string; description: string; input: JsonSchema; output: JsonSchema }
+export interface WorkflowCatalogVariable { name: string; version: string; headline: string; extensionDescription: string; description: string; schema: JsonSchema }
+export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; variables: readonly WorkflowCatalogVariable[]; modelAliases?: Readonly<Record<string, string>> }
+export interface WorkflowCatalogIndexFunction { name: string; description: string; input: JsonSchema }
+export interface WorkflowCatalogIndexVariable { name: string; description: string; schema: JsonSchema }
+export interface WorkflowCatalogIndex { functions: readonly WorkflowCatalogIndexFunction[]; variables: readonly WorkflowCatalogIndexVariable[]; modelAliases?: Readonly<Record<string, string>> }
+export interface WorkflowCatalogError { error: { code: "NOT_FOUND"; name: string; message: string } }
+export interface WorkflowValidationParameters { name?: string; description?: string; script?: string; workflow?: string; args?: unknown }
+export interface WorkflowValidationContext { cwd: string; projectTrusted: boolean; availableModels: ReadonlySet<string>; rootTools: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; agentDir?: string }
+export interface ValidatedWorkflowLaunch { script: string; checked: PreflightResult; agentDefinitions: Readonly<Record<string, AgentDefinition>>; projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>; roleNames: readonly string[]; functionName?: string }

package/src/utils.ts

@@ -0,0 +1,108 @@
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError, type AgentResourceExclusions, type JsonValue, type ModelSpec, type WorkflowErrorCode } from "./types.js";
+
+export function object(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+export { object as isObject };
+export function jsonValue(value: unknown, seen = new Set<object>()): value is JsonValue {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object" || seen.has(value)) return false;
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return false;
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string")) return false;
+  seen.add(value);
+  const valid = (Array.isArray(value) ? Array.from(value) : keys.map((key) => (value as Record<string, unknown>)[key as string])).every((item) => jsonValue(item, seen));
+  seen.delete(value);
+  return valid;
+}
+export function jsonObject(value: unknown): value is Record<string, JsonValue> { return jsonValue(value) && object(value); }
+export function positiveInteger(value: unknown): value is number { return Number.isInteger(value) && (value as number) > 0; }
+export function deepFreeze<T>(value: T): T {
+  if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+export function errorText(error: unknown): string { return error && typeof error === "object" && typeof (error as { message?: unknown }).message === "string" ? (error as { message: string }).message : error instanceof Error ? error.message : String(error); }
+export function errorCode(error: unknown): WorkflowErrorCode | undefined {
+  if (error instanceof WorkflowError) return ERROR_CODES.includes(error.code) ? error.code : undefined;
+  if (!error || typeof error !== "object") return undefined;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" && ERROR_CODES.includes(code as WorkflowErrorCode) ? code as WorkflowErrorCode : undefined;
+}
+const WORKFLOW_AUTHORED_ERROR = Symbol("workflowAuthoredError");
+export function markWorkflowAuthored(error: WorkflowError, authored = false): WorkflowError {
+  if (authored) Object.defineProperty(error, WORKFLOW_AUTHORED_ERROR, { value: true });
+  return error;
+}
+export function isWorkflowAuthored(error: unknown): boolean { return Boolean(error && typeof error === "object" && WORKFLOW_AUTHORED_ERROR in error); }
+export function asWorkflowError(error: unknown): WorkflowError {
+  const code = errorCode(error);
+  return markWorkflowAuthored(error instanceof WorkflowError && code ? error : new WorkflowError(code ?? "INTERNAL_ERROR", errorText(error)), isWorkflowAuthored(error) || !code);
+}
+export function fail(code: WorkflowErrorCode, message: string): never { throw new WorkflowError(code, message); }
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const MODEL_ALIAS_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+export function parseThinking(value: unknown): ModelSpec["thinking"] | undefined { return typeof value === "string" && THINKING_LEVELS.includes(value as (typeof THINKING_LEVELS)[number]) ? value as ModelSpec["thinking"] : undefined; }
+export function parseModelReference(value: string): ModelSpec {
+  const match = /^([^/:\s]+)\/([^:\s]+)(?::([^:\s]+))?$/.exec(value);
+  if (!match?.[1] || !match[2]) fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
+  const thinking = match[3];
+  if (thinking && !THINKING_LEVELS.includes(thinking as (typeof THINKING_LEVELS)[number])) fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
+  return { provider: match[1], model: match[2], ...(thinking ? { thinking: thinking as NonNullable<ModelSpec["thinking"]> } : {}) };
+}
+function aliasError(message: string, settingsPath: string): never { fail("CONFIG_ERROR", `${message} (settings: ${settingsPath})`); }
+export function modelAliasName(value: string, aliases: Readonly<Record<string, string>>): string | undefined {
+  const name = /^([^/:\s]+)(?::[^:\s]+)?$/.exec(value)?.[1];
+  return name && Object.prototype.hasOwnProperty.call(aliases, name) ? name : undefined;
+}
+export function validateModelAliases(value: unknown, settingsPath = "workflow settings"): Readonly<Record<string, string>> {
+  if (!object(value)) aliasError("modelAliases must be an object", settingsPath);
+  const aliases: Record<string, string> = {};
+  for (const [name, target] of Object.entries(value)) {
+    if (!MODEL_ALIAS_NAME.test(name)) aliasError(`Invalid model alias name: ${name}`, settingsPath);
+    if (typeof target !== "string" || !target.trim()) aliasError(`Invalid model alias target for ${name}`, settingsPath);
+    aliases[name] = target;
+  }
+  for (const name of Object.keys(aliases)) {
+    try { resolveModelReference(name, aliases); } catch (error) { aliasError(`Invalid model alias target for ${name}: ${errorText(error)}`, settingsPath); }
+  }
+  return Object.freeze(aliases);
+}
+export function unknownModel(value: string, target: string | undefined, settingsPath?: string): never {
+  const resolved = target ? ` resolved to ${target}` : "";
+  const path = settingsPath ? ` (settings: ${settingsPath})` : "";
+  fail("UNKNOWN_MODEL", `Unknown model${target ? " alias" : ""} ${value}${resolved}${path}`);
+}
+export function resolveModelReference(value: string, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec {
+  const resolveReference = (reference: string, chain: readonly string[]): ModelSpec => {
+    if (reference.includes("/")) return parseModelReference(reference);
+    const match = /^([^:\s]+)(?::([^:\s]+))?$/.exec(reference);
+    const thinking = match?.[2];
+    if (!match?.[1] || thinking && !THINKING_LEVELS.includes(thinking as (typeof THINKING_LEVELS)[number])) unknownModel(reference, undefined, settingsPath);
+    const alias = modelAliasName(reference, aliases);
+    if (alias) {
+      if (chain.includes(alias)) fail("UNKNOWN_MODEL", `Circular model alias: ${[...chain, alias].join(" -> ")}${settingsPath ? ` (settings: ${settingsPath})` : ""}`);
+      const parsed = resolveReference(aliases[alias] as string, [...chain, alias]);
+      return thinking ? { ...parsed, thinking: thinking as NonNullable<ModelSpec["thinking"]> } : parsed;
+    }
+    const candidates = [...(knownModels ?? [])].filter((model) => model.slice(model.indexOf("/") + 1) === match[1]);
+    if (candidates.length === 1) {
+      const parsed = parseModelReference(candidates[0] as string);
+      return thinking ? { ...parsed, thinking: thinking as NonNullable<ModelSpec["thinking"]> } : parsed;
+    }
+    unknownModel(reference, undefined, settingsPath);
+  };
+  return resolveReference(value, []);
+}
+export function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string {
+  const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
+  return `${parsed.provider}/${parsed.model}`;
+}
+export function aliasDrift(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): string[] {
+  return [...new Set([...Object.keys(previous), ...Object.keys(current)])].sort().flatMap((name) => previous[name] === current[name] ? [] : [`${name}: ${previous[name] ?? "(missing)"} -> ${current[name] ?? "(missing)"}`]);
+}
+export function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions { return { skills: [...new Set(values.flatMap((value) => value?.skills ?? []))], extensions: [...new Set(values.flatMap((value) => value?.extensions ?? []))] }; }
+export function createLaunchSnapshot(input: Omit<import("./types.js").LaunchSnapshot, "identityVersion"> & { identityVersion?: number }): Readonly<import("./types.js").LaunchSnapshot> { return deepFreeze(structuredClone({ ...input, launchKind: input.launchKind ?? (input.functionName ? "function" : "inline"), identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION })); }
+export function loadLaunchSnapshot(input: import("./types.js").LaunchSnapshot): Readonly<import("./types.js").LaunchSnapshot> { return deepFreeze(structuredClone(input)); }