byterover-cli 3.2.0 → 3.4.0

package/.env.production

@@ -1,7 +1,3 @@
-# ByteRover CLI - Environment Configuration
-# Copy this file to .env.development (for dev) or .env.production (for production)
-# and fill in the values for your environment.
-
 BRV_API_BASE_URL=https://iam.byterover.dev/api/v1
 BRV_AUTHORIZATION_URL=https://iam.byterover.dev/api/v1/oidc/authorize
 BRV_COGIT_API_BASE_URL=https://v3-cgit.byterover.dev/api/v1

package/dist/agent/core/domain/swarm/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * All supported memory provider types.
+ */
+export declare const PROVIDER_TYPES: readonly ["byterover", "honcho", "hindsight", "obsidian", "local-markdown", "gbrain", "memory-wiki"];
+/**
+ * Union type of supported memory provider identifiers.
+ */
+export type ProviderType = (typeof PROVIDER_TYPES)[number];
+/**
+ * Query type classification for routing decisions.
+ */
+export type QueryType = 'factual' | 'personal' | 'relational' | 'temporal';
+/**
+ * Check if a provider type is local (no network required).
+ */
+export declare function isLocalProvider(type: ProviderType): boolean;
+/**
+ * Check if a provider type requires network/cloud access.
+ */
+export declare function isCloudProvider(type: ProviderType): boolean;
+/**
+ * Capabilities that a memory provider can expose.
+ */
+export type ProviderCapabilities = {
+    /** Average response time in milliseconds */
+    avgLatencyMs: number;
+    /** Can follow entity links / graph edges */
+    graphTraversal: boolean;
+    /** BM25 / full-text search */
+    keywordSearch: boolean;
+    /** No network calls needed */
+    localOnly: boolean;
+    /** Context budget per query */
+    maxTokensPerQuery: number;
+    /** Vector similarity search */
+    semanticSearch: boolean;
+    /** Time-range filtering */
+    temporalQuery: boolean;
+    /** Psychological profiles / user preferences */
+    userModeling: boolean;
+    /** Can store new memories */
+    writeSupported: boolean;
+};
+/**
+ * A single memory entry stored in a provider.
+ */
+export type MemoryEntry = {
+    content: string;
+    metadata: {
+        confidence?: number;
+        entities?: string[];
+        expiresAt?: number;
+        relations?: string[];
+        source: string;
+        tags?: string[];
+        timestamp: number;
+    };
+};
+/**
+ * Request to query a memory provider.
+ */
+export type QueryRequest = {
+    /** Enrichment data from predecessor providers (for graph execution) */
+    enrichment?: {
+        context?: string;
+        entities?: string[];
+        excerpts?: string[];
+    };
+    /** Whether to return provenance info */
+    includeMetadata?: boolean;
+    /** Limit results */
+    maxResults?: number;
+    /** Token budget for this provider */
+    maxTokens?: number;
+    /** The natural language query */
+    query: string;
+    /** Restrict to subtree/namespace */
+    scope?: string;
+    /** Temporal filter */
+    timeRange?: {
+        after?: number;
+        before?: number;
+    };
+    /** Hint: factual, temporal, personal, relational */
+    type?: QueryType;
+};
+/**
+ * A single result from a memory provider query.
+ */
+export type QueryResult = {
+    content: string;
+    id: string;
+    metadata: {
+        confidence?: number;
+        matchType: 'graph' | 'keyword' | 'profile' | 'semantic' | 'temporal';
+        path?: string;
+        source: string;
+        timestamp?: number;
+    };
+    provider: string;
+    providerType: ProviderType;
+    score: number;
+};
+/**
+ * Result from storing a memory entry.
+ */
+export type StoreResult = {
+    id: string;
+    provider: string;
+    success: boolean;
+};
+/**
+ * Health status of a memory provider.
+ */
+export type HealthStatus = {
+    available: boolean;
+    error?: string;
+    latencyMs?: number;
+};
+/**
+ * Cost estimate for executing a query against a provider.
+ */
+export type CostEstimate = {
+    estimatedCostCents: number;
+    estimatedLatencyMs: number;
+    estimatedTokens: number;
+};
+/**
+ * Create default capabilities for a given provider type.
+ * Used for initialization before actual provider reports its capabilities.
+ */
+export declare function createDefaultCapabilities(type: ProviderType): ProviderCapabilities;

