byterover-cli 1.6.0 → 1.7.0

package/dist/agent/infra/agent/service-initializer.js

@@ -0,0 +1,298 @@
+/**
+ * Service Initializer: Centralized Wiring for Cipher Agent Services
+ *
+ * This module is responsible for initializing and wiring together all core agent services.
+ * It provides a single entry point for constructing the service graph.
+ *
+ * Following DextoAgent pattern:
+ * - Config file is source of truth (ValidatedAgentConfig)
+ * - Centralized function (not factory class) for service creation
+ * - Explicit dependency order with numbered steps
+ * - Event bus passed in as parameter (created in agent constructor)
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createBlobStorage } from '../blob/blob-storage-factory.js';
+import { EnvironmentContextBuilder } from '../environment/environment-context-builder.js';
+import { SessionEventBus } from '../events/event-emitter.js';
+import { FileSystemService } from '../file-system/file-system-service.js';
+import { ByteRoverLlmHttpService } from '../http/internal-llm-http-service.js';
+import { CompactionService } from '../llm/context/compaction/compaction-service.js';
+import { ByteRoverContentGenerator, LoggingContentGenerator, RetryableContentGenerator } from '../llm/generators/index.js';
+import { ByteRoverLLMService } from '../llm/internal-llm-service.js';
+import { OpenRouterLLMService } from '../llm/openrouter-llm-service.js';
+import { DEFAULT_RETRY_POLICY } from '../llm/retry/retry-policy.js';
+import { GeminiTokenizer } from '../llm/tokenizers/gemini-tokenizer.js';
+import { EventBasedLogger } from '../logger/event-based-logger.js';
+import { MemoryManager } from '../memory/memory-manager.js';
+import { ProcessService } from '../process/process-service.js';
+import { SandboxService } from '../sandbox/sandbox-service.js';
+import { BlobHistoryStorage } from '../storage/blob-history-storage.js';
+import { DualFormatHistoryStorage } from '../storage/dual-format-history-storage.js';
+import { GranularHistoryStorage } from '../storage/granular-history-storage.js';
+import { MessageStorageService } from '../storage/message-storage-service.js';
+import { SqliteKeyStorage } from '../storage/sqlite-key-storage.js';
+import { ContextTreeStructureContributor } from '../system-prompt/contributors/context-tree-structure-contributor.js';
+import { SystemPromptManager } from '../system-prompt/system-prompt-manager.js';
+import { CoreToolScheduler } from '../tools/core-tool-scheduler.js';
+import { DEFAULT_POLICY_RULES } from '../tools/default-policy-rules.js';
+import { PolicyEngine } from '../tools/policy-engine.js';
+import { ToolDescriptionLoader } from '../tools/tool-description-loader.js';
+import { ToolManager } from '../tools/tool-manager.js';
+import { ToolProvider } from '../tools/tool-provider.js';
+/**
+ * Creates shared services for CipherAgent.
+ * These services are singletons shared across all sessions.
+ *
+ * Initialization order follows DextoAgent pattern (explicit numbered steps):
+ * 1. Logger (uses provided event bus)
+ * 2. File system service (no dependencies)
+ * 3. Process service (no dependencies)
+ * 4. Blob storage (no dependencies)
+ * 5. Memory system (depends on BlobStorage, Logger)
+ * 6. System prompt manager (no dependencies)
+ * 7. Tool provider (depends on FileSystemService, ProcessService, MemoryManager)
+ * 8. Policy engine (no dependencies)
+ * 9. Tool scheduler (depends on ToolProvider, PolicyEngine)
+ * 10. Tool manager (depends on ToolProvider, ToolScheduler)
+ * 11. History storage (depends on BlobStorage)
+ * 12. Return all services
+ *
+ * @param config - Validated agent configuration (Zod-validated)
+ * @param agentEventBus - Pre-created event bus from agent constructor (DextoAgent pattern)
+ * @returns Initialized shared services
+ */
+export async function createCipherAgentServices(config, agentEventBus) {
+    // 1. Logger (uses provided event bus - DextoAgent pattern)
+    const logger = new EventBasedLogger(agentEventBus, 'CipherAgent');
+    // 2. File system service (no dependencies)
+    const fileSystemService = new FileSystemService(config.fileSystem);
+    await fileSystemService.initialize();
+    // 3. Process service (no dependencies)
+    const workingDirectory = config.fileSystem?.workingDirectory ?? process.cwd();
+    const processService = new ProcessService({
+        allowedCommands: [],
+        blockedCommands: [],
+        environment: {},
+        maxConcurrentProcesses: 5,
+        maxOutputBuffer: 1_048_576, // 1MB (1024 * 1024)
+        maxTimeout: 600_000, // 10 minutes
+        securityLevel: 'permissive', // Permissive mode: relies on working directory confinement
+        workingDirectory,
+    });
+    await processService.initialize();
+    // 4. Blob storage (no dependencies)
+    const blobStorage = createBlobStorage(config.blobStorage ?? {
+        maxBlobSize: 100 * 1024 * 1024, // 100MB
+        maxTotalSize: 1024 * 1024 * 1024, // 1GB
+        storageDir: join(workingDirectory, '.brv', 'blobs'),
+    });
+    await blobStorage.initialize();
+    // 5. Memory system (depends on BlobStorage, Logger)
+    const memoryLogger = logger.withSource('MemoryManager');
+    const memoryManager = new MemoryManager(blobStorage, memoryLogger);
+    // 5b. Sandbox service for code execution (no dependencies)
+    const sandboxService = new SandboxService();
+    // 5c. Build environment context for sandbox injection
+    const environmentBuilder = new EnvironmentContextBuilder();
+    const environmentContext = await environmentBuilder.build({
+        includeBrvStructure: false, // Not needed for sandbox - only basic env info
+        includeFileTree: false, // Not needed for sandbox - only basic env info
+        workingDirectory,
+    });
+    // 6. System prompt manager - SHARED across sessions
+    // Calculate path to prompts directory relative to this file's location
+    // This file is at dist/agent/core/service-initializer.js
+    // Resources are at dist/resources/prompts/
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const promptsBasePath = join(currentDir, '../../resources/prompts');
+    const systemPromptManager = new SystemPromptManager({
+        basePath: promptsBasePath,
+        validateConfig: true,
+    });
+    // Register default contributors
+    systemPromptManager.registerContributors([
+        { enabled: true, filepath: 'system-prompt.yml', id: 'base', priority: 0, type: 'file' },
+        { enabled: true, id: 'env', priority: 10, type: 'environment' },
+        { enabled: true, id: 'memories', priority: 20, type: 'memory' },
+        { enabled: true, id: 'datetime', priority: 30, type: 'dateTime' },
+    ]);
+    // Register context tree structure contributor for query/curate commands
+    // This injects the .brv/context-tree structure into the system prompt,
+    // giving agents immediate awareness of available curated knowledge.
+    // Priority 15 ensures it appears after environment but before memories.
+    const contextTreeContributor = new ContextTreeStructureContributor('contextTree', 15, {
+        workingDirectory,
+    });
+    systemPromptManager.registerContributor(contextTreeContributor);
+    // 7. Tool provider (depends on FileSystemService, ProcessService, MemoryManager, SystemPromptManager)
+    const verbose = config.llm.verbose ?? false;
+    const descriptionLoader = new ToolDescriptionLoader();
+    const toolProvider = new ToolProvider({
+        environmentContext,
+        fileSystemService,
+        getToolProvider: () => toolProvider,
+        memoryManager,
+        processService,
+        sandboxService,
+    }, systemPromptManager, descriptionLoader);
+    await toolProvider.initialize();
+    // 8. Policy engine with default rules for autonomous execution
+    const policyEngine = new PolicyEngine({ defaultDecision: 'ALLOW' });
+    policyEngine.addRules(DEFAULT_POLICY_RULES);
+    // 9. Tool scheduler (orchestrates policy check → execution)
+    const toolScheduler = new CoreToolScheduler(toolProvider, policyEngine, undefined, {
+        verbose,
+    });
+    // 10. Tool manager (with scheduler for policy-based execution)
+    const toolManager = new ToolManager(toolProvider, toolScheduler);
+    await toolManager.initialize();
+    // 11. History storage (depends on BlobStorage) - SHARED across sessions
+    let historyStorage;
+    let compactionService;
+    let messageStorageService;
+    if (config.useGranularStorage) {
+        // Create granular storage infrastructure
+        const keyStorage = new SqliteKeyStorage({
+            storageDir: join(workingDirectory, '.brv', 'blobs'),
+        });
+        await keyStorage.initialize();
+        const messageStorage = new MessageStorageService(keyStorage);
+        messageStorageService = messageStorage;
+        const granularStorage = new GranularHistoryStorage(messageStorage);
+        const blobHistoryStorage = new BlobHistoryStorage(blobStorage);
+        // DualFormatHistoryStorage routes between formats:
+        // - New sessions → GranularHistoryStorage
+        // - Existing sessions → BlobHistoryStorage (no migration)
+        historyStorage = new DualFormatHistoryStorage(blobHistoryStorage, granularStorage);
+        // Create CompactionService for context overflow management
+        const tokenizer = new GeminiTokenizer(config.model ?? 'gemini-3-flash-preview');
+        compactionService = new CompactionService(messageStorage, tokenizer, {
+            overflowThreshold: 0.85, // 85% triggers compaction check
+            protectedTurns: 2, // Protect first 2 user turns from pruning
+            pruneKeepTokens: 40_000, // Keep 40k tokens in tool outputs
+            pruneMinimumTokens: 20_000, // Only prune if 20k+ tokens can be saved
+        });
+        logger.info('Granular history storage enabled for new sessions');
+    }
+    else {
+        // Default: use blob storage for all sessions
+        historyStorage = new BlobHistoryStorage(blobStorage);
+    }
+    // 12. Log successful initialization
+    logger.info('CipherAgent services initialized successfully', {
+        model: config.model,
+        verbose: config.llm.verbose,
+        workingDirectory,
+    });
+    return {
+        agentEventBus,
+        blobStorage,
+        compactionService,
+        fileSystemService,
+        historyStorage,
+        memoryManager,
+        messageStorageService,
+        policyEngine,
+        processService,
+        sandboxService,
+        systemPromptManager,
+        toolManager,
+        toolProvider,
+        toolScheduler,
+    };
+}
+/**
+ * Creates session-specific services for a ChatSession.
+ * Generator composition order (innermost to outermost):
+ * 1. Base generator (ByteRoverContentGenerator or OpenRouterContentGenerator)
+ * 2. RetryableContentGenerator - handles transient errors with backoff
+ * 3. LoggingContentGenerator - debug logging (if verbose enabled)
+ *
+ * @param sessionId - Unique session identifier
+ * @param sharedServices - Shared services from agent
+ * @param httpConfig - HTTP configuration
+ * @param llmConfig - LLM service configuration
+ * @returns Initialized session services
+ */
+export function createSessionServices(sessionId, sharedServices, httpConfig, llmConfig) {
+    // 1. Create session-specific event bus
+    const sessionEventBus = new SessionEventBus();
+    // 2. Create session-scoped logger
+    const sessionLogger = new EventBasedLogger(sharedServices.agentEventBus, 'LLMService', sessionId);
+    // 3. Create LLM service based on configuration
+    // Priority: OpenRouter > ByteRover HTTP
+    let llmService;
+    if (llmConfig.openRouterApiKey) {
+        // Use OpenRouter service when OpenRouter API key is provided
+        llmService = new OpenRouterLLMService(sessionId, {
+            apiKey: llmConfig.openRouterApiKey,
+            httpReferer: llmConfig.httpReferer,
+            maxIterations: llmConfig.maxIterations ?? 50,
+            maxTokens: llmConfig.maxTokens ?? 8192,
+            model: llmConfig.model ?? 'google/gemini-3-flash-preview',
+            siteName: llmConfig.siteName,
+            temperature: llmConfig.temperature ?? 0.7,
+            verbose: llmConfig.verbose ?? false,
+        }, {
+            logger: sessionLogger,
+            memoryManager: sharedServices.memoryManager, // SHARED
+            sessionEventBus,
+            systemPromptManager: sharedServices.systemPromptManager, // SHARED
+            toolManager: sharedServices.toolManager, // SHARED
+        });
+    }
+    else {
+        // Use HTTP backend service (default) with generator pattern
+        // Step 1: Create HTTP service
+        const httpService = new ByteRoverLlmHttpService({
+            apiBaseUrl: httpConfig.apiBaseUrl,
+            projectId: httpConfig.projectId,
+            region: httpConfig.region,
+            sessionKey: httpConfig.sessionKey,
+            spaceId: httpConfig.spaceId,
+            teamId: httpConfig.teamId,
+            timeout: httpConfig.timeout,
+        });
+        // Step 2: Create base content generator
+        let generator = new ByteRoverContentGenerator(httpService, {
+            maxTokens: llmConfig.maxTokens ?? 8192,
+            model: llmConfig.model ?? 'gemini-3-flash-preview',
+            temperature: llmConfig.temperature ?? 0.7,
+        });
+        // Step 3: Wrap with retry decorator
+        generator = new RetryableContentGenerator(generator, {
+            eventBus: sessionEventBus,
+            policy: DEFAULT_RETRY_POLICY,
+        });
+        // Step 4: Wrap with logging decorator (always, for spinner events)
+        generator = new LoggingContentGenerator(generator, sessionEventBus, {
+            logChunks: llmConfig.verbose,
+            logRequests: llmConfig.verbose,
+            logResponses: llmConfig.verbose,
+            verbose: llmConfig.verbose,
+        });
+        // Step 5: Create LLM service with composed generator
+        llmService = new ByteRoverLLMService(sessionId, generator, {
+            maxIterations: llmConfig.maxIterations ?? 50,
+            maxTokens: llmConfig.maxTokens ?? 8192,
+            model: llmConfig.model ?? 'gemini-3-flash-preview',
+            temperature: llmConfig.temperature ?? 0.7,
+            verbose: llmConfig.verbose ?? false,
+        }, {
+            compactionService: sharedServices.compactionService, // SHARED - for context overflow management
+            historyStorage: sharedServices.historyStorage, // SHARED
+            logger: sessionLogger,
+            memoryManager: sharedServices.memoryManager, // SHARED
+            sessionEventBus,
+            systemPromptManager: sharedServices.systemPromptManager, // SHARED
+            toolManager: sharedServices.toolManager, // SHARED
+        });
+    }
+    // Event forwarding is handled by ChatSession.setupEventForwarding()
+    // to ensure proper cleanup when sessions are disposed
+    return {
+        llmService,
+        sessionEventBus,
+    };
+}

