byterover-cli 0.2.1 → 0.3.1

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

@@ -0,0 +1,419 @@
+/**
+ * Agent-level event names for CipherAgent.
+ * These events are emitted at the agent level and include sessionId in payloads.
+ */
+export declare const AGENT_EVENT_NAMES: readonly ["cipher:conversationReset", "cipher:executionStarted", "cipher:executionTerminated", "cipher:log", "cipher:stateChanged", "cipher:stateReset", "cipher:ui"];
+/**
+ * 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"];
+/**
+ * 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"];
+/**
+ * Union type of all agent event names.
+ */
+export type AgentEventName = (typeof AGENT_EVENT_NAMES)[number];
+/**
+ * Union type of all session event names.
+ */
+export type SessionEventName = (typeof SESSION_EVENT_NAMES)[number];
+/**
+ * Union type of all event names.
+ */
+export type EventName = (typeof EVENT_NAMES)[number];
+/**
+ * Token usage information for LLM responses.
+ */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+/**
+ * Log level for structured logging events.
+ */
+export type LogLevel = 'debug' | 'error' | 'info' | 'warn';
+/**
+ * UI event type for user interface actions.
+ */
+export type UIEventType = 'banner' | 'help' | 'prompt' | 'response' | 'separator' | 'shutdown';
+/**
+ * Tool error type classification.
+ * Used for structured error reporting in tool execution.
+ */
+export type ToolErrorType = 'CANCELLED' | 'CONFIRMATION_REJECTED' | 'EXECUTION_FAILED' | 'INTERNAL_ERROR' | 'INVALID_PARAM_TYPE' | 'INVALID_PARAMS' | 'MISSING_REQUIRED_PARAM' | 'PARAM_VALIDATION_FAILED' | 'PERMISSION_DENIED' | 'PROVIDER_ERROR' | 'TIMEOUT' | 'TOOL_DISABLED' | 'TOOL_NOT_FOUND';
+/**
+ * Termination reason type for agent execution.
+ * Matches TerminationReason enum values as strings.
+ */
+export type AgentTerminationReason = 'ABORTED' | 'ERROR' | 'GOAL' | 'MAX_TURNS' | 'PROTOCOL_VIOLATION' | 'TIMEOUT';
+/**
+ * Agent execution state type.
+ * Matches AgentState enum values as strings.
+ */
+export type AgentExecutionStateType = 'ABORTED' | 'COMPLETE' | 'ERROR' | 'EXECUTING' | 'IDLE' | 'TOOL_CALLING';
+/**
+ * Agent-level event payloads.
+ * All agent events include sessionId for tracking which session triggered the event.
+ */
+export interface AgentEventMap {
+    /**
+     * Emitted when a conversation is reset.
+     * @property {string} sessionId - ID of the session being reset
+     */
+    'cipher:conversationReset': {
+        sessionId: string;
+    };
+    /**
+     * Emitted when agent execution starts.
+     * @property {number} maxIterations - Maximum iterations allowed
+     * @property {number} [maxTimeMs] - Maximum execution time in milliseconds
+     * @property {string} sessionId - ID of the session
+     * @property {Date} startTime - When execution started
+     */
+    'cipher:executionStarted': {
+        maxIterations: number;
+        maxTimeMs?: number;
+        sessionId: string;
+        startTime: Date;
+    };
+    /**
+     * Emitted when agent execution terminates.
+     * @property {number} [durationMs] - Execution duration in milliseconds
+     * @property {Date} endTime - When execution ended
+     * @property {Error} [error] - Error if terminated due to error
+     * @property {AgentTerminationReason} reason - Why execution terminated
+     * @property {string} sessionId - ID of the session
+     * @property {number} toolCallsExecuted - Number of tool calls made
+     * @property {number} turnCount - Number of turns completed
+     */
+    'cipher:executionTerminated': {
+        durationMs?: number;
+        endTime: Date;
+        error?: Error;
+        reason: AgentTerminationReason;
+        sessionId: string;
+        toolCallsExecuted: number;
+        turnCount: number;
+    };
+    /**
+     * Emitted for structured logging from any layer.
+     * @property {Record<string, unknown>} [context] - Optional structured context data
+     * @property {LogLevel} level - Log level (debug, info, warn, error)
+     * @property {string} message - Human-readable log message
+     * @property {string} [sessionId] - Optional session ID (if log is session-specific)
+     * @property {string} [source] - Optional source identifier (e.g., class name, module)
+     */
+    'cipher:log': {
+        context?: Record<string, unknown>;
+        level: LogLevel;
+        message: string;
+        sessionId?: string;
+        source?: string;
+    };
+    /**
+     * Emitted when agent state changes.
+     * @property {string} field - Name of the state field that changed
+     * @property {unknown} newValue - New value
+     * @property {unknown} [oldValue] - Previous value (if applicable)
+     * @property {string} [sessionId] - ID of the session (optional for global state changes)
+     */
+    'cipher:stateChanged': {
+        field: string;
+        newValue: unknown;
+        oldValue?: unknown;
+        sessionId?: string;
+    };
+    /**
+     * Emitted when agent state is completely reset.
+     * @property {string} [sessionId] - ID of the session (optional for global state resets)
+     */
+    'cipher:stateReset': {
+        sessionId?: string;
+    };
+    /**
+     * Emitted for UI-related actions (banners, prompts, responses, etc.).
+     * This separates UI concerns from business logic logging.
+     * @property {Record<string, unknown>} [context] - Optional context (e.g., colors, formatting data)
+     * @property {string} [message] - Optional human-readable message
+     * @property {string} [sessionId] - Optional session ID
+     * @property {UIEventType} type - Type of UI event
+     */
+    'cipher:ui': {
+        context?: Record<string, unknown>;
+        message?: string;
+        sessionId?: string;
+        type: UIEventType;
+    };
+    /**
+     * Session events forwarded to agent bus with sessionId added.
+     */
+    /**
+     * Emitted when a chunk of content is received (streaming).
+     * @property {string} content - Content of the chunk
+     * @property {boolean} [isComplete] - Whether this is the final chunk
+     * @property {string} sessionId - ID of the session
+     * @property {'reasoning' | 'text'} type - Type of chunk (text or reasoning)
+     */
+    'llmservice:chunk': {
+        content: string;
+        isComplete?: boolean;
+        sessionId: string;
+        type: 'reasoning' | 'text';
+    };
+    /**
+     * 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
+     */
+    'llmservice:error': {
+        code?: string;
+        error: string;
+        sessionId: 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} toolName - Name of the tool that produced the output
+     */
+    'llmservice:outputTruncated': {
+        originalLength: number;
+        savedToFile: string;
+        sessionId: string;
+        toolName: string;
+    };
+    /**
+     * Emitted when LLM completes a response.
+     * @property {string} content - Full response content
+     * @property {string} [model] - Model identifier
+     * @property {boolean} [partial] - Whether this is a partial response (e.g., max iterations reached)
+     * @property {string} [provider] - LLM provider name
+     * @property {string} [reasoning] - Internal reasoning (if available)
+     * @property {string} sessionId - ID of the session
+     * @property {TokenUsage} [tokenUsage] - Token usage statistics
+     */
+    'llmservice:response': {
+        content: string;
+        model?: string;
+        partial?: boolean;
+        provider?: string;
+        reasoning?: string;
+        sessionId: string;
+        tokenUsage?: TokenUsage;
+    };
+    /**
+     * Emitted when LLM service starts thinking/processing.
+     * @property {string} sessionId - ID of the session
+     */
+    'llmservice:thinking': {
+        sessionId: 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} subject - Brief thought subject
+     */
+    'llmservice:thought': {
+        description: string;
+        sessionId: string;
+        subject: string;
+    };
+    /**
+     * Emitted when the todo list is updated via write_todos tool.
+     * @property {string} sessionId - ID of the session
+     * @property {Array<{content: string, status: string, activeForm: string}>} todos - Updated todo list
+     */
+    'llmservice:todoUpdated': {
+        sessionId: string;
+        todos: Array<{
+            activeForm: string;
+            content: string;
+            status: 'cancelled' | 'completed' | 'in_progress' | 'pending';
+        }>;
+    };
+    /**
+     * Emitted when LLM requests a tool call.
+     * @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} toolName - Name of the tool to execute
+     */
+    'llmservice:toolCall': {
+        args: Record<string, unknown>;
+        callId?: string;
+        sessionId: string;
+        toolName: string;
+    };
+    /**
+     * Emitted when a tool execution completes.
+     * @property {string} [callId] - Tool call identifier
+     * @property {string} [error] - Error message (if failed)
+     * @property {ToolErrorType} [errorType] - Classified error type (if failed)
+     * @property {Record<string, unknown>} [metadata] - Execution metadata (duration, tokens, etc.)
+     * @property {unknown} [result] - Tool execution result
+     * @property {string} sessionId - ID of the session
+     * @property {boolean} success - Whether execution succeeded
+     * @property {string} toolName - Name of the executed tool
+     */
+    'llmservice:toolResult': {
+        callId?: string;
+        error?: string;
+        errorType?: ToolErrorType;
+        metadata?: Record<string, unknown>;
+        result?: unknown;
+        sessionId: string;
+        success: boolean;
+        toolName: string;
+    };
+    /**
+     * Emitted when LLM receives unsupported input.
+     * @property {string} reason - Reason why input is unsupported
+     * @property {string} sessionId - ID of the session
+     */
+    'llmservice:unsupportedInput': {
+        reason: string;
+        sessionId: string;
+    };
+    /**
+     * Emitted when LLM service encounters a warning (e.g., max iterations reached).
+     * @property {string} message - Warning message
+     * @property {string} [model] - Model identifier
+     * @property {string} [provider] - LLM provider name
+     * @property {string} sessionId - ID of the session
+     */
+    'llmservice:warning': {
+        message: string;
+        model?: string;
+        provider?: string;
+        sessionId: string;
+    };
+}
+/**
+ * Session-level event payloads.
+ * These are scoped to a specific session and do not include sessionId.
+ */
+export interface SessionEventMap {
+    /**
+     * Emitted when a chunk of content is received (streaming).
+     * @property {string} content - Content of the chunk
+     * @property {boolean} [isComplete] - Whether this is the final chunk
+     * @property {'reasoning' | 'text'} type - Type of chunk (text or reasoning)
+     */
+    'llmservice:chunk': {
+        content: string;
+        isComplete?: boolean;
+        type: 'reasoning' | 'text';
+    };
+    /**
+     * Emitted when an error occurs during LLM service operation.
+     * @property {string} [code] - Error code (optional)
+     * @property {string} error - Error message
+     */
+    'llmservice:error': {
+        code?: string;
+        error: 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} toolName - Name of the tool that produced the output
+     */
+    'llmservice:outputTruncated': {
+        originalLength: number;
+        savedToFile: string;
+        toolName: string;
+    };
+    /**
+     * Emitted when LLM completes a response.
+     * @property {string} content - Full response content
+     * @property {string} [model] - Model identifier
+     * @property {boolean} [partial] - Whether this is a partial response (e.g., max iterations reached)
+     * @property {string} [provider] - LLM provider name
+     * @property {string} [reasoning] - Internal reasoning (if available)
+     * @property {TokenUsage} [tokenUsage] - Token usage statistics
+     */
+    'llmservice:response': {
+        content: string;
+        model?: string;
+        partial?: boolean;
+        provider?: string;
+        reasoning?: string;
+        tokenUsage?: TokenUsage;
+    };
+    /**
+     * Emitted when LLM service starts thinking/processing.
+     */
+    'llmservice:thinking': void;
+    /**
+     * Emitted when LLM generates a thought (Gemini models only).
+     * @property {string} description - Detailed thought description
+     * @property {string} subject - Brief thought subject
+     */
+    'llmservice:thought': {
+        description: string;
+        subject: string;
+    };
+    /**
+     * Emitted when LLM requests a tool call.
+     * @property {Record<string, unknown>} args - Arguments for the tool
+     * @property {string} [callId] - Unique identifier for this tool call
+     * @property {string} toolName - Name of the tool to execute
+     */
+    'llmservice:toolCall': {
+        args: Record<string, unknown>;
+        callId?: string;
+        toolName: string;
+    };
+    /**
+     * Emitted when a tool execution completes.
+     * @property {string} [callId] - Tool call identifier
+     * @property {string} [error] - Error message (if failed)
+     * @property {ToolErrorType} [errorType] - Classified error type (if failed)
+     * @property {Record<string, unknown>} [metadata] - Execution metadata (duration, tokens, etc.)
+     * @property {unknown} [result] - Tool execution result
+     * @property {boolean} success - Whether execution succeeded
+     * @property {string} toolName - Name of the executed tool
+     */
+    'llmservice:toolResult': {
+        callId?: string;
+        error?: string;
+        errorType?: ToolErrorType;
+        metadata?: Record<string, unknown>;
+        result?: unknown;
+        success: boolean;
+        toolName: string;
+    };
+    /**
+     * Emitted when LLM receives unsupported input.
+     * @property {string} reason - Reason why input is unsupported
+     */
+    'llmservice:unsupportedInput': {
+        reason: string;
+    };
+    /**
+     * Emitted when LLM service encounters a warning (e.g., max iterations reached).
+     * @property {string} message - Warning message
+     * @property {string} [model] - Model identifier
+     * @property {string} [provider] - LLM provider name
+     */
+    'llmservice:warning': {
+        message: string;
+        model?: string;
+        provider?: string;
+    };
+}
+/**
+ * Prevent unused variable warnings for compile-time checks.
+ */
+export declare const __compileTimeChecks: {
+    _checkAgentEventNames: true;
+    _checkSessionEventNames: true;
+};

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