package/dist/agent/core/domain/swarm/types.js

@@ -0,0 +1,128 @@
+/**
+ * All supported memory provider types.
+ */
+export const PROVIDER_TYPES = [
+    'byterover',
+    'honcho',
+    'hindsight',
+    'obsidian',
+    'local-markdown',
+    'gbrain',
+    'memory-wiki',
+];
+/**
+ * Local providers that require no network calls.
+ */
+const LOCAL_PROVIDERS = new Set(['byterover', 'local-markdown', 'memory-wiki', 'obsidian']);
+/**
+ * Check if a provider type is local (no network required).
+ */
+export function isLocalProvider(type) {
+    return LOCAL_PROVIDERS.has(type);
+}
+/**
+ * Check if a provider type requires network/cloud access.
+ */
+export function isCloudProvider(type) {
+    return !LOCAL_PROVIDERS.has(type);
+}
+/* eslint-disable perfectionist/sort-switch-case */
+/**
+ * Create default capabilities for a given provider type.
+ * Used for initialization before actual provider reports its capabilities.
+ */
+export function createDefaultCapabilities(type) {
+    switch (type) {
+        case 'byterover': {
+            return {
+                avgLatencyMs: 50,
+                graphTraversal: false,
+                keywordSearch: true,
+                localOnly: true,
+                maxTokensPerQuery: 8000,
+                semanticSearch: false,
+                temporalQuery: false,
+                userModeling: false,
+                writeSupported: false,
+            };
+        }
+        case 'obsidian': {
+            return {
+                avgLatencyMs: 100,
+                graphTraversal: true,
+                keywordSearch: true,
+                localOnly: true,
+                maxTokensPerQuery: 8000,
+                semanticSearch: false,
+                temporalQuery: false,
+                userModeling: false,
+                writeSupported: false,
+            };
+        }
+        case 'local-markdown': {
+            return {
+                avgLatencyMs: 80,
+                graphTraversal: true,
+                keywordSearch: true,
+                localOnly: true,
+                maxTokensPerQuery: 6000,
+                semanticSearch: false,
+                temporalQuery: false,
+                userModeling: false,
+                writeSupported: true,
+            };
+        }
+        case 'honcho': {
+            return {
+                avgLatencyMs: 500,
+                graphTraversal: false,
+                keywordSearch: false,
+                localOnly: false,
+                maxTokensPerQuery: 16_000,
+                semanticSearch: true,
+                temporalQuery: true,
+                userModeling: true,
+                writeSupported: true,
+            };
+        }
+        case 'hindsight': {
+            return {
+                avgLatencyMs: 300,
+                graphTraversal: true,
+                keywordSearch: true,
+                localOnly: false,
+                maxTokensPerQuery: 12_000,
+                semanticSearch: true,
+                temporalQuery: true,
+                userModeling: false,
+                writeSupported: true,
+            };
+        }
+        case 'gbrain': {
+            return {
+                avgLatencyMs: 200,
+                graphTraversal: false,
+                keywordSearch: true,
+                localOnly: false,
+                maxTokensPerQuery: 10_000,
+                semanticSearch: true,
+                temporalQuery: true,
+                userModeling: false,
+                writeSupported: true,
+            };
+        }
+        case 'memory-wiki': {
+            return {
+                avgLatencyMs: 60,
+                graphTraversal: false,
+                keywordSearch: true,
+                localOnly: true,
+                maxTokensPerQuery: 8000,
+                semanticSearch: false,
+                temporalQuery: false,
+                userModeling: false,
+                writeSupported: true,
+            };
+        }
+    }
+}

package/dist/agent/core/domain/tools/constants.d.ts

