@agnt5/sdk 0.2.1

package/dist/workflow-utils.js

@@ -0,0 +1,370 @@
+/**
+ * Workflow utilities for parallel execution and orchestration.
+ *
+ * Phase 4.3: Enhanced workflow capabilities including:
+ * - Parallel execution with Promise.all
+ * - Gather with named results
+ * - Child workflow execution
+ * - Enhanced step tracking
+ */
+import { WorkflowRegistry } from './workflow.js';
+/**
+ * Run multiple async tasks in parallel and return results in order.
+ *
+ * @param tasks - Array of promises to execute in parallel
+ * @returns Array of results in the same order as tasks
+ *
+ * @example
+ * ```typescript
+ * const [result1, result2, result3] = await parallel([
+ *   fetchUser(userId),
+ *   fetchOrders(userId),
+ *   fetchSettings(userId),
+ * ]);
+ * ```
+ */
+export async function parallel(tasks) {
+    return Promise.all(tasks);
+}
+/**
+ * Run tasks in parallel with named results.
+ *
+ * @param tasks - Object with task names as keys and promises as values
+ * @returns Object with same keys and resolved values
+ *
+ * @example
+ * ```typescript
+ * const results = await gather({
+ *   user: fetchUser(userId),
+ *   orders: fetchOrders(userId),
+ *   settings: fetchSettings(userId),
+ * });
+ * // results.user, results.orders, results.settings
+ * ```
+ */
+export async function gather(tasks) {
+    const keys = Object.keys(tasks);
+    const promises = Object.values(tasks);
+    const results = await Promise.all(promises);
+    const resultObj = {};
+    for (let i = 0; i < keys.length; i++) {
+        resultObj[keys[i]] = results[i];
+    }
+    return resultObj;
+}
+/**
+ * Execute a child workflow from within a parent workflow.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflowNameOrHandler - Workflow name or handler function
+ * @param input - Input data for the child workflow
+ * @returns Result from the child workflow
+ *
+ * @example
+ * ```typescript
+ * const processOrder = workflow('process-order', async (ctx, orderId) => {
+ *   // Execute child workflow
+ *   const validation = await executeChildWorkflow(ctx, 'validate-order', orderId);
+ *
+ *   if (!validation.valid) {
+ *     throw new Error('Invalid order');
+ *   }
+ *
+ *   return { status: 'processed' };
+ * });
+ * ```
+ */
+export async function executeChildWorkflow(ctx, workflowNameOrHandler, input) {
+    let workflowName;
+    let handler;
+    // Resolve workflow handler
+    if (typeof workflowNameOrHandler === 'string') {
+        workflowName = workflowNameOrHandler;
+        const config = WorkflowRegistry.get(workflowName);
+        if (!config) {
+            throw new Error(`Workflow '${workflowName}' not found in registry`);
+        }
+        handler = config.handler;
+    }
+    else {
+        handler = workflowNameOrHandler;
+        workflowName = handler.name || 'anonymous-child-workflow';
+    }
+    ctx.logger.info(`Starting child workflow: ${workflowName}`);
+    try {
+        // Execute child workflow with parent context
+        const result = await handler(ctx, input);
+        ctx.logger.info(`Child workflow completed: ${workflowName}`);
+        return result;
+    }
+    catch (error) {
+        ctx.logger.error(`Child workflow failed: ${workflowName}`, { error: error.message });
+        throw error;
+    }
+}
+/**
+ * Execute multiple child workflows in parallel.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflows - Array of [workflowNameOrHandler, input] tuples
+ * @returns Array of results from child workflows
+ *
+ * @example
+ * ```typescript
+ * const results = await parallelWorkflows(ctx, [
+ *   ['validate-user', userId],
+ *   ['validate-payment', paymentId],
+ *   ['validate-inventory', items],
+ * ]);
+ * ```
+ */
+export async function parallelWorkflows(ctx, workflows) {
+    const tasks = workflows.map(([nameOrHandler, input]) => executeChildWorkflow(ctx, nameOrHandler, input));
+    return parallel(tasks);
+}
+/**
+ * Execute child workflows with named results.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflows - Object with workflow names as keys and [nameOrHandler, input] as values
+ * @returns Object with same keys and workflow results
+ *
+ * @example
+ * ```typescript
+ * const results = await gatherWorkflows(ctx, {
+ *   user: ['validate-user', userId],
+ *   payment: ['validate-payment', paymentId],
+ *   inventory: ['check-inventory', items],
+ * });
+ * // results.user, results.payment, results.inventory
+ * ```
+ */
+export async function gatherWorkflows(ctx, workflows) {
+    const tasks = {};
+    for (const [key, [nameOrHandler, input]] of Object.entries(workflows)) {
+        tasks[key] = executeChildWorkflow(ctx, nameOrHandler, input);
+    }
+    return gather(tasks);
+}
+/**
+ * Fan-out pattern: Execute the same workflow with different inputs in parallel.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflowNameOrHandler - Workflow to execute
+ * @param inputs - Array of inputs for each workflow execution
+ * @returns Array of results
+ *
+ * @example
+ * ```typescript
+ * const userIds = [1, 2, 3, 4, 5];
+ * const results = await fanOut(ctx, 'process-user', userIds);
+ * ```
+ */
+export async function fanOut(ctx, workflowNameOrHandler, inputs) {
+    const tasks = inputs.map(input => executeChildWorkflow(ctx, workflowNameOrHandler, input));
+    return parallel(tasks);
+}
+/**
+ * Execute workflows in batches to avoid overwhelming the system.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflowNameOrHandler - Workflow to execute
+ * @param inputs - Array of inputs for each workflow execution
+ * @param batchSize - Number of workflows to execute in parallel per batch (default: 10)
+ * @returns Array of results
+ *
+ * @example
+ * ```typescript
+ * const userIds = Array.from({ length: 100 }, (_, i) => i);
+ * const results = await batchExecute(ctx, 'process-user', userIds, 10);
+ * // Processes 100 users in batches of 10
+ * ```
+ */
+export async function batchExecute(ctx, workflowNameOrHandler, inputs, batchSize = 10) {
+    const results = [];
+    for (let i = 0; i < inputs.length; i += batchSize) {
+        const batch = inputs.slice(i, i + batchSize);
+        ctx.logger.info(`Processing batch ${Math.floor(i / batchSize) + 1}/${Math.ceil(inputs.length / batchSize)}`);
+        const batchResults = await fanOut(ctx, workflowNameOrHandler, batch);
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Race pattern: Return the first workflow that completes successfully.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflows - Array of [workflowNameOrHandler, input] tuples
+ * @returns Result from the first workflow to complete
+ *
+ * @example
+ * ```typescript
+ * const result = await race(ctx, [
+ *   ['fetch-from-cache', cacheKey],
+ *   ['fetch-from-db', dbId],
+ *   ['fetch-from-api', apiUrl],
+ * ]);
+ * // Returns whichever completes first
+ * ```
+ */
+export async function race(ctx, workflows) {
+    const tasks = workflows.map(([nameOrHandler, input]) => executeChildWorkflow(ctx, nameOrHandler, input));
+    return Promise.race(tasks);
+}
+/**
+ * Execute workflows with a timeout.
+ *
+ * @param ctx - Parent workflow context
+ * @param workflowNameOrHandler - Workflow to execute
+ * @param input - Input data for the workflow
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Result from the workflow
+ * @throws TimeoutError if workflow exceeds timeout
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await withTimeout(ctx, 'slow-workflow', input, 5000);
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     // Handle timeout
+ *   }
+ * }
+ * ```
+ */
+export async function withTimeout(ctx, workflowNameOrHandler, input, timeoutMs) {
+    const { TimeoutError } = await import('./errors.js');
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new TimeoutError(`Workflow execution timed out after ${timeoutMs}ms`, timeoutMs, 'withTimeout'));
+        }, timeoutMs);
+    });
+    const workflowPromise = executeChildWorkflow(ctx, workflowNameOrHandler, input);
+    return Promise.race([workflowPromise, timeoutPromise]);
+}
+/**
+ * Saga pattern coordinator for managing compensating transactions.
+ *
+ * Executes steps sequentially, and if any step fails, executes compensating
+ * actions in reverse order.
+ *
+ * @param ctx - Workflow context
+ * @param steps - Array of [action, compensation] tuples
+ * @returns Result from the final step
+ * @throws Error from failed step after compensation
+ *
+ * @example
+ * ```typescript
+ * const result = await saga(ctx, [
+ *   [
+ *     async () => await reserveInventory(items),
+ *     async () => await releaseInventory(items),
+ *   ],
+ *   [
+ *     async () => await chargePayment(paymentInfo),
+ *     async () => await refundPayment(paymentInfo),
+ *   ],
+ *   [
+ *     async () => await shipOrder(orderId),
+ *     async () => await cancelShipment(orderId),
+ *   ],
+ * ]);
+ * ```
+ */
+export async function saga(ctx, steps) {
+    const completedSteps = [];
+    let lastResult;
+    try {
+        for (let i = 0; i < steps.length; i++) {
+            const [action, compensation] = steps[i];
+            ctx.logger.info(`Executing saga step ${i + 1}/${steps.length}`);
+            lastResult = await action();
+            completedSteps.push(compensation);
+        }
+        return lastResult;
+    }
+    catch (error) {
+        ctx.logger.error(`Saga failed at step ${completedSteps.length + 1}, executing compensations`);
+        // Execute compensations in reverse order
+        for (let i = completedSteps.length - 1; i >= 0; i--) {
+            try {
+                ctx.logger.info(`Executing compensation ${i + 1}/${completedSteps.length}`);
+                await completedSteps[i]();
+            }
+            catch (compensationError) {
+                ctx.logger.error(`Compensation ${i + 1} failed: ${compensationError.message}`);
+            }
+        }
+        throw error;
+    }
+}
+/**
+ * Retry a workflow with exponential backoff.
+ *
+ * @param ctx - Workflow context
+ * @param workflowNameOrHandler - Workflow to execute
+ * @param input - Input data for the workflow
+ * @param maxAttempts - Maximum number of attempts (default: 3)
+ * @param initialDelayMs - Initial delay in milliseconds (default: 1000)
+ * @returns Result from the workflow
+ *
+ * @example
+ * ```typescript
+ * const result = await retryWorkflow(
+ *   ctx,
+ *   'unstable-api-call',
+ *   apiParams,
+ *   5,    // 5 attempts
+ *   2000  // Start with 2 second delay
+ * );
+ * ```
+ */
+/**
+ * Durable sleep that survives workflow restarts.
+ *
+ * Unlike `setTimeout` or `new Promise(resolve => setTimeout(...))`, this sleep
+ * is checkpointed via `ctx.step()`. If the workflow crashes and restarts, it
+ * only sleeps for the remaining duration (or skips entirely if the period has
+ * already elapsed).
+ *
+ * @param ctx - Workflow context
+ * @param durationMs - Duration to sleep in milliseconds
+ * @param name - Optional name for the sleep checkpoint (auto-generated if omitted)
+ *
+ * @example
+ * ```typescript
+ * const notifyLater = workflow('notify-later', async (ctx, userId) => {
+ *   await ctx.step('send-ack', () => sendAck(userId));
+ *
+ *   // Wait 24 hours (survives restarts!)
+ *   await sleep(ctx, 24 * 60 * 60 * 1000, 'wait_24h');
+ *
+ *   await ctx.step('send-followup', () => sendFollowup(userId));
+ * });
+ * ```
+ */
+export async function sleep(ctx, durationMs, name) {
+    const sleepName = name || `sleep_${durationMs}ms`;
+    // ctx.step() checkpoints the start time — on replay it returns the cached value
+    const startTime = await ctx.step(sleepName, () => Date.now());
+    const elapsed = Date.now() - startTime;
+    const remaining = durationMs - elapsed;
+    if (remaining > 0) {
+        ctx.logger.info(`Starting durable sleep '${sleepName}': ${remaining}ms`);
+        await new Promise(resolve => setTimeout(resolve, remaining));
+        ctx.logger.info(`Sleep '${sleepName}' completed`);
+    }
+    else {
+        ctx.logger.info(`Sleep '${sleepName}' already elapsed (${elapsed}ms ago)`);
+    }
+}
+export async function retryWorkflow(ctx, workflowNameOrHandler, input, maxAttempts = 3, initialDelayMs = 1000) {
+    const { executeWithRetry } = await import('./retry-utils.js');
+    return executeWithRetry(() => executeChildWorkflow(ctx, workflowNameOrHandler, input), {
+        retryPolicy: { maxAttempts, initialIntervalMs: initialDelayMs, maxIntervalMs: 60000 },
+        backoffPolicy: 'exponential',
+        jitter: true,
+        context: ctx,
+    });
+}
+//# sourceMappingURL=workflow-utils.js.map

