ai-workflows 2.1.1 → 2.1.3

package/dist/cascade-context.js

@@ -0,0 +1,324 @@
+/**
+ * Cascade Context - Correlation IDs and step metadata for workflow execution
+ *
+ * Provides distributed tracing support with:
+ * - Unique correlation IDs per cascade
+ * - Step timing metadata (started_at, completed_at, duration)
+ * - Cascade path recording
+ * - Context inheritance for nested operations
+ * - Serialization for distributed systems
+ * - W3C Trace Context compatibility
+ */
+/**
+ * Generate a UUID v4
+ */
+function generateUUID() {
+    // Use crypto.randomUUID if available, otherwise fallback
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback UUID v4 generation
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Generate a span ID (16 hex characters)
+ */
+function generateSpanId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID().replace(/-/g, '').slice(0, 16);
+    }
+    return 'xxxxxxxxxxxxxxxx'.replace(/x/g, () => {
+        return ((Math.random() * 16) | 0).toString(16);
+    });
+}
+/**
+ * Parse W3C traceparent header
+ */
+function parseTraceparent(traceparent) {
+    const parts = traceparent.split('-');
+    if (parts.length !== 4)
+        return null;
+    return {
+        traceId: parts[1], // 32 hex chars
+        parentId: parts[2], // 16 hex chars
+    };
+}
+/**
+ * Convert correlation ID to trace ID format (32 hex chars)
+ */
+function correlationIdToTraceId(correlationId) {
+    // Remove dashes and pad/truncate to 32 chars
+    const hex = correlationId.replace(/-/g, '');
+    return hex.slice(0, 32).padEnd(32, '0');
+}
+/**
+ * Convert trace ID to correlation ID format (UUID)
+ */
+function traceIdToCorrelationId(traceId) {
+    // Convert 32 hex chars to UUID format
+    return `${traceId.slice(0, 8)}-${traceId.slice(8, 12)}-${traceId.slice(12, 16)}-${traceId.slice(16, 20)}-${traceId.slice(20, 32)}`;
+}
+/**
+ * Create a cascade context for tracking workflow execution
+ */
+export function createCascadeContext(options = {}) {
+    const { parent, name, fromSerialized, fromTraceContext } = options;
+    // Handle restoration from serialized format
+    if (fromSerialized) {
+        const restoredSteps = fromSerialized.steps.map((s) => createRestoredStep(s, name));
+        const ctx = {
+            correlationId: fromSerialized.correlationId,
+            spanId: fromSerialized.spanId,
+            parentId: fromSerialized.parentId,
+            name: fromSerialized.name,
+            depth: fromSerialized.depth,
+            steps: restoredSteps,
+            path: fromSerialized.path,
+            createdAt: fromSerialized.createdAt,
+            get fullPath() {
+                return this.path;
+            },
+            serialize: () => serializeContext(ctx),
+            format: () => formatContext(ctx),
+            formatTree: () => formatContextTree(ctx),
+            toTraceContext: () => toTraceContext(ctx),
+        };
+        return ctx;
+    }
+    // Handle restoration from W3C trace context
+    if (fromTraceContext) {
+        const parsed = parseTraceparent(fromTraceContext.traceparent);
+        if (parsed) {
+            const correlationId = traceIdToCorrelationId(parsed.traceId);
+            const newSpanId = generateSpanId();
+            const ctx = {
+                correlationId,
+                spanId: newSpanId,
+                parentId: parsed.parentId,
+                name,
+                depth: 0,
+                steps: [],
+                path: [],
+                createdAt: Date.now(),
+                get fullPath() {
+                    return this.path;
+                },
+                serialize: () => serializeContext(ctx),
+                format: () => formatContext(ctx),
+                formatTree: () => formatContextTree(ctx),
+                toTraceContext: () => toTraceContext(ctx),
+            };
+            return ctx;
+        }
+    }
+    // Determine correlation ID
+    let correlationId;
+    if (parent) {
+        correlationId = parent.correlationId;
+    }
+    else if (options.correlationId) {
+        correlationId = options.correlationId;
+    }
+    else {
+        correlationId = generateUUID();
+    }
+    const spanId = generateSpanId();
+    const parentId = parent?.spanId;
+    const depth = parent ? parent.depth + 1 : 0;
+    const createdAt = Date.now();
+    const steps = [];
+    const path = [];
+    const ctx = {
+        correlationId,
+        spanId,
+        parentId,
+        name,
+        depth,
+        steps,
+        path,
+        createdAt,
+        parent,
+        get fullPath() {
+            if (this.parent) {
+                return [...this.parent.fullPath, ...this.path];
+            }
+            return this.path;
+        },
+        serialize: () => serializeContext(ctx),
+        format: () => formatContext(ctx),
+        formatTree: () => formatContextTree(ctx),
+        toTraceContext: () => toTraceContext(ctx),
+    };
+    return ctx;
+}
+/**
+ * Create a restored step from serialized data
+ */
+function createRestoredStep(serialized, contextName) {
+    const step = {
+        name: serialized.name,
+        startedAt: serialized.startedAt,
+        completedAt: serialized.completedAt,
+        duration: serialized.duration,
+        status: serialized.status,
+        metadata: serialized.metadata ? { ...serialized.metadata } : undefined,
+        complete: () => {
+            step.status = 'completed';
+            step.completedAt = Date.now();
+            step.duration = step.completedAt - step.startedAt;
+        },
+        fail: (error) => {
+            step.status = 'failed';
+            step.error = error;
+            step.completedAt = Date.now();
+            step.duration = step.completedAt - step.startedAt;
+        },
+        addMetadata: (data) => {
+            step.metadata = { ...step.metadata, ...data };
+        },
+        to5WHEvent: () => ({
+            who: step.metadata?.actor || 'system',
+            what: step.metadata?.action || step.name,
+            when: step.startedAt,
+            where: contextName || 'unknown',
+            why: step.metadata?.reason,
+            how: {
+                duration: step.duration,
+                status: step.status,
+                metadata: step.metadata,
+            },
+        }),
+    };
+    return step;
+}
+/**
+ * Record a step in the cascade context
+ */
+export function recordStep(ctx, name, metadata) {
+    const startedAt = Date.now();
+    const step = {
+        name,
+        startedAt,
+        status: 'running',
+        metadata: metadata ? { ...metadata } : undefined,
+        complete: () => {
+            step.status = 'completed';
+            step.completedAt = Date.now();
+            step.duration = step.completedAt - step.startedAt;
+            ctx.path.push(name);
+        },
+        fail: (error) => {
+            step.status = 'failed';
+            step.error = error;
+            step.completedAt = Date.now();
+            step.duration = step.completedAt - step.startedAt;
+        },
+        addMetadata: (data) => {
+            step.metadata = { ...step.metadata, ...data };
+        },
+        to5WHEvent: () => ({
+            who: step.metadata?.actor || 'system',
+            what: step.metadata?.action || name,
+            when: startedAt,
+            where: ctx.name || 'cascade',
+            why: step.metadata?.reason,
+            how: {
+                duration: step.duration,
+                status: step.status,
+                metadata: step.metadata,
+            },
+        }),
+    };
+    ctx.steps.push(step);
+    return step;
+}
+/**
+ * Execute a callback with cascade context
+ */
+export async function withCascadeContext(callback, options = {}) {
+    const ctx = createCascadeContext(options);
+    return callback(ctx);
+}
+/**
+ * Serialize context for transmission/storage
+ */
+function serializeContext(ctx) {
+    return {
+        correlationId: ctx.correlationId,
+        spanId: ctx.spanId,
+        parentId: ctx.parentId,
+        name: ctx.name,
+        depth: ctx.depth,
+        steps: ctx.steps.map((step) => ({
+            name: step.name,
+            startedAt: step.startedAt,
+            completedAt: step.completedAt,
+            duration: step.duration,
+            status: step.status,
+            metadata: step.metadata,
+        })),
+        path: ctx.path,
+        createdAt: ctx.createdAt,
+    };
+}
+/**
+ * Format context as readable string
+ */
+function formatContext(ctx) {
+    const lines = [];
+    lines.push(`Cascade: ${ctx.name || 'unnamed'}`);
+    lines.push(`  Correlation ID: ${ctx.correlationId}`);
+    lines.push(`  Span ID: ${ctx.spanId}`);
+    if (ctx.parentId) {
+        lines.push(`  Parent ID: ${ctx.parentId}`);
+    }
+    lines.push(`  Depth: ${ctx.depth}`);
+    lines.push(`  Steps:`);
+    for (const step of ctx.steps) {
+        const status = step.status === 'completed' ? '[OK]' : step.status === 'failed' ? '[FAIL]' : '[...]';
+        const duration = step.duration ? ` (${step.duration}ms)` : '';
+        lines.push(`    ${status} ${step.name}${duration}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format context as tree including parent contexts
+ */
+function formatContextTree(ctx) {
+    const lines = [];
+    // Build tree from root
+    const contexts = [];
+    let current = ctx;
+    while (current) {
+        contexts.unshift(current);
+        current = current.parent;
+    }
+    for (let i = 0; i < contexts.length; i++) {
+        const context = contexts[i];
+        const indent = '  '.repeat(i);
+        lines.push(`${indent}${context.name || 'cascade'} (depth: ${context.depth})`);
+        for (const step of context.steps) {
+            const status = step.status === 'completed' ? '[OK]' : step.status === 'failed' ? '[FAIL]' : '[...]';
+            const duration = step.duration ? ` (${step.duration}ms)` : '';
+            lines.push(`${indent}  ${status} ${step.name}${duration}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Convert to W3C Trace Context format
+ */
+function toTraceContext(ctx) {
+    const version = '00';
+    const traceId = correlationIdToTraceId(ctx.correlationId);
+    const spanId = ctx.spanId.padEnd(16, '0').slice(0, 16);
+    const flags = '01'; // sampled
+    return {
+        traceparent: `${version}-${traceId}-${spanId}-${flags}`,
+    };
+}
+//# sourceMappingURL=cascade-context.js.map

package/dist/cascade-context.js.map

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

package/dist/cascade-executor.d.ts

@@ -0,0 +1,196 @@
+/**
+ * CascadeExecutor - Code -> Generative -> Agentic -> Human escalation pattern
+ *
+ * Implements a tiered execution strategy that tries deterministic code first,
+ * then escalates to AI-powered solutions, and finally to human-in-the-loop
+ * if all automated approaches fail.
+ *
+ * Features:
+ * - Tier escalation on failure
+ * - Per-tier and total cascade timeouts
+ * - 5W+H event emission for audit trails
+ * - Context propagation through tiers
+ * - Retry support per tier
+ * - Custom skip conditions
+ *
+ * @packageDocumentation
+ */
+import { type CascadeContext, type FiveWHEvent } from './cascade-context.js';
+/**
+ * Ordered list of capability tiers
+ */
+export declare const TIER_ORDER: readonly ["code", "generative", "agentic", "human"];
+/**
+ * Default timeouts per tier (from capability-tiers)
+ */
+export declare const DEFAULT_TIER_TIMEOUTS: Record<CapabilityTier, number>;
+/**
+ * Capability tier levels
+ */
+export type CapabilityTier = 'code' | 'generative' | 'agentic' | 'human';
+/**
+ * Context passed to tier handlers
+ */
+export interface TierContext {
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Current tier being executed */
+    tier: CapabilityTier;
+    /** Input data */
+    input: unknown;
+    /** Cascade context */
+    cascadeContext: CascadeContext;
+}
+/**
+ * Handler for a specific tier
+ */
+export interface TierHandler<T = unknown> {
+    /** Handler name for debugging */
+    name: string;
+    /** Execute the tier logic */
+    execute: (input: unknown, context: TierContext) => Promise<T>;
+}
+/**
+ * Retry configuration per tier
+ */
+export interface TierRetryConfig {
+    /** Maximum number of retries */
+    maxRetries: number;
+    /** Base delay in milliseconds */
+    baseDelay: number;
+    /** Multiplier for exponential backoff */
+    multiplier?: number;
+}
+/**
+ * Result from a single tier execution
+ */
+export interface TierResult {
+    /** Tier that was executed */
+    tier: CapabilityTier;
+    /** Whether the tier succeeded */
+    success: boolean;
+    /** Result value (if success) */
+    value?: unknown;
+    /** Error (if failure) */
+    error?: Error;
+    /** Whether the tier timed out */
+    timedOut?: boolean;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Metrics from cascade execution
+ */
+export interface CascadeMetrics {
+    /** Total execution duration */
+    totalDuration: number;
+    /** Duration per tier */
+    tierDurations: Partial<Record<CapabilityTier, number>>;
+    /** Number of retries per tier */
+    tierRetries?: Partial<Record<CapabilityTier, number>>;
+}
+/**
+ * Result from cascade execution
+ */
+export interface CascadeResult<T = unknown> {
+    /** Final result value */
+    value: T;
+    /** Tier that produced the result */
+    tier: CapabilityTier;
+    /** History of all tier executions */
+    history: TierResult[];
+    /** Tiers that were skipped */
+    skippedTiers: CapabilityTier[];
+    /** Cascade context with tracing info */
+    context: CascadeContext;
+    /** Execution metrics */
+    metrics: CascadeMetrics;
+}
+/**
+ * Skip condition function
+ */
+export type SkipCondition = (input: unknown) => boolean;
+/**
+ * Configuration for CascadeExecutor
+ */
+export interface CascadeConfig<T = unknown> {
+    /** Tier handlers */
+    tiers: Partial<Record<CapabilityTier, TierHandler<T>>>;
+    /** Per-tier timeouts in milliseconds */
+    timeouts?: Partial<Record<CapabilityTier, number>>;
+    /** Total cascade timeout in milliseconds */
+    totalTimeout?: number;
+    /** Use default timeouts from capability-tiers */
+    useDefaultTimeouts?: boolean;
+    /** Actor identifier for 5W+H events */
+    actor?: string;
+    /** Cascade name for 5W+H events */
+    cascadeName?: string;
+    /** Event callback for 5W+H events */
+    onEvent?: (event: FiveWHEvent) => void;
+    /** Skip conditions per tier */
+    skipConditions?: Partial<Record<CapabilityTier, SkipCondition>>;
+    /** Retry configuration per tier */
+    retryConfig?: Partial<Record<CapabilityTier, TierRetryConfig>>;
+}
+/**
+ * Error thrown when cascade times out
+ */
+export declare class CascadeTimeoutError extends Error {
+    readonly timeout: number;
+    readonly elapsed: number;
+    constructor(timeout: number, elapsed: number);
+}
+/**
+ * Error thrown when a tier is skipped
+ */
+export declare class TierSkippedError extends Error {
+    readonly tier: CapabilityTier;
+    readonly reason: string;
+    constructor(tier: CapabilityTier, reason: string);
+}
+/**
+ * Error thrown when all tiers fail
+ */
+export declare class AllTiersFailedError extends Error {
+    readonly history: TierResult[];
+    constructor(history: TierResult[]);
+}
+/**
+ * CascadeExecutor implements the code -> generative -> agentic -> human pattern
+ */
+export declare class CascadeExecutor<T = unknown> {
+    private readonly config;
+    private readonly actor;
+    private readonly cascadeName;
+    constructor(config: CascadeConfig<T>);
+    /**
+     * Execute the cascade
+     */
+    execute(input: unknown): Promise<CascadeResult<T>>;
+    /**
+     * Execute a single tier with timeout and retry support
+     */
+    private executeTier;
+    /**
+     * Execute a function with a timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Get timeout for a tier
+     */
+    private getTierTimeout;
+    /**
+     * Get the next configured tier after the given tier
+     */
+    private getNextConfiguredTier;
+    /**
+     * Emit a 5W+H event
+     */
+    private emitEvent;
+    /**
+     * Sleep for a given duration
+     */
+    private sleep;
+}
+//# sourceMappingURL=cascade-executor.d.ts.map

package/dist/cascade-executor.d.ts.map

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