byterover-cli 3.3.0 → 3.4.0

package/dist/agent/infra/sandbox/tools-sdk.d.ts

@@ -3,6 +3,7 @@ import type { IContentGenerator } from '../../core/interfaces/i-content-generato
 import type { CurateOperation, CurateOptions, CurateResult, DetectDomainsInput, DetectDomainsResult, 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 ChunkResult, type CurationFact, type MessageBoundary, type ReconResult } from './curation-helpers.js';
 /**
@@ -210,6 +211,28 @@ export interface ToolsSDK {
      * @returns Promise resolving to search results
      */
     searchKnowledge(query: string, options?: SearchKnowledgeOptions): Promise<SearchKnowledgeResult>;
+    /**
+     * Search across all active swarm memory providers.
+     * Available in both query and curate modes (read operation).
+     * @param query - Natural language search query
+     * @param options - Optional limit and scope
+     * @returns Promise resolving to ranked results from all active providers
+     */
+    swarmQuery(query: string, options?: {
+        limit?: number;
+        scope?: string;
+    }): Promise<unknown>;
+    /**
+     * Store knowledge in a swarm provider (GBrain, local markdown).
+     * Disabled in query (read-only) mode.
+     * @param request - Store request with content, optional contentType and provider
+     * @returns Promise resolving to store result with provider ID and latency
+     */
+    swarmStore(request: {
+        content: string;
+        contentType?: 'entity' | 'general' | 'note';
+        provider?: string;
+    }): Promise<unknown>;
     /**
      * Write content to a file.
      * @param filePath - Absolute path where the file should be written
@@ -241,6 +264,8 @@ export interface CreateToolsSDKOptions {
     searchKnowledgeService?: ISearchKnowledgeService;
     /** Session manager for sub-agent delegation (required for agentQuery) */
     sessionManager?: SessionManager;