@@ -14,6 +14,8 @@ export declare const ToolName: {
     readonly LLM_MAP: 'llm_map';
     readonly READ_FILE: 'read_file';
     readonly SEARCH_KNOWLEDGE: 'search_knowledge';
+    readonly SWARM_QUERY: 'swarm_query';
+    readonly SWARM_STORE: 'swarm_store';
     readonly WRITE_FILE: 'write_file';
 };
 /**

package/dist/agent/core/domain/tools/constants.js

@@ -14,5 +14,7 @@ export const ToolName = {
     LLM_MAP: 'llm_map',
     READ_FILE: 'read_file',
     SEARCH_KNOWLEDGE: 'search_knowledge',
+    SWARM_QUERY: 'swarm_query',
+    SWARM_STORE: 'swarm_store',
     WRITE_FILE: 'write_file',
 };

package/dist/agent/core/interfaces/i-memory-provider.d.ts

@@ -0,0 +1,45 @@
+import type { CostEstimate, HealthStatus, MemoryEntry, ProviderCapabilities, ProviderType, QueryRequest, QueryResult, StoreResult } from '../domain/swarm/types.js';
+/**
+ * Unified interface for memory providers.
+ * Every memory provider (ByteRover, Obsidian, Honcho, etc.) implements this contract.
+ * The swarm graph operates exclusively through this interface.
+ */
+export interface IMemoryProvider {
+    /** Provider capabilities (search types, write support, latency) */
+    readonly capabilities: ProviderCapabilities;
+    /**
+     * Delete a memory entry.
+     * @throws if the entry doesn't exist or provider is read-only
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Estimate the cost of executing a query.
+     * Used by the router for budget-aware dispatching.
+     */
+    estimateCost(request: QueryRequest): CostEstimate;
+    /**
+     * Check if this provider is reachable and functional.
+     * Used by the control plane to skip unavailable providers.
+     */
+    healthCheck(): Promise<HealthStatus>;
+    /** Unique provider identifier */
+    readonly id: string;
+    /**
+     * Query this provider for relevant memories.
+     * The core operation — every provider MUST support this.
+     */
+    query(request: QueryRequest): Promise<QueryResult[]>;
+    /**
+     * Store a memory entry into this provider.
+     * Not all providers support writes (e.g., Obsidian may be read-only).
+     * @throws if the provider is read-only
+     */
+    store(entry: MemoryEntry): Promise<StoreResult>;
+    /** Provider type for routing decisions */
+    readonly type: ProviderType;
+    /**
+     * Update an existing memory entry.
+     * @throws if the entry doesn't exist or provider is read-only
+     */
+    update(id: string, entry: Partial<MemoryEntry>): Promise<void>;
+}

package/dist/agent/core/interfaces/i-memory-provider.js

@@ -0,0 +1 @@
+export {};

package/dist/agent/core/interfaces/i-sandbox-service.d.ts

@@ -5,6 +5,7 @@ import type { REPLResult, SandboxConfig } from '../domain/sandbox/types.js';
 import type { IContentGenerator } from './i-content-generator.js';
 import type { ICurateService } from './i-curate-service.js';
 import type { IFileSystem } from './i-file-system.js';
+import type { ISwarmCoordinator } from './i-swarm-coordinator.js';
 /**
  * Service interface for code sandbox execution.
  * Provides isolated JavaScript/TypeScript code execution with security controls.
@@ -89,4 +90,11 @@ export interface ISandboxService {
      * @param sessionManager - Session manager instance
      */
     setSessionManager?(sessionManager: SessionManager): void;
+    /**
+     * Set the swarm coordinator for cross-provider query and store.
+     * When set, sandboxes will have access to `tools.swarmQuery()` and `tools.swarmStore()`.
+     *
+     * @param swarmCoordinator - Swarm coordinator instance
+     */
+    setSwarmCoordinator?(swarmCoordinator: ISwarmCoordinator): void;
 }

package/dist/agent/core/interfaces/i-swarm-coordinator.d.ts