package/dist/workflow-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-utils.js","sourceRoot":"","sources":["../src/workflow-utils.ts"],"names":[],"mappings":"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"}

package/dist/workflow.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Workflow component for multi-step orchestration.
+ *
+ * Phase 1: In-memory orchestration with basic coordination
+ * Phase 2: Durable execution with checkpoint/replay and distributed tasks
+ */
+import type { WorkflowHandler } from './types.js';
+/**
+ * Workflow configuration
+ */
+export interface WorkflowConfig {
+    name: string;
+    handler: WorkflowHandler;
+    /** Cron expression for scheduled execution (e.g., "0 0/6 * * *") */
+    cron?: string;
+}
+/**
+ * Global workflow registry
+ */
+export declare class WorkflowRegistry {
+    private static workflows;
+    /**
+     * Register a workflow handler
+     */
+    static register(config: WorkflowConfig): void;
+    /**
+     * Get workflow configuration by name
+     */
+    static get(name: string): WorkflowConfig | undefined;
+    /**
+     * Get all registered workflows
+     */
+    static all(): Map<string, WorkflowConfig>;
+    /**
+     * List all registered workflow names
+     */
+    static listNames(): string[];
+    /**
+     * Clear all registered workflows (for testing)
+     */
+    static clear(): void;
+}
+/**
+ * Workflow options
+ */
+export interface WorkflowOptions {
+    /** Custom workflow name (defaults to function name) */
+    name?: string;
+    /** Cron expression for scheduled execution (e.g., "0 0/6 * * *") */
+    cron?: string;
+}
+/**
+ * Decorator to mark a function as a durable workflow
+ *
+ * @example
+ * ```typescript
+ * const processOrder = workflow('process-order', async (ctx: Context, orderId: string) => {
+ *   // Validate order
+ *   const order = await ctx.step('validate', async () => {
+ *     return { id: orderId, total: 100 };
+ *   });
+ *
+ *   // Process payment
+ *   const payment = await ctx.step('payment', async () => {
+ *     return { status: 'success' };
+ *   });
+ *
+ *   // Fulfill order
+ *   await ctx.step('fulfill', async () => {
+ *     console.log('Order fulfilled');
+ *   });
+ *
+ *   return { status: 'completed' };
+ * });
+ * ```
+ */
+export declare function workflow<TInput = any, TOutput = any>(nameOrHandler: string | WorkflowHandler<TInput, TOutput>, handlerOrOptions?: WorkflowHandler<TInput, TOutput> | WorkflowOptions, optionsParam?: WorkflowOptions): WorkflowHandler<TInput, TOutput>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,YAAY,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,eAAe,CAAC;IACzB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAqC;IAE7D;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAO7C;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIpD;;OAEG;IACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAIzC;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,MAAM,EAAE;IAI5B;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAGrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,EAClD,aAAa,EAAE,MAAM,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,gBAAgB,CAAC,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EACrE,YAAY,CAAC,EAAE,eAAe,GAC7B,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CA+DlC"}

