byterover-cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,216 @@
+/**
+ * Tool Invocation Builder Pattern
+ *
+ * Implements a two-phase tool execution architecture:
+ * 1. Builder Phase: Validate tool call and build invocation
+ * 2. Invocation Phase: Execute the validated invocation
+ *
+ * This separation enables:
+ * - Early validation before execution
+ * - Queuing of validated invocations
+ * - Retry logic without re-validation
+ * - Better error handling and debugging
+ */
+import type { Tool, ToolExecutionContext } from '../../../core/domain/cipher/tools/types.js';
+import { ToolError } from '../../../core/domain/cipher/tools/tool-error.js';
+/**
+ * Status of a tool invocation.
+ *
+ * Simplified for autonomous execution - no AWAITING_APPROVAL or CANCELLED states.
+ * Added DENIED for policy rejections.
+ */
+export declare enum ToolInvocationStatus {
+    /**
+     * Invocation completed successfully
+     */
+    COMPLETED = "COMPLETED",
+    /**
+     * Invocation was denied by policy
+     */
+    DENIED = "DENIED",
+    /**
+     * Invocation failed with error
+     */
+    ERROR = "ERROR",
+    /**
+     * Invocation is currently executing
+     */
+    EXECUTING = "EXECUTING",
+    /**
+     * Invocation is scheduled for execution
+     */
+    SCHEDULED = "SCHEDULED",
+    /**
+     * Invocation is validating (builder phase)
+     */
+    VALIDATING = "VALIDATING"
+}
+/**
+ * Result from tool invocation execution
+ */
+export interface ToolInvocationResult {
+    /**
+     * Duration of execution in milliseconds
+     */
+    durationMs: number;
+    /**
+     * Error if execution failed
+     */
+    error?: ToolError;
+    /**
+     * Execution result (if successful)
+     */
+    result?: unknown;
+    /**
+     * Final status after execution
+     */
+    status: ToolInvocationStatus;
+    /**
+     * Timestamp when execution completed
+     */
+    timestamp: number;
+}
+/**
+ * Options for creating a tool invocation
+ */
+export interface ToolInvocationOptions {
+    /**
+     * Validated tool arguments
+     */
+    args: Record<string, unknown>;
+    /**
+     * Execution context (sessionId, etc.)
+     */
+    context: ToolExecutionContext;
+    /**
+     * Unique identifier for this invocation
+     */
+    id: string;
+    /**
+     * Tool instance
+     */
+    tool: Tool;
+    /**
+     * Tool name
+     */
+    toolName: string;
+}
+/**
+ * Validated tool invocation ready for execution
+ *
+ * Contains all information needed to execute a tool call:
+ * - Tool reference and metadata
+ * - Validated arguments
+ * - Execution context
+ * - Status tracking
+ */
+export declare class ToolInvocation {
+    /**
+     * Validated tool arguments
+     */
+    readonly args: Record<string, unknown>;
+    /**
+     * Execution context (sessionId, etc.)
+     */
+    readonly context: ToolExecutionContext;
+    /**
+     * Unique identifier for this invocation
+     */
+    readonly id: string;
+    /**
+     * Tool instance
+     */
+    readonly tool: Tool;
+    /**
+     * Tool name
+     */
+    readonly toolName: string;
+    /**
+     * Current status
+     */
+    private _status;
+    /**
+     * Timestamp when invocation was created
+     */
+    private readonly createdAt;
+    /**
+     * Create a new tool invocation
+     *
+     * @param options - Tool invocation options
+     */
+    constructor(options: ToolInvocationOptions);
+    /**
+     * Get current status
+     */
+    get status(): ToolInvocationStatus;
+    /**
+     * Mark this invocation as denied by policy.
+     *
+     * Can only deny if not yet executing or completed.
+     *
+     * @returns True if denied, false if already executing/completed
+     */
+    deny(): boolean;
+    /**
+     * Execute this invocation
+     *
+     * Transitions through states:
+     * SCHEDULED -> EXECUTING -> COMPLETED/ERROR
+     *
+     * @returns Execution result
+     */
+    execute(): Promise<ToolInvocationResult>;
+    /**
+     * Get age of this invocation in milliseconds
+     */
+    getAge(): number;
+    /**
+     * Check if invocation can be executed
+     */
+    isExecutable(): boolean;
+}
+/**
+ * Builder for creating validated tool invocations
+ *
+ * Validates tool existence, arguments, and builds executable invocations.
+ * Separates validation concerns from execution.
+ */
+export declare class ToolInvocationBuilder {
+    /**
+     * Map of tool name to tool instance
+     */
+    private readonly tools;
+    /**
+     * Create a new tool invocation builder
+     *
+     * @param tools - Map of available tools
+     */
+    constructor(tools: Map<string, Tool>);
+    /**
+     * Build and validate a tool invocation
+     *
+     * Performs validation:
+     * 1. Tool exists
+     * 2. Arguments match schema
+     * 3. Required parameters present
+     *
+     * @param id - Unique invocation ID (e.g., from LLM tool call)
+     * @param toolName - Name of tool to invoke
+     * @param args - Tool arguments
+     * @param context - Execution context
+     * @returns Validated tool invocation ready for execution
+     * @throws ToolError if validation fails
+     */
+    build(id: string, toolName: string, args: Record<string, unknown>, context?: ToolExecutionContext): ToolInvocation;
+    /**
+     * Validate tool arguments without building invocation
+     *
+     * Useful for pre-validation or dry-run checks.
+     *
+     * @param toolName - Name of tool
+     * @param args - Arguments to validate
+     * @returns True if valid
+     * @throws ToolError if validation fails
+     */
+    validate(toolName: string, args: Record<string, unknown>): boolean;
+}

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

