byterover-cli 0.2.1 → 0.3.0

package/dist/core/domain/cipher/todos/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Todo status values.
+ * Only ONE task can be "in_progress" at any time.
+ */
+export declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "cancelled"];
+/**
+ * Union type of valid todo statuses.
+ */
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+/**
+ * Represents a single todo item.
+ */
+export interface Todo {
+    /**
+     * Present continuous form shown during execution.
+     * Example: "Running tests", "Building the project"
+     */
+    activeForm: string;
+    /**
+     * Imperative description of what needs to be done.
+     * Example: "Run tests", "Build the project"
+     */
+    content: string;
+    /**
+     * Current status of the todo.
+     * - pending: Not yet started
+     * - in_progress: Currently working on (only ONE at a time)
+     * - completed: Successfully finished
+     * - cancelled: No longer needed
+     */
+    status: TodoStatus;
+}
+/**
+ * List of todos maintained by the agent.
+ */
+export interface TodoList {
+    /**
+     * All todo items.
+     */
+    todos: Todo[];
+}
+/**
+ * Result of write_todos tool execution.
+ * Contains both LLM-facing content and display-facing content.
+ */
+export interface WriteTodosResult {
+    /**
+     * Content to send back to the LLM.
+     */
+    llmContent: string;
+    /**
+     * Display content for rendering to user.
+     */
+    returnDisplay: {
+        todos: Todo[];
+    };
+}

package/dist/core/domain/cipher/todos/types.js

@@ -0,0 +1,5 @@
+/**
+ * Todo status values.
+ * Only ONE task can be "in_progress" at any time.
+ */
+export const TODO_STATUSES = ['pending', 'in_progress', 'completed', 'cancelled'];

package/dist/core/domain/cipher/tools/constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Known tool names.
+ * These constants ensure type safety and prevent typos.
+ */
+export declare const ToolName: {
+    readonly BASH_EXEC: 'bash_exec';
+    readonly BASH_OUTPUT: 'bash_output';
+    readonly CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic';
+    readonly DELETE_MEMORY: 'delete_memory';
+    readonly DETECT_DOMAINS: 'detect_domains';
+    readonly EDIT_FILE: 'edit_file';
+    readonly EDIT_MEMORY: 'edit_memory';
+    readonly FIND_KNOWLEDGE_TOPICS: 'find_knowledge_topics';
+    readonly GLOB_FILES: 'glob_files';
+    readonly GREP_CONTENT: 'grep_content';
+    readonly KILL_PROCESS: 'kill_process';
+    readonly LIST_MEMORIES: 'list_memories';
+    readonly READ_FILE: 'read_file';
+    readonly READ_MEMORY: 'read_memory';
+    readonly SEARCH_HISTORY: 'search_history';
+    readonly WRITE_FILE: 'write_file';
+    readonly WRITE_MEMORY: 'write_memory';
+    readonly WRITE_TODOS: 'write_todos';
+};
+/**
+ * Union type of all known tool names.
+ */
+export type KnownTool = (typeof ToolName)[keyof typeof ToolName];

package/dist/core/domain/cipher/tools/constants.js

@@ -0,0 +1,24 @@
+/**
+ * Known tool names.
+ * These constants ensure type safety and prevent typos.
+ */
+export const ToolName = {
+    BASH_EXEC: 'bash_exec',
+    BASH_OUTPUT: 'bash_output',
+    CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic',
+    DELETE_MEMORY: 'delete_memory',
+    DETECT_DOMAINS: 'detect_domains',
+    EDIT_FILE: 'edit_file',
+    EDIT_MEMORY: 'edit_memory',
+    FIND_KNOWLEDGE_TOPICS: 'find_knowledge_topics',
+    GLOB_FILES: 'glob_files',
+    GREP_CONTENT: 'grep_content',
+    KILL_PROCESS: 'kill_process',
+    LIST_MEMORIES: 'list_memories',
+    READ_FILE: 'read_file',
+    READ_MEMORY: 'read_memory',
+    SEARCH_HISTORY: 'search_history',
+    WRITE_FILE: 'write_file',
+    WRITE_MEMORY: 'write_memory',
+    WRITE_TODOS: 'write_todos',
+};

