byterover-cli 0.2.1 → 0.3.0

package/dist/core/interfaces/cipher/i-tool-scheduler.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Tool Scheduler Interface.
+ *
+ * Orchestrates tool execution with:
+ * 1. Policy checking (ALLOW/DENY)
+ * 2. State tracking (pending → executing → completed/failed/denied)
+ * 3. Execution history for debugging/auditing
+ *
+ * Based on gemini-cli's CoreToolScheduler pattern, simplified for autonomous mode.
+ */
+import type { PolicyEvaluationResult } from './i-policy-engine.js';
+/**
+ * Status of a scheduled tool execution.
+ */
+export type ScheduledToolStatus = 'completed' | 'denied' | 'executing' | 'failed' | 'pending';
+/**
+ * Represents a scheduled tool execution with tracking information.
+ */
+export interface ScheduledToolExecution {
+    /**
+     * Arguments passed to the tool.
+     */
+    args: Record<string, unknown>;
+    /**
+     * When execution completed (success, failure, or denial).
+     */
+    completedAt?: Date;
+    /**
+     * Error that occurred (if failed or denied).
+     */
+    error?: Error;
+    /**
+     * Unique identifier for this execution.
+     */
+    id: string;
+    /**
+     * Result of policy evaluation (if performed).
+     */
+    policyResult?: PolicyEvaluationResult;
+    /**
+     * Tool execution result (if completed successfully).
+     */
+    result?: unknown;
+    /**
+     * When execution started.
+     */
+    startedAt?: Date;
+    /**
+     * Current status of the execution.
+     */
+    status: ScheduledToolStatus;
+    /**
+     * Name of the tool being executed.
+     */
+    toolName: string;
+}
+/**
+ * Context for tool execution.
+ */
+export interface ToolSchedulerContext {
+    /**
+     * Session ID for the current session.
+     */
+    sessionId: string;
+}
+/**
+ * Interface for the tool scheduler.
+ *
+ * The scheduler coordinates tool execution by:
+ * 1. Checking policy rules before execution
+ * 2. Tracking execution state transitions
+ * 3. Maintaining execution history for debugging
+ */
+export interface IToolScheduler {
+    /**
+     * Clear execution history.
+     * Useful for testing or memory management.
+     */
+    clearHistory(): void;
+    /**
+     * Schedule and execute a tool call.
+     *
+     * Flow:
+     * 1. Create execution record (pending)
+     * 2. Evaluate policy (ALLOW/DENY)
+     * 3. If ALLOW: execute tool (executing → completed/failed)
+     * 4. If DENY: throw error (denied)
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Arguments for the tool
+     * @param context - Execution context with session info
+     * @returns Tool execution result
+     * @throws Error if tool is denied by policy or execution fails
+     */
+    execute(toolName: string, args: Record<string, unknown>, context: ToolSchedulerContext): Promise<unknown>;
+    /**
+     * Get execution history for debugging/auditing.
+     * Returns most recent executions (implementation may limit size).
+     *
+     * @returns Read-only array of scheduled executions
+     */
+    getHistory(): readonly ScheduledToolExecution[];
+}

package/dist/core/interfaces/cipher/i-tool-scheduler.js

@@ -0,0 +1,11 @@
+/**
+ * Tool Scheduler Interface.
+ *
+ * Orchestrates tool execution with:
+ * 1. Policy checking (ALLOW/DENY)
+ * 2. State tracking (pending → executing → completed/failed/denied)
+ * 3. Execution history for debugging/auditing
+ *
+ * Based on gemini-cli's CoreToolScheduler pattern, simplified for autonomous mode.
+ */
+export {};

package/dist/core/interfaces/cipher/llm-types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared types for LLM providers.
+ * These types are common across all LLM provider implementations.
+ */
+/**
+ * Tool definition for LLM function calling.
+ * Describes a function that the LLM can call during execution.
+ */
+export type Tool = {
+    /** Description of what the tool does */
+    description: string;
+    /** The name of the tool/function */
+    name: string;
+    /** JSON Schema defining the parameters */
+    parameters: {
+        properties: Record<string, unknown>;
+        required?: string[];
+        type: 'object';
+    };
+};
+/**
+ * Executor function that implements the actual tool logic.
+ * Called by the LLM provider when the model requests a tool execution.
+ *
+ * @param name - The name of the tool being executed
+ * @param args - The arguments passed by the LLM
+ * @returns The result as a string to be sent back to the LLM
+ */
+export type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<string>;
+/**
+ * Base configuration shared by all LLM providers.
+ */
+export type BaseLlmConfig = {
+    /** API key for authentication */
+    apiKey: string;
+    /** Maximum iterations for agentic loops */
+    maxIterations?: number;
+    /** Maximum tokens in the response */
+    maxTokens?: number;
+    /** Model name/identifier */
+    model?: string;
+    /** Temperature for randomness (0-1) */
+    temperature?: number;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+};

