byterover-cli 0.3.5 → 0.4.0

package/dist/core/interfaces/cipher/i-key-storage.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Storage key as a tuple of string segments.
+ * Examples:
+ *   ["message", sessionId, messageId]
+ *   ["part", messageId, partId]
+ *   ["session", sessionId]
+ */
+export type StorageKey = readonly string[];
+/**
+ * Batch operation for atomic multi-key updates.
+ */
+export type BatchOperation = {
+    key: StorageKey;
+    type: 'delete';
+} | {
+    key: StorageKey;
+    type: 'set';
+    value: unknown;
+};
+/**
+ * Low-level key-value storage interface for granular persistence.
+ *
+ * Enables hierarchical data organization with prefix-based operations.
+ * Designed to support the OpenCode-style message/part storage pattern
+ * where messages and parts are stored at separate keys for selective loading.
+ *
+ * Key path structure:
+ * - ["session", sessionId] → Session metadata
+ * - ["message", sessionId, messageId] → Individual message
+ * - ["part", messageId, partId] → Message part (tool output, file, etc.)
+ */
+export interface IKeyStorage {
+    /**
+     * Batch operations for atomic multi-key updates.
+     * All operations succeed or fail together.
+     *
+     * @param operations - Array of set/delete operations
+     */
+    batch(operations: BatchOperation[]): Promise<void>;
+    /**
+     * Delete a value by its composite key.
+     *
+     * @param key - Composite key as string segments
+     * @returns True if the key existed and was deleted, false if not found
+     */
+    delete(key: StorageKey): Promise<boolean>;
+    /**
+     * Check if a key exists.
+     *
+     * @param key - Composite key as string segments
+     * @returns True if the key exists
+     */
+    exists(key: StorageKey): Promise<boolean>;
+    /**
+     * Get a value by its composite key.
+     *
+     * @param key - Composite key as string segments
+     * @returns The stored value, or undefined if not found
+     */
+    get<T>(key: StorageKey): Promise<T | undefined>;
+    /**
+     * Initialize the storage backend.
+     * Should be called once before any other operations.
+     */
+    initialize(): Promise<void>;
+    /**
+     * List all keys matching a prefix.
+     * Used for iterating over messages in a session or parts of a message.
+     *
+     * @param prefix - Key prefix to match (e.g., ["message", sessionId])
+     * @returns Array of matching full keys
+     */
+    list(prefix: StorageKey): Promise<StorageKey[]>;
+    /**
+     * Set a value at a composite key.
+     * Creates or overwrites the value at the key.
+     *
+     * @param key - Composite key as string segments
+     * @param value - Value to store (will be JSON serialized)
+     */
+    set<T>(key: StorageKey, value: T): Promise<void>;
+    /**
+     * Atomic update with optimistic locking.
+     * Reads the current value, applies the updater function, and writes back.
+     *
+     * @param key - Key to update
+     * @param updater - Function that receives current value and returns new value
+     * @returns The new value after update
+     */
+    update<T>(key: StorageKey, updater: (current: T | undefined) => T): Promise<T>;
+}

package/dist/core/interfaces/cipher/i-key-storage.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/i-global-config-store.d.ts

@@ -0,0 +1,34 @@
+import type { GlobalConfig } from '../domain/entities/global-config.js';
+/**
+ * Interface for storing and retrieving global ByteRover CLI configuration.
+ * Implementations handle persistence of user-level config (e.g., ~/.config/brv/config.json).
+ */
+export interface IGlobalConfigStore {
+    /**
+     * Gets the existing device ID or creates a new one if not present.
+     * This is the primary method for obtaining the device ID for tracking.
+     *
+     * @returns The device ID (existing or newly generated)
+     */
+    getOrCreateDeviceId: () => Promise<string>;
+    /**
+     * Reads the global configuration from the user's config directory.
+     *
+     * @returns The configuration if found and valid, undefined otherwise
+     */
+    read: () => Promise<GlobalConfig | undefined>;
+    /**
+     * Regenerates the device ID by creating a new UUID v4 and persisting it.
+     * Called when leaving authenticated state to break tracking continuity.
+     *
+     * @returns The newly generated device ID
+     */
+    regenerateDeviceId: () => Promise<string>;
+    /**
+     * Writes the global configuration to the user's config directory.
+     * Creates the directory if it doesn't exist.
+     *
+     * @param config The configuration to write
+     */
+    write: (config: GlobalConfig) => Promise<void>;
+}