package/dist/core/domain/cipher/tools/tool-error.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Tool Error Types and Classes
+ *
+ * Provides structured error classification for tool execution failures.
+ * Enables better error handling, debugging, and LLM guidance.
+ */
+/**
+ * Enum of all possible tool error types.
+ * Each type represents a specific failure category.
+ */
+export declare enum ToolErrorType {
+    CANCELLED = "CANCELLED",
+    CONFIRMATION_REJECTED = "CONFIRMATION_REJECTED",
+    EXECUTION_FAILED = "EXECUTION_FAILED",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    INVALID_PARAM_TYPE = "INVALID_PARAM_TYPE",
+    INVALID_PARAMS = "INVALID_PARAMS",
+    MISSING_REQUIRED_PARAM = "MISSING_REQUIRED_PARAM",
+    PARAM_VALIDATION_FAILED = "PARAM_VALIDATION_FAILED",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    TIMEOUT = "TIMEOUT",
+    TOOL_DISABLED = "TOOL_DISABLED",
+    TOOL_NOT_FOUND = "TOOL_NOT_FOUND"
+}
+/**
+ * Structured result from tool execution.
+ * Provides consistent format for both success and error cases.
+ */
+export interface ToolExecutionResult {
+    /**
+     * Tool output content (any type - will be stringified by ToolOutputProcessor)
+     * For errors, contains error message formatted for LLM
+     */
+    content: unknown;
+    /**
+     * Detailed error message (only present on failure)
+     */
+    errorMessage?: string;
+    /**
+     * Error type classification (only present on failure)
+     */
+    errorType?: ToolErrorType;
+    /**
+     * Additional metadata about the execution
+     */
+    metadata?: {
+        /**
+         * Any other custom metadata
+         */
+        [key: string]: unknown;
+        /**
+         * Execution duration in milliseconds
+         */
+        durationMs?: number;
+        /**
+         * Original content length before truncation
+         */
+        originalLength?: number;
+        /**
+         * Path to file if output was saved
+         */
+        savedToFile?: string;
+        /**
+         * Token count for the result (if available)
+         */
+        tokensUsed?: number;
+        /**
+         * Whether output was truncated
+         */
+        truncated?: boolean;
+    };
+    /**
+     * Whether the tool executed successfully
+     */
+    success: boolean;
+}
+/**
+ * Options for creating a ToolError
+ */
+export interface ToolErrorOptions {
+    /**
+     * Additional context about the error
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Original error that caused the failure
+     */
+    originalError?: Error;
+}
+/**
+ * Structured error class for tool failures.
+ * Wraps error information with type classification.
+ */
+export declare class ToolError extends Error {
+    /**
+     * Additional context about the error
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * Original error that caused the failure (if any)
+     */
+    readonly originalError?: Error;
+    /**
+     * Name of the tool that failed
+     */
+    readonly toolName: string;
+    /**
+     * Classified error type
+     */
+    readonly type: ToolErrorType;
+    /**
+     * Create a new ToolError
+     *
+     * @param message - Human-readable error message
+     * @param type - Classified error type
+     * @param toolName - Name of the tool that failed
+     * @param options - Optional error context and original error
+     */
+    constructor(message: string, type: ToolErrorType, toolName: string, options?: ToolErrorOptions);
+    /**
+     * Convert error to JSON for serialization
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Format error message for LLM consumption
+     * Provides clear, actionable error information
+     */
+    toLLMMessage(): string;
+}
+/**
+ * Utility functions for error classification and handling
+ */
+export declare class ToolErrorUtils {
+    /**
+     * Classify an unknown error into a ToolError
+     *
+     * @param error - Error to classify
+     * @param toolName - Name of the tool
+     * @returns Classified ToolError
+     */
+    static classify(error: unknown, toolName: string): ToolError;
+    /**
+     * Create an error result from a ToolError
+     *
+     * @param toolError - Tool error to convert
+     * @param metadata - Optional metadata
+     * @returns Error result
+     */
+    static createErrorResult(toolError: ToolError, metadata?: ToolExecutionResult['metadata']): ToolExecutionResult;
+    /**
+     * Create a success result
+     *
+     * Note: Content is passed through as-is (not stringified here).
+     * ToolOutputProcessor.stringify() handles proper JSON serialization later.
+     *
+     * @param content - Tool output content
+     * @param metadata - Optional metadata
+     * @returns Success result
+     */
+    static createSuccess(content: unknown, metadata?: ToolExecutionResult['metadata']): ToolExecutionResult;
+    /**
+     * Format error for LLM with specific guidance based on error type
+     *
+     * @param toolError - Tool error to format
+     * @returns Formatted error message for LLM
+     */
+    static formatForLLM(toolError: ToolError): string;
+    /**
+     * Check if an error is retryable
+     *
+     * @param toolError - Tool error to check
+     * @returns True if the error might succeed on retry
+     */
+    static isRetryable(toolError: ToolError): boolean;
+    /**
+     * Get actionable guidance for an error type
+     *
+     * @param errorType - Type of error
+     * @returns Guidance message or null
+     */
+    private static getGuidanceForErrorType;
+}

