byterover-cli 0.4.0 → 1.0.0

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

@@ -1,3 +1,4 @@
+import { getAgentRegistry } from '../../../core/domain/cipher/agent/agent-registry.js';
 import { ToolError, ToolErrorType, ToolErrorUtils } from '../../../core/domain/cipher/tools/tool-error.js';
 /**
  * Tool Manager for CipherAgent
@@ -7,6 +8,7 @@ import { ToolError, ToolErrorType, ToolErrorUtils } from '../../../core/domain/c
  *
  * Features:
  * - Optional scheduler integration for policy-based execution
+ * - Optional plugin system for before/after execution hooks
  * - Tool caching for performance
  * - Structured error handling with classification
  *
@@ -14,6 +16,11 @@ import { ToolError, ToolErrorType, ToolErrorUtils } from '../../../core/domain/c
  * 1. Policy check (ALLOW/DENY)
  * 2. Execution (if allowed)
  *
+ * When a plugin manager is provided, execution flows through:
+ * 1. Before hooks (can modify args or block execution)
+ * 2. Tool execution
+ * 3. After hooks (for logging, auditing, etc.)
+ *
  * Without a scheduler, tools execute directly via the provider.
  */
 export class ToolManager {
@@ -22,7 +29,6 @@ export class ToolManager {
      */
     static CURATE_TOOL_NAMES = [
         'detect_domains',
-        'find_knowledge_topics',
         'read_file',
         'grep_content',
         'glob_files',
@@ -32,12 +38,14 @@ export class ToolManager {
      * Read-only tools allowed for query operations
      */
     static QUERY_TOOL_NAMES = [
-        'find_knowledge_topics',
         'read_file',
         'grep_content',
         'glob_files',
+        'task',
     ];
     cacheValid = false;
+    callIdCounter = 0;
+    pluginManager;
     scheduler;
     toolProvider;
     toolsCache = {};
@@ -46,10 +54,12 @@ export class ToolManager {
      *
      * @param toolProvider - Tool provider instance
      * @param scheduler - Optional tool scheduler for policy-based execution
+     * @param pluginManager - Optional plugin manager for before/after hooks
      */
-    constructor(toolProvider, scheduler) {
+    constructor(toolProvider, scheduler, pluginManager) {
         this.toolProvider = toolProvider;
         this.scheduler = scheduler;
+        this.pluginManager = pluginManager;
     }
     /**
      * Execute a tool by name with structured error handling.
@@ -58,7 +68,12 @@ export class ToolManager {
      * error classification, and metadata. This enables better error handling
      * and provides actionable feedback to the LLM.
      *
-     * When a scheduler is configured, execution flows through:
+     * When a plugin manager is configured, execution flows through:
+     * 1. Before hooks (can modify args or block execution)
+     * 2. Tool execution (via scheduler or provider)
+     * 3. After hooks (for logging, auditing, etc.)
+     *
+     * When a scheduler is configured, tool execution flows through:
      * 1. Policy check (ALLOW/DENY)
      * 2. Execution (if allowed)
      *
@@ -67,29 +82,65 @@ export class ToolManager {
      * @param toolName - Name of the tool to execute
      * @param args - Tool arguments (validated by provider)
      * @param sessionId - Optional session ID for context
+     * @param context - Optional execution context (includes metadata callback for streaming)
      * @returns Structured tool execution result
      */
-    async executeTool(toolName, args, sessionId) {
+    async executeTool(toolName, args, sessionId, context) {
         const startTime = Date.now();
+        const callId = this.generateCallId();
+        const hookContext = {
+            callId,
+            sessionId: sessionId ?? 'default',
+            toolName,
+        };
+        // Merge sessionId into context if not already present
+        const effectiveContext = {
+            ...context,
+            sessionId: context?.sessionId ?? sessionId,
+        };
         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() } });
             }
+            // Run before hooks (can modify args or block execution)
+            let effectiveArgs = args;
+            if (this.pluginManager) {
+                const beforeResult = await this.pluginManager.triggerBefore(hookContext, args);
+                if (!beforeResult.proceed) {
+                    const errorResult = ToolErrorUtils.createErrorResult(new ToolError(beforeResult.reason ?? 'Execution blocked by plugin', ToolErrorType.PERMISSION_DENIED, toolName), { durationMs: Date.now() - startTime });
+                    await this.pluginManager.triggerAfter(hookContext, args, errorResult);
+                    return errorResult;
+                }
+                effectiveArgs = beforeResult.args;
+            }
             // 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);
+                ? await this.scheduler.execute(toolName, effectiveArgs, {
+                    sessionId: sessionId ?? 'default',
+                    taskId: effectiveContext.taskId,
+                })
+                : await this.toolProvider.executeTool(toolName, effectiveArgs, sessionId, effectiveContext);
             const durationMs = Date.now() - startTime;
-            // Return success result
-            return ToolErrorUtils.createSuccess(result, { durationMs });
+            // Create success result
+            const successResult = ToolErrorUtils.createSuccess(result, { durationMs });
+            // Run after hooks
+            if (this.pluginManager) {
+                await this.pluginManager.triggerAfter(hookContext, effectiveArgs, successResult);
+            }
+            return successResult;
         }
         catch (error) {
             const durationMs = Date.now() - startTime;
             // Classify error
             const toolError = ToolErrorUtils.classify(error, toolName);
-            // Return error result
-            return ToolErrorUtils.createErrorResult(toolError, { durationMs });
+            // Create error result
+            const errorResult = ToolErrorUtils.createErrorResult(toolError, { durationMs });
+            // Run after hooks even on error
+            if (this.pluginManager) {
+                await this.pluginManager.triggerAfter(hookContext, args, errorResult);
+            }
+            return errorResult;
         }
     }
     /**
@@ -162,6 +213,44 @@ export class ToolManager {
     getToolsByMarker(marker) {
         return this.toolProvider.getToolsByMarker(marker);
     }
+    /**
+     * Get filtered tools based on agent configuration.
+     * Uses the agent registry to determine which tools are enabled/disabled for the agent.
+     *
+     * Tool filtering rules from agent.tools config:
+     * - `{ '*': false }` - Disable all tools
+     * - `{ '*': false, 'tool_name': true }` - Only enable specific tools
+     * - `{ 'tool_name': false }` - Disable specific tools, keep others enabled
+     * - `{}` or undefined - All tools enabled (default)
+     *
+     * @param agentName - The agent name (e.g., 'plan', 'query', 'curate')
+     * @returns Filtered tool set based on agent configuration
+     */
+    getToolsForAgent(agentName) {
+        const registry = getAgentRegistry();
+        const agent = registry.get(agentName);
+        if (!agent) {
+            // Unknown agent - return all tools
+            return this.getAllTools();
+        }
+        const allTools = this.getAllTools();
+        const toolConfig = agent.tools;
+        // If no tool config or empty, return all tools
+        if (!toolConfig || Object.keys(toolConfig).length === 0) {
+            return allTools;
+        }
+        // Check for wildcard disable
+        const wildcardValue = toolConfig['*'];
+        const filteredTools = {};
+        for (const [toolName, toolDef] of Object.entries(allTools)) {
+            // Get specific config for this tool, or use wildcard, or default to true
+            const isEnabled = toolConfig[toolName] ?? wildcardValue ?? true;
+            if (isEnabled) {
+                filteredTools[toolName] = toolDef;
+            }
+        }
+        return filteredTools;
+    }
     /**
      * Get filtered tools based on command type.
      * For 'query' command, returns only read-only discovery tools.
@@ -225,6 +314,13 @@ export class ToolManager {
     refresh() {
         this.invalidateCache();
     }
+    /**
+     * Generates a unique call ID for tool execution.
+     */
+    generateCallId() {
+        this.callIdCounter++;
+        return `call_${Date.now()}_${this.callIdCounter}`;
+    }
     /**
      * Invalidates the tool cache.
      * Next call to getAllTools() will rebuild the cache.

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

@@ -0,0 +1,6 @@
+import type { IToolProvider } from '../../../core/interfaces/cipher/i-tool-provider.js';
+/**
+ * Lazy getter for ToolProvider to avoid circular dependencies.
+ * Used by batch tool to execute other tools at runtime.
+ */
+export type ToolProviderGetter = () => IToolProvider;

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

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

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

@@ -1,6 +1,7 @@
-import type { ToolSet } from '../../../core/domain/cipher/tools/types.js';
+import type { ToolExecutionContext, 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 { SystemPromptManager } from '../system-prompt/system-prompt-manager.js';
+import type { ToolDescriptionLoader } from './tool-description-loader.js';
 import type { ToolServices } from './tool-registry.js';
 import { ToolMarker } from './tool-markers.js';
 /**
@@ -12,18 +13,20 @@ import { ToolMarker } from './tool-markers.js';
  * 2. Execution phase (via invocation)
  */
 export declare class ToolProvider implements IToolProvider {
+    private readonly descriptionLoader?;
     private initialized;
     private invocationBuilder?;
-    private readonly promptFactory?;
-    private readonly services;
+    private services;
+    private readonly systemPromptManager?;
     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
+     * @param systemPromptManager - Optional system prompt manager for tool output guidance
+     * @param descriptionLoader - Optional loader for external tool descriptions
      */
-    constructor(services: ToolServices, promptFactory?: SimplePromptFactory);
+    constructor(services: ToolServices, systemPromptManager?: SystemPromptManager, descriptionLoader?: ToolDescriptionLoader);
     /**
      * Execute a tool with the given arguments using builder/invocation pattern.
      *
@@ -34,12 +37,13 @@ export declare class ToolProvider implements IToolProvider {
      * @param toolName - Name of the tool to execute
      * @param args - Tool arguments
      * @param sessionId - Optional session ID for context
+     * @param context - Optional execution context (includes metadata callback for streaming)
      * @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>;
+    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string, context?: ToolExecutionContext): Promise<unknown>;
     /**
      * Get all registered tools in JSON Schema format.
      */
@@ -67,11 +71,32 @@ export declare class ToolProvider implements IToolProvider {
     /**
      * Initialize the tool provider.
      * Registers all tools whose required services are available.
+     * If a description loader is provided, tool descriptions are loaded from external files.
      */
     initialize(): Promise<void>;
+    /**
+     * Update services and re-register tools that depend on newly available services.
+     * This is used to inject services that are created after ToolProvider initialization
+     * (e.g., SessionManager which is created after ToolProvider).
+     *
+     * @param additionalServices - Additional services to add
+     */
+    updateServices(additionalServices: Partial<ToolServices>): void;
     /**
      * Ensures the provider is initialized.
      * @throws ToolProviderNotInitializedError if not initialized
      */
     private ensureInitialized;
+    /**
+     * Loads description from external file if configured.
+     * @param descriptionFile - The description file name (without .txt extension)
+     * @returns The loaded description or undefined if not available
+     */
+    private loadExternalDescription;
+    /**
+     * Registers a single tool if all required services are available.
+     * @param toolName - Name of the tool to register
+     * @param entry - Registry entry for the tool
+     */
+    private registerToolIfAvailable;
 }

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

@@ -12,20 +12,23 @@ import { convertZodToJsonSchema } from './utils/schema-converter.js';
  * 2. Execution phase (via invocation)
  */
 export class ToolProvider {
+    descriptionLoader;
     initialized = false;
     invocationBuilder;
-    promptFactory;
     services;
+    systemPromptManager;
     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
+     * @param systemPromptManager - Optional system prompt manager for tool output guidance
+     * @param descriptionLoader - Optional loader for external tool descriptions
      */
-    constructor(services, promptFactory) {
+    constructor(services, systemPromptManager, descriptionLoader) {
         this.services = services;
-        this.promptFactory = promptFactory;
+        this.systemPromptManager = systemPromptManager;
+        this.descriptionLoader = descriptionLoader;
     }
     /**
      * Execute a tool with the given arguments using builder/invocation pattern.
@@ -37,21 +40,26 @@ export class ToolProvider {
      * @param toolName - Name of the tool to execute
      * @param args - Tool arguments
      * @param sessionId - Optional session ID for context
+     * @param context - Optional execution context (includes metadata callback for streaming)
      * @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) {
+    async executeTool(toolName, args, sessionId, context) {
         this.ensureInitialized();
         if (!this.invocationBuilder) {
             throw new ToolProviderNotInitializedError();
         }
         try {
             // Phase 1: Build and validate invocation
-            const context = { sessionId };
+            // Merge sessionId into context for backward compatibility
+            const effectiveContext = {
+                ...context,
+                sessionId: context?.sessionId ?? sessionId,
+            };
             const invocation = this.invocationBuilder.build(`tool_call_${Date.now()}`, // Generate unique ID
-            toolName, args, context);
+            toolName, args, effectiveContext);
             // Phase 2: Execute validated invocation
             const executionResult = await invocation.execute();
             // Handle execution result
@@ -64,8 +72,8 @@ export class ToolProvider {
             }
             // 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 (registryEntry?.outputGuidance && this.systemPromptManager) {
+                const guidance = this.systemPromptManager.getToolOutputGuidance(registryEntry.outputGuidance);
                 if (guidance) {
                     // Return structured result with guidance
                     return {
@@ -156,6 +164,7 @@ export class ToolProvider {
     /**
      * Initialize the tool provider.
      * Registers all tools whose required services are available.
+     * If a description loader is provided, tool descriptions are loaded from external files.
      */
     async initialize() {
         if (this.initialized) {
@@ -163,27 +172,35 @@ export class ToolProvider {
         }
         // 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);
-                }
-            }
+            this.registerToolIfAvailable(toolName, entry);
         }
         // Initialize invocation builder with registered tools
         this.invocationBuilder = new ToolInvocationBuilder(this.tools);
         this.initialized = true;
     }
+    /**
+     * Update services and re-register tools that depend on newly available services.
+     * This is used to inject services that are created after ToolProvider initialization
+     * (e.g., SessionManager which is created after ToolProvider).
+     *
+     * @param additionalServices - Additional services to add
+     */
+    updateServices(additionalServices) {
+        // Merge new services into existing services
+        this.services = { ...this.services, ...additionalServices };
+        // Re-register tools that may now have their required services available
+        for (const [toolName, entry] of Object.entries(TOOL_REGISTRY)) {
+            // Skip if tool is already registered
+            if (this.tools.has(toolName)) {
+                continue;
+            }
+            this.registerToolIfAvailable(toolName, entry);
+        }
+        // Update invocation builder with any newly registered tools
+        if (this.initialized && this.invocationBuilder) {
+            this.invocationBuilder = new ToolInvocationBuilder(this.tools);
+        }
+    }
     /**
      * Ensures the provider is initialized.
      * @throws ToolProviderNotInitializedError if not initialized
@@ -193,4 +210,43 @@ export class ToolProvider {
             throw new ToolProviderNotInitializedError();
         }
     }
+    /**
+     * Loads description from external file if configured.
+     * @param descriptionFile - The description file name (without .txt extension)
+     * @returns The loaded description or undefined if not available
+     */
+    loadExternalDescription(descriptionFile) {
+        if (!descriptionFile || !this.descriptionLoader) {
+            return undefined;
+        }
+        return this.descriptionLoader.load(descriptionFile);
+    }
+    /**
+     * Registers a single tool if all required services are available.
+     * @param toolName - Name of the tool to register
+     * @param entry - Registry entry for the tool
+     */
+    registerToolIfAvailable(toolName, entry) {
+        const allServicesAvailable = entry.requiredServices.every((serviceName) => this.services[serviceName] !== undefined);
+        if (!allServicesAvailable) {
+            return;
+        }
+        try {
+            const tool = entry.factory(this.services);
+            // Override description from external file if available
+            const fileDescription = this.loadExternalDescription(entry.descriptionFile);
+            if (fileDescription) {
+                tool.description = fileDescription;
+            }
+            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);
+        }
+    }
 }

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

@@ -2,7 +2,10 @@ 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 { ITodoStorage } from '../../../core/interfaces/cipher/i-todo-storage.js';
 import type { MemoryManager } from '../memory/memory-manager.js';
+import type { SessionManager } from '../session/session-manager.js';
+import type { ToolProviderGetter } from './tool-provider-getter.js';
 import { ToolMarker } from './tool-markers.js';
 /**
  * Service dependencies available to tools.
@@ -11,10 +14,23 @@ import { ToolMarker } from './tool-markers.js';
 export interface ToolServices {
     /** File system service for file operations */
     fileSystemService?: IFileSystem;
+    /**
+     * Lazy getter for session manager (avoids circular dependency).
+     * SessionManager is created after ToolProvider, so we need a getter.
+     * Used by task tool for subagent delegation.
+     */
+    getSessionManager?: () => SessionManager | undefined;
+    /**
+     * Lazy getter for tool provider (avoids circular dependency).
+     * Used by batch tool to execute other tools.
+     */
+    getToolProvider?: ToolProviderGetter;
     /** Memory manager for agent memory operations */
     memoryManager?: MemoryManager;
     /** Process service for command execution */
     processService?: IProcessService;
+    /** Todo storage service for session-based todo persistence */
+    todoStorage?: ITodoStorage;
 }
 /**
  * Tool factory function type.
@@ -26,6 +42,13 @@ export type ToolFactory = (services: ToolServices) => Tool;
  * Defines the factory, required services, semantic markers, and optional output guidance for each tool.
  */
 export interface ToolRegistryEntry {
+    /**
+     * Optional external description file name (without .txt extension).
+     * If specified, the ToolProvider will load the description from
+     * src/resources/tools/{descriptionFile}.txt instead of using the inline description.
+     * Example: 'bash_exec' will load from 'src/resources/tools/bash_exec.txt'
+     */
+    descriptionFile?: string;
     /** Factory function to create the tool */
     factory: ToolFactory;
     /** Semantic markers for this tool (enables smart filtering and conditional prompts) */