byterover-cli 2.0.0 → 2.1.0

package/dist/agent/infra/agent/cipher-agent.js

@@ -1,6 +1,12 @@
+import { randomUUID } from 'node:crypto';
 import { setMaxListeners } from 'node:events';
+import { getEffectiveMaxInputTokens, resolveRegistryProvider } from '../../core/domain/llm/index.js';
 import { STREAMING_EVENT_NAMES } from '../../core/domain/streaming/types.js';
+import { ToolName } from '../../core/domain/tools/constants.js';
 import { AgentEventBus } from '../events/event-emitter.js';
+import { createGeneratorForProvider } from '../llm/providers/index.js';
+import { EventBasedLogger } from '../logger/event-based-logger.js';
+import { deregisterRootEligibleSession, registerRootEligibleSession } from '../map/agentic-map-service.js';
 import { SessionManager } from '../session/session-manager.js';
 import { TransportEventBridge } from '../transport/transport-event-bridge.js';
 import { AgentError } from './agent-error.js';
@@ -30,6 +36,8 @@ export class CipherAgent extends BaseAgent {
     // Private state (must come before methods)
     _agentEventBus;
     _brvConfig;
+    /** Unique ID for this agent instance — scopes nesting registry ownership. */
+    _instanceId = randomUUID();
     _projectIdProvider;
     /**
      * Session ID - created once during start().
@@ -42,6 +50,11 @@ export class CipherAgent extends BaseAgent {
     _transportClient;
     activeStreamControllers = new Map();
     eventBridge;
+    /**
+     * Tracks session IDs this agent instance registered as root-eligible.
+     * Used for bulk deregistration on agent teardown (cleanupServices).
+     */
+    rootEligibleSessions = new Set();
     sessionManager;
     /**
      * Creates a new CipherAgent instance.
@@ -143,6 +156,13 @@ export class CipherAgent extends BaseAgent {
             this.eventBridge.dispose();
             this.eventBridge = undefined;
         }
+        // Deregister all root-eligible sessions before session manager disposal.
+        // stop()/restart() disposes without calling deleteSession() per session,
+        // so this bulk cleanup prevents registry accumulation across restarts.
+        for (const sessionId of this.rootEligibleSessions) {
+            deregisterRootEligibleSession(sessionId, this._instanceId);
+        }
+        this.rootEligibleSessions.clear();
         // Dispose session manager
         if (this.sessionManager) {
             this.sessionManager.dispose();
@@ -166,17 +186,27 @@ export class CipherAgent extends BaseAgent {
      */
     async createSession(sessionId) {
         this.ensureStarted();
-        return this.getSessionManagerInternal().createSession(sessionId);
+        const session = await this.getSessionManagerInternal().createSession(sessionId);
+        this.registerSessionInternal(session.id);
+        return session;
     }
     /**
      * Create a task-scoped child session for parallel execution.
      * The session gets its own sandbox, context manager, and LLM service.
      */
-    async createTaskSession(taskId, commandType) {
+    async createTaskSession(taskId, commandType, options) {
         this.ensureStarted();
         const sessionMgr = this.getSessionManagerInternal();
         const parentSessionId = this.getSessionIdInternal();
         const childSession = await sessionMgr.createChildSession(parentSessionId, commandType, `task-${commandType}-${taskId}`);
+        // Only register as root-eligible when explicitly opted in.
+        // Top-level executors that may call agentic_map (curate-executor,
+        // folder-pack-executor) pass mapRootEligible: true.
+        // For agentic_map sub-sessions (created by processItem), registration
+        // is skipped here — processItem sets its own isRootCaller: false record.
+        if (options?.mapRootEligible) {
+            this.registerSessionInternal(childSession.id);
+        }
         return childSession.id;
     }
     /**
@@ -203,7 +233,15 @@ export class CipherAgent extends BaseAgent {
         if (this.stateManager) {
             this.stateManager.clearSessionOverride(sessionId);
         }
-        return this.getSessionManagerInternal().deleteSession(sessionId);
+        const deleted = await this.getSessionManagerInternal().deleteSession(sessionId);
+        if (deleted && this.rootEligibleSessions.has(sessionId)) {
+            // Deregister only if this agent instance owns the session.
+            // Scoping prevents one agent's teardown from removing another
+            // agent's live record when they share a session ID.
+            deregisterRootEligibleSession(sessionId, this._instanceId);
+            this.rootEligibleSessions.delete(sessionId);
+        }
+        return deleted;
     }
     /**
      * Delete a task session and all its resources (sandbox + history).
@@ -212,6 +250,13 @@ export class CipherAgent extends BaseAgent {
         this.ensureStarted();
         await this.services.sandboxService.clearSession(sessionId);
         await this.getSessionManagerInternal().deleteSession(sessionId);
+        // Deregister root-eligible record if this agent owns it.
+        // For agentic_map sub-sessions, the record was overwritten to isRootCaller: false
+        // by processItem, so deregisterRootEligibleSession is a no-op (correct).
+        if (this.rootEligibleSessions.has(sessionId)) {
+            deregisterRootEligibleSession(sessionId, this._instanceId);
+            this.rootEligibleSessions.delete(sessionId);
+        }
     }
     /**
      * Execute the agent with user input.
@@ -299,7 +344,11 @@ export class CipherAgent extends BaseAgent {
         this.ensureStarted();
         const sessionMgr = this.getSessionManagerInternal();
         const existingSession = sessionMgr.getSession(sessionId);
-        return existingSession ?? sessionMgr.createSession(sessionId);
+        if (existingSession)
+            return existingSession;
+        const newSession = await sessionMgr.createSession(sessionId);
+        this.registerSessionInternal(newSession.id); // only on actual creation
+        return newSession;
     }
     /**
      * Get a session by ID.
@@ -382,8 +431,6 @@ export class CipherAgent extends BaseAgent {
             providerApiKey: providerUpdate.providerApiKey,
             providerBaseUrl: providerUpdate.providerBaseUrl,
             providerHeaders: providerUpdate.providerHeaders,
-            providerLocation: providerUpdate.providerLocation,
-            providerProject: providerUpdate.providerProject,
             siteName: this.config.siteName,
             temperature: this.config.llm.temperature,
             verbose: this.config.llm.verbose,
@@ -394,16 +441,27 @@ export class CipherAgent extends BaseAgent {
                 maxSessions: this.config.sessions.maxSessions,
                 sessionTTL: this.config.sessions.sessionTTL,
             },
+            onSessionRemoved: (sessionId) => {
+                this.handleSessionRemoved(sessionId);
+            },
         });
-        // Success — dispose old and swap
+        // Success — dispose old and swap.
+        // Deregister all root-eligible sessions from the old SM first —
+        // they no longer exist after dispose(). The next stream()/execute()
+        // will recreate sessions via getOrCreateSession and re-register them.
         if (this.sessionManager) {
+            for (const sid of this.rootEligibleSessions) {
+                deregisterRootEligibleSession(sid, this._instanceId);
+            }
+            this.rootEligibleSessions.clear();
             this.sessionManager.dispose();
         }
         this.sessionManager = newSessionManager;
         // Re-wire SessionManager into sandbox for tools.agentQuery()
         this.services.sandboxService.setSessionManager?.(this.sessionManager);
+        // Rebind map tools with fresh generator/tokenizer/maxContextTokens
+        this.rebindMapTools(services, httpConfig, sessionLLMConfig);
     }
-    // === Protected Methods (implement abstract from BaseAgent) ===
     /**
      * Reset the agent to initial state.
      * Resets execution state only. To reset sessions, use resetSession(sessionId).
@@ -414,6 +472,7 @@ export class CipherAgent extends BaseAgent {
             this.stateManager.reset();
         }
     }
+    // === Protected Methods (implement abstract from BaseAgent) ===
     /**
      * Reset a specific session's conversation history.
      * @param sessionId - The session ID to reset
@@ -478,8 +537,6 @@ export class CipherAgent extends BaseAgent {
             providerApiKey: this.config.providerApiKey,
             providerBaseUrl: this.config.providerBaseUrl,
             providerHeaders: this.config.providerHeaders,
-            providerLocation: this.config.providerLocation,
-            providerProject: this.config.providerProject,
             siteName: this.config.siteName,
             temperature: this.config.llm.temperature,
             verbose: this.config.llm.verbose,
@@ -490,6 +547,9 @@ export class CipherAgent extends BaseAgent {
                 maxSessions: this.config.sessions.maxSessions,
                 sessionTTL: this.config.sessions.sessionTTL,
             },
+            onSessionRemoved: (sessionId) => {
+                this.handleSessionRemoved(sessionId);
+            },
         });
         // Wire SessionManager into sandbox for tools.agentQuery() sub-agent delegation
         this.services.sandboxService.setSessionManager?.(this.sessionManager);
@@ -497,6 +557,11 @@ export class CipherAgent extends BaseAgent {
         // Each agent has exactly 1 session created at start time
         const defaultSession = await this.sessionManager.createSession();
         this._sessionId = defaultSession.id;
+        this.registerSessionInternal(defaultSession.id);
+        // Inject agent instance and content generator into ToolProvider for map tools.
+        // Uses rebindMapTools() which atomically replaces map tools with fresh deps
+        // (generator, tokenizer, maxContextTokens, logger).
+        this.rebindMapTools(services, httpConfig, sessionLLMConfig);
         // Create event bridge if transport client is injected (child process mode).
         // The bridge forwards AgentEventBus llmservice:* events to the transport server.
         if (this._transportClient) {
@@ -581,6 +646,9 @@ export class CipherAgent extends BaseAgent {
                 const sessionMgr = this.getSessionManagerInternal();
                 const existingSession = sessionMgr.getSession(sessionId);
                 const session = existingSession ?? (await sessionMgr.createSession(sessionId));
+                if (!existingSession) {
+                    this.registerSessionInternal(session.id); // only on actual creation
+                }
                 // Increment iteration counter
                 this.getStateManager().incrementIteration();
                 // Call session.streamRun() which emits events and run:complete
@@ -695,7 +763,6 @@ export class CipherAgent extends BaseAgent {
         }
         this._sessionId = sessionId;
     }
-    // === Private Helpers (alphabetical order) ===
     /**
      * Build HTTP config for ByteRover API calls.
      * Uses lazy providers when injected (child process mode), otherwise static config.
@@ -710,6 +777,7 @@ export class CipherAgent extends BaseAgent {
             teamId: this._teamIdProvider ?? this.config.teamId ?? this._brvConfig?.teamId ?? '',
         };
     }
+    // === Private Helpers (alphabetical order) ===
     getHistoryStorageInternal() {
         const storage = this.services?.historyStorage;
         if (!storage) {
@@ -736,4 +804,63 @@ export class CipherAgent extends BaseAgent {
         }
         return manager;
     }
+    /**
+     * Handle SessionManager lifecycle removals (delete/end/TTL-expire) and keep
+     * root-eligible tracking synchronized with the global nesting registry.
+     */
+    handleSessionRemoved(sessionId) {
+        if (!this.rootEligibleSessions.has(sessionId))
+            return;
+        deregisterRootEligibleSession(sessionId, this._instanceId);
+        this.rootEligibleSessions.delete(sessionId);
+    }
+    /**
+     * Rebuild map tool dependencies and update ToolProvider + SandboxService.
+     * Called from both start() (initial setup) and refreshProviderConfig() (hot-swap).
+     */
+    rebindMapTools(services, httpConfig, sessionLLMConfig) {
+        const mapProvider = sessionLLMConfig.provider
+            ?? (sessionLLMConfig.openRouterApiKey ? 'openrouter' : 'byterover');
+        const mapGenerator = createGeneratorForProvider(mapProvider, {
+            apiKey: mapProvider === 'openrouter'
+                ? (sessionLLMConfig.openRouterApiKey ?? sessionLLMConfig.providerApiKey)
+                : sessionLLMConfig.providerApiKey,
+            baseUrl: sessionLLMConfig.providerBaseUrl,
+            headers: sessionLLMConfig.providerHeaders,
+            httpConfig: httpConfig,
+            httpReferer: sessionLLMConfig.httpReferer,
+            maxTokens: 4096,
+            model: sessionLLMConfig.model,
+            siteName: sessionLLMConfig.siteName,
+            temperature: 0,
+        });
+        // Adapter pattern: wrap mapGenerator.estimateTokensSync() as ITokenizer
+        const mapTokenizer = {
+            countTokens: (text) => mapGenerator.estimateTokensSync(text),
+        };
+        // Compute registry-clamped maxContextTokens
+        const mapModel = sessionLLMConfig.model ?? 'gemini-3-flash-preview';
+        const mapRegistryProvider = resolveRegistryProvider(mapModel, mapProvider);
+        const effectiveMaxContextTokens = getEffectiveMaxInputTokens(mapRegistryProvider, mapModel, sessionLLMConfig.maxInputTokens);
+        const mapLogger = new EventBasedLogger(this._agentEventBus, 'MapTools');
+        // Atomically replace map tools with fresh generator/tokenizer/maxContextTokens.
+        // replaceTools() is build-then-swap — if build fails, old tools remain intact.
+        services.toolProvider.replaceTools([ToolName.LLM_MAP, ToolName.AGENTIC_MAP], {
+            agentInstance: this,
+            contentGenerator: mapGenerator,
+            logger: mapLogger,
+            maxContextTokens: effectiveMaxContextTokens,
+            tokenizer: mapTokenizer,
+        });
+        // Update sandbox for tools.curation.mapExtract()
+        services.sandboxService.setContentGenerator?.(mapGenerator);
+    }
+    /**
+     * Register a session as root-eligible and track it for lifecycle cleanup.
+     * Routes all root-eligible registrations through a single point.
+     */
+    registerSessionInternal(sessionId) {
+        registerRootEligibleSession(sessionId, this._instanceId); // throws if id is a live sub-session record
+        this.rootEligibleSessions.add(sessionId);
+    }
 }

package/dist/agent/infra/agent/provider-update-config.d.ts

@@ -14,6 +14,4 @@ export interface ProviderUpdateConfig {
     providerApiKey?: string;
     providerBaseUrl?: string;
     providerHeaders?: Record<string, string>;
-    providerLocation?: string;
-    providerProject?: string;
 }

package/dist/agent/infra/agent/service-initializer.d.ts

@@ -44,7 +44,7 @@ export interface SessionLLMConfig {
     maxTokens?: number;
     model: string;
     openRouterApiKey?: string;
-    /** Provider ID (anthropic, openai, google, google-vertex, xai, groq, mistral, openrouter, byterover) */
+    /** Provider ID (anthropic, openai, google, xai, groq, mistral, openrouter, byterover) */
     provider?: string;
     /** API key for the direct provider */
     providerApiKey?: string;
@@ -52,10 +52,6 @@ export interface SessionLLMConfig {
     providerBaseUrl?: string;
     /** Custom headers for the provider */
     providerHeaders?: Record<string, string>;
-    /** GCP location for Vertex AI (default: us-central1) */
-    providerLocation?: string;
-    /** GCP project ID for Vertex AI */
-    providerProject?: string;
     siteName?: string;
     temperature?: number;
     verbose?: boolean;
@@ -76,7 +72,7 @@ export type { CipherAgentServices, SessionManagerConfig, SessionServices } from
  * 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)
+ * 11. History storage (file-based granular storage)
  * 12. Return all services
  *
  * @param config - Validated agent configuration (Zod-validated)

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

@@ -18,6 +18,9 @@ import { SessionEventBus } from '../events/event-emitter.js';
 import { FileSystemService } from '../file-system/file-system-service.js';
 import { AgentLLMService } from '../llm/agent-llm-service.js';
 import { CompactionService } from '../llm/context/compaction/compaction-service.js';
+import { EscalatedCompressionStrategy } from '../llm/context/compression/escalated-compression.js';
+import { MiddleRemovalStrategy } from '../llm/context/compression/middle-removal.js';
+import { OldestRemovalStrategy } from '../llm/context/compression/oldest-removal.js';
 import { LoggingContentGenerator, RetryableContentGenerator, } from '../llm/generators/index.js';
 import { createGeneratorForProvider } from '../llm/providers/index.js';
 import { DEFAULT_RETRY_POLICY } from '../llm/retry/retry-policy.js';
@@ -26,12 +29,11 @@ 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 { FileKeyStorage } from '../storage/file-key-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 { MapSelectionContributor } from '../system-prompt/contributors/map-selection-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';
@@ -54,7 +56,7 @@ import { ToolProvider } from '../tools/tool-provider.js';
  * 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)
+ * 11. History storage (file-based granular storage)
  * 12. Return all services
  *
  * @param config - Validated agent configuration (Zod-validated)
@@ -126,6 +128,10 @@ export async function createCipherAgentServices(config, agentEventBus) {
         workingDirectory,
     });
     systemPromptManager.registerContributor(contextTreeContributor);
