@dotsetlabs/bellwether 0.10.0

package/dist/errors/retry.js

@@ -0,0 +1,323 @@
+/**
+ * Retry logic with exponential backoff.
+ */
+import { getLogger } from '../logging/logger.js';
+import { BellwetherError, LLMRateLimitError, isRetryable, wrapError, createTimingContext, } from './types.js';
+import { RETRY_STRATEGIES, CIRCUIT_BREAKER, MATH_FACTORS } from '../constants.js';
+const DEFAULT_OPTIONS = {
+    maxAttempts: RETRY_STRATEGIES.DEFAULT.maxAttempts,
+    initialDelayMs: RETRY_STRATEGIES.DEFAULT.initialDelayMs,
+    maxDelayMs: RETRY_STRATEGIES.DEFAULT.maxDelayMs,
+    backoffMultiplier: RETRY_STRATEGIES.DEFAULT.backoffMultiplier,
+    jitter: RETRY_STRATEGIES.DEFAULT.jitter,
+};
+/**
+ * Calculate delay with exponential backoff and optional jitter.
+ */
+function calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter) {
+    // Exponential backoff: delay = initial * multiplier^(attempt - 1)
+    const exponentialDelay = initialDelayMs * Math.pow(backoffMultiplier, attempt - 1);
+    const clampedDelay = Math.min(exponentialDelay, maxDelayMs);
+    if (jitter) {
+        // Add random jitter: ±25% of the delay
+        const jitterRange = clampedDelay * MATH_FACTORS.JITTER_RANGE;
+        const jitterAmount = Math.random() * jitterRange * 2 - jitterRange;
+        return Math.max(0, clampedDelay + jitterAmount);
+    }
+    return clampedDelay;
+}
+/**
+ * Sleep for the specified duration.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with retry logic.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => await llmClient.complete(prompt),
+ *   { maxAttempts: 3, operation: 'LLM completion' }
+ * );
+ * ```
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxAttempts = DEFAULT_OPTIONS.maxAttempts, initialDelayMs = DEFAULT_OPTIONS.initialDelayMs, maxDelayMs = DEFAULT_OPTIONS.maxDelayMs, backoffMultiplier = DEFAULT_OPTIONS.backoffMultiplier, jitter = DEFAULT_OPTIONS.jitter, shouldRetry = isRetryable, onRetry, operation = 'operation', context, } = options;
+    const logger = getLogger('retry');
+    const startedAt = new Date();
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry
+            if (attempt >= maxAttempts || !shouldRetry(error, attempt)) {
+                // Wrap and rethrow with context
+                const wrappedError = wrapError(error, {
+                    ...context,
+                    operation,
+                    timing: createTimingContext(startedAt),
+                    retry: {
+                        attempt,
+                        maxAttempts,
+                    },
+                });
+                logger.warn({
+                    operation,
+                    attempt,
+                    maxAttempts,
+                    error: wrappedError.toJSON(),
+                    message: `${operation} failed after ${attempt} attempt(s)`,
+                });
+                throw wrappedError;
+            }
+            // Calculate delay for next attempt
+            // Use server-provided retry-after if available (from LLMRateLimitError)
+            let delayMs;
+            if (error instanceof LLMRateLimitError && error.retryAfterMs) {
+                // Use server-specified delay, but respect our maxDelayMs cap
+                delayMs = Math.min(error.retryAfterMs, maxDelayMs);
+                logger.debug({
+                    operation,
+                    serverDelayMs: error.retryAfterMs,
+                    actualDelayMs: delayMs,
+                    message: `Using server-provided retry delay`,
+                });
+            }
+            else {
+                delayMs = calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter);
+            }
+            // Log retry
+            logger.debug({
+                operation,
+                attempt,
+                maxAttempts,
+                delayMs: Math.round(delayMs),
+                error: error instanceof Error ? error.message : String(error),
+                message: `Retrying ${operation} in ${Math.round(delayMs)}ms`,
+            });
+            // Notify callback
+            if (onRetry) {
+                onRetry(error, attempt, delayMs);
+            }
+            // Wait before retry
+            await sleep(delayMs);
+        }
+    }
+    // This should never happen, but TypeScript needs it
+    throw wrapError(lastError, {
+        ...context,
+        operation,
+        timing: createTimingContext(startedAt),
+        retry: { attempt: maxAttempts, maxAttempts },
+    });
+}
+/**
+ * Create a retry wrapper for a specific operation.
+ *
+ * @example
+ * ```typescript
+ * const retryableFetch = createRetryWrapper({
+ *   maxAttempts: 5,
+ *   operation: 'API fetch'
+ * });
+ *
+ * const data = await retryableFetch(() => fetchData());
+ * ```
+ */
+export function createRetryWrapper(defaultOptions) {
+    return (fn, overrides = {}) => {
+        return withRetry(fn, { ...defaultOptions, ...overrides });
+    };
+}
+/**
+ * Retry options specifically tuned for LLM calls.
+ */
+export const LLM_RETRY_OPTIONS = {
+    maxAttempts: RETRY_STRATEGIES.LLM.maxAttempts,
+    initialDelayMs: RETRY_STRATEGIES.LLM.initialDelayMs, // LLM rate limits often need longer waits
+    maxDelayMs: RETRY_STRATEGIES.LLM.maxDelayMs,
+    backoffMultiplier: RETRY_STRATEGIES.LLM.backoffMultiplier,
+    jitter: RETRY_STRATEGIES.LLM.jitter,
+    shouldRetry: (error) => {
+        // Check for known LLM error patterns
+        const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        // Rate limits - always retry
+        if (message.includes('rate limit') || message.includes('429')) {
+            return true;
+        }
+        // Connection issues - retry
+        if (message.includes('econnreset') ||
+            message.includes('econnrefused') ||
+            message.includes('socket hang up') ||
+            message.includes('fetch failed')) {
+            return true;
+        }
+        // Timeouts - retry
+        if (message.includes('timeout')) {
+            return true;
+        }
+        // Server errors (5xx) - retry
+        if (message.includes('500') || message.includes('502') || message.includes('503')) {
+            return true;
+        }
+        // Auth errors - don't retry
+        if (message.includes('401') || message.includes('unauthorized') || message.includes('api key')) {
+            return false;
+        }
+        // Quota errors - don't retry
+        if (message.includes('quota') || message.includes('insufficient') || message.includes('credit')) {
+            return false;
+        }
+        // Default: use standard isRetryable
+        return isRetryable(error);
+    },
+};
+/**
+ * Retry options for MCP transport operations.
+ */
+export const TRANSPORT_RETRY_OPTIONS = {
+    maxAttempts: RETRY_STRATEGIES.TRANSPORT.maxAttempts, // Transport failures are often persistent
+    initialDelayMs: RETRY_STRATEGIES.TRANSPORT.initialDelayMs,
+    maxDelayMs: RETRY_STRATEGIES.TRANSPORT.maxDelayMs,
+    backoffMultiplier: RETRY_STRATEGIES.TRANSPORT.backoffMultiplier,
+    jitter: RETRY_STRATEGIES.TRANSPORT.jitter,
+    shouldRetry: (error) => {
+        const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        // Timeouts might be transient
+        if (message.includes('timeout')) {
+            return true;
+        }
+        // Connection resets might recover
+        if (message.includes('econnreset')) {
+            return true;
+        }
+        // Protocol errors are permanent
+        if (message.includes('protocol') || message.includes('parse')) {
+            return false;
+        }
+        // Server exit is permanent
+        if (message.includes('exit') || message.includes('closed')) {
+            return false;
+        }
+        return isRetryable(error);
+    },
+};
+/**
+ * Retry options for tool calls during interviews.
+ */
+export const TOOL_CALL_RETRY_OPTIONS = {
+    maxAttempts: RETRY_STRATEGIES.TOOL_CALL.maxAttempts, // Tool failures are often deterministic
+    initialDelayMs: RETRY_STRATEGIES.TOOL_CALL.initialDelayMs,
+    maxDelayMs: RETRY_STRATEGIES.TOOL_CALL.maxDelayMs,
+    backoffMultiplier: RETRY_STRATEGIES.TOOL_CALL.backoffMultiplier,
+    jitter: RETRY_STRATEGIES.TOOL_CALL.jitter,
+    shouldRetry: (error) => {
+        const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        // Timeout - might succeed on retry
+        if (message.includes('timeout')) {
+            return true;
+        }
+        // Most tool errors are deterministic - don't retry
+        return false;
+    },
+};
+const DEFAULT_CIRCUIT_OPTIONS = {
+    failureThreshold: CIRCUIT_BREAKER.FAILURE_THRESHOLD,
+    resetTimeMs: CIRCUIT_BREAKER.RESET_TIME_MS,
+    failureWindowMs: CIRCUIT_BREAKER.FAILURE_WINDOW_MS,
+};
+/**
+ * Create a circuit breaker for an operation.
+ *
+ * @example
+ * ```typescript
+ * const protectedCall = createCircuitBreaker('llm-api');
+ *
+ * try {
+ *   const result = await protectedCall(() => llmClient.complete(prompt));
+ * } catch (error) {
+ *   // Either operation error or circuit open error
+ * }
+ * ```
+ */
+export function createCircuitBreaker(name, options = {}) {
+    const { failureThreshold = DEFAULT_CIRCUIT_OPTIONS.failureThreshold, resetTimeMs = DEFAULT_CIRCUIT_OPTIONS.resetTimeMs, failureWindowMs = DEFAULT_CIRCUIT_OPTIONS.failureWindowMs, } = options;
+    const state = {
+        failures: 0,
+        isOpen: false,
+    };
+    const logger = getLogger('circuit-breaker');
+    return async (fn) => {
+        // Check if circuit is open
+        if (state.isOpen) {
+            const now = new Date();
+            const timeSinceOpen = state.openedAt
+                ? now.getTime() - state.openedAt.getTime()
+                : 0;
+            if (timeSinceOpen < resetTimeMs) {
+                // Still in open state
+                throw new BellwetherError(`Circuit breaker '${name}' is open`, {
+                    code: 'CIRCUIT_BREAKER_OPEN',
+                    severity: 'high',
+                    retryable: 'retryable',
+                    context: {
+                        metadata: {
+                            name,
+                            failures: state.failures,
+                            openedAt: state.openedAt?.toISOString(),
+                            timeUntilReset: resetTimeMs - timeSinceOpen,
+                        },
+                    },
+                });
+            }
+            // Half-open: try one request
+            logger.info({
+                circuitBreaker: name,
+                message: `Circuit breaker '${name}' attempting half-open test`,
+            });
+        }
+        try {
+            const result = await fn();
+            // Success: reset state
+            if (state.isOpen) {
+                logger.info({
+                    circuitBreaker: name,
+                    message: `Circuit breaker '${name}' closed after successful test`,
+                });
+            }
+            state.failures = 0;
+            state.isOpen = false;
+            state.openedAt = undefined;
+            return result;
+        }
+        catch (error) {
+            const now = new Date();
+            // Reset failure count if outside window
+            if (state.lastFailure) {
+                const timeSinceLastFailure = now.getTime() - state.lastFailure.getTime();
+                if (timeSinceLastFailure > failureWindowMs) {
+                    state.failures = 0;
+                }
+            }
+            state.failures++;
+            state.lastFailure = now;
+            // Check if we should open the circuit
+            if (state.failures >= failureThreshold && !state.isOpen) {
+                state.isOpen = true;
+                state.openedAt = now;
+                logger.warn({
+                    circuitBreaker: name,
+                    failures: state.failures,
+                    message: `Circuit breaker '${name}' opened after ${state.failures} failures`,
+                });
+            }
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/errors/types.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Comprehensive error types for Bellwether.
+ *
+ * Error hierarchy:
+ * - BellwetherError (base)
+ *   - TransportError (MCP communication)
+ *   - LLMError (LLM provider issues)
+ *   - InterviewError (interview execution)
+ *   - WorkflowError (workflow execution)
+ *   - ConfigError (configuration issues)
+ */
+/**
+ * Error severity levels.
+ */
+export type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Whether an error is retryable.
+ */
+export type RetryableStatus = 'retryable' | 'terminal' | 'unknown';
+/**
+ * Error context for debugging and recovery.
+ */
+export interface ErrorContext {
+    /** Operation that failed */
+    operation?: string;
+    /** Component where error occurred */
+    component?: string;
+    /** Tool name if applicable */
+    tool?: string;
+    /** Workflow ID if applicable */
+    workflow?: string;
+    /** Step index if applicable */
+    stepIndex?: number;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Timing information */
+    timing?: {
+        startedAt: Date;
+        failedAt: Date;
+        durationMs: number;
+    };
+    /** Retry information */
+    retry?: {
+        attempt: number;
+        maxAttempts: number;
+        nextDelayMs?: number;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base error class for all Bellwether errors.
+ */
+export declare class BellwetherError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Error severity */
+    readonly severity: ErrorSeverity;
+    /** Whether this error is retryable */
+    readonly retryable: RetryableStatus;
+    /** Error context for debugging */
+    readonly context: ErrorContext;
+    /** Original error if this wraps another */
+    readonly cause?: Error;
+    constructor(message: string, options: {
+        code: string;
+        severity?: ErrorSeverity;
+        retryable?: RetryableStatus;
+        context?: ErrorContext;
+        cause?: Error;
+    });
+    /**
+     * Create a new error with additional context.
+     */
+    withContext(additionalContext: Partial<ErrorContext>): BellwetherError;
+    /**
+     * Convert to JSON for logging.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Base class for transport-related errors.
+ */
+export declare class TransportError extends BellwetherError {
+    constructor(message: string, options: {
+        code: string;
+        severity?: ErrorSeverity;
+        retryable?: RetryableStatus;
+        context?: ErrorContext;
+        cause?: Error;
+    });
+}
+/**
+ * Connection failed or was lost.
+ */
+export declare class ConnectionError extends TransportError {
+    constructor(message: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Request timed out.
+ */
+export declare class TimeoutError extends TransportError {
+    /** Timeout value in milliseconds */
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Server process exited unexpectedly.
+ */
+export declare class ServerExitError extends TransportError {
+    /** Exit code if available */
+    readonly exitCode?: number;
+    /** Exit signal if available */
+    readonly signal?: string;
+    constructor(message: string, exitCode?: number, signal?: string, context?: ErrorContext);
+}
+/**
+ * Protocol error (invalid message format, etc).
+ */
+export declare class ProtocolError extends TransportError {
+    constructor(message: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Buffer overflow during message processing.
+ */
+export declare class BufferOverflowError extends TransportError {
+    /** Current buffer size */
+    readonly bufferSize: number;
+    /** Maximum allowed size */
+    readonly maxSize: number;
+    constructor(bufferSize: number, maxSize: number, context?: ErrorContext);
+}
+/**
+ * Base class for LLM-related errors.
+ */
+export declare class LLMError extends BellwetherError {
+    /** LLM provider name */
+    readonly provider: string;
+    /** Model name if available */
+    readonly model?: string;
+    constructor(message: string, provider: string, options: {
+        code: string;
+        model?: string;
+        severity?: ErrorSeverity;
+        retryable?: RetryableStatus;
+        context?: ErrorContext;
+        cause?: Error;
+    });
+}
+/**
+ * Authentication/API key error.
+ */
+export declare class LLMAuthError extends LLMError {
+    constructor(provider: string, model?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Rate limit exceeded.
+ */
+export declare class LLMRateLimitError extends LLMError {
+    /** Retry after in milliseconds if known */
+    readonly retryAfterMs?: number;
+    constructor(provider: string, retryAfterMs?: number, model?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Quota/credits exhausted.
+ */
+export declare class LLMQuotaError extends LLMError {
+    constructor(provider: string, model?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Model refused to complete request (content policy, etc).
+ */
+export declare class LLMRefusalError extends LLMError {
+    /** Refusal reason if available */
+    readonly reason?: string;
+    constructor(provider: string, reason?: string, model?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * LLM response parsing failed.
+ */
+export declare class LLMParseError extends LLMError {
+    /** Raw response that couldn't be parsed */
+    readonly rawResponse?: string;
+    constructor(provider: string, rawResponse?: string, model?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * LLM connection failed.
+ */
+export declare class LLMConnectionError extends LLMError {
+    constructor(provider: string, model?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Base class for interview-related errors.
+ */
+export declare class InterviewError extends BellwetherError {
+    constructor(message: string, options: {
+        code: string;
+        severity?: ErrorSeverity;
+        retryable?: RetryableStatus;
+        context?: ErrorContext;
+        cause?: Error;
+    });
+}
+/**
+ * Tool call failed.
+ */
+export declare class ToolCallError extends InterviewError {
+    /** Tool name */
+    readonly toolName: string;
+    /** Arguments passed to tool */
+    readonly args: Record<string, unknown>;
+    constructor(toolName: string, args: Record<string, unknown>, message: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Discovery failed.
+ */
+export declare class DiscoveryError extends InterviewError {
+    constructor(message: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Question generation failed.
+ */
+export declare class QuestionGenerationError extends InterviewError {
+    constructor(toolName: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Analysis/synthesis failed.
+ */
+export declare class AnalysisError extends InterviewError {
+    constructor(phase: 'response' | 'profile' | 'summary', context?: ErrorContext, cause?: Error);
+}
+/**
+ * Base class for workflow-related errors.
+ */
+export declare class WorkflowError extends BellwetherError {
+    /** Workflow ID */
+    readonly workflowId: string;
+    /** Workflow name */
+    readonly workflowName?: string;
+    constructor(message: string, workflowId: string, options: {
+        code: string;
+        workflowName?: string;
+        severity?: ErrorSeverity;
+        retryable?: RetryableStatus;
+        context?: ErrorContext;
+        cause?: Error;
+    });
+}
+/**
+ * Workflow step failed.
+ */
+export declare class WorkflowStepError extends WorkflowError {
+    /** Step index (0-based) */
+    readonly stepIndex: number;
+    /** Tool name for this step */
+    readonly toolName: string;
+    constructor(workflowId: string, stepIndex: number, toolName: string, message: string, workflowName?: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Argument resolution failed (JSON path evaluation).
+ */
+export declare class ArgResolutionError extends WorkflowError {
+    /** The path expression that failed */
+    readonly pathExpression: string;
+    /** Step index where resolution failed */
+    readonly stepIndex: number;
+    constructor(workflowId: string, stepIndex: number, pathExpression: string, message: string, workflowName?: string, context?: ErrorContext);
+}
+/**
+ * Assertion failed during workflow execution.
+ */
+export declare class AssertionError extends WorkflowError {
+    /** The assertion that failed */
+    readonly assertion: string;
+    /** Actual value received */
+    readonly actualValue?: unknown;
+    constructor(workflowId: string, stepIndex: number, assertion: string, actualValue?: unknown, workflowName?: string, context?: ErrorContext);
+}
+/**
+ * Configuration-related error.
+ */
+export declare class ConfigError extends BellwetherError {
+    constructor(message: string, context?: ErrorContext, cause?: Error);
+}
+/**
+ * Configuration file not found.
+ */
+export declare class ConfigNotFoundError extends ConfigError {
+    /** Path that was searched */
+    readonly path: string;
+    constructor(path: string, context?: ErrorContext);
+}
+/**
+ * Configuration validation failed.
+ */
+export declare class ConfigValidationError extends ConfigError {
+    /** Validation errors */
+    readonly validationErrors: string[];
+    constructor(errors: string[], context?: ErrorContext);
+}
+/**
+ * Check if an error is a BellwetherError.
+ */
+export declare function isBellwetherError(error: unknown): error is BellwetherError;
+/**
+ * Check if an error is retryable.
+ */
+export declare function isRetryable(error: unknown): boolean;
+/**
+ * Wrap an unknown error in a BellwetherError.
+ */
+export declare function wrapError(error: unknown, context?: ErrorContext): BellwetherError;
+/**
+ * Extract error message from any error type.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Create timing context for error tracking.
+ */
+export declare function createTimingContext(startedAt: Date): ErrorContext['timing'];
+//# sourceMappingURL=types.d.ts.map