byterover-cli 0.2.1 → 0.3.0

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

@@ -0,0 +1,53 @@
+import type { SessionMetadata } from '../../domain/cipher/storage/history-types.js';
+import type { InternalMessage } from '../cipher/message-types.js';
+/**
+ * Interface for session history persistence.
+ *
+ * Implementations can use different storage backends (blob storage, database, etc.)
+ * to persist and restore conversation history across sessions.
+ */
+export interface IHistoryStorage {
+    /**
+     * Delete all history for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves when history is deleted
+     */
+    deleteHistory(sessionId: string): Promise<void>;
+    /**
+     * Check if history exists for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves to true if history exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Get metadata for a specific session without loading full history.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves to session metadata or undefined if not found
+     */
+    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * List all session IDs that have persisted history.
+     *
+     * @returns Promise that resolves to array of session IDs
+     */
+    listSessions(): Promise<string[]>;
+    /**
+     * Load conversation history for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves to array of messages, or undefined if session not found
+     */
+    loadHistory(sessionId: string): Promise<InternalMessage[] | undefined>;
+    /**
+     * Save conversation history for a specific session.
+     * Overwrites any existing history for the session.
+     *
+     * @param sessionId - Unique session identifier
+     * @param messages - Array of messages to persist
+     * @returns Promise that resolves when history is saved
+     */
+    saveHistory(sessionId: string, messages: InternalMessage[]): Promise<void>;
+}

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

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

package/dist/core/interfaces/cipher/i-llm-provider.d.ts

@@ -0,0 +1,14 @@
+export type LlmGenerateParams = {
+    maxTokens?: number;
+    model?: string;
+    prompt: string;
+    temperature?: number;
+};
+export interface ILlmProvider {
+    /**
+     * Generate a response from the LLM
+     * @param params - Generation parameters including prompt and optional model settings
+     * @returns The generated text response
+     */
+    generate: (params: LlmGenerateParams) => Promise<string>;
+}

package/dist/core/interfaces/cipher/i-llm-provider.js

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

package/dist/core/interfaces/cipher/i-llm-service.d.ts

@@ -0,0 +1,62 @@
+import type { ContextManager, FileData, ImageData } from '../../../infra/cipher/llm/context/context-manager.js';
+import type { LLMServiceConfig } from '../../../infra/cipher/llm/internal-llm-service.js';
+import type { ToolSet } from '../../domain/cipher/tools/types.js';
+import type { ExecutionContext } from './i-cipher-agent.js';
+/**
+ * LLM Service interface.
+ *
+ * Defines the contract for LLM service implementations.
+ * Services handle the agentic loop, tool calling, and context management.
+ *
+ * Based on dexto's ILLMService pattern.
+ */
+export interface ILLMService {
+    /**
+     * Complete a task with agentic tool calling support.
+     *
+     * Main entry point for executing user requests with tool support.
+     * The service handles:
+     * - Adding user message to context
+     * - Agentic loop (LLM → tool calls → LLM)
+     * - Returning final response
+     *
+     * @param textInput - User input text
+     * @param sessionId - Session ID for tracking the conversation
+     * @param options - Execution options
+     * @param options.signal - Optional abort signal for cancellation
+     * @param options.imageData - Optional image data
+     * @param options.fileData - Optional file data
+     * @param options.stream - Whether to stream the response (optional)
+     * @param options.executionContext - Optional execution context (for autonomous mode, etc.)
+     * @param options.mode - Optional mode for system prompt ('autonomous' enables autonomous mode)
+     * @returns Final assistant response
+     */
+    completeTask(textInput: string, sessionId: string, options?: {
+        executionContext?: ExecutionContext;
+        fileData?: FileData;
+        imageData?: ImageData;
+        mode?: 'autonomous' | 'default' | 'query';
+        signal?: AbortSignal;
+        stream?: boolean;
+    }): Promise<string>;
+    /**
+     * Get all available tools.
+     *
+     * @returns Tool set with JSON Schema definitions
+     */
+    getAllTools(): Promise<ToolSet>;
+    /**
+     * Get service configuration.
+     *
+     * @returns Service configuration including model, provider, token limits
+     */
+    getConfig(): LLMServiceConfig;
+    /**
+     * Get the context manager instance.
+     *
+     * Allows access to conversation history and context management.
+     *
+     * @returns Context manager instance
+     */
+    getContextManager(): ContextManager<unknown>;
+}

package/dist/core/interfaces/cipher/i-llm-service.js

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

