byterover-cli 3.0.1 → 3.1.0

package/dist/server/core/domain/transport/schemas.d.ts

@@ -521,18 +521,18 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     taskId: string;
     clientId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     clientId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
 }>;
 /**
  * task:cancel - Transport tells Agent to cancel a task
@@ -689,15 +689,15 @@ export declare const TaskCreatedSchema: z.ZodObject<{
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
 }>;
 /**
  * task:started - Agent begins processing the task
@@ -965,17 +965,17 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
 }>;
 /**
  * Response after task creation

package/dist/server/infra/context-tree/derived-artifact.js

@@ -6,7 +6,7 @@
  * - isArchiveStub()      — searchable stubs (included in BM25 index and fingerprint)
  * - isExcludedFromSync() — union of above (excluded from snapshot/sync/merge/push)
  */
-import { ARCHIVE_DIR, FULL_ARCHIVE_EXTENSION, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE } from '../../constants.js';
+import { ABSTRACT_EXTENSION, ARCHIVE_DIR, FULL_ARCHIVE_EXTENSION, MANIFEST_FILE, OVERVIEW_EXTENSION, STUB_EXTENSION, SUMMARY_INDEX_FILE } from '../../constants.js';
 import { toUnixPath } from './path-utils.js';
 /**
  * Returns true if the given relative path is a derived artifact
@@ -24,6 +24,10 @@ export function isDerivedArtifact(relativePath) {
         return true;
     if (fileName === MANIFEST_FILE)
         return true;
+    if (fileName.endsWith(ABSTRACT_EXTENSION))
+        return true;
+    if (fileName.endsWith(OVERVIEW_EXTENSION))
+        return true;
     if (segments.includes(ARCHIVE_DIR) && fileName.endsWith(FULL_ARCHIVE_EXTENSION))
         return true;
     return false;

package/dist/server/infra/context-tree/file-context-tree-manifest-service.d.ts

@@ -44,7 +44,8 @@ export declare class FileContextTreeManifestService implements IContextTreeManif
     private scanForManifest;
     /**
      * Recursively collect stat data for all source files (for fingerprint).
-     * Excludes derived artifacts.
+     * Excludes derived artifacts except .abstract.md siblings, which are included
+     * so abstract generation invalidates the manifest without a second tree walk.
      */
     private scanSourceStats;
 }

package/dist/server/infra/context-tree/file-context-tree-manifest-service.js

@@ -15,7 +15,7 @@
  */
 import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-import { ARCHIVE_DIR, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE, } from '../../constants.js';
+import { ABSTRACT_EXTENSION, ARCHIVE_DIR, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE, } from '../../constants.js';
 import { parseFrontmatterScoring } from '../../core/domain/knowledge/markdown-writer.js';
 import { DEFAULT_LANE_BUDGETS } from '../../core/domain/knowledge/summary-types.js';
 import { estimateTokens } from '../executor/pre-compaction/compaction-escalation.js';