@@ -0,0 +1,127 @@
+import type { ProviderCapabilities, ProviderType, QueryRequest, QueryResult, QueryType } from '../domain/swarm/types.js';
+/**
+ * Metadata about a single provider's contribution to a swarm query.
+ */
+export type ProviderQueryMeta = {
+    /** Which provider enriched this provider's query (if any) */
+    enrichedBy?: string;
+    /** Content excerpts injected via enrichment from predecessors */
+    enrichmentExcerpts?: string[];
+    /** Why this provider was excluded (only when selected=false) */
+    excludeReason?: string;
+    /** How long this provider took to respond */
+    latencyMs: number;
+    /** How many results this provider returned */
+    resultCount: number;
+    /** Whether this provider was selected for this query */
+    selected: boolean;
+};
+/**
+ * Metadata about the overall swarm query execution.
+ */
+export type QueryMeta = {
+    /** Total monetary cost across all cloud providers */
+    costCents: number;
+    /** Per-provider execution metadata */
+    providers: Record<string, ProviderQueryMeta>;
+    /** How the query was classified */
+    queryType: QueryType;
+    /** End-to-end latency including routing, execution, and merging */
+    totalLatencyMs: number;
+};
+/**
+ * Complete result from a swarm query — results + execution metadata.
+ */
+export type SwarmQueryResult = {
+    /** Execution metadata (providers used, latency, cost) */
+    meta: QueryMeta;
+    /** Ranked, fused results from all active providers */
+    results: QueryResult[];
+};
+/**
+ * Summary info about a registered provider (for status display).
+ */
+export type ProviderInfo = {
+    /** Provider capabilities */
+    capabilities: ProviderCapabilities;
+    /** Whether the provider is currently reachable */
+    healthy: boolean;
+    /** Provider identifier */
+    id: string;
+    /** Provider type (local/cloud) */
+    type: ProviderType;
+};
+/**
+ * Presentation-oriented summary of the swarm state.
+ * Used by CLI status, system prompt contributor, and REPL commands.
+ */
+export type SwarmSummary = {
+    /** Number of active (healthy + enabled) providers */
+    activeCount: number;
+    /** Average query latency in milliseconds */
+    avgLatencyMs: number;
+    /** Learning status */
+    learningStatus: 'cold-start' | 'converged' | 'learning';
+    /** Monthly budget cap in cents */
+    monthlyBudgetCents: number;
+    /** Monthly spend so far in cents */
+    monthlySpendCents: number;
+    /** Per-provider summaries */
+    providers: ProviderInfo[];
+    /** Total number of registered providers */
+    totalCount: number;
+    /** Total queries executed */
+    totalQueries: number;
+};
+/**
+ * Request to store knowledge via the swarm.
+ */
+export type SwarmStoreRequest = {
+    /** The knowledge content to store */
+    content: string;
+    /** Optional write type hint — skips classification when provided */
+    contentType?: 'entity' | 'general' | 'note';
+    /** Explicit target provider ID — overrides classification */
+    provider?: string;
+};
+/**
+ * Result from a swarm store operation.
+ */
+export type SwarmStoreResult = {
+    /** Error message if store failed */
+    error?: string;
+    /** True when content was routed to context tree as fallback (no external providers available) */
+    fallback?: boolean;
+    /** ID assigned by the target provider */
+    id: string;
+    /** Store latency in milliseconds */
+    latencyMs: number;
+    /** Provider that stored the content */
+    provider: string;
+    /** Whether the store succeeded */
+    success: boolean;
+};
+/**
+ * Central coordinator for the memory swarm.
+ * Routes queries to providers, executes the graph, and fuses results.
+ * Routes store operations to the best writable provider.
+ */
+export interface ISwarmCoordinator {
+    /**
+     * Execute a swarm query — route, execute providers, fuse results.
+     */
+    execute(request: QueryRequest): Promise<SwarmQueryResult>;
+    /**
+     * Get info about all registered providers and their health status.
+     */
+    getActiveProviders(): ProviderInfo[];
+    /**
+     * Get a presentation-oriented summary of the swarm state.
+     */
+    getSummary(): SwarmSummary;
+    /**
+     * Store knowledge in the best writable provider.
+     * Routes by content type or explicit provider target.
+     */
+    store(request: SwarmStoreRequest): Promise<SwarmStoreResult>;
+}