package/dist/core/interfaces/cipher/i-logger.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Log level enumeration
+ */
+export declare enum LogLevel {
+    DEBUG = "debug",
+    ERROR = "error",
+    INFO = "info",
+    WARN = "warn"
+}
+/**
+ * Logger interface for Clean Architecture compliance.
+ *
+ * This interface defines the contract for logging in the application.
+ * Domain and infrastructure layers should depend on this interface,
+ * not on concrete logging implementations.
+ *
+ * Design principles:
+ * - No dependencies on external libraries (console, winston, etc.)
+ * - Simple, focused API for common logging needs
+ * - Supports structured logging with context objects
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   constructor(private readonly logger: ILogger) {}
+ *
+ *   async doWork(): Promise<void> {
+ *     this.logger.info('Starting work', { taskId: '123' });
+ *     try {
+ *       // ... work ...
+ *       this.logger.debug('Work completed', { duration: 100 });
+ *     } catch (error) {
+ *       this.logger.error('Work failed', { error });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface ILogger {
+    /**
+     * Log a debug message (verbose, for development).
+     *
+     * @param message - Human-readable message
+     * @param context - Optional structured context data
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an error message (for failures and exceptions).
+     *
+     * @param message - Human-readable error message
+     * @param context - Optional structured context data (e.g., error object, stack trace)
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an info message (general informational).
+     *
+     * @param message - Human-readable message
+     * @param context - Optional structured context data
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a warning message (potential issues).
+     *
+     * @param message - Human-readable warning message
+     * @param context - Optional structured context data
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * No-op logger implementation that discards all log messages.
+ * Useful for testing or when logging is disabled.
+ */
+export declare class NoOpLogger implements ILogger {
+    debug(_message: string, _context?: Record<string, unknown>): void;
+    error(_message: string, _context?: Record<string, unknown>): void;
+    info(_message: string, _context?: Record<string, unknown>): void;
+    warn(_message: string, _context?: Record<string, unknown>): void;
+}

package/dist/core/interfaces/cipher/i-logger.js

@@ -0,0 +1,28 @@
+/**
+ * Log level enumeration
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "debug";
+    LogLevel["ERROR"] = "error";
+    LogLevel["INFO"] = "info";
+    LogLevel["WARN"] = "warn";
+})(LogLevel || (LogLevel = {}));
+/**
+ * No-op logger implementation that discards all log messages.
+ * Useful for testing or when logging is disabled.
+ */
+export class NoOpLogger {
+    debug(_message, _context) {
+        // No-op
+    }
+    error(_message, _context) {
+        // No-op
+    }
+    info(_message, _context) {
+        // No-op
+    }
+    warn(_message, _context) {
+        // No-op
+    }
+}

package/dist/core/interfaces/cipher/i-message-formatter.d.ts

@@ -0,0 +1,44 @@
+import type { InternalMessage } from './message-types.js';
+/**
+ * Interface for converting internal message format to LLM provider-specific formats.
+ * Each LLM provider requires a different message structure, and the formatter's job
+ * is to handle these conversions while maintaining a consistent internal representation.
+ *
+ * @template TProviderMessage The provider-specific message type (e.g., Content for Gemini)
+ */
+export interface IMessageFormatter<TProviderMessage> {
+    /**
+     * Formats the internal message history for a specific LLM provider API.
+     * Transforms our standardized internal message format into the specific structure
+     * required by the target LLM API.
+     *
+     * @param history The raw internal message history (read-only to prevent modifications)
+     * @param systemPrompt Optional system prompt to include
+     * @returns The message history structured for the target API (provider-specific type)
+     */
+    format: (history: Readonly<InternalMessage[]>, systemPrompt?: null | string) => TProviderMessage[];
+    /**
+     * Optional method for handling system prompt separately.
+     * Some LLM providers (like Anthropic) don't include the system prompt in the
+     * messages array but pass it as a separate parameter.
+     *
+     * @param systemPrompt The system prompt to format
+     * @returns The formatted system prompt or null/undefined if not needed
+     */
+    formatSystemPrompt?: (systemPrompt: null | string) => null | string | undefined;
+    /**
+     * Parses raw LLM response into an array of InternalMessage objects.
+     * Converts provider-specific response format back to our internal representation.
+     *
+     * @param response The raw response from the LLM provider
+     * @returns Array of internal messages extracted from the response
+     */
+    parseResponse: (response: unknown) => InternalMessage[];
+    /**
+     * Optional method for parsing streaming LLM responses into InternalMessage objects.
+     *
+     * @param response The streaming response from the LLM provider
+     * @returns Promise that resolves to an array of InternalMessage objects
+     */
+    parseStreamResponse?(response: unknown): Promise<InternalMessage[]>;
+}

