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

package/src/types.ts

@@ -0,0 +1,374 @@
+import type { CreateAgentSessionOptions, InlineExtension, SessionManager, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+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 type RunState = (typeof RUN_STATES)[number];
+export type AgentState = (typeof AGENT_STATES)[number];
+// Shared terminal-state vocabularies: a hard-terminal run and a settled agent are decided here once,
+// so display, persistence, and lifecycle code cannot drift apart on what "finished" means.
+export type HardTerminalRunState = "completed" | "failed" | "stopped";
+export const HARD_TERMINAL_RUN_STATES: ReadonlySet<RunState> = new Set<HardTerminalRunState>(["completed", "failed", "stopped"]);
+export function isHardTerminalRunState(state: RunState): state is HardTerminalRunState { return HARD_TERMINAL_RUN_STATES.has(state); }
+// Ended by a stop, a host shutdown, or budget exhaustion rather than by its own failure: a failing execution must not overwrite these with "failed".
+export type ExternallyEndedRunState = "stopped" | "interrupted" | "budget_exhausted";
+export function isExternallyEndedRunState(state: RunState): state is ExternallyEndedRunState { return state === "stopped" || state === "interrupted" || state === "budget_exhausted"; }
+export const SETTLED_AGENT_STATES: ReadonlySet<AgentState> = new Set(["completed", "failed", "cancelled"]);
+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 WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
+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", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID",
+  "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+  ] as const;
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[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 };
+type WorkflowSchema = JsonSchema | TSchema;
+export function roleNameOf(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+// Extra keys are reserved for extensions and forwarded as JSON to agentOptions; core options remain typed.
+export interface AgentOptions<Schema extends TSchema = never> {
+  label?: string;
+  model?: string;
+  tools?: string[];
+  skills?: string[];
+  extensions?: string[];
+  contextFiles?: ContextFileScope[];
+  role?: string;
+  outputSchema?: JsonSchema | Schema;
+  retries?: number;
+  timeoutMs?: number | null;
+  [key: string]: JsonValue | NoInfer<Schema>;
+}
+export type ParallelTasks = Record<string, () => JsonValue | Promise<JsonValue>>;
+export type ParallelResult<Tasks extends ParallelTasks> = { [Key in keyof Tasks]: Awaited<ReturnType<Tasks[Key]>> };
+export type PipelineItems = Record<string, JsonValue>;
+export type PipelineStage<Input extends JsonValue, Output extends JsonValue> = (value: Input) => Output | Promise<Output>;
+export type PipelineStages<Input extends JsonValue, Output extends JsonValue> = Record<string, PipelineStage<Input, Output>>;
+export type PipelineResult<Items extends PipelineItems, Output extends JsonValue> = { [Key in keyof Items]: Output };
+export interface ShellOptions { timeoutMs?: number; env?: Record<string, string> }
+export interface ShellResult { exitCode: number | null; stdout: string; stderr: string }
+export const BUDGET_DIMENSIONS = ["tokens", "costUsd", "durationMs", "agentLaunches"] as const;
+export type BudgetDimension = (typeof BUDGET_DIMENSIONS)[number];
+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 const BUDGET_EVENT_TYPES = ["soft_crossed", "hard_overrun", "hard_exhausted", "adjustment_requested", "adjustment_approved", "adjustment_rejected"] as const;
+export type BudgetEventType = (typeof BUDGET_EVENT_TYPES)[number];
+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; foreground?: boolean }
+export interface WorkflowErrorShape { code: WorkflowErrorCode; message: string; failedAt?: 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?: ThinkingLevel }
+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 HerdrExtensionSettings { enableFullyInspectableMode?: boolean }
+export interface TrajectoryExtensionSettings { port?: number; themes?: boolean }
+export interface WorkflowExtensionSettings { readonly [namespace: string]: JsonValue; readonly herdr?: Readonly<HerdrExtensionSettings>; readonly trajectory?: Readonly<TrajectoryExtensionSettings> }
+export type WorkflowExtensionSettingsSource = "global" | "project" | "role" | "effective";
+export interface WorkflowExtensionSettingsValidatorContext { source: WorkflowExtensionSettingsSource; cwd: string; projectTrusted: boolean; settingsPath?: string; role?: string }
+export type WorkflowExtensionSettingsValidator = (settings: Readonly<WorkflowExtensionSettings>, context: Readonly<WorkflowExtensionSettingsValidatorContext>) => void;
+export interface WorkflowSessionStartEvent { type: "session_start"; reason: "startup" | "reload" | "new" | "resume" | "fork"; previousSessionFile?: string; settings: Readonly<WorkflowExtensionSettings> }
+export interface WorkflowRetentionSettings { olderThanDays?: number; maxTerminalRuns?: number }
+export interface WorkflowSettings { concurrency: number; backgroundWidget?: boolean; modelAliases?: Readonly<Record<string, string>>; skills?: readonly string[]; extensions?: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; tools?: readonly string[]; retention?: Readonly<WorkflowRetentionSettings>; worktreePostCreateCommand?: readonly string[] }
+export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget">>;
+export interface WorkflowSettingsSources { concurrency: string; modelAliases: string; skills?: string; extensions?: string; tools?: string; extensionSettings?: string; retention?: string; worktreePostCreateCommand?: string }
+export interface WorkflowSettingsResolution { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: Readonly<WorkflowSettings>; project: Readonly<WorkflowSettingsOverrides>; effective: Readonly<WorkflowSettings>; sources: Readonly<WorkflowSettingsSources> }
+export interface AgentResourceSelectors { skills?: readonly string[]; extensions?: readonly string[]; tools?: readonly string[] }
+export interface AgentResourceSelectorSet { skills: readonly string[]; extensions: readonly string[]; tools?: readonly string[] }
+export interface AgentResourceSelectorSources { global: AgentResourceSelectors; project: AgentResourceSelectors; role?: AgentResourceSelectors; call?: AgentResourceSelectors }
+export const CONTEXT_FILE_SCOPES = ["global", "project", "cwd"] as const;
+export type ContextFileScope = (typeof CONTEXT_FILE_SCOPES)[number];
+export function isContextFileScope(value: unknown): value is ContextFileScope { return CONTEXT_FILE_SCOPES.some((scope) => scope === value); }
+export interface AgentResourcePolicy {
+  globalSettingsPath: string;
+  projectSettingsPath: string;
+  projectTrusted: boolean;
+  global: AgentResourceSelectorSet;
+  project: AgentResourceSelectorSet;
+  effective: AgentResourceSelectorSet;
+  selectedSkills?: readonly string[];
+  selectedExtensions?: readonly string[];
+  selectedTools?: readonly string[];
+  unmatchedSkills: readonly string[];
+  unmatchedExtensions: readonly string[];
+  unmatchedTools?: readonly string[];
+  selectorSources: AgentResourceSelectorSources;
+}
+export interface AgentResourceInspection { selectors: AgentResourceSelectorSet; skills: readonly string[]; extensions: readonly string[]; tools: readonly string[]; unmatchedSkills: readonly string[]; unmatchedExtensions: readonly string[]; unmatchedTools: readonly string[]; selectorSources?: AgentResourceSelectorSources }
+
+export interface ContextFile { readonly path: string; readonly content: string }
+export interface AgentActivity { kind: "reasoning" | "tool" | "text"; text: string }
+export const WORKFLOW_AGENT_STALL_THRESHOLD_MS = 10 * 60 * 1000;
+export interface AgentAccounting { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }
+export function zeroAccounting(): AgentAccounting { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }; }
+export function addAccounting(left: AgentAccounting, right: AgentAccounting): AgentAccounting { return { input: left.input + right.input, output: left.output + right.output, cacheRead: left.cacheRead + right.cacheRead, cacheWrite: left.cacheWrite + right.cacheWrite, cost: left.cost + right.cost }; }
+export function sumAccounting(values: Iterable<AgentAccounting>): AgentAccounting {
+  let total = zeroAccounting();
+  for (const value of values) total = addAccounting(total, value);
+  return total;
+}
+export interface AgentSetupSummary { hookNames: readonly string[]; model: ModelSpec; tools: readonly string[]; cwd: string; resourceSelectors?: AgentResourceInspection }
+
+export interface AgentAttemptError { code: string; message: string }
+export interface AgentAttemptSummary { attempt: number; transport: string; session?: WorkflowAgentSessionReference; setup: AgentSetupSummary; error?: AgentAttemptError; accounting: AgentAccounting }
+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 {
+  systemPrompt?: string;
+  prompt?: string;
+  id: string;
+  name: string;
+  label?: string;
+  path: string;
+  state: AgentState;
+  parentId?: string;
+  structuralPath?: readonly string[];
+  resultPath?: string;
+  parentBreadcrumb?: string;
+  worktreeOwner?: string;
+  handle?: string;
+  turn?: number;
+  continuity?: AgentContinuity;
+  role?: string;
+  requestedModel?: string;
+  model: ModelSpec;
+  tools: readonly string[];
+  toolDefinitions?: readonly { readonly name: string; readonly description: string }[];
+  attempts: number;
+  startedAt?: number;
+  durationMs?: number;
+  attemptDetails?: readonly AgentAttemptSummary[];
+  accounting?: AgentAccounting;
+  toolCalls?: readonly { id: string; name: string; state: "running" | "completed" | "failed" }[];
+  activity?: AgentActivity | undefined;
+  lastEventAt?: number;
+}
+export type WorkflowDeliveryMode = "foreground" | "background";
+export type WorkflowDeliveryStatus = "attached" | "pending" | "delivered";
+export interface WorkflowRunDelivery { mode: WorkflowDeliveryMode; state: WorkflowDeliveryStatus; toolCallId?: string }
+export interface WorkflowRunEvent { type: string; message: string; timestamp?: number }
+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 WorkflowPhaseShellActivity { phaseIndex: number; active: number; startedAt: number }
+export interface RunRecord {
+  id: string;
+  workflowName: string;
+  cwd: string;
+  sessionId: string;
+  state: RunState;
+  agentSessions: readonly WorkflowAgentSessionReference[];
+  parentRunId?: string;
+  retry?: WorkflowRetryProvenance;
+  phase?: string;
+  phaseHistory?: readonly WorkflowPhaseRecord[];
+  phaseHistoryIndex?: number;
+  agents: readonly AgentRecord[];
+  activeShells?: number;
+  activeShellStartedAt?: number;
+  activeShellsByPhase?: readonly WorkflowPhaseShellActivity[];
+  error?: WorkflowErrorShape;
+  failedAt?: string;
+  budget?: WorkflowBudget;
+  budgetVersion?: number;
+  usage?: WorkflowBudgetUsage;
+  budgetEvents?: readonly BudgetEvent[];
+  events?: readonly WorkflowRunEvent[];
+  delivery?: WorkflowRunDelivery;
+}
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export type WorkflowLaunchMode = "foreground" | "background";
+export interface AgentDefinition { prompt?: string; description?: string; model?: string; thinking?: NonNullable<ModelSpec["thinking"]>; tools?: readonly string[]; skills?: readonly string[]; extensions?: readonly string[]; overrideSystemPrompt?: boolean; contextFiles?: readonly ContextFileScope[]; extensionSettings?: Readonly<WorkflowExtensionSettings> }
+export interface LaunchSnapshot {
+  identityVersion?: number;
+  launchMode?: WorkflowLaunchMode;
+  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: { <Schema extends TSchema>(prompt: string, options: Readonly<AgentOptions<Schema> & { outputSchema: Schema }>): Promise<Static<Schema>>; (prompt: string, options?: Readonly<AgentOptions>): Promise<JsonValue> }; shell: (command: string, options?: ShellOptions) => Promise<ShellResult>; prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string; parallel: <Tasks extends ParallelTasks>(operationName: string, tasks: Tasks) => Promise<ParallelResult<Tasks>>; pipeline: <Items extends PipelineItems, Output extends JsonValue>(operationName: string, items: Items, stages: PipelineStages<Items[keyof Items], Output>) => Promise<PipelineResult<Items, Output>>; withWorktree: <Result extends JsonValue>(name: string, callback: WorkflowWorktreeCallback<Result>) => Promise<Result>; checkpoint: (input: CheckpointInput) => 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>; settings: Readonly<WorkflowExtensionSettings>; invoke: (name: string, input: Readonly<Record<string, JsonValue>>, label?: string) => Promise<JsonValue> }
+export type WorkflowWorktreeCallback<Result extends JsonValue = JsonValue> = (reference: Readonly<WorkflowWorktreeReference>) => Result | Promise<Result>;
+export interface WorkflowFunction { description: string; input: WorkflowSchema; output: WorkflowSchema; run(input: Readonly<Record<string, JsonValue>>, context: Readonly<WorkflowFunctionContext>): unknown }
+type TypedWorkflowFunction<InputSchema extends TSchema, OutputSchema extends TSchema> = {
+  description: string;
+  input: InputSchema;
+  output: OutputSchema;
+  run: (input: Readonly<Static<NoInfer<InputSchema>>>, context: Readonly<WorkflowFunctionContext>) => Promise<Static<NoInfer<OutputSchema>>> | Static<NoInfer<OutputSchema>>;
+};
+type DefinedWorkflowFunction<InputSchema extends TSchema, OutputSchema extends TSchema, Run extends TypedWorkflowFunction<InputSchema, OutputSchema>["run"]> = Omit<TypedWorkflowFunction<InputSchema, OutputSchema>, "run"> & { run: Run };
+export function defineWorkflowFunction<InputSchema extends TSchema, OutputSchema extends TSchema, Run extends TypedWorkflowFunction<InputSchema, OutputSchema>["run"]>(workflowFunction: DefinedWorkflowFunction<InputSchema, OutputSchema, Run>): DefinedWorkflowFunction<InputSchema, OutputSchema, Run> { return workflowFunction; }
+export interface WorkflowAgentSessionReference { readonly transport: string; readonly sessionId: string; readonly locator?: JsonValue }
+export interface WorkflowAgentSessionStats { readonly tokens: { readonly input: number; readonly output: number; readonly cacheRead: number; readonly cacheWrite: number; readonly total: number }; readonly cost: number }
+export interface WorkflowAgentMessage { readonly role: string; readonly content?: unknown; readonly stopReason?: string; readonly errorMessage?: string; readonly usage?: { readonly input: number; readonly output: number; readonly cacheRead: number; readonly cacheWrite: number; readonly cost: { readonly total: number } } }
+export interface WorkflowAgentSessionState { readonly model: ModelSpec; readonly thinking?: ModelSpec["thinking"]; readonly tools: readonly string[]; readonly systemPrompt?: string }
+export interface WorkflowAgentSessionEvent { readonly type: string; readonly state?: Readonly<WorkflowAgentSessionState>; readonly message?: WorkflowAgentMessage; readonly assistantMessageEvent?: { readonly type: string; readonly delta?: string }; readonly toolCallId?: string; readonly toolName?: string; readonly isError?: boolean }
+export type LiveSessionHandoffState = "local-running" | "handoff-pending" | "herdr-running" | "returning-local" | "completed";
+export interface LiveSessionHandoff {
+  readonly state: LiveSessionHandoffState;
+  readonly transferred: boolean;
+  observe(event: WorkflowAgentSessionEvent): void;
+  request(launch: () => Promise<void>): Promise<void>;
+  waitForTakeover(): Promise<void>;
+  takeover(): void;
+  waitForResume(): Promise<void>;
+  release(reason?: string): void;
+}
+export interface WorkflowAgentTurnResult { readonly assistant?: WorkflowAgentMessage }
+export interface WorkflowAgentSession {
+  readonly reference: WorkflowAgentSessionReference;
+  getState(): Readonly<WorkflowAgentSessionState>;
+  getSessionStats(): WorkflowAgentSessionStats;
+  getLastAssistant(): WorkflowAgentMessage | undefined;
+  subscribe(listener: (event: WorkflowAgentSessionEvent) => void): () => void;
+  subscribeAsync?(listener: (event: WorkflowAgentSessionEvent) => void | Promise<void>): () => void;
+  prompt(text: string): Promise<WorkflowAgentTurnResult>;
+  steer(text: string): Promise<void>;
+  abort(): Promise<void>;
+  suspendForHandoff?(): Promise<void>;
+  resumeFromHandoff?(): Promise<void>;
+  dispose(): Promise<void>;
+  getResourceInspection?(): { readonly skills: readonly string[]; readonly extensions: readonly string[] };
+}
+type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
+type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
+export interface SessionInput {
+  cwd: string;
+  model: ModelSpec;
+  tools: SessionTools;
+  sessionLabel: string;
+  sessionPath?: string;
+  sessionManager?: SessionManager;
+  agentDir?: string;
+  customTools?: SessionCustomTools;
+  resultTool?: ToolDefinition;
+  systemPrompt?: string;
+  systemPromptAppend?: string;
+  extensionFactories?: InlineExtension[];
+  additionalSkillPaths?: readonly string[];
+  contextFiles?: readonly ContextFileScope[];
+  resourcePolicy?: AgentResourcePolicy;
+  readonly settings?: Readonly<WorkflowExtensionSettings>;
+  options?: AgentOptions;
+}
+export interface PiRuntimeLaunchInfo {
+  readonly executable: string;
+  readonly entrypoint?: string;
+}
+export interface PreparedAgentSession {
+  readonly cwd: string;
+  readonly model: ModelSpec;
+  readonly tools: readonly string[];
+  readonly sessionLabel: string;
+  readonly sessionPath?: string;
+  readonly initialPrompt?: string;
+  readonly agentDir?: string;
+  readonly customTools?: readonly ToolDefinition[];
+  readonly resultTool?: ToolDefinition;
+  readonly options?: Readonly<Record<string, JsonValue>>;
+  readonly piRuntime?: Readonly<PiRuntimeLaunchInfo>;
+  readonly piRuntimeError?: string;
+  readonly systemPrompt?: string;
+  readonly systemPromptPath?: string;
+  readonly systemPromptAppend?: string;
+  readonly extensionFactories?: readonly InlineExtension[];
+  readonly additionalSkillPaths?: readonly string[];
+  readonly contextFiles?: readonly ContextFileScope[];
+  readonly resourcePolicy?: Readonly<AgentResourcePolicy>;
+  readonly settings?: Readonly<WorkflowExtensionSettings>;
+}
+export type AgentInspectionMode = "execution" | "inspection";
+export interface AgentTransportContext { readonly run: Readonly<WorkflowRunContext>; readonly identity: Readonly<AgentIdentity>; readonly attempt: number; readonly signal: AbortSignal; readonly tuiIndex?: number; readonly tuiLabel?: string; readonly settings: Readonly<WorkflowExtensionSettings> }
+export interface AgentTransport { readonly id: string; createSession(prepared: Readonly<PreparedAgentSession>, context: Readonly<AgentTransportContext>): Promise<WorkflowAgentSession> }
+export interface AgentSetup { prompt: string; options: AgentOptions; sessionInput: SessionInput; prepared: Readonly<PreparedAgentSession>; transport: AgentTransport }
+export interface AgentSetupContext { readonly run: Readonly<WorkflowRunContext>; readonly identity: Readonly<AgentIdentity>; readonly attempt: number; readonly signal: AbortSignal; readonly tuiIndex?: number; readonly tuiLabel?: string; readonly mode?: AgentInspectionMode; readonly settings: Readonly<WorkflowExtensionSettings> }
+
+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 }
+export interface WorkflowFunctionSource { readonly module: string; readonly export: string; readonly dependencies: readonly string[] }
+export interface WorkflowRoleDirectoryRegistration { path: string; extension: WorkflowExtensionMetadata; readonly builtin?: true }
+export interface AgentAttemptActionUi { notify(message: string, level?: "info" | "warning" | "error"): void; confirm(title: string, message: string): Promise<boolean>; select(title: string, options: readonly string[]): Promise<string | undefined>; input(title: string, placeholder?: string): Promise<string | undefined>; setWorkingMessage?(message?: string): void }
+export interface StandaloneAgentRecord { readonly id: string; readonly name: string; readonly label?: string; readonly state: "running" | "completed" | "failed" | "stopped"; readonly structuralPath?: readonly string[] }
+export interface StandaloneAgentAttemptActionContext { readonly agent: Readonly<StandaloneAgentRecord>; readonly attempt: Readonly<AgentAttemptSummary>; readonly session?: WorkflowAgentSessionReference; readonly liveSession?: WorkflowAgentSession; readonly prepared?: Readonly<PreparedAgentSession>; readonly handoff?: LiveSessionHandoff; readonly signal: AbortSignal; readonly ui: Readonly<AgentAttemptActionUi> }
+export interface AgentAttemptActionContext { readonly run: Readonly<RunRecord>; readonly agent: Readonly<AgentRecord>; readonly attempt: Readonly<AgentAttemptSummary>; readonly session?: WorkflowAgentSessionReference; readonly liveSession?: WorkflowAgentSession; readonly prepared?: Readonly<PreparedAgentSession>; readonly handoff?: LiveSessionHandoff; readonly signal: AbortSignal; readonly ui: Readonly<AgentAttemptActionUi> }
+export interface AgentAttemptAction { readonly label: string; visible(context: Readonly<AgentAttemptActionContext>): boolean; run(context: Readonly<AgentAttemptActionContext>): void | Promise<void>; visibleStandalone?(context: Readonly<StandaloneAgentAttemptActionContext>): boolean; runStandalone?(context: Readonly<StandaloneAgentAttemptActionContext>): void | Promise<void> }
+export interface WorkflowExtension extends WorkflowExtensionMetadata { description?: string; source?: string; dependencies?: readonly string[]; validateSettings?: WorkflowExtensionSettingsValidator; functions?: Readonly<Record<string, WorkflowFunction>>; modelAliases?: Readonly<Record<string, WorkflowModelAlias>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>; agentAttemptActions?: Readonly<Record<string, AgentAttemptAction>>; roleDirectories?: readonly (string | URL)[] }
+export interface WorkflowJournal { get(path: string): JsonValue | undefined; put(path: string, value: JsonValue): void }
+// The brand keeps instanceof working across the bundled extension entries, which each inline their own copy of this class.
+const WORKFLOW_ERROR_BRAND = Symbol.for("pi-extensible-workflows.workflow-error");
+export class WorkflowError extends Error {
+  constructor(public readonly code: WorkflowErrorCode, message: string) { super(message); this.name = "WorkflowError"; (this as unknown as Record<symbol, boolean>)[WORKFLOW_ERROR_BRAND] = true; }
+  static [Symbol.hasInstance](value: unknown): boolean {
+    if (Function.prototype[Symbol.hasInstance].call(this, value)) return true;
+    // Subclasses do not own the brand marker, so they keep plain prototype-chain semantics.
+    return Object.hasOwn(this, WORKFLOW_ERROR_BRAND) && typeof value === "object" && value !== null && WORKFLOW_ERROR_BRAND in value;
+  }
+}
+Object.defineProperty(WorkflowError, WORKFLOW_ERROR_BRAND, { value: true });
+export interface WorkflowFailureAgent { id: string; label?: string; role?: string; structuralPath: readonly string[]; attempt: number; transport?: string; session?: WorkflowAgentSessionReference }
+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 FunctionIdentity { path: string; structuralPath: readonly string[]; occurrence: number; worktreeOwner?: string }
+export type AgentContinuity = "fresh" | "continued";
+export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string; handle?: string; turn?: number }
+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>>, signal: AbortSignal, identity: FunctionIdentity) => Promise<JsonValue>; worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>; functions?: Readonly<Record<string, { name: string }>>; 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; description: string; input: JsonSchema; output: JsonSchema }
+export interface WorkflowCatalogModelAlias { name: string; kind: "static" | "dynamic"; provenance: string; version?: string; headline?: string }
+export interface WorkflowCatalogSettings { concurrency: number; backgroundWidget: boolean; modelAliases: Readonly<Record<string, string>>; skills: readonly string[]; extensions: readonly string[]; tools: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; worktreePostCreateCommand?: readonly string[]; globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; sources: WorkflowSettingsSources }
+export interface WorkflowCatalogContext { cwd: string; projectTrusted: boolean; globalSettingsPath?: string }
+export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; modelAliases?: Readonly<Record<string, string>>; modelAliasEntries?: readonly WorkflowCatalogModelAlias[]; settings?: WorkflowCatalogSettings }
+export interface WorkflowCatalogIndexFunction { name: string; description: string; input: JsonSchema }
+export interface WorkflowCatalogIndex { functions: readonly WorkflowCatalogIndexFunction[]; 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; scriptPath?: 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; extensionSettings?: Readonly<WorkflowExtensionSettings> }
+export interface ValidatedWorkflowLaunch { script: string; checked: PreflightResult; agentDefinitions: Readonly<Record<string, AgentDefinition>>; projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>; roleNames: readonly string[] }