+    // Register map selection contributor for curate commands
+    // Priority 16 — right after context tree structure, before memories
+    const mapSelectionContributor = new MapSelectionContributor('mapSelection', 16);
+    systemPromptManager.registerContributor(mapSelectionContributor);
     // 7. Tool provider (depends on FileSystemService, ProcessService, MemoryManager, SystemPromptManager)
     const verbose = config.llm.verbose ?? false;
     const descriptionLoader = new ToolDescriptionLoader();
@@ -148,38 +154,22 @@ export async function createCipherAgentServices(config, agentEventBus) {
     // 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: storageBasePath,
-        });
-        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 last 2 user turns from pruning
-            pruneKeepPercent: 0.2, // Keep 20% of context window in tool outputs
-            pruneMinimumPercent: 0.1, // Only prune if 10%+ of context window can be saved
-        });
-        logger.info('Granular history storage enabled for new sessions');
-    }
-    else {
-        // Default: use blob storage for all sessions
-        historyStorage = new BlobHistoryStorage(blobStorage);
-    }
+    // 11. History storage - granular file-based storage
+    const keyStorage = new FileKeyStorage({
+        storageDir: storageBasePath,
+    });
+    await keyStorage.initialize();
+    const messageStorage = new MessageStorageService(keyStorage);
+    const messageStorageService = messageStorage;
+    const historyStorage = new GranularHistoryStorage(messageStorage);
+    // CompactionService for context overflow management
+    const tokenizer = new GeminiTokenizer(config.model ?? 'gemini-3-flash-preview');
+    const compactionService = new CompactionService(messageStorage, tokenizer, {
+        overflowThreshold: 0.85, // 85% triggers compaction check
+        protectedTurns: 2, // Protect last 2 user turns from pruning
+        pruneKeepPercent: 0.2, // Keep 20% of context window in tool outputs
+        pruneMinimumPercent: 0.1, // Only prune if 10%+ of context window can be saved
+    });
     // 12. Log successful initialization
     logger.info('CipherAgent services initialized successfully', {
         model: config.model,
@@ -239,6 +229,20 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
             logResponses: llmConfig.verbose,
             verbose: llmConfig.verbose,
         });