package/dist/core/interfaces/cipher/i-message-formatter.js

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

package/dist/core/interfaces/cipher/i-policy-engine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Policy Engine Interface.
+ *
+ * Provides rule-based ALLOW/DENY decisions for tool execution.
+ * Designed for autonomous execution - no ASK_USER decisions.
+ *
+ * Based on gemini-cli's policy engine pattern, simplified for autonomous mode.
+ */
+/**
+ * Policy decision for autonomous execution.
+ * Note: No ASK_USER - agent runs autonomously without user confirmation.
+ */
+export type PolicyDecision = 'ALLOW' | 'DENY';
+/**
+ * A policy rule that determines whether a tool execution should be allowed.
+ */
+export interface PolicyRule {
+    /**
+     * Optional condition function for fine-grained control.
+     * Only evaluated if toolPattern matches.
+     *
+     * @param toolName - The name of the tool being executed
+     * @param args - The arguments passed to the tool
+     * @returns True if this rule should apply, false to skip to next rule
+     */
+    condition?: (toolName: string, args: Record<string, unknown>) => boolean;
+    /**
+     * The decision to return if this rule matches.
+     */
+    decision: PolicyDecision;
+    /**
+     * Unique name for this rule (used for removal/debugging).
+     */
+    name: string;
+    /**
+     * Optional human-readable reason for this rule.
+     * Useful for logging and debugging.
+     */
+    reason?: string;
+    /**
+     * Tool name pattern to match.
+     * - String: exact match or '*' for all tools
+     * - RegExp: pattern matching for tool names
+     */
+    toolPattern: RegExp | string;
+}
+/**
+ * Result of evaluating a tool execution against policy rules.
+ */
+export interface PolicyEvaluationResult {
+    /**
+     * The policy decision (ALLOW or DENY).
+     */
+    decision: PolicyDecision;
+    /**
+     * Human-readable reason for the decision.
+     */
+    reason?: string;
+    /**
+     * The rule that matched (if any).
+     * Undefined if using default policy.
+     */
+    rule?: PolicyRule;
+}
+/**
+ * Interface for the policy engine.
+ *
+ * The policy engine evaluates tool execution requests against a set of rules
+ * to determine whether execution should be allowed or denied.
+ *
+ * Rules are evaluated in order - first matching rule wins.
+ */
+export interface IPolicyEngine {
+    /**
+     * Add a policy rule.
+     * Rules are evaluated in the order they are added.
+     *
+     * @param rule - The policy rule to add
+     */
+    addRule(rule: PolicyRule): void;
+    /**
+     * Evaluate a tool execution request against policy rules.
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Arguments for the tool
+     * @returns Policy evaluation result with decision and reason
+     */
+    evaluate(toolName: string, args: Record<string, unknown>): PolicyEvaluationResult;
+    /**
+     * Get all registered policy rules.
+     * Useful for debugging and introspection.
+     *
+     * @returns Read-only array of policy rules
+     */
+    getRules(): readonly PolicyRule[];
+    /**
+     * Remove a policy rule by name.
+     *
+     * @param name - The name of the rule to remove
+     */
+    removeRule(name: string): void;
+}

package/dist/core/interfaces/cipher/i-policy-engine.js

@@ -0,0 +1,9 @@
+/**
+ * Policy Engine Interface.
+ *
+ * Provides rule-based ALLOW/DENY decisions for tool execution.
+ * Designed for autonomous execution - no ASK_USER decisions.
+ *
+ * Based on gemini-cli's policy engine pattern, simplified for autonomous mode.
+ */
+export {};

package/dist/core/interfaces/cipher/i-process-service.d.ts

@@ -0,0 +1,65 @@
+import type { ExecuteOptions, ProcessConfig, ProcessHandle, ProcessInfo, ProcessOutput, ProcessResult } from '../../domain/cipher/process/types.js';
+/**
+ * Process service interface.
+ *
+ * Provides secure command execution with foreground/background support,
+ * security validation, and resource management.
+ */
+export interface IProcessService {
+    /**
+     * Clean up completed background processes.
+     *
+     * Removes processes that have been completed for more than 1 hour.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Execute a shell command.
+     *
+     * Validates command security, handles approval if needed, and executes
+     * either in foreground (waiting for completion) or background (returns immediately).
+     *
+     * @param command - Shell command to execute
+     * @param options - Execution options (timeout, cwd, background, etc.)
+     * @returns Process result (foreground) or process handle (background)
+     * @throws ProcessError if validation fails, approval denied, or execution fails
+     */
+    executeCommand(command: string, options?: ExecuteOptions): Promise<ProcessHandle | ProcessResult>;
+    /**
+     * Get the current process configuration.
+     *
+     * @returns Readonly configuration object
+     */
+    getConfig(): Readonly<ProcessConfig>;
+    /**
+     * Get output from a background process.
+     *
+     * Retrieves new output since last read and clears the buffer (destructive read).
+     *
+     * @param processId - Unique process identifier
+     * @returns Process output with status and exit code (if completed)
+     * @throws ProcessError if process not found
+     */
+    getProcessOutput(processId: string): Promise<ProcessOutput>;
+    /**
+     * Initialize the process service.
+     *
+     * Must be called before executing commands.
+     * Performs cleanup of any stale processes from previous runs.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Terminate a background process.
+     *
+     * Sends SIGTERM, waits 5 seconds, then escalates to SIGKILL if still running.
+     *
+     * @param processId - Unique process identifier
+     * @throws ProcessError if process not found or kill fails
+     */
+    killProcess(processId: string): Promise<void>;
+    /**
+     * List all background processes.
+     *
+     * @returns Array of process information (status, timestamps, etc.)
+     */
+    listProcesses(): Promise<ProcessInfo[]>;
+}

package/dist/core/interfaces/cipher/i-process-service.js

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

package/dist/core/interfaces/cipher/i-system-prompt-contributor.d.ts

@@ -0,0 +1,25 @@
+import type { SystemPromptContext } from '../../domain/cipher/system-prompt/types.js';
+/**
+ * Interface for system prompt contributors.
+ * Contributors are responsible for generating parts of the system prompt
+ * that will be sent to the LLM. Each contributor has a priority that
+ * determines the order in which its content appears in the final prompt.
+ */
+export interface ISystemPromptContributor {
+    /**
+     * Generate the content for this contributor.
+     * @param context - Runtime context containing dependencies and configuration
+     * @returns The generated content string
+     */
+    getContent(context: SystemPromptContext): Promise<string>;
+    /**
+     * Unique identifier for this contributor
+     */
+    id: string;
+    /**
+     * Priority for ordering contributors. Lower numbers = higher priority.
+     * Contributors are executed in priority order, and their content is
+     * concatenated in that order.
+     */
+    priority: number;
+}

package/dist/core/interfaces/cipher/i-system-prompt-contributor.js

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

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

@@ -0,0 +1,15 @@
+/**
+ * Interface for tokenizing text according to LLM provider-specific rules.
+ * Different LLM providers use different tokenization algorithms, and this interface
+ * provides a unified way to count tokens across providers.
+ */
+export interface ITokenizer {
+    /**
+     * Counts the number of tokens in the provided text according to
+     * the specific LLM provider's tokenization rules.
+     *
+     * @param text - Text content to count tokens for
+     * @returns Number of tokens in the text
+     */
+    countTokens: (text: string) => number;
+}

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

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

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

@@ -0,0 +1,64 @@
+import type { ToolMarker } from '../../../infra/cipher/tools/tool-markers.js';
+import type { ToolSet } from '../../domain/cipher/tools/types.js';
+/**
+ * Interface for tool provider.
+ * Manages tool registration, validation, and execution.
+ */
+export interface IToolProvider {
+    /**
+     * Execute a tool with the given arguments.
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Tool arguments (will be validated against schema)
+     * @param sessionId - Optional session ID for context
+     * @returns Tool execution result
+     * @throws ToolNotFoundError if tool doesn't exist
+     * @throws ToolValidationError if input validation fails
+     * @throws ToolExecutionError if execution fails
+     */
+    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string): Promise<unknown>;
+    /**
+     * Get all registered tools in JSON Schema format.
+     * Used to expose tools to the LLM.
+     *
+     * @returns Tool set with JSON Schema definitions
+     */
+    getAllTools(): ToolSet;
+    /**
+     * Get all available tool markers from registered tools.
+     *
+     * @returns Set of tool marker strings
+     */
+    getAvailableMarkers(): Set<string>;
+    /**
+     * Get the count of registered tools.
+     *
+     * @returns Number of registered tools
+     */
+    getToolCount(): number;
+    /**
+     * Get names of all registered tools.
+     *
+     * @returns Array of tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Get tool names that have a specific marker.
+     *
+     * @param marker - The tool marker to filter by
+     * @returns Array of tool names with the specified marker
+     */
+    getToolsByMarker(marker: ToolMarker): string[];
+    /**
+     * Check if a tool exists.
+     *
+     * @param toolName - Name of the tool
+     * @returns True if the tool exists
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Initialize the tool provider.
+     * Registers all available tools based on available services.
+     */
+    initialize(): Promise<void>;
+}

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

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