package/dist/core/interfaces/cipher/llm-types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for LLM providers.
+ * These types are common across all LLM provider implementations.
+ */
+export {};

package/dist/core/interfaces/cipher/message-types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Internal representation of messages in a conversation.
+ * Standardizes message format across different LLM providers.
+ */
+/**
+ * Text content part
+ */
+export interface TextPart {
+    text: string;
+    type: 'text';
+}
+/**
+ * Image content part
+ */
+export interface ImagePart {
+    image: ArrayBuffer | Buffer | string | Uint8Array | URL;
+    mimeType?: string;
+    type: 'image';
+}
+/**
+ * File content part
+ */
+export interface FilePart {
+    data: ArrayBuffer | Buffer | string | Uint8Array | URL;
+    filename?: string;
+    mimeType: string;
+    type: 'file';
+}
+/**
+ * Union type for message content parts
+ */
+export type MessagePart = FilePart | ImagePart | TextPart;
+/**
+ * Tool call made by the assistant
+ */
+export interface ToolCall {
+    /**
+     * Function call details
+     */
+    function: {
+        /**
+         * Arguments for the function in JSON string format
+         */
+        arguments: string;
+        /**
+         * Name of the function to call
+         */
+        name: string;
+    };
+    /**
+     * Unique identifier for this tool call
+     */
+    id: string;
+    /**
+     * The type of tool call (currently only 'function' is supported)
+     */
+    type: 'function';
+}
+/**
+ * Internal message representation used across all LLM providers.
+ * This standardized format is converted to/from provider-specific formats by formatters.
+ */
+export interface InternalMessage {
+    /**
+     * The content of the message.
+     * - String for system, assistant (text only), and tool messages.
+     * - Array of parts for user messages (can include text, images, and files).
+     * - null if an assistant message only contains tool calls.
+     */
+    content: Array<MessagePart> | null | string;
+    /**
+     * Name of the tool that produced this result.
+     * Only present in tool messages.
+     */
+    name?: string;
+    /**
+     * Optional model reasoning text associated with an assistant response.
+     * Present when the provider supports reasoning and returns a final reasoning trace.
+     */
+    reasoning?: string;
+    /**
+     * The role of the entity sending the message.
+     * - 'system': System instructions or context
+     * - 'user': End-user input
+     * - 'assistant': LLM response
+     * - 'tool': Result from a tool execution
+     */
+    role: 'assistant' | 'system' | 'tool' | 'user';
+    /**
+     * Raw thought text from the model (Gemini only).
+     * Contains the model's thinking process before generating a response.
+     */
+    thought?: string;
+    /**
+     * Parsed thought summary with subject and description (Gemini only).
+     * Extracted from the thought text for easier display.
+     */
+    thoughtSummary?: {
+        /**
+         * Detailed description of the thought
+         */
+        description: string;
+        /**
+         * Brief subject of the thought
+         */
+        subject: string;
+    };
+    /**
+     * ID of the tool call this message is responding to.
+     * Only present in tool messages.
+     */
+    toolCallId?: string;
+    /**
+     * Tool calls made by the assistant.
+     * Only present in assistant messages when the LLM requests tool execution.
+     */
+    toolCalls?: ToolCall[];
+}

package/dist/core/interfaces/cipher/message-types.js

@@ -0,0 +1,5 @@
+/**
+ * Internal representation of messages in a conversation.
+ * Standardizes message format across different LLM providers.
+ */
+export {};

package/dist/core/interfaces/cipher/tokenizer-types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Custom error class for tokenization-related errors.
+ * Used to distinguish tokenization failures from other types of errors.
+ */
+export declare class TokenizationError extends Error {
+    /**
+     * Creates a new TokenizationError
+     * @param message - Error message describing what went wrong
+     */
+    constructor(message: string);
+}