package/dist/workflow.js

@@ -0,0 +1,138 @@
+/**
+ * Workflow component for multi-step orchestration.
+ *
+ * Phase 1: In-memory orchestration with basic coordination
+ * Phase 2: Durable execution with checkpoint/replay and distributed tasks
+ */
+import { ContextImpl } from './context.js';
+/**
+ * Global workflow registry
+ */
+export class WorkflowRegistry {
+    /**
+     * Register a workflow handler
+     */
+    static register(config) {
+        if (this.workflows.has(config.name)) {
+            console.warn(`Overwriting existing workflow '${config.name}'`);
+        }
+        this.workflows.set(config.name, config);
+    }
+    /**
+     * Get workflow configuration by name
+     */
+    static get(name) {
+        return this.workflows.get(name);
+    }
+    /**
+     * Get all registered workflows
+     */
+    static all() {
+        return new Map(this.workflows);
+    }
+    /**
+     * List all registered workflow names
+     */
+    static listNames() {
+        return Array.from(this.workflows.keys());
+    }
+    /**
+     * Clear all registered workflows (for testing)
+     */
+    static clear() {
+        this.workflows.clear();
+    }
+}
+WorkflowRegistry.workflows = new Map();
+/**
+ * Decorator to mark a function as a durable workflow
+ *
+ * @example
+ * ```typescript
+ * const processOrder = workflow('process-order', async (ctx: Context, orderId: string) => {
+ *   // Validate order
+ *   const order = await ctx.step('validate', async () => {
+ *     return { id: orderId, total: 100 };
+ *   });
+ *
+ *   // Process payment
+ *   const payment = await ctx.step('payment', async () => {
+ *     return { status: 'success' };
+ *   });
+ *
+ *   // Fulfill order
+ *   await ctx.step('fulfill', async () => {
+ *     console.log('Order fulfilled');
+ *   });
+ *
+ *   return { status: 'completed' };
+ * });
+ * ```
+ */
+export function workflow(nameOrHandler, handlerOrOptions, optionsParam) {
+    let workflowName;
+    let handler;
+    let options = {};
+    // Parse arguments
+    if (typeof nameOrHandler === 'string') {
+        workflowName = nameOrHandler;
+        if (typeof handlerOrOptions === 'function') {
+            handler = handlerOrOptions;
+            options = optionsParam || {};
+        }
+        else {
+            throw new Error('Invalid workflow definition: handler must be a function');
+        }
+    }
+    else if (typeof nameOrHandler === 'function') {
+        handler = nameOrHandler;
+        workflowName = handler.name || 'anonymous-workflow';
+        options = handlerOrOptions || {};
+    }
+    else {
+        throw new Error('Invalid workflow definition');
+    }
+    // Override name if provided in options
+    if (options.name) {
+        workflowName = options.name;
+    }
+    // Register workflow
+    const config = {
+        name: workflowName,
+        handler,
+        cron: options.cron,
+    };
+    WorkflowRegistry.register(config);
+    // Create wrapper that provides context
+    const workflowWrapper = async (ctxOrInput, input) => {
+        let ctx;
+        let actualInput;
+        // Determine if first arg is Context or input
+        if (isContext(ctxOrInput)) {
+            ctx = ctxOrInput;
+            actualInput = input;
+        }
+        else {
+            // Auto-create context for direct workflow calls
+            ctx = new ContextImpl(`workflow-${workflowName}-${Date.now()}`, `run-${Date.now()}`, 0, workflowName);
+            actualInput = ctxOrInput;
+        }
+        // Execute workflow
+        return handler(ctx, actualInput);
+    };
+    // Attach config for introspection
+    workflowWrapper._agnt5_config = config;
+    return workflowWrapper;
+}
+/**
+ * Type guard to check if value is a Context
+ */
+function isContext(value) {
+    return (value &&
+        typeof value === 'object' &&
+        'invocationId' in value &&
+        'runId' in value &&
+        'step' in value &&
+        'logger' in value);
+}
+//# sourceMappingURL=workflow.js.map

package/dist/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"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"}