+        // Create escalated compression strategy with retry-only generator (no UI noise).
+        // Skip LoggingContentGenerator: avoids llmservice:thinking spinner events.
+        // Use a silenced SessionEventBus: RetryableContentGenerator emits
+        // llmservice:warning/error via eventBus on retries. Using a detached
+        // event bus with no listeners ensures these fire into void.
+        const compactionEventBus = new SessionEventBus();
+        const compactionGenerator = new RetryableContentGenerator(baseGenerator, {
+            eventBus: compactionEventBus,
+            policy: DEFAULT_RETRY_POLICY,
+        });
+        const escalatedStrategy = new EscalatedCompressionStrategy({
+            generator: compactionGenerator,
+            model: llmConfig.model ?? 'gemini-3-flash-preview',
+        });
         return new AgentLLMService(sessionId, generator, {
             maxInputTokens: llmConfig.maxInputTokens,
             maxIterations: llmConfig.maxIterations ?? 50,
@@ -249,6 +253,11 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
             verbose: llmConfig.verbose ?? false,
         }, {
             compactionService: sharedServices.compactionService,
+            compressionStrategies: [
+                escalatedStrategy,
+                new MiddleRemovalStrategy({ preserveEnd: 5, preserveStart: 4 }),
+                new OldestRemovalStrategy({ minMessagesToKeep: 4 }),
+            ],
             historyStorage: sharedServices.historyStorage,
             logger: sessionLogger,
             memoryManager: sharedServices.memoryManager,
@@ -267,10 +276,8 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
         headers: llmConfig.providerHeaders,
         httpConfig: httpConfig,
         httpReferer: llmConfig.httpReferer,
-        location: llmConfig.providerLocation,
         maxTokens: llmConfig.maxTokens ?? 8192,
         model: llmConfig.model,
-        project: llmConfig.providerProject,
         siteName: llmConfig.siteName,
         temperature: llmConfig.temperature ?? 0.7,
     });

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

