byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/tools/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export { LoggingPlugin } from './logging-plugin.js';
+export { ToolPluginManager } from './plugin-manager.js';
+export type { BeforeTriggerResult } from './plugin-manager.js';

package/dist/infra/cipher/tools/plugins/index.js

@@ -0,0 +1,2 @@
+export { LoggingPlugin } from './logging-plugin.js';
+export { ToolPluginManager } from './plugin-manager.js';

package/dist/infra/cipher/tools/plugins/logging-plugin.d.ts

@@ -0,0 +1,28 @@
+import type { ToolExecutionResult } from '../../../../core/domain/cipher/tools/tool-error.js';
+import type { ILogger } from '../../../../core/interfaces/cipher/i-logger.js';
+import type { BeforeHookResult, IToolPlugin, ToolHookContext } from '../../../../core/interfaces/cipher/i-tool-plugin.js';
+/**
+ * Example plugin that logs tool execution.
+ *
+ * Demonstrates how to implement the IToolPlugin interface
+ * for logging/auditing purposes.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger('tools')
+ * const loggingPlugin = new LoggingPlugin(logger)
+ * pluginManager.register(loggingPlugin)
+ * ```
+ */
+export declare class LoggingPlugin implements IToolPlugin {
+    readonly name = "logging";
+    readonly priority = 1;
+    private readonly logger;
+    constructor(logger: ILogger);
+    afterExecute(ctx: ToolHookContext, _args: Record<string, unknown>, result: ToolExecutionResult): void;
+    beforeExecute(ctx: ToolHookContext, args: Record<string, unknown>): BeforeHookResult;
+    /**
+     * Sanitize args for logging (truncate large values, redact sensitive data).
+     */
+    private sanitizeArgs;
+}

package/dist/infra/cipher/tools/plugins/logging-plugin.js

@@ -0,0 +1,66 @@
+/**
+ * Example plugin that logs tool execution.
+ *
+ * Demonstrates how to implement the IToolPlugin interface
+ * for logging/auditing purposes.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger('tools')
+ * const loggingPlugin = new LoggingPlugin(logger)
+ * pluginManager.register(loggingPlugin)
+ * ```
+ */
+export class LoggingPlugin {
+    name = 'logging';
+    priority = 1; // Execute early to capture all events
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    afterExecute(ctx, _args, result) {
+        const duration = result.metadata?.durationMs ?? 'unknown';
+        if (result.success) {
+            this.logger.debug(`[Tool] ${ctx.toolName} completed in ${duration}ms`, {
+                callId: ctx.callId,
+                sessionId: ctx.sessionId,
+            });
+        }
+        else {
+            this.logger.warn(`[Tool] ${ctx.toolName} failed in ${duration}ms: ${result.errorMessage}`, {
+                callId: ctx.callId,
+                errorType: result.errorType,
+                sessionId: ctx.sessionId,
+            });
+        }
+    }
+    beforeExecute(ctx, args) {
+        this.logger.debug(`[Tool] ${ctx.toolName} starting`, {
+            args: this.sanitizeArgs(args),
+            callId: ctx.callId,
+            sessionId: ctx.sessionId,
+        });
+        return { proceed: true };
+    }
+    /**
+     * Sanitize args for logging (truncate large values, redact sensitive data).
+     */
+    sanitizeArgs(args) {
+        const sanitized = {};
+        const maxLength = 200;
+        for (const [key, value] of Object.entries(args)) {
+            // Redact potentially sensitive fields
+            if (key.toLowerCase().includes('password') || key.toLowerCase().includes('secret')) {
+                sanitized[key] = '[REDACTED]';
+                continue;
+            }
+            // Truncate long strings
+            if (typeof value === 'string' && value.length > maxLength) {
+                sanitized[key] = `${value.slice(0, maxLength)}... (${value.length} chars)`;
+                continue;
+            }
+            sanitized[key] = value;
+        }
+        return sanitized;
+    }
+}

package/dist/infra/cipher/tools/plugins/plugin-manager.d.ts