package/dist/core/domain/cipher/tools/tool-error.js

@@ -0,0 +1,246 @@
+/**
+ * Tool Error Types and Classes
+ *
+ * Provides structured error classification for tool execution failures.
+ * Enables better error handling, debugging, and LLM guidance.
+ */
+/**
+ * Enum of all possible tool error types.
+ * Each type represents a specific failure category.
+ */
+export var ToolErrorType;
+(function (ToolErrorType) {
+    // Discovery errors - tool not found or unavailable
+    ToolErrorType["CANCELLED"] = "CANCELLED";
+    ToolErrorType["CONFIRMATION_REJECTED"] = "CONFIRMATION_REJECTED";
+    ToolErrorType["EXECUTION_FAILED"] = "EXECUTION_FAILED";
+    ToolErrorType["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    ToolErrorType["INVALID_PARAM_TYPE"] = "INVALID_PARAM_TYPE";
+    ToolErrorType["INVALID_PARAMS"] = "INVALID_PARAMS";
+    ToolErrorType["MISSING_REQUIRED_PARAM"] = "MISSING_REQUIRED_PARAM";
+    ToolErrorType["PARAM_VALIDATION_FAILED"] = "PARAM_VALIDATION_FAILED";
+    ToolErrorType["PERMISSION_DENIED"] = "PERMISSION_DENIED";
+    ToolErrorType["PROVIDER_ERROR"] = "PROVIDER_ERROR";
+    ToolErrorType["TIMEOUT"] = "TIMEOUT";
+    ToolErrorType["TOOL_DISABLED"] = "TOOL_DISABLED";
+    ToolErrorType["TOOL_NOT_FOUND"] = "TOOL_NOT_FOUND";
+})(ToolErrorType || (ToolErrorType = {}));
+/**
+ * Structured error class for tool failures.
+ * Wraps error information with type classification.
+ */
+export class ToolError extends Error {
+    /**
+     * Additional context about the error
+     */
+    context;
+    /**
+     * Original error that caused the failure (if any)
+     */
+    originalError;
+    /**
+     * Name of the tool that failed
+     */
+    toolName;
+    /**
+     * Classified error type
+     */
+    type;
+    /**
+     * Create a new ToolError
+     *
+     * @param message - Human-readable error message
+     * @param type - Classified error type
+     * @param toolName - Name of the tool that failed
+     * @param options - Optional error context and original error
+     */
+    constructor(message, type, toolName, options) {
+        super(message);
+        this.name = 'ToolError';
+        this.type = type;
+        this.toolName = toolName;
+        this.originalError = options?.originalError;
+        this.context = options?.context;
+        // Maintain proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ToolError);
+        }
+    }
+    /**
+     * Convert error to JSON for serialization
+     */
+    toJSON() {
+        return {
+            context: this.context,
+            message: this.message,
+            name: this.name,
+            originalError: this.originalError?.message,
+            toolName: this.toolName,
+            type: this.type,
+        };
+    }
+    /**
+     * Format error message for LLM consumption
+     * Provides clear, actionable error information
+     */
+    toLLMMessage() {
+        const parts = [
+            `Tool execution failed: ${this.toolName}`,
+            `Error type: ${this.type}`,
+            `Message: ${this.message}`,
+        ];
+        if (this.context && Object.keys(this.context).length > 0) {
+            parts.push(`Context: ${JSON.stringify(this.context)}`);
+        }
+        return parts.join('\n');
+    }
+}
+/**
+ * Utility functions for error classification and handling
+ */
+export class ToolErrorUtils {
+    /**
+     * Classify an unknown error into a ToolError
+     *
+     * @param error - Error to classify
+     * @param toolName - Name of the tool
+     * @returns Classified ToolError
+     */
+    static classify(error, toolName) {
+        // Already a ToolError - return as-is
+        if (error instanceof ToolError) {
+            return error;
+        }
+        // Convert to ToolError with classification
+        if (error instanceof Error) {
+            const message = error.message.toLowerCase();
+            // Classify based on error message patterns
+            if (message.includes('not found') || message.includes('does not exist')) {
+                return new ToolError(error.message, ToolErrorType.TOOL_NOT_FOUND, toolName, { originalError: error });
+            }
+            if (message.includes('timeout') || message.includes('timed out')) {
+                return new ToolError(error.message, ToolErrorType.TIMEOUT, toolName, { originalError: error });
+            }
+            if (message.includes('permission') || message.includes('unauthorized') || message.includes('forbidden')) {
+                return new ToolError(error.message, ToolErrorType.PERMISSION_DENIED, toolName, { originalError: error });
+            }
+            if (message.includes('cancelled') || message.includes('abort')) {
+                return new ToolError(error.message, ToolErrorType.CANCELLED, toolName, { originalError: error });
+            }
+            if (message.includes('invalid') || message.includes('validation')) {
+                return new ToolError(error.message, ToolErrorType.INVALID_PARAMS, toolName, { originalError: error });
+            }
+            if (message.includes('required') || message.includes('missing')) {
+                return new ToolError(error.message, ToolErrorType.MISSING_REQUIRED_PARAM, toolName, { originalError: error });
+            }
+            // Default to execution failed
+            return new ToolError(error.message, ToolErrorType.EXECUTION_FAILED, toolName, { originalError: error });
+        }
+        // Non-Error object - wrap as internal error
+        return new ToolError(String(error), ToolErrorType.INTERNAL_ERROR, toolName, { context: { originalValue: error } });
+    }
+    /**
+     * Create an error result from a ToolError
+     *
+     * @param toolError - Tool error to convert
+     * @param metadata - Optional metadata
+     * @returns Error result
+     */
+    static createErrorResult(toolError, metadata) {
+        return {
+            content: toolError.toLLMMessage(),
+            errorMessage: toolError.message,
+            errorType: toolError.type,
+            metadata: {
+                ...metadata,
+                context: toolError.context,
+                originalError: toolError.originalError?.message,
+            },
+            success: false,
+        };
+    }
+    /**
+     * Create a success result
+     *
+     * Note: Content is passed through as-is (not stringified here).
+     * ToolOutputProcessor.stringify() handles proper JSON serialization later.
+     *
+     * @param content - Tool output content
+     * @param metadata - Optional metadata
+     * @returns Success result
+     */
+    static createSuccess(content, metadata) {
+        return {
+            content,
+            metadata,
+            success: true,
+        };
+    }
+    /**
+     * Format error for LLM with specific guidance based on error type
+     *
+     * @param toolError - Tool error to format
+     * @returns Formatted error message for LLM
+     */
+    static formatForLLM(toolError) {
+        const baseMessage = toolError.toLLMMessage();
+        // Add specific guidance based on error type
+        const guidance = this.getGuidanceForErrorType(toolError.type);
+        if (guidance) {
+            return `${baseMessage}\n\nGuidance: ${guidance}`;
+        }
+        return baseMessage;
+    }
+    /**
+     * Check if an error is retryable
+     *
+     * @param toolError - Tool error to check
+     * @returns True if the error might succeed on retry
+     */
+    static isRetryable(toolError) {
+        // Some error types should not be retried
+        const nonRetryableTypes = new Set([
+            ToolErrorType.CANCELLED,
+            ToolErrorType.CONFIRMATION_REJECTED,
+            ToolErrorType.EXECUTION_FAILED,
+            ToolErrorType.INVALID_PARAM_TYPE,
+            ToolErrorType.INVALID_PARAMS,
+            ToolErrorType.MISSING_REQUIRED_PARAM,
+            ToolErrorType.PARAM_VALIDATION_FAILED,
+            ToolErrorType.PERMISSION_DENIED,
+            ToolErrorType.TOOL_DISABLED,
+            ToolErrorType.TOOL_NOT_FOUND,
+        ]);
+        return !nonRetryableTypes.has(toolError.type);
+    }
+    /**
+     * Get actionable guidance for an error type
+     *
+     * @param errorType - Type of error
+     * @returns Guidance message or null
+     */
+    static getGuidanceForErrorType(errorType) {
+        switch (errorType) {
+            case ToolErrorType.EXECUTION_FAILED: {
+                return 'The tool encountered an error during execution. Review the error message and adjust your approach.';
+            }
+            case ToolErrorType.INVALID_PARAM_TYPE:
+            case ToolErrorType.INVALID_PARAMS:
+            case ToolErrorType.MISSING_REQUIRED_PARAM: {
+                return 'Check the tool schema and ensure all required parameters are provided with correct types.';
+            }
+            case ToolErrorType.PERMISSION_DENIED: {
+                return 'You do not have permission to execute this tool. Consider asking the user for permission.';
+            }
+            case ToolErrorType.TIMEOUT: {
+                return 'The tool execution timed out. Try breaking the task into smaller steps or use a different approach.';
+            }
+            case ToolErrorType.TOOL_NOT_FOUND: {
+                return 'The tool you requested does not exist. Use list_tools to see available tools.';
+            }
+            default: {
+                return null;
+            }
+        }
+    }
+}

