byterover-cli 3.0.0 → 3.1.0

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;
+}

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

@@ -0,0 +1,218 @@
+import { appendFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateFileAbstracts } from './abstract-generator.js';
+const QUEUE_TRACE_ENABLED = process.env.BRV_QUEUE_TRACE === '1';
+const LOG_PATH = process.env.BRV_SESSION_LOG;
+function queueLog(message) {
+    if (!QUEUE_TRACE_ENABLED || !LOG_PATH)
+        return;
+    try {
+        appendFileSync(LOG_PATH, `${new Date().toISOString()} [abstract-queue] ${message}\n`);
+    }
+    catch {
+        // ignore — tracing must never block queue progress
+    }
+}
+/**
+ * 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 class AbstractGenerationQueue {
+    projectRoot;
+    maxAttempts;
+    drainResolvers = [];
+    failed = 0;
+    generator;
+    onBeforeProcess;
+    pending = [];
+    processed = 0;
+    processing = false;
+    /** Number of items currently in retry backoff (removed from pending but not yet re-enqueued). */
+    retrying = 0;
+    statusDirCreated = false;
+    statusWriteFailed = false;
+    statusWritePromise = Promise.resolve();
+    constructor(projectRoot, maxAttempts = 3) {
+        this.projectRoot = projectRoot;
+        this.maxAttempts = maxAttempts;
+    }
+    /**
+     * Wait for all pending items to finish processing (graceful shutdown).
+     * Includes items currently in retry backoff so drain() does not resolve prematurely.
+     */
+    async drain() {
+        queueLog(`drain:start idle=${this.isIdle()} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
+        if (this.isIdle()) {
+            await this.statusWritePromise.catch(() => { });
+            queueLog('drain:resolved-immediate');
+            return;
+        }
+        await new Promise((resolve) => {
+            this.drainResolvers.push(resolve);
+            this.resolveDrainersIfIdle();
+        });
+        queueLog('drain:resolved-deferred');
+    }
+    /**
+     * Add a file to the abstract generation queue.
+     */
+    enqueue(item) {
+        // Guard against paths that must never trigger abstract generation:
+        // - derived artifacts (.abstract.md, .overview.md) — would produce .abstract.abstract.md
+        // - summary index files (_index.md) — domain/topic summaries, not knowledge nodes
+        // - hierarchy scaffolding (context.md) — helper files, not leaf knowledge entries
+        const fileName = item.contextPath.split('/').at(-1) ?? item.contextPath;
+        if (fileName === 'context.md' ||
+            fileName === '_index.md' ||
+            item.contextPath.endsWith('.abstract.md') ||
+            item.contextPath.endsWith('.overview.md')) {
+            return;
+        }
+        this.pending.push({ attempts: 0, contextPath: item.contextPath, fullContent: item.fullContent });
+        queueLog(`enqueue path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
+        this.queueStatusWrite();
+        this.scheduleNext();
+    }
+    /**
+     * Return current queue status snapshot.
+     */
+    getStatus() {
+        return {
+            failed: this.failed,
+            // Items in retry backoff are still pending work — include them so the status
+            // does not falsely report the queue as idle during backoff windows.
+            pending: this.pending.length + this.retrying,
+            processed: this.processed,
+            processing: this.processing,
+        };
+    }
+    /**
+     * Set a callback that runs before each item is processed.
+     * Used to refresh OAuth tokens before LLM calls.
+     */
+    setBeforeProcess(fn) {
+        this.onBeforeProcess = fn;
+    }
+    /**
+     * Inject the LLM generator. Triggers processing of any buffered items.
+     */
+    setGenerator(generator) {
+        this.generator = generator;
+        this.scheduleNext();
+    }
+    isIdle() {
+        return this.pending.length === 0 && !this.processing && this.retrying === 0;
+    }
+    async processNext() {
+        if (!this.generator || this.processing || this.pending.length === 0) {
+            this.resolveDrainersIfIdle();
+            return;
+        }
+        this.processing = true;
+        this.queueStatusWrite();
+        const item = this.pending.shift();
+        queueLog(`process:start path=${item.contextPath} remaining=${this.pending.length} retrying=${this.retrying}`);
+        try {
+            // Refresh credentials before each generation (OAuth tokens may expire)
+            try {
+                await this.onBeforeProcess?.();
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                console.debug(`[AbstractQueue] token refresh failed, proceeding with existing generator: ${msg}`);
+            }
+            const { abstractContent, overviewContent } = await generateFileAbstracts(item.fullContent, this.generator);
+            // Derive sibling paths: replace .md with .abstract.md and .overview.md
+            const abstractPath = item.contextPath.replace(/\.md$/, '.abstract.md');
+            const overviewPath = item.contextPath.replace(/\.md$/, '.overview.md');
+            await Promise.all([
+                writeFile(abstractPath, abstractContent, 'utf8'),
+                writeFile(overviewPath, overviewContent, 'utf8'),
+            ]);
+            this.processed++;
+            queueLog(`process:success path=${item.contextPath} processed=${this.processed}`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.debug(`[AbstractQueue] ${item.contextPath} attempt ${item.attempts + 1}/${this.maxAttempts}: ${msg}`);
+            item.attempts++;
+            if (item.attempts < this.maxAttempts) {
+                // Exponential backoff: 500ms, 1000ms, 2000ms, ...
+                const delay = 500 * 2 ** (item.attempts - 1);
+                this.retrying++;
+                this.queueStatusWrite();
+                setTimeout(() => {
+                    this.retrying--;
+                    this.pending.unshift(item);
+                    queueLog(`process:retry-requeue path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying}`);
+                    this.queueStatusWrite();
+                    this.scheduleNext();
+                }, delay);
+            }
+            else {
+                this.failed++;
+                queueLog(`process:failed path=${item.contextPath} failed=${this.failed}`);
+            }
+        }
+        finally {
+            this.processing = false;
+            queueLog(`process:finally path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
+            this.queueStatusWrite();
+        }
+        this.scheduleNext();
+        this.resolveDrainersIfIdle();
+    }
+    queueStatusWrite() {
+        this.statusWritePromise = this.statusWritePromise
+            .catch(() => { })
+            .then(async () => this.writeStatusFile());
+    }
+    resolveDrainersIfIdle() {
+        if (!this.isIdle() || this.drainResolvers.length === 0) {
+            return;
+        }
+        queueLog(`drain:idle pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
+        const resolvers = this.drainResolvers.splice(0);
+        const settledStatusWrite = this.statusWritePromise.catch(() => { });
+        for (const resolve of resolvers) {
+            settledStatusWrite.then(() => resolve()).catch(() => { });
+        }
+    }
+    scheduleNext() {
+        if (!this.generator || this.processing || this.pending.length === 0) {
+            this.resolveDrainersIfIdle();
+            return;
+        }
+        // eslint-disable-next-line no-void
+        setImmediate(() => { void this.processNext(); });
+    }
+    async writeStatusFile() {
+        const statusPath = join(this.projectRoot, '.brv', '_queue_status.json');
+        try {
+            if (!this.statusDirCreated) {
+                await mkdir(join(this.projectRoot, '.brv'), { recursive: true });
+                this.statusDirCreated = true;
+            }
+            await writeFile(statusPath, JSON.stringify(this.getStatus()), 'utf8');
+            this.statusWriteFailed = false;
+        }
+        catch (error) {
+            const errorCode = typeof error === 'object' && error !== null && 'code' in error
+                ? error.code
+                : undefined;
+            if (errorCode === 'ENOENT') {
+                return;
+            }
+            if (!this.statusWriteFailed) {
+                this.statusWriteFailed = true;
+                console.debug(`[AbstractGenerationQueue] Failed to write queue status: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}

package/dist/agent/infra/memory/memory-deduplicator.d.ts

@@ -0,0 +1,44 @@
+import type { Memory } from '../../core/domain/memory/types.js';
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+/**
+ * A draft memory extracted from a session, before deduplication.
+ */
+export interface DraftMemory {
+    category: string;
+    content: string;
+    tags?: string[];
+}
+/**
+ * Deduplication decision for a single draft memory.
+ */
+export type DeduplicationAction = {
+    action: 'CREATE';
+    memory: DraftMemory;
+} | {
+    action: 'MERGE';
+    memory: DraftMemory;
+    mergedContent: string;
+    targetId: string;
+} | {
+    action: 'SKIP';
+    memory: DraftMemory;
+};
+/**
+ * LLM-based deduplicator for agent-extracted memories.
+ *
+ * For each draft, checks against existing memories via an LLM call.
+ * DECISIONS category drafts always result in CREATE (immutable log).
+ */
+export declare class MemoryDeduplicator {
+    private readonly generator;
+    constructor(generator: IContentGenerator);
+    /**
+     * Deduplicate a list of draft memories against existing stored memories.
+     *
+     * @param drafts - Draft memories to check
+     * @param existing - Existing memories to compare against
+     * @returns Deduplication action for each draft
+     */
+    deduplicate(drafts: DraftMemory[], existing: Memory[]): Promise<DeduplicationAction[]>;
+    private deduplicateSingle;
+}