package/dist/agent/infra/agent/types.d.ts

@@ -0,0 +1,35 @@
+import type { AgentExecutionState } from '../../core/interfaces/i-cipher-agent.js';
+import type { AgentEventBus } from '../events/event-emitter.js';
+/**
+ * Termination reason type for agent execution.
+ */
+export type TerminationReason = 'ABORTED' | 'ERROR' | 'GOAL' | 'MAX_TURNS' | 'PROTOCOL_VIOLATION' | 'TIMEOUT';
+/**
+ * Agent execution context with enhanced state tracking.
+ */
+export interface AgentExecutionContext {
+    currentIteration: number;
+    durationMs?: number;
+    endTime?: Date;
+    executionState: AgentExecutionState;
+    startTime?: Date;
+    terminationReason?: TerminationReason;
+    toolCallsExecuted: number;
+}
+/**
+ * Agent event subscriber interface.
+ * Objects implementing this can be registered for event subscription.
+ * Follows DextoAgent's AgentEventSubscriber pattern.
+ */
+export interface AgentEventSubscriber {
+    /**
+     * Subscribe to events on the agent event bus.
+     * Called when the agent starts and after restart.
+     */
+    subscribe(eventBus: AgentEventBus): void;
+    /**
+     * Optional cleanup method called when unsubscribing.
+     */
+    unsubscribe?(): void;
+}
+export type { AgentConfig, BlobStorageConfig, FileSystemConfig, LLMConfig, LLMUpdates, SessionConfig, ValidatedAgentConfig, ValidatedBlobStorageConfig, ValidatedFileSystemConfig, ValidatedLLMConfig, ValidatedSessionConfig, } from './agent-schemas.js';