@@ -0,0 +1,42 @@
+/**
+ * Agent-level event names for CipherAgent.
+ * These events are emitted at the agent level and include sessionId in payloads.
+ */
+export const AGENT_EVENT_NAMES = [
+    'cipher:conversationReset',
+    'cipher:executionStarted',
+    'cipher:executionTerminated',
+    'cipher:log',
+    'cipher:stateChanged',
+    'cipher:stateReset',
+    'cipher:ui',
+];
+/**
+ * Session-level event names for LLM service operations.
+ * These events are emitted at the session level and do not include sessionId in payloads.
+ */
+export const SESSION_EVENT_NAMES = [
+    'llmservice:chunk',
+    'llmservice:error',
+    'llmservice:outputTruncated',
+    'llmservice:response',
+    'llmservice:thinking',
+    'llmservice:thought',
+    'llmservice:toolCall',
+    'llmservice:toolResult',
+    'llmservice:unsupportedInput',
+    'llmservice:warning',
+];
+/**
+ * All event names (union of agent and session events).
+ */
+export const EVENT_NAMES = [...AGENT_EVENT_NAMES, ...SESSION_EVENT_NAMES];
+const _checkAgentEventNames = true;
+const _checkSessionEventNames = true;
+/**
+ * Prevent unused variable warnings for compile-time checks.
+ */
+export const __compileTimeChecks = {
+    _checkAgentEventNames,
+    _checkSessionEventNames,
+};

