byterover-cli 3.0.1 → 3.2.0

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

@@ -4,7 +4,7 @@
  * This module is responsible for initializing and wiring together all core agent services.
  * It provides a single entry point for constructing the service graph.
  *
- * Following DextoAgent pattern:
+ * Following pattern:
  * - Config file is source of truth (ValidatedAgentConfig)
  * - Centralized function (not factory class) for service creation
  * - Explicit dependency order with numbered steps
@@ -26,6 +26,7 @@ import { createGeneratorForProvider } from '../llm/providers/index.js';
 import { DEFAULT_RETRY_POLICY } from '../llm/retry/retry-policy.js';
 import { GeminiTokenizer } from '../llm/tokenizers/gemini-tokenizer.js';
 import { EventBasedLogger } from '../logger/event-based-logger.js';
+import { AbstractGenerationQueue } from '../map/abstract-queue.js';
 import { MemoryManager } from '../memory/memory-manager.js';
 import { ProcessService } from '../process/process-service.js';
 import { SandboxService } from '../sandbox/sandbox-service.js';
@@ -45,7 +46,7 @@ import { ToolProvider } from '../tools/tool-provider.js';
  * Creates shared services for CipherAgent.
  * These services are singletons shared across all sessions.
  *
- * Initialization order follows DextoAgent pattern (explicit numbered steps):
+ * Initialization order (explicit numbered steps):
  * 1. Logger (uses provided event bus)
  * 2. File system service (no dependencies)
  * 3. Process service (no dependencies)
@@ -60,11 +61,11 @@ import { ToolProvider } from '../tools/tool-provider.js';
  * 12. Return all services
  *
  * @param config - Validated agent configuration (Zod-validated)