@@ -0,0 +1,81 @@
+import type { ToolExecutionResult } from '../../../../core/domain/cipher/tools/tool-error.js';
+import type { IToolPlugin, ToolHookContext } from '../../../../core/interfaces/cipher/i-tool-plugin.js';
+/**
+ * Result from triggering before hooks.
+ */
+export interface BeforeTriggerResult {
+    /** Modified arguments (may differ from original if plugins transformed them) */
+    args: Record<string, unknown>;
+    /** Whether to proceed with execution */
+    proceed: boolean;
+    /** Reason for blocking (if proceed is false) */
+    reason?: string;
+}
+/**
+ * Manages tool execution plugins.
+ *
+ * Provides a plugin system for extending tool behavior with before/after hooks.
+ * Plugins are executed in priority order (lower priority = earlier execution).
+ *
+ * @example
+ * ```typescript
+ * const manager = new ToolPluginManager()
+ * manager.register(loggingPlugin)
+ * manager.register(validationPlugin)
+ *
+ * // Before execution
+ * const { proceed, args } = await manager.triggerBefore(ctx, originalArgs)
+ * if (!proceed) return error
+ *
+ * // Execute tool...
+ *
+ * // After execution
+ * await manager.triggerAfter(ctx, args, result)
+ * ```
+ */
+export declare class ToolPluginManager {
+    private static readonly DEFAULT_PRIORITY;
+    private plugins;
+    /**
+     * Get all registered plugins.
+     * @returns Array of registered plugins in priority order
+     */
+    getPlugins(): readonly IToolPlugin[];
+    /**
+     * Register a plugin.
+     * Plugins are automatically sorted by priority after registration.
+     *
+     * @param plugin - Plugin to register
+     */
+    register(plugin: IToolPlugin): void;
+    /**
+     * Trigger all afterExecute hooks.
+     * Errors in individual plugins are caught and logged but don't propagate.
+     *
+     * @param ctx - Hook context
+     * @param args - Arguments that were passed to the tool
+     * @param result - Tool execution result
+     */
+    triggerAfter(ctx: ToolHookContext, args: Record<string, unknown>, result: ToolExecutionResult): Promise<void>;
+    /**
+     * Trigger all beforeExecute hooks in priority order.
+     * If any plugin returns proceed: false, execution stops and returns that result.
+     * Arguments can be transformed by plugins (each receives the previous plugin's output).
+     *
+     * @param ctx - Hook context
+     * @param args - Original arguments
+     * @returns Result indicating whether to proceed and final arguments
+     */
+    triggerBefore(ctx: ToolHookContext, args: Record<string, unknown>): Promise<BeforeTriggerResult>;
+    /**
+     * Unregister a plugin by name.
+     *
+     * @param name - Name of the plugin to unregister
+     * @returns True if a plugin was removed
+     */
+    unregister(name: string): boolean;
+    /**
+     * Sort plugins by priority (ascending).
+     */
+    private sortByPriority;
+}

package/dist/infra/cipher/tools/plugins/plugin-manager.js