package/dist/core/domain/cipher/blob/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Blob metadata type
+ * Contains information about a stored blob
+ */
+export type BlobMetadata = {
+    /**
+     * MIME type of the blob content
+     * @example 'image/png', 'application/pdf', 'text/plain'
+     */
+    contentType?: string;
+    /**
+     * Timestamp when the blob was created (Unix timestamp in milliseconds)
+     */
+    createdAt: number;
+    /**
+     * Original filename if the blob was created from a file
+     * @example 'screenshot.png', 'document.pdf'
+     */
+    originalName?: string;
+    /**
+     * Size of the blob in bytes
+     */
+    size: number;
+    /**
+     * Custom metadata tags for categorization and filtering
+     * @example { category: 'screenshot', project: 'myapp' }
+     */
+    tags?: Record<string, string>;
+    /**
+     * Timestamp when the blob was last updated (Unix timestamp in milliseconds)
+     */
+    updatedAt: number;
+};
+/**
+ * Stored blob with content and metadata
+ * Represents a complete blob retrieved from storage
+ */
+export type StoredBlob = {
+    /**
+     * Binary content of the blob
+     */
+    content: Buffer;
+    /**
+     * Unique identifier for the blob
+     * Must be alphanumeric with hyphens and underscores only
+     */
+    key: string;
+    /**
+     * Associated metadata
+     */
+    metadata: BlobMetadata;
+};
+/**
+ * Simple logger interface for blob storage operations
+ */
+export interface BlobLogger {
+    error: (message: string) => void;
+    info: (message: string) => void;
+}
+/**
+ * Configuration options for blob storage
+ * SQLite is always used as the backend
+ */
+export type BlobStorageConfig = {
+    /**
+     * Use in-memory storage (useful for testing)
+     * When true, no file is created - data lives only in memory
+     * @default false
+     */
+    inMemory?: boolean;
+    /**
+     * Logger for blob storage operations
+     * If not provided, console will be used as fallback
+     */
+    logger?: BlobLogger;
+    /**
+     * Maximum size for a single blob in bytes
+     * @default 104857600 (100MB)
+     */
+    maxBlobSize?: number;
+    /**
+     * Maximum total size for all blobs in bytes
+     * @default 1073741824 (1GB)
+     */
+    maxTotalSize?: number;
+    /**
+     * Base directory where blobs/database will be stored
+     * @default '.brv/blobs'
+     */
+    storageDir?: string;
+};
+/**
+ * Statistics about blob storage
+ */
+export type BlobStats = {
+    /**
+     * Timestamp when stats were last calculated (Unix timestamp in milliseconds)
+     */
+    lastUpdated: number;
+    /**
+     * Total number of blobs stored
+     */
+    totalBlobs: number;
+    /**
+     * Total size of all blobs in bytes
+     */
+    totalSize: number;
+};

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