package/dist/agent/infra/blob/blob-reference-resolver.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Blob reference resolver for lazy media evaluation.
+ *
+ * This service resolves @blob:id references in message content to actual data
+ * at format-time (when sending to LLM), enabling lazy evaluation of large media.
+ *
+ * Key features:
+ * - Lazy expansion: Blob references only resolved when needed
+ * - MIME type filtering: Exclude unsupported media types
+ * - Placeholder generation: Replace filtered media with descriptive placeholders
+ *
+ */
+import type { IBlobStorage } from '../../core/interfaces/i-blob-storage.js';
+import type { MessagePart } from '../../core/interfaces/message-types.js';
+/**
+ * Options for blob reference expansion.
+ */
+export interface BlobResolutionOptions {
+    /**
+     * MIME patterns to allow (e.g., ["image/*", "application/pdf"]).
+     * Media not matching any pattern will be replaced with placeholders.
+     * If not specified, all media types are allowed.
+     */
+    allowedMimeTypes?: string[];
+    /**
+     * Whether to include metadata in resolved parts.
+     * Default: false
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * Result of resolving a single blob reference.
+ */
+export interface ResolvedBlobResult {
+    /** Error message if resolution failed */
+    error?: string;
+    /** Resolved message parts (may be multiple if embedded in text) */
+    parts: MessagePart[];
+    /** Whether resolution was successful */
+    success: boolean;
+}
+/**
+ * Blob reference resolver.
+ *
+ * Resolves @blob:id references to actual content at format-time.
+ */
+export declare class BlobReferenceResolver {
+    private readonly blobStorage;
+    constructor(blobStorage: IBlobStorage);
+    /**
+     * Expand blob references in message content.
+     *
+     * Processes an array of message parts and resolves any @blob:id references
+     * to actual content. Supports blob refs in:
+     * - TextPart.text (inline references)
+     * - ImagePart.image (blob ref instead of base64)
+     * - FilePart.data (blob ref instead of base64)
+     *
+     * @param content - Array of message parts to expand
+     * @param options - Resolution options
+     * @returns Array of message parts with blob refs resolved
+     */
+    expandBlobReferences(content: MessagePart[], options?: BlobResolutionOptions): Promise<MessagePart[]>;
+    /**
+     * Get all blob IDs referenced in content.
+     */
+    getBlobIds(content: MessagePart[]): string[];
+    /**
+     * Check if content contains any blob references.
+     *
+     * Useful for determining if expansion is needed before calling expandBlobReferences.
+     */
+    hasAnyBlobReferences(content: MessagePart[]): boolean;
+    /**
+     * Prefetch blobs for a set of message parts.
+     *
+     * Useful for warming the cache before expansion.
+     */
+    prefetchBlobs(content: MessagePart[]): Promise<void>;
+    /**
+     * Expand blob references embedded in text.
+     *
+     * Text like "Here is the image: @blob:abc123" will be split into
+     * multiple parts: text before, image part, text after.
+     */
+    private expandBlobsInText;
+    /**
+     * Expand a single message part.
+     */
+    private expandPart;
+    /**
+     * Resolve a blob ID to message parts.
+     */
+    private resolveBlobToParts;
+    /**
+     * Resolve a file part with blob reference.
+     */
+    private resolveFileBlob;
+    /**
+     * Resolve an image part with blob reference.
+     */
+    private resolveImageBlob;
+}
+/**
+ * Create a BlobReferenceResolver instance.
+ */
+export declare function createBlobReferenceResolver(blobStorage: IBlobStorage): BlobReferenceResolver;

package/dist/agent/infra/blob/blob-storage-factory.d.ts

@@ -0,0 +1,13 @@
+import type { BlobStorageConfig } from '../../core/domain/blob/types.js';
+import type { IBlobStorage } from '../../core/interfaces/i-blob-storage.js';
+/**
+ * Factory function to create blob storage backend.
+ * Always uses SQLite for better performance, single file, and ACID transactions.
+ *
+ * @param config - Blob storage configuration
+ * @returns SQLite blob storage implementation
+ *
+ * @example
+ * const storage = createBlobStorage({ storageDir: '.brv/blobs' });
+ */
+export declare function createBlobStorage(config?: Partial<BlobStorageConfig>): IBlobStorage;

package/dist/agent/infra/blob/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Blob storage module
+ * Provides persistent storage for binary/large data blobs using SQLite
+ */
+export type { BlobMetadata, BlobStats, BlobStorageConfig, StoredBlob } from '../../core/domain/blob/types.js';
+export { BlobError, BlobErrorCode } from '../../core/domain/errors/blob-error.js';
+export type { IBlobStorage } from '../../core/interfaces/i-blob-storage.js';
+export { createBlobStorage } from './blob-storage-factory.js';
+export * as BlobMigrations from './migrations.js';
+export { SqliteBlobStorage } from './sqlite-blob-storage.js';

package/dist/agent/infra/blob/index.js

@@ -0,0 +1,12 @@
+/**
+ * Blob storage module
+ * Provides persistent storage for binary/large data blobs using SQLite
+ */
+// Re-export errors from core
+export { BlobError, BlobErrorCode } from '../../core/domain/errors/blob-error.js';
+// Factory (always returns SQLite implementation)
+export { createBlobStorage } from './blob-storage-factory.js';
+// Migration system
+export * as BlobMigrations from './migrations.js';
+// SQLite storage implementation
+export { SqliteBlobStorage } from './sqlite-blob-storage.js';

package/dist/agent/infra/blob/migrations.d.ts

@@ -0,0 +1,63 @@
+import type Database from 'better-sqlite3';
+import type { BlobLogger } from '../../core/domain/blob/types.js';
+/**
+ * Migration definition type
+ */
+export type Migration = {
+    /**
+     * Description of what this migration does
+     */
+    description: string;
+    /**
+     * Optional backward migration (downgrade)
+     * Only needed for critical rollback scenarios
+     * @param db - SQLite database instance
+     */
+    down?(db: Database.Database): void;
+    /**
+     * Forward migration (upgrade)
+     * @param db - SQLite database instance
+     */
+    up(db: Database.Database): void;
+    /**
+     * Migration version number (must be sequential)
+     */
+    version: number;
+};
+/**
+ * SQLite Blob Storage Migrations
+ *
+ * IMPORTANT RULES:
+ * 1. NEVER modify existing migrations - always add new ones
+ * 2. Version numbers must be sequential (1, 2, 3, ...)
+ * 3. Always use IF NOT EXISTS for safety
+ * 4. Test migrations thoroughly before releasing
+ * 5. Consider adding 'down' for complex changes
+ */
+export declare const MIGRATIONS: Migration[];
+/**
+ * Get the current schema version from the database
+ */
+export declare function getCurrentVersion(db: Database.Database): number;
+/**
+ * Set the schema version in the database
+ */
+export declare function setVersion(db: Database.Database, version: number): void;
+/**
+ * Run all pending migrations
+ *
+ * @param db - SQLite database instance
+ * @param logger - Optional logger for migration output (defaults to console)
+ * @returns Number of migrations applied
+ * @throws Error if migration fails
+ */
+export declare function runMigrations(db: Database.Database, logger?: BlobLogger): number;
+/**
+ * Rollback to a specific version (use with extreme caution!)
+ *
+ * @param db - SQLite database instance
+ * @param targetVersion - Version to rollback to
+ * @param logger - Optional logger for rollback output (defaults to console)
+ * @throws Error if rollback fails or migrations don't have 'down' methods
+ */
+export declare function rollbackToVersion(db: Database.Database, targetVersion: number, logger?: BlobLogger): void;

package/dist/agent/infra/blob/sqlite-blob-storage.d.ts

@@ -0,0 +1,82 @@
+import type { BlobMetadata, BlobStats, BlobStorageConfig, StoredBlob } from '../../core/domain/blob/types.js';
+import type { IBlobStorage } from '../../core/interfaces/i-blob-storage.js';
+/**
+ * SQLite-based blob storage implementation
+ *
+ * Stores all blobs in a single SQLite database file:
+ * - .brv/storage.db
+ *
+ * Schema:
+ * - blobs: key, content, content_type, original_name, size, tags, created_at, updated_at
+ *
+ * Benefits over file-based storage:
+ * - O(1) lookup for exists/retrieve
+ * - Fast listing and filtering
+ * - ACID transactions for data integrity
+ * - Single file for easy backup/migration
+ */
+export declare class SqliteBlobStorage implements IBlobStorage {
+    private db;
+    private readonly dbPath;
+    private initialized;
+    private readonly inMemory;
+    private readonly logger;
+    private readonly maxBlobSize;
+    private readonly maxTotalSize;
+    private readonly storageDir;
+    constructor(config?: Partial<BlobStorageConfig>);
+    /**
+     * Clear all blobs from storage
+     * WARNING: This is a destructive operation
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Delete a blob by its key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a blob exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get metadata for a blob without retrieving its content
+     */
+    getMetadata(key: string): Promise<BlobMetadata | undefined>;
+    /**
+     * Get storage statistics
+     */
+    getStats(): Promise<BlobStats>;
+    /**
+     * Initialize storage by creating the database and running migrations
+     */
+    initialize(): Promise<void>;
+    /**
+     * List all blob keys, optionally filtered by prefix
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Retrieve a blob by its key
+     */
+    retrieve(key: string): Promise<StoredBlob | undefined>;
+    /**
+     * Store a blob with optional metadata
+     */
+    store(key: string, content: Buffer | string, metadata?: Partial<BlobMetadata>): Promise<StoredBlob>;
+    /**
+     * Ensure storage has been initialized
+     */
+    private ensureInitialized;
+    /**
+     * Convert database row to BlobMetadata
+     */
+    private rowToMetadata;
+    /**
+     * Validate blob key
+     * Keys must be alphanumeric with hyphens and underscores only
+     */
+    private validateKey;
+}