@@ -0,0 +1,122 @@
+/**
+ * Manages tool execution plugins.
+ *
+ * Provides a plugin system for extending tool behavior with before/after hooks.
+ * Plugins are executed in priority order (lower priority = earlier execution).
+ *
+ * @example
+ * ```typescript
+ * const manager = new ToolPluginManager()
+ * manager.register(loggingPlugin)
+ * manager.register(validationPlugin)
+ *
+ * // Before execution
+ * const { proceed, args } = await manager.triggerBefore(ctx, originalArgs)
+ * if (!proceed) return error
+ *
+ * // Execute tool...
+ *
+ * // After execution
+ * await manager.triggerAfter(ctx, args, result)
+ * ```
+ */
+export class ToolPluginManager {
+    static DEFAULT_PRIORITY = 100;
+    plugins = [];
+    /**
+     * Get all registered plugins.
+     * @returns Array of registered plugins in priority order
+     */
+    getPlugins() {
+        return this.plugins;
+    }
+    /**
+     * Register a plugin.
+     * Plugins are automatically sorted by priority after registration.
+     *
+     * @param plugin - Plugin to register
+     */
+    register(plugin) {
+        this.plugins.push(plugin);
+        this.sortByPriority();
+    }
+    /**
+     * Trigger all afterExecute hooks.
+     * Errors in individual plugins are caught and logged but don't propagate.
+     *
+     * @param ctx - Hook context
+     * @param args - Arguments that were passed to the tool
+     * @param result - Tool execution result
+     */
+    async triggerAfter(ctx, args, result) {
+        const promises = this.plugins
+            .filter((plugin) => plugin.afterExecute)
+            .map(async (plugin) => {
+            try {
+                await plugin.afterExecute(ctx, args, result);
+            }
+            catch (error) {
+                console.warn(`Plugin ${plugin.name} afterExecute failed:`, error);
+            }
+        });
+        await Promise.all(promises);
+    }
+    /**
+     * Trigger all beforeExecute hooks in priority order.
+     * If any plugin returns proceed: false, execution stops and returns that result.
+     * Arguments can be transformed by plugins (each receives the previous plugin's output).
+     *
+     * @param ctx - Hook context
+     * @param args - Original arguments
+     * @returns Result indicating whether to proceed and final arguments
+     */
+    async triggerBefore(ctx, args) {
+        const pluginsWithBefore = this.plugins.filter((plugin) => plugin.beforeExecute);
+        // Sequential execution required: each plugin may modify args for the next
+        const processPlugin = async (index, currentArgs) => {
+            if (index >= pluginsWithBefore.length) {
+                return {
+                    args: currentArgs,
+                    proceed: true,
+                };
+            }
+            const plugin = pluginsWithBefore[index];
+            try {
+                const result = await plugin.beforeExecute(ctx, currentArgs);
+                if (!result.proceed) {
+                    return {
+                        args: currentArgs,
+                        proceed: false,
+                        reason: result.reason,
+                    };
+                }
+                const nextArgs = result.args ?? currentArgs;
+                return processPlugin(index + 1, nextArgs);
+            }
+            catch (error) {
+                console.warn(`Plugin ${plugin.name} beforeExecute failed:`, error);
+                // Continue with next plugin on error
+                return processPlugin(index + 1, currentArgs);
+            }
+        };
+        return processPlugin(0, { ...args });
+    }
+    /**
+     * Unregister a plugin by name.
+     *
+     * @param name - Name of the plugin to unregister
+     * @returns True if a plugin was removed
+     */
+    unregister(name) {
+        const initialLength = this.plugins.length;
+        this.plugins = this.plugins.filter((p) => p.name !== name);
+        return this.plugins.length < initialLength;
+    }
+    /**
+     * Sort plugins by priority (ascending).
+     */
+    sortByPriority() {
+        this.plugins.sort((a, b) => (a.priority ?? ToolPluginManager.DEFAULT_PRIORITY) -
+            (b.priority ?? ToolPluginManager.DEFAULT_PRIORITY));
+    }
+}

package/dist/infra/cipher/tools/streaming/index.d.ts

@@ -0,0 +1 @@
+export { ToolMetadataHandler } from './metadata-handler.js';

package/dist/infra/cipher/tools/streaming/index.js

@@ -0,0 +1 @@
+export { ToolMetadataHandler } from './metadata-handler.js';

package/dist/infra/cipher/tools/streaming/metadata-handler.d.ts

@@ -0,0 +1,31 @@
+import type { MetadataCallback } from '../../../../core/domain/cipher/tools/types.js';
+import type { SessionEventBus } from '../../events/event-emitter.js';
+/**
+ * Handles real-time metadata streaming from tools during execution.
+ *
+ * Creates metadata callbacks that tools can use to push updates
+ * (e.g., streaming bash output) which are then emitted as events.
+ *
+ * @example
+ * ```typescript
+ * const handler = new ToolMetadataHandler(eventBus)
+ * const callback = handler.createCallback('call_123', 'bash_exec')
+ *
+ * // Tool can now stream updates:
+ * callback({ output: 'Building...\n', description: 'Running npm build' })
+ * callback({ output: 'Done!\n', progress: 100 })
+ * ```
+ */
+export declare class ToolMetadataHandler {
+    private readonly eventBus;
+    constructor(eventBus: SessionEventBus);
+    /**
+     * Creates a metadata callback for a specific tool call.
+     * The callback will emit 'llmservice:toolMetadata' events when invoked.
+     *
+     * @param callId - Unique identifier for the tool call
+     * @param toolName - Name of the tool being executed
+     * @returns Callback function for the tool to push metadata updates
+     */
+    createCallback(callId: string, toolName: string): MetadataCallback;
+}

package/dist/infra/cipher/tools/streaming/metadata-handler.js