- * @param agentEventBus - Pre-created event bus from agent constructor (DextoAgent pattern)
+ * @param agentEventBus - Pre-created event bus from agent constructor
  * @returns Initialized shared services
  */
 export async function createCipherAgentServices(config, agentEventBus) {
-    // 1. Logger (uses provided event bus - DextoAgent pattern)
+    // 1. Logger (uses provided event bus )
     const logger = new EventBasedLogger(agentEventBus, 'CipherAgent');
     // 2. File system service (no dependencies)
     const fileSystemService = new FileSystemService(config.fileSystem);
@@ -132,10 +133,13 @@ export async function createCipherAgentServices(config, agentEventBus) {
     // Priority 16 — right after context tree structure, before memories
     const mapSelectionContributor = new MapSelectionContributor('mapSelection', 16);
     systemPromptManager.registerContributor(mapSelectionContributor);
-    // 7. Tool provider (depends on FileSystemService, ProcessService, MemoryManager, SystemPromptManager)
+    // 7. Abstract generation queue (generator injected later via rebindCurateTools)
+    const abstractQueue = new AbstractGenerationQueue(workingDirectory);
+    // 8. Tool provider (depends on FileSystemService, ProcessService, MemoryManager, SystemPromptManager)
     const verbose = config.llm.verbose ?? false;
     const descriptionLoader = new ToolDescriptionLoader();
     const toolProvider = new ToolProvider({
+        abstractQueue,
         environmentContext,
         fileSystemService,
         getToolProvider: () => toolProvider,
@@ -144,14 +148,14 @@ export async function createCipherAgentServices(config, agentEventBus) {
         sandboxService,
     }, systemPromptManager, descriptionLoader);
     await toolProvider.initialize();
-    // 8. Policy engine with default rules for autonomous execution
+    // 9. Policy engine with default rules for autonomous execution
     const policyEngine = new PolicyEngine({ defaultDecision: 'ALLOW' });
     policyEngine.addRules(DEFAULT_POLICY_RULES);
-    // 9. Tool scheduler (orchestrates policy check → execution)
+    // 10. Tool scheduler (orchestrates policy check → execution)
     const toolScheduler = new CoreToolScheduler(toolProvider, policyEngine, undefined, {
         verbose,
     });
-    // 10. Tool manager (with scheduler for policy-based execution)
+    // 11. Tool manager (with scheduler for policy-based execution)
     const toolManager = new ToolManager(toolProvider, toolScheduler);
     await toolManager.initialize();
     // 11. History storage - granular file-based storage
@@ -177,6 +181,7 @@ export async function createCipherAgentServices(config, agentEventBus) {
         workingDirectory,
     });
     return {
+        abstractQueue,
         agentEventBus,
         blobStorage,
         compactionService,
@@ -191,6 +196,7 @@ export async function createCipherAgentServices(config, agentEventBus) {
         toolManager,
         toolProvider,
         toolScheduler,
+        workingDirectory,
     };
 }
 /**

package/dist/agent/infra/agent/types.d.ts

@@ -19,7 +19,6 @@ export interface AgentExecutionContext {
 /**
  * Agent event subscriber interface.
  * Objects implementing this can be registered for event subscription.
- * Follows DextoAgent's AgentEventSubscriber pattern.
  */
 export interface AgentEventSubscriber {
     /**

package/dist/agent/infra/file-system/file-system-service.js

@@ -208,17 +208,18 @@ export class FileSystemService {
         this.ensureInitialized();
         const rawCwd = options.cwd ?? this.config.workingDirectory;
         const cwd = path.isAbsolute(rawCwd) ? rawCwd : path.resolve(this.config.workingDirectory, rawCwd);
+        const normalizedCwd = await fs.realpath(cwd).catch(() => cwd);
         const maxResults = options.maxResults ?? 1000;
         const includeMetadata = options.includeMetadata ?? true;
         const caseSensitive = options.caseSensitive ?? true;
         const respectGitignore = options.respectGitignore ?? true;
         try {
             // Handle special characters - escape pattern if it matches an existing file
-            const escapedPattern = await escapeIfExactMatch(pattern, cwd);
+            const escapedPattern = await escapeIfExactMatch(pattern, normalizedCwd);
             // Execute glob with case sensitivity option
             const files = await glob(escapedPattern, {
                 absolute: true,
-                cwd,
+                cwd: normalizedCwd,
                 follow: false, // Don't follow symlinks
                 nocase: !caseSensitive, // Case insensitive if caseSensitive is false
                 nodir: true, // Only files
@@ -226,7 +227,7 @@ export class FileSystemService {
             // Initialize gitignore filter if requested
             let gitignoreFilter = null;
             if (respectGitignore) {
-                gitignoreFilter = await createGitignoreFilter(cwd);
+                gitignoreFilter = await createGitignoreFilter(normalizedCwd);
             }
             // Validate paths and apply gitignore filtering
             const validPaths = [];
@@ -240,7 +241,7 @@ export class FileSystemService {
                 }
                 // Apply gitignore filter if enabled
                 if (gitignoreFilter) {
-                    const relativePath = path.relative(cwd, validation.normalizedPath);
+                    const relativePath = path.relative(normalizedCwd, validation.normalizedPath);
                     if (gitignoreFilter.isIgnored(relativePath)) {
                         ignoredCount++;
                         continue;
@@ -250,7 +251,7 @@ export class FileSystemService {
             }
             const totalFound = validPaths.length;
             // Collect metadata for all valid paths
-            const filesWithMetadata = await collectFileMetadata(validPaths, cwd);
+            const filesWithMetadata = await collectFileMetadata(validPaths, normalizedCwd);
             // Sort files: recent files first (within 24h), then alphabetical
             const sortedFiles = sortFilesByRecency(filesWithMetadata);
             // Apply maxResults limit after sorting

package/dist/agent/infra/folder-pack/folder-pack-service.d.ts

@@ -54,4 +54,5 @@ export declare class FolderPackService implements IFolderPackService {
      * Parse an Office document using the document parser.
      */
     private parseOfficeDocument;
+    private toRelativePackPath;
 }

package/dist/agent/infra/folder-pack/folder-pack-service.js

@@ -109,9 +109,10 @@ export class FolderPackService {
         const startTime = Date.now();
         const mergedConfig = this.mergeConfig(config);
         // Resolve to absolute path
-        const absolutePath = path.isAbsolute(folderPath)
+        const rawAbsolutePath = path.isAbsolute(folderPath)
             ? folderPath
             : path.resolve(process.cwd(), folderPath);
+        const absolutePath = await fs.realpath(rawAbsolutePath).catch(() => rawAbsolutePath);
         // Phase 1: Search for files
         onProgress?.({ current: 0, message: 'Searching for files...', phase: 'searching' });
         const ignorePatterns = [...getDefaultIgnorePatterns(), ...mergedConfig.ignore];
@@ -130,8 +131,18 @@ export class FolderPackService {
             }
             throw error;
         }
-        // Filter files based on ignore patterns
-        const filteredFiles = globResult.files.filter((file) => !this.matchesIgnorePattern(file.path, ignorePatterns));
+        const discoveredFiles = globResult.files
+            .map((file) => {
+            const absoluteFilePath = path.isAbsolute(file.path) ? file.path : path.resolve(absolutePath, file.path);
+            return {
+                absolutePath: absoluteFilePath,
+                relativePath: this.toRelativePackPath(absolutePath, absoluteFilePath),
+                size: file.size,
+            };
+        })
+            .filter((file) => file.relativePath.length > 0 && !file.relativePath.startsWith('../'));
+        // Filter files based on ignore patterns using paths relative to the packed root.
+        const filteredFiles = discoveredFiles.filter((file) => !this.matchesIgnorePattern(file.relativePath, ignorePatterns));
         onProgress?.({
             current: filteredFiles.length,
             message: `Found ${filteredFiles.length} files`,
@@ -152,7 +163,7 @@ export class FolderPackService {
             // Report progress (note: may be out of order due to parallelism)
             onProgress?.({
                 current: index + 1,
-                message: `Reading ${fileInfo.path}`,
+                message: `Reading ${fileInfo.relativePath}`,
                 phase: 'collecting',
                 total: totalFiles,
             });
@@ -162,19 +173,19 @@ export class FolderPackService {
                     return {
                         skipped: {
                             message: `File size ${fileInfo.size} exceeds limit ${mergedConfig.maxFileSize}`,
-                            path: fileInfo.path,
+                            path: fileInfo.relativePath,
                             reason: 'size-limit',
                         },
                         type: 'skipped',
                     };
                 }
                 // Check if this is an Office document that should be parsed
-                if (mergedConfig.extractDocuments && this.documentParser && isOfficeFile(fileInfo.path)) {
-                    return this.parseOfficeDocument(fileInfo.path, fileInfo.size);
+                if (mergedConfig.extractDocuments && this.documentParser && isOfficeFile(fileInfo.absolutePath)) {
+                    return this.parseOfficeDocument(fileInfo.absolutePath, fileInfo.relativePath, fileInfo.size);
                 }
                 // Read file content using FileSystemService
                 // This handles binary detection, PDF extraction, encoding, etc.
-                const fileContent = await this.fileSystemService.readFile(fileInfo.path, {
+                const fileContent = await this.fileSystemService.readFile(fileInfo.absolutePath, {
                     limit: mergedConfig.maxLinesPerFile,
                 });
                 // Check if it's a PDF with extracted text
@@ -182,9 +193,9 @@ export class FolderPackService {
                 return {
                     file: {
                         content: fileContent.content,
-                        fileType: isPdf ? 'pdf' : this.detectFileType(fileInfo.path),
+                        fileType: isPdf ? 'pdf' : this.detectFileType(fileInfo.relativePath),
                         lineCount: fileContent.lines,
-                        path: fileInfo.path,
+                        path: fileInfo.relativePath,
                         size: fileInfo.size,
                         truncated: fileContent.truncated,
                     },
@@ -197,7 +208,7 @@ export class FolderPackService {
                 return {
                     skipped: {
                         message: error instanceof Error ? error.message : String(error),
-                        path: fileInfo.path,
+                        path: fileInfo.relativePath,
                         reason: skipReason,
                     },
                     type: 'skipped',
@@ -329,12 +340,12 @@ export class FolderPackService {
     /**
      * Parse an Office document using the document parser.
      */
-    async parseOfficeDocument(filePath, size) {
+    async parseOfficeDocument(filePath, outputPath, size) {
         if (!this.documentParser) {
             return {
                 skipped: {
                     message: 'Document parser not available',
-                    path: filePath,
+                    path: outputPath,
                     reason: 'read-error',
                 },
                 type: 'skipped',
@@ -351,7 +362,7 @@ export class FolderPackService {
                     content: result.content,
                     fileType: 'document',
                     lineCount: lines.length,
-                    path: filePath,
+                    path: outputPath,
                     size,
                     truncated: false,
                 },
@@ -362,11 +373,14 @@ export class FolderPackService {
             return {
                 skipped: {
                     message: error instanceof Error ? error.message : String(error),
-                    path: filePath,
+                    path: outputPath,
                     reason: 'read-error',
                 },
                 type: 'skipped',
             };
         }
     }
+    toRelativePackPath(rootPath, filePath) {
+        return path.relative(rootPath, filePath).replaceAll('\\', '/');
+    }
 }

package/dist/agent/infra/llm/providers/openai.js

@@ -31,6 +31,18 @@ export function createChatGptOAuthFetch() {
             catch {
                 return globalThis.fetch(input, init);
             }
+            // The AI SDK sends systemPrompt as input[0] with role "system" or "developer".
+            // The ChatGPT OAuth Responses endpoint expects it in top-level `instructions`.
+            if (!body.instructions && Array.isArray(body.input) && body.input.length > 0) {
+                const first = body.input[0];
+                if (typeof first === 'object' && first !== null) {
+                    const record = first;
+                    if ((record.role === 'system' || record.role === 'developer') && typeof record.content === 'string') {
+                        body.instructions = record.content;
+                        body.input.splice(0, 1);
+                    }
+                }
+            }
             if (!body.instructions) {
                 body.instructions = '';
             }

package/dist/agent/infra/llm/stream-to-text.d.ts

@@ -0,0 +1,7 @@
+import type { GenerateContentRequest, IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+/**
+ * Consume generateContentStream() and return accumulated text.
+ * Used instead of generateContent() because the ChatGPT OAuth Codex
+ * endpoint requires stream: true in all requests.
+ */
+export declare function streamToText(generator: IContentGenerator, request: GenerateContentRequest): Promise<string>;

package/dist/agent/infra/llm/stream-to-text.js

@@ -0,0 +1,14 @@
+/**
+ * Consume generateContentStream() and return accumulated text.
+ * Used instead of generateContent() because the ChatGPT OAuth Codex
+ * endpoint requires stream: true in all requests.
+ */
+export async function streamToText(generator, request) {
+    const chunks = [];
+    for await (const chunk of generator.generateContentStream(request)) {
+        if (chunk.content) {
+            chunks.push(chunk.content);
+        }
+    }
+    return chunks.join('');
+}

package/dist/agent/infra/map/abstract-generator.d.ts

@@ -0,0 +1,22 @@
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+/**
+ * Result from abstract generation.
+ */
+export interface AbstractGenerateResult {
+    /** L0: one-line summary (~80 tokens) */
+    abstractContent: string;
+    /** L1: key points + structure (~1500 tokens) */
+    overviewContent: string;
+}
+/**
+ * Generate L0 abstract and L1 overview for a knowledge file.
+ *
+ * Makes two parallel LLM calls at temperature=0:
+ *   1. L0 .abstract.md — one-line summary (~80 tokens)
+ *   2. L1 .overview.md — key points + structure (~1500 tokens)
+ *
+ * @param fullContent - Full markdown content of the knowledge file
+ * @param generator - LLM content generator
+ * @returns Abstract and overview content strings
+ */
+export declare function generateFileAbstracts(fullContent: string, generator: IContentGenerator): Promise<AbstractGenerateResult>;

package/dist/agent/infra/map/abstract-generator.js

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto';
+import { streamToText } from '../llm/stream-to-text.js';
+const ABSTRACT_SYSTEM_PROMPT = `You are a technical documentation assistant.
+Your job is to produce precise, factual summaries of knowledge documents.
+Output only the requested content — no preamble, no commentary.`;
+const OVERVIEW_SYSTEM_PROMPT = `You are a technical documentation assistant.
+Your job is to produce structured overviews of knowledge documents.
+Preserve factual accuracy, surface important entities and decisions, and format the result in concise markdown.`;
+function buildAbstractPrompt(content) {
+    return `Produce a ONE-LINE summary (max 80 tokens) of the following knowledge document.
+The line must be a complete sentence that captures the core topic and key insight.
+Output only the single line — nothing else.
+
+<document>
+${content}
+</document>`;
+}
+function buildOverviewPrompt(content) {
+    return `Produce a structured overview of the following knowledge document.
+Include:
+- Key points (3-7 bullet points)
+- Structure / sections summary
+- Any notable entities, patterns, or decisions mentioned
+
+Keep it under 1500 tokens. Use markdown formatting.
+Output only the overview — no preamble.
+
+<document>
+${content}
+</document>`;
+}
+/** Truncate content before embedding in LLM prompts to avoid exceeding model context windows during bulk ingest. */
+const MAX_ABSTRACT_CONTENT_CHARS = 20_000;
+/**
+ * Generate L0 abstract and L1 overview for a knowledge file.
+ *
+ * Makes two parallel LLM calls at temperature=0:
+ *   1. L0 .abstract.md — one-line summary (~80 tokens)
+ *   2. L1 .overview.md — key points + structure (~1500 tokens)
+ *
+ * @param fullContent - Full markdown content of the knowledge file
+ * @param generator - LLM content generator
+ * @returns Abstract and overview content strings
+ */
+export async function generateFileAbstracts(fullContent, generator) {
+    const truncated = fullContent.slice(0, MAX_ABSTRACT_CONTENT_CHARS);
+    const [abstractText, overviewText] = await Promise.all([
+        streamToText(generator, {
+            config: { maxTokens: 150, temperature: 0 },
+            contents: [{ content: buildAbstractPrompt(truncated), role: 'user' }],
+            model: 'default',
+            systemPrompt: ABSTRACT_SYSTEM_PROMPT,
+            taskId: randomUUID(),
+        }),
+        streamToText(generator, {
+            config: { maxTokens: 2000, temperature: 0 },
+            contents: [{ content: buildOverviewPrompt(truncated), role: 'user' }],
+            model: 'default',
+            systemPrompt: OVERVIEW_SYSTEM_PROMPT,
+            taskId: randomUUID(),
+        }),
+    ]);
+    return {
+        abstractContent: abstractText.trim(),
+        overviewContent: overviewText.trim(),
+    };
+}

package/dist/agent/infra/map/abstract-queue.d.ts

@@ -0,0 +1,67 @@
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+/**
+ * Observable status of the abstract generation queue.
+ */
+export interface AbstractQueueStatus {
+    failed: number;
+    pending: number;
+    processed: number;
+    processing: boolean;
+}
+/**
+ * Background queue for generating L0/L1 abstract files (.abstract.md, .overview.md).
+ *
+ * - Generator is injected lazily via setGenerator() (mirrors rebindMapTools pattern)
+ * - Items arriving before setGenerator() are buffered and processed once generator is set
+ * - Writes status to <projectRoot>/.brv/_queue_status.json after each state transition
+ * - Retries up to maxAttempts with exponential backoff (500ms base)
+ * - drain() waits for all pending/processing items to complete (for graceful shutdown)
+ */
+export declare class AbstractGenerationQueue {
+    private readonly projectRoot;
+    private readonly maxAttempts;
+    private drainResolvers;
+    private failed;
+    private generator;
+    private onBeforeProcess?;
+    private pending;
+    private processed;
+    private processing;
+    /** Number of items currently in retry backoff (removed from pending but not yet re-enqueued). */
+    private retrying;
+    private statusDirCreated;
+    private statusWriteFailed;
+    private statusWritePromise;
+    constructor(projectRoot: string, maxAttempts?: number);
+    /**
+     * Wait for all pending items to finish processing (graceful shutdown).
+     * Includes items currently in retry backoff so drain() does not resolve prematurely.
+     */
+    drain(): Promise<void>;
+    /**
+     * Add a file to the abstract generation queue.
+     */
+    enqueue(item: {
+        contextPath: string;
+        fullContent: string;
+    }): void;
+    /**
+     * Return current queue status snapshot.
+     */
+    getStatus(): AbstractQueueStatus;
+    /**
+     * Set a callback that runs before each item is processed.
+     * Used to refresh OAuth tokens before LLM calls.
+     */
+    setBeforeProcess(fn: () => Promise<void>): void;
+    /**
+     * Inject the LLM generator. Triggers processing of any buffered items.
+     */
+    setGenerator(generator: IContentGenerator): void;
+    private isIdle;
+    private processNext;
+    private queueStatusWrite;
+    private resolveDrainersIfIdle;
+    private scheduleNext;
+    private writeStatusFile;
+}