@@ -2,10 +2,10 @@ 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.
+ * Uses file-based storage with one directory per blob.
  *
  * @param config - Blob storage configuration
- * @returns SQLite blob storage implementation
+ * @returns File-based blob storage implementation
  *
  * @example
  * const storage = createBlobStorage({ storageDir: '/path/to/xdg/storage' });

package/dist/agent/infra/blob/blob-storage-factory.js

@@ -1,14 +1,14 @@
-import { SqliteBlobStorage } from './sqlite-blob-storage.js';
+import { FileBlobStorage } from './file-blob-storage.js';
 /**
  * Factory function to create blob storage backend.
- * Always uses SQLite for better performance, single file, and ACID transactions.
+ * Uses file-based storage with one directory per blob.
  *
  * @param config - Blob storage configuration
- * @returns SQLite blob storage implementation
+ * @returns File-based blob storage implementation
  *
  * @example
  * const storage = createBlobStorage({ storageDir: '/path/to/xdg/storage' });
  */
 export function createBlobStorage(config) {
-    return new SqliteBlobStorage(config);
+    return new FileBlobStorage(config);
 }

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

@@ -0,0 +1,96 @@
+import type { BlobMetadata, BlobStats, BlobStorageConfig, StoredBlob } from '../../core/domain/blob/types.js';
+import type { IBlobStorage } from '../../core/interfaces/i-blob-storage.js';
+/**
+ * File-based blob storage implementation.
+ *
+ * Stores blobs as individual files on the filesystem:
+ *   {storageDir}/blobs/{key}/content.bin  — binary content
+ *   {storageDir}/blobs/{key}/metadata.json — JSON metadata
+ *
+ * Features:
+ * - One directory per blob (O(1) read/write/delete)
+ * - Atomic writes via write-to-temp + rename
+ * - Size limit enforcement (per-blob and total)
+ * - In-memory mode for fast unit tests
+ * - Prefix-based listing via readdir
+ */
+export declare class FileBlobStorage implements IBlobStorage {
+    private readonly baseDir;
+    private initialized;
+    private readonly inMemory;
+    private readonly maxBlobSize;
+    private readonly maxTotalSize;
+    private memoryStore;
+    private readonly storageDir;
+    constructor(config?: Partial<BlobStorageConfig>);
+    /**
+     * Clear all blobs from storage.
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the storage. Releases in-memory data.
+     */
+    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 the storage backend.
+     */
+    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>;
+    private ensureInitialized;
+    /**
+     * Get stats by scanning the blobs directory.
+     */
+    private getStatsFromDisk;
+    /**
+     * List keys from disk, optionally filtered by prefix.
+     */
+    private listFromDisk;
+    /**
+     * Read metadata from disk for a given key.
+     */
+    private readMetadataFromDisk;
+    /**
+     * Retrieve a blob from disk.
+     */
+    private retrieveFromDisk;
+    /**
+     * Convert StoredMetadata to public BlobMetadata.
+     */
+    private toPublicMetadata;
+    /**
+     * Validate blob key.
+     * Keys must be alphanumeric with hyphens and underscores only.
+     */
+    private validateKey;
+    /**
+     * Write blob content and metadata to disk atomically.
+     */
+    private writeToDisk;
+}