pi-extensible-workflows 2.0.0 → 3.1.0

package/src/types.ts

@@ -0,0 +1,158 @@
+import type { AgentSessionEvent, CreateAgentSessionOptions, InlineExtension, SessionStats, ToolDefinition } from "@earendil-works/pi-coding-agent";
+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 WorkflowModelAliasResolverContext { cwd: string; projectTrusted: boolean; rootModel: ModelSpec; knownModels: ReadonlySet<string>; availableModels: ReadonlySet<string>; signal: AbortSignal }
+export interface WorkflowModelAlias { resolve: (context: Readonly<WorkflowModelAliasResolverContext>) => string | Promise<string> }
+export interface WorkflowMetadata { name: string; description?: string }
+export interface WorkflowSettings { concurrency: number; modelAliases?: Readonly<Record<string, string>>; disabledAgentResources?: Readonly<AgentResourceExclusions> }
+export interface WorkflowSettingsOverrides { concurrency?: number; modelAliases?: Readonly<Record<string, string>>; disabledAgentResources?: Readonly<AgentResourceExclusions> }
+export interface WorkflowSettingsSources { concurrency: string; modelAliases: string; disabledAgentResources: string }
+export interface WorkflowSettingsResolution { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: Readonly<WorkflowSettings>; project: Readonly<WorkflowSettingsOverrides>; effective: Readonly<WorkflowSettings>; sources: Readonly<WorkflowSettingsSources> }
+export interface AgentResourceExclusions { skills: readonly string[]; extensions: readonly string[] }
+export interface AgentResourcePolicy { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: AgentResourceExclusions; project: AgentResourceExclusions; effective: AgentResourceExclusions; unmatchedSkills: string[]; unmatchedExtensions: string[]; excludedSkills?: string[]; excludedExtensions?: 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[]; excludedSkills?: readonly string[]; excludedExtensions?: 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; settingsSources?: WorkflowSettingsSources; budget?: WorkflowBudget; settingsPath?: string; modelAliases?: Readonly<Record<string, string>>; phases?: readonly 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 }
+type NativeAgentMessage = { role: string; content?: unknown; stopReason?: string; errorMessage?: string; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { total: number } } };
+type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
+export interface NativeSession {
+  readonly sessionId: string;
+  readonly sessionFile: string | undefined;
+  readonly messages: readonly NativeAgentMessage[];
+  getSessionStats(): NativeSessionStats;
+  readonly systemPrompt?: string;
+  readonly model?: { provider: string; model?: string; id?: string };
+  readonly agent?: { state: { tools: readonly { name: string }[] } };
+  getLeafId?: () => string | null;
+  getToolDefinitions?: () => unknown;
+  subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
+  prompt(text: string): Promise<void>;
+  steer?(text: string): Promise<void>;
+  abort?(): Promise<void>;
+  dispose(): void;
+}
+type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
+type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
+export interface SessionInput {
+  cwd: string;
+  model: ModelSpec;
+  tools: SessionTools;
+  sessionLabel: string;
+  agentDir?: string;
+  customTools?: SessionCustomTools;
+  resultTool?: ToolDefinition;
+  systemPromptAppend?: string;
+  extensionFactories?: InlineExtension[];
+  resourcePolicy?: AgentResourcePolicy;
+  options?: AgentOptions;
+}
+export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
+export interface AgentSetup { prompt: string; options: AgentOptions; sessionInput: SessionInput; createSession: SessionFactory }
+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 WorkflowExtensionMetadata { version: string; headline: string; description: string }
+export interface WorkflowRoleDirectoryRegistration { path: string; extension: WorkflowExtensionMetadata }
+export interface WorkflowExtension extends WorkflowExtensionMetadata { functions?: Readonly<Record<string, WorkflowFunction>>; variables?: Readonly<Record<string, WorkflowVariable>>; modelAliases?: Readonly<Record<string, WorkflowModelAlias>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>; roleDirectories?: readonly (string | URL)[] }
+export interface WorkflowJournal { get(path: string): JsonValue | undefined; 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 WorkflowCatalogModelAlias { name: string; kind: "static" | "dynamic"; provenance: string; version?: string; headline?: string; extensionDescription?: string }
+export interface WorkflowCatalogSettings { concurrency: number; modelAliases: Readonly<Record<string, string>>; disabledAgentResources: AgentResourceExclusions; globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; sources: WorkflowSettingsSources }
+export interface WorkflowCatalogContext { cwd: string; projectTrusted: boolean; globalSettingsPath?: string }
+export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; variables: readonly WorkflowCatalogVariable[]; modelAliases?: Readonly<Record<string, string>>; modelAliasEntries?: readonly WorkflowCatalogModelAlias[]; settings?: WorkflowCatalogSettings }
+export interface WorkflowCatalogIndexFunction { name: string; 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>>; modelAliasEntries?: readonly WorkflowCatalogModelAlias[]; settings?: WorkflowCatalogSettings }
+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,142 @@
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError, type AgentResourceExclusions, type JsonValue, type ModelSpec, type WorkflowErrorCode } from "./types.js";
+import { Minimatch } from "minimatch";
+
+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"]> } : {}) };
+}
+const MODEL_ALIAS_ERROR_NAME = Symbol("modelAliasErrorName");
+type ModelAliasError = WorkflowError & { [MODEL_ALIAS_ERROR_NAME]?: string };
+function aliasError(message: string, settingsPath: string, name?: string): never {
+  const error = new WorkflowError("CONFIG_ERROR", `${message} (settings: ${settingsPath})`);
+  if (name) Object.defineProperty(error, MODEL_ALIAS_ERROR_NAME, { value: name, configurable: true });
+  throw error;
+}
+export function annotateModelAliasError(error: unknown, name: string): unknown {
+  if (error instanceof WorkflowError) Object.defineProperty(error, MODEL_ALIAS_ERROR_NAME, { value: name, configurable: true });
+  return error;
+}
+export function modelAliasErrorName(error: unknown): string | undefined {
+  return error instanceof WorkflowError ? (error as ModelAliasError)[MODEL_ALIAS_ERROR_NAME] : undefined;
+}
+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, name);
+    if (typeof target !== "string" || !target.trim()) aliasError(`Invalid model alias target for ${name}`, settingsPath, name);
+    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, name); }
+  }
+  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)"}`]);
+}
+const RESOURCE_PATTERN_OPTIONS = { dot: true, nonegate: true, nocomment: true } as const;
+function resourcePatternBody(pattern: string): string { return pattern.startsWith("!") ? pattern.slice(1) : pattern; }
+function resourcePatternPath(value: string): string { return value.replaceAll("\\", "/"); }
+export function validateResourcePattern(pattern: string): void {
+  const body = resourcePatternBody(pattern);
+  if (!body) throw new Error(`Empty minimatch pattern ${JSON.stringify(pattern)}`);
+  const matcher = new Minimatch(resourcePatternPath(body), RESOURCE_PATTERN_OPTIONS);
+  if (matcher.makeRe() === false) throw new Error(`Invalid minimatch pattern ${JSON.stringify(pattern)}`);
+}
+export function resourcePatternMatches(resource: string, pattern: string): boolean { return new Minimatch(resourcePatternPath(resourcePatternBody(pattern)), RESOURCE_PATTERN_OPTIONS).match(resourcePatternPath(resource)); }
+export function disabledResources(patterns: readonly string[], resources: readonly string[]): string[] {
+  const disabled = new Set<string>();
+  for (const resource of resources) {
+    let excluded = false;
+    for (const pattern of patterns) if (resourcePatternMatches(resource, pattern)) excluded = !pattern.startsWith("!");
+    if (excluded) disabled.add(resource);
+  }
+  return [...disabled];
+}
+export function unmatchedResourcePatterns(patterns: readonly string[], resources: readonly string[]): string[] { return patterns.filter((pattern) => !resources.some((resource) => resourcePatternMatches(resource, pattern))); }
+export function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions { return { skills: values.flatMap((value) => value?.skills ?? []), extensions: 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)); }