byterover-cli 2.6.0 → 3.0.1

package/dist/agent/resources/prompts/system-prompt.yml

@@ -112,6 +112,7 @@ prompt: |
       path: 'design/alert_engine',
       title: 'Alert Engine',
       reason: 'Document alert engine architecture',
+      summary: 'Alert Engine consuming events with dedup and SLA-based routing',
       content: {
         rawConcept: { task: 'Document Alert Engine', flow: 'Events -> Router -> Routing' },
         narrative: { structure: 'Consumes events and routes alerts.', highlights: 'Deduplication, SLAs' }
@@ -318,7 +319,8 @@ prompt: |
     const result = await tools.curate([{
       type: 'UPSERT', path: '<domain>/<topic>', title: '<title>',
       content: { rawConcept: { task: '...', /* ... */ }, narrative: { /* ... */ } },
-      reason: 'Curate from RLM context'
+      reason: 'Curate from RLM context',
+      summary: 'One-line semantic summary of what this knowledge file contains'
     }]);
     // Verify inline — CurateResult.applied[].filePath already has paths
     const created = result.applied.filter(r => r.status === 'success').map(r => r.filePath);
@@ -379,12 +381,14 @@ prompt: |
 
   | Operation | When to Use | Required Fields |
   |-----------|-------------|-----------------|
-  | **UPSERT** | **PREFERRED** - Creates or updates automatically | path, title, content, reason |
-  | **ADD** | Only when you're certain file doesn't exist | path, title, content, reason |
-  | **UPDATE** | Only when you're certain file exists | path, title, content, reason |
-  | **MERGE** | Combining TWO EXISTING files | path, title, mergeTarget, mergeTargetTitle, reason |
+  | **UPSERT** | **PREFERRED** - Creates or updates automatically | path, title, content, reason, summary |
+  | **ADD** | Only when you're certain file doesn't exist | path, title, content, reason, summary |
+  | **UPDATE** | Only when you're certain file exists | path, title, content, reason, summary |
+  | **MERGE** | Combining TWO EXISTING files | path, title, mergeTarget, mergeTargetTitle, reason, summary |
   | **DELETE** | Removing file or folder | path, reason (title optional) |
 
+  **summary** — One-line semantic summary of what the knowledge file contains after this operation. Required for ADD/UPDATE/UPSERT/MERGE. Helps reviewers quickly grasp the content without reading the full document.
+
   **UPSERT is the recommended default:**
   - Automatically checks if file exists
   - Creates new file (ADD) if missing
@@ -427,6 +431,8 @@ prompt: |
       type: 'UPSERT',  // Auto-detects ADD vs UPDATE
       path: 'authentication/jwt',
       title: 'Token Handling',
+      reason: 'Documenting JWT authentication',
+      summary: 'JWT authentication with 15-min access tokens and refresh token rotation',
       content: {
         rawConcept: {
           task: 'Implement JWT authentication',
@@ -440,7 +446,6 @@ prompt: |
       },
       domainContext: { /* only for new domains */ },
       topicContext: { /* only for new topics */ },
-      reason: 'Documenting JWT authentication'
     }
   ]);
 
@@ -523,6 +528,8 @@ prompt: |
       type: 'UPSERT',  // Preferred - auto-detects ADD vs UPDATE
       path: 'structure/authentication',
       title: 'JWT Token Handling',
+      reason: 'Documenting new JWT authentication system',
+      summary: 'JWT auth with 15-min access tokens, 7-day refresh tokens, Redis blacklist, and token rotation',
       content: {
         rawConcept: {
           task: 'Implement JWT-based authentication with refresh tokens',
@@ -552,7 +559,6 @@ prompt: |
         },
         relations: ['@structure/redis/overview.md', '@design/security/token-validation.md']
       },
-      reason: 'Documenting new JWT authentication system'
     }
   ]);
   ```
@@ -564,6 +570,8 @@ prompt: |
       type: 'UPSERT',
       path: 'project_management/retrospectives',
       title: 'Sprint 13 Retro',
+      reason: 'Documenting Sprint 13 retrospective findings and action items',
+      summary: 'Sprint 13 retro: 34/35 points delivered, adopted mob programming and day-3 change cutoff',
       content: {
         rawConcept: {
           task: 'Sprint 13 Retrospective - Jan 22 to Feb 5, 2026',
@@ -585,7 +593,6 @@ prompt: |
         },
         relations: ['@project_management/sprints/sprint_14_review.md']
       },
-      reason: 'Documenting Sprint 13 retrospective findings and action items'
     }
   ]);
   ```