@@ -98,8 +98,23 @@ export class FileContextTreeManifestService {
         /* eslint-disable no-await-in-loop */
         for (const entry of ordered) {
             try {
-                const fullPath = join(contextTreeDir, entry.path);
-                const content = await readFile(fullPath, 'utf8');
+                let content;
+                // For context entries, prefer .abstract.md sibling if it exists on disk
+                // (dynamic read avoids stale-manifest issues since .abstract.md is a derived artifact)
+                if (entry.type === 'context') {
+                    const abstractRelPath = entry.path.replace(/\.md$/, ABSTRACT_EXTENSION);
+                    const abstractFullPath = join(contextTreeDir, abstractRelPath);
+                    try {
+                        content = await readFile(abstractFullPath, 'utf8');
+                    }
+                    catch {
+                        // Abstract not ready yet — fall back to full content
+                        content = await readFile(join(contextTreeDir, entry.path), 'utf8');
+                    }
+                }
+                else {
+                    content = await readFile(join(contextTreeDir, entry.path), 'utf8');
+                }
                 resolved.push({
                     content,
                     path: entry.path,
@@ -188,6 +203,12 @@ export class FileContextTreeManifestService {
         catch {
             return;
         }
+        // Build a set of abstract sibling paths present in this directory so we can
+        // check existence without throwing ENOENT for every context file that has
+        // no abstract yet (the common case early in a project's lifetime).
+        const abstractsInDir = new Set(entries
+            .filter((e) => e.isFile() && e.name.endsWith(ABSTRACT_EXTENSION))
+            .map((e) => join(currentDir, e.name)));
         /* eslint-disable no-await-in-loop */
         for (const entry of entries) {
             const entryName = entry.name;
@@ -221,10 +242,24 @@ export class FileContextTreeManifestService {
                     try {
                         const content = await readFile(fullPath, 'utf8');
                         const scoring = parseFrontmatterScoring(content);
+                        // Use abstract sibling for token budgeting only if it is known to exist
+                        // (checked via abstractsInDir set, avoiding ENOENT as control flow).
+                        const abstractRelPath = relativePath.replace(/\.md$/, ABSTRACT_EXTENSION);
+                        const abstractFullPath = join(contextTreeDir, abstractRelPath);
+                        let abstractTokens;
+                        if (abstractsInDir.has(abstractFullPath)) {
+                            try {
+                                const abstractContent = await readFile(abstractFullPath, 'utf8');
+                                abstractTokens = estimateTokens(abstractContent);
+                            }
+                            catch { /* unreadable — treat as absent */ }
+                        }
                         contexts.push({
+                            abstractPath: abstractTokens === undefined ? undefined : abstractRelPath,
+                            abstractTokens,
                             importance: scoring?.importance ?? 50,
                             path: relativePath,
-                            tokens: estimateTokens(content),
+                            tokens: abstractTokens ?? estimateTokens(content),
                             type: 'context',
                         });
                     }
@@ -238,7 +273,8 @@ export class FileContextTreeManifestService {
     }
     /**
      * Recursively collect stat data for all source files (for fingerprint).
-     * Excludes derived artifacts.
+     * Excludes derived artifacts except .abstract.md siblings, which are included
+     * so abstract generation invalidates the manifest without a second tree walk.
      */
     async scanSourceStats(currentDir, contextTreeDir, entries) {
         let dirEntries;
@@ -257,8 +293,8 @@ export class FileContextTreeManifestService {
             }
             else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
                 const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
-                // Include all non-derived files (contexts + stubs) in fingerprint
-                if (isDerivedArtifact(relativePath))
+                const isAbstractSibling = entryName.endsWith(ABSTRACT_EXTENSION);
+                if (!isAbstractSibling && isDerivedArtifact(relativePath))
                     continue;
                 try {
                     const fileStat = await stat(fullPath);

package/dist/server/infra/context-tree/file-context-tree-summary-service.js

@@ -74,7 +74,18 @@ export class FileContextTreeSummaryService {
             // Step 5: Three-tier escalation via CipherAgent
             const taskId = `summary_${directoryPath.replaceAll('/', '_') || 'root'}`;
             const childEntries = children.map((c) => ({ content: c.content, name: c.name }));
-            const summaryText = await this.generateWithEscalation(agent, taskId, childEntries, level, totalInputTokens);
+            let summaryText;
+            try {
+                summaryText = await this.generateWithEscalation(agent, taskId, childEntries, level, totalInputTokens);
+            }
+            catch {
+                const combinedInput = childEntries.map((entry) => `## ${entry.name}\n${entry.content}`).join('\n\n');
+                summaryText = buildDeterministicFallbackCompaction({
+                    inputTokens: totalInputTokens,
+                    sourceText: combinedInput,
+                    suffixLabel: 'summary compaction',
+                });
+            }
             // Step 6: Write _index.md
             const summaryTokens = estimateTokens(summaryText);
             const frontmatter = {
@@ -289,7 +300,14 @@ export class FileContextTreeSummaryService {
             });
         }
         finally {
-            await agent.deleteTaskSession(sessionId);
+            try {
+                // Cleanup is best-effort. A generated summary should still be written even
+                // if the backing task session cannot be torn down cleanly.
+                await agent.deleteTaskSession(sessionId);
+            }
+            catch {
+                // Ignore cleanup failures
+            }
         }
     }
     /**

package/dist/server/infra/executor/curate-executor.js

@@ -54,7 +54,7 @@ export class CurateExecutor {
         catch {
             // Fail-open: if snapshot fails, skip summary propagation
         }
-        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true, userFacing: true });
         try {
             // Task-scoped variable names for RLM pattern.
             // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
@@ -124,6 +124,7 @@ export class CurateExecutor {
                     // Fail-open: summary/manifest errors never block curation
                 }
             }
+            await agent.drainBackgroundWork?.();
             return response;
         }
         finally {

package/dist/server/infra/executor/folder-pack-executor.js

@@ -1,6 +1,10 @@
 import { appendFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
+import { FileContextTreeSnapshotService } from '../context-tree/file-context-tree-snapshot-service.js';
+import { FileContextTreeSummaryService } from '../context-tree/file-context-tree-summary-service.js';
+import { diffStates } from '../context-tree/snapshot-diff.js';
 const LOG_PATH = process.env.BRV_SESSION_LOG;
 function folderPackLog(message) {
     if (!LOG_PATH)
@@ -41,6 +45,14 @@ export class FolderPackExecutor {
         // Resolve folder path
         const basePath = clientCwd ?? process.cwd();
         const absoluteFolderPath = path.isAbsolute(folderPath) ? folderPath : path.resolve(basePath, folderPath);
+        const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: basePath });
+        let preState;
+        try {
+            preState = await snapshotService.getCurrentState(basePath);
+        }
+        catch {
+            // Fail-open: if snapshot fails, skip summary propagation
+        }
         // Pack the folder
         const packResult = await this.folderPackService.pack(absoluteFolderPath, {
             extractDocuments: true,
@@ -50,7 +62,26 @@ export class FolderPackExecutor {
         // Use iterative extraction strategy (inspired by rlm)
         // Stores packed folder in sandbox environment and lets agent iteratively query/extract
         // This avoids token limits entirely - works for folders of any size
-        return this.executeIterative(agent, packResult, content, absoluteFolderPath, taskId, basePath);
+        const response = await this.executeIterative(agent, packResult, content, absoluteFolderPath, taskId, basePath);
+        if (preState) {
+            try {
+                const postState = await snapshotService.getCurrentState(basePath);
+                const changedPaths = diffStates(preState, postState);
+                if (changedPaths.length > 0) {
+                    const summaryService = new FileContextTreeSummaryService();
+                    const results = await summaryService.propagateStaleness(changedPaths, agent, basePath);
+                    if (results.some((result) => result.actionTaken)) {
+                        const manifestService = new FileContextTreeManifestService({ baseDirectory: basePath });
+                        await manifestService.buildManifest(basePath);
+                    }
+                }
+            }
+            catch {
+                // Fail-open: summary/manifest errors never block curation
+            }
+        }
+        await agent.drainBackgroundWork?.();
+        return response;
     }
     /**
      * Build iterative extraction prompt with file-based access.
@@ -133,6 +164,15 @@ Use **code_exec with tools.readFile/tools.grep** to extract knowledge:
 
 **Important**: All tools.* methods are async - always use \`await\`!
 
+## Curate Shape Constraints
+
+- Prefer one concrete knowledge entry per relevant source file when curating a small leaf folder.
+- For folders with 3 or fewer relevant source files, keep the number of curated leaf entries at or below the number of curated source files by default.
+- Do **NOT** create an extra module/folder "overview" leaf at the bare topic path just because the folder has multiple files.
+- Treat bare topic paths as scopes for \`topicContext\`, not as default destinations for standalone knowledge files.
+- If you need topic-level framing, provide \`topicContext\` on the operation that creates the topic. The system will create/update \`context.md\` and higher-level summaries separately.
+- Only add a standalone overview leaf when the user explicitly asks for it or when there is a distinct cross-file concept that cannot be represented by the per-file entries.
+
 ## Common Mistakes to Avoid
 
 **❌ WRONG - Using require() inside code_exec:**
@@ -773,7 +813,7 @@ await tools.curate([{
             throw new Error(`Failed to write temp file: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Create per-task session for parallel isolation (own sandbox + history + LLM service)
-        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true, userFacing: true });
         // Step 3: Store full instructions as sandbox variable (lazy prompt loading).
         // This saves ~12-15K tokens by keeping the massive instruction set out of the prompt.
         // The LLM reads instructions on-demand via code_exec.
@@ -783,15 +823,45 @@ await tools.curate([{
         const taskIdSafe = taskId.replaceAll('-', '_');
         const instructionsVar = `__curate_instructions_${taskIdSafe}`;
         agent.setSandboxVariableOnSession(taskSessionId, instructionsVar, fullInstructions);
+        const smallFolderFilesVar = `__curate_files_${taskIdSafe}`;
+        const shouldExposePackedFiles = packResult.files.length > 0 && packResult.files.length <= 10 && packResult.totalCharacters <= 80_000;
+        if (shouldExposePackedFiles) {
+            agent.setSandboxVariableOnSession(taskSessionId, smallFolderFilesVar, packResult.files.map((file) => ({
+                content: file.content,
+                fileType: file.fileType,
+                lineCount: file.lineCount,
+                path: file.path,
+                size: file.size,
+                truncated: file.truncated,
+            })));
+        }
         // Compact prompt with variable reference and essential metadata
         const contextSection = userContext?.trim() ? `\nUser context: ${userContext}\n` : '';
+        const sourceFilePaths = packResult.files.map((file) => file.path);
+        const sourceFilesSection = sourceFilePaths.length > 0
+            ? `Relevant source files: ${sourceFilePaths.join(', ')} (these paths are relative to the packed folder root; do not prefix them with parent directories like src/auth/)`
+            : undefined;
+        const smallFolderLeafQuota = sourceFilePaths.length > 0 && sourceFilePaths.length <= 3
+            ? `Leaf quota: create no more than ${sourceFilePaths.length} curated leaf knowledge files for this folder unless the user explicitly asks for more.`
+            : undefined;
+        const smallFolderQuotaWarning = sourceFilePaths.length > 0 && sourceFilePaths.length <= 3
+            ? `A topic-level overview leaf counts toward that quota and is usually incorrect here; keep folder-level framing in topicContext instead.`
+            : undefined;
         const compactPrompt = [
             `# Folder Curation Task`,
             ``,
             `Folder: ${folderPath} (${packResult.fileCount} files, ${packResult.totalLines} lines)`,
             `Data file: \`${tmpFilePath}\` (repomix-style XML format)`,
             `Full instructions: variable \`${instructionsVar}\``,
+            shouldExposePackedFiles
+                ? `Relevant files variable: \`${smallFolderFilesVar}\` (array of packed files; for this small folder, prefer using it directly instead of parsing XML with brittle regexes).`
+                : undefined,
             contextSection,
+            sourceFilesSection,
+            `Small-folder rule: for folders with 3 or fewer relevant source files, create at most one leaf knowledge entry per file by default.`,
+            smallFolderLeafQuota,
+            smallFolderQuotaWarning,
+            `Do not create an extra overview leaf at the bare topic path; use topicContext for topic-level framing instead.`,
             `**Start by reading instructions**: Use code_exec to read \`${instructionsVar}.slice(0, 5000)\` for the strategy section, then \`${instructionsVar}.slice(5000, 10000)\` for content rules.`,
             `Use \`tools.readFile()\` and \`tools.grep()\` inside code_exec to process the XML data file.`,
             `Use \`tools.curate()\` to create knowledge topics. Use \`setFinalResult()\` when done.`,

package/dist/server/infra/executor/query-executor.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../constants.js';
+import { ABSTRACT_EXTENSION, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../constants.js';
 import { isDerivedArtifact } from '../context-tree/derived-artifact.js';
 import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
 import { canRespondDirectly, formatDirectResponse, formatNotFoundResponse, } from './direct-search-responder.js';
@@ -124,7 +124,7 @@ export class QueryExecutor {
             }
         }
         // Create per-task session for parallel isolation (own sandbox + history + LLM service)
-        const taskSessionId = await agent.createTaskSession(taskId, 'query');
+        const taskSessionId = await agent.createTaskSession(taskId, 'query', { userFacing: true });
         // Task-scoped variable names for sandbox injection (RLM pattern).
         // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
         // so the LLM uses underscores when writing code-exec calls — matching curate-executor pattern.
@@ -273,7 +273,15 @@ ${responseFormat}`;
                 mtime: f.modified?.getTime() ?? 0,
                 path: f.path,
             }));
-            const fingerprint = QueryResultCache.computeFingerprint(files);
+            // Include .abstract.md siblings so newly-written abstracts invalidate the cache.
+            // They are excluded by isDerivedArtifact() above, so we append them separately.
+            const abstractFiles = globResult.files
+                .filter((f) => f.path.endsWith(ABSTRACT_EXTENSION))
+                .map((f) => ({
+                mtime: f.modified?.getTime() ?? 0,
+                path: f.path,
+            }));
+            const fingerprint = QueryResultCache.computeFingerprint([...files, ...abstractFiles]);
             this.cachedFingerprint = {
                 expiresAt: Date.now() + QueryExecutor.FINGERPRINT_CACHE_TTL_MS,
                 value: fingerprint,

package/dist/server/infra/transport/handlers/status-handler.js

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { StatusEvents } from '../../../../shared/transport/events/status-events.js';
 import { BRV_DIR, CONTEXT_TREE_DIR } from '../../../constants.js';
@@ -65,6 +66,15 @@ export class StatusHandler {
             }
         }
         catch { }
+        // Abstract generation queue status (written by agent process via abstract-queue.ts)
+        try {
+            const queueStatusPath = join(projectPath, BRV_DIR, '_queue_status.json');
+            const raw = await readFile(queueStatusPath, 'utf8');
+            result.abstractQueue = JSON.parse(raw);
+        }
+        catch {
+            // File doesn't exist yet — no queue running
+        }
         // Context tree status
         try {
             const contextTreeExists = await this.contextTreeService.exists(projectPath);

package/dist/server/utils/curate-result-parser.d.ts

@@ -98,22 +98,22 @@ export declare const CurateResultSchema: z.ZodObject<{
         failed?: number | undefined;
         deleted?: number | undefined;
         updated?: number | undefined;
-        added?: number | undefined;
         merged?: number | undefined;
+        added?: number | undefined;
     }, {
         failed?: number | undefined;
         deleted?: number | undefined;
         updated?: number | undefined;
-        added?: number | undefined;
         merged?: number | undefined;
+        added?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     summary?: {
         failed?: number | undefined;
         deleted?: number | undefined;
         updated?: number | undefined;
-        added?: number | undefined;
         merged?: number | undefined;
+        added?: number | undefined;
     } | undefined;
     applied?: {
         path: string;
@@ -135,8 +135,8 @@ export declare const CurateResultSchema: z.ZodObject<{
         failed?: number | undefined;
         deleted?: number | undefined;
         updated?: number | undefined;
-        added?: number | undefined;
         merged?: number | undefined;
+        added?: number | undefined;
     } | undefined;
     applied?: {
         path: string;

package/dist/shared/transport/types/dto.d.ts

@@ -114,6 +114,13 @@ export interface ProjectLocationDTO {
     projectPath: string;
 }
 export interface StatusDTO {
+    /** Current state of the background abstract generation queue, if active */
+    abstractQueue?: {
+        failed: number;
+        pending: number;
+        processed: number;
+        processing: boolean;
+    };
     authStatus: 'expired' | 'logged_in' | 'not_logged_in' | 'unknown';
     contextTreeChanges?: ContextTreeChanges;
     /** Absolute path to the context tree directory (e.g., '/Users/foo/project/.brv/context-tree') */