byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/llm/response-validator.js

@@ -0,0 +1,157 @@
+/**
+ * Response Validation Layer
+ *
+ * Validates LLM responses before processing to catch malformed content.
+ * Pure validation only - retry logic is handled by RetryableContentGenerator.
+ */
+/**
+ * Error thrown when response validation fails
+ */
+export class ResponseValidationError extends Error {
+    /**
+     * Original response that failed validation (for debugging)
+     */
+    originalResponse;
+    /**
+     * Type of validation failure
+     */
+    validationType;
+    /**
+     * Create a new ResponseValidationError
+     *
+     * @param message - Human-readable error message
+     * @param validationType - Type of validation failure
+     * @param originalResponse - Original response object (optional)
+     */
+    constructor(message, validationType, originalResponse) {
+        super(message);
+        this.name = 'ResponseValidationError';
+        this.validationType = validationType;
+        this.originalResponse = originalResponse;
+        // Maintain proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ResponseValidationError);
+        }
+    }
+    /**
+     * Convert error to JSON for serialization
+     */
+    toJSON() {
+        return {
+            message: this.message,
+            name: this.name,
+            validationType: this.validationType,
+        };
+    }
+}
+/**
+ * Response validator with validation rules and helper methods.
+ *
+ * Pure validation only - no retry logic.
+ * Retry behavior is handled by RetryableContentGenerator decorator.
+ */
+export const ResponseValidator = {
+    /**
+     * Validate individual message structure
+     *
+     * Checks that message has:
+     * 1. Valid role (assistant)
+     * 2. Either content or tool calls
+     * 3. Well-formed tool calls (if present)
+     *
+     * @param message - Internal message to validate
+     * @throws ResponseValidationError if validation fails
+     */
+    validateMessage(message) {
+        // Validate role
+        if (!message.role) {
+            throw new ResponseValidationError('Message missing role', 'INVALID_ROLE', message);
+        }
+        if (message.role !== 'assistant') {
+            throw new ResponseValidationError(`Invalid role for LLM response: ${message.role} (expected 'assistant')`, 'INVALID_ROLE', message);
+        }
+        // Validate has content or tool calls
+        const hasContent = message.content && ((typeof message.content === 'string' && message.content.length > 0) ||
+            (Array.isArray(message.content) && message.content.length > 0));
+        const hasToolCalls = message.toolCalls && message.toolCalls.length > 0;
+        if (!hasContent && !hasToolCalls) {
+            throw new ResponseValidationError('Message has neither content nor tool calls', 'NO_CONTENT', message);
+        }
+        // Validate tool calls if present
+        if (hasToolCalls && message.toolCalls) {
+            for (const toolCall of message.toolCalls) {
+                if (!toolCall.id) {
+                    throw new ResponseValidationError('Tool call missing id', 'MALFORMED_TOOL_CALL', toolCall);
+                }
+                if (!toolCall.function?.name) {
+                    throw new ResponseValidationError('Tool call missing function name', 'MALFORMED_TOOL_CALL', toolCall);
+                }
+                // Validate arguments is valid JSON string
+                if (toolCall.function.arguments) {
+                    try {
+                        JSON.parse(toolCall.function.arguments);
+                    }
+                    catch {
+                        throw new ResponseValidationError(`Tool call has invalid JSON arguments: ${toolCall.function.arguments}`, 'MALFORMED_TOOL_CALL', toolCall);
+                    }
+                }
+            }
+        }
+    },
+    /**
+     * Validate parsed message array
+     *
+     * Checks that:
+     * 1. Array is not empty
+     * 2. Has at least one message
+     *
+     * @param messages - Parsed messages from formatter
+     * @throws ResponseValidationError if validation fails
+     */
+    validateMessageArray(messages) {
+        // Check has messages
+        if (!Array.isArray(messages) || messages.length === 0) {
+            throw new ResponseValidationError('Response contains no messages', 'NO_MESSAGES', messages);
+        }
+    },
+    /**
+     * Validate raw response from LLM provider
+     *
+     * Checks that response is:
+     * 1. Not null/undefined
+     * 2. An object
+     *
+     * @param response - Raw response from provider
+     * @throws ResponseValidationError if validation fails
+     */
+    validateRawResponse(response) {
+        // Check response exists
+        if (response === null || response === undefined) {
+            throw new ResponseValidationError('Response is null or undefined', 'EMPTY_RESPONSE', response);
+        }
+        // Check response is an object
+        if (typeof response !== 'object') {
+            throw new ResponseValidationError(`Response is not an object: ${typeof response}`, 'EMPTY_RESPONSE', response);
+        }
+    },
+    /**
+     * Validate complete response after parsing
+     *
+     * Runs all validation checks on raw response, message array, and last message.
+     *
+     * @param response - Raw response from provider
+     * @param messages - Parsed messages from formatter
+     * @returns Last message if all validations pass
+     * @throws ResponseValidationError if any validation fails
+     */
+    validateResponse(response, messages) {
+        // Validate raw response
+        this.validateRawResponse(response);
+        // Validate message array
+        this.validateMessageArray(messages);
+        // Get and validate last message
+        const lastMessage = messages.at(-1);
+        this.validateMessage(lastMessage);
+        return lastMessage;
+    },
+};