@@ -0,0 +1,39 @@
+/**
+ * Handles real-time metadata streaming from tools during execution.
+ *
+ * Creates metadata callbacks that tools can use to push updates
+ * (e.g., streaming bash output) which are then emitted as events.
+ *
+ * @example
+ * ```typescript
+ * const handler = new ToolMetadataHandler(eventBus)
+ * const callback = handler.createCallback('call_123', 'bash_exec')
+ *
+ * // Tool can now stream updates:
+ * callback({ output: 'Building...\n', description: 'Running npm build' })
+ * callback({ output: 'Done!\n', progress: 100 })
+ * ```
+ */
+export class ToolMetadataHandler {
+    eventBus;
+    constructor(eventBus) {
+        this.eventBus = eventBus;
+    }
+    /**
+     * Creates a metadata callback for a specific tool call.
+     * The callback will emit 'llmservice:toolMetadata' events when invoked.
+     *
+     * @param callId - Unique identifier for the tool call
+     * @param toolName - Name of the tool being executed
+     * @returns Callback function for the tool to push metadata updates
+     */
+    createCallback(callId, toolName) {
+        return (update) => {
+            this.eventBus.emit('llmservice:toolMetadata', {
+                callId,
+                metadata: update,
+                toolName,
+            });
+        };
+    }
+}

package/dist/infra/cipher/tools/tool-description-loader.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Loads tool descriptions from external .txt files.
+ *
+ * This service enables tool descriptions to be stored in external files
+ * for easier editing without code changes. It implements lazy loading
+ * with caching for performance, following the same pattern as SimplePromptFactory.
+ *
+ * Features:
+ * - Lazy loading: Descriptions are only loaded when requested
+ * - Caching: Loaded descriptions are cached to avoid repeated file reads
+ * - Fallback: Returns undefined if file not found, allowing inline fallback
+ * - Path resolution: Handles compiled dist vs source paths automatically
+ */
+export declare class ToolDescriptionLoader {
+    private readonly basePath;
+    private readonly cache;
+    /**
+     * Creates a new tool description loader.
+     *
+     * @param basePath - Base path for tool description files.
+     *                   Defaults to dist/resources/tools/ relative to this file.
+     */
+    constructor(basePath?: string);
+    /**
+     * Clear the description cache.
+     * Useful for testing or hot-reloading descriptions.
+     */
+    clearCache(): void;
+    /**
+     * Get the base path for tool descriptions.
+     *
+     * @returns The base path being used for loading descriptions
+     */
+    getBasePath(): string;
+    /**
+     * Check if a description file exists for a tool.
+     *
+     * @param toolName - Name of the tool
+     * @returns True if the description file exists
+     */
+    has(toolName: string): boolean;
+    /**
+     * Load description for a tool from its .txt file.
+     *
+     * @param toolName - Name of the tool (e.g., 'bash_exec')
+     * @returns Description text, or undefined if file not found
+     */
+    load(toolName: string): string | undefined;
+    /**
+     * Preload descriptions for multiple tools.
+     * Useful for batch initialization.
+     *
+     * @param toolNames - Array of tool names to preload
+     * @returns Map of tool names to their descriptions (excludes not found)
+     */
+    preload(toolNames: string[]): Map<string, string>;
+}

