byterover-cli 1.0.4 → 1.1.0

package/dist/infra/cipher/tools/implementations/curate-tool.js

@@ -1,4 +1,3 @@
-import * as fs from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
@@ -10,14 +9,43 @@ import { toSnakeCase } from '../../../../utils/file-helpers.js';
  * Inspired by ACE Curator patterns.
  */
 const OperationType = z.enum(['ADD', 'UPDATE', 'MERGE', 'DELETE']);
+/**
+ * Raw Concept schema for structured metadata and technical footprint.
+ */
+const RawConceptSchema = z.object({
+    changes: z.array(z.string()).optional().describe('What changes in the codebase are induced by this concept'),
+    files: z.array(z.string()).optional().describe('Which files are related to this concept'),
+    flow: z.string().optional().describe('What is the flow included in this concept'),
+    task: z.string().optional().describe('What is the task related to this concept'),
+    timestamp: z
+        .string()
+        .optional()
+        .describe('When the concept was created or modified (ISO 8601 format, e.g., 2025-03-18)'),
+});
+/**
+ * Narrative schema for descriptive and structural context.
+ */
+const NarrativeSchema = z.object({
+    dependencies: z
+        .string()
+        .optional()
+        .describe('Dependency management information (e.g., "Singleton, init when service starts, hard dependency in smoke test")'),
+    features: z
+        .string()
+        .optional()
+        .describe('Feature documentation for this concept (e.g., "User permission can be stale for up to 300 seconds due to Redis cache")'),
+    structure: z.string().optional().describe('Code structure documentation (e.g., "clients/redis_client.go")'),
+});
 /**
  * Content structure for ADD and UPDATE operations.
  */
 const ContentSchema = z.object({
+    narrative: NarrativeSchema.optional().describe('Narrative section with descriptive and structural context'),
+    rawConcept: RawConceptSchema.optional().describe('Raw concept section with metadata and technical footprint'),
     relations: z
         .array(z.string())
         .optional()
-        .describe('Related topics using domain/topic or domain/topic/subtopic notation'),
+        .describe('Related topics using domain/topic/title.md or domain/topic/subtopic/title.md notation'),
     snippets: z.array(z.string()).optional().describe('Code/text snippets'),
 });
 /**
@@ -27,9 +55,12 @@ const OperationSchema = z.object({
     content: ContentSchema.optional().describe('Content for ADD/UPDATE operations'),
     mergeTarget: z.string().optional().describe('Target path for MERGE operation'),
     mergeTargetTitle: z.string().optional().describe('Title of the target file for MERGE operation'),
-    path: z.string().describe('Path: domain/topic or domain/topic/subtopic'),
+    path: z.string().describe('Path: domain/topic/title.md or domain/topic/subtopic/title.md'),
     reason: z.string().describe('Reasoning for this operation'),
-    title: z.string().optional().describe('Title for the context file (saved as {title}.md in snake_case). Required for ADD/UPDATE/MERGE, optional for DELETE'),
+    title: z
+        .string()
+        .optional()
+        .describe('Title for the context file (saved as {title}.md in snake_case). Required for ADD/UPDATE/MERGE, optional for DELETE'),
     type: OperationType.describe('Operation type: ADD, UPDATE, MERGE, or DELETE'),
 });
 /**
@@ -53,33 +84,17 @@ function parsePath(path) {
         topic: parts[1],
     };
 }
-/**
- * Get existing domain names from the context tree.
- * Returns domain folder names that exist in the context tree.
- */
-async function getExistingDomains(basePath) {
-    try {
-        const entries = await fs.readdir(basePath, { withFileTypes: true });
-        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-    }
-    catch {
-        // Directory doesn't exist yet
-        return [];
-    }
-}
 /**
  * Validate domain name format.
  * Dynamic domains are allowed - no predefined list or limits.
  * The agent is responsible for creating semantically meaningful domains.
  */
