byterover-cli 1.0.4 → 1.0.5

package/dist/infra/context-tree/file-context-file-reader.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
+import { MarkdownWriter } from '../../core/domain/knowledge/markdown-writer.js';
 /**
  * Extracts the title from the first markdown heading in the content.
  * @param content - The file content
@@ -27,9 +28,12 @@ export class FileContextFileReader {
         try {
             const content = await readFile(fullPath, 'utf8');
             const title = extractTitle(content, relativePath);
+            const parsedContent = MarkdownWriter.parseContent(content, title);
             return {
                 content,
+                narrative: parsedContent.narrative,
                 path: relativePath,
+                rawConcept: parsedContent.rawConcept,
                 title,
             };
         }

package/dist/infra/core/task-processor.d.ts

@@ -7,10 +7,10 @@ import type { IQueryExecutor } from '../../core/interfaces/executor/i-query-exec
  * Agent uses its default session (Single-Session pattern).
  */
 export type TaskInput = {
-    /** Task content/prompt */
-    content: string;
     /** Client's working directory for file validation */
     clientCwd?: string;
+    /** Task content/prompt */
+    content: string;
     /** Optional file paths for curate --files */
     files?: string[];
     /** Task ID */

package/dist/infra/process/process-manager.d.ts

@@ -47,6 +47,13 @@ export type ProcessManagerConfig = {
     /** Timeout for process startup (ms) */
     startupTimeoutMs?: number;
 };
+/**
+ * Options for starting the process manager.
+ */
+export type ProcessStartOptions = {
+    /** Session ID to pass to Agent process (for stateful sessions) */
+    sessionId?: string;
+};
 /**
  * ProcessManager - Spawns and manages Transport and Agent processes.
  *
@@ -57,6 +64,7 @@ export type ProcessManagerConfig = {
  * - Crash recovery: respawn on exit
  */
 export declare class ProcessManager {
+    private currentSessionId?;
     private healthCheckInterval?;
     private lastHealthCheckTime;
     private readonly shutdownTimeoutMs;
@@ -84,9 +92,10 @@ export declare class ProcessManager {
      * 3. Start Agent Process with TRANSPORT_PORT env
      * 4. Wait for Agent 'ready'
      *
+     * @param options - Start options including session ID for stateful sessions
      * @throws Error if startup fails or times out
      */
-    start(): Promise<void>;
+    start(options?: ProcessStartOptions): Promise<void>;
     /**
      * Stop all processes gracefully.
      *

package/dist/infra/process/process-manager.js

@@ -46,6 +46,7 @@ function createSystemError(error, context) {
  * - Crash recovery: respawn on exit
  */
 export class ProcessManager {
+    currentSessionId;
     healthCheckInterval;
     lastHealthCheckTime = Date.now();
     shutdownTimeoutMs;
@@ -86,12 +87,15 @@ export class ProcessManager {
      * 3. Start Agent Process with TRANSPORT_PORT env
      * 4. Wait for Agent 'ready'
      *
+     * @param options - Start options including session ID for stateful sessions
      * @throws Error if startup fails or times out
      */
-    async start() {
+    async start(options) {
         if (this.state.running) {
             return;
         }
+        // Store session ID for use when spawning agent
+        this.currentSessionId = options?.sessionId;
         // Step 1: Start Transport Process
         const port = await this.startTransportProcess();
         this.state.port = port;
@@ -235,12 +239,18 @@ export class ProcessManager {
     async startAgentProcess(transportPort) {
         return new Promise((resolve, reject) => {
             const workerPath = path.resolve(this.getWorkerDir(), 'agent-worker.js');
+            // Build environment variables for agent
+            const agentEnv = {
+                ...process.env,
+                BRV_SESSION_LOG: getSessionLogPath(),
+                TRANSPORT_PORT: String(transportPort),
+            };
+            // Pass session ID if provided (for stateful sessions)
+            if (this.currentSessionId) {
+                agentEnv.BYTEROVER_SESSION_ID = this.currentSessionId;
+            }
             const child = fork(workerPath, [], {
-                env: {
-                    ...process.env,
-                    BRV_SESSION_LOG: getSessionLogPath(),
-                    TRANSPORT_PORT: String(transportPort),
-                },
+                env: agentEnv,
                 stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
             });
             this.state.agentProcess = child;

package/dist/infra/process/transport-handlers.js

@@ -285,6 +285,37 @@ export class TransportHandlers {
                 this.transport.broadcast(TransportAgentEventNames.RESTARTED, { error: data.error, success: false });
             }
         });
+        // agent:newSession - Client requests a new session (ends current, starts fresh)
+        this.transport.onRequest(TransportAgentEventNames.NEW_SESSION, (data, clientId) => {
+            transportLog(`New session requested by ${clientId}: ${data.reason ?? 'no reason'}`);
+            if (!this.agentClientId) {
+                return { error: 'Agent not connected', success: false };
+            }
+            // Forward new session command to Agent
+            this.transport.sendTo(this.agentClientId, TransportAgentEventNames.NEW_SESSION, { reason: data.reason });
+            // The actual response will come via agent:newSessionCreated event
+            // For now, return success to indicate the request was forwarded
+            return { success: true };
+        });
+        // agent:newSessionCreated - Agent reports new session creation result
+        this.transport.onRequest(TransportAgentEventNames.NEW_SESSION_CREATED, (data) => {
+            if (data.success) {
+                transportLog(`New session created: ${data.sessionId}`);
+                eventLog('agent:newSessionCreated', { sessionId: data.sessionId, success: true });
+                this.transport.broadcast(TransportAgentEventNames.NEW_SESSION_CREATED, {
+                    sessionId: data.sessionId,
+                    success: true,
+                });
+            }
+            else {
+                transportLog(`New session creation failed: ${data.error}`);
+                eventLog('agent:newSessionCreated', { error: data.error, success: false });
+                this.transport.broadcast(TransportAgentEventNames.NEW_SESSION_CREATED, {
+                    error: data.error,
+                    success: false,
+                });
+            }
+        });
     }
     /**
      * Setup Agent-related handlers.

package/dist/infra/repl/commands/index.js

@@ -1,12 +1,13 @@
-import { clearCommand } from './clear-command.js';
 import { curateCommand } from './curate-command.js';
 import { genRulesCommand } from './gen-rules-command.js';
 import { initCommand } from './init-command.js';
 import { loginCommand } from './login-command.js';
 import { logoutCommand } from './logout-command.js';
+import { newCommand } from './new-command.js';
 import { pullCommand } from './pull-command.js';
 import { pushCommand } from './push-command.js';
 import { queryCommand } from './query-command.js';
+import { resetCommand } from './reset-command.js';
 import { spaceCommand } from './space/index.js';
 import { statusCommand } from './status-command.js';
 /**
@@ -27,7 +28,9 @@ export const load = () => [
     spaceCommand, // Switch/list spaces
     // Context tree management
     genRulesCommand, // Generate rule files
-    clearCommand, // Reset context tree (destructive)
+    resetCommand, // Reset context tree (destructive)
+    // Session management
+    newCommand, // Start fresh session (ends current, clears conversation)
     // Setup
     initCommand, // Project setup (once per project)
     // Auth

package/dist/infra/repl/commands/new-command.d.ts

@@ -0,0 +1,14 @@
+import { type SlashCommand } from '../../../tui/types.js';
+/**
+ * /new command - Start a fresh session.
+ *
+ * This command:
+ * 1. Marks the current session as 'ended'
+ * 2. Creates a new session ID
+ * 3. Updates the active session pointer
+ * 4. Clears conversation history from the TUI view
+ *
+ * Note: This command does NOT affect the context tree (use /clear for that).
+ * The actual session switching is handled by command-view.tsx after this command executes.
+ */
+export declare const newCommand: SlashCommand;

package/dist/infra/repl/commands/new-command.js

@@ -0,0 +1,61 @@
+import { CommandKind } from '../../../tui/types.js';
+import { ReplTerminal } from '../../terminal/repl-terminal.js';
+import { Flags, parseReplArgs, toCommandFlags } from './arg-parser.js';
+// Flags - defined once, used for both parsing and help display
+const newFlags = {
+    yes: Flags.boolean({
+        char: 'y',
+        default: false,
+        description: 'Skip confirmation prompt',
+    }),
+};
+// Args - no args needed
+const newArgs = {};
+/**
+ * /new command - Start a fresh session.
+ *
+ * This command:
+ * 1. Marks the current session as 'ended'
+ * 2. Creates a new session ID
+ * 3. Updates the active session pointer
+ * 4. Clears conversation history from the TUI view
+ *
+ * Note: This command does NOT affect the context tree (use /clear for that).
+ * The actual session switching is handled by command-view.tsx after this command executes.
+ */
+export const newCommand = {
+    action(_context, args) {
+        return {
+            async execute(onMessage, onPrompt) {
+                const terminal = new ReplTerminal({ onMessage, onPrompt });
+                const parsed = await parseReplArgs(args, {
+                    args: newArgs,
+                    flags: newFlags,
+                    strict: false,
+                });
+                // Show confirmation unless -y flag is passed
+                if (!parsed.flags.yes) {
+                    const confirmed = await terminal.confirm({
+                        default: false,
+                        message: 'Start a new session (ends current session and clears conversation history)',
+                    });
+                    if (!confirmed) {
+                        terminal.log('Cancelled.');
+                        return;
+                    }
+                }
+                terminal.log('Starting new session...');
+                // The actual session creation is handled by command-view.tsx
+                // after this command completes. It sends agent:newSession event.
+            },
+            type: 'streaming',
+        };
+    },
+    aliases: [],
+    args: [],
+    autoExecute: true,
+    description: 'Start a fresh session (ends current session, clears conversation)',
+    flags: toCommandFlags(newFlags),
+    kind: CommandKind.BUILT_IN,
+    name: 'new',
+};

package/dist/infra/repl/commands/{clear-command.d.ts → reset-command.d.ts}

@@ -1,5 +1,5 @@
 import { type SlashCommand } from '../../../tui/types.js';
 /**
- * clear command
+ * reset command
  */
-export declare const clearCommand: SlashCommand;
+export declare const resetCommand: SlashCommand;

package/dist/infra/repl/commands/{clear-command.js → reset-command.js}

@@ -2,10 +2,10 @@ import { CommandKind } from '../../../tui/types.js';
 import { FileContextTreeService } from '../../context-tree/file-context-tree-service.js';
 import { FileContextTreeSnapshotService } from '../../context-tree/file-context-tree-snapshot-service.js';
 import { ReplTerminal } from '../../terminal/repl-terminal.js';
-import { ClearUseCase } from '../../usecase/clear-use-case.js';
+import { ResetUseCase } from '../../usecase/reset-use-case.js';
 import { Args, Flags, parseReplArgs, toCommandFlags } from './arg-parser.js';
 // Flags - defined once, used for both parsing and help display
-const clearFlags = {
+const resetFlags = {
     yes: Flags.boolean({
         char: 'y',
         default: false,
@@ -13,26 +13,26 @@ const clearFlags = {
     }),
 };
 // Args - defined once for parsing
-const clearArgs = {
+const resetArgs = {
     directory: Args.string({
         description: 'Project directory (defaults to current directory)',
         required: false,
     }),
 };
 /**
- * clear command
+ * reset command
  */
-export const clearCommand = {
+export const resetCommand = {
     action(_context, args) {
         return {
             async execute(onMessage, onPrompt) {
                 const terminal = new ReplTerminal({ onMessage, onPrompt });
                 const parsed = await parseReplArgs(args, {
-                    args: clearArgs,
-                    flags: clearFlags,
+                    args: resetArgs,
+                    flags: resetFlags,
                     strict: false,
                 });
-                const useCase = new ClearUseCase({
+                const useCase = new ResetUseCase({
                     contextTreeService: new FileContextTreeService(),
                     contextTreeSnapshotService: new FileContextTreeSnapshotService(),
                     terminal,
@@ -55,7 +55,7 @@ export const clearCommand = {
     ],
     autoExecute: true,
     description: 'Reset the current context tree and start with 6 default domains',
-    flags: toCommandFlags(clearFlags),
+    flags: toCommandFlags(resetFlags),
     kind: CommandKind.BUILT_IN,
-    name: 'clear',
+    name: 'reset',
 };

package/dist/infra/usecase/generate-rules-use-case.js

@@ -69,7 +69,7 @@ export class GenerateRulesUseCase {
     async promptForFileCreation(agent, filePath) {
         return this.terminal.confirm({
             default: true,
-            message: `Rule file '${filePath}' doesn't exist. Create it with ByteRover rules?`,
+            message: `Rule file '${filePath}' doesn't exist. Create it with ByteRover rules`,
         });
     }
     /**
@@ -81,7 +81,7 @@ export class GenerateRulesUseCase {
     async promptForOverwriteConfirmation(agent) {
         return this.terminal.confirm({
             default: true,
-            message: `Rule file already exists for ${agent}. Overwrite?`,
+            message: `Rule file already exists for ${agent}. Overwrite`,
         });
     }
     async run() {

package/dist/infra/usecase/init-use-case.js

@@ -81,7 +81,7 @@ export class InitUseCase {
         this.terminal.log('  - Regenerate rule instructions\n');
         return this.terminal.confirm({
             default: false,
-            message: 'Continue with re-initialization?',
+            message: 'Continue with re-initialization',
         });
     }
     detectWorkspacesForAgent(agent) {
@@ -259,7 +259,7 @@ export class InitUseCase {
         this.terminal.log(' This folder and all its contents can be safely removed.\n');
         return this.terminal.confirm({
             default: true,
-            message: 'Remove the ACE folder and its contents?',
+            message: 'Remove the ACE folder and its contents',
         });
     }
     /**
@@ -314,7 +314,7 @@ export class InitUseCase {
     async promptForFileCreation(agent, filePath) {
         return this.terminal.confirm({
             default: true,
-            message: `Rule file '${filePath}' doesn't exist. Create it with ByteRover rules?`,
+            message: `Rule file '${filePath}' doesn't exist. Create it with ByteRover rules`,
         });
     }
     /**
@@ -324,7 +324,7 @@ export class InitUseCase {
     async promptForOverwriteConfirmation(agent) {
         return this.terminal.confirm({
             default: true,
-            message: `Rule file already exists for ${agent}. Overwrite?`,
+            message: `Rule file already exists for ${agent}. Overwrite`,
         });
     }
     async promptForSpaceSelection(spaces) {

package/dist/infra/usecase/logout-use-case.js

@@ -12,7 +12,7 @@ export class LogoutUseCase {
     async confirmLogout(userEmail) {
         return this.terminal.confirm({
             default: true,
-            message: `Logging out ${userEmail}. Are you sure?`,
+            message: `Logging out ${userEmail}. Are you sure`,
         });
     }
     async run(options) {

package/dist/infra/usecase/push-use-case.js

@@ -106,7 +106,7 @@ export class PushUseCase {
         this.terminal.log(`  Branch: ${branch}`);
         return this.terminal.confirm({
             default: false,
-            message: 'Push to ByteRover?',
+            message: 'Push to ByteRover',
         });
     }
     async validateAuth() {

package/dist/infra/usecase/{clear-use-case.d.ts → reset-use-case.d.ts}

@@ -1,18 +1,18 @@
 import type { IContextTreeService } from '../../core/interfaces/i-context-tree-service.js';
 import type { IContextTreeSnapshotService } from '../../core/interfaces/i-context-tree-snapshot-service.js';
 import type { ITerminal } from '../../core/interfaces/i-terminal.js';
-import type { IClearUseCase } from '../../core/interfaces/usecase/i-clear-use-case.js';
-export interface ClearUseCaseOptions {
+import type { IResetUseCase } from '../../core/interfaces/usecase/i-reset-use-case.js';
+export interface ResetUseCaseOptions {
     contextTreeService: IContextTreeService;
     contextTreeSnapshotService: IContextTreeSnapshotService;
     terminal: ITerminal;
 }
-export declare class ClearUseCase implements IClearUseCase {
+export declare class ResetUseCase implements IResetUseCase {
     private readonly contextTreeService;
     private readonly contextTreeSnapshotService;
     private readonly terminal;
-    constructor(options: ClearUseCaseOptions);
-    protected confirmClear(): Promise<boolean>;
+    constructor(options: ResetUseCaseOptions);
+    protected confirmReset(): Promise<boolean>;
     run(options: {
         directory?: string;
         skipConfirmation: boolean;

package/dist/infra/usecase/{clear-use-case.js → reset-use-case.js}

@@ -1,7 +1,7 @@
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
-export class ClearUseCase {
+export class ResetUseCase {
     contextTreeService;
     contextTreeSnapshotService;
     terminal;
@@ -11,10 +11,10 @@ export class ClearUseCase {
         this.terminal = options.terminal;
     }
     // Protected method for testability - can be overridden in tests
-    async confirmClear() {
+    async confirmReset() {
         return this.terminal.confirm({
             default: false,
-            message: 'Are you sure you want to reset the context tree? This will remove all existing context and restore default domains.',
+            message: 'Are you sure you want to reset the context tree? This will remove all existing context and restore default domains',
         });
     }
     async run(options) {
@@ -22,12 +22,12 @@ export class ClearUseCase {
             // Check if context tree exists
             const exists = await this.contextTreeService.exists(options.directory);
             if (!exists) {
-                this.terminal.log('No context tree found. Nothing to clear.');
+                this.terminal.log('No context tree found. Nothing to reset.');
                 return;
             }
             // Confirmation prompt (unless skipConfirmation is true)
             if (!options.skipConfirmation) {
-                const confirmed = await this.confirmClear();
+                const confirmed = await this.confirmReset();
                 if (!confirmed) {
                     this.terminal.log('Cancelled. Context tree was not reset.');
                     return;

package/dist/resources/prompts/curate.yml

@@ -10,8 +10,8 @@ prompt: |
   - the domains of the context (dynamically created based on content)
   - the topics of the context
   - the subtopics of the context (maximum one level under topics)
-  - the code snippets of the context
-  - the content of the context
+  - the structured metadata (Raw Concept) and descriptive context (Narrative)
+  - the code snippets of the context (optional, for backward compatibility)
 
   For doing that, you will need to acquire information from the chat history with the corresponding tools. Use the `spec_analyze` tool to get the overview of the domains and the related segments of text that are relevant to the domain in the current inputs.
 
@@ -31,6 +31,8 @@ prompt: |
      Use the `curate` tool to create new knowledge topics or update existing ones. Ensure that:
      - **Dynamic Domain Creation**: Create domains that are semantically meaningful for the content being curated
      - The context is well-structured and MUST meet **Context quality requirements**
+     - **Domain selection**: Always prefer predefined domains (code_style, design, structure, compliance, testing, bug_fixes). Only create custom domains if content clearly doesn't fit any predefined domain. Maximum 3 custom domains allowed.
+     - The context is well-structured and MUST use the **Two-Part Context Model**
      - There is no duplication with existing context
      - The information is clear and easy to understand
 
@@ -43,22 +45,71 @@ prompt: |
      - **Before creating a new domain**: Check if existing domains could accommodate the content
      - **Consolidate related concepts**: Group similar topics under the same domain for better organization
 
-  5. **Tool Execution Efficiency:**
-     - When multiple tools don't depend on each other's results, execute them in parallel with `batch`
-     - Example: `glob_files`, `list_directory`, `grep_content` and `read_file` operations for different files can run together
+  5. **Two-Part Context Model (REQUIRED)**: When creating context using the `curate` tool, you MUST use the structured format with `rawConcept` and `narrative`:
+
+     **rawConcept** - Captures essential metadata and technical footprint:
+     - `task`: What is the task/feature being documented (required - always include this)
+     - `changes`: Array of changes induced in the codebase (e.g., ["Added Redis caching", "Created singleton client"])
+     - `files`: Array of related files (e.g., ["services/auth.ts", "utils/cache.ts"])
+     - `flow`: The execution flow (e.g., "request -> validate -> cache check -> process -> respond")
+     - `timestamp`: When created (ISO 8601 format, e.g., "2025-03-18")
+
+     **narrative** - Captures descriptive and structural context:
+     - `structure`: Code structure documentation (describe file organization, class hierarchy, etc.)
+     - `dependencies`: Dependency management information (external libs, internal dependencies, initialization order)
+     - `features`: Feature documentation (behavior, limitations, edge cases, caching TTLs, etc.)
 
-  6. **Context quality requirements**: Each context in the `contexts` array must:
-     - Important: Minimum 2-4 sentences per context. Otherwise, DO NOT add that context.
-     - A developer should understand the concept without reading source code
+     **Example curate tool call:**
+     ```json
+     {
+       "type": "ADD",
+       "path": "structure/authentication",
+       "title": "JWT Token Handling",
+       "content": {
+         "rawConcept": {
+           "task": "Implement JWT-based authentication with refresh tokens",
+           "changes": [
+             "Added JWT verification middleware",
+             "Implemented refresh token rotation",
+             "Added token blacklist using Redis"
+           ],
+           "files": [
+             "src/middleware/auth.ts",
+             "src/services/token-service.ts",
+             "src/utils/jwt.ts"
+           ],
+           "flow": "request -> extract token -> verify JWT -> check blacklist -> attach user -> proceed",
+           "timestamp": "2025-01-02"
+         },
+         "narrative": {
+           "structure": "Authentication is handled by middleware in src/middleware/auth.ts which delegates to TokenService for JWT operations",
+           "dependencies": "Uses jsonwebtoken library for JWT operations, Redis for token blacklist with 24h TTL",
+           "features": "Access tokens expire in 15 minutes, refresh tokens in 7 days. Refresh token rotation invalidates old tokens immediately"
+         },
+         "relations": ["@structure/redis", "@design/security"]
+       },
+       "reason": "Documenting new JWT authentication system"
+     }
+     ```
+
+  6. **Context Quality Requirements**: Each context MUST:
+     - Include a clear `task` in rawConcept describing what the concept is about
+     - Provide at least one of: `changes`, `files`, or `flow` in rawConcept
+     - Include at least one narrative field (`structure`, `dependencies`, or `features`)
+     - Contain minimum 2-4 sentences per context - otherwise, DO NOT add that context
+     - Ensure a developer can understand the concept without reading source code
      - Include names of functions, classes, patterns, or key concepts
 
-   AVOID vague contexts like:
+     **AVOID** vague contexts like:
        - "Hook system"
        - "Error handling"
+       - Only snippets without rawConcept/narrative
+       - Missing task description
+       - Vague single-word descriptions
 
-   WRITE detailed contexts like:
+     **WRITE** detailed contexts like:
        - "The hook system allows registering callbacks for lifecycle events. Register hooks using
-        `HookRegistry.register(hookName, callback)` and trigger them with `HookRegistry.trigger(hookName, context)`. Hooks are used to:
+        `HookRegistry.register(hookName, callback)` and trigger them with `HookRegistry.trigger(hookName, context)`. Hooks
         support async callbacks and are commonly used for: pre/post tool execution, agent lifecycle events, and custom
         integrations."
 
@@ -66,7 +117,11 @@ prompt: |
         code, message, context object, and optional cause. Use `ErrorHandler.wrap(fn)` for consistent error boundaries across
         async operations."
 
-  7. **Response Format**:
+  7. **Tool Execution Efficiency**:
+     - When multiple tools don't depend on each other's results, execute them in parallel with `batch`
+     - Example: `glob_files`, `list_directory`, `grep_content` and `read_file` operations for different files can run together
+
+  8. **Response Format**:
      - Your final response must be a brief summary (1-2 sentences) describing what knowledge was curated
      - Do NOT include any file paths, directory paths, or specific location details in your response
-     - The system will automatically display created/updated file paths in a separate section 
+     - The system will automatically display created/updated file paths in a separate section