@bratsos/workflow-engine 0.0.11 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,936 @@
+import { S as Stage, a as StageMetrics, W as WorkflowEventType, b as WorkflowSSEEvent, L as LogContext, A as AIHelper, M as ModelKey, c as LogLevel } from './client-5vz5Vv4A.js';
+export { d as AIBatch, e as AIBatchHandle, f as AIBatchProvider, g as AIBatchRequest, h as AIBatchResult, i as AICallType, j as AIEmbedResult, k as AIObjectResult, l as AIStreamResult, m as AITextResult, n as AVAILABLE_MODELS, o as AsyncBatchStageDefinition, B as BatchLogFn, D as DEFAULT_MODEL_KEY, E as EmbedOptions, p as EnhancedStageContext, I as InferInput, q as ModelConfig, r as ModelRegistry, s as ModelStats, t as ModelStatsTracker, u as ModelSyncConfig, N as NoInputSchema, O as ObjectOptions, R as RecordCallParams, v as SimpleStageResult, w as StageResult, x as StreamOptions, y as SyncStageDefinition, T as TextOptions, z as calculateCost, C as createAIHelper, F as defineAsyncBatchStage, G as defineStage, H as getDefaultModel, J as getModel, K as getModelById, P as getRegisteredModel, Q as listModels, U as listRegisteredModels, V as modelSupportsBatch, X as printAvailableModels, Y as registerModels, Z as requireStageOutput } from './client-5vz5Vv4A.js';
+import z$1, { z } from 'zod';
+import { EventEmitter } from 'node:events';
+import { W as WorkflowPersistence, A as AICallLogger, J as JobQueue } from './interface-Cv22wvLG.js';
+export { b as AICallRecord, a as AIHelperStats, p as ArtifactType, C as CreateAICallInput, m as CreateLogInput, e as CreateRunInput, h as CreateStageInput, D as DequeueResult, E as EnqueueJobInput, c as JobRecord, d as JobStatus, L as LogLevel, S as SaveArtifactInput, q as Status, U as UpdateRunInput, k as UpdateStageInput, j as UpsertStageInput, n as WorkflowArtifactRecord, o as WorkflowLogRecord, f as WorkflowRunRecord, i as WorkflowStageRecord, l as WorkflowStageStatus, g as WorkflowStatus } from './interface-Cv22wvLG.js';
+export { P as PrismaAICallLogger, a as PrismaJobQueue, c as PrismaWorkflowPersistence, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from './index-DmR3E8D7.js';
+import { ToolSet } from 'ai';
+
+/**
+ * Workflow Builder - Fluent API for composing type-safe workflows
+ *
+ * Workflows are composed of stages that are executed sequentially or in parallel.
+ * The builder ensures type safety: output of one stage matches input of next stage.
+ *
+ * ## Type System Features
+ *
+ * ### Automatic Context Inference
+ * The workflow context type is automatically accumulated as you pipe stages.
+ * Use `InferWorkflowContext<typeof workflow>` to extract the context type.
+ *
+ * ```typescript
+ * const workflow = new WorkflowBuilder(...)
+ *   .pipe(stage1)
+ *   .pipe(stage2)
+ *   .build();
+ *
+ * // Auto-generated type
+ * type MyContext = InferWorkflowContext<typeof workflow>;
+ * // = { "stage-1": Stage1Output, "stage-2": Stage2Output }
+ * ```
+ *
+ * ### Stage ID Constants
+ * Use `workflow.stageIds` for type-safe stage ID references.
+ */
+
+interface StageNode {
+    stage: Stage<any, any, any>;
+    executionGroup: number;
+}
+declare class Workflow<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, TContext extends Record<string, unknown> = {}> {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TInput;
+    readonly outputSchema: TOutput;
+    private readonly stages;
+    readonly contextType?: TContext | undefined;
+    constructor(id: string, name: string, description: string, inputSchema: TInput, outputSchema: TOutput, stages: StageNode[], contextType?: TContext | undefined);
+    /**
+     * Get execution plan as groups of stages
+     * Stages in the same group can be executed in parallel
+     */
+    getExecutionPlan(): StageNode[][];
+    /**
+     * Get a specific stage by ID
+     */
+    getStage(stageId: string): Stage<any, any, any> | undefined;
+    /**
+     * Get all stages in order
+     */
+    getAllStages(): StageNode[];
+    /**
+     * Get a visual representation of the workflow execution order
+     */
+    getExecutionOrder(): string;
+    /**
+     * Get all stage IDs in execution order
+     *
+     * @returns Array of stage IDs
+     *
+     * @example
+     * ```typescript
+     * const ids = workflow.getStageIds();
+     * // ["data-extraction", "guidelines", "generator"]
+     * ```
+     */
+    getStageIds(): string[];
+    /**
+     * Check if a stage ID exists in this workflow
+     *
+     * @param stageId - The stage ID to check
+     * @returns true if the stage exists
+     */
+    hasStage(stageId: string): boolean;
+    /**
+     * Validate workflow configuration before execution
+     * Checks that all stage configs match their schemas
+     *
+     * @param config - Configuration object with keys matching stage IDs
+     * @returns Validation result with any errors
+     */
+    validateConfig(config: Record<string, unknown>): {
+        valid: boolean;
+        errors: Array<{
+            stageId: string;
+            error: string;
+        }>;
+    };
+    /**
+     * Estimate total cost for the workflow
+     */
+    estimateCost(input: z.infer<TInput>, config: Record<string, unknown>): number;
+    /**
+     * Get configuration schemas for all stages in this workflow
+     * Returns a map of stageId → { schema, defaults, name, description }
+     */
+    getStageConfigs(): Record<string, {
+        schema: z.ZodTypeAny;
+        defaults: Record<string, unknown>;
+        name: string;
+        description?: string;
+    }>;
+    /**
+     * Generate default configuration object for all stages
+     * Automatically discovers all stage configs - add/remove stages and this updates automatically
+     */
+    getDefaultConfig(): Record<string, Record<string, unknown>>;
+    /**
+     * Get all stages in a specific execution group
+     */
+    getStagesInExecutionGroup(groupIndex: number): Stage<any, any, any>[];
+    /**
+     * Get the sequential index of a stage (0-based)
+     */
+    getStageIndex(stageId: string): number;
+    /**
+     * Get the execution group index for a stage
+     */
+    getExecutionGroupIndex(stageId: string): number;
+    /**
+     * Get the ID of the stage immediately preceding the given stage
+     */
+    getPreviousStageId(stageId: string): string | undefined;
+}
+declare class WorkflowBuilder<TInput extends z.ZodTypeAny, TCurrentOutput extends z.ZodTypeAny, TContext extends Record<string, unknown> = {}> {
+    private id;
+    private name;
+    private description;
+    private inputSchema;
+    private currentOutputSchema;
+    private stages;
+    private currentExecutionGroup;
+    constructor(id: string, name: string, description: string, inputSchema: TInput, currentOutputSchema: TCurrentOutput);
+    /**
+     * Add a stage to the workflow (sequential execution)
+     *
+     * Automatically accumulates the stage's output in the context under its stage ID.
+     * This provides type-safe access to all previous stage outputs.
+     *
+     * Note: This accepts any stage regardless of strict input type matching.
+     * This is necessary because stages using passthrough() can accept objects
+     * with additional fields beyond what's declared in their input schema.
+     * Runtime validation via Zod ensures type safety at execution time.
+     *
+     * Validates that all declared dependencies exist in the workflow.
+     */
+    pipe<TStageInput extends z.ZodTypeAny, TStageOutput extends z.ZodTypeAny, TStageConfig extends z.ZodTypeAny, TStageContext extends Record<string, unknown>>(stage: Stage<TStageInput, TStageOutput, TStageConfig, TStageContext>): WorkflowBuilder<TInput, TStageOutput, TContext & {
+        [x: string]: z.infer<TStageOutput>;
+    }>;
+    /**
+     * Add a stage with strict input type checking
+     *
+     * Note: pipeStrict() and pipeLoose() have been removed as they were
+     * just aliases for pipe(). Use pipe() for all stage chaining.
+     */
+    /**
+     * Add multiple stages that execute in parallel
+     *
+     * All stages receive the same input (current output)
+     * Their outputs are merged into an object by index AND accumulated in context by stage ID.
+     *
+     * Note: This accepts stages regardless of strict input type matching.
+     * This is necessary because stages using passthrough() can accept objects
+     * with additional fields. Runtime validation via Zod ensures type safety.
+     *
+     * Validates that all declared dependencies exist in the workflow.
+     */
+    parallel<TStages extends {
+        id: string;
+        outputSchema: z.ZodTypeAny;
+        dependencies?: string[];
+    }[]>(stages: [...TStages]): WorkflowBuilder<TInput, z.ZodTypeAny, TContext & {
+        [K in TStages[number]["id"]]: TStages[number] extends {
+            outputSchema: infer O;
+        } ? O extends z.ZodTypeAny ? z.infer<O> : never : never;
+    }>;
+    /**
+     * Build the final workflow
+     */
+    build(): Workflow<TInput, TCurrentOutput, TContext>;
+    /**
+     * Get current stage count
+     */
+    getStageCount(): number;
+    /**
+     * Get execution group count
+     */
+    getExecutionGroupCount(): number;
+}
+/**
+ * Extract stage IDs as a union type from a Workflow instance
+ *
+ * Useful for creating type-safe stage ID references.
+ *
+ * @example
+ * ```typescript
+ * type StageId = InferWorkflowStageIds<typeof myWorkflow>;
+ * // = "data-extraction" | "guidelines" | "generator"
+ *
+ * function getStageOutput(stageId: StageId) { ... }
+ * ```
+ */
+type InferWorkflowStageIds<W> = W extends Workflow<any, any, infer C> ? keyof C & string : never;
+
+/**
+ * Workflow Executor - Executes workflows with support for resume and suspension
+ *
+ * Key features:
+ * - Sequential and parallel stage execution
+ * - Automatic state persistence to R2 and database
+ * - Resume from last completed stage
+ * - Suspend/resume for long-running batch jobs
+ * - Event emission for real-time updates
+ *
+ * Note: Stages should import createAIHelper directly from ~/lib/ai-helper
+ * and create their own AI helper instances with appropriate topics.
+ * The executor creates a helper for tracking aggregate stats per stage.
+ */
+
+interface WorkflowExecutorOptions {
+    persistence?: WorkflowPersistence;
+    /** Optional AI call logger. If not provided, AI tracking is disabled. */
+    aiLogger?: AICallLogger;
+}
+declare class WorkflowExecutor extends EventEmitter {
+    private workflow;
+    private workflowRunId;
+    private workflowType;
+    private cancelled;
+    private persistence;
+    private aiLogger;
+    constructor(workflow: Workflow<any, any>, workflowRunId: string, workflowType: string, storageProviderOrOptions?: WorkflowExecutorOptions);
+    /**
+     * Override emit to also forward events to the global event bus for SSE
+     */
+    emit(eventName: string | symbol, ...args: any[]): boolean;
+    /**
+     * Check if the workflow has been interrupted (cancelled or suspended) externally
+     * This checks the database status to detect external requests
+     */
+    private checkExternalInterruption;
+    /**
+     * Execute the workflow
+     *
+     * @param input - Workflow input data
+     * @param config - Configuration for each stage (keyed by stage ID)
+     * @param options - Execution options (resume, etc.)
+     * @returns Final output or 'suspended' if workflow is suspended
+     */
+    execute<TInput, TOutput>(input: TInput, config: Record<string, unknown>, options?: {
+        resume?: boolean;
+        fromStage?: string;
+    }): Promise<TOutput | "suspended">;
+    /**
+     * Execute a single stage
+     */
+    private executeStage;
+    /**
+     * Load resume state from database
+     */
+    private loadResumeState;
+    /**
+     * Load workflow context from all completed stages
+     * This rebuilds the workflowContext object so resumed stages can access previous outputs
+     */
+    private loadWorkflowContext;
+    /**
+     * Load state for rerunning from a specific stage.
+     * Requires that previous stages have already been executed and their outputs persisted.
+     *
+     * @param stageId - The stage ID to start execution from
+     * @returns The execution group, input data, and workflow context
+     */
+    private loadFromStageState;
+    /**
+     * Create a minimal storage shim for context.storage (for API compatibility).
+     * Stage implementations should not rely on this - it may be removed in future.
+     */
+    private createStorageShim;
+    /**
+     * Get aggregated statistics for the workflow run
+     */
+    private getAggregatedStats;
+    /**
+     * Log a message with automatic database persistence
+     */
+    private log;
+}
+
+/**
+ * Stage Executor - Executes a single stage
+ *
+ * Unlike WorkflowExecutor which runs entire workflows,
+ * this executes exactly ONE stage and returns.
+ *
+ * Designed for distributed workers.
+ */
+
+interface WorkflowRegistry {
+    getWorkflow(id: string): Workflow<any, any> | undefined;
+}
+interface StageExecutionRequest {
+    workflowRunId: string;
+    workflowId: string;
+    stageId: string;
+    config: Record<string, unknown>;
+}
+interface StageExecutionResult {
+    type: "completed" | "suspended" | "failed";
+    output?: unknown;
+    suspendedState?: unknown;
+    nextPollAt?: Date;
+    error?: string;
+    metrics?: StageMetrics;
+}
+declare class StageExecutor {
+    private registry;
+    private persistence;
+    private workerId;
+    constructor(registry: WorkflowRegistry, persistence: WorkflowPersistence, workerId?: string);
+    /**
+     * Execute a single stage
+     */
+    execute(request: StageExecutionRequest): Promise<StageExecutionResult>;
+    private handleCompleted;
+    private handleSuspended;
+    private handleFailed;
+    private loadWorkflowContext;
+    /**
+     * Create a minimal storage shim for context.storage (for API compatibility).
+     * Stage implementations should not rely on this - it may be removed in future.
+     */
+    private createStorageShim;
+    private resolveStageInput;
+    private getStageNumber;
+    private getExecutionGroup;
+    private log;
+}
+
+/**
+ * Storage abstraction for stage artifacts and outputs
+ *
+ * Modified to support Prisma/Memory storage only (R2 removed)
+ */
+interface StageStorage {
+    /**
+     * Save data to storage
+     */
+    save<T>(key: string, data: T): Promise<void>;
+    /**
+     * Load data from storage
+     */
+    load<T>(key: string): Promise<T>;
+    /**
+     * Check if key exists in storage
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Delete data from storage
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Generate a storage key for a stage
+     */
+    getStageKey(stageId: string, suffix?: string): string;
+    /**
+     * Save stage output with standard key
+     */
+    saveStageOutput<T>(stageId: string, output: T): Promise<string>;
+    /**
+     * Load stage output with standard key
+     */
+    loadStageOutput<T>(stageId: string): Promise<T>;
+    /**
+     * Save arbitrary artifact for a stage
+     */
+    saveArtifact<T>(stageId: string, artifactName: string, data: T): Promise<string>;
+    /**
+     * Load arbitrary artifact for a stage
+     */
+    loadArtifact<T>(stageId: string, artifactName: string): Promise<T>;
+    /**
+     * List all artifacts for a workflow run (for export)
+     */
+    listAllArtifacts(): Promise<Array<{
+        key: string;
+        stageId: string;
+        name: string;
+    }>>;
+    /**
+     * Provider metadata
+     */
+    readonly providerType: "prisma" | "memory";
+}
+
+/**
+ * Factory for creating storage provider instances
+ *
+ * Prisma storage requires a PrismaClient to be passed via options.
+ */
+
+type PrismaClient = any;
+type StorageProviderType = "prisma" | "memory";
+interface StorageFactoryOptions {
+    provider: StorageProviderType;
+    workflowRunId: string;
+    workflowType: string;
+    /** Required when provider is "prisma" */
+    prisma?: PrismaClient;
+}
+/**
+ * Create a storage instance based on the provider type
+ */
+declare function createStorage(options: StorageFactoryOptions): StageStorage;
+/**
+ * Get default provider from environment or config
+ * Falls back to 'prisma' for database-backed persistence
+ */
+declare function getDefaultStorageProvider(): StorageProviderType;
+
+/**
+ * Workflow Event Bus - Global event emitter for workflow events
+ *
+ * This singleton allows SSE endpoints to subscribe to real-time workflow events
+ * emitted by WorkflowExecutor instances running in the same process.
+ *
+ * Supports cross-process events via PostgreSQL LISTEN/NOTIFY when enabled.
+ *
+ * Events are namespaced by workflowRunId:
+ * - workflow:{runId}:stage:started
+ * - workflow:{runId}:stage:completed
+ * - workflow:{runId}:log
+ * - etc.
+ */
+
+/**
+ * Interface matching PgNotify from @zertai/database
+ * Defined here to avoid importing the database package into workflow-engine
+ */
+interface PgNotifyLike {
+    listen(channel: string, handler: (channel: string, payload: string) => void): Promise<() => void>;
+    notify(channel: string, payload: string): Promise<void>;
+    isConnected(): boolean;
+}
+declare class WorkflowEventBus extends EventEmitter {
+    private static instance;
+    private pgNotify;
+    private static readonly PG_CHANNEL;
+    private pgListenerUnsubscribe;
+    private static readonly MAX_PAYLOAD_SIZE;
+    private constructor();
+    static getInstance(): WorkflowEventBus;
+    /**
+     * Enable cross-process event publishing via PostgreSQL NOTIFY
+     *
+     * Call this during process initialization to enable events to propagate
+     * across multiple workers and the React Router app.
+     *
+     * @param pgNotify - A connected PgNotify instance from @zertai/database
+     */
+    enablePgNotify(pgNotify: PgNotifyLike): Promise<void>;
+    /**
+     * Disable cross-process events (for cleanup)
+     */
+    disablePgNotify(): void;
+    /**
+     * Check if cross-process events are enabled
+     */
+    isPgNotifyEnabled(): boolean;
+    /**
+     * Truncate event payload to fit within PostgreSQL NOTIFY size limits.
+     * Large data fields (like workflow output) are replaced with a truncation marker.
+     */
+    private truncatePayloadForNotify;
+    /**
+     * Emit event locally only (used for re-emitting pg notifications)
+     */
+    private emitLocally;
+    /**
+     * Emit a workflow event with proper namespacing
+     *
+     * When PgNotify is enabled, also publishes to PostgreSQL for cross-process
+     * consumption by other workers and the React Router app.
+     */
+    emitWorkflowEvent(workflowRunId: string, eventType: WorkflowEventType, payload: Record<string, unknown>): void;
+    /**
+     * Subscribe to all events for a specific workflow run
+     */
+    subscribeToWorkflow(workflowRunId: string, handler: (event: WorkflowSSEEvent) => void): () => void;
+    /**
+     * Subscribe to a specific event type globally (across all workflows)
+     */
+    subscribeGlobal(eventType: WorkflowEventType, handler: (event: WorkflowSSEEvent) => void): () => void;
+    /**
+     * Subscribe to a specific event type for a workflow
+     */
+    subscribeToEvent(workflowRunId: string, eventType: WorkflowEventType, handler: (event: WorkflowSSEEvent) => void): () => void;
+}
+declare const workflowEventBus: WorkflowEventBus;
+
+/**
+ * Workflow Runtime - Unified API for workflow execution
+ *
+ * The main entry point for the workflow engine. Handles everything:
+ * - Creating new workflow runs (with validation)
+ * - Polling for pending workflows → enqueuing first stage
+ * - Processing jobs from the queue (executing stages)
+ * - Polling for suspended stages → resuming execution
+ * - Transitioning workflows between stages
+ */
+
+interface WorkflowRuntimeConfig {
+    /** Persistence implementation */
+    persistence: WorkflowPersistence;
+    /** Job queue implementation */
+    jobQueue: JobQueue;
+    /** Workflow registry */
+    registry: WorkflowRegistry;
+    /** AI call logger for createAIHelper */
+    aiCallLogger?: AICallLogger;
+    /** Interval between poll cycles in milliseconds (default: 10000) */
+    pollIntervalMs?: number;
+    /** Interval between job dequeue attempts in milliseconds (default: 1000) */
+    jobPollIntervalMs?: number;
+    /** Worker ID (default: auto-generated) */
+    workerId?: string;
+    /** Stale job threshold in milliseconds (default: 60000) */
+    staleJobThresholdMs?: number;
+    /** Function to determine workflow priority */
+    getWorkflowPriority?: (workflowId: string) => number;
+}
+interface CreateRunOptions {
+    workflowId: string;
+    input: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    priority?: number;
+    /** Domain-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+interface CreateRunResult {
+    workflowRunId: string;
+}
+declare class WorkflowRuntime {
+    private isPolling;
+    private isProcessingJobs;
+    private isRunning;
+    private pollIntervalMs;
+    private jobPollIntervalMs;
+    private staleJobThresholdMs;
+    private workerId;
+    private persistence;
+    private jobQueue;
+    private registry;
+    private aiCallLogger?;
+    private getWorkflowPriority?;
+    private pollTimer;
+    private stageExecutor;
+    private jobsProcessed;
+    constructor(config: WorkflowRuntimeConfig);
+    /**
+     * Create an AI helper bound to this runtime's logger
+     * @param topic - Topic for logging (e.g., "workflow.abc123.stage.extraction")
+     * @param logContext - Optional log context for persistence logging in batch operations
+     */
+    createAIHelper(topic: string, logContext?: LogContext): AIHelper;
+    /**
+     * Create a LogContext for a workflow stage (for use with createAIHelper)
+     * This enables batch operations to log to the workflow persistence.
+     */
+    createLogContext(workflowRunId: string, stageRecordId: string): LogContext;
+    /**
+     * Start the runtime as a full worker (processes jobs + polls)
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the runtime
+     */
+    stop(): void;
+    /**
+     * Create a new workflow run with validation.
+     * The runtime will pick it up on the next poll cycle and start execution.
+     */
+    createRun(options: CreateRunOptions): Promise<CreateRunResult>;
+    /**
+     * Process jobs from the queue
+     */
+    private processJobs;
+    private getWorkflowId;
+    /**
+     * Poll for pending workflows and suspended stages
+     */
+    private poll;
+    /**
+     * Poll for pending workflows and enqueue their first stage.
+     * Uses claimNextPendingRun() for zero-contention claiming with FOR UPDATE SKIP LOCKED.
+     */
+    private pollPendingWorkflows;
+    /**
+     * Poll suspended stages and resume if ready (public for manual triggering)
+     */
+    pollSuspendedStages(): Promise<void>;
+    /**
+     * Transition a workflow to its next state (public for external calls)
+     */
+    transitionWorkflow(workflowRunId: string): Promise<void>;
+    private checkAndResume;
+    private resumeWorkflow;
+    /**
+     * Create a minimal storage shim for context.storage (for API compatibility).
+     */
+    private createStorageShim;
+    private markStageFailed;
+    private enqueueExecutionGroup;
+    private completeWorkflow;
+}
+/**
+ * Factory function to create a WorkflowRuntime instance
+ */
+declare function createWorkflowRuntime(config: WorkflowRuntimeConfig): WorkflowRuntime;
+
+/**
+ * Model Mapping for Batch Providers
+ *
+ * Dynamically maps models from the registry to provider-specific batch API identifiers.
+ * Uses the `supportsAsyncBatch` flag and OpenRouter ID prefix to determine compatibility.
+ */
+
+declare const BatchProviderName: z$1.ZodEnum<{
+    google: "google";
+    anthropic: "anthropic";
+    openai: "openai";
+}>;
+type BatchProviderName = z$1.infer<typeof BatchProviderName>;
+/**
+ * Get the provider-specific model ID, with fallback to default
+ *
+ * @param modelKey - The ModelKey from model-helper.ts (optional)
+ * @param provider - The batch provider
+ * @returns Provider-specific model ID
+ * @throws Error if model is not supported by the provider
+ */
+declare function resolveModelForProvider(modelKey: ModelKey | undefined, provider: BatchProviderName): string;
+/**
+ * Get the best provider for a given ModelKey
+ * Returns the provider that natively supports the model
+ */
+declare function getBestProviderForModel(modelKey: ModelKey): BatchProviderName | undefined;
+
+/**
+ * Low-Level Batch Provider Types
+ *
+ * These types are used internally by batch providers (Google, Anthropic, OpenAI).
+ * They have more fields than the high-level user-facing types in ai/ai-helper.ts.
+ *
+ * For the user-facing batch API, see:
+ * - AIBatchRequest - simple request with id, prompt, schema
+ * - AIBatchResult<T> - result with id, result, tokens
+ * - AIBatchHandle - handle with id, status, provider
+ *
+ * These provider-level types include additional fields like:
+ * - BatchHandle: requestCount, createdAt, metadata
+ * - BaseBatchRequest: model, system, maxTokens, temperature, tools
+ * - RawBatchResult: raw text before parsing, index
+ */
+
+/** Tool choice options compatible with AI SDK */
+type BatchToolChoice = "auto" | "required" | "none" | {
+    type: "tool";
+    toolName: string;
+};
+/**
+ * Handle returned when a batch is submitted
+ */
+interface BatchHandle {
+    /** Unique identifier for the batch (provider-specific format) */
+    id: string;
+    /** Provider name (google, anthropic, openai) */
+    provider: string;
+    /** Number of requests in the batch */
+    requestCount: number;
+    /** When the batch was created */
+    createdAt: Date;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Status of a batch job
+ */
+interface BatchStatus {
+    /** Current state of the batch */
+    state: BatchState;
+    /** Number of requests processed so far */
+    processedCount: number;
+    /** Total number of requests in the batch */
+    totalCount: number;
+    /** Number of successful requests (if available) */
+    succeededCount?: number;
+    /** Number of failed requests (if available) */
+    failedCount?: number;
+    /** Error message if batch failed */
+    error?: string;
+    /** Estimated completion time (if available) */
+    estimatedCompletion?: Date;
+    /** Total input tokens used (available when batch is complete) */
+    totalInputTokens?: number;
+    /** Total output tokens used (available when batch is complete) */
+    totalOutputTokens?: number;
+}
+type BatchState = "pending" | "processing" | "completed" | "failed" | "cancelled";
+/**
+ * Result of a single request in a batch
+ */
+interface BatchResult<T> {
+    /** Index in the original request array */
+    index: number;
+    /** Custom ID if provided */
+    customId?: string;
+    /** Parsed/validated data */
+    data: T;
+    /** Input tokens used */
+    inputTokens: number;
+    /** Output tokens used */
+    outputTokens: number;
+    /** Status of this individual result */
+    status: "succeeded" | "failed";
+    /** Error message if this specific request failed */
+    error?: string;
+}
+/**
+ * Raw result from a provider (before schema validation)
+ */
+interface RawBatchResult {
+    index: number;
+    customId?: string;
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    error?: string;
+}
+/**
+ * Base request configuration shared across providers
+ */
+interface BaseBatchRequest {
+    /** The prompt/content to send */
+    prompt: string;
+    /** Optional custom ID for tracking */
+    customId?: string;
+    /** Model to use - accepts ModelKey from model-helper.ts */
+    model?: ModelKey;
+    /** System prompt (if supported) */
+    system?: string;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for generation */
+    temperature?: number;
+    /** Optional Zod schema for structured output */
+    schema?: z.ZodTypeAny;
+    /** Tool definitions (same as AI SDK generateText/streamText) */
+    tools?: ToolSet;
+    /** Tool choice mode */
+    toolChoice?: BatchToolChoice;
+}
+/**
+ * Request with schema for structured output
+ */
+interface BatchRequestWithSchema<TSchema extends z.ZodTypeAny> extends BaseBatchRequest {
+    schema: TSchema;
+}
+/**
+ * Request without schema (plain text output)
+ */
+interface BatchRequestText extends BaseBatchRequest {
+    schema?: never;
+}
+/**
+ * Union type for batch requests
+ */
+type BatchRequest<TSchema extends z.ZodTypeAny = z.ZodTypeAny> = BatchRequestWithSchema<TSchema> | BatchRequestText;
+/**
+ * Interface that all batch providers must implement
+ */
+interface BatchProvider<TRequest extends BaseBatchRequest = BaseBatchRequest, TRawResult extends RawBatchResult = RawBatchResult> {
+    /** Provider name (google, anthropic, openai) */
+    readonly name: string;
+    /** Whether this provider supports batching */
+    readonly supportsBatching: boolean;
+    /**
+     * Submit requests to batch processing
+     * @param requests Array of requests to process
+     * @param options Provider-specific options
+     * @returns Handle to track the batch
+     */
+    submit(requests: TRequest[], options?: BatchSubmitOptions): Promise<BatchHandle>;
+    /**
+     * Check the status of a batch
+     * @param handle Batch handle from submit()
+     * @returns Current status
+     */
+    checkStatus(handle: BatchHandle): Promise<BatchStatus>;
+    /**
+     * Retrieve results from a completed batch
+     * @param handle Batch handle from submit()
+     * @returns Array of raw results
+     */
+    getResults(handle: BatchHandle): Promise<TRawResult[]>;
+    /**
+     * Cancel a running batch (optional - not all providers support this)
+     * @param handle Batch handle from submit()
+     */
+    cancel?(handle: BatchHandle): Promise<void>;
+}
+interface BatchSubmitOptions {
+    /** Display name for the batch (if supported) */
+    displayName?: string;
+    /** Completion window (e.g., "24h" for OpenAI) */
+    completionWindow?: string;
+    /** Custom metadata to attach */
+    metadata?: Record<string, string>;
+}
+/**
+ * Serialized batch for persistence during workflow suspension
+ */
+interface SerializedBatch {
+    handle: BatchHandle;
+    providerName: string;
+    /** Serialized schema definitions (if any) */
+    schemaDefinitions?: unknown[];
+}
+/**
+ * Logger interface for batch operations
+ */
+interface BatchLogger {
+    log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Aggregated metrics for a batch
+ */
+interface BatchMetrics {
+    provider: string;
+    model: string;
+    requestCount: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    estimatedCost: number;
+    actualDuration: number;
+    successRate: number;
+}
+interface GoogleBatchRequest extends BaseBatchRequest {
+}
+interface AnthropicBatchRequest extends BaseBatchRequest {
+}
+interface OpenAIBatchRequest extends BaseBatchRequest {
+}
+
+/**
+ * Google Batch Provider
+ *
+ * Implements batch processing using Google's GenAI Batch API.
+ * Uses inline requests for simpler API.
+ */
+
+interface GoogleBatchProviderConfig {
+    apiKey?: string;
+}
+declare class GoogleBatchProvider implements BatchProvider<GoogleBatchRequest, RawBatchResult> {
+    readonly name = "google";
+    readonly supportsBatching = true;
+    private ai;
+    private logger?;
+    constructor(config?: GoogleBatchProviderConfig, logger?: BatchLogger);
+    submit(requests: GoogleBatchRequest[], options?: BatchSubmitOptions): Promise<BatchHandle>;
+    checkStatus(handle: BatchHandle): Promise<BatchStatus>;
+    getResults(handle: BatchHandle, customIds?: string[]): Promise<RawBatchResult[]>;
+    cancel(handle: BatchHandle): Promise<void>;
+    private mapState;
+}
+
+/**
+ * Anthropic Batch Provider
+ *
+ * Implements batch processing using Anthropic's Message Batches API.
+ * Supports up to 10,000 requests per batch with 24h processing window.
+ */
+
+interface AnthropicBatchProviderConfig {
+    apiKey?: string;
+}
+declare class AnthropicBatchProvider implements BatchProvider<AnthropicBatchRequest, RawBatchResult> {
+    readonly name = "anthropic";
+    readonly supportsBatching = true;
+    private client;
+    private logger?;
+    constructor(config?: AnthropicBatchProviderConfig, logger?: BatchLogger);
+    submit(requests: AnthropicBatchRequest[], options?: BatchSubmitOptions): Promise<BatchHandle>;
+    checkStatus(handle: BatchHandle): Promise<BatchStatus>;
+    getResults(handle: BatchHandle): Promise<RawBatchResult[]>;
+    cancel(handle: BatchHandle): Promise<void>;
+    private mapStatus;
+}
+
+/**
+ * OpenAI Batch Provider
+ *
+ * Implements batch processing using OpenAI's Batch API.
+ * Note: OpenAI requires JSONL file uploads for batches.
+ * Supports up to 50,000 requests per batch with 24h processing window.
+ */
+
+interface OpenAIBatchProviderConfig {
+    apiKey?: string;
+}
+declare class OpenAIBatchProvider implements BatchProvider<OpenAIBatchRequest, RawBatchResult> {
+    readonly name = "openai";
+    readonly supportsBatching = true;
+    private client;
+    private logger?;
+    constructor(config?: OpenAIBatchProviderConfig, logger?: BatchLogger);
+    submit(requests: OpenAIBatchRequest[], options?: BatchSubmitOptions): Promise<BatchHandle>;
+    checkStatus(handle: BatchHandle): Promise<BatchStatus>;
+    getResults(handle: BatchHandle): Promise<RawBatchResult[]>;
+    cancel(handle: BatchHandle): Promise<void>;
+    private mapStatus;
+}
+
+export { AICallLogger, AIHelper, AnthropicBatchProvider, type AnthropicBatchProviderConfig, type AnthropicBatchRequest, type BaseBatchRequest, type BatchHandle, type BatchLogger, type BatchMetrics, type BatchProvider, type BatchRequest, type BatchRequestText, type BatchRequestWithSchema, type BatchResult, type BatchState, type BatchStatus, type BatchSubmitOptions, type CreateRunOptions, type CreateRunResult, GoogleBatchProvider, type GoogleBatchProviderConfig, type GoogleBatchRequest, type InferWorkflowStageIds, JobQueue, LogContext, ModelKey, OpenAIBatchProvider, type OpenAIBatchProviderConfig, type OpenAIBatchRequest, type PgNotifyLike, type RawBatchResult, type SerializedBatch, Stage, type StageExecutionRequest, type StageExecutionResult, StageExecutor, Workflow, WorkflowBuilder, WorkflowEventType, WorkflowExecutor, WorkflowPersistence, type WorkflowRegistry, WorkflowRuntime, type WorkflowRuntimeConfig, WorkflowSSEEvent, createStorage, createWorkflowRuntime, getBestProviderForModel, getDefaultStorageProvider, resolveModelForProvider, workflowEventBus };