package/dist/infra/cipher/tools/tool-description-loader.js

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Loads tool descriptions from external .txt files.
+ *
+ * This service enables tool descriptions to be stored in external files
+ * for easier editing without code changes. It implements lazy loading
+ * with caching for performance, following the same pattern as SimplePromptFactory.
+ *
+ * Features:
+ * - Lazy loading: Descriptions are only loaded when requested
+ * - Caching: Loaded descriptions are cached to avoid repeated file reads
+ * - Fallback: Returns undefined if file not found, allowing inline fallback
+ * - Path resolution: Handles compiled dist vs source paths automatically
+ */
+export class ToolDescriptionLoader {
+    basePath;
+    cache = new Map();
+    /**
+     * Creates a new tool description loader.
+     *
+     * @param basePath - Base path for tool description files.
+     *                   Defaults to dist/resources/tools/ relative to this file.
+     */
+    constructor(basePath) {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        // When compiled: dist/infra/cipher/tools/tool-description-loader.js
+        // Resources are at: dist/resources/tools/
+        // So we need to go up 3 levels: ../../../resources/tools
+        this.basePath = basePath ?? path.join(currentDir, '../../../resources/tools');
+    }
+    /**
+     * Clear the description cache.
+     * Useful for testing or hot-reloading descriptions.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Get the base path for tool descriptions.
+     *
+     * @returns The base path being used for loading descriptions
+     */
+    getBasePath() {
+        return this.basePath;
+    }
+    /**
+     * Check if a description file exists for a tool.
+     *
+     * @param toolName - Name of the tool
+     * @returns True if the description file exists
+     */
+    has(toolName) {
+        // Check cache first
+        if (this.cache.has(toolName)) {
+            return true;
+        }
+        // Check file system
+        const filePath = path.join(this.basePath, `${toolName}.txt`);
+        return fs.existsSync(filePath);
+    }
+    /**
+     * Load description for a tool from its .txt file.
+     *
+     * @param toolName - Name of the tool (e.g., 'bash_exec')
+     * @returns Description text, or undefined if file not found
+     */
+    load(toolName) {
+        // Check cache first
+        if (this.cache.has(toolName)) {
+            return this.cache.get(toolName);
+        }
+        // Build file path
+        const filePath = path.join(this.basePath, `${toolName}.txt`);
+        // Check if file exists
+        if (!fs.existsSync(filePath)) {
+            return undefined;
+        }
+        // Load and cache the description
+        try {
+            const description = fs.readFileSync(filePath, 'utf8').trim();
+            this.cache.set(toolName, description);
+            return description;
+        }
+        catch {
+            // Return undefined on read errors (e.g., permission issues)
+            return undefined;
+        }
+    }
+    /**
+     * Preload descriptions for multiple tools.
+     * Useful for batch initialization.
+     *
+     * @param toolNames - Array of tool names to preload
+     * @returns Map of tool names to their descriptions (excludes not found)
+     */
+    preload(toolNames) {
+        const loaded = new Map();
+        for (const toolName of toolNames) {
+            const description = this.load(toolName);
+            if (description !== undefined) {
+                loaded.set(toolName, description);
+            }
+        }
+        return loaded;
+    }
+}

package/dist/infra/cipher/tools/tool-manager.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 { IToolScheduler } from '../../../core/interfaces/cipher/i-tool-scheduler.js';
+import type { ToolPluginManager } from './plugins/plugin-manager.js';
 import type { ToolMarker } from './tool-markers.js';
 import { type ToolExecutionResult } from '../../../core/domain/cipher/tools/tool-error.js';
 /**
@@ -11,6 +12,7 @@ import { type ToolExecutionResult } from '../../../core/domain/cipher/tools/tool
  *
  * 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
  *
@@ -18,6 +20,11 @@ import { type ToolExecutionResult } from '../../../core/domain/cipher/tools/tool
  * 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 declare class ToolManager {
@@ -30,6 +37,8 @@ export declare class ToolManager {
      */
     private static readonly QUERY_TOOL_NAMES;
     private cacheValid;
+    private callIdCounter;
+    private readonly pluginManager?;
     private readonly scheduler?;
     private readonly toolProvider;
     private toolsCache;
@@ -38,8 +47,9 @@ export declare 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: IToolProvider, scheduler?: IToolScheduler);
+    constructor(toolProvider: IToolProvider, scheduler?: IToolScheduler, pluginManager?: ToolPluginManager);
     /**
      * Execute a tool by name with structured error handling.
      *
@@ -47,7 +57,12 @@ export declare 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)
      *
@@ -56,9 +71,10 @@ export declare 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
      */
-    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string): Promise<ToolExecutionResult>;
+    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string, context?: ToolExecutionContext): Promise<ToolExecutionResult>;
     /**
      * Get all available tools in JSON Schema format.
      * Results are cached for performance.
@@ -101,6 +117,20 @@ export declare class ToolManager {
      * @returns Array of tool names with the specified marker
      */
     getToolsByMarker(marker: ToolMarker): string[];
+    /**
+     * 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: string): ToolSet;
     /**
      * Get filtered tools based on command type.
      * For 'query' command, returns only read-only discovery tools.
@@ -133,6 +163,10 @@ export declare class ToolManager {
      * - Manual cache clearing needed
      */
     refresh(): void;
+    /**
+     * Generates a unique call ID for tool execution.
+     */
+    private generateCallId;
     /**
      * Invalidates the tool cache.
      * Next call to getAllTools() will rebuild the cache.