@llumiverse/common 1.0.0-dev.20260224.234313Z → 1.0.0-dev.20260331.080752Z

package/src/types.ts

@@ -172,6 +172,137 @@ export interface ResultValidationError {
     data?: CompletionResult[];
 }
 
+/**
+ * Context information for LlumiverseError.
+ * Provides details about where and how the error occurred.
+ */
+export interface LlumiverseErrorContext {
+    /** The provider that generated the error (e.g., 'openai', 'bedrock', 'vertexai') */
+    provider: string;
+    /** The model that was being used when the error occurred */
+    model: string;
+    /** The operation that failed */
+    operation: 'execute' | 'stream';
+}
+
+/**
+ * Standardized error class for Llumiverse driver errors.
+ * 
+ * Normalizes errors from different LLM providers (OpenAI, Anthropic, Bedrock, VertexAI, etc.)
+ * into a consistent format. The primary value is the `retryable` flag, which enables upstream
+ * consumers to implement smart retry logic.
+ * 
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await driver.execute(segments, options);
+ * } catch (error) {
+ *   if (LlumiverseError.isLlumiverseError(error)) {
+ *     console.log(`Provider: ${error.context.provider}`);
+ *     console.log(`Model: ${error.context.model}`);
+ *     console.log(`Retryable: ${error.retryable}`);
+ *     
+ *     if (error.retryable) {
+ *       // Implement retry logic with exponential backoff
+ *       await retryWithBackoff(() => driver.execute(segments, options));
+ *     } else {
+ *       // Handle non-retryable error (e.g., invalid API key, malformed request)
+ *       logError(error);
+ *     }
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export class LlumiverseError extends Error {
+    /** 
+     * HTTP status code (e.g., 429, 500) if available.
+     * Undefined if the error doesn't have a numeric status code.
+     */
+    readonly code?: number;
+
+    /**
+     * Provider-specific error name/type (e.g., "ThrottlingException", "ValidationException").
+     * Optional - used to preserve the semantic error type from the provider SDK.
+     */
+    readonly name: string;
+
+    /** 
+     * Whether this error is retryable.
+     * - True: Definitely retryable (rate limits, timeouts, server errors)
+     * - False: Definitely not retryable (auth failures, invalid requests, malformed schemas)
+     * - Undefined: Unknown retryability - allows consumers to decide default behavior
+     * 
+     * When undefined, consumers can choose their retry strategy:
+     * - Conservative: Don't retry unknown errors (avoid spam)
+     * - Resilient: Retry unknown errors (prioritize success)
+     */
+    readonly retryable?: boolean;
+
+    /**
+     * Context about where and how the error occurred.
+     * Includes provider, model, operation type.
+     */
+    readonly context: LlumiverseErrorContext;
+
+    /**
+     * The original error from the provider SDK.
+     * Preserved for debugging and detailed error inspection.
+     */
+    readonly originalError: unknown;
+
+    constructor(
+        message: string,
+        retryable: boolean | undefined,
+        context: LlumiverseErrorContext,
+        originalError: unknown,
+        code?: number,
+        name?: string
+    ) {
+        super(message);
+        this.name = name || 'LlumiverseError';
+        this.code = code;
+        this.retryable = retryable;
+        this.context = context;
+        this.originalError = originalError;
+
+        // Preserve stack trace from original error if available
+        if (originalError instanceof Error && originalError.stack) {
+            this.stack = originalError.stack;
+        }
+    }
+
+    /**
+     * Serialize the error to JSON for logging or transmission.
+     * Includes all error properties except the original error object itself.
+     */
+    toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            retryable: this.retryable,
+            context: this.context,
+            stack: this.stack,
+            // Include original error message if available
+            originalErrorMessage: this.originalError instanceof Error
+                ? this.originalError.message
+                : String(this.originalError),
+        };
+    }
+
+    /**
+     * Type guard to check if an error is a LlumiverseError.
+     * Useful for conditional error handling.
+     * 
+     * @param error - The error to check
+     * @returns True if the error is a LlumiverseError
+     */
+    static isLlumiverseError(error: unknown): error is LlumiverseError {
+        return error instanceof LlumiverseError;
+    }
+}
+
 // ============== Result Types ===============
 
 export interface BaseResult {
@@ -402,6 +533,14 @@ export interface ExecutionOptions extends StatelessExecutionOptions {
      * - N > 0: Truncate text to approximately N tokens (using ~4 chars/token estimate)
      */
     stripTextMaxTokens?: number;
+
+    /**
+     * Number of turns to keep heartbeat messages before stripping.
+     * - 0: Strip immediately
+     * - 1 (default): Keep for 1 turn then strip
+     * - undefined: Same as 1, strip after 1 turn
+     */
+    stripHeartbeatsAfterTurns?: number;
 }
 
 //Common names to share between different models