package/dist/core/interfaces/i-global-config-store.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/i-onboarding-preference-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Store for onboarding preferences.
+ * Used to persist when onboarding was last dismissed to implement
+ * cooldown periods (e.g., show onboarding at most once per week).
+ */
+export interface IOnboardingPreferenceStore {
+    /**
+     * Get the timestamp when onboarding was last dismissed.
+     * Returns undefined if never dismissed.
+     */
+    getLastDismissedAt(): Promise<number | undefined>;
+    /**
+     * Set the timestamp when onboarding was dismissed.
+     */
+    setLastDismissedAt(timestamp: number): Promise<void>;
+    /**
+     * Clear the stored preference.
+     */
+    clear(): Promise<void>;
+}

package/dist/core/interfaces/i-onboarding-preference-store.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/i-terminal.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Choice option for select prompts.
+ */
+export interface SelectChoice<T> {
+    description?: string;
+    name: string;
+    value: T;
+}
+/**
+ * Search source function type.
+ */
+export type SearchSource<T> = (input: string | undefined) => Promise<SelectChoice<T>[]> | SelectChoice<T>[];
+/**
+ * Options for confirm prompt.
+ */
+export interface ConfirmOptions {
+    /** The default value (default: true) */
+    default?: boolean;
+    /** The confirmation message */
+    message: string;
+}
+/**
+ * Options for search prompt.
+ */
+export interface SearchOptions<T> {
+    /** The prompt message */
+    message: string;
+    /** Function that returns choices based on input */
+    source: SearchSource<T>;
+}
+/**
+ * Options for select prompt.
+ */
+export interface SelectOptions<T> {
+    /** The available choices */
+    choices: SelectChoice<T>[];
+    /** The prompt message */
+    message: string;
+}
+/**
+ * Options for input prompt.
+ */
+export interface InputOptions {
+    /** The prompt message */
+    message: string;
+    /** Validation function (return true if valid, or error message string) */
+    validate?: (value: string) => boolean | string;
+}
+/**
+ * File selector item representation.
+ */
+export interface FileSelectorItem {
+    /** Whether the item is a directory */
+    isDirectory: boolean;
+    /** The file/directory name */
+    name: string;
+    /** The full path to the item */
+    path: string;
+}
+/**
+ * Options for file selector prompt.
+ */
+export interface FileSelectorOptions {
+    /** Allow user to cancel selection */
+    allowCancel?: boolean;
+    /** Base path to start selection from */
+    basePath: string;
+    /** Filter function to show/hide items */
+    filter?: (item: Readonly<FileSelectorItem>) => boolean;
+    /** The prompt message */
+    message: string;
+    /** Number of items to show per page */
+    pageSize?: number;
+    /** Custom theme labels */
+    theme?: {
+        labels?: {
+            messages?: {
+                cancel?: string;
+                empty?: string;
+            };
+        };
+    };
+    /** Type of items to select: 'directory' or 'file' */
+    type?: 'directory' | 'file';
+}
+/**
+ * Interface for terminal interactions.
+ * Provides output and user input operations.
+ */
+export interface ITerminal {
+    /**
+     * Start a spinner/action indicator with a message.
+     * @param message The message to display while action is in progress
+     */
+    actionStart(message: string): void;
+    /**
+     * Stop the current spinner/action indicator.
+     * @param message Optional message to display when stopped
+     */
+    actionStop(message?: string): void;
+    /**
+     * Display a error message.
+     * @param message The message to display
+     */
+    error(message: string): void;
+    /**
+     * Display a message to the terminal.
+     * @param message The message to display (optional, empty line if omitted)
+     */
+    log(message?: string): void;
+    /**
+     * Display a warning message.
+     * @param message The message to display
+     */
+    warn(message: string): void;
+    /**
+     * Prompt the user for confirmation.
+     * @param options Confirmation options
+     * @returns Promise resolving to user's choice
+     */
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    /**
+     * Prompt the user to select a file or directory.
+     * @param options File selector options
+     * @returns Promise resolving to selected item, or null if cancelled
+     */
+    fileSelector(options: FileSelectorOptions): Promise<FileSelectorItem | null>;
+    /**
+     * Prompt the user for text input.
+     * @param options Input options
+     * @returns Promise resolving to user's input string
+     */
+    input(options: InputOptions): Promise<string>;
+    /**
+     * Prompt the user to search and select from options.
+     * @param options Search options
+     * @returns Promise resolving to selected value
+     */
+    search<T>(options: SearchOptions<T>): Promise<T>;
+    /**
+     * Prompt the user to select from a list of choices.
+     * @param options Select options
+     * @returns Promise resolving to selected value
+     */
+    select<T>(options: SelectOptions<T>): Promise<T>;
+}

package/dist/core/interfaces/i-terminal.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/i-workspace-detector-service.d.ts