+    /** Swarm coordinator for cross-provider query and store (optional) */
+    swarmCoordinator?: ISwarmCoordinator;
 }
 /**
  * Creates a Tools SDK instance for sandbox code execution.

package/dist/agent/infra/sandbox/tools-sdk.js

@@ -12,7 +12,7 @@ import { chunk, dedup, detectMessageBoundaries, groupBySubject, recon, recordPro
  * @returns ToolsSDK instance ready to be injected into sandbox context
  */
 export function createToolsSDK(options) {
-    const { commandType, contentGenerator, curateService, fileSystem, parentSessionId, projectRoot, sandboxService, searchKnowledgeService, sessionManager } = options;
+    const { commandType, contentGenerator, curateService, fileSystem, parentSessionId, projectRoot, sandboxService, searchKnowledgeService, sessionManager, swarmCoordinator } = options;
     const isReadOnly = commandType === 'query';
     return {
         async agentQuery(prompt, options) {
@@ -153,6 +153,29 @@ export function createToolsSDK(options) {
             }
             return searchKnowledgeService.search(query, options);
         },
+        async swarmQuery(query, queryOptions) {
+            if (!swarmCoordinator) {
+                throw new Error('Swarm query not available — no swarm coordinator configured.');
+            }
+            return swarmCoordinator.execute({
+                maxResults: queryOptions?.limit,
+                query,
+                scope: queryOptions?.scope,
+            });
+        },
+        async swarmStore(request) {
+            if (isReadOnly) {
+                throw new Error('swarmStore() is disabled in read-only (query) mode');
+            }
+            if (!swarmCoordinator) {
+                throw new Error('Swarm store not available — no swarm coordinator configured.');
+            }
+            return swarmCoordinator.store({
+                content: request.content,
+                contentType: request.contentType,
+                provider: request.provider,
+            });
+        },
         async writeFile(filePath, content, options) {
             if (isReadOnly) {
                 throw new Error('writeFile() is disabled in read-only (query) mode');

package/dist/agent/infra/swarm/adapters/byterover-adapter.d.ts

@@ -0,0 +1,39 @@
+import type { CostEstimate, HealthStatus, MemoryEntry, ProviderCapabilities, QueryRequest, QueryResult, StoreResult } from '../../../core/domain/swarm/types.js';
+import type { IMemoryProvider } from '../../../core/interfaces/i-memory-provider.js';
+/**
+ * Minimal interface for the search service dependency.
+ * Matches SearchKnowledgeService.search() signature.
+ */
+export interface SearchService {
+    search(query: string, options?: {
+        limit?: number;
+        scope?: string;
+    }): Promise<{
+        results: Array<{
+            excerpt: string;
+            path: string;
+            score: number;
+            title: string;
+        }>;
+        totalFound: number;
+    }>;
+}
+/**
+ * ByteRover adapter — wraps the existing SearchKnowledgeService
+ * behind the IMemoryProvider interface.
+ *
+ * Always active (built-in). Uses BM25 keyword search over the context-tree.
+ */
+export declare class ByteRoverAdapter implements IMemoryProvider {
+    private readonly searchService;
+    readonly capabilities: ProviderCapabilities;
+    readonly id = "byterover";
+    readonly type: "byterover";
+    constructor(searchService: SearchService);
+    delete(_id: string): Promise<void>;
+    estimateCost(_request: QueryRequest): CostEstimate;
+    healthCheck(): Promise<HealthStatus>;
+    query(request: QueryRequest): Promise<QueryResult[]>;
+    store(_entry: MemoryEntry): Promise<StoreResult>;
+    update(_id: string, _entry: Partial<MemoryEntry>): Promise<void>;
+}

package/dist/agent/infra/swarm/adapters/byterover-adapter.js

@@ -0,0 +1,62 @@
+/**
+ * ByteRover adapter — wraps the existing SearchKnowledgeService
+ * behind the IMemoryProvider interface.
+ *
+ * Always active (built-in). Uses BM25 keyword search over the context-tree.
+ */
+export class ByteRoverAdapter {
+    searchService;
+    capabilities = {
+        avgLatencyMs: 50,
+        graphTraversal: false,
+        keywordSearch: true,
+        localOnly: true,
+        maxTokensPerQuery: 8000,
+        semanticSearch: false,
+        temporalQuery: false,
+        userModeling: false,
+        writeSupported: false,
+    };
+    id = 'byterover';
+    type = 'byterover';
+    constructor(searchService) {
+        this.searchService = searchService;
+    }
+    async delete(_id) {
+        throw new Error('ByteRover delete not implemented — use curate tool directly.');
+    }
+    estimateCost(_request) {
+        return {
+            estimatedCostCents: 0,
+            estimatedLatencyMs: this.capabilities.avgLatencyMs,
+            estimatedTokens: 0,
+        };
+    }
+    async healthCheck() {
+        return { available: true };
+    }
+    async query(request) {
+        const searchResult = await this.searchService.search(request.query, {
+            limit: request.maxResults,
+            scope: request.scope,
+        });
+        return searchResult.results.map((result, index) => ({
+            content: result.excerpt,
+            id: `brv-${index}`,
+            metadata: {
+                matchType: 'keyword',
+                path: result.path,
+                source: result.path,
+            },
+            provider: 'byterover',
+            providerType: 'byterover',
+            score: result.score,
+        }));
+    }
+    async store(_entry) {
+        throw new Error('ByteRover store not implemented — use curate tool directly.');
+    }
+    async update(_id, _entry) {
+        throw new Error('ByteRover update not implemented — use curate tool directly.');
+    }
+}

package/dist/agent/infra/swarm/adapters/gbrain-adapter.d.ts

@@ -0,0 +1,63 @@
+import type { CostEstimate, HealthStatus, MemoryEntry, ProviderCapabilities, QueryRequest, QueryResult, StoreResult } from '../../../core/domain/swarm/types.js';
+import type { IMemoryProvider } from '../../../core/interfaces/i-memory-provider.js';
+/**
+ * Options for the GBrain adapter.
+ */
+export interface GBrainAdapterOptions {
+    /** Explicit path to the gbrain binary or .ts entrypoint. Auto-resolved if omitted. */
+    gbrainBinPath?: string;
+    /** Path to the brain repo (also used to find local gbrain installation) */
+    repoPath: string;
+    /** Search mode: hybrid (default), keyword, or vector */
+    searchMode: 'hybrid' | 'keyword' | 'vector';
+}
+/**
+ * Executor function type for running gbrain CLI operations.
+ * Abstracted for testability — tests inject a mock, production uses execGbrain().
+ */
+export type GBrainExecutor = (operation: string, params: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Resolve the gbrain binary path.
+ *
+ * Search order:
+ * 1. Explicit `gbrainBinPath` from options
+ * 2. `gbrain` in PATH (globally installed)
+ * 3. `src/cli.ts` in `repoPath` (local Bun clone — repoPath IS the source checkout)
+ * 4. `src/cli.ts` in common workspace siblings (../gbrain relative to cwd)
+ */
+export declare function resolveGBrainBin(options: GBrainAdapterOptions): {
+    argsPrefix: string[];
+    command: string;
+};
+/**
+ * GBrain adapter — queries a GBrain knowledge brain via CLI subprocess.
+ *
+ * Supports three search modes:
+ * - hybrid (default): vector + keyword + RRF + multi-query expansion
+ * - keyword: full-text search only (no API key needed)
+ * - vector: vector search without expansion
+ */
+export declare class GBrainAdapter implements IMemoryProvider {
+    readonly capabilities: ProviderCapabilities;
+    readonly id = "gbrain";
+    readonly type: "gbrain";
+    private cachedExecutor?;
+    private readonly injectedExecutor?;
+    private readonly options;
+    private readonly repoPath;
+    private readonly searchMode;
+    constructor(options: GBrainAdapterOptions, executor?: GBrainExecutor);
+    private get executor();
+    delete(id: string): Promise<void>;
+    estimateCost(_request: QueryRequest): CostEstimate;
+    healthCheck(): Promise<HealthStatus>;
+    query(request: QueryRequest): Promise<QueryResult[]>;
+    store(entry: MemoryEntry): Promise<StoreResult>;
+    update(id: string, entry: Partial<MemoryEntry>): Promise<void>;
+    /**
+     * Normalize scores to 0-1 range.
+     * - Hybrid/RRF scores are already in 0-1 range (sum of 1/(60+rank))
+     * - Keyword ts_rank scores can exceed 1 — normalize with score/(1+score)
+     */
+    private normalizeScore;
+}

package/dist/agent/infra/swarm/adapters/gbrain-adapter.js

@@ -0,0 +1,209 @@
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Default timeout for gbrain subprocess calls.
+ * PGLite WASM startup via Node execFile is significantly slower than interactive shell
+ * (cold-start ~60s for writes vs <1s for reads). 120s covers worst-case write operations.
+ */
+const EXEC_TIMEOUT_MS = 120_000;
+/**
+ * Resolve the gbrain binary path.
+ *
+ * Search order:
+ * 1. Explicit `gbrainBinPath` from options
+ * 2. `gbrain` in PATH (globally installed)
+ * 3. `src/cli.ts` in `repoPath` (local Bun clone — repoPath IS the source checkout)
+ * 4. `src/cli.ts` in common workspace siblings (../gbrain relative to cwd)
+ */
+export function resolveGBrainBin(options) {
+    // 1. Explicit path
+    if (options.gbrainBinPath) {
+        if (options.gbrainBinPath.endsWith('.ts')) {
+            return { argsPrefix: ['run', options.gbrainBinPath], command: 'bun' };
+        }
+        return { argsPrefix: [], command: options.gbrainBinPath };
+    }
+    // 2. Check PATH (sync probe — runs lazily on first executor access, not at construction)
+    try {
+        execFileSync('gbrain', ['--version'], { encoding: 'utf8', stdio: 'pipe', timeout: 5000 });
+        return { argsPrefix: [], command: 'gbrain' };
+    }
+    catch {
+        // Not in PATH — continue to fallback
+    }
+    // 3. Local clone at repoPath
+    const localScript = join(options.repoPath, 'src', 'cli.ts');
+    if (existsSync(localScript)) {
+        return { argsPrefix: ['run', localScript], command: 'bun' };
+    }
+    // 4. Common workspace siblings — look for ../gbrain relative to cwd
+    const workspaceSibling = join(process.cwd(), '..', 'gbrain', 'src', 'cli.ts');
+    if (existsSync(workspaceSibling)) {
+        return { argsPrefix: ['run', workspaceSibling], command: 'bun' };
+    }
+    // 5. Fallback — try 'gbrain' anyway (will fail with ENOENT at runtime)
+    return { argsPrefix: [], command: 'gbrain' };
+}
+/**
+ * Execute a gbrain CLI operation via subprocess.
+ * Runs: <command> [argsPrefix...] call <operation> '<json params>'
+ */
+function createDefaultExecutor(resolved) {
+    return (operation, params) => new Promise((resolve, reject) => {
+        const jsonArgs = JSON.stringify(params);
+        const args = [...resolved.argsPrefix, 'call', operation, jsonArgs];
+        execFile(resolved.command, args, { encoding: 'utf8', timeout: EXEC_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (error) {
+                const message = stderr?.trim() || error.message;
+                reject(new Error(`gbrain ${operation} failed: ${message}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                reject(new Error(`gbrain ${operation} returned invalid JSON: ${stdout.slice(0, 200)}`));
+            }
+        });
+    });
+}
+/**
+ * Derive a slug from content for gbrain page creation.
+ * Extracts title from first heading or uses timestamp fallback.
+ */
+function deriveSlug(content) {
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch?.[1] ?? `note-${Date.now()}`;
+    const slug = title
+        .toLowerCase()
+        .replaceAll(/[^\w\s-]/g, '')
+        .replaceAll(/\s+/g, '-')
+        .replaceAll(/-+/g, '-')
+        .replaceAll(/^-+|-+$/g, '');
+    return `concept/${slug || `note-${Date.now()}`}`;
+}
+/**
+ * GBrain adapter — queries a GBrain knowledge brain via CLI subprocess.
+ *
+ * Supports three search modes:
+ * - hybrid (default): vector + keyword + RRF + multi-query expansion
+ * - keyword: full-text search only (no API key needed)
+ * - vector: vector search without expansion
+ */
+export class GBrainAdapter {
+    capabilities = {
+        avgLatencyMs: 300,
+        graphTraversal: false,
+        keywordSearch: true,
+        localOnly: false,
+        maxTokensPerQuery: 10_000,
+        semanticSearch: true,
+        temporalQuery: true,
+        userModeling: false,
+        writeSupported: true,
+    };
+    id = 'gbrain';
+    type = 'gbrain';
+    cachedExecutor;
+    injectedExecutor;
+    options;
+    repoPath;
+    searchMode;
+    constructor(options, executor) {
+        this.repoPath = options.repoPath;
+        this.searchMode = options.searchMode;
+        this.options = options;
+        this.injectedExecutor = executor;
+    }
+    get executor() {
+        if (this.injectedExecutor)
+            return this.injectedExecutor;
+        this.cachedExecutor ??= createDefaultExecutor(resolveGBrainBin(this.options));
+        return this.cachedExecutor;
+    }
+    async delete(id) {
+        await this.executor('delete_page', { slug: id });
+    }
+    estimateCost(_request) {
+        // Keyword mode is free (no embedding API call)
+        // Hybrid/vector use OpenAI embedding (~$0.001 per query)
+        const costCents = this.searchMode === 'keyword' ? 0 : 0.1;
+        return {
+            estimatedCostCents: costCents,
+            estimatedLatencyMs: this.capabilities.avgLatencyMs,
+            estimatedTokens: 0,
+        };
+    }
+    async healthCheck() {
+        if (!existsSync(this.repoPath)) {
+            return {
+                available: false,
+                error: `GBrain repo not found at ${this.repoPath}`,
+            };
+        }
+        try {
+            await this.executor('get_stats', {});
+            return { available: true };
+        }
+        catch (error) {
+            return {
+                available: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async query(request) {
+        const limit = request.maxResults ?? 10;
+        let results;
+        switch (this.searchMode) {
+            case 'keyword': {
+                results = await this.executor('search', { limit, query: request.query });
+                break;
+            }
+            case 'vector': {
+                results = await this.executor('query', { expand: false, limit, query: request.query });
+                break;
+            }
+            default: {
+                // hybrid
+                results = await this.executor('query', { expand: true, limit, query: request.query });
+            }
+        }
+        return results.map((r) => ({
+            content: r.chunk_text,
+            id: r.slug,
+            metadata: {
+                matchType: this.searchMode === 'keyword' ? 'keyword' : 'semantic',
+                path: r.slug,
+                source: r.slug,
+            },
+            provider: 'gbrain',
+            providerType: 'gbrain',
+            score: this.normalizeScore(r.score),
+        }));
+    }
+    async store(entry) {
+        const slug = deriveSlug(entry.content);
+        const content = `---\ntype: concept\ntitle: ${entry.content.match(/^#\s+(.+)$/m)?.[1] ?? slug}\n---\n${entry.content}`;
+        await this.executor('put_page', { content, slug });
+        return { id: slug, provider: 'gbrain', success: true };
+    }
+    async update(id, entry) {
+        if (!entry.content)
+            return;
+        const content = `---\ntype: concept\ntitle: ${entry.content.match(/^#\s+(.+)$/m)?.[1] ?? id}\n---\n${entry.content}`;
+        await this.executor('put_page', { content, slug: id });
+    }
+    /**
+     * Normalize scores to 0-1 range.
+     * - Hybrid/RRF scores are already in 0-1 range (sum of 1/(60+rank))
+     * - Keyword ts_rank scores can exceed 1 — normalize with score/(1+score)
+     */
+    normalizeScore(score) {
+        if (this.searchMode === 'keyword' && score > 1) {
+            return score / (1 + score);
+        }
+        return Math.min(score, 1);
+    }
+}

package/dist/agent/infra/swarm/adapters/local-markdown-adapter.d.ts

@@ -0,0 +1,41 @@
+import type { CostEstimate, HealthStatus, MemoryEntry, ProviderCapabilities, QueryRequest, QueryResult, StoreResult } from '../../../core/domain/swarm/types.js';
+import type { IMemoryProvider } from '../../../core/interfaces/i-memory-provider.js';
+/**
+ * Options for LocalMarkdownAdapter behavior.
+ */
+export interface LocalMarkdownAdapterOptions {
+    /** Whether to follow [[wikilinks]] for graph expansion (default: true) */
+    followWikilinks?: boolean;
+    /** Whether the folder is read-only (default: false) */
+    readOnly?: boolean;
+    /** Whether to rescan files on each query (default: true). When false, the index is built once and frozen. */
+    watchForChanges?: boolean;
+}
+/**
+ * Local markdown folder adapter — indexes .md files via MiniSearch,
+ * optionally follows [[wikilinks]] one hop, supports write unless read-only.
+ *
+ * Each folder instance has a unique id: `local-markdown:{name}`.
+ */
+export declare class LocalMarkdownAdapter implements IMemoryProvider {
+    private readonly folderPath;
+    private readonly name;
+    readonly capabilities: ProviderCapabilities;
+    readonly id: string;
+    readonly type: "local-markdown";
+    private documents;
+    private readonly followWikilinks;
+    private index?;
+    private indexSignature?;
+    private pathToDoc;
+    private readonly readOnly;
+    private readonly watchForChanges;
+    constructor(folderPath: string, name: string, options?: LocalMarkdownAdapterOptions);
+    delete(_id: string): Promise<void>;
+    estimateCost(_request: QueryRequest): CostEstimate;
+    healthCheck(): Promise<HealthStatus>;
+    query(request: QueryRequest): Promise<QueryResult[]>;
+    store(entry: MemoryEntry): Promise<StoreResult>;
+    update(_id: string, _entry: Partial<MemoryEntry>): Promise<void>;
+    private ensureIndex;
+}