package/dist/agent/core/interfaces/i-swarm-coordinator.js

@@ -0,0 +1 @@
+export {};

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

@@ -33,11 +33,17 @@ import { SandboxService } from '../sandbox/sandbox-service.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 { loadSwarmConfig } from '../swarm/config/swarm-config-loader.js';
+import { buildProvidersFromConfig } from '../swarm/provider-factory.js';
+import { SwarmCoordinator } from '../swarm/swarm-coordinator.js';
+import { validateSwarmProviders } from '../swarm/validation/config-validator.js';
 import { ContextTreeStructureContributor } from '../system-prompt/contributors/context-tree-structure-contributor.js';
 import { MapSelectionContributor } from '../system-prompt/contributors/map-selection-contributor.js';
+import { SwarmStateContributor } from '../system-prompt/contributors/swarm-state-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 { createSearchKnowledgeService } from '../tools/implementations/search-knowledge-service.js';
 import { PolicyEngine } from '../tools/policy-engine.js';
 import { ToolDescriptionLoader } from '../tools/tool-description-loader.js';
 import { ToolManager } from '../tools/tool-manager.js';
@@ -133,6 +139,47 @@ export async function createCipherAgentServices(config, agentEventBus) {
     // Priority 16 — right after context tree structure, before memories
     const mapSelectionContributor = new MapSelectionContributor('mapSelection', 16);
     systemPromptManager.registerContributor(mapSelectionContributor);
+    // 6b. Swarm coordinator — try to load config and build providers.
+    // Missing config → fail-open (no swarm). Invalid config → warn but continue.
+    let swarmCoordinator;
+    try {
+        const swarmConfig = await loadSwarmConfig(workingDirectory);
+        // Validate enrichment topology — structural errors block swarm init.
+        // Provider-specific errors (bad paths, missing API keys) are handled
+        // by health checks, preserving degraded-mode semantics.
+        const swarmValidation = await validateSwarmProviders(swarmConfig);
+        const topologyErrors = swarmValidation.errors.filter((e) => e.provider === 'enrichment');
+        if (topologyErrors.length > 0) {
+            const messages = topologyErrors.map((e) => e.message);
+            throw new Error(`Invalid enrichment topology:\n  ${messages.join('\n  ')}`);
+        }
+        // Log provider-specific warnings/errors without blocking
+        for (const error of swarmValidation.errors.filter((e) => e.provider !== 'enrichment')) {
+            logger.warn(`Swarm provider issue: ${error.provider}: ${error.message}`);
+        }
+        const swarmProviders = buildProvidersFromConfig(swarmConfig, {
+            searchService: createSearchKnowledgeService(fileSystemService),
+        });
+        if (swarmProviders.length > 0) {
+            swarmCoordinator = new SwarmCoordinator(swarmProviders, swarmConfig);
+            // Run initial health checks so unhealthy providers are skipped from first query
+            await swarmCoordinator.refreshHealth();
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const isConfigMissing = message.includes('not found');
+        if (!isConfigMissing) {
+            // Config exists but is invalid — warn so the user can diagnose
+            logger.warn(`Swarm disabled due to config error: ${message}`);
+        }
+        // Missing config is expected — silently skip
+    }
+    // Register swarm state contributor when multi-provider swarm is active
+    if (swarmCoordinator) {
+        const swarmStateContributor = new SwarmStateContributor('swarmState', 17, swarmCoordinator);
+        systemPromptManager.registerContributor(swarmStateContributor);
+    }
     // 7. Abstract generation queue (generator injected later via rebindCurateTools)
     const abstractQueue = new AbstractGenerationQueue(workingDirectory);
     // 8. Tool provider (depends on FileSystemService, ProcessService, MemoryManager, SystemPromptManager)
@@ -146,6 +193,7 @@ export async function createCipherAgentServices(config, agentEventBus) {
         memoryManager,
         processService,
         sandboxService,
+        swarmCoordinator,
     }, systemPromptManager, descriptionLoader);
     await toolProvider.initialize();
     // 9. Policy engine with default rules for autonomous execution

package/dist/agent/infra/map/map-shared.d.ts

@@ -99,19 +99,19 @@ export declare const AgenticMapParametersSchema: z.ZodObject<{
     output_schema: Record<string, any>;
     input_path: string;
     output_path: string;
+    read_only?: boolean | undefined;
     max_attempts?: number | undefined;
     timeout_seconds?: number | undefined;
     max_depth?: number | undefined;
-    read_only?: boolean | undefined;
 }, {
     prompt: string;
     output_schema: Record<string, any>;
     input_path: string;
     output_path: string;
+    read_only?: boolean | undefined;
     max_attempts?: number | undefined;
     timeout_seconds?: number | undefined;
     max_depth?: number | undefined;
-    read_only?: boolean | undefined;
 }>;
 export type AgenticMapParameters = z.infer<typeof AgenticMapParametersSchema>;
 /**

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

@@ -4,6 +4,7 @@ import type { IContentGenerator } from '../../core/interfaces/i-content-generato
 import type { ICurateService } from '../../core/interfaces/i-curate-service.js';
 import type { IFileSystem } from '../../core/interfaces/i-file-system.js';
 import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
+import type { ISwarmCoordinator } from '../../core/interfaces/i-swarm-coordinator.js';
 import type { SessionManager } from '../session/session-manager.js';
 import type { ISearchKnowledgeService } from './tools-sdk.js';
 /**
@@ -31,6 +32,8 @@ export declare class SandboxService implements ISandboxService {
     private searchKnowledgeService?;
     /** Session manager for sub-agent delegation via tools.agentQuery() */
     private sessionManager?;
+    /** Swarm coordinator for cross-provider query and store */
+    private swarmCoordinator?;
     /**
      * Clean up all resources (called on agent shutdown).
      */
@@ -110,6 +113,13 @@ export declare class SandboxService implements ISandboxService {
      * @param sessionManager - Session manager instance
      */
     setSessionManager(sessionManager: SessionManager): void;
+    /**
+     * Set the swarm coordinator for cross-provider query and store.
+     * When set, sandboxes will have access to `tools.swarmQuery()` and `tools.swarmStore()`.
+     *
+     * @param swarmCoordinator - Swarm coordinator instance
+     */
+    setSwarmCoordinator(swarmCoordinator: ISwarmCoordinator): void;
     /**
      * Build a Tools SDK instance for a specific session.
      * Includes `agentQuery` bound to the session's ID for sub-agent delegation.

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

@@ -26,6 +26,8 @@ export class SandboxService {
     searchKnowledgeService;
     /** Session manager for sub-agent delegation via tools.agentQuery() */
     sessionManager;
+    /** Swarm coordinator for cross-provider query and store */
+    swarmCoordinator;
     /**
      * Clean up all resources (called on agent shutdown).
      */
@@ -201,6 +203,16 @@ export class SandboxService {
     setSessionManager(sessionManager) {
         this.sessionManager = sessionManager;
     }
+    /**
+     * Set the swarm coordinator for cross-provider query and store.
+     * When set, sandboxes will have access to `tools.swarmQuery()` and `tools.swarmStore()`.
+     *
+     * @param swarmCoordinator - Swarm coordinator instance
+     */
+    setSwarmCoordinator(swarmCoordinator) {
+        this.swarmCoordinator = swarmCoordinator;
+        this.invalidateSandboxes();
+    }
     /**
      * Build a Tools SDK instance for a specific session.
      * Includes `agentQuery` bound to the session's ID for sub-agent delegation.
@@ -219,6 +231,7 @@ export class SandboxService {
             sandboxService: this,
             searchKnowledgeService: this.searchKnowledgeService,
             sessionManager: this.sessionManager,
+            swarmCoordinator: this.swarmCoordinator,
         });
     }
     /**