package/dist/infra/cipher/llm/retry/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Retry exports.
+ *
+ * This module provides retry utilities for LLM operations:
+ * - RetryPolicy: Configuration interface and presets
+ * - withRetry: Generic retry utility with backoff
+ * - RetryableContentGenerator: Decorator for IContentGenerator
+ */
+export { AGGRESSIVE_RETRY_POLICY, calculateRetryDelay, createRetryPolicy, DEFAULT_RETRY_POLICY, isRetryableError, MINIMAL_RETRY_POLICY, NO_RETRY_POLICY, type RetryPolicy, } from './retry-policy.js';
+export { makeRetryable, type RetryContext, type RetryOptions, type RetryResult, withRetry, withRetryResult, } from './retry-with-backoff.js';

package/dist/infra/cipher/llm/retry/index.js

@@ -0,0 +1,10 @@
+/**
+ * Retry exports.
+ *
+ * This module provides retry utilities for LLM operations:
+ * - RetryPolicy: Configuration interface and presets
+ * - withRetry: Generic retry utility with backoff
+ * - RetryableContentGenerator: Decorator for IContentGenerator
+ */
+export { AGGRESSIVE_RETRY_POLICY, calculateRetryDelay, createRetryPolicy, DEFAULT_RETRY_POLICY, isRetryableError, MINIMAL_RETRY_POLICY, NO_RETRY_POLICY, } from './retry-policy.js';
+export { makeRetryable, withRetry, withRetryResult, } from './retry-with-backoff.js';

package/dist/infra/cipher/llm/retry/retry-policy.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Retry Policy Configuration.
+ *
+ * Defines retry behavior for LLM operations with exponential backoff.
+ * Based on patterns from gemini-cli for consistent retry handling.
+ */
+/**
+ * Configuration for retry behavior.
+ */
+export interface RetryPolicy {
+    /** Multiplier for exponential backoff (e.g., 2 = double delay each time) */
+    backoffMultiplier: number;
+    /** Base delay in milliseconds before first retry */
+    baseDelayMs: number;
+    /** Jitter factor (0-1) to randomize delays and prevent thundering herd */
+    jitterFactor: number;
+    /** Maximum delay in milliseconds between retries */
+    maxDelayMs: number;
+    /** Maximum number of retry attempts (0 = no retries) */
+    maxRetries: number;
+    /** Error types/messages that should trigger a retry */
+    retryableErrors: string[];
+    /** HTTP status codes that should trigger a retry */
+    retryableStatusCodes: number[];
+}
+/**
+ * Default retry policy with sensible defaults.
+ *
+ * - 3 retry attempts
+ * - Starting at 1 second, max 30 seconds
+ * - 2x exponential backoff
+ * - 25% jitter
+ * - Retries on common transient errors (429, 500, 502, 503, 504)
+ */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Aggressive retry policy for critical operations.
+ *
+ * More retries with longer delays for operations that must succeed.
+ */
+export declare const AGGRESSIVE_RETRY_POLICY: RetryPolicy;
+/**
+ * Minimal retry policy for fast-fail scenarios.
+ *
+ * Single retry with short delay when quick feedback is preferred.
+ */
+export declare const MINIMAL_RETRY_POLICY: RetryPolicy;
+/**
+ * No retry policy - fail immediately on any error.
+ */
+export declare const NO_RETRY_POLICY: RetryPolicy;
+/**
+ * Create a custom retry policy by merging with defaults.
+ *
+ * @param overrides - Partial policy to override defaults
+ * @returns Complete retry policy
+ */
+export declare function createRetryPolicy(overrides: Partial<RetryPolicy>): RetryPolicy;
+/**
+ * Check if an error should be retried based on the policy.
+ *
+ * @param error - The error to check
+ * @param policy - The retry policy to use
+ * @returns True if the error is retryable
+ */
+export declare function isRetryableError(error: unknown, policy: RetryPolicy): boolean;
+/**
+ * Calculate delay for a specific retry attempt with exponential backoff and jitter.
+ *
+ * @param attempt - Current retry attempt (1-based)
+ * @param policy - The retry policy to use
+ * @returns Delay in milliseconds
+ */
+export declare function calculateRetryDelay(attempt: number, policy: RetryPolicy): number;