@@ -0,0 +1,294 @@
+/**
+ * Tool Invocation Builder Pattern
+ *
+ * Implements a two-phase tool execution architecture:
+ * 1. Builder Phase: Validate tool call and build invocation
+ * 2. Invocation Phase: Execute the validated invocation
+ *
+ * This separation enables:
+ * - Early validation before execution
+ * - Queuing of validated invocations
+ * - Retry logic without re-validation
+ * - Better error handling and debugging
+ */
+import { ToolError, ToolErrorType } from '../../../core/domain/cipher/tools/tool-error.js';
+/**
+ * Status of a tool invocation.
+ *
+ * Simplified for autonomous execution - no AWAITING_APPROVAL or CANCELLED states.
+ * Added DENIED for policy rejections.
+ */
+export var ToolInvocationStatus;
+(function (ToolInvocationStatus) {
+    /**
+     * Invocation completed successfully
+     */
+    ToolInvocationStatus["COMPLETED"] = "COMPLETED";
+    /**
+     * Invocation was denied by policy
+     */
+    ToolInvocationStatus["DENIED"] = "DENIED";
+    /**
+     * Invocation failed with error
+     */
+    ToolInvocationStatus["ERROR"] = "ERROR";
+    /**
+     * Invocation is currently executing
+     */
+    ToolInvocationStatus["EXECUTING"] = "EXECUTING";
+    /**
+     * Invocation is scheduled for execution
+     */
+    ToolInvocationStatus["SCHEDULED"] = "SCHEDULED";
+    /**
+     * Invocation is validating (builder phase)
+     */
+    ToolInvocationStatus["VALIDATING"] = "VALIDATING";
+})(ToolInvocationStatus || (ToolInvocationStatus = {}));
+/**
+ * Validated tool invocation ready for execution
+ *
+ * Contains all information needed to execute a tool call:
+ * - Tool reference and metadata
+ * - Validated arguments
+ * - Execution context
+ * - Status tracking
+ */
+export class ToolInvocation {
+    /**
+     * Validated tool arguments
+     */
+    args;
+    /**
+     * Execution context (sessionId, etc.)
+     */
+    context;
+    /**
+     * Unique identifier for this invocation
+     */
+    id;
+    /**
+     * Tool instance
+     */
+    tool;
+    /**
+     * Tool name
+     */
+    toolName;
+    /**
+     * Current status
+     */
+    _status = ToolInvocationStatus.SCHEDULED;
+    /**
+     * Timestamp when invocation was created
+     */
+    createdAt = Date.now();
+    /**
+     * Create a new tool invocation
+     *
+     * @param options - Tool invocation options
+     */
+    constructor(options) {
+        this.id = options.id;
+        this.toolName = options.toolName;
+        this.tool = options.tool;
+        this.args = options.args;
+        this.context = options.context;
+    }
+    /**
+     * Get current status
+     */
+    get status() {
+        return this._status;
+    }
+    /**
+     * Mark this invocation as denied by policy.
+     *
+     * Can only deny if not yet executing or completed.
+     *
+     * @returns True if denied, false if already executing/completed
+     */
+    deny() {
+        if (this._status === ToolInvocationStatus.EXECUTING ||
+            this._status === ToolInvocationStatus.COMPLETED ||
+            this._status === ToolInvocationStatus.ERROR ||
+            this._status === ToolInvocationStatus.DENIED) {
+            return false;
+        }
+        this._status = ToolInvocationStatus.DENIED;
+        return true;
+    }
+    /**
+     * Execute this invocation
+     *
+     * Transitions through states:
+     * SCHEDULED -> EXECUTING -> COMPLETED/ERROR
+     *
+     * @returns Execution result
+     */
+    async execute() {
+        // Check if invocation was denied by policy
+        if (this._status === ToolInvocationStatus.DENIED) {
+            return {
+                durationMs: 0,
+                error: new ToolError('Tool invocation was denied by policy', ToolErrorType.PERMISSION_DENIED, this.toolName),
+                status: ToolInvocationStatus.DENIED,
+                timestamp: Date.now(),
+            };
+        }
+        // Check if invocation is in executable state
+        if (this._status !== ToolInvocationStatus.SCHEDULED) {
+            return {
+                durationMs: 0,
+                error: new ToolError(`Cannot execute invocation in status: ${this._status}`, ToolErrorType.EXECUTION_FAILED, this.toolName),
+                status: this._status,
+                timestamp: Date.now(),
+            };
+        }
+        // Start execution
+        this._status = ToolInvocationStatus.EXECUTING;
+        const startTime = Date.now();
+        try {
+            // Execute tool with validated arguments
+            const result = await this.tool.execute(this.args, this.context);
+            // Mark as completed
+            this._status = ToolInvocationStatus.COMPLETED;
+            const durationMs = Date.now() - startTime;
+            return {
+                durationMs,
+                result,
+                status: ToolInvocationStatus.COMPLETED,
+                timestamp: Date.now(),
+            };
+        }
+        catch (error) {
+            // Mark as error
+            this._status = ToolInvocationStatus.ERROR;
+            const durationMs = Date.now() - startTime;
+            // Convert to ToolError
+            const toolError = error instanceof ToolError
+                ? error
+                : new ToolError(error instanceof Error ? error.message : String(error), ToolErrorType.EXECUTION_FAILED, this.toolName, { originalError: error instanceof Error ? error : undefined });
+            return {
+                durationMs,
+                error: toolError,
+                status: ToolInvocationStatus.ERROR,
+                timestamp: Date.now(),
+            };
+        }
+    }
+    /**
+     * Get age of this invocation in milliseconds
+     */
+    getAge() {
+        return Date.now() - this.createdAt;
+    }
+    /**
+     * Check if invocation can be executed
+     */
+    isExecutable() {
+        return this._status === ToolInvocationStatus.SCHEDULED;
+    }
+}
+/**
+ * Builder for creating validated tool invocations
+ *
+ * Validates tool existence, arguments, and builds executable invocations.
+ * Separates validation concerns from execution.
+ */
+export class ToolInvocationBuilder {
+    /**
+     * Map of tool name to tool instance
+     */
+    tools;
+    /**
+     * Create a new tool invocation builder
+     *
+     * @param tools - Map of available tools
+     */
+    constructor(tools) {
+        this.tools = tools;
+    }
+    /**
+     * Build and validate a tool invocation
+     *
+     * Performs validation:
+     * 1. Tool exists
+     * 2. Arguments match schema
+     * 3. Required parameters present
+     *
+     * @param id - Unique invocation ID (e.g., from LLM tool call)
+     * @param toolName - Name of tool to invoke
+     * @param args - Tool arguments
+     * @param context - Execution context
+     * @returns Validated tool invocation ready for execution
+     * @throws ToolError if validation fails
+     */
+    build(id, toolName, args, context = {}) {
+        // Check tool exists
+        const tool = this.tools.get(toolName);
+        if (!tool) {
+            throw new ToolError(`Tool '${toolName}' not found`, ToolErrorType.TOOL_NOT_FOUND, toolName, {
+                context: {
+                    availableTools: [...this.tools.keys()],
+                },
+            });
+        }
+        // Validate arguments against schema
+        try {
+            const validatedArgs = tool.inputSchema.parse(args);
+            // Create invocation with validated arguments
+            return new ToolInvocation({
+                args: validatedArgs,
+                context,
+                id,
+                tool,
+                toolName,
+            });
+        }
+        catch (error) {
+            // Handle Zod validation errors
+            if (error && typeof error === 'object' && 'errors' in error) {
+                const zodError = error;
+                const errorMessages = zodError.errors
+                    .map((err) => `${err.path.join('.')}: ${err.message}`)
+                    .join('; ');
+                throw new ToolError(`Invalid arguments: ${errorMessages}`, ToolErrorType.INVALID_PARAMS, toolName, { originalError: error instanceof Error ? error : undefined });
+            }
+            // Handle other validation errors
+            throw new ToolError(error instanceof Error ? error.message : String(error), ToolErrorType.PARAM_VALIDATION_FAILED, toolName, { originalError: error instanceof Error ? error : undefined });
+        }
+    }
+    /**
+     * Validate tool arguments without building invocation
+     *
+     * Useful for pre-validation or dry-run checks.
+     *
+     * @param toolName - Name of tool
+     * @param args - Arguments to validate
+     * @returns True if valid
+     * @throws ToolError if validation fails
+     */
+    validate(toolName, args) {
+        // Check tool exists
+        const tool = this.tools.get(toolName);
+        if (!tool) {
+            throw new ToolError(`Tool '${toolName}' not found`, ToolErrorType.TOOL_NOT_FOUND, toolName);
+        }
+        // Validate against schema
+        try {
+            tool.inputSchema.parse(args);
+            return true;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'errors' in error) {
+                const zodError = error;
+                const errorMessages = zodError.errors
+                    .map((err) => `${err.path.join('.')}: ${err.message}`)
+                    .join('; ');
+                throw new ToolError(`Invalid arguments: ${errorMessages}`, ToolErrorType.INVALID_PARAMS, toolName, { originalError: error instanceof Error ? error : undefined });
+            }
+            throw new ToolError(error instanceof Error ? error.message : String(error), ToolErrorType.PARAM_VALIDATION_FAILED, toolName, { originalError: error instanceof Error ? error : undefined });
+        }
+    }
+}

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