package/dist/agent/resources/tools/code_exec.txt

@@ -88,6 +88,9 @@ When calling `tools.*` methods, you **MUST** wrap code in an async IIFE:
     path: 'design/alert_engine',
     title: 'Alert Engine',
     reason: 'Document alert engine architecture',
+    summary: 'Alert Engine consuming events with dedup, escalation, and SLA-based routing to PagerDuty/Slack/Email',
+    confidence: 'high',
+    impact: 'low',
     content: {
       rawConcept: {
         task: 'Document the Alert Engine component',

package/dist/agent/resources/tools/curate.txt

@@ -21,9 +21,15 @@ Curate knowledge topics with atomic operations. This tool manages the knowledge
 - **snippets**: Code/text snippets (legacy support, optional)
 - **relations**: Related topics using @domain/topic notation
 
+**Per-Operation Metadata (required for all operations):**
+- **reason**: WHY this knowledge is being curated — the motivation for a human reviewer
+- **summary**: One-line semantic summary of what the knowledge file contains after this operation. Written for a human reviewer to quickly grasp the content. Example: "Caching strategy using Redis with 5-min TTL and write-through invalidation". Required for ADD/UPDATE/UPSERT/MERGE, not needed for DELETE.
+- **confidence**: "high" or "low" — your confidence in accuracy/completeness
+- **impact**: "high" or "low" — scope of change (see tool schema for details)
+
 **Operations:**
 1. **ADD** - Create new titled context file in domain/topic/subtopic
-   - Requires: path, title, content, reason
+   - Requires: path, title, content, reason, summary
    - Example with Raw Concept + Narrative:
      {
        type: "ADD",
@@ -46,12 +52,15 @@ Curate knowledge topics with atomic operations. This tool manages the knowledge
          },
          relations: ["@structure/database"]
        },
-       reason: "New caching pattern"
+       reason: "New caching pattern",
+       summary: "Redis caching layer for getUserPermissions with 300s TTL and singleton client pattern",
+       confidence: "high",
+       impact: "low"
      }
    - Creates: structure/caching/redis_user_permissions.md
 
 2. **UPDATE** - Modify existing titled context file (full replacement)
-   - Requires: path, title, content, reason
+   - Requires: path, title, content, reason, summary
    - Supports same content structure as ADD
 
 3. **MERGE** - Combine source file into target file, delete source

package/dist/oclif/commands/connectors/install.d.ts