package/dist/infra/cipher/llm/retry/retry-policy.js

@@ -0,0 +1,146 @@
+/**
+ * Retry Policy Configuration.
+ *
+ * Defines retry behavior for LLM operations with exponential backoff.
+ * Based on patterns from gemini-cli for consistent retry handling.
+ */
+/**
+ * Default retry policy with sensible defaults.
+ *
+ * - 3 retry attempts
+ * - Starting at 1 second, max 30 seconds
+ * - 2x exponential backoff
+ * - 25% jitter
+ * - Retries on common transient errors (429, 500, 502, 503, 504)
+ */
+export const DEFAULT_RETRY_POLICY = {
+    backoffMultiplier: 2,
+    baseDelayMs: 1000,
+    jitterFactor: 0.25,
+    maxDelayMs: 30_000,
+    maxRetries: 3,
+    retryableErrors: [
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'ECONNREFUSED',
+        'ENOTFOUND',
+        'rate_limit',
+        'overloaded',
+        'capacity',
+        'timeout',
+        'temporarily unavailable',
+    ],
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+};
+/**
+ * Aggressive retry policy for critical operations.
+ *
+ * More retries with longer delays for operations that must succeed.
+ */
+export const AGGRESSIVE_RETRY_POLICY = {
+    backoffMultiplier: 2,
+    baseDelayMs: 2000,
+    jitterFactor: 0.3,
+    maxDelayMs: 60_000,
+    maxRetries: 5,
+    retryableErrors: [
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'ECONNREFUSED',
+        'ENOTFOUND',
+        'rate_limit',
+        'overloaded',
+        'capacity',
+        'timeout',
+        'temporarily unavailable',
+    ],
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+};
+/**
+ * Minimal retry policy for fast-fail scenarios.
+ *
+ * Single retry with short delay when quick feedback is preferred.
+ */
+export const MINIMAL_RETRY_POLICY = {
+    backoffMultiplier: 2,
+    baseDelayMs: 500,
+    jitterFactor: 0.1,
+    maxDelayMs: 2000,
+    maxRetries: 1,
+    retryableErrors: ['rate_limit', 'overloaded'],
+    retryableStatusCodes: [429, 503],
+};
+/**
+ * No retry policy - fail immediately on any error.
+ */
+export const NO_RETRY_POLICY = {
+    backoffMultiplier: 1,
+    baseDelayMs: 0,
+    jitterFactor: 0,
+    maxDelayMs: 0,
+    maxRetries: 0,
+    retryableErrors: [],
+    retryableStatusCodes: [],
+};
+/**
+ * Create a custom retry policy by merging with defaults.
+ *
+ * @param overrides - Partial policy to override defaults
+ * @returns Complete retry policy
+ */
+export function createRetryPolicy(overrides) {
+    return {
+        ...DEFAULT_RETRY_POLICY,
+        ...overrides,
+    };
+}
+/**
+ * Check if an error should be retried based on the policy.
+ *
+ * @param error - The error to check
+ * @param policy - The retry policy to use
+ * @returns True if the error is retryable
+ */
+export function isRetryableError(error, policy) {
+    // Check if we have any retry configuration
+    if (policy.maxRetries === 0) {
+        return false;
+    }
+    // Handle HTTP-like errors with status codes
+    if (error && typeof error === 'object') {
+        const errorObj = error;
+        // Check status code
+        const status = errorObj.status ?? errorObj.statusCode ?? errorObj.code;
+        if (typeof status === 'number' && policy.retryableStatusCodes.includes(status)) {
+            return true;
+        }
+        // Check for gRPC status codes (common transient errors)
+        const grpcCode = errorObj.code;
+        // gRPC codes: 14 = UNAVAILABLE, 8 = RESOURCE_EXHAUSTED, 4 = DEADLINE_EXCEEDED
+        if (typeof grpcCode === 'number' && [4, 8, 14].includes(grpcCode)) {
+            return true;
+        }
+    }
+    // Check error message against retryable patterns
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const lowerMessage = errorMessage.toLowerCase();
+    return policy.retryableErrors.some((pattern) => lowerMessage.includes(pattern.toLowerCase()));
+}
+/**
+ * Calculate delay for a specific retry attempt with exponential backoff and jitter.
+ *
+ * @param attempt - Current retry attempt (1-based)
+ * @param policy - The retry policy to use
+ * @returns Delay in milliseconds
+ */
+export function calculateRetryDelay(attempt, policy) {
+    // Calculate base exponential delay
+    const exponentialDelay = policy.baseDelayMs * policy.backoffMultiplier ** (attempt - 1);
+    // Cap at max delay
+    const cappedDelay = Math.min(exponentialDelay, policy.maxDelayMs);
+    // Apply jitter (randomize within jitter factor range)
+    const jitterRange = cappedDelay * policy.jitterFactor;
+    const jitter = Math.random() * jitterRange * 2 - jitterRange;
+    // Ensure delay is at least 0
+    return Math.max(0, Math.round(cappedDelay + jitter));
+}