@@ -0,0 +1,135 @@
+import type { 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 { ToolMarker } from './tool-markers.js';
+import { type ToolExecutionResult } 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 declare class ToolManager {
+    /**
+     * Read-only tools allowed for query operations
+     */
+    private static readonly QUERY_TOOL_NAMES;
+    private cacheValid;
+    private readonly scheduler?;
+    private readonly toolProvider;
+    private toolsCache;
+    /**
+     * Creates a new tool manager
+     *
+     * @param toolProvider - Tool provider instance
+     * @param scheduler - Optional tool scheduler for policy-based execution
+     */
+    constructor(toolProvider: IToolProvider, scheduler?: IToolScheduler);
+    /**
+     * 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
+     */
+    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string): Promise<ToolExecutionResult>;
+    /**
+     * Get all available tools in JSON Schema format.
+     * Results are cached for performance.
+     *
+     * @returns Tool set with JSON Schema definitions for LLM
+     */
+    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 available tools
+     */
+    getToolCount(): number;
+    /**
+     * Get names of all registered tools.
+     *
+     * @returns Array of tool names
+     */
+    getToolNames(): string[];
+    /**
+     * 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?: string): 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[];
+    /**
+     * 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?: string): ToolSet;
+    /**
+     * Check if a tool exists.
+     *
+     * @param toolName - Name of the tool
+     * @returns True if the tool exists
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Initialize the tool manager.
+     * Registers all available tools and invalidates cache.
+     */
+    initialize(): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * Invalidates the tool cache.
+     * Next call to getAllTools() will rebuild the cache.
+     */
+    private invalidateCache;
+}