byterover-cli 1.0.3 → 1.0.5

package/dist/infra/cipher/session/session-metadata-store.js

@@ -0,0 +1,406 @@
+/**
+ * SessionMetadataStore - Manages session metadata persistence.
+ *
+ * Stores session metadata in .brv/sessions/ directory:
+ * - active.json: Current active session pointer
+ * - session-*.json: Individual session metadata files
+ *
+ * Design adapted from gemini-cli's ChatRecordingService pattern.
+ */
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { ACTIVE_SESSION_FILE, ActiveSessionPointerSchema, cleanMessageForTitle, generateSessionFilename, parseSessionFilename, SESSION_FILE_PREFIX, SessionMetadataSchema, SESSIONS_DIR, } from '../../../core/domain/cipher/session/session-metadata.js';
+/**
+ * Check if a process with given PID is running.
+ *
+ * @param pid - Process ID to check
+ * @returns True if process is running
+ */
+function isProcessRunning(pid) {
+    try {
+        // Sending signal 0 checks if process exists without actually sending a signal
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Session ID prefix used in the application.
+ */
+const SESSION_ID_PREFIX = 'agent-session-';
+/**
+ * Unique token for this process instance.
+ * Used to detect PID reuse: different process instance = different token,
+ * even if the OS assigned the same PID after the original process crashed.
+ */
+const PROCESS_TOKEN = randomUUID();
+/**
+ * Extract the UUID portion from a session ID.
+ *
+ * Session IDs have format: "agent-session-<UUID>" or just "<UUID>"
+ * This function handles both formats for backward compatibility.
+ *
+ * @param sessionId - The full session ID
+ * @returns The UUID portion without the prefix
+ */
+function extractUuidFromSessionId(sessionId) {
+    return sessionId.startsWith(SESSION_ID_PREFIX)
+        ? sessionId.slice(SESSION_ID_PREFIX.length)
+        : sessionId;
+}
+/**
+ * SessionMetadataStore implementation.
+ *
+ * Manages session metadata stored in .brv/sessions/ directory.
+ */
+export class SessionMetadataStore {
+    activeSessionPath;
+    sessionsDir;
+    workingDirectory;
+    /**
+     * Create a new SessionMetadataStore.
+     *
+     * @param workingDirectory - Project working directory (defaults to process.cwd())
+     */
+    constructor(workingDirectory) {
+        this.workingDirectory = workingDirectory ?? process.cwd();
+        this.sessionsDir = join(this.workingDirectory, '.brv', SESSIONS_DIR);
+        this.activeSessionPath = join(this.sessionsDir, ACTIVE_SESSION_FILE);
+    }
+    // ============================================================================
+    // Active Session Management
+    // ============================================================================
+    async cleanupSessions(config) {
+        const result = {
+            corruptedRemoved: 0,
+            deletedByAge: 0,
+            deletedByCount: 0,
+            remaining: 0,
+        };
+        try {
+            const files = await fs.readdir(this.sessionsDir);
+            const sessionFiles = files.filter((f) => f.startsWith(SESSION_FILE_PREFIX) && f.endsWith('.json'));
+            // IMPORTANT: Capture the active session ID as an immutable primitive BEFORE
+            // any file mutations. This prevents race conditions where concurrent cleanup
+            // operations could modify the active session pointer while we're iterating.
+            // Using a primitive string (not object reference) ensures we have a stable
+            // value to check against throughout the entire cleanup operation.
+            const active = await this.getActiveSession();
+            const activeSessionId = active?.sessionId;
+            const validSessions = [];
+            // First pass: identify corrupted files and valid sessions
+            for (const file of sessionFiles) {
+                const filePath = join(this.sessionsDir, file);
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const data = JSON.parse(content);
+                    const parseResult = SessionMetadataSchema.safeParse(data);
+                    if (!parseResult.success) {
+                        // Corrupted file - delete it
+                        // eslint-disable-next-line no-await-in-loop
+                        await fs.unlink(filePath);
+                        result.corruptedRemoved++;
+                        continue;
+                    }
+                    validSessions.push({ file, metadata: parseResult.data });
+                }
+                catch {
+                    // Can't read/parse - delete it
+                    try {
+                        // eslint-disable-next-line no-await-in-loop
+                        await fs.unlink(filePath);
+                        result.corruptedRemoved++;
+                    }
+                    catch {
+                        // Ignore delete errors
+                    }
+                }
+            }
+            // Sort by lastUpdated (newest first)
+            validSessions.sort((a, b) => new Date(b.metadata.lastUpdated).getTime() - new Date(a.metadata.lastUpdated).getTime());
+            const now = Date.now();
+            const maxAgeMs = config.maxAgeDays * 24 * 60 * 60 * 1000;
+            // Second pass: apply retention policies
+            for (const [i, { file, metadata }] of validSessions.entries()) {
+                // Never delete the current active session (uses captured primitive ID)
+                if (activeSessionId && metadata.sessionId === activeSessionId) {
+                    continue;
+                }
+                const age = now - new Date(metadata.lastUpdated).getTime();
+                const shouldDeleteByAge = age > maxAgeMs;
+                const shouldDeleteByCount = i >= config.maxCount;
+                const shouldDelete = shouldDeleteByAge || shouldDeleteByCount;
+                if (!shouldDelete) {
+                    continue;
+                }
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    await fs.unlink(join(this.sessionsDir, file));
+                    if (shouldDeleteByAge) {
+                        result.deletedByAge++;
+                    }
+                    else {
+                        result.deletedByCount++;
+                    }
+                }
+                catch {
+                    // Ignore delete errors
+                }
+            }
+            // Count remaining
+            const remainingFiles = await fs.readdir(this.sessionsDir);
+            result.remaining = remainingFiles.filter((f) => f.startsWith(SESSION_FILE_PREFIX) && f.endsWith('.json')).length;
+            return result;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return result;
+            }
+            throw error;
+        }
+    }
+    async clearActiveSession() {
+        try {
+            await fs.unlink(this.activeSessionPath);
+        }
+        catch (error) {
+            // Ignore if file doesn't exist
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Create a new session metadata object.
+     *
+     * @param sessionId - Session ID
+     * @returns New session metadata with defaults
+     */
+    createSessionMetadata(sessionId) {
+        const now = new Date().toISOString();
+        return {
+            createdAt: now,
+            lastUpdated: now,
+            messageCount: 0,
+            sessionId,
+            status: 'active',
+            workingDirectory: this.workingDirectory,
+        };
+    }
+    async deleteSession(sessionId) {
+        try {
+            const files = await fs.readdir(this.sessionsDir);
+            for (const file of files) {
+                if (!file.startsWith(SESSION_FILE_PREFIX) || !file.endsWith('.json')) {
+                    continue;
+                }
+                const parsed = parseSessionFilename(file);
+                // Extract UUID from sessionId (removes "agent-session-" prefix if present)
+                // then compare with the filename's uuid prefix
+                const uuid = extractUuidFromSessionId(sessionId);
+                if (parsed && uuid.startsWith(parsed.uuidPrefix)) {
+                    // eslint-disable-next-line no-await-in-loop
+                    await fs.unlink(join(this.sessionsDir, file));
+                    return true;
+                }
+                // Also check by reading the file to match full sessionId
+                try {
+                    const filePath = join(this.sessionsDir, file);
+                    // eslint-disable-next-line no-await-in-loop
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const data = JSON.parse(content);
+                    if (data.sessionId === sessionId) {
+                        // eslint-disable-next-line no-await-in-loop
+                        await fs.unlink(filePath);
+                        return true;
+                    }
+                }
+                catch {
+                    // Continue to next file
+                }
+            }
+            return false;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async getActiveSession() {
+        try {
+            const content = await fs.readFile(this.activeSessionPath, 'utf8');
+            const data = JSON.parse(content);
+            const result = ActiveSessionPointerSchema.safeParse(data);
+            if (!result.success) {
+                // Invalid format - treat as no active session
+                return null;
+            }
+            return result.data;
+        }
+        catch (error) {
+            // File doesn't exist or can't be read
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async getSession(sessionId) {
+        const sessions = await this.listSessions();
+        return sessions.find((s) => s.sessionId === sessionId) ?? null;
+    }
+    async isActiveSessionStale() {
+        const active = await this.getActiveSession();
+        if (!active) {
+            return false;
+        }
+        // If the process is not running, the session is definitely stale
+        if (!isProcessRunning(active.pid)) {
+            return true;
+        }
+        // If process is running but token is missing or doesn't match,
+        // it's either an old session file or a different process with the same PID.
+        // Both cases indicate a stale session.
+        if (!active.processToken || active.processToken !== PROCESS_TOKEN) {
+            return true;
+        }
+        return false;
+    }
+    async isSessionForCurrentProject(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            return false;
+        }
+        return session.workingDirectory === this.workingDirectory;
+    }
+    async listSessions() {
+        try {
+            await this.ensureSessionsDir();
+            const files = await fs.readdir(this.sessionsDir);
+            const sessionFiles = files.filter((f) => f.startsWith(SESSION_FILE_PREFIX) && f.endsWith('.json'));
+            const active = await this.getActiveSession();
+            const sessions = [];
+            for (const file of sessionFiles) {
+                try {
+                    const filePath = join(this.sessionsDir, file);
+                    // eslint-disable-next-line no-await-in-loop
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const data = JSON.parse(content);
+                    const result = SessionMetadataSchema.safeParse(data);
+                    if (!result.success) {
+                        // Skip corrupted files
+                        continue;
+                    }
+                    const metadata = result.data;
+                    const isCurrentSession = active?.sessionId === metadata.sessionId;
+                    sessions.push({
+                        ...metadata,
+                        file: file.replace('.json', ''),
+                        fileName: file,
+                        firstUserMessage: metadata.title,
+                        index: 0, // Will be set after sorting
+                        isCurrentSession,
+                    });
+                }
+                catch {
+                    // Skip files that can't be read or parsed
+                    continue;
+                }
+            }
+            // Sort by lastUpdated (newest first)
+            sessions.sort((a, b) => new Date(b.lastUpdated).getTime() - new Date(a.lastUpdated).getTime());
+            // Set 1-based indexes
+            for (const [index, session] of sessions.entries()) {
+                session.index = index + 1;
+            }
+            return sessions;
+        }
+        catch (error) {
+            // Directory doesn't exist
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    // ============================================================================
+    // Session Lifecycle
+    // ============================================================================
+    async markSessionEnded(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            session.status = 'ended';
+            session.lastUpdated = new Date().toISOString();
+            await this.saveSession(session);
+        }
+    }
+    async markSessionInterrupted(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            session.status = 'interrupted';
+            session.lastUpdated = new Date().toISOString();
+            await this.saveSession(session);
+        }
+    }
+    async saveSession(metadata) {
+        await this.ensureSessionsDir();
+        // Find existing file for this session or create new
+        let filename;
+        try {
+            const files = await fs.readdir(this.sessionsDir);
+            const existingFile = files.find((f) => {
+                if (!f.startsWith(SESSION_FILE_PREFIX) || !f.endsWith('.json')) {
+                    return false;
+                }
+                const parsed = parseSessionFilename(f);
+                // Extract UUID from sessionId and compare with filename's uuid prefix
+                const uuid = extractUuidFromSessionId(metadata.sessionId);
+                return parsed && uuid.startsWith(parsed.uuidPrefix);
+            });
+            filename = existingFile ?? generateSessionFilename(metadata.sessionId);
+        }
+        catch {
+            filename = generateSessionFilename(metadata.sessionId);
+        }
+        const filePath = join(this.sessionsDir, filename);
+        await fs.writeFile(filePath, JSON.stringify(metadata, null, 2), 'utf8');
+    }
+    async setActiveSession(sessionId) {
+        await this.ensureSessionsDir();
+        const pointer = {
+            activatedAt: new Date().toISOString(),
+            pid: process.pid,
+            processToken: PROCESS_TOKEN,
+            sessionId,
+        };
+        await fs.writeFile(this.activeSessionPath, JSON.stringify(pointer, null, 2), 'utf8');
+    }
+    async setSessionTitle(sessionId, title) {
+        const session = await this.getSession(sessionId);
+        if (session && !session.title) {
+            session.title = cleanMessageForTitle(title);
+            session.lastUpdated = new Date().toISOString();
+            await this.saveSession(session);
+        }
+    }
+    async updateSessionActivity(sessionId, messageCount) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            session.lastUpdated = new Date().toISOString();
+            session.messageCount = messageCount;
+            await this.saveSession(session);
+        }
+    }
+    /**
+     * Ensure the sessions directory exists.
+     */
+    async ensureSessionsDir() {
+        await fs.mkdir(this.sessionsDir, { recursive: true });
+    }
+}

package/dist/infra/cipher/system-prompt/contributors/context-tree-structure-contributor.js

@@ -92,7 +92,7 @@ export class ContextTreeStructureContributor {
         if (truncatedCount.value > 0) {
             parts.push('', `[${truncatedCount.value} additional entries not shown]`);
         }
-        parts.push('', '## Structure Guide', '- Each top-level folder is a **domain** (e.g., `code_style/`, `design/`, `structure/`)', '- Inside domains are **topics** as `.md` files or subfolders with `context.md`', '- `context.md` files contain the curated knowledge content', '', '## Usage', '- **Query commands**: Search ONLY within this context tree structure', '- **Curate commands**: Check existing content here before creating new topics', '</context-tree-structure>');
+        parts.push('', '## Structure Guide', '- Each top-level folder is a **domain** (dynamically created based on content)', '- Inside domains are **topics** as `.md` files or subfolders with `context.md`', '- `context.md` files contain the curated knowledge content', '', '## Dynamic Domains', '- Domains are created dynamically based on the semantics of curated content', '- Domain names should be descriptive, use snake_case (e.g., `authentication`, `api_design`)', '- Before creating a new domain, check if existing domains could accommodate the content', '', '## Usage', '- **Query commands**: Search ONLY within this context tree structure', '- **Curate commands**: Check existing domains/topics before creating new ones', '</context-tree-structure>');
         return parts.join('\n');
     }
     /**
@@ -105,7 +105,9 @@ export class ContextTreeStructureContributor {
             '',
             'The context tree at `.brv/context-tree/` exists but contains no curated content yet.',
             '',
-            '**For curate commands**: You can create new knowledge topics in any domain.',
+            '**For curate commands**: Create new domains and topics dynamically based on content.',
+            '- Choose semantically meaningful domain names (e.g., `authentication`, `api_design`, `data_models`)',
+            '- Use snake_case format for domain names',
             '**For query commands**: No context is available to search.',
             '</context-tree-structure>',
         ].join('\n');

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

@@ -7,16 +7,16 @@ import { sanitizeFolderName } from '../../../../utils/file-helpers.js';
 const CreateKnowledgeTopicInputSchema = z.object({
     // Base path for knowledge storage
     basePath: z.string().default('.brv/context-tree'),
-    domains: z.array(z.string()).describe('Array of domain names'),
+    domains: z.array(z.string()).describe('Array of domain names (dynamically created based on content)'),
     // Manual topics (optional)
     topics: z
         .array(z.object({
-        domain: z.string().describe('Domain category name from predefined list'),
+        domain: z.string().describe('Domain category name (can be any semantically meaningful name)'),
         name: z.string().describe('Topic name'),
         relations: z
             .array(z.string())
             .optional()
-            .describe('Related topics using @domain/topic or @domain/topic/subtopic notation'),
+            .describe('Related topics using domain/topic or domain/topic/subtopic notation'),
         snippets: z.array(z.string()).describe('Code/text snippets'),
         subtopics: z
             .array(z.object({
@@ -24,7 +24,7 @@ const CreateKnowledgeTopicInputSchema = z.object({
             relations: z
                 .array(z.string())
                 .optional()
-                .describe('Related topics using @domain/topic or @domain/topic/subtopic notation'),
+                .describe('Related topics using domain/topic or domain/topic/subtopic notation'),
             snippets: z.array(z.string()).describe('Code/text snippets'),
         }))
             .describe('Array of subtopics'),
@@ -112,27 +112,34 @@ async function executeCreateKnowledgeTopic(input, _context) {
  */
 export function createCreateKnowledgeTopicTool() {
     return {
-        description: `Create organized knowledge topics within domain folders. This tool structures knowledge by creating topic and subtopic folders, each containing a context.md file with relevant snippets and optional relations.
+        description: `Create organized knowledge topics within dynamically-created domain folders. This tool structures knowledge by creating domain, topic, and subtopic folders, each containing a context.md file with relevant snippets and optional relations.
 
-Use this tool after detecting domains to organize extracted knowledge into a hierarchical structure:
-- Domain folders (e.g., .brv/context-tree/domain-name/)
-- Topic folders (e.g., .brv/context-tree/domain-name/topic-name/)
-- Topic context.md files (e.g., .brv/context-tree/domain-name/topic-name/context.md)
-- Subtopic folders (e.g., .brv/context-tree/domain-name/topic-name/subtopic-name/)
-- Subtopic context.md files (e.g., .brv/context-tree/domain-name/topic-name/subtopic-name/context.md)
+**Dynamic Domain Creation:**
+Domains are created dynamically based on the content being organized. Choose domain names that:
+- Are semantically meaningful and descriptive (e.g., "authentication", "api_design", "data_models")
+- Use snake_case format (1-3 words)
+- Group related concepts together
+- Avoid overly generic names (e.g., "misc", "other") or overly specific names
 
-Each topic should include:
+**Hierarchical Structure:**
+- Domain folders (e.g., .brv/context-tree/authentication/)
+- Topic folders (e.g., .brv/context-tree/authentication/oauth_flow/)
+- Topic context.md files (e.g., .brv/context-tree/authentication/oauth_flow/context.md)
+- Subtopic folders (e.g., .brv/context-tree/authentication/oauth_flow/token_refresh/)
+- Subtopic context.md files (e.g., .brv/context-tree/authentication/oauth_flow/token_refresh/context.md)
+
+**Each topic should include:**
 1. A clear topic name
 2. Relevant code/text snippets that demonstrate the knowledge
-3. Optional relations to other topics using @domain/topic or @domain/topic/subtopic notation
+3. Optional relations to other topics using domain/topic or domain/topic/subtopic notation
 4. Subtopics (optional) that break down the topic into smaller pieces
 
-Relations enhance knowledge discovery by linking related contexts. Example:
-- relations: ['code_style/error-handling', 'structure/api-endpoints/validation']
+**Relations** enhance knowledge discovery by linking related contexts. Example:
+- relations: ['authentication/session_management', 'api_design/endpoints/validation']
 
-The tool automatically:
+**The tool automatically:**
 - Creates the base knowledge structure if it doesn't exist
-- Creates topic and subtopic folders as needed
+- Creates domain, topic, and subtopic folders as needed
 - Generates context.md files with snippets and relations
 - Handles existing topics gracefully (updates instead of recreating)`,
         execute: executeCreateKnowledgeTopic,