package/dist/core/interfaces/cipher/tokenizer-types.js

@@ -0,0 +1,14 @@
+/**
+ * Custom error class for tokenization-related errors.
+ * Used to distinguish tokenization failures from other types of errors.
+ */
+export class TokenizationError extends Error {
+    /**
+     * Creates a new TokenizationError
+     * @param message - Error message describing what went wrong
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'TokenizationError';
+    }
+}

package/dist/core/interfaces/i-cogit-pull-service.d.ts

@@ -0,0 +1,24 @@
+import type { CogitSnapshot } from '../domain/entities/cogit-snapshot.js';
+/**
+ * Parameters for pulling a snapshot from CoGit.
+ */
+export type PullParams = {
+    accessToken: string;
+    branch: string;
+    sessionKey: string;
+    spaceId: string;
+    teamId: string;
+};
+/**
+ * Interface for pulling context tree snapshots from the CoGit service.
+ * Retrieves the complete state of context files from a CoGit repository.
+ */
+export interface ICogitPullService {
+    /**
+     * Pulls the latest snapshot from the CoGit repository.
+     * @param params Pull parameters including auth and branch
+     * @returns CogitSnapshot containing files and metadata
+     * @throws Error if pull fails
+     */
+    pull: (params: PullParams) => Promise<CogitSnapshot>;
+}

package/dist/core/interfaces/i-cogit-pull-service.js

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

package/dist/core/interfaces/i-cogit-push-service.d.ts

@@ -0,0 +1,27 @@
+import type { CogitPushContext } from '../domain/entities/cogit-push-context.js';
+import type { CogitPushResponse } from '../domain/entities/cogit-push-response.js';
+/**
+ * Parameters for pushing context files to CoGit.
+ */
+export type PushParams = {
+    accessToken: string;
+    branch: string;
+    contexts: CogitPushContext[];
+    sessionKey: string;
+    spaceId: string;
+    teamId: string;
+};
+/**
+ * Interface for pushing context files to the CoGit service.
+ * Handles the push operation to store context files in the CoGit repository.
+ */
+export interface ICogitPushService {
+    /**
+     * Pushes context files to the CoGit repository.
+     * Implements a two-request SHA flow to handle concurrent updates.
+     * @param params Push parameters including auth, branch, and context files
+     * @returns CogitPushResponse containing commit SHA and status
+     * @throws Error if push fails
+     */
+    push: (params: PushParams) => Promise<CogitPushResponse>;
+}

package/dist/core/interfaces/i-cogit-push-service.js

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

package/dist/core/interfaces/i-context-file-reader.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents the content of a context file with extracted metadata.
+ */
+export type ContextFileContent = {
+    /** The raw content of the file */
+    content: string;
+    /** Relative path within the context tree (e.g., "structure/context.md") */
+    path: string;
+    /** Title extracted from the first heading, or the relative path if no heading found */
+    title: string;
+};
+/**
+ * Interface for reading context files and extracting their metadata.
+ * Used to prepare context files for the CoGit API.
+ */
+export interface IContextFileReader {
+    /**
+     * Reads a single context file and extracts its metadata.
+     * @param relativePath - Relative path within the context tree (e.g., "structure/context.md")
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns ContextFileContent if file exists and can be read, undefined otherwise
+     */
+    read(relativePath: string, directory?: string): Promise<ContextFileContent | undefined>;
+    /**
+     * Reads multiple context files and extracts their metadata.
+     * Files that cannot be read are silently skipped.
+     * @param relativePaths - Array of relative paths within the context tree
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns Array of ContextFileContent for successfully read files
+     */
+    readMany(relativePaths: string[], directory?: string): Promise<ContextFileContent[]>;
+}

package/dist/core/interfaces/i-context-file-reader.js

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

package/dist/core/interfaces/i-context-tree-service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Interface for context tree operations service.
+ * Provides operations for managing the context tree structure including
+ * initialization and existence checking.
+ */
+export interface IContextTreeService {
+    /**
+     * Checks if the context tree structure exists in the project.
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns True if context tree directory exists
+     */
+    exists(directory?: string): Promise<boolean>;
+    /**
+     * Initializes the context tree directory structure.
+     * Creates .brv/context-tree/ directory with domain subdirectories and context.md files.
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns The absolute path to the created context tree directory
+     * @throws Error if context tree already exists or initialization fails
+     */
+    initialize(directory?: string): Promise<string>;
+}

package/dist/core/interfaces/i-context-tree-service.js

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

package/dist/core/interfaces/i-context-tree-snapshot-service.d.ts

@@ -0,0 +1,36 @@
+import type { ContextTreeChanges, FileState } from '../domain/entities/context-tree-snapshot.js';
+/**
+ * Interface for context tree snapshot operations.
+ * Provides change tracking by comparing current file states against saved snapshots.
+ */
+export interface IContextTreeSnapshotService {
+    /**
+     * Compares current context tree state against the saved snapshot.
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns Changes detected (added, modified, deleted files)
+     */
+    getChanges(directory?: string): Promise<ContextTreeChanges>;
+    /**
+     * Gets the current state of all files in the context tree.
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns Map of relative file paths to their current state (hash and size)
+     */
+    getCurrentState(directory?: string): Promise<Map<string, FileState>>;
+    /**
+     * Checks if a snapshot file exists.
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns True if snapshot exists
+     */
+    hasSnapshot(directory?: string): Promise<boolean>;
+    /**
+     * Creates an empty snapshot (no files tracked).
+     * Use this to establish a baseline where all current files will appear as "added".
+     * @param directory - Optional base directory (defaults to current working directory)
+     */
+    initEmptySnapshot(directory?: string): Promise<void>;
+    /**
+     * Creates or updates the snapshot from current context tree state.
+     * @param directory - Optional base directory (defaults to current working directory)
+     */
+    saveSnapshot(directory?: string): Promise<void>;
+}

package/dist/core/interfaces/i-context-tree-snapshot-service.js

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

package/dist/core/interfaces/i-context-tree-writer-service.d.ts

@@ -0,0 +1,32 @@
+import type { CogitSnapshotFile } from '../domain/entities/cogit-snapshot-file.js';
+/**
+ * Result of a sync operation.
+ */
+export type SyncResult = {
+    added: string[];
+    deleted: string[];
+    edited: string[];
+};
+/**
+ * Parameters for the sync operation.
+ */
+export type SyncParams = {
+    directory?: string;
+    files: readonly CogitSnapshotFile[];
+};
+/**
+ * Interface for context tree writer operations.
+ * This should be used to process pull response from Cogit.
+ * Provides file synchronization capabilities for the context tree.
+ */
+export interface IContextTreeWriterService {
+    /**
+     * Synchronizes the context tree with the provided files.
+     * - Files present in params but not locally are added
+     * - Files present in both are edited
+     * - Files present locally but not in params are deleted
+     * @param params - Sync parameters including files and optional directory
+     * @returns Result containing arrays of added, edited, and deleted file paths
+     */
+    sync: (params: SyncParams) => Promise<SyncResult>;
+}

package/dist/core/interfaces/i-context-tree-writer-service.js

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

package/dist/core/interfaces/i-file-watcher-service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Represents a file system event.
+ */
+export type FileEvent = {
+    /**
+     * The path to the file or directory that changed.
+     */
+    path: string;
+    /**
+     * The type of event that occurred.
+     * - add: File added
+     * - addDir: Directory added
+     * - change: File modified
+     * - unlink: File deleted
+     * - unlinkDir: Directory deleted
+     */
+    type: 'add' | 'addDir' | 'change' | 'unlink' | 'unlinkDir';
+};
+/**
+ * Interface for a file watcher service that monitors file system changes.
+ */
+export interface IFileWatcherService {
+    /**
+     * Sets the handler to be called when file system events occur.
+     * Only one handler can be registered at a time.
+     * The handler is async to support file reading and processing.
+     * @param handler The async callback function to invoke with file events.
+     */
+    setFileEventHandler: (handler: (event: FileEvent) => Promise<void>) => void;
+    /**
+     * Starts watching the specified paths for file system changes.
+     * @param paths Array of directory paths to watch.
+     * @returns Promise that resolves when watching has started.
+     */
+    start: (paths: string[]) => Promise<void>;
+    /**
+     * Stops watching and cleans up resources.
+     * @returns Promise that resolves when cleanup is complete.
+     */
+    stop: () => Promise<void>;
+}

package/dist/core/interfaces/i-file-watcher-service.js

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

package/dist/core/interfaces/parser/i-clean-parser-service.d.ts

@@ -0,0 +1,18 @@
+import type { CleanSession } from '../../domain/entities/parser.js';
+/**
+ * Interface for clean parser services
+ * Implementations handle transformation of raw IDE session data to clean normalized format
+ */
+export interface ICleanParserService {
+    /**
+     * Parse and transform raw IDE sessions to clean normalized format
+     *
+     * Reads raw session files and transforms them into standardized format with
+     * normalized messages, metadata, and workspace information.
+     * Returns parsed sessions in-memory without writing to disk.
+     *
+     * @param rawDir - Path to directory containing raw IDE session files
+     * @returns Promise resolving to array of CleanSession objects
+     */
+    parse: (rawDir: string) => Promise<readonly CleanSession[]>;
+}

package/dist/core/interfaces/parser/i-clean-parser-service.js

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

package/dist/core/interfaces/parser/i-raw-parser-service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface for raw parser services
+ * Implementations handle extraction and transformation of raw IDE session data
+ */
+export interface IRawParserService {
+    /**
+     * Parse IDE sessions from a custom directory
+     *
+     * Extracts raw session data from IDE storage and writes normalized JSON files
+     * to output directory (.brv/logs/{ide}/raw by default).
+     *
+     * @param customDir - Path to directory containing IDE session data
+     * @param outputDir - Optional output directory for parsed files (defaults to process.cwd()/.brv/logs/{ide}/raw)
+     * @returns Promise resolving to true if parsing succeeded, false otherwise
+     */
+    parse(customDir: string, outputDir?: string): Promise<boolean>;
+}

package/dist/core/interfaces/parser/i-raw-parser-service.js

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

package/dist/core/interfaces/parser/i-session-normalizer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Interface for session normalization utilities
+ * Provides standardized transformation of raw session data to clean normalized format
+ */
+import { CleanMessage, CleanSession, SessionType } from '../../domain/entities/parser.js';
+export interface ISessionNormalizer {
+    /**
+     * Add turn_id to each message based on order
+     *
+     * @param messages - Array of messages to assign turn IDs to
+     * @returns Array of messages with turn_id property added
+     */
+    addTurnIds(messages: CleanMessage[]): CleanMessage[];
+    /**
+     * Combine tool_use and tool_result messages
+     *
+     * @param messages - Array of clean messages to process
+     * @returns Array of messages with combined tool execution blocks
+     */
+    combineToolResults(messages: CleanMessage[]): CleanMessage[];
+    /**
+     * Extract unique workspace paths from session messages and metadata
+     *
+     * @param messages - Array of clean messages to extract paths from
+     * @param metadata - Session metadata object (may contain cwd property)
+     * @param existingPaths - Optional pre-existing paths to include
+     * @returns Sorted array of unique workspace paths
+     */
+    extractWorkspacePaths(messages: CleanMessage[], metadata: unknown, existingPaths?: string[]): string[];
+    /**
+     * Normalize message content to always be an array of content blocks
+     *
+     * @param content - Content to normalize (can be string, array of blocks, object, or any value)
+     * @returns Array of normalized ContentBlock objects
+     */
+    normalizeContent(content: unknown): unknown[];
+    /**
+     * Normalize a single content block
+     *
+     * @param block - Block to normalize (string, object, or any value)
+     * @returns Normalized ContentBlock with proper type inference
+     */
+    normalizeContentBlock(block: unknown): unknown;
+    /**
+     * Normalize session to clean format
+     *
+     * Transforms raw session data into standardized CleanSession format. Normalizes message
+     * content to content blocks, combines tool calls with results, assigns turn IDs,
+     * and extracts workspace paths.
+     *
+     * @param session - Raw session object with messages and metadata
+     * @param sessionType - Type of session (Claude, Copilot, Cursor, Codex)
+     * @returns Normalized CleanSession with standardized format
+     */
+    normalizeSession(session: Record<string, unknown>, sessionType?: SessionType): CleanSession;
+}

package/dist/core/interfaces/parser/i-session-normalizer.js

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