-async function validateDomain(basePath, domainName) {
+function validateDomain(domainName) {
     const normalizedDomain = toSnakeCase(domainName);
-    const existingDomains = await getExistingDomains(basePath);
     // Validate domain name format (must be non-empty and valid for filesystem)
     if (!normalizedDomain || normalizedDomain.length === 0) {
         return {
             allowed: false,
-            existingDomains,
             reason: 'Domain name cannot be empty.',
         };
     }
@@ -87,12 +102,11 @@ async function validateDomain(basePath, domainName) {
     if (!/^[\w-]+$/.test(normalizedDomain)) {
         return {
             allowed: false,
-            existingDomains,
             reason: `Domain name "${normalizedDomain}" contains invalid characters. Use only letters, numbers, underscores, and hyphens.`,
         };
     }
     // All valid domain names are allowed - dynamic domain creation enabled
-    return { allowed: true, existingDomains };
+    return { allowed: true };
 }
 /**
  * Build the full filesystem path from base path and knowledge path.
@@ -142,7 +156,7 @@ async function executeAdd(basePath, operation) {
             };
         }
         // Validate domain before creating
-        const domainValidation = await validateDomain(basePath, parsed.domain);
+        const domainValidation = validateDomain(parsed.domain);
         if (!domainValidation.allowed) {
             return {
                 message: domainValidation.reason,
@@ -159,8 +173,10 @@ async function executeAdd(basePath, operation) {
         // Note: writeFileAtomic creates parent directories as needed, avoiding empty folder creation
         const contextContent = MarkdownWriter.generateContext({
             name: title,
+            narrative: content.narrative,
+            rawConcept: content.rawConcept,
             relations: content.relations,
-            snippets: content.snippets || [],
+            snippets: content.snippets ?? [],
         });
         const filename = `${toSnakeCase(title)}.md`;
         const contextPath = join(finalPath, filename);
@@ -220,8 +236,10 @@ async function executeUpdate(basePath, operation) {
         // Generate and write updated content (full replacement)
         const contextContent = MarkdownWriter.generateContext({
             name: title,
+            narrative: content.narrative,
+            rawConcept: content.rawConcept,
             relations: content.relations,
-            snippets: content.snippets || [],
+            snippets: content.snippets ?? [],
         });
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         return {
@@ -381,7 +399,27 @@ async function executeDelete(basePath, operation) {
  * Execute curate operations on knowledge topics.
  */
 async function executeCurate(input, _context) {
-    const { basePath, operations } = input;
+    const parseResult = CurateInputSchema.safeParse(input);
+    if (!parseResult.success) {
+        return {
+            applied: [
+                {
+                    message: `Invalid input: ${parseResult.error.message}`,
+                    path: '',
+                    status: 'failed',
+                    type: 'ADD',
+                },
+            ],
+            summary: {
+                added: 0,
+                deleted: 0,
+                failed: 1,
+                merged: 0,
+                updated: 0,
+            },
+        };
+    }
+    const { basePath, operations } = parseResult.data;
     const applied = [];
     const summary = {
         added: 0,
@@ -420,8 +458,10 @@ async function executeCurate(input, _context) {
                 break;
             }
             default: {
+                // Exhaustive type check - TypeScript will error if any case is missed
+                const exhaustiveCheck = operation.type;
                 result = {
-                    message: `Unknown operation type: ${operation.type}`,
+                    message: `Unknown operation type: ${exhaustiveCheck}`,
                     path: operation.path,
                     status: 'failed',
                     type: operation.type,
@@ -446,30 +486,84 @@ async function executeCurate(input, _context) {
  */
 export function createCurateTool() {
     return {
-        description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types:
+        description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types and supports a two-part context model: Raw Concept + Narrative.
+
+**Content Structure (Two-Part Model):**
+- **rawConcept**: Captures essential metadata and technical footprint
+  - task: What is the task related to this concept
+  - changes: Array of changes induced in the codebase
+  - files: Array of related files
+  - flow: The execution flow of this concept
+  - timestamp: When created/modified (ISO 8601 format)
+- **narrative**: Captures descriptive and structural context
+  - structure: Code structure documentation
+  - dependencies: Dependency management information
+  - features: Feature documentation
+- **snippets**: Code/text snippets (legacy support)
+- **relations**: Related topics using @domain/topic notation
 
 **Operations:**
 1. **ADD** - Create new titled context file in domain/topic/subtopic
    - Requires: path, title, content (snippets and/or relations), reason
-   - Example: { type: "ADD", path: "code_style/error_handling", title: "Best Practices", content: { snippets: ["..."], relations: ["logging/basics"] }, reason: "New pattern" }
-   - Creates: code_style/error_handling/best_practices.md
+   - Relations must be in the format of "domain/topic/title.md" or "domain/topic/subtopic/title.md"
+   - Example with Raw Concept + Narrative:
+     {
+       type: "ADD",
+       path: "structure/caching",
+       title: "Redis User Permissions",
+       content: {
+         rawConcept: {
+           task: "Introduce Redis cache for getUserPermissions(userId)",
+           changes: ["Cached result using remote Redis", "Redis client: singleton"],
+           files: ["services/permission_service.go", "clients/redis_client.go"],
+           flow: "getUserPermissions -> check Redis -> on miss query DB -> store result -> return",
+           timestamp: "2025-03-18"
+         },
+         narrative: {
+           structure: "# Redis client\\n- clients/redis_client.go",
+           dependencies: "# Redis client\\n- Singleton, init when service starts",
+           features: "# Authorization\\n- User permission can be stale for up to 300 seconds"
+         },
+         relations: ["structure/api-endpoints/validation.md", "structure/api-endpoints/error-handling/retry-logic.md"]
+       },
+       reason: "New caching pattern"
+     }
+   - Creates: structure/caching/redis_user_permissions.md
 
 2. **UPDATE** - Modify existing titled context file (full replacement)
    - Requires: path, title, content, reason
-   - Example: { type: "UPDATE", path: "code_style/error_handling", title: "Best Practices", content: { snippets: ["Updated"] }, reason: "Improved" }
+   - Relations must be in the format of "domain/topic/title.md" or "domain/topic/subtopic/title.md"
+   - Supports same content structure as ADD
 
 3. **MERGE** - Combine source file into target file, delete source
    - Requires: path (source), title (source file), mergeTarget (destination path), mergeTargetTitle (destination file), reason
    - Example: { type: "MERGE", path: "code_style/old_topic", title: "Old Guide", mergeTarget: "code_style/new_topic", mergeTargetTitle: "New Guide", reason: "Consolidating" }
+   - Raw concepts and narratives are intelligently merged
 
 4. **DELETE** - Remove specific file or entire folder
    - Requires: path, title (optional), reason
    - With title: deletes specific file; without title: deletes entire folder
-   - Example (file): { type: "DELETE", path: "code_style/deprecated", title: "Old Guide", reason: "No longer relevant" }
-   - Example (folder): { type: "DELETE", path: "code_style/deprecated", title: "", reason: "Removing topic" }
 
-**Path format:** domain/topic or domain/topic/subtopic (uses snake_case automatically)
-**File naming:** Titles are converted to snake_case (e.g., "Best Practices" -> "best_practices.md")
+**CRITICAL - Path vs Title separation:**
+- "path" = folder location only (domain/topic or domain/topic/subtopic) - NEVER include file extension suffixes 
+- "title" = the context name (becomes {title}.md file automatically)
+- The system auto-generates the .md file from title - DO NOT put .md or _md anywhere in path
+
+**Path format:** domain/topic OR domain/topic/subtopic (2-3 segments, NO filename, NO extension)
+**File naming:** Title is auto-converted to snake_case and .md is auto-appended (e.g., title "Best Practices" -> best_practices.md)
+
+**Good path examples:**
+- path: "authentication/jwt", title: "Token Refresh" -> creates authentication/jwt/token_refresh.md
+- path: "api_design/error_handling", title: "Retry Logic" -> creates api_design/error_handling/retry_logic.md
+- path: "database/migrations/versioning", title: "Schema Changes" -> creates database/migrations/versioning/schema_changes.md
+
+**Bad path examples (NEVER DO THIS):**
+- "code_style/error_handling_md" - WRONG: _md suffix in path
+- "code_style/error_handling.md" - WRONG: .md extension in path
+- "authentication/jwt/token_refresh.md" - WRONG: filename in path (use title parameter instead)
+- "authentication/jwt/token_refresh_md" - WRONG: _md suffix (this is NOT how to specify filename)
+- "api/auth/jwt/tokens" - WRONG: 4 levels deep (max 3 allowed)
+- "a/b" - WRONG: too vague, use descriptive names
 
 **Dynamic Domain Creation:**
 - Domains are created dynamically based on the context being curated
@@ -485,6 +579,8 @@ export function createCurateTool() {
 - Avoid overly specific names that only fit one topic
 - Keep domain count reasonable by consolidating related concepts
 
+**Backward Compatibility:** Existing context entries using only snippets and relations continue to work.
+
 **Output:** Returns applied operations with status (success/failed), filePath (for created/modified files), and a summary of counts.`,
         execute: executeCurate,
         id: ToolName.CURATE,

package/dist/infra/cipher/tools/implementations/read-file-tool.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+import { isImageFile } from '../../file-system/binary-utils.js';
 /**
  * Input schema for read file tool.
  */
@@ -31,23 +32,43 @@ export function createReadFileTool(fileSystemService) {
         description: 'Read the contents of a file. Supports relative/absolute paths, pagination, and returns images/PDFs as base64 attachments.',
         async execute(input, _context) {
             const { filePath, limit, offset } = input;
-            // Call file system service
-            const result = await fileSystemService.readFile(filePath, {
-                limit,
-                offset,
-            });
-            // Return formatted result with all metadata
-            return {
-                attachment: result.attachment,
-                content: result.formattedContent,
-                lines: result.lines,
-                message: result.message,
-                preview: result.preview,
-                size: result.size,
-                totalLines: result.totalLines,
-                truncated: result.truncated,
-                truncatedLineCount: result.truncatedLineCount,
-            };
+            try {
+                // Call file system service
+                const result = await fileSystemService.readFile(filePath, {
+                    limit,
+                    offset,
+                });
+                // Transform attachment format (singular → plural array)
+                let attachments;
+                if (result.attachment) {
+                    const type = isImageFile(filePath) ? 'image' : 'file';
+                    attachments = [{
+                            data: result.attachment.base64,
+                            filename: result.attachment.fileName,
+                            mimeType: result.attachment.mimeType,
+                            type,
+                        }];
+                }
+                // Return formatted result with all metadata
+                return {
+                    attachments,
+                    content: result.formattedContent,
+                    lines: result.lines,
+                    message: result.message,
+                    preview: result.preview,
+                    size: result.size,
+                    success: true,
+                    totalLines: result.totalLines,
+                    truncated: result.truncated,
+                    truncatedLineCount: result.truncatedLineCount,
+                };
+            }
+            catch (error) {
+                return {
+                    error: error instanceof Error ? error.message : String(error),
+                    success: false,
+                };
+            }
         },
         id: ToolName.READ_FILE,
         inputSchema: ReadFileInputSchema,

package/dist/infra/cipher/tools/implementations/search-knowledge-tool.d.ts

@@ -0,0 +1,7 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../../core/interfaces/cipher/i-file-system.js';
+export interface SearchKnowledgeToolConfig {
+    baseDirectory?: string;
+    cacheTtlMs?: number;
+}
+export declare function createSearchKnowledgeTool(fileSystem: IFileSystem, config?: SearchKnowledgeToolConfig): Tool;

package/dist/infra/cipher/tools/implementations/search-knowledge-tool.js

@@ -0,0 +1,303 @@
+import MiniSearch from 'minisearch';
+import { join } from 'node:path';
+import { removeStopwords } from 'stopword';
+import { z } from 'zod';
+import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../../../constants.js';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+const MAX_CONTEXT_TREE_FILES = 10_000;
+const CACHE_TTL_MS = 5000;
+const MINISEARCH_OPTIONS = {
+    fields: ['title', 'content'],
+    idField: 'id',
+    searchOptions: {
+        boost: { title: 2 },
+        fuzzy: 0.2,
+        prefix: true,
+    },
+    storeFields: ['title', 'path'],
+};
+const SearchKnowledgeInputSchema = z
+    .object({
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(10)
+        .describe('Maximum number of results to return (default: 10)'),
+    query: z.string().min(1).describe('Natural language query string to search for in the knowledge base'),
+})
+    .strict();
+function filterStopWords(query) {
+    const words = query.toLowerCase().split(/\s+/);
+    const filtered = removeStopwords(words);
+    return filtered.length > 0 ? filtered.join(' ') : query;
+}
+function extractTitle(content, fallbackTitle) {
+    const match = /^# (.+)$/m.exec(content);
+    return match ? match[1].trim() : fallbackTitle;
+}
+function extractExcerpt(content, query, maxLength = 300) {
+    const relationsMatch = /^## Relations\n([\S\s]*?)(?=\n## |\n# |$)/m.exec(content);
+    let cleanContent = content;
+    if (relationsMatch) {
+        cleanContent = content.replace(relationsMatch[0], '').trim();
+    }
+    cleanContent = cleanContent.replace(/^# .+$/m, '').trim();
+    const queryTerms = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length >= 2);
+    const lines = cleanContent.split('\n');
+    let bestStartIndex = 0;
+    let bestScore = 0;
+    for (const [i, line] of lines.entries()) {
+        const lineLower = line.toLowerCase();
+        let score = 0;
+        for (const term of queryTerms) {
+            if (lineLower.includes(term)) {
+                score++;
+            }
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestStartIndex = i;
+        }
+    }
+    let excerpt = '';
+    for (const line of lines.slice(bestStartIndex)) {
+        if (excerpt.length >= maxLength)
+            break;
+        excerpt += line + '\n';
+    }
+    excerpt = excerpt.trim();
+    if (excerpt.length > maxLength) {
+        excerpt = excerpt.slice(0, maxLength).trim() + '...';
+    }
+    else if (bestStartIndex > 0 || excerpt.length < cleanContent.length) {
+        excerpt += '...';
+    }
+    return excerpt || cleanContent.slice(0, maxLength) + (cleanContent.length > maxLength ? '...' : '');
+}
+async function findMarkdownFilesWithMtime(fileSystem, contextTreePath) {
+    try {
+        const globResult = await fileSystem.globFiles(`**/*${CONTEXT_FILE_EXTENSION}`, {
+            cwd: contextTreePath,
+            includeMetadata: true,
+            maxResults: MAX_CONTEXT_TREE_FILES,
+            respectGitignore: false,
+        });
+        return globResult.files.map((f) => {
+            let relativePath = f.path;
+            if (f.path.startsWith(contextTreePath)) {
+                relativePath = f.path.slice(contextTreePath.length + 1);
+            }
+            return {
+                mtime: f.modified?.getTime() ?? 0,
+                path: relativePath,
+            };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function isCacheValid(cache, currentFiles) {
+    if (cache.fileMtimes.size !== currentFiles.length) {
+        return false;
+    }
+    for (const file of currentFiles) {
+        const cachedMtime = cache.fileMtimes.get(file.path);
+        if (cachedMtime === undefined || cachedMtime !== file.mtime) {
+            return false;
+        }
+    }
+    return true;
+}
+async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
+    const now = Date.now();
+    if (filesWithMtime.length === 0) {
+        const index = new MiniSearch(MINISEARCH_OPTIONS);
+        return {
+            contextTreePath,
+            documentMap: new Map(),
+            fileMtimes: new Map(),
+            index,
+            lastValidatedAt: now,
+        };
+    }
+    const documentPromises = filesWithMtime.map(async ({ mtime, path: filePath }) => {
+        try {
+            const fullPath = join(contextTreePath, filePath);
+            const { content } = await fileSystem.readFile(fullPath);
+            const title = extractTitle(content, filePath.replace(/\.md$/, '').split('/').pop() || filePath);
+            return {
+                content,
+                id: filePath,
+                mtime,
+                path: filePath,
+                title,
+            };
+        }
+        catch {
+            return null;
+        }
+    });
+    const results = await Promise.all(documentPromises);
+    const documents = results.filter((doc) => doc !== null);
+    const documentMap = new Map();
+    const fileMtimes = new Map();
+    for (const doc of documents) {
+        documentMap.set(doc.id, doc);
+        fileMtimes.set(doc.path, doc.mtime);
+    }
+    const index = new MiniSearch(MINISEARCH_OPTIONS);
+    index.addAll(documents);
+    return {
+        contextTreePath,
+        documentMap,
+        fileMtimes,
+        index,
+        lastValidatedAt: now,
+    };
+}
+/**
+ * Acquires the search index, using cached data when valid or building a fresh index.
+ * Uses promise-based locking to prevent duplicate builds during parallel execution.
+ *
+ * @param state - Mutable state object for caching and locking
+ * @param fileSystem - File system service
+ * @param contextTreePath - Path to the context tree directory
+ * @param ttlMs - Cache TTL in milliseconds
+ * @returns The cached index or an error result
+ */
+async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
+    const now = Date.now();
+    // Fast path: TTL-based cache hit (no I/O needed)
+    if (state.cachedIndex &&
+        state.cachedIndex.contextTreePath === contextTreePath &&
+        ttlMs > 0 &&
+        now - state.cachedIndex.lastValidatedAt < ttlMs) {
+        return state.cachedIndex;
+    }
+    // If another call is already building the index, wait for it
+    if (state.buildingPromise) {
+        return state.buildingPromise;
+    }
+    // Create and store the build promise SYNCHRONOUSLY before any await
+    // This prevents race conditions where multiple parallel calls all start building
+    const buildPromise = (async () => {
+        // Check if context tree exists (only if no cache or different path)
+        if (!state.cachedIndex || state.cachedIndex.contextTreePath !== contextTreePath) {
+            try {
+                await fileSystem.listDirectory(contextTreePath);
+            }
+            catch {
+                // Return empty index to signal error - caller will handle
+                const emptyIndex = new MiniSearch(MINISEARCH_OPTIONS);
+                return {
+                    contextTreePath: '',
+                    documentMap: new Map(),
+                    fileMtimes: new Map(),
+                    index: emptyIndex,
+                    lastValidatedAt: 0,
+                };
+            }
+        }
+        const currentFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
+        // Re-check cache validity after getting file list (another call may have finished)
+        if (state.cachedIndex &&
+            state.cachedIndex.contextTreePath === contextTreePath &&
+            isCacheValid(state.cachedIndex, currentFiles)) {
+            // Update timestamp atomically by creating a new object
+            const updatedCache = {
+                ...state.cachedIndex,
+                lastValidatedAt: Date.now(),
+            };
+            state.cachedIndex = updatedCache;
+            return updatedCache;
+        }
+        // Build fresh index
+        const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, currentFiles);
+        state.cachedIndex = freshIndex;
+        return freshIndex;
+    })();
+    // Store promise IMMEDIATELY (synchronously) so parallel calls can wait on it
+    state.buildingPromise = buildPromise;
+    try {
+        const result = await buildPromise;
+        // Check for error signal (empty contextTreePath means listDirectory failed)
+        if (result.contextTreePath === '') {
+            return {
+                error: true,
+                result: {
+                    message: 'Context tree not initialized. Run /init to create it.',
+                    results: [],
+                    totalFound: 0,
+                },
+            };
+        }
+        return result;
+    }
+    finally {
+        // Clear the lock after completion (success or failure)
+        state.buildingPromise = undefined;
+    }
+}
+export function createSearchKnowledgeTool(fileSystem, config = {}) {
+    // Shared state for caching and locking across parallel executions
+    const state = {
+        buildingPromise: undefined,
+        cachedIndex: undefined,
+    };
+    return {
+        description: 'Search the curated knowledge base in .brv/context-tree/ for relevant topics. ' +
+            'Use natural language queries to find knowledge about specific topics (e.g., "auth design", "API patterns"). ' +
+            'Returns matching file paths, titles, and relevant excerpts.',
+        async execute(input, _context) {
+            const { limit, query } = SearchKnowledgeInputSchema.parse(input);
+            const baseDir = config.baseDirectory ?? process.cwd();
+            const contextTreePath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+            const ttlMs = config.cacheTtlMs ?? CACHE_TTL_MS;
+            // Acquire index with parallel-safe locking
+            const indexResult = await acquireIndex(state, fileSystem, contextTreePath, ttlMs);
+            // Handle error case (context tree not initialized)
+            if ('error' in indexResult) {
+                return indexResult.result;
+            }
+            const { documentMap, index } = indexResult;
+            if (documentMap.size === 0) {
+                return {
+                    message: 'Context tree is empty. Use /curate to add knowledge.',
+                    results: [],
+                    totalFound: 0,
+                };
+            }
+            const filteredQuery = filterStopWords(query);
+            const searchResults = index.search(filteredQuery, { combineWith: 'OR' });
+            const results = [];
+            const resultLimit = Math.min(limit, searchResults.length);
+            for (let i = 0; i < resultLimit; i++) {
+                const result = searchResults[i];
+                const document = documentMap.get(result.id);
+                if (document) {
+                    results.push({
+                        excerpt: extractExcerpt(document.content, query),
+                        path: document.path,
+                        score: Math.round(result.score * 100) / 100,
+                        title: document.title,
+                    });
+                }
+            }
+            return {
+                message: results.length > 0
+                    ? `Found ${searchResults.length} result(s). Use read_file to view full content.`
+                    : 'No matching knowledge found. Try different search terms or check available topics with /query.',
+                results,
+                totalFound: searchResults.length,
+            };
+        },
+        id: ToolName.SEARCH_KNOWLEDGE,
+        inputSchema: SearchKnowledgeInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/task-tool.js

@@ -95,6 +95,7 @@ export function createTaskTool(dependencies) {
     const registry = getAgentRegistry();
     return {
         description: buildTaskToolDescription(registry),
+        // eslint-disable-next-line complexity -- Inherent complexity: validates agent, manages sessions, handles errors
         async execute(input, context) {
             const params = input;
             const { contextTreeOnly, description, prompt, sessionId, subagentType } = params;