package/dist/core/domain/cipher/tools/types.d.ts

@@ -0,0 +1,145 @@
+import type { ZodSchema } from 'zod';
+/**
+ * Risk level for tool execution.
+ * Used for logging, auditing, and policy decisions.
+ */
+export type RiskLevel = 'critical' | 'high' | 'low' | 'medium';
+/**
+ * Semantic category for tools.
+ * Helps classify tools by their primary function.
+ */
+export type ToolCategory = 'discovery' | 'execute' | 'memory' | 'read' | 'write';
+/**
+ * Metadata about a tool execution.
+ * Computed dynamically based on tool arguments.
+ */
+export interface ToolMetadata {
+    /**
+     * Files or directories that may be affected.
+     * Computed from tool arguments.
+     */
+    affectedLocations?: string[];
+    /**
+     * Semantic category of this tool.
+     */
+    category?: ToolCategory;
+    /**
+     * Risk level for this execution.
+     * Useful for logging and auditing.
+     */
+    riskLevel: RiskLevel;
+}
+/**
+ * Represents a tool that can be executed by the LLM.
+ * Tools are the primary way for the LLM to interact with the system.
+ */
+export interface Tool {
+    /** Human-readable description of what the tool does */
+    description: string;
+    /**
+     * The actual function that executes the tool.
+     * Input is pre-validated against inputSchema before execution.
+     *
+     * @param input - Validated input parameters
+     * @param context - Optional execution context
+     * @returns Tool execution result
+     */
+    execute: (input: unknown, context?: ToolExecutionContext) => Promise<unknown> | unknown;
+    /**
+     * Optional: Get metadata about this tool execution.
+     * Used for logging, auditing, and policy decisions.
+     *
+     * @param args - The arguments being passed to the tool
+     * @returns Metadata about this execution
+     */
+    getMetadata?: (args: Record<string, unknown>) => ToolMetadata;
+    /** Unique identifier for the tool */
+    id: string;
+    /** Zod schema defining the input parameters - validated before execution */
+    inputSchema: ZodSchema;
+}
+/**
+ * Context provided to tools during execution.
+ * Contains metadata about the execution environment.
+ */
+export interface ToolExecutionContext {
+    /** Session ID if available */
+    sessionId?: string;
+}
+/**
+ * Tool set exposed to the LLM.
+ * Maps tool names to their JSON Schema definitions for LLM consumption.
+ */
+export interface ToolSet {
+    [toolName: string]: {
+        /** Human-readable description */
+        description?: string;
+        /** Tool name (same as key) */
+        name?: string;
+        /** JSON Schema v7 definition of parameters */
+        parameters: JSONSchema7;
+    };
+}
+/**
+ * JSON Schema v7 type definition.
+ * Simplified version for tool parameter schemas.
+ */
+export interface JSONSchema7 {
+    $id?: string;
+    $ref?: string;
+    $schema?: string;
+    additionalItems?: boolean | JSONSchema7;
+    additionalProperties?: boolean | JSONSchema7;
+    allOf?: JSONSchema7[];
+    anyOf?: JSONSchema7[];
+    const?: unknown;
+    contains?: JSONSchema7;
+    contentEncoding?: string;
+    contentMediaType?: string;
+    default?: unknown;
+    definitions?: {
+        [key: string]: JSONSchema7;
+    };
+    dependencies?: {
+        [key: string]: JSONSchema7 | string[];
+    };
+    description?: string;
+    else?: JSONSchema7;
+    enum?: unknown[];
+    examples?: unknown[];
+    exclusiveMaximum?: number;
+    exclusiveMinimum?: number;
+    format?: string;
+    if?: JSONSchema7;
+    items?: JSONSchema7 | JSONSchema7[];
+    maximum?: number;
+    maxItems?: number;
+    maxLength?: number;
+    maxProperties?: number;
+    minimum?: number;
+    minItems?: number;
+    minLength?: number;
+    minProperties?: number;
+    multipleOf?: number;
+    not?: JSONSchema7;
+    oneOf?: JSONSchema7[];
+    pattern?: string;
+    patternProperties?: {
+        [key: string]: JSONSchema7;
+    };
+    properties?: {
+        [key: string]: JSONSchema7;
+    };
+    propertyNames?: JSONSchema7;
+    readOnly?: boolean;
+    required?: string[];
+    then?: JSONSchema7;
+    title?: string;
+    type?: JSONSchema7TypeName | JSONSchema7TypeName[];
+    uniqueItems?: boolean;
+    writeOnly?: boolean;
+}
+/**
+ * JSON Schema type names.
+ */
+export type JSONSchema7TypeName = 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string';