package/dist/infra/cipher/llm/retry/retry-with-backoff.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Retry with Backoff Utility.
+ *
+ * Provides a generic retry mechanism with exponential backoff for async operations.
+ * Used by RetryableContentGenerator and can be used for other retry scenarios.
+ */
+import { type RetryPolicy } from './retry-policy.js';
+/**
+ * Context provided to retry callbacks.
+ */
+export interface RetryContext {
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Delay before next retry in milliseconds */
+    delayMs: number;
+    /** The error that triggered the retry */
+    error: unknown;
+    /** Maximum number of attempts */
+    maxAttempts: number;
+}
+/**
+ * Options for the retry operation.
+ */
+export interface RetryOptions {
+    /** Custom function to determine if an error is retryable */
+    isRetryable?: (error: unknown) => boolean;
+    /** Callback invoked when all retries are exhausted */
+    onExhausted?: (context: RetryContext) => void;
+    /** Callback invoked before each retry attempt */
+    onRetry?: (context: RetryContext) => void;
+    /** Retry policy configuration */
+    policy?: RetryPolicy;
+    /** Abort signal to cancel retries */
+    signal?: AbortSignal;
+}
+/**
+ * Result of a retry operation.
+ */
+export interface RetryResult<T> {
+    /** Number of attempts made */
+    attempts: number;
+    /** The final error if failed */
+    error?: unknown;
+    /** The result if successful */
+    result?: T;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Total time spent in milliseconds */
+    totalTimeMs: number;
+}
+/**
+ * Execute an async operation with retry and exponential backoff.
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry options
+ * @returns Promise resolving to the operation result or throwing after all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   {
+ *     policy: DEFAULT_RETRY_POLICY,
+ *     onRetry: ({ attempt, delayMs }) => {
+ *       console.log(`Retry ${attempt}, waiting ${delayMs}ms`)
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Execute an async operation with retry and return a detailed result.
+ *
+ * Unlike `withRetry`, this function never throws and always returns a result object.
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry options
+ * @returns Promise resolving to a RetryResult object
+ *
+ * @example
+ * ```typescript
+ * const { success, result, error, attempts } = await withRetryResult(
+ *   () => fetchData(),
+ *   { policy: DEFAULT_RETRY_POLICY }
+ * )
+ *
+ * if (success) {
+ *   console.log('Data:', result)
+ * } else {
+ *   console.error('Failed after', attempts, 'attempts:', error)
+ * }
+ * ```
+ */
+export declare function withRetryResult<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * Create a retryable version of an async function.
+ *
+ * @param fn - The async function to wrap
+ * @param options - Retry options
+ * @returns A new function that will retry on failure
+ *
+ * @example
+ * ```typescript
+ * const retryableFetch = makeRetryable(
+ *   (url: string) => fetch(url).then(r => r.json()),
+ *   { policy: DEFAULT_RETRY_POLICY }
+ * )
+ *
+ * const data = await retryableFetch('https://api.example.com/data')
+ * ```
+ */
+export declare function makeRetryable<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, options?: RetryOptions): (...args: TArgs) => Promise<TResult>;