@@ -3,7 +3,7 @@ import { type ConnectorInstallResponse } from '../../../shared/transport/events/
 import { type DaemonClientOptions } from '../../lib/daemon-client.js';
 export default class ConnectorsInstall extends Command {
     static args: {
-        agent: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        agent: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static description: string;
     static examples: string[];
@@ -27,5 +27,6 @@ export default class ConnectorsInstall extends Command {
         fromType: "rules" | "hook" | "mcp" | "skill" | undefined;
         result: ConnectorInstallResponse;
     }>;
+    protected promptForAgent(options?: DaemonClientOptions): Promise<string>;
     run(): Promise<void>;
 }

package/dist/oclif/commands/connectors/install.js

@@ -1,3 +1,4 @@
+import { select } from '@inquirer/prompts';
 import { Args, Command, Flags } from '@oclif/core';
 import { AGENT_CONNECTOR_CONFIG } from '../../../server/core/domain/entities/agent.js';
 import { ConnectorEvents, } from '../../../shared/transport/events/connector-events.js';
@@ -6,6 +7,7 @@ import { isConnectorType, requiresAgentRestart } from '../../../shared/types/con
 import { getConnectorName } from '../../../tui/features/connectors/utils/get-connector-name.js';
 import { withDaemonRetry } from '../../lib/daemon-client.js';
 import { writeJsonResponse } from '../../lib/json-response.js';
+import { isPromptCancelled } from '../../lib/prompt-utils.js';
 const agentTable = AGENT_VALUES.map((agent) => {
     const config = AGENT_CONNECTOR_CONFIG[agent];
     const supported = config.supported.map((type) => getConnectorName(type)).join(', ');
@@ -14,8 +16,8 @@ const agentTable = AGENT_VALUES.map((agent) => {
 export default class ConnectorsInstall extends Command {
     static args = {
         agent: Args.string({
-            description: 'Agent name to install connector for (e.g., "Claude Code", "Cursor")',
-            required: true,
+            description: 'Agent name to install connector for (e.g., "Claude Code", "Cursor"). Omit for interactive selection.',
+            required: false,
         }),
     };
     static description = `Install or switch a connector for an agent
@@ -81,12 +83,45 @@ ${agentTable}`;
             };
         }, options);
     }
+    async promptForAgent(options) {
+        const { agents } = await withDaemonRetry(async (client) => client.requestWithAck(ConnectorEvents.GET_AGENTS), options);
+        // Add a blank line before the prompt
+        this.log('');
+        return select({
+            choices: agents.map((a) => ({
+                description: `Connector type: ${getConnectorName(a.defaultConnectorType)}`,
+                name: a.name,
+                value: a.id,
+            })),
+            loop: false,
+            message: 'Select your coding agent to install the connector (type to search):',
+        });
+    }
     async run() {
         const { args, flags } = await this.parse(ConnectorsInstall);
+        let agentId = args.agent;
         const format = flags.format;
+        if (!agentId) {
+            if (format === 'json') {
+                writeJsonResponse({
+                    command: 'connectors install',
+                    data: { error: 'Agent argument is required for JSON output' },
+                    success: false,
+                });
+                return;
+            }
+            try {
+                agentId = await this.promptForAgent();
+            }
+            catch (error) {
+                if (!isPromptCancelled(error))
+                    throw error;
+                return; // user cancelled agent selection
+            }
+        }
         try {
             const installResult = await this.installConnector({
-                agentId: args.agent,
+                agentId,
                 connectorType: flags.type,
             });
             if (format === 'json') {

package/dist/oclif/commands/curate/index.d.ts

@@ -14,11 +14,29 @@ export default class Curate extends Command {
     };
     protected getDaemonClientOptions(): DaemonClientOptions;
     run(): Promise<void>;
+    /**
+     * Build the pendingReview JSON payload for --format json output.
+     * Uses server-authoritative count; files list is best-effort enrichment from tool results.
+     */
+    private buildPendingReviewJson;
+    /**
+     * Collect all operations requiring review from the completed tool calls.
+     * Best-effort enrichment: returns per-file detail when tool results include needsReview.
+     * The authoritative signal for whether review is required comes from ReviewEvents.NOTIFY.
+     */
+    private collectPendingReviewOps;
     /**
      * Extract file changes from collected tool calls (same logic as TUI useActivityLogs).
      */
     private composeChangesFromToolCalls;
     private extractChangesFromApplied;
+    private extractContextTreeRelativePath;
+    /**
+     * Print a human-readable pending review summary to stdout.
+     * Called after successful curate completion when review is required.
+     * pendingCount is server-authoritative; pendingOps provides best-effort per-file detail.
+     */
+    private printPendingReviewSummary;
     private reportError;
     private submitTask;
     private validateInput;

package/dist/oclif/commands/curate/index.js

@@ -1,5 +1,6 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { randomUUID } from 'node:crypto';
+import { BRV_DIR, CONTEXT_TREE_DIR } from '../../../server/constants.js';
 import { TransportStateEventNames } from '../../../server/core/domain/transport/index.js';
 import { extractCurateOperations } from '../../../server/utils/curate-result-parser.js';
 import { TaskEvents } from '../../../shared/transport/events/index.js';
@@ -105,6 +106,43 @@ Bad examples:
             this.reportError(error, format, providerContext);
         }
     }
+    /**
+     * Build the pendingReview JSON payload for --format json output.
+     * Uses server-authoritative count; files list is best-effort enrichment from tool results.
+     */
+    buildPendingReviewJson(pendingCount, pendingOps, taskId) {
+        return {
+            count: pendingCount,
+            files: pendingOps.map((op) => ({
+                after: op.summary,
+                before: op.previousSummary,
+                filePath: this.extractContextTreeRelativePath(op.filePath) ?? op.path,
+                impact: op.impact,
+                path: op.path,
+                reason: op.reason,
+                type: op.type,
+            })),
+            taskId,
+        };
+    }
+    /**
+     * Collect all operations requiring review from the completed tool calls.
+     * Best-effort enrichment: returns per-file detail when tool results include needsReview.
+     * The authoritative signal for whether review is required comes from ReviewEvents.NOTIFY.
+     */
+    collectPendingReviewOps(toolCalls) {
+        const pending = [];
+        for (const tc of toolCalls) {
+            if (tc.status !== 'completed')
+                continue;
+            const ops = extractCurateOperations({ result: tc.result, toolName: tc.toolName });
+            for (const op of ops) {
+                if (op.needsReview === true)
+                    pending.push(op);
+            }
+        }
+        return pending;
+    }
     /**
      * Extract file changes from collected tool calls (same logic as TUI useActivityLogs).
      */
@@ -138,6 +176,37 @@ Bad examples:
             }
         }
     }