@@ -0,0 +1,36 @@
+/**
+ * Error codes for blob storage operations
+ */
+export declare enum BlobErrorCode {
+    BLOB_ALREADY_EXISTS = "BLOB_ALREADY_EXISTS",
+    BLOB_DELETE_ERROR = "BLOB_DELETE_ERROR",
+    BLOB_INITIALIZATION_ERROR = "BLOB_INITIALIZATION_ERROR",
+    BLOB_INVALID_CONTENT = "BLOB_INVALID_CONTENT",
+    BLOB_INVALID_KEY = "BLOB_INVALID_KEY",
+    BLOB_NOT_FOUND = "BLOB_NOT_FOUND",
+    BLOB_NOT_INITIALIZED = "BLOB_NOT_INITIALIZED",
+    BLOB_RETRIEVAL_ERROR = "BLOB_RETRIEVAL_ERROR",
+    BLOB_STORAGE_ERROR = "BLOB_STORAGE_ERROR",
+    BLOB_TOO_LARGE = "BLOB_TOO_LARGE",
+    BLOB_TOTAL_SIZE_EXCEEDED = "BLOB_TOTAL_SIZE_EXCEEDED"
+}
+/**
+ * Blob error class with factory methods for creating specific error instances
+ */
+export declare class BlobError extends Error {
+    readonly code: BlobErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    readonly suggestion?: string | undefined;
+    constructor(message: string, code: BlobErrorCode, details?: Record<string, unknown> | undefined, suggestion?: string | undefined);
+    static alreadyExists(key: string): BlobError;
+    static deleteError(message: string, cause?: Error): BlobError;
+    static initializationError(message: string, cause?: Error): BlobError;
+    static invalidContent(reason: string): BlobError;
+    static invalidKey(key: string, reason: string): BlobError;
+    static notFound(key: string): BlobError;
+    static notInitialized(): BlobError;
+    static retrievalError(message: string, cause?: Error): BlobError;
+    static storageError(message: string, cause?: Error): BlobError;
+    static tooLarge(size: number, maxSize: number): BlobError;
+    static totalSizeExceeded(currentSize: number, blobSize: number, maxTotalSize: number): BlobError;
+}

