byterover-cli 0.4.0 → 1.0.0

package/dist/core/domain/cipher/agent-events/types.d.ts

@@ -7,11 +7,11 @@ export declare const AGENT_EVENT_NAMES: readonly ["cipher:conversationReset", "c
  * Session-level event names for LLM service operations.
  * These events are emitted at the session level and do not include sessionId in payloads.
  */
-export declare const SESSION_EVENT_NAMES: readonly ["llmservice:chunk", "llmservice:error", "llmservice:outputTruncated", "llmservice:response", "llmservice:thinking", "llmservice:thought", "llmservice:toolCall", "llmservice:toolResult", "llmservice:unsupportedInput", "llmservice:warning"];
+export declare const SESSION_EVENT_NAMES: readonly ["llmservice:chunk", "llmservice:contextCompressed", "llmservice:contextOverflow", "llmservice:contextPruned", "llmservice:doomLoopDetected", "llmservice:error", "llmservice:outputTruncated", "llmservice:response", "llmservice:thinking", "llmservice:thought", "llmservice:toolCall", "llmservice:toolMetadata", "llmservice:toolResult", "llmservice:unsupportedInput", "llmservice:warning", "message:dequeued", "message:queued", "run:complete", "session:statusChanged", "step:finished", "step:started"];
 /**
  * All event names (union of agent and session events).
  */
-export declare const EVENT_NAMES: readonly ["cipher:conversationReset", "cipher:executionStarted", "cipher:executionTerminated", "cipher:log", "cipher:stateChanged", "cipher:stateReset", "cipher:ui", "llmservice:chunk", "llmservice:error", "llmservice:outputTruncated", "llmservice:response", "llmservice:thinking", "llmservice:thought", "llmservice:toolCall", "llmservice:toolResult", "llmservice:unsupportedInput", "llmservice:warning"];
+export declare const EVENT_NAMES: readonly ["cipher:conversationReset", "cipher:executionStarted", "cipher:executionTerminated", "cipher:log", "cipher:stateChanged", "cipher:stateReset", "cipher:ui", "llmservice:chunk", "llmservice:contextCompressed", "llmservice:contextOverflow", "llmservice:contextPruned", "llmservice:doomLoopDetected", "llmservice:error", "llmservice:outputTruncated", "llmservice:response", "llmservice:thinking", "llmservice:thought", "llmservice:toolCall", "llmservice:toolMetadata", "llmservice:toolResult", "llmservice:unsupportedInput", "llmservice:warning", "message:dequeued", "message:queued", "run:complete", "session:statusChanged", "step:finished", "step:started"];
 /**
  * Union type of all agent event names.
  */
@@ -156,36 +156,105 @@ export interface AgentEventMap {
      * @property {string} content - Content of the chunk
      * @property {boolean} [isComplete] - Whether this is the final chunk
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {'reasoning' | 'text'} type - Type of chunk (text or reasoning)
      */
     'llmservice:chunk': {
         content: string;
         isComplete?: boolean;
         sessionId: string;
+        taskId?: string;
         type: 'reasoning' | 'text';
     };
+    /**
+     * Emitted when conversation context is compressed via summarization.
+     * @property {number} compressedTokens - Token count after compression
+     * @property {number} originalTokens - Token count before compression
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {'middle_removal' | 'oldest_removal' | 'summary'} strategy - Compression strategy used
+     */
+    'llmservice:contextCompressed': {
+        compressedTokens: number;
+        originalTokens: number;
+        sessionId: string;
+        strategy: 'middle_removal' | 'oldest_removal' | 'summary';
+        taskId?: string;
+    };
+    /**
+     * Emitted when context is approaching the token limit.
+     * @property {number} currentTokens - Current token count
+     * @property {number} maxTokens - Maximum allowed tokens
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {number} utilizationPercent - Percentage of context used (0-100)
+     */
+    'llmservice:contextOverflow': {
+        currentTokens: number;
+        maxTokens: number;
+        sessionId: string;
+        taskId?: string;
+        utilizationPercent: number;
+    };
+    /**
+     * Emitted when old tool outputs are pruned to save context space.
+     * @property {number} pruneCount - Number of tool outputs pruned
+     * @property {'manual' | 'overflow'} reason - Why pruning was triggered
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {number} tokensSaved - Estimated tokens saved
+     */
+    'llmservice:contextPruned': {
+        pruneCount: number;
+        reason: 'manual' | 'overflow';
+        sessionId: string;
+        taskId?: string;
+        tokensSaved: number;
+    };
+    /**
+     * Emitted when a doom loop is detected (repeated identical tool calls).
+     * The tool call is automatically rejected to prevent infinite loops.
+     * @property {Record<string, unknown>} args - Arguments that were repeated
+     * @property {'exact_repeat' | 'oscillation'} loopType - Type of loop detected
+     * @property {number} repeatCount - Number of times the pattern repeated
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {string} toolName - Name of the tool involved in the loop
+     */
+    'llmservice:doomLoopDetected': {
+        args: Record<string, unknown>;
+        loopType: 'exact_repeat' | 'oscillation';
+        repeatCount: number;
+        sessionId: string;
+        taskId?: string;
+        toolName: string;
+    };
     /**
      * Emitted when an error occurs during LLM service operation.
      * @property {string} [code] - Error code (optional)
      * @property {string} error - Error message
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:error': {
         code?: string;
         error: string;
         sessionId: string;
+        taskId?: string;
     };
     /**
      * Emitted when tool output is truncated due to size.
      * @property {number} originalLength - Original output length before truncation
      * @property {string} savedToFile - Path to file where full output was saved
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the tool that produced the output
      */
     'llmservice:outputTruncated': {
         originalLength: number;
         savedToFile: string;
         sessionId: string;
+        taskId?: string;
         toolName: string;
     };
     /**
@@ -196,6 +265,7 @@ export interface AgentEventMap {
      * @property {string} [provider] - LLM provider name
      * @property {string} [reasoning] - Internal reasoning (if available)
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {TokenUsage} [tokenUsage] - Token usage statistics
      */
     'llmservice:response': {
@@ -205,33 +275,40 @@ export interface AgentEventMap {
         provider?: string;
         reasoning?: string;
         sessionId: string;
+        taskId?: string;
         tokenUsage?: TokenUsage;
     };
     /**
      * Emitted when LLM service starts thinking/processing.
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:thinking': {
         sessionId: string;
+        taskId?: string;
     };
     /**
      * Emitted when LLM generates a thought (Gemini models only).
      * @property {string} description - Detailed thought description
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} subject - Brief thought subject
      */
     'llmservice:thought': {
         description: string;
         sessionId: string;
         subject: string;
+        taskId?: string;
     };
     /**
      * Emitted when the todo list is updated via write_todos tool.
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {Array<{content: string, status: string, activeForm: string}>} todos - Updated todo list
      */
     'llmservice:todoUpdated': {
         sessionId: string;
+        taskId?: string;
         todos: Array<{
             activeForm: string;
             content: string;
@@ -243,12 +320,33 @@ export interface AgentEventMap {
      * @property {Record<string, unknown>} args - Arguments for the tool
      * @property {string} [callId] - Unique identifier for this tool call
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the tool to execute
      */
     'llmservice:toolCall': {
         args: Record<string, unknown>;
         callId?: string;
         sessionId: string;
+        taskId?: string;
+        toolName: string;
+    };
+    /**
+     * Emitted when a tool streams metadata updates during execution.
+     * Allows tools to push real-time updates (e.g., bash output streaming).
+     * @property {string} callId - Tool call identifier
+     * @property {string} [description] - Human-readable status description
+     * @property {Record<string, unknown>} metadata - The metadata update
+     * @property {string} [output] - Streamed output content
+     * @property {number} [progress] - Progress indicator (0-100)
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {string} toolName - Name of the tool streaming metadata
+     */
+    'llmservice:toolMetadata': {
+        callId: string;
+        metadata: Record<string, unknown>;
+        sessionId: string;
+        taskId?: string;
         toolName: string;
     };
     /**
@@ -259,6 +357,7 @@ export interface AgentEventMap {
      * @property {Record<string, unknown>} [metadata] - Execution metadata (duration, tokens, etc.)
      * @property {unknown} [result] - Tool execution result
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {boolean} success - Whether execution succeeded
      * @property {string} toolName - Name of the executed tool
      */
@@ -270,16 +369,19 @@ export interface AgentEventMap {
         result?: unknown;
         sessionId: string;
         success: boolean;
+        taskId?: string;
         toolName: string;
     };
     /**
      * Emitted when LLM receives unsupported input.
      * @property {string} reason - Reason why input is unsupported
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:unsupportedInput': {
         reason: string;
         sessionId: string;
+        taskId?: string;
     };
     /**
      * Emitted when LLM service encounters a warning (e.g., max iterations reached).
@@ -287,12 +389,103 @@ export interface AgentEventMap {
      * @property {string} [model] - Model identifier
      * @property {string} [provider] - LLM provider name
      * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:warning': {
         message: string;
         model?: string;
         provider?: string;
         sessionId: string;
+        taskId?: string;
+    };
+    /**
+     * Emitted when queued messages are dequeued for processing.
+     * @property {number} count - Number of messages that were dequeued
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     */
+    'message:dequeued': {
+        count: number;
+        sessionId: string;
+        taskId?: string;
+    };
+    /**
+     * Emitted when a message is queued because session is busy.
+     * @property {object} message - The queued message
+     * @property {string} message.id - Unique identifier for the queued message
+     * @property {string} message.content - Message text content
+     * @property {number} message.queuedAt - Timestamp when queued
+     * @property {number} position - Position in the queue (1-based)
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     */
+    'message:queued': {
+        message: {
+            content: string;
+            id: string;
+            queuedAt: number;
+        };
+        position: number;
+        sessionId: string;
+        taskId?: string;
+    };
+    /**
+     * Emitted when a session run completes (streaming API lifecycle event).
+     * @property {number} durationMs - Execution duration in milliseconds
+     * @property {Error} [error] - Error if terminated due to error
+     * @property {'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout'} finishReason - Why execution terminated
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {number} stepCount - Number of agentic steps completed
+     */
+    'run:complete': {
+        durationMs: number;
+        error?: Error;
+        finishReason: 'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout';
+        sessionId: string;
+        stepCount: number;
+        taskId?: string;
+    };
+    /**
+     * Emitted when session status changes.
+     * Tracks the lifecycle state of a session (idle, busy, retry, waiting).
+     * @property {string} sessionId - ID of the session
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {SessionStatusType} status - The new session status
+     */
+    'session:statusChanged': {
+        sessionId: string;
+        status: SessionStatusType;
+        taskId?: string;
+    };
+    /**
+     * Emitted when an execution step finishes.
+     * Provides per-step cost and token tracking.
+     * @property {number} cost - Cost in dollars for this step
+     * @property {'max_tokens' | 'stop' | 'tool_calls'} finishReason - Why step finished
+     * @property {string} sessionId - ID of the session
+     * @property {number} stepIndex - Step index (0-based)
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     * @property {StepTokenUsage} tokens - Token usage for this step
+     */
+    'step:finished': {
+        cost: number;
+        finishReason: 'max_tokens' | 'stop' | 'tool_calls';
+        sessionId: string;
+        stepIndex: number;
+        taskId?: string;
+        tokens: StepTokenUsage;
+    };
+    /**
+     * Emitted when an execution step starts.
+     * @property {string} sessionId - ID of the session
+     * @property {number} stepIndex - Step index (0-based)
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
+     */
+    'step:started': {
+        sessionId: string;
+        stepIndex: number;
+        taskId?: string;
     };
 }
 /**
@@ -311,6 +504,53 @@ export interface SessionEventMap {
         isComplete?: boolean;
         type: 'reasoning' | 'text';
     };
+    /**
+     * Emitted when conversation context is compressed via summarization.
+     * @property {number} compressedTokens - Token count after compression
+     * @property {number} originalTokens - Token count before compression
+     * @property {'middle_removal' | 'oldest_removal' | 'summary'} strategy - Compression strategy used
+     */
+    'llmservice:contextCompressed': {
+        compressedTokens: number;
+        originalTokens: number;
+        strategy: 'middle_removal' | 'oldest_removal' | 'summary';
+    };
+    /**
+     * Emitted when context is approaching the token limit.
+     * @property {number} currentTokens - Current token count
+     * @property {number} maxTokens - Maximum allowed tokens
+     * @property {number} utilizationPercent - Percentage of context used (0-100)
+     */
+    'llmservice:contextOverflow': {
+        currentTokens: number;
+        maxTokens: number;
+        utilizationPercent: number;
+    };
+    /**
+     * Emitted when old tool outputs are pruned to save context space.
+     * @property {number} pruneCount - Number of tool outputs pruned
+     * @property {'manual' | 'overflow'} reason - Why pruning was triggered
+     * @property {number} tokensSaved - Estimated tokens saved
+     */
+    'llmservice:contextPruned': {
+        pruneCount: number;
+        reason: 'manual' | 'overflow';
+        tokensSaved: number;
+    };
+    /**
+     * Emitted when a doom loop is detected (repeated identical tool calls).
+     * The tool call is automatically rejected to prevent infinite loops.
+     * @property {Record<string, unknown>} args - Arguments that were repeated
+     * @property {'exact_repeat' | 'oscillation'} loopType - Type of loop detected
+     * @property {number} repeatCount - Number of times the pattern repeated
+     * @property {string} toolName - Name of the tool involved in the loop
+     */
+    'llmservice:doomLoopDetected': {
+        args: Record<string, unknown>;
+        loopType: 'exact_repeat' | 'oscillation';
+        repeatCount: number;
+        toolName: string;
+    };
     /**
      * Emitted when an error occurs during LLM service operation.
      * @property {string} [code] - Error code (optional)
@@ -372,6 +612,18 @@ export interface SessionEventMap {
         callId?: string;
         toolName: string;
     };
+    /**
+     * Emitted when a tool streams metadata updates during execution.
+     * Allows tools to push real-time updates (e.g., bash output streaming).
+     * @property {string} callId - Tool call identifier
+     * @property {Record<string, unknown>} metadata - The metadata update
+     * @property {string} toolName - Name of the tool streaming metadata
+     */
+    'llmservice:toolMetadata': {
+        callId: string;
+        metadata: Record<string, unknown>;
+        toolName: string;
+    };
     /**
      * Emitted when a tool execution completes.
      * @property {string} [callId] - Tool call identifier
@@ -409,7 +661,108 @@ export interface SessionEventMap {
         model?: string;
         provider?: string;
     };
+    /**
+     * Emitted when queued messages are dequeued for processing.
+     * @property {number} count - Number of messages that were dequeued
+     */
+    'message:dequeued': {
+        count: number;
+    };
+    /**
+     * Emitted when a message is queued because session is busy.
+     * @property {object} message - The queued message
+     * @property {string} message.id - Unique identifier for the queued message
+     * @property {string} message.content - Message text content
+     * @property {number} message.queuedAt - Timestamp when queued
+     * @property {number} position - Position in the queue (1-based)
+     */
+    'message:queued': {
+        message: {
+            content: string;
+            id: string;
+            queuedAt: number;
+        };
+        position: number;
+    };
+    /**
+     * Emitted when a session run completes (streaming API lifecycle event).
+     * @property {number} durationMs - Execution duration in milliseconds
+     * @property {Error} [error] - Error if terminated due to error
+     * @property {'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout'} finishReason - Why execution terminated
+     * @property {number} stepCount - Number of agentic steps completed
+     */
+    'run:complete': {
+        durationMs: number;
+        error?: Error;
+        finishReason: 'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout';
+        stepCount: number;
+    };
+    /**
+     * Emitted when session status changes.
+     * Tracks the lifecycle state of a session (idle, busy, retry, waiting).
+     * @property {SessionStatusType} status - The new session status
+     */
+    'session:statusChanged': {
+        status: SessionStatusType;
+    };
+    /**
+     * Emitted when an execution step finishes.
+     * Provides per-step cost and token tracking.
+     * @property {number} cost - Cost in dollars for this step
+     * @property {'max_tokens' | 'stop' | 'tool_calls'} finishReason - Why step finished
+     * @property {number} stepIndex - Step index (0-based)
+     * @property {StepTokenUsage} tokens - Token usage for this step
+     */
+    'step:finished': {
+        cost: number;
+        finishReason: 'max_tokens' | 'stop' | 'tool_calls';
+        stepIndex: number;
+        tokens: StepTokenUsage;
+    };
+    /**
+     * Emitted when an execution step starts.
+     * @property {number} stepIndex - Step index (0-based)
+     */
+    'step:started': {
+        stepIndex: number;
+    };
 }
+/**
+ * Token usage for a single execution step.
+ */
+export interface StepTokenUsage {
+    /** Cache tokens (read/write) */
+    cache?: {
+        read: number;
+        write: number;
+    };
+    /** Input tokens consumed */
+    input: number;
+    /** Output tokens generated */
+    output: number;
+    /** Reasoning tokens (if extended thinking enabled) */
+    reasoning?: number;
+}
+/**
+ * Session status type representing lifecycle states.
+ * - busy: Session is currently executing a request
+ * - idle: Session is ready to accept new messages
+ * - retry: Session is waiting to retry after a transient error
+ * - waiting_permission: Session is waiting for user permission (e.g., tool confirmation)
+ */
+export type SessionStatusType = {
+    attempt: number;
+    message: string;
+    nextRetryAt: number;
+    type: 'retry';
+} | {
+    toolName: string;
+    type: 'waiting_permission';
+} | {
+    type: 'busy';
+} | {
+    type: 'idle';
+};
 /**
  * Prevent unused variable warnings for compile-time checks.
  */

package/dist/core/domain/cipher/agent-events/types.js

@@ -17,15 +17,26 @@ export const AGENT_EVENT_NAMES = [
  */
 export const SESSION_EVENT_NAMES = [
     'llmservice:chunk',
+    'llmservice:contextCompressed',
+    'llmservice:contextOverflow',
+    'llmservice:contextPruned',
+    'llmservice:doomLoopDetected',
     'llmservice:error',
     'llmservice:outputTruncated',
     'llmservice:response',
     'llmservice:thinking',
     'llmservice:thought',
     'llmservice:toolCall',
+    'llmservice:toolMetadata',
     'llmservice:toolResult',
     'llmservice:unsupportedInput',
     'llmservice:warning',
+    'message:dequeued',
+    'message:queued',
+    'run:complete',
+    'session:statusChanged',
+    'step:finished',
+    'step:started',
 ];
 /**
  * All event names (union of agent and session events).

package/dist/core/domain/cipher/errors/error-normalizer.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Error Normalizer
+ *
+ * Converts various error types into a unified, normalized format.
+ * Following the OpenCode pattern of MessageV2.fromError() for consistent
+ * error handling across providers.
+ *
+ * Key features:
+ * - Discriminated union for error types
+ * - Provider-agnostic error representation
+ * - Retryable error detection
+ * - Consistent error structure for UI consumption
+ */
+/**
+ * Normalized error types following OpenCode pattern.
+ * Discriminated by the `type` field for easy pattern matching.
+ */
+export type NormalizedError = NormalizedAbortedError | NormalizedApiError | NormalizedAuthError | NormalizedConfigError | NormalizedOutputLengthError | NormalizedRateLimitError | NormalizedToolError | NormalizedUnknownError;
+/**
+ * Authentication/authorization error.
+ */
+export interface NormalizedAuthError {
+    /** Error message */
+    message: string;
+    /** Provider that rejected auth */
+    providerId: string;
+    type: 'auth';
+}
+/**
+ * API call error (network, server errors, etc.).
+ */
+export interface NormalizedApiError {
+    /** Whether this error can be retried */
+    isRetryable: boolean;
+    /** Error message */
+    message: string;
+    /** Model that was being used */
+    model?: string;
+    /** Provider that returned the error */
+    providerId?: string;
+    /** HTTP status code if available */
+    statusCode?: number;
+    type: 'api';
+}
+/**
+ * Request was aborted/cancelled.
+ */
+export interface NormalizedAbortedError {
+    /** Error message */
+    message: string;
+    type: 'aborted';
+}
+/**
+ * Output length exceeded (max tokens).
+ */
+export interface NormalizedOutputLengthError {
+    /** Maximum tokens that were allowed */
+    maxTokens?: number;
+    /** Error message */
+    message: string;
+    type: 'output_length';
+}
+/**
+ * Rate limit exceeded.
+ */
+export interface NormalizedRateLimitError {
+    /** Error message */
+    message: string;
+    /** Provider that rate limited */
+    providerId: string;
+    /** When to retry (seconds) */
+    retryAfter?: number;
+    type: 'rate_limit';
+}
+/**
+ * Tool execution error.
+ */
+export interface NormalizedToolError {
+    /** Error message */
+    message: string;
+    /** Name of the tool that failed */
+    toolName: string;
+    type: 'tool';
+}
+/**
+ * Configuration error.
+ */
+export interface NormalizedConfigError {
+    /** Configuration key that's problematic */
+    configKey: string;
+    /** Error message */
+    message: string;
+    /** Provider if applicable */
+    providerId?: string;
+    type: 'config';
+}
+/**
+ * Unknown/unclassified error.
+ */
+export interface NormalizedUnknownError {
+    /** Error message */
+    message: string;
+    /** Original error if available */
+    originalError?: Error;
+    type: 'unknown';
+}
+/**
+ * Context for error normalization.
+ */
+export interface ErrorContext {
+    /** Model being used */
+    model?: string;
+    /** Provider being used */
+    providerId?: string;
+    /** Session ID if applicable */
+    sessionId?: string;
+}
+/**
+ * Normalize any error into a consistent format.
+ *
+ * This function handles all known error types and converts them
+ * to a unified NormalizedError format for consistent handling.
+ *
+ * @param error - The error to normalize
+ * @param context - Optional context about the operation
+ * @returns Normalized error with consistent structure
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await llm.generate(prompt)
+ * } catch (error) {
+ *   const normalized = normalizeError(error, { providerId: 'claude' })
+ *
+ *   switch (normalized.type) {
+ *     case 'rate_limit':
+ *       await sleep(normalized.retryAfter * 1000)
+ *       break
+ *     case 'auth':
+ *       showLoginPrompt()
+ *       break
+ *     default:
+ *       logError(normalized.message)
+ *   }
+ * }
+ * ```
+ */
+export declare function normalizeError(error: unknown, context?: ErrorContext): NormalizedError;
+/**
+ * Check if a normalized error is retryable.
+ */
+export declare function isNormalizedErrorRetryable(error: NormalizedError): boolean;
+/**
+ * Get a user-friendly message for a normalized error.
+ */
+export declare function getErrorDisplayMessage(error: NormalizedError): string;