+    extractContextTreeRelativePath(filePath) {
+        if (!filePath)
+            return undefined;
+        const marker = `${BRV_DIR}/${CONTEXT_TREE_DIR}/`;
+        const idx = filePath.indexOf(marker);
+        if (idx === -1)
+            return undefined;
+        return filePath.slice(idx + marker.length);
+    }
+    /**
+     * Print a human-readable pending review summary to stdout.
+     * Called after successful curate completion when review is required.
+     * pendingCount is server-authoritative; pendingOps provides best-effort per-file detail.
+     */
+    printPendingReviewSummary(pendingCount, pendingOps, taskId) {
+        this.log(`\n⚠  ${pendingCount} operation${pendingCount === 1 ? '' : 's'} require${pendingCount === 1 ? 's' : ''} review (task: ${taskId})`);
+        for (const op of pendingOps) {
+            const impact = op.impact === 'high' ? ' · HIGH IMPACT' : '';
+            const displayPath = this.extractContextTreeRelativePath(op.filePath) ?? op.path;
+            this.log(`\n  [${op.type}${impact}] - path: ${displayPath}`);
+            if (op.reason)
+                this.log(`  Why:   ${op.reason}`);
+            if (op.previousSummary)
+                this.log(`  Before: ${op.previousSummary.replaceAll('\n', '\n          ')}`);
+            if (op.summary)
+                this.log(`  After:  ${op.summary.replaceAll('\n', '\n          ')}`);
+        }
+        this.log(`\n  To approve all:  brv review approve ${taskId}`);
+        this.log(`  To reject all:   brv review reject ${taskId}`);
+        this.log(`  Per file:        brv review approve/reject ${taskId} --file <path> [--file <path>]`);
+    }
     reportError(error, format, providerContext) {
         const errorMessage = error instanceof Error ? error.message : 'Curate failed';
         if (format === 'json') {
@@ -184,8 +253,10 @@ Bad examples:
                 client,
                 command: 'curate',
                 format,
-                onCompleted: ({ logId, taskId: tid, toolCalls }) => {
+                onCompleted: ({ logId, pendingReview, taskId: tid, toolCalls }) => {
                     const changes = this.composeChangesFromToolCalls(toolCalls);
+                    // Per-file detail is best-effort enrichment; server notify is authoritative
+                    const pendingOps = pendingReview ? this.collectPendingReviewOps(toolCalls) : [];
                     if (format === 'text') {
                         for (const file of changes.created) {
                             this.log(`  add ${file}`);
@@ -195,6 +266,9 @@ Bad examples:
                         }
                         const logSuffix = logId ? ` (Log: ${logId})` : '';
                         this.log(`✓ Context curated successfully.${logSuffix}`);
+                        if (pendingReview) {
+                            this.printPendingReviewSummary(pendingReview.pendingCount, pendingOps, tid);
+                        }
                     }
                     else {
                         writeJsonResponse({
@@ -204,6 +278,9 @@ Bad examples:
                                 event: 'completed',
                                 logId,
                                 message: 'Context curated successfully',
+                                ...(pendingReview
+                                    ? { pendingReview: this.buildPendingReviewJson(pendingReview.pendingCount, pendingOps, tid) }
+                                    : {}),
                                 status: 'completed',
                                 taskId: tid,
                             },

package/dist/oclif/commands/init.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+import { type DaemonClientOptions } from '../lib/daemon-client.js';
+export default class Init extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static hidden: boolean;
+    protected getDaemonOptions(): DaemonClientOptions;
+    run(): Promise<void>;
+}

package/dist/oclif/commands/init.js

@@ -0,0 +1,75 @@
+/* eslint-disable no-unreachable */
+import { Command, Flags } from '@oclif/core';
+import { InitEvents } from '../../shared/transport/events/init-events.js';
+import { ProviderEvents } from '../../shared/transport/events/provider-events.js';
+import { formatConnectionError, withDaemonRetry } from '../lib/daemon-client.js';
+export default class Init extends Command {
+    static description = 'Initialize a ByteRover project in the current directory';
+    static examples = ['<%= config.bin %> <%= command.id %>', '<%= config.bin %> <%= command.id %> --force'];
+    static flags = {
+        force: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: 'Force re-initialization even if already initialized',
+        }),
+    };
+    static hidden = true;
+    getDaemonOptions() {
+        return { projectPath: process.cwd() };
+    }
+    async run() {
+        this.log('The init command is not available. Use: brv vc init');
+        return;
+        const { flags } = await this.parse(Init);
+        const daemonOptions = this.getDaemonOptions();
+        // Step 1: Local init (.brv/config.json + context tree)
+        try {
+            const response = await withDaemonRetry(async (client) => client.requestWithAck(InitEvents.LOCAL, { force: flags.force }), daemonOptions);
+            if (response.alreadyInitialized) {
+                this.log('ByteRover project already initialized.');
+                return;
+            }
+        }
+        catch (error) {
+            this.log(formatConnectionError(error));
+            return;
+        }
+        // Step 2: Version control init
+        try {
+            await this.config.runCommand('vc:init');
+        }
+        catch {
+            // vc:init logs its own errors
+            return;
+        }
+        // Step 3: Provider setup — only if no provider connected yet
+        let activeProviderId;
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(ProviderEvents.GET_ACTIVE), daemonOptions);
+            activeProviderId = result.activeProviderId;
+        }
+        catch (error) {
+            this.log(formatConnectionError(error));
+            return;
+        }
+        if (!activeProviderId) {
+            try {
+                await this.config.runCommand('providers:connect');
+            }
+            catch {
+                // providers:connect logs its own errors
+                return;
+            }
+        }
+        // Step 4: Connector setup — interactive agent selection + default connector
+        try {
+            await this.config.runCommand('connectors:install');
+        }
+        catch {
+            // connector setup is optional
+        }
+        this.log(`\nByteRover is ready in ${process.cwd()}`);
+        this.log('  Ask your coding agent to curate your project —');
+        this.log('  try "hey, curate the context for this project"');
+    }
+}

package/dist/oclif/commands/locations.js

@@ -24,7 +24,7 @@ export default class Locations extends Command {
         const { flags } = await this.parse(Locations);
         const isJson = flags.format === 'json';
         try {
-            const locations = await this.fetchLocations();
+            const locations = await this.fetchLocations({ projectPath: process.cwd() });
             if (isJson) {
                 writeJsonResponse({ command: 'locations', data: { locations }, success: true });
             }

package/dist/oclif/commands/providers/connect.d.ts

@@ -1,8 +1,10 @@
 import { Command } from '@oclif/core';
+import type { ProviderDTO } from '../../../shared/transport/types/dto.js';
+import { type ModelListResponse } from '../../../shared/transport/events/model-events.js';
 import { type DaemonClientOptions } from '../../lib/daemon-client.js';
 export default class ProviderConnect extends Command {
     static args: {
-        provider: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        provider: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static description: string;
     static examples: string[];
@@ -31,5 +33,33 @@ export default class ProviderConnect extends Command {
         providerName: string;
         showInstructions: boolean;
     }>;
+    protected disconnectProvider(providerId: string, options?: DaemonClientOptions): Promise<void>;
+    protected fetchModels(providerId: string, options?: DaemonClientOptions): Promise<ModelListResponse>;
+    protected fetchProviders(options?: DaemonClientOptions): Promise<ProviderDTO[]>;
+    protected promptForApiKey(providerName: string, apiKeyUrl?: string, signal?: AbortSignal): Promise<string>;
+    protected promptForAuthMethod(provider: ProviderDTO, signal?: AbortSignal): Promise<'api-key' | 'oauth'>;
+    protected promptForBaseUrl(signal?: AbortSignal): Promise<string>;
+    protected promptForConnectedAction(provider: ProviderDTO, signal?: AbortSignal): Promise<'activate' | 'disconnect' | 'reconfigure'>;
+    protected promptForModel(models: {
+        id: string;
+        name: string;
+    }[], signal?: AbortSignal): Promise<string | undefined>;
+    protected promptForOptionalApiKey(providerName: string, signal?: AbortSignal): Promise<string | undefined>;
+    protected promptForProvider(providers: ProviderDTO[], signal?: AbortSignal): Promise<string>;
     run(): Promise<void>;
+    /**
+     * Interactive flow with cancel-to-go-back navigation.
+     * Step 1 (provider) ← Step 2 (auth) ← Step 3 (model)
+     */
+    protected runInteractive(): Promise<void>;
+    protected runNonInteractive(providerId: string, flags: {
+        apiKey: string | undefined;
+        baseUrl: string | undefined;
+        code: string | undefined;
+        model: string | undefined;
+        oauth: boolean;
+    }, format: 'json' | 'text'): Promise<void>;
+    /** Returns true when wizard should end (skip model step), false to continue to model step. */
+    private runAuthStep;
+    private runModelStep;
 }