package/dist/core/domain/cipher/errors/blob-error.js

@@ -0,0 +1,68 @@
+/**
+ * Error codes for blob storage operations
+ */
+export var BlobErrorCode;
+(function (BlobErrorCode) {
+    BlobErrorCode["BLOB_ALREADY_EXISTS"] = "BLOB_ALREADY_EXISTS";
+    BlobErrorCode["BLOB_DELETE_ERROR"] = "BLOB_DELETE_ERROR";
+    BlobErrorCode["BLOB_INITIALIZATION_ERROR"] = "BLOB_INITIALIZATION_ERROR";
+    BlobErrorCode["BLOB_INVALID_CONTENT"] = "BLOB_INVALID_CONTENT";
+    BlobErrorCode["BLOB_INVALID_KEY"] = "BLOB_INVALID_KEY";
+    // Blob errors
+    BlobErrorCode["BLOB_NOT_FOUND"] = "BLOB_NOT_FOUND";
+    // State errors
+    BlobErrorCode["BLOB_NOT_INITIALIZED"] = "BLOB_NOT_INITIALIZED";
+    BlobErrorCode["BLOB_RETRIEVAL_ERROR"] = "BLOB_RETRIEVAL_ERROR";
+    // Storage operation errors
+    BlobErrorCode["BLOB_STORAGE_ERROR"] = "BLOB_STORAGE_ERROR";
+    BlobErrorCode["BLOB_TOO_LARGE"] = "BLOB_TOO_LARGE";
+    BlobErrorCode["BLOB_TOTAL_SIZE_EXCEEDED"] = "BLOB_TOTAL_SIZE_EXCEEDED";
+})(BlobErrorCode || (BlobErrorCode = {}));
+/**
+ * Blob error class with factory methods for creating specific error instances
+ */
+export class BlobError extends Error {
+    code;
+    details;
+    suggestion;
+    constructor(message, code, details, suggestion) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.suggestion = suggestion;
+        this.name = 'BlobError';
+    }
+    static alreadyExists(key) {
+        return new BlobError(`Blob already exists: ${key}`, BlobErrorCode.BLOB_ALREADY_EXISTS, { key }, 'Use a different key or delete the existing blob first.');
+    }
+    static deleteError(message, cause) {
+        return new BlobError(`Blob deletion error: ${message}`, BlobErrorCode.BLOB_DELETE_ERROR, { cause }, 'Check if the blob file exists and you have write permissions.');
+    }
+    static initializationError(message, cause) {
+        return new BlobError(`Blob storage initialization error: ${message}`, BlobErrorCode.BLOB_INITIALIZATION_ERROR, { cause }, 'Check if the storage directory can be created and you have necessary permissions.');
+    }
+    static invalidContent(reason) {
+        return new BlobError(`Invalid blob content: ${reason}`, BlobErrorCode.BLOB_INVALID_CONTENT, { reason }, 'Provide valid Buffer or string content.');
+    }
+    static invalidKey(key, reason) {
+        return new BlobError(`Invalid blob key: ${key} - ${reason}`, BlobErrorCode.BLOB_INVALID_KEY, { key, reason }, 'Use only alphanumeric characters, hyphens, and underscores in blob keys.');
+    }
+    static notFound(key) {
+        return new BlobError(`Blob not found: ${key}`, BlobErrorCode.BLOB_NOT_FOUND, { key }, 'Check if the blob key is correct or use list() to find available blobs.');
+    }
+    static notInitialized() {
+        return new BlobError('Blob storage not initialized', BlobErrorCode.BLOB_NOT_INITIALIZED, undefined, 'Call initialize() before performing any blob operations.');
+    }
+    static retrievalError(message, cause) {
+        return new BlobError(`Blob retrieval error: ${message}`, BlobErrorCode.BLOB_RETRIEVAL_ERROR, { cause }, 'Check if the blob storage is accessible and readable.');
+    }
+    static storageError(message, cause) {
+        return new BlobError(`Blob storage error: ${message}`, BlobErrorCode.BLOB_STORAGE_ERROR, { cause }, 'Check if the storage directory exists and you have write permissions.');
+    }
+    static tooLarge(size, maxSize) {
+        return new BlobError(`Blob too large: ${size} bytes exceeds maximum ${maxSize} bytes`, BlobErrorCode.BLOB_TOO_LARGE, { maxSize, size }, `Reduce the blob size to ${maxSize} bytes or less, or increase the maxBlobSize configuration.`);
+    }
+    static totalSizeExceeded(currentSize, blobSize, maxTotalSize) {
+        return new BlobError(`Total storage size exceeded: ${currentSize + blobSize} bytes would exceed maximum ${maxTotalSize} bytes`, BlobErrorCode.BLOB_TOTAL_SIZE_EXCEEDED, { blobSize, currentSize, maxTotalSize, wouldBe: currentSize + blobSize }, 'Delete some blobs to free up space or increase the maxTotalSize configuration.');
+    }
+}