package/src/utils.ts

@@ -0,0 +1,192 @@
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError, type JsonValue, type ModelSpec, type ThinkingLevel, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
+import { Minimatch } from "minimatch";
+export class SerialLane {
+  #tail: Promise<void> = Promise.resolve();
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const next = this.#tail.then(task, task);
+    this.#tail = next.then(() => undefined, () => undefined);
+    return next;
+  }
+}
+
+export function object(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+const ESCAPE_CHARACTER = String.fromCharCode(27);
+const BELL_CHARACTER = String.fromCharCode(7);
+const ANSI_ESCAPE_SEQUENCE = new RegExp(`${ESCAPE_CHARACTER}(?:\\[[0-?]*[ -/]*[@-~]|\\][^${BELL_CHARACTER}]*(?:${BELL_CHARACTER}|${ESCAPE_CHARACTER}\\\\))`, "g");
+const TERMINAL_CONTROL_CHARACTER = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(31)}${String.fromCharCode(127)}-${String.fromCharCode(159)}]`, "g");
+export function sanitizeDisplayText(value: string): string { return value.replace(ANSI_ESCAPE_SEQUENCE, "").replace(TERMINAL_CONTROL_CHARACTER, " "); }
+export { object as isObject };
+function isStringKey(key: PropertyKey): key is string { return typeof key === "string"; }
+function stringKeyValue(value: object, key: string): unknown { return object(value) ? value[key] : undefined; }
+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 ownKeys = Reflect.ownKeys(value);
+  const keys = ownKeys.filter(isStringKey);
+  if (keys.length !== ownKeys.length) return false;
+  seen.add(value);
+  const valid = (Array.isArray(value) ? Array.from(value) : keys.map((key) => stringKeyValue(value, key))).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 mergeWorkflowExtensionSettings(...layers: readonly (Readonly<WorkflowExtensionSettings> | undefined)[]): Readonly<WorkflowExtensionSettings> | undefined {
+  const merged: Record<string, JsonValue> = {};
+  let present = false;
+  for (const layer of layers) {
+    if (layer === undefined) continue;
+    present = true;
+    for (const [namespace, value] of Object.entries(layer)) Object.defineProperty(merged, namespace, { value: structuredClone(value), enumerable: true, configurable: true, writable: true });
+  }
+  return present ? deepFreeze(merged as WorkflowExtensionSettings) : undefined;
+}
+export function positiveInteger(value: unknown): value is number { return typeof value === "number" && Number.isInteger(value) && value > 0; }
+export function finiteNumber(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value); }
+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 isNodeError(error: unknown, code: string): error is { code: string } { return object(error) && error.code === code; }
+export function isWorkflowErrorCode(value: unknown): value is WorkflowErrorCode { return ERROR_CODES.some((candidate) => candidate === value); }
+export function errorText(error: unknown): string { return object(error) && typeof error.message === "string" ? error.message : error instanceof Error ? error.message : String(error); }
+export function coerceWorkflowError(code: WorkflowErrorCode, error: unknown): WorkflowError {
+  return error instanceof WorkflowError && error.code === code ? error : new WorkflowError(code, errorText(error));
+}
+export function errorCode(error: unknown): WorkflowErrorCode | undefined {
+  if (error instanceof WorkflowError) return isWorkflowErrorCode(error.code) ? error.code : undefined;
+  if (!object(error)) return undefined;
+  return isWorkflowErrorCode(error.code) ? error.code : 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); }
+/** Sort order for agent setup hooks: lower priority first, ties broken by name so registration order never matters. */
+export function byPriorityThenName(left: { priority: number; name: string }, right: { priority: number; name: string }): number { return left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0); }
+
+export function isThinkingLevel(value: unknown): value is ThinkingLevel { return THINKING_LEVELS.some((level) => level === value); }
+export const MODEL_ALIAS_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+export const WORKFLOW_EXTENSION_NAMESPACE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+export function validWorkflowExtensionNamespace(value: string): boolean { return WORKFLOW_EXTENSION_NAMESPACE.test(value) && value !== "__proto__" && value !== "constructor" && value !== "prototype"; }
+export function parseThinking(value: unknown): ModelSpec["thinking"] | undefined { return isThinkingLevel(value) ? value : 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 !== undefined && !isThinkingLevel(thinking)) fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
+  return { provider: match[1], model: match[2], ...(thinking !== undefined ? { thinking } : {}) };
+}
+export function assertModelThinking(value: string, path = "model"): void {
+  if (value.includes("/") && parseModelReference(value).thinking === undefined) fail("INVALID_METADATA", `${path} must be provider/model: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 !== undefined && !isThinkingLevel(thinking)) 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 { [alias]: target } = aliases;
+      if (typeof target !== "string") unknownModel(reference, undefined, settingsPath);
+      const parsed = resolveReference(target, [...chain, alias]);
+      return thinking !== undefined ? { ...parsed, thinking } : parsed;
+    }
+    const candidates = [...(knownModels ?? [])].filter((model) => model.slice(model.indexOf("/") + 1) === match[1]);
+    if (candidates.length === 1) {
+      const [candidate] = candidates;
+      if (candidate !== undefined) {
+        const parsed = parseModelReference(candidate);
+        return thinking !== undefined ? { ...parsed, 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 {
+  const body = resourcePatternBody(pattern);
+  if (body === "*") return true;
+  return new Minimatch(resourcePatternPath(body), RESOURCE_PATTERN_OPTIONS).match(resourcePatternPath(resource));
+}
+export function selectResourcesByLayers(layers: readonly (readonly string[] | undefined)[], resources: readonly string[]): string[] {
+  const enabled = new Set(resources);
+  for (const layer of layers) {
+    if (layer === undefined) continue;
+    for (const resource of resources) {
+      for (const pattern of layer) if (resourcePatternMatches(resource, pattern)) {
+        if (pattern.startsWith("!")) enabled.delete(resource); else enabled.add(resource);
+      }
+    }
+  }
+  return resources.filter((resource) => enabled.has(resource));
+}
+export function resourcePatternHasMagic(pattern: string): boolean { return /[*?\x5b\x5d{}()]/.test(resourcePatternBody(pattern)); }
+export function unmatchedResourcePatterns(patterns: readonly string[], resources: readonly string[]): string[] { return patterns.filter((pattern) => !resources.some((resource) => resourcePatternMatches(resource, pattern))); }
+export function createLaunchSnapshot(input: Omit<import("./types.js").LaunchSnapshot, "identityVersion"> & { identityVersion?: number }): Readonly<import("./types.js").LaunchSnapshot> { return deepFreeze(structuredClone({ ...input, identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION })); }
+export function loadLaunchSnapshot(input: import("./types.js").LaunchSnapshot): Readonly<import("./types.js").LaunchSnapshot> { return deepFreeze(structuredClone(input)); }