@@ -0,0 +1,8 @@
+import type { Agent } from '../domain/entities/agent.js';
+export interface WorkspaceInfo {
+    chatLogPath: string;
+    cwd: string;
+}
+export interface IWorkspaceDetectorService {
+    detectWorkspaces(agent: Agent): WorkspaceInfo;
+}

package/dist/core/interfaces/i-workspace-detector-service.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-clear-use-case.d.ts

@@ -0,0 +1,6 @@
+export interface IClearUseCase {
+    run(options: {
+        directory?: string;
+        skipConfirmation: boolean;
+    }): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-clear-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-curate-use-case.d.ts

@@ -0,0 +1,10 @@
+export interface CurateUseCaseRunOptions {
+    apiKey?: string;
+    context?: string;
+    files?: string[];
+    model?: string;
+    verbose?: boolean;
+}
+export interface ICurateUseCase {
+    run(options: CurateUseCaseRunOptions): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-curate-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-generate-rules-use-case.d.ts

@@ -0,0 +1,3 @@
+export interface IGenerateRulesUseCase {
+    run(): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-generate-rules-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-init-use-case.d.ts

@@ -0,0 +1,5 @@
+export interface IInitUseCase {
+    run(options: {
+        force: boolean;
+    }): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-init-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-login-use-case.d.ts

@@ -0,0 +1,3 @@
+export interface ILoginUseCase {
+    run(): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-login-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-logout-use-case.d.ts

@@ -0,0 +1,5 @@
+export interface ILogoutUseCase {
+    run: (options: {
+        skipConfirmation: boolean;
+    }) => Promise<void>;
+}

package/dist/core/interfaces/usecase/i-logout-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-pull-use-case.d.ts

@@ -0,0 +1,5 @@
+export interface IPullUseCase {
+    run: (options: {
+        branch: string;
+    }) => Promise<void>;
+}

package/dist/core/interfaces/usecase/i-pull-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-push-use-case.d.ts

@@ -0,0 +1,6 @@
+export interface IPushUseCase {
+    run(options: {
+        branch: string;
+        skipConfirmation: boolean;
+    }): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-push-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-query-use-case.d.ts

@@ -0,0 +1,9 @@
+export interface QueryUseCaseRunOptions {
+    apiKey?: string;
+    model?: string;
+    query: string;
+    verbose?: boolean;
+}
+export interface IQueryUseCase {
+    run(options: QueryUseCaseRunOptions): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-query-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-space-list-use-case.d.ts

@@ -0,0 +1,3 @@
+export interface ISpaceListUseCase {
+    run(): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-space-list-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-space-switch-use-case.d.ts

@@ -0,0 +1,3 @@
+export interface ISpaceSwitchUseCase {
+    run(): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-space-switch-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/usecase/i-status-use-case.d.ts

@@ -0,0 +1,5 @@
+export interface IStatusUseCase {
+    run(options: {
+        cliVersion: string;
+    }): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-status-use-case.js

@@ -0,0 +1 @@
+export {};

package/dist/hooks/init/welcome.js

@@ -68,8 +68,7 @@ const hook = async function (options) {
         }
     }
     // Detect root help commands only (not command-specific help)
-    const isRootHelp = (options.id === undefined && options.argv.length === 0) || // bare `brv`
-        (options.id === '--help' && options.argv.length === 0) || // `brv --help`
+    const isRootHelp = (options.id === '--help' && options.argv.length === 0) || // `brv --help`
         (options.id === 'help' && options.argv.length === 0); // `brv help`
     if (isRootHelp) {
         const logo = [

package/dist/infra/cipher/agent-service-factory.d.ts

@@ -6,10 +6,10 @@ import type { CipherAgentServices, SessionServices } from '../../core/interfaces
  */
 export interface CipherLLMConfig {
     accessToken: string;
+    apiBaseUrl: string;
     apiKey?: string;
     blobStorageConfig?: Partial<BlobStorageConfig>;
     fileSystemConfig?: Partial<FileSystemConfig>;
-    grpcEndpoint: string;
     httpReferer?: string;
     maxIterations?: number;
     maxTokens?: number;
@@ -22,14 +22,21 @@ export interface CipherLLMConfig {
     temperature?: number;
     topK?: number;
     topP?: number;
+    /**
+     * Enable granular history storage for new sessions.
+     * When enabled, new sessions use per-message storage with streaming support.
+     * Existing sessions continue using blob storage (no migration).
+     * Default: false (use blob storage for all sessions)
+     */
+    useGranularStorage?: boolean;
     verbose?: boolean;
 }
 /**
- * gRPC configuration for ByteRover LLM service
+ * HTTP configuration for ByteRover LLM service
  */
-export interface ByteRoverGrpcConfig {
+export interface ByteRoverHttpConfig {
     accessToken: string;
-    grpcEndpoint: string;
+    apiBaseUrl: string;
     projectId: string;
     region?: string;
     sessionKey: string;
@@ -62,7 +69,7 @@ export declare function createCipherAgentServices(llmConfig: CipherLLMConfig): P
  *
  * @param sessionId - Unique session identifier
  * @param sharedServices - Shared services from agent
- * @param grpcConfig - gRPC configuration
+ * @param httpConfig - HTTP configuration
  * @param llmConfig - LLM service configuration
  * @param llmConfig.openRouterApiKey - Optional OpenRouter API key for OpenRouter service
  * @param llmConfig.httpReferer - Optional HTTP Referer for OpenRouter rankings
@@ -74,7 +81,7 @@ export declare function createCipherAgentServices(llmConfig: CipherLLMConfig): P
  * @param llmConfig.verbose - Enable verbose debug output
  * @returns Initialized session services
  */
-export declare function createSessionServices(sessionId: string, sharedServices: CipherAgentServices, grpcConfig: ByteRoverGrpcConfig, llmConfig: {
+export declare function createSessionServices(sessionId: string, sharedServices: CipherAgentServices, httpConfig: ByteRoverHttpConfig, llmConfig: {
     httpReferer?: string;
     maxIterations?: number;
     maxTokens?: number;

package/dist/infra/cipher/agent-service-factory.js

@@ -2,7 +2,7 @@ import { join } from 'node:path';
 import { createBlobStorage } from './blob/blob-storage-factory.js';
 import { AgentEventBus, SessionEventBus } from './events/event-emitter.js';
 import { FileSystemService } from './file-system/file-system-service.js';
-import { ByteRoverLlmGrpcService } from './grpc/internal-llm-grpc-service.js';
+import { ByteRoverLlmHttpService } from './http/internal-llm-http-service.js';
 import { ByteRoverContentGenerator, LoggingContentGenerator, RetryableContentGenerator } from './llm/generators/index.js';
 import { ByteRoverLLMService } from './llm/internal-llm-service.js';
 import { OpenRouterLLMService } from './llm/openrouter-llm-service.js';
@@ -11,6 +11,10 @@ import { EventBasedLogger } from './logger/event-based-logger.js';
 import { MemoryManager } from './memory/memory-manager.js';
 import { ProcessService } from './process/process-service.js';
 import { BlobHistoryStorage } from './storage/blob-history-storage.js';
+import { DualFormatHistoryStorage } from './storage/dual-format-history-storage.js';
+import { GranularHistoryStorage } from './storage/granular-history-storage.js';
+import { MessageStorageService } from './storage/message-storage-service.js';
+import { SqliteKeyStorage } from './storage/sqlite-key-storage.js';
 import { SimplePromptFactory } from './system-prompt/simple-prompt-factory.js';
 import { CoreToolScheduler } from './tools/core-tool-scheduler.js';
 import { DEFAULT_POLICY_RULES } from './tools/default-policy-rules.js';
@@ -82,7 +86,27 @@ export async function createCipherAgentServices(llmConfig) {
     const toolManager = new ToolManager(toolProvider, toolScheduler);
     await toolManager.initialize();
     // 11. History storage (depends on BlobStorage) - SHARED across sessions
-    const historyStorage = new BlobHistoryStorage(blobStorage);
+    // Use DualFormatHistoryStorage when granular storage is enabled
+    let historyStorage;
+    if (llmConfig.useGranularStorage) {
+        // Create granular storage infrastructure
+        const keyStorage = new SqliteKeyStorage({
+            storageDir: join(workingDirectory, '.brv'),
+        });
+        await keyStorage.initialize();
+        const messageStorage = new MessageStorageService(keyStorage);
+        const granularStorage = new GranularHistoryStorage(messageStorage);
+        const blobHistoryStorage = new BlobHistoryStorage(blobStorage);
+        // DualFormatHistoryStorage routes between formats:
+        // - New sessions → GranularHistoryStorage
+        // - Existing sessions → BlobHistoryStorage (no migration)
+        historyStorage = new DualFormatHistoryStorage(blobHistoryStorage, granularStorage);
+        logger.info('Granular history storage enabled for new sessions');
+    }
+    else {
+        // Default: use blob storage for all sessions
+        historyStorage = new BlobHistoryStorage(blobStorage);
+    }
     // Log successful initialization
     logger.info('CipherAgent services initialized successfully', {
         model: llmConfig.model,
@@ -116,7 +140,7 @@ export async function createCipherAgentServices(llmConfig) {
  *
  * @param sessionId - Unique session identifier
  * @param sharedServices - Shared services from agent
- * @param grpcConfig - gRPC configuration
+ * @param httpConfig - HTTP configuration
  * @param llmConfig - LLM service configuration
  * @param llmConfig.openRouterApiKey - Optional OpenRouter API key for OpenRouter service
  * @param llmConfig.httpReferer - Optional HTTP Referer for OpenRouter rankings
@@ -128,7 +152,7 @@ export async function createCipherAgentServices(llmConfig) {
  * @param llmConfig.verbose - Enable verbose debug output
  * @returns Initialized session services
  */
-export function createSessionServices(sessionId, sharedServices, grpcConfig, llmConfig) {
+export function createSessionServices(sessionId, sharedServices, httpConfig, llmConfig) {
     // 1. Create session-specific event bus
     const sessionEventBus = new SessionEventBus();
     // 2. Create session-scoped logger
@@ -157,20 +181,20 @@ export function createSessionServices(sessionId, sharedServices, grpcConfig, llm
         });
     }
     else {
-        // Use gRPC backend service (default) with new generator pattern
-        // Step 1: Create gRPC service
-        const grpcService = new ByteRoverLlmGrpcService({
-            accessToken: grpcConfig.accessToken,
-            grpcEndpoint: grpcConfig.grpcEndpoint,
-            projectId: grpcConfig.projectId,
-            region: grpcConfig.region,
-            sessionKey: grpcConfig.sessionKey,
-            spaceId: grpcConfig.spaceId,
-            teamId: grpcConfig.teamId,
-            timeout: grpcConfig.timeout,
+        // Use HTTP backend service (default) with new generator pattern
+        // Step 1: Create HTTP service
+        const httpService = new ByteRoverLlmHttpService({
+            accessToken: httpConfig.accessToken,
+            apiBaseUrl: httpConfig.apiBaseUrl,
+            projectId: httpConfig.projectId,
+            region: httpConfig.region,
+            sessionKey: httpConfig.sessionKey,
+            spaceId: httpConfig.spaceId,
+            teamId: httpConfig.teamId,
+            timeout: httpConfig.timeout,
         });
         // Step 2: Create base content generator
-        let generator = new ByteRoverContentGenerator(grpcService, {
+        let generator = new ByteRoverContentGenerator(httpService, {
             maxTokens: llmConfig.maxTokens ?? 8192,
             model: llmConfig.model ?? 'gemini-2.5-pro',
             temperature: llmConfig.temperature ?? 0.7,

package/dist/infra/cipher/cipher-agent.js

@@ -209,10 +209,10 @@ export class CipherAgent {
         // No need for upfront validation - let services handle their own setup
         // Create SHARED services only (following Dexto's pattern)
         const sharedServices = await createCipherAgentServices(this.llmConfig);
-        // Extract gRPC config from llmConfig
-        const grpcConfig = {
+        // Extract HTTP config from llmConfig
+        const httpConfig = {
             accessToken: this.llmConfig.accessToken,
-            grpcEndpoint: this.llmConfig.grpcEndpoint,
+            apiBaseUrl: this.llmConfig.apiBaseUrl,
             projectId: this.llmConfig.projectId,
             region: this.llmConfig.region,
             sessionKey: this.llmConfig.sessionKey,
@@ -231,7 +231,7 @@ export class CipherAgent {
             verbose: this.llmConfig.verbose,
         };
         // Create SessionManager with shared services
-        const sessionManager = new SessionManager(sharedServices, grpcConfig, sessionLLMConfig, {
+        const sessionManager = new SessionManager(sharedServices, httpConfig, sessionLLMConfig, {
             config: {
                 maxSessions: 100,
                 sessionTTL: 3_600_000, // 1 hour

package/dist/infra/cipher/consumer/consumer-lock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DB-based consumer lock utilities
+ *
+ * The actual locking is now handled by AgentStorage methods:
+ * - acquireConsumerLock(consumerId)
+ * - releaseConsumerLock(consumerId)
+ * - hasActiveConsumer(timeoutMs)
+ *
+ * These utility functions provide a simple interface for checking consumer status.
+ */
+/**
+ * Check if a consumer is currently running (has active heartbeat in DB)
+ * Auto-detects .brv/blobs path from cwd
+ */
+export declare function isConsumerRunning(): Promise<boolean>;
+/**
+ * Check if a consumer is currently running (sync version)
+ * Assumes storage is already initialized
+ */
+export declare function isConsumerRunningSync(): boolean;