byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/tools/tool-manager.js

@@ -0,0 +1,209 @@
+import { ToolError, ToolErrorType, ToolErrorUtils } from '../../../core/domain/cipher/tools/tool-error.js';
+/**
+ * Tool Manager for CipherAgent
+ *
+ * Provides a clean interface for tool discovery and execution.
+ * Wraps ToolProvider with caching for improved performance.
+ *
+ * Features:
+ * - Optional scheduler integration for policy-based execution
+ * - Tool caching for performance
+ * - Structured error handling with classification
+ *
+ * When a scheduler is provided, tool execution flows through:
+ * 1. Policy check (ALLOW/DENY)
+ * 2. Execution (if allowed)
+ *
+ * Without a scheduler, tools execute directly via the provider.
+ */
+export class ToolManager {
+    /**
+     * Read-only tools allowed for query operations
+     */
+    static QUERY_TOOL_NAMES = [
+        'find_knowledge_topics',
+        'read_file',
+        'grep_content',
+        'glob_files',
+    ];
+    cacheValid = false;
+    scheduler;
+    toolProvider;
+    toolsCache = {};
+    /**
+     * Creates a new tool manager
+     *
+     * @param toolProvider - Tool provider instance
+     * @param scheduler - Optional tool scheduler for policy-based execution
+     */
+    constructor(toolProvider, scheduler) {
+        this.toolProvider = toolProvider;
+        this.scheduler = scheduler;
+    }
+    /**
+     * Execute a tool by name with structured error handling.
+     *
+     * Returns a structured result that includes success status, content,
+     * error classification, and metadata. This enables better error handling
+     * and provides actionable feedback to the LLM.
+     *
+     * When a scheduler is configured, execution flows through:
+     * 1. Policy check (ALLOW/DENY)
+     * 2. Execution (if allowed)
+     *
+     * Without a scheduler, tools execute directly via the provider.
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Tool arguments (validated by provider)
+     * @param sessionId - Optional session ID for context
+     * @returns Structured tool execution result
+     */
+    async executeTool(toolName, args, sessionId) {
+        const startTime = Date.now();
+        try {
+            // Check if tool exists before execution
+            if (!this.hasTool(toolName)) {
+                throw new ToolError(`Tool '${toolName}' not found`, ToolErrorType.TOOL_NOT_FOUND, toolName, { context: { availableTools: this.getToolNames() } });
+            }
+            // Execute tool via scheduler (with policy check) or directly via provider
+            const result = this.scheduler
+                ? await this.scheduler.execute(toolName, args, { sessionId: sessionId ?? 'default' })
+                : await this.toolProvider.executeTool(toolName, args, sessionId);
+            const durationMs = Date.now() - startTime;
+            // Return success result
+            return ToolErrorUtils.createSuccess(result, { durationMs });
+        }
+        catch (error) {
+            const durationMs = Date.now() - startTime;
+            // Classify error
+            const toolError = ToolErrorUtils.classify(error, toolName);
+            // Return error result
+            return ToolErrorUtils.createErrorResult(toolError, { durationMs });
+        }
+    }
+    /**
+     * Get all available tools in JSON Schema format.
+     * Results are cached for performance.
+     *
+     * @returns Tool set with JSON Schema definitions for LLM
+     */
+    getAllTools() {
+        // Return cached tools if valid
+        if (this.cacheValid) {
+            return this.toolsCache;
+        }
+        // Rebuild cache
+        this.toolsCache = this.toolProvider.getAllTools();
+        this.cacheValid = true;
+        return this.toolsCache;
+    }
+    /**
+     * Get all available tool markers from registered tools.
+     *
+     * @returns Set of tool marker strings
+     */
+    getAvailableMarkers() {
+        return this.toolProvider.getAvailableMarkers();
+    }
+    /**
+     * Get the count of registered tools.
+     *
+     * @returns Number of available tools
+     */
+    getToolCount() {
+        return this.toolProvider.getToolCount();
+    }
+    /**
+     * Get names of all registered tools.
+     *
+     * @returns Array of tool names
+     */
+    getToolNames() {
+        return this.toolProvider.getToolNames();
+    }
+    /**
+     * Get filtered tool names based on command type.
+     * For 'query' command, returns only read-only discovery tools.
+     * For other commands, returns all tools.
+     *
+     * @param commandType - The command type ('add', 'query', etc.)
+     * @returns Array of filtered tool names
+     */
+    getToolNamesForCommand(commandType) {
+        if (commandType === 'query') {
+            // For query: only allow read-only tools
+            return [...ToolManager.QUERY_TOOL_NAMES].filter((name) => this.hasTool(name));
+        }
+        // For all other commands: return all tools
+        return this.getToolNames();
+    }
+    /**
+     * 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) {
+        return this.toolProvider.getToolsByMarker(marker);
+    }
+    /**
+     * Get filtered tools based on command type.
+     * For 'query' command, returns only read-only discovery tools.
+     * For other commands, returns all tools.
+     *
+     * @param commandType - The command type ('add', 'query', etc.)
+     * @returns Filtered tool set with JSON Schema definitions
+     */
+    getToolsForCommand(commandType) {
+        const allTools = this.getAllTools();
+        if (commandType === 'query') {
+            // For query: only allow read-only tools
+            const filteredTools = {};
+            for (const toolName of ToolManager.QUERY_TOOL_NAMES) {
+                if (allTools[toolName]) {
+                    filteredTools[toolName] = allTools[toolName];
+                }
+            }
+            return filteredTools;
+        }
+        // For all other commands: return all tools
+        return allTools;
+    }
+    /**
+     * Check if a tool exists.
+     *
+     * @param toolName - Name of the tool
+     * @returns True if the tool exists
+     */
+    hasTool(toolName) {
+        return this.toolProvider.hasTool(toolName);
+    }
+    /**
+     * Initialize the tool manager.
+     * Registers all available tools and invalidates cache.
+     */
+    async initialize() {
+        await this.toolProvider.initialize();
+        this.invalidateCache();
+    }
+    /**
+     * Refresh tool discovery.
+     * Invalidates the tool cache, forcing a rebuild on next getAllTools() call.
+     *
+     * Useful when:
+     * - Adding/removing tools dynamically (future)
+     * - MCP servers connect/disconnect (future)
+     * - Manual cache clearing needed
+     */
+    refresh() {
+        this.invalidateCache();
+    }
+    /**
+     * Invalidates the tool cache.
+     * Next call to getAllTools() will rebuild the cache.
+     */
+    invalidateCache() {
+        this.cacheValid = false;
+        this.toolsCache = {};
+    }
+}

package/dist/infra/cipher/tools/tool-markers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool markers for semantic classification of tools.
+ *
+ * Tool markers enable:
+ * - Smart filtering based on operational mode (planning, execution, etc.)
+ * - Conditional prompt sections based on available capabilities
+ * - Context tree building workflows
+ */
+/**
+ * Enum of available tool markers
+ */
+export declare enum ToolMarker {
+    /**
+     * Tools for building context trees and organizing conversation/project information
+     * Examples: segment_conversation, search_history
+     */
+    ContextBuilding = "ToolMarkerContextBuilding",
+    /**
+     * Core tools that are always needed for basic operation
+     * Examples: read_file, glob_files, grep_content
+     */
+    Core = "ToolMarkerCore",
+    /**
+     * Tools for discovering and exploring codebase structure
+     * Examples: glob_files, grep_content, read_file
+     */
+    Discovery = "ToolMarkerDiscovery",
+    /**
+     * Tools that execute external commands/processes
+     * Examples: bash_exec, bash_output, kill_process
+     */
+    Execution = "ToolMarkerExecution",
+    /**
+     * Tools that modify files
+     * Examples: write_file, edit_file
+     */
+    Modification = "ToolMarkerModification",
+    /**
+     * Optional tools that are not needed for basic operations
+     * Examples: bash_output, kill_process, segment_conversation
+     */
+    Optional = "ToolMarkerOptional",
+    /**
+     * Tools for planning and task management
+     * Examples: write_todos
+     */
+    Planning = "ToolMarkerPlanning"
+}

package/dist/infra/cipher/tools/tool-markers.js

@@ -0,0 +1,49 @@
+/**
+ * Tool markers for semantic classification of tools.
+ *
+ * Tool markers enable:
+ * - Smart filtering based on operational mode (planning, execution, etc.)
+ * - Conditional prompt sections based on available capabilities
+ * - Context tree building workflows
+ */
+/**
+ * Enum of available tool markers
+ */
+export var ToolMarker;
+(function (ToolMarker) {
+    /**
+     * Tools for building context trees and organizing conversation/project information
+     * Examples: segment_conversation, search_history
+     */
+    ToolMarker["ContextBuilding"] = "ToolMarkerContextBuilding";
+    /**
+     * Core tools that are always needed for basic operation
+     * Examples: read_file, glob_files, grep_content
+     */
+    ToolMarker["Core"] = "ToolMarkerCore";
+    /**
+     * Tools for discovering and exploring codebase structure
+     * Examples: glob_files, grep_content, read_file
+     */
+    ToolMarker["Discovery"] = "ToolMarkerDiscovery";
+    /**
+     * Tools that execute external commands/processes
+     * Examples: bash_exec, bash_output, kill_process
+     */
+    ToolMarker["Execution"] = "ToolMarkerExecution";
+    /**
+     * Tools that modify files
+     * Examples: write_file, edit_file
+     */
+    ToolMarker["Modification"] = "ToolMarkerModification";
+    /**
+     * Optional tools that are not needed for basic operations
+     * Examples: bash_output, kill_process, segment_conversation
+     */
+    ToolMarker["Optional"] = "ToolMarkerOptional";
+    /**
+     * Tools for planning and task management
+     * Examples: write_todos
+     */
+    ToolMarker["Planning"] = "ToolMarkerPlanning";
+})(ToolMarker || (ToolMarker = {}));

package/dist/infra/cipher/tools/tool-provider.d.ts

@@ -0,0 +1,77 @@
+import type { ToolSet } from '../../../core/domain/cipher/tools/types.js';
+import type { IToolProvider } from '../../../core/interfaces/cipher/i-tool-provider.js';
+import type { SimplePromptFactory } from '../system-prompt/simple-prompt-factory.js';
+import type { ToolServices } from './tool-registry.js';
+import { ToolMarker } from './tool-markers.js';
+/**
+ * Tool provider implementation.
+ * Manages tool lifecycle: registration, validation, and execution.
+ *
+ * Uses builder/invocation pattern for two-phase tool execution:
+ * 1. Validation phase (via builder)
+ * 2. Execution phase (via invocation)
+ */
+export declare class ToolProvider implements IToolProvider {
+    private initialized;
+    private invocationBuilder?;
+    private readonly promptFactory?;
+    private readonly services;
+    private readonly toolMarkers;
+    private readonly tools;
+    /**
+     * Creates a new tool provider
+     * @param services - Services available to tools
+     * @param promptFactory - Optional prompt factory for tool output guidance
+     */
+    constructor(services: ToolServices, promptFactory?: SimplePromptFactory);
+    /**
+     * Execute a tool with the given arguments using builder/invocation pattern.
+     *
+     * Two-phase execution:
+     * 1. Build Phase: Validate and create invocation
+     * 2. Execute Phase: Run the validated invocation
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Tool arguments
+     * @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.
+     */
+    getAllTools(): ToolSet;
+    /**
+     * Get all available tool markers from registered tools.
+     */
+    getAvailableMarkers(): Set<string>;
+    /**
+     * Get the count of registered tools.
+     */
+    getToolCount(): number;
+    /**
+     * Get names of all registered tools.
+     */
+    getToolNames(): string[];
+    /**
+     * Get tool names that have a specific marker.
+     */
+    getToolsByMarker(marker: ToolMarker): string[];
+    /**
+     * Check if a tool exists.
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Initialize the tool provider.
+     * Registers all tools whose required services are available.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensures the provider is initialized.
+     * @throws ToolProviderNotInitializedError if not initialized
+     */
+    private ensureInitialized;
+}

package/dist/infra/cipher/tools/tool-provider.js

@@ -0,0 +1,196 @@
+import { ZodError } from 'zod';
+import { ToolExecutionError, ToolNotFoundError, ToolProviderNotInitializedError, ToolValidationError, } from '../../../core/domain/cipher/errors/tool-error.js';
+import { ToolInvocationBuilder } from './tool-invocation.js';
+import { TOOL_REGISTRY } from './tool-registry.js';
+import { convertZodToJsonSchema } from './utils/schema-converter.js';
+/**
+ * Tool provider implementation.
+ * Manages tool lifecycle: registration, validation, and execution.
+ *
+ * Uses builder/invocation pattern for two-phase tool execution:
+ * 1. Validation phase (via builder)
+ * 2. Execution phase (via invocation)
+ */
+export class ToolProvider {
+    initialized = false;
+    invocationBuilder;
+    promptFactory;
+    services;
+    toolMarkers = new Set();
+    tools = new Map();
+    /**
+     * Creates a new tool provider
+     * @param services - Services available to tools
+     * @param promptFactory - Optional prompt factory for tool output guidance
+     */
+    constructor(services, promptFactory) {
+        this.services = services;
+        this.promptFactory = promptFactory;
+    }
+    /**
+     * Execute a tool with the given arguments using builder/invocation pattern.
+     *
+     * Two-phase execution:
+     * 1. Build Phase: Validate and create invocation
+     * 2. Execute Phase: Run the validated invocation
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Tool arguments
+     * @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
+     */
+    async executeTool(toolName, args, sessionId) {
+        this.ensureInitialized();
+        if (!this.invocationBuilder) {
+            throw new ToolProviderNotInitializedError();
+        }
+        try {
+            // Phase 1: Build and validate invocation
+            const context = { sessionId };
+            const invocation = this.invocationBuilder.build(`tool_call_${Date.now()}`, // Generate unique ID
+            toolName, args, context);
+            // Phase 2: Execute validated invocation
+            const executionResult = await invocation.execute();
+            // Handle execution result
+            if (!executionResult.result) {
+                // Execution failed
+                if (executionResult.error) {
+                    throw new ToolExecutionError(toolName, executionResult.error.message, sessionId);
+                }
+                throw new ToolExecutionError(toolName, 'Unknown execution error', sessionId);
+            }
+            // Check if this tool has output guidance configured
+            const registryEntry = TOOL_REGISTRY[toolName];
+            if (registryEntry?.outputGuidance && this.promptFactory) {
+                const guidance = this.promptFactory.getToolOutputGuidance(registryEntry.outputGuidance);
+                if (guidance) {
+                    // Return structured result with guidance
+                    return {
+                        guidance,
+                        result: executionResult.result,
+                    };
+                }
+            }
+            // Return result without guidance
+            return executionResult.result;
+        }
+        catch (error) {
+            // Handle validation errors from builder
+            if (error instanceof ZodError) {
+                const errorMessages = error.errors.map((err) => `${err.path.join('.')}: ${err.message}`).join('; ');
+                throw new ToolValidationError(toolName, errorMessages);
+            }
+            // Re-throw known errors
+            if (error instanceof ToolNotFoundError ||
+                error instanceof ToolValidationError ||
+                error instanceof ToolExecutionError) {
+                throw error;
+            }
+            // Handle other execution errors
+            if (error instanceof Error) {
+                throw new ToolExecutionError(toolName, error.message, sessionId);
+            }
+            // Unknown error type
+            throw new ToolExecutionError(toolName, String(error), sessionId);
+        }
+    }
+    /**
+     * Get all registered tools in JSON Schema format.
+     */
+    getAllTools() {
+        this.ensureInitialized();
+        const toolSet = {};
+        for (const [toolName, tool] of this.tools.entries()) {
+            toolSet[toolName] = {
+                description: tool.description,
+                name: toolName,
+                parameters: convertZodToJsonSchema(tool.inputSchema),
+            };
+        }
+        return toolSet;
+    }
+    /**
+     * Get all available tool markers from registered tools.
+     */
+    getAvailableMarkers() {
+        this.ensureInitialized();
+        return new Set(this.toolMarkers);
+    }
+    /**
+     * Get the count of registered tools.
+     */
+    getToolCount() {
+        this.ensureInitialized();
+        return this.tools.size;
+    }
+    /**
+     * Get names of all registered tools.
+     */
+    getToolNames() {
+        this.ensureInitialized();
+        return [...this.tools.keys()];
+    }
+    /**
+     * Get tool names that have a specific marker.
+     */
+    getToolsByMarker(marker) {
+        this.ensureInitialized();
+        const toolNames = [];
+        for (const [toolName, entry] of Object.entries(TOOL_REGISTRY)) {
+            if (entry.markers.includes(marker) && this.tools.has(toolName)) {
+                toolNames.push(toolName);
+            }
+        }
+        return toolNames;
+    }
+    /**
+     * Check if a tool exists.
+     */
+    hasTool(toolName) {
+        this.ensureInitialized();
+        return this.tools.has(toolName);
+    }
+    /**
+     * Initialize the tool provider.
+     * Registers all tools whose required services are available.
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Register tools from registry
+        for (const [toolName, entry] of Object.entries(TOOL_REGISTRY)) {
+            // Check if all required services are available
+            const allServicesAvailable = entry.requiredServices.every((serviceName) => this.services[serviceName] !== undefined);
+            if (allServicesAvailable) {
+                try {
+                    const tool = entry.factory(this.services);
+                    this.tools.set(toolName, tool);
+                    // Collect markers from registered tools
+                    for (const marker of entry.markers) {
+                        this.toolMarkers.add(marker);
+                    }
+                }
+                catch (error) {
+                    // Log error but don't fail initialization
+                    console.error(`Failed to register tool ${toolName}:`, error);
+                }
+            }
+        }
+        // Initialize invocation builder with registered tools
+        this.invocationBuilder = new ToolInvocationBuilder(this.tools);
+        this.initialized = true;
+    }
+    /**
+     * Ensures the provider is initialized.
+     * @throws ToolProviderNotInitializedError if not initialized
+     */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new ToolProviderNotInitializedError();
+        }
+    }
+}

package/dist/infra/cipher/tools/tool-registry.d.ts

@@ -0,0 +1,52 @@
+import type { KnownTool } from '../../../core/domain/cipher/tools/constants.js';
+import type { Tool } from '../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../core/interfaces/cipher/i-file-system.js';
+import type { IProcessService } from '../../../core/interfaces/cipher/i-process-service.js';
+import type { MemoryManager } from '../memory/memory-manager.js';
+import { ToolMarker } from './tool-markers.js';
+/**
+ * Service dependencies available to tools.
+ * Tools declare which services they need via requiredServices.
+ */
+export interface ToolServices {
+    /** File system service for file operations */
+    fileSystemService?: IFileSystem;
+    /** Memory manager for agent memory operations */
+    memoryManager?: MemoryManager;
+    /** Process service for command execution */
+    processService?: IProcessService;
+}
+/**
+ * Tool factory function type.
+ * Creates a tool instance given the required services.
+ */
+export type ToolFactory = (services: ToolServices) => Tool;
+/**
+ * Registry entry for a tool.
+ * Defines the factory, required services, semantic markers, and optional output guidance for each tool.
+ */
+export interface ToolRegistryEntry {
+    /** Factory function to create the tool */
+    factory: ToolFactory;
+    /** Semantic markers for this tool (enables smart filtering and conditional prompts) */
+    markers: readonly ToolMarker[];
+    /**
+     * Optional output guidance prompt key.
+     * If specified, the ToolProvider will append guidance from tool-outputs.yml
+     * after tool execution to help the LLM understand next steps.
+     * Example: 'write_memory' will load the 'write_memory_output' prompt.
+     */
+    outputGuidance?: string;
+    /** Services required by this tool */
+    requiredServices: readonly (keyof ToolServices)[];
+}
+/**
+ * Central registry of all tools.
+ * Maps tool names to their factory functions and required services.
+ *
+ * To add a new tool:
+ * 1. Add tool name to ToolName constants
+ * 2. Create tool implementation file
+ * 3. Add entry to this registry
+ */
+export declare const TOOL_REGISTRY: Record<KnownTool, ToolRegistryEntry>;