@multiplier-labs/stepflow 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,748 @@
+import { a as WorkflowError, L as Logger, W as WorkflowKind, b as StepErrorStrategy, c as WorkflowStep } from './types-BVShq7zT.js';
+export { d as RunResult, R as RunStatus, e as SpawnChildOptions, S as StepStatus, f as WorkflowContext, g as WorkflowDefinition, h as WorkflowHooks } from './types-BVShq7zT.js';
+export { C as CronScheduler, a as CronSchedulerConfig, P as PostgresSchedulePersistence, b as PostgresSchedulePersistenceConfig, S as SQLiteSchedulePersistence, c as SQLiteSchedulePersistenceConfig, d as SchedulePersistence, e as Scheduler, f as StartRunOptions, T as TriggerType, W as WorkflowEngine, g as WorkflowEngineConfig, h as WorkflowSchedule } from './index-CPfGsmrp.js';
+export { C as CreateRunInput, E as ExtendedListRunsOptions, a as ExtendedRunStatus, b as ExtendedStepStatus, c as ExtendedWorkflowRunRecord, L as ListEventsOptions, d as ListRunsOptions, P as PaginatedResult, S as StepRecord, e as StepResult, f as StepflowDatabase, g as StepflowRunsTable, h as StepflowStepResultsTable, i as StorageAdapter, U as UpdateRunInput, W as WorkflowEventRecord, j as WorkflowRunRecord, k as WorkflowRunStepRecord, l as WorkflowStorage } from './types-BlwFEGzj.js';
+export { MemoryStorageAdapter, PostgresStorage, PostgresStorage as PostgresStorageAdapter, PostgresStorageConfig, SQLiteStorageAdapter, SQLiteStorageConfig } from './storage/index.js';
+export { B as BuiltInEventType, E as EventCallback, a as EventTransport, U as Unsubscribe, W as WorkflowEvent, b as WorkflowEventType } from './types-DzkEqnQJ.js';
+export { MemoryEventTransport, SocketIOAuthorizeFn, SocketIOEventTransport, SocketIOEventTransportConfig, SocketIOServer, SocketIOSocket, WebhookEndpoint, WebhookEventTransport, WebhookEventTransportConfig, WebhookPayload } from './events/index.js';
+import 'better-sqlite3';
+import 'pg';
+
+/**
+ * Generate a unique ID for database records.
+ * Uses a ULID-like format: base36 timestamp + random suffix.
+ * This provides:
+ * - Rough time-ordering (useful for debugging)
+ * - High collision resistance
+ * - URL-safe characters
+ * - Cryptographically secure random component
+ *
+ * @returns A unique identifier string (approx 16 characters)
+ */
+declare function generateId(): string;
+
+/**
+ * Custom error classes for the workflow engine.
+ */
+
+/**
+ * Base error class for workflow-related errors.
+ */
+declare class WorkflowEngineError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+    /**
+     * Convert to a WorkflowError record for storage.
+     */
+    toRecord(): WorkflowError;
+    /**
+     * Create a WorkflowError record from any error.
+     */
+    static fromError(error: unknown, defaultCode?: string): WorkflowError;
+}
+/**
+ * Error thrown when a workflow is not found in the registry.
+ */
+declare class WorkflowNotFoundError extends WorkflowEngineError {
+    constructor(kind: string);
+}
+/**
+ * Error thrown when a workflow is already registered.
+ */
+declare class WorkflowAlreadyRegisteredError extends WorkflowEngineError {
+    constructor(kind: string);
+}
+/**
+ * Error thrown when a run is not found.
+ */
+declare class RunNotFoundError extends WorkflowEngineError {
+    constructor(runId: string);
+}
+/**
+ * Error thrown when a step fails.
+ */
+declare class StepError extends WorkflowEngineError {
+    readonly stepKey: string;
+    readonly attempt: number;
+    readonly cause?: Error;
+    constructor(stepKey: string, message: string, attempt: number, cause?: Error);
+}
+/**
+ * Error thrown when a step times out.
+ */
+declare class StepTimeoutError extends WorkflowEngineError {
+    readonly stepKey: string;
+    readonly timeoutMs: number;
+    constructor(stepKey: string, timeoutMs: number);
+}
+/**
+ * Error thrown when a workflow is canceled.
+ */
+declare class WorkflowCanceledError extends WorkflowEngineError {
+    constructor(runId: string);
+}
+/**
+ * Error thrown when waitForRun times out polling for a terminal status.
+ */
+declare class WaitForRunTimeoutError extends WorkflowEngineError {
+    readonly runId: string;
+    readonly timeoutMs: number;
+    constructor(runId: string, timeoutMs: number);
+}
+/**
+ * Error thrown when a workflow times out.
+ */
+declare class WorkflowTimeoutError extends WorkflowEngineError {
+    readonly timeoutMs: number;
+    constructor(runId: string, timeoutMs: number);
+}
+
+/**
+ * Logger utilities for the workflow engine.
+ */
+
+/** Log level for ConsoleLogger. Levels are ordered: debug < info < warn < error. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Console-based logger implementation.
+ * Uses console.log with prefixes for different levels.
+ * Supports a configurable minimum log level (default: 'info').
+ */
+declare class ConsoleLogger implements Logger {
+    private prefix;
+    private minLevel;
+    constructor(prefix?: string, level?: LogLevel);
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Silent logger that does nothing.
+ * Useful for testing or when logs are not wanted.
+ */
+declare class SilentLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+/**
+ * Strip stack traces from a WorkflowError before persisting to storage.
+ * Stack traces expose internal file paths and should be kept in logs only.
+ */
+declare function sanitizeErrorForStorage(error: WorkflowError): WorkflowError;
+/**
+ * Create a scoped logger that includes run/step context.
+ */
+declare function createScopedLogger(logger: Logger, runId: string, stepKey?: string): Logger;
+
+/**
+ * Retry utilities for the workflow engine.
+ */
+/**
+ * Options for retry behavior.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial delay between retries in ms (default: 1000) */
+    delay: number;
+    /** Backoff multiplier (default: 2) */
+    backoff: number;
+    /** Optional abort signal to cancel retries */
+    signal?: AbortSignal;
+    /** Optional callback before each retry */
+    onRetry?: (attempt: number, error: Error, nextDelay: number) => void;
+}
+/**
+ * Default retry options.
+ */
+declare const DEFAULT_RETRY_OPTIONS: RetryOptions;
+/**
+ * Sleep for a given number of milliseconds.
+ * Can be canceled via AbortSignal.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Execute a function with retry logic.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration
+ * @returns The result of the function
+ * @throws The last error if all retries are exhausted
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Calculate the delay for a specific retry attempt.
+ */
+declare function calculateRetryDelay(attempt: number, baseDelay: number, backoff: number): number;
+
+/**
+ * Planning types for the workflow engine.
+ * Enables dynamic workflow orchestration through recipes and plans.
+ */
+
+/**
+ * Comparison operators for recipe conditions.
+ */
+type ConditionOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "matches" | "exists" | "notExists";
+/**
+ * A condition that determines when a recipe should be selected.
+ * Conditions are evaluated against the workflow input.
+ */
+interface RecipeCondition {
+    /** Input field to check (supports dot notation for nested fields) */
+    field: string;
+    /** Comparison operator */
+    operator: ConditionOperator;
+    /** Value to compare against (not required for exists/notExists) */
+    value?: unknown;
+}
+/**
+ * Default parameters for a recipe.
+ */
+interface RecipeDefaults {
+    /** Workflow-level timeout in ms */
+    timeout?: number;
+    /** Default max retries for steps */
+    maxRetries?: number;
+    /** Base retry delay in ms */
+    retryDelay?: number;
+    /** Retry backoff multiplier */
+    retryBackoff?: number;
+    /** Default error strategy for steps */
+    onError?: StepErrorStrategy;
+}
+/**
+ * Reference to a step handler function.
+ * The actual handler is resolved at plan execution time.
+ */
+interface StepHandlerRef {
+    /** Unique handler identifier (e.g., 'handlers.loadDocument') */
+    id: string;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * A step definition within a recipe.
+ * Similar to WorkflowStep but uses handler references instead of functions.
+ */
+interface RecipeStep {
+    /** Unique step identifier within the recipe */
+    key: string;
+    /** Human-readable step name */
+    name: string;
+    /** Reference to the step handler function */
+    handlerRef: string;
+    /** Step-specific configuration passed to the handler */
+    config?: Record<string, unknown>;
+    /** Error handling strategy */
+    onError?: StepErrorStrategy;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** Retry delay in ms */
+    retryDelay?: number;
+    /** Retry backoff multiplier */
+    retryBackoff?: number;
+    /** Step timeout in ms */
+    timeout?: number;
+    /**
+     * Expression to evaluate for skipping (simple field reference).
+     * If the referenced field is truthy, the step is skipped.
+     * Example: 'input.skipValidation' or 'results.load.alreadyExists'
+     */
+    skipCondition?: string;
+}
+/**
+ * A recipe is a reusable workflow configuration template.
+ * Recipes define the steps to execute and conditions for selection.
+ */
+interface Recipe {
+    /** Unique recipe identifier (e.g., 'summarize.comprehensive') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this recipe does */
+    description?: string;
+    /** Target workflow type */
+    workflowKind: WorkflowKind;
+    /** Variant name (e.g., 'default', 'fast', 'thorough') */
+    variant: string;
+    /** Ordered list of steps to execute */
+    steps: RecipeStep[];
+    /** Default parameters for this recipe */
+    defaults?: RecipeDefaults;
+    /** Conditions for auto-selecting this recipe */
+    conditions?: RecipeCondition[];
+    /**
+     * Selection priority. Semantics differ by context:
+     * - {@link MemoryRecipeRegistry.getDefault}: lower number = higher precedence
+     *   (used as fallback when no 'default' variant exists).
+     * - {@link RuleBasedPlanner.selectRecipe}: condition-based scoring (0-100) is
+     *   the primary selection axis; this value is only a tiebreaker where higher
+     *   numeric value wins.
+     */
+    priority?: number;
+    /** Tags for categorization and filtering */
+    tags?: string[];
+}
+/**
+ * Types of modifications that can be made to a plan.
+ */
+type PlanModificationType = "add_step" | "remove_step" | "modify_step" | "reorder_steps" | "set_default";
+/**
+ * A modification to apply to a recipe when generating a plan.
+ */
+interface PlanModification {
+    /** Type of modification */
+    type: PlanModificationType;
+    /** Target step key (for step modifications) */
+    stepKey?: string;
+    /** New value or configuration */
+    value: unknown;
+    /** Human-readable reason for this modification */
+    reason: string;
+}
+/**
+ * A resolved step in a plan, ready for execution.
+ */
+interface PlannedStep {
+    /** Unique step identifier */
+    key: string;
+    /** Human-readable step name */
+    name: string;
+    /** Reference to the step handler */
+    handlerRef: string;
+    /** Resolved configuration for this step */
+    config: Record<string, unknown>;
+    /** Error handling strategy */
+    onError?: StepErrorStrategy;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** Retry delay in ms */
+    retryDelay?: number;
+    /** Retry backoff multiplier */
+    retryBackoff?: number;
+    /** Step timeout in ms */
+    timeout?: number;
+    /** Skip condition expression */
+    skipCondition?: string;
+}
+/**
+ * A planned child workflow to spawn during execution.
+ */
+interface ChildWorkflowPlan {
+    /** Workflow type to spawn */
+    kind: WorkflowKind;
+    /** Input for the child workflow */
+    input: Record<string, unknown>;
+    /** Whether to wait for the child to complete */
+    waitFor?: boolean;
+    /** Step key after which to spawn this workflow */
+    afterStep?: string;
+    /** Optional metadata for the child workflow */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Resource requirements estimated for a plan.
+ */
+interface ResourceEstimate {
+    /** Estimated API calls */
+    apiCalls?: number;
+    /** Estimated LLM tokens */
+    tokens?: number;
+    /** Estimated duration in ms */
+    duration?: number;
+    /** Estimated memory usage in bytes */
+    memory?: number;
+}
+/**
+ * A plan is the output of planning - a concrete execution strategy.
+ */
+interface Plan {
+    /** Unique plan identifier */
+    id: string;
+    /** Recipe this plan is based on */
+    recipeId: string;
+    /** Recipe variant used */
+    variant: string;
+    /** Modifications applied to the base recipe */
+    modifications: PlanModification[];
+    /** Final step sequence after modifications */
+    steps: PlannedStep[];
+    /** Child workflows to spawn */
+    childWorkflows?: ChildWorkflowPlan[];
+    /** Resolved default parameters */
+    defaults: RecipeDefaults;
+    /** Human-readable reasoning for plan decisions */
+    reasoning?: string;
+    /** Estimated resource requirements */
+    resourceEstimate?: ResourceEstimate;
+    /** When this plan was generated */
+    createdAt: Date;
+}
+/**
+ * Priority modes for planning.
+ */
+type PlanningPriority = "speed" | "quality" | "cost" | "balanced";
+/**
+ * Constraints that limit planning and execution.
+ */
+interface PlanningConstraints {
+    /** Maximum allowed duration in ms */
+    maxDuration?: number;
+    /** Maximum API calls allowed */
+    maxApiCalls?: number;
+    /** Maximum LLM tokens allowed */
+    maxTokens?: number;
+    /** Optimization priority */
+    priority?: PlanningPriority;
+}
+/**
+ * User-provided hints to guide planning.
+ */
+interface PlanningHints {
+    /** Preferred recipe variant */
+    preferredVariant?: string;
+    /** Specific recipe to use (bypasses selection) */
+    forceRecipeId?: string;
+    /** Steps to skip */
+    skipSteps?: string[];
+    /** Steps to include (even if normally skipped) */
+    includeSteps?: string[];
+    /** Focus areas (domain-specific) */
+    focusAreas?: string[];
+    /** Additional configuration to merge */
+    additionalConfig?: Record<string, unknown>;
+}
+/**
+ * Context provided to the planner for decision-making.
+ */
+interface PlanningContext {
+    /** Parent workflow run ID (if spawned as child) */
+    parentRunId?: string;
+    /** Domain-specific metadata */
+    metadata?: Record<string, unknown>;
+    /** Resource constraints */
+    constraints?: PlanningConstraints;
+    /** User-provided hints */
+    hints?: PlanningHints;
+}
+/**
+ * Result of recipe selection.
+ */
+interface RecipeSelectionResult {
+    /** Selected recipe */
+    recipe: Recipe;
+    /** Score indicating confidence (0-100) */
+    score: number;
+    /** Why this recipe was selected */
+    reason: string;
+}
+/**
+ * Validation result for a plan.
+ */
+interface PlanValidationResult {
+    /** Whether the plan is valid */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+}
+/**
+ * Planner interface for generating execution plans.
+ */
+interface Planner {
+    /**
+     * Select the best recipe for a workflow and input.
+     */
+    selectRecipe(workflowKind: WorkflowKind, input: Record<string, unknown>, context?: PlanningContext): Promise<RecipeSelectionResult>;
+    /**
+     * Generate a plan from a recipe and input.
+     */
+    generatePlan(recipe: Recipe, input: Record<string, unknown>, context?: PlanningContext): Promise<Plan>;
+    /**
+     * Combined operation: select recipe and generate plan.
+     */
+    plan(workflowKind: WorkflowKind, input: Record<string, unknown>, context?: PlanningContext): Promise<Plan>;
+    /**
+     * Validate a plan before execution.
+     */
+    validatePlan(plan: Plan): PlanValidationResult;
+    /**
+     * Estimate resources required for a plan.
+     */
+    estimateResources(plan: Plan): ResourceEstimate;
+}
+/**
+ * A registered step handler function.
+ */
+interface RegisteredStepHandler<TInput = Record<string, unknown>> {
+    /** Unique handler identifier */
+    id: string;
+    /** Human-readable description */
+    description?: string;
+    /** The handler function */
+    handler: WorkflowStep<TInput>["handler"];
+    /** Tags for categorization */
+    tags?: string[];
+}
+/**
+ * Registry for step handlers.
+ * Allows recipes to reference handlers by ID.
+ */
+interface StepHandlerRegistry {
+    /**
+     * Register a step handler.
+     */
+    register<TInput = Record<string, unknown>>(handler: RegisteredStepHandler<TInput>): void;
+    /**
+     * Get a handler by ID.
+     */
+    get(id: string): RegisteredStepHandler | undefined;
+    /**
+     * Check if a handler exists.
+     */
+    has(id: string): boolean;
+    /**
+     * List all registered handlers.
+     */
+    list(): RegisteredStepHandler[];
+    /**
+     * List handlers by tag.
+     */
+    listByTag(tag: string): RegisteredStepHandler[];
+}
+/**
+ * Options for querying recipes.
+ */
+interface RecipeQueryOptions {
+    /** Filter by workflow kind */
+    workflowKind?: WorkflowKind;
+    /** Filter by variant */
+    variant?: string;
+    /** Filter by tags (any match) */
+    tags?: string[];
+    /** Only include recipes matching conditions */
+    matchConditions?: Record<string, unknown>;
+}
+/**
+ * Registry for recipes.
+ */
+interface RecipeRegistry {
+    /**
+     * Register a recipe.
+     */
+    register(recipe: Recipe): void;
+    /**
+     * Register multiple recipes.
+     */
+    registerAll(recipes: Recipe[]): void;
+    /**
+     * Get a recipe by ID.
+     */
+    get(recipeId: string): Recipe | undefined;
+    /**
+     * Check if a recipe exists.
+     */
+    has(recipeId: string): boolean;
+    /**
+     * Get all recipes for a workflow kind.
+     */
+    getByKind(workflowKind: WorkflowKind): Recipe[];
+    /**
+     * Get a specific variant for a workflow kind.
+     */
+    getVariant(workflowKind: WorkflowKind, variant: string): Recipe | undefined;
+    /**
+     * Get the default recipe for a workflow kind.
+     */
+    getDefault(workflowKind: WorkflowKind): Recipe | undefined;
+    /**
+     * List all available variants for a workflow kind.
+     */
+    listVariants(workflowKind: WorkflowKind): string[];
+    /**
+     * Query recipes with filters.
+     */
+    query(options: RecipeQueryOptions): Recipe[];
+    /**
+     * List all registered recipes.
+     */
+    list(): Recipe[];
+}
+
+/**
+ * Recipe and Step Handler registries.
+ * Provides storage and retrieval of recipes and handlers.
+ */
+
+/**
+ * In-memory implementation of the step handler registry.
+ */
+declare class MemoryStepHandlerRegistry implements StepHandlerRegistry {
+    private handlers;
+    private tagIndex;
+    /** Register a step handler. Throws if a handler with the same ID is already registered. */
+    register<TInput = Record<string, unknown>>(handler: RegisteredStepHandler<TInput>): void;
+    /** Get a handler by its unique ID, or undefined if not registered. */
+    get(id: string): RegisteredStepHandler | undefined;
+    /** Check whether a handler with the given ID is registered. */
+    has(id: string): boolean;
+    /** List all registered step handlers. */
+    list(): RegisteredStepHandler[];
+    /** List all handlers tagged with the given tag. */
+    listByTag(tag: string): RegisteredStepHandler[];
+    /**
+     * Resolve a handler reference to a WorkflowStep handler function.
+     * Returns undefined if the handler is not found.
+     */
+    resolve(handlerRef: string): WorkflowStep["handler"] | undefined;
+    /**
+     * Clear all registered handlers (useful for testing).
+     */
+    clear(): void;
+}
+/**
+ * In-memory implementation of the recipe registry.
+ */
+declare class MemoryRecipeRegistry implements RecipeRegistry {
+    private recipes;
+    private kindIndex;
+    private variantIndex;
+    private tagIndex;
+    /** Register a single recipe. Throws if a recipe with the same ID or kind:variant pair is already registered. */
+    register(recipe: Recipe): void;
+    /** Register multiple recipes at once. */
+    registerAll(recipes: Recipe[]): void;
+    /** Get a recipe by its unique ID, or undefined if not registered. */
+    get(recipeId: string): Recipe | undefined;
+    /** Check whether a recipe with the given ID is registered. */
+    has(recipeId: string): boolean;
+    /** Get all recipes registered for a given workflow kind. */
+    getByKind(workflowKind: WorkflowKind): Recipe[];
+    /** Get the recipe for a specific workflow kind and variant combination. */
+    getVariant(workflowKind: WorkflowKind, variant: string): Recipe | undefined;
+    /**
+     * Get the default recipe for a workflow kind.
+     * Returns the 'default' variant if one exists, otherwise falls back to the
+     * recipe with the lowest numeric priority value (lower number = higher precedence).
+     */
+    getDefault(workflowKind: WorkflowKind): Recipe | undefined;
+    /** List all variant names registered for a workflow kind. */
+    listVariants(workflowKind: WorkflowKind): string[];
+    /** Query recipes with optional filters for kind, variant, tags, and input conditions. */
+    query(options: RecipeQueryOptions): Recipe[];
+    /** List all registered recipes. */
+    list(): Recipe[];
+    /**
+     * Clear all registered recipes (useful for testing).
+     */
+    clear(): void;
+    /**
+     * Evaluate recipe conditions against an input.
+     * Returns true if all conditions match.
+     *
+     * Note: This intentionally mirrors the condition evaluation in planner.ts
+     * to keep registry queries independent of the planner implementation.
+     */
+    private evaluateConditions;
+    /**
+     * Get a nested value from an object using dot notation.
+     */
+    private getNestedValue;
+    /**
+     * Evaluate a single condition.
+     */
+    private evaluateCondition;
+}
+/**
+ * Create a combined registry that holds both recipes and step handlers.
+ */
+interface CombinedRegistry {
+    recipes: MemoryRecipeRegistry;
+    handlers: MemoryStepHandlerRegistry;
+}
+/**
+ * Create a new combined registry instance.
+ */
+declare function createRegistry(): CombinedRegistry;
+
+/**
+ * Rule-based planner implementation.
+ * Selects recipes and generates plans based on conditions and input analysis.
+ */
+
+/**
+ * Configuration for the RuleBasedPlanner.
+ */
+interface RuleBasedPlannerConfig {
+    /** Recipe registry to use */
+    recipeRegistry: RecipeRegistry;
+    /** Step handler registry for validation */
+    handlerRegistry?: StepHandlerRegistry;
+    /** Whether to validate handler references during planning */
+    validateHandlers?: boolean;
+    /** Resource estimation defaults (used by estimateResources) */
+    resourceEstimates?: {
+        /** Estimated API calls per step (default: 1) */
+        apiCallsPerStep?: number;
+        /** Estimated tokens per step (default: 500) */
+        tokensPerStep?: number;
+        /** Estimated duration per step in ms (default: 2000) */
+        durationPerStep?: number;
+        /** Estimated API calls per child workflow (default: 5) */
+        apiCallsPerChild?: number;
+    };
+}
+/**
+ * Rule-based planner that selects recipes based on condition matching.
+ */
+declare class RuleBasedPlanner implements Planner {
+    private recipeRegistry;
+    private handlerRegistry?;
+    private validateHandlers;
+    private resourceEstimates;
+    constructor(config: RuleBasedPlannerConfig);
+    /**
+     * Select the best recipe for a workflow kind and input.
+     */
+    selectRecipe(workflowKind: WorkflowKind, input: Record<string, unknown>, context?: PlanningContext): Promise<RecipeSelectionResult>;
+    /**
+     * Generate a plan from a recipe and input.
+     */
+    generatePlan(recipe: Recipe, input: Record<string, unknown>, context?: PlanningContext): Promise<Plan>;
+    /**
+     * Combined operation: select recipe and generate plan.
+     */
+    plan(workflowKind: WorkflowKind, input: Record<string, unknown>, context?: PlanningContext): Promise<Plan>;
+    /**
+     * Validate a plan before execution.
+     */
+    validatePlan(plan: Plan): PlanValidationResult;
+    /**
+     * Estimate resources required for a plan.
+     */
+    estimateResources(plan: Plan): ResourceEstimate;
+    /**
+     * Convert a recipe step to a planned step.
+     */
+    private recipeStepToPlannedStep;
+    /**
+     * Apply constraints to steps and generate modifications.
+     */
+    private applyConstraints;
+    /**
+     * Build a human-readable selection reason.
+     */
+    private buildSelectionReason;
+    /**
+     * Build reasoning text for a plan.
+     */
+    private buildPlanReasoning;
+}
+
+export { type ChildWorkflowPlan, type CombinedRegistry, type ConditionOperator, ConsoleLogger, DEFAULT_RETRY_OPTIONS, type LogLevel, Logger, MemoryRecipeRegistry, MemoryStepHandlerRegistry, type Plan, type PlanModification, type PlanModificationType, type PlanValidationResult, type PlannedStep, type Planner, type PlanningConstraints, type PlanningContext, type PlanningHints, type PlanningPriority, type Recipe, type RecipeCondition, type RecipeDefaults, type RecipeQueryOptions, type RecipeRegistry, type RecipeSelectionResult, type RecipeStep, type RegisteredStepHandler, type ResourceEstimate, type RetryOptions, RuleBasedPlanner, type RuleBasedPlannerConfig, RunNotFoundError, SilentLogger, StepError, StepErrorStrategy, type StepHandlerRef, type StepHandlerRegistry, StepTimeoutError, WaitForRunTimeoutError, WorkflowAlreadyRegisteredError, WorkflowCanceledError, WorkflowEngineError, WorkflowError, WorkflowKind, WorkflowNotFoundError, WorkflowStep, WorkflowTimeoutError, calculateRetryDelay, createRegistry, createScopedLogger, generateId, sanitizeErrorForStorage, sleep, withRetry };