@codebolt/agent 1.2.1 → 2.2.3

package/dist/composablepattern/workflow.d.ts

@@ -0,0 +1,388 @@
+/**
+ * @fileoverview Workflow system for Composable Agent Pattern
+ * @description Provides workflow orchestration for multi-step agent processes
+ */
+import type { ComposableAgent } from './types';
+import { z } from 'zod';
+export interface WorkflowContext {
+    /** Shared data between workflow steps */
+    data: Record<string, any>;
+    /** Execution history */
+    history: WorkflowStepResult[];
+    /** Current step index */
+    currentStep: number;
+    /** Workflow metadata */
+    metadata: Record<string, any>;
+}
+export interface WorkflowStepResult {
+    /** Step ID */
+    stepId: string;
+    /** Whether step succeeded */
+    success: boolean;
+    /** Step output data */
+    output?: any;
+    /** Error message if failed */
+    error?: string;
+    /** Step execution time */
+    executionTime: number;
+    /** Step metadata */
+    metadata?: Record<string, any>;
+}
+export interface WorkflowStep {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name: string;
+    /** Step description */
+    description?: string;
+    /** Input schema validation */
+    inputSchema?: z.ZodType;
+    /** Output schema validation */
+    outputSchema?: z.ZodType;
+    /** Step execution function */
+    execute: (context: WorkflowContext) => Promise<WorkflowStepResult>;
+    /** Condition to determine if step should run */
+    condition?: (context: WorkflowContext) => boolean | Promise<boolean>;
+    /** Steps that must complete before this step */
+    dependencies?: string[];
+    /** Whether step can run in parallel */
+    parallel?: boolean;
+    /** Retry configuration */
+    retry?: {
+        maxAttempts: number;
+        delay: number;
+        backoff?: 'linear' | 'exponential';
+    };
+}
+export interface WorkflowConfig {
+    /** Workflow name */
+    name: string;
+    /** Workflow description */
+    description?: string;
+    /** Workflow steps */
+    steps: WorkflowStep[];
+    /** Initial context data */
+    initialData?: Record<string, any>;
+    /** Workflow timeout in milliseconds */
+    timeout?: number;
+    /** Whether to continue on step failure */
+    continueOnError?: boolean;
+    /** Maximum parallel steps */
+    maxParallelSteps?: number;
+}
+export interface WorkflowResult {
+    /** Whether workflow completed successfully */
+    success: boolean;
+    /** Final context data */
+    data: Record<string, any>;
+    /** All step results */
+    stepResults: WorkflowStepResult[];
+    /** Total execution time */
+    executionTime: number;
+    /** Error message if failed */
+    error?: string;
+    /** Workflow metadata */
+    metadata: Record<string, any>;
+}
+/**
+ * Agent step - executes a composable agent
+ */
+export interface AgentStepConfig {
+    /** Agent instance to execute */
+    agent: ComposableAgent;
+    /** Message template (can use context variables) */
+    messageTemplate: string;
+    /** Input mapping from context */
+    inputMapping?: Record<string, string>;
+    /** Output mapping to context */
+    outputMapping?: Record<string, string>;
+}
+/**
+ * Conditional step - executes different branches based on condition
+ */
+export interface ConditionalStepConfig {
+    /** Condition function */
+    condition: (context: WorkflowContext) => boolean | Promise<boolean>;
+    /** Steps to execute if condition is true */
+    trueBranch: WorkflowStep[];
+    /** Steps to execute if condition is false */
+    falseBranch?: WorkflowStep[];
+}
+/**
+ * Parallel step - executes multiple steps in parallel
+ */
+export interface ParallelStepConfig {
+    /** Steps to execute in parallel */
+    steps: WorkflowStep[];
+    /** Whether to wait for all steps to complete */
+    waitForAll?: boolean;
+    /** Maximum number of parallel executions */
+    maxConcurrency?: number;
+}
+/**
+ * Loop step - repeats steps while condition is true
+ */
+export interface LoopStepConfig {
+    /** Loop condition */
+    condition: (context: WorkflowContext, iteration: number) => boolean | Promise<boolean>;
+    /** Steps to repeat */
+    steps: WorkflowStep[];
+    /** Maximum iterations */
+    maxIterations?: number;
+    /** Current iteration variable name in context */
+    iterationVariable?: string;
+}
+export declare class Workflow {
+    private config;
+    private context;
+    constructor(config: WorkflowConfig);
+    /**
+     * Execute the workflow
+     */
+    execute(): Promise<WorkflowResult>;
+    /**
+     * Execute a list of steps
+     */
+    private executeSteps;
+    /**
+     * Execute parallel steps
+     */
+    private executeParallelSteps;
+    /**
+     * Execute a single step with retry logic
+     */
+    private executeStep;
+    /**
+     * Calculate retry delay with backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Split array into chunks
+     */
+    private chunkArray;
+    /**
+     * Get current workflow context
+     */
+    getContext(): WorkflowContext;
+    /**
+     * Update workflow context data
+     */
+    updateContext(data: Record<string, any>): void;
+}
+/**
+ * Create an agent execution step
+ */
+export declare function createAgentStep(config: AgentStepConfig & {
+    id: string;
+    name: string;
+}): WorkflowStep;
+/**
+ * Create a data transformation step
+ */
+export declare function createTransformStep(config: {
+    id: string;
+    name: string;
+    transform: (data: any) => any | Promise<any>;
+    inputSchema?: z.ZodType;
+    outputSchema?: z.ZodType;
+}): WorkflowStep;
+/**
+ * Create a conditional branch step
+ */
+export declare function createConditionalStep(config: ConditionalStepConfig & {
+    id: string;
+    name: string;
+}): WorkflowStep;
+/**
+ * Create a delay step
+ */
+export declare function createDelayStep(config: {
+    id: string;
+    name: string;
+    delay: number;
+}): WorkflowStep;
+/**
+ * Create a simple custom step with your own logic
+ *
+ * @param config - Step configuration with custom execute function
+ * @returns WorkflowStep
+ *
+ * @example
+ * ```typescript
+ * const customStep = createStep({
+ *   id: 'my-step',
+ *   name: 'My Custom Step',
+ *   description: 'Does something custom',
+ *   execute: async (context) => {
+ *     // Your custom logic here
+ *     const result = await doSomething(context.data);
+ *     return {
+ *       stepId: 'my-step',
+ *       success: true,
+ *       output: { customResult: result },
+ *       executionTime: 0
+ *     };
+ *   }
+ * });
+ * ```
+ */
+export declare function createStep(config: {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name: string;
+    /** Step description */
+    description?: string;
+    /** Input schema validation */
+    inputSchema?: z.ZodType;
+    /** Output schema validation */
+    outputSchema?: z.ZodType;
+    /** Step execution function */
+    execute: (context: WorkflowContext) => Promise<WorkflowStepResult>;
+    /** Condition to determine if step should run */
+    condition?: (context: WorkflowContext) => boolean | Promise<boolean>;
+    /** Steps that must complete before this step */
+    dependencies?: string[];
+    /** Whether step can run in parallel */
+    parallel?: boolean;
+    /** Retry configuration */
+    retry?: {
+        maxAttempts: number;
+        delay: number;
+        backoff?: 'linear' | 'exponential';
+    };
+}): WorkflowStep;
+/**
+ * Create a simple step that executes a function with the context data
+ *
+ * @param config - Step configuration with transform function
+ * @returns WorkflowStep
+ *
+ * @example
+ * ```typescript
+ * const mathStep = createSimpleStep({
+ *   id: 'calculate',
+ *   name: 'Calculate Total',
+ *   execute: (data) => {
+ *     const total = data.items.reduce((sum, item) => sum + item.price, 0);
+ *     return { total, itemCount: data.items.length };
+ *   }
+ * });
+ * ```
+ */
+export declare function createSimpleStep(config: {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name: string;
+    /** Step description */
+    description?: string;
+    /** Input schema validation */
+    inputSchema?: z.ZodType;
+    /** Output schema validation */
+    outputSchema?: z.ZodType;
+    /** Simple execution function that takes data and returns output */
+    execute: (data: any) => any | Promise<any>;
+    /** Condition to determine if step should run */
+    condition?: (context: WorkflowContext) => boolean | Promise<boolean>;
+    /** Steps that must complete before this step */
+    dependencies?: string[];
+    /** Whether step can run in parallel */
+    parallel?: boolean;
+    /** Retry configuration */
+    retry?: {
+        maxAttempts: number;
+        delay: number;
+        backoff?: 'linear' | 'exponential';
+    };
+}): WorkflowStep;
+/**
+ * Create an async step that can perform asynchronous operations
+ *
+ * @param config - Step configuration with async function
+ * @returns WorkflowStep
+ *
+ * @example
+ * ```typescript
+ * const apiStep = createAsyncStep({
+ *   id: 'fetch-data',
+ *   name: 'Fetch External Data',
+ *   execute: async (data) => {
+ *     const response = await fetch(`/api/data/${data.id}`);
+ *     const result = await response.json();
+ *     return { fetchedData: result };
+ *   },
+ *   retry: {
+ *     maxAttempts: 3,
+ *     delay: 1000,
+ *     backoff: 'exponential'
+ *   }
+ * });
+ * ```
+ */
+export declare function createAsyncStep(config: {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name: string;
+    /** Step description */
+    description?: string;
+    /** Input schema validation */
+    inputSchema?: z.ZodType;
+    /** Output schema validation */
+    outputSchema?: z.ZodType;
+    /** Async execution function */
+    execute: (data: any, context: WorkflowContext) => Promise<any>;
+    /** Condition to determine if step should run */
+    condition?: (context: WorkflowContext) => boolean | Promise<boolean>;
+    /** Steps that must complete before this step */
+    dependencies?: string[];
+    /** Whether step can run in parallel */
+    parallel?: boolean;
+    /** Retry configuration */
+    retry?: {
+        maxAttempts: number;
+        delay: number;
+        backoff?: 'linear' | 'exponential';
+    };
+}): WorkflowStep;
+/**
+ * Create a validation step that validates data against a schema
+ *
+ * @param config - Validation configuration
+ * @returns WorkflowStep
+ */
+export declare function createValidationStep(config: {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name: string;
+    /** Schema to validate against */
+    schema: z.ZodType;
+    /** Field to validate (defaults to entire context data) */
+    field?: string;
+    /** Whether to stop workflow on validation failure */
+    stopOnFailure?: boolean;
+}): WorkflowStep;
+/**
+ * Create a logging step for debugging workflows
+ *
+ * @param config - Logging configuration
+ * @returns WorkflowStep
+ */
+export declare function createLoggingStep(config: {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name: string;
+    /** Log level */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** Custom message template */
+    message?: string;
+    /** Fields to log */
+    fields?: string[];
+}): WorkflowStep;
+/**
+ * Create a workflow from configuration
+ */
+export declare function createWorkflow(config: WorkflowConfig): Workflow;