byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/tools/implementations/kill-process-tool.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for kill_process tool.
+ */
+const KillProcessInputSchema = z
+    .object({
+    /**
+     * Unique process identifier from bash_exec.
+     */
+    processId: z.string().describe('Unique process identifier from bash_exec'),
+})
+    .strict();
+/**
+ * Create kill_process tool.
+ *
+ * Terminates a background process started by bash_exec.
+ * Uses graceful shutdown (SIGTERM) with escalation to SIGKILL after 5 seconds.
+ *
+ * @param processService - Process service for killing processes
+ * @returns kill_process tool instance
+ */
+export function createKillProcessTool(processService) {
+    return {
+        description: `Terminate a background process started by bash_exec.
+
+Features:
+- Graceful shutdown: Sends SIGTERM first to allow cleanup
+- Force kill: Escalates to SIGKILL after 5 seconds if still running
+- Idempotent: Safe to call on already-terminated processes
+
+Signal handling:
+1. Sends SIGTERM (allows process to cleanup gracefully)
+2. Waits 5 seconds
+3. Sends SIGKILL if process still running (force terminate)
+
+Use cases:
+- Stop long-running commands that are no longer needed
+- Cancel background processes that are taking too long
+- Clean up processes before starting new ones`,
+        async execute(input, _context) {
+            const { processId } = input;
+            // Kill process via process service
+            await processService.killProcess(processId);
+            // Return success confirmation
+            return {
+                message: `Process ${processId} terminated successfully`,
+                processId,
+                success: true,
+            };
+        },
+        id: ToolName.KILL_PROCESS,
+        inputSchema: KillProcessInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/list-memories-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { MemoryManager } from '../../memory/memory-manager.js';
+/**
+ * Creates the list memories tool.
+ *
+ * Lists and filters memories stored in the scratch pad. Supports filtering by
+ * tags, pinned status, and source. Results are sorted by most recently updated first.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured list memories tool
+ */
+export declare function createListMemoriesTool(memoryManager: MemoryManager): Tool;

package/dist/infra/cipher/tools/implementations/list-memories-tool.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for list memories tool.
+ */
+const ListMemoriesInputSchema = z
+    .object({
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum number of memories to return'),
+    offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Number of memories to skip (for pagination)'),
+    pinned: z.boolean().optional().describe('Filter by pinned status'),
+    source: z
+        .enum(['agent', 'system', 'user'])
+        .optional()
+        .describe('Filter by source (default: agent)'),
+})
+    .strict();
+/**
+ * Creates the list memories tool.
+ *
+ * Lists and filters memories stored in the scratch pad. Supports filtering by
+ * tags, pinned status, and source. Results are sorted by most recently updated first.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured list memories tool
+ */
+export function createListMemoriesTool(memoryManager) {
+    return {
+        description: 'List and filter memories from the scratch pad. Returns memories sorted by most recent first. Use this to discover what context has been stored.',
+        async execute(input, _context) {
+            const { limit, offset, pinned, source } = input;
+            // List memories with filters
+            const memories = await memoryManager.list({
+                limit,
+                offset,
+                pinned,
+                source,
+            });
+            // Return formatted result with preview
+            return {
+                count: memories.length,
+                memories: memories.map(m => ({
+                    contentPreview: m.content.length > 200 ? `${m.content.slice(0, 200)}...` : m.content,
+                    createdAt: new Date(m.createdAt).toISOString(),
+                    id: m.id,
+                    pinned: m.metadata?.pinned ?? false,
+                    updatedAt: new Date(m.updatedAt).toISOString(),
+                })),
+            };
+        },
+        id: ToolName.LIST_MEMORIES,
+        inputSchema: ListMemoriesInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/read-file-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../../core/interfaces/cipher/i-file-system.js';
+/**
+ * Creates the read file tool.
+ *
+ * Reads the contents of a file with optional pagination support.
+ * Supports offset (starting line) and limit (max lines) for large files.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured read file tool
+ */
+export declare function createReadFileTool(fileSystemService: IFileSystem): Tool;

package/dist/infra/cipher/tools/implementations/read-file-tool.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for read file tool.
+ */
+const ReadFileInputSchema = z
+    .object({
+    filePath: z.string().describe('Absolute path to the file to read'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum number of lines to read (optional)'),
+    offset: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Starting line number (1-based, optional)'),
+})
+    .strict();
+/**
+ * Creates the read file tool.
+ *
+ * Reads the contents of a file with optional pagination support.
+ * Supports offset (starting line) and limit (max lines) for large files.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured read file tool
+ */
+export function createReadFileTool(fileSystemService) {
+    return {
+        description: 'Read the contents of a file. Supports pagination with offset (1-based line number) and limit (max lines).',
+        async execute(input, _context) {
+            const { filePath, limit, offset } = input;
+            // Call file system service
+            const result = await fileSystemService.readFile(filePath, {
+                limit,
+                offset,
+            });
+            // Return formatted result
+            return {
+                content: result.content,
+                encoding: result.encoding,
+                lines: result.lines,
+                size: result.size,
+                truncated: result.truncated,
+            };
+        },
+        id: ToolName.READ_FILE,
+        inputSchema: ReadFileInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/read-memory-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { MemoryManager } from '../../memory/memory-manager.js';
+/**
+ * Read memory tool.
+ *
+ * Retrieves a specific memory by its ID. Use this to recall previously stored
+ * context, intermediate results, or findings from the scratch pad.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured read memory tool
+ */
+export declare function createReadMemoryTool(memoryManager: MemoryManager): Tool;

package/dist/infra/cipher/tools/implementations/read-memory-tool.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for read memory tool.
+ */
+const ReadMemoryInputSchema = z
+    .object({
+    id: z.string().min(1).describe('Unique identifier of the memory to retrieve'),
+})
+    .strict();
+/**
+ * Read memory tool.
+ *
+ * Retrieves a specific memory by its ID. Use this to recall previously stored
+ * context, intermediate results, or findings from the scratch pad.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured read memory tool
+ */
+export function createReadMemoryTool(memoryManager) {
+    return {
+        description: 'Read a specific memory by ID. Use this to retrieve previously stored context, findings, or intermediate results from the scratch pad.',
+        async execute(input, _context) {
+            const { id } = input;
+            // Retrieve memory
+            const memory = await memoryManager.get(id);
+            // Return formatted result
+            return {
+                content: memory.content,
+                createdAt: new Date(memory.createdAt).toISOString(),
+                id: memory.id,
+                metadata: memory.metadata,
+                updatedAt: new Date(memory.updatedAt).toISOString(),
+            };
+        },
+        id: ToolName.READ_MEMORY,
+        inputSchema: ReadMemoryInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/search-history-tool.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+/**
+ * Creates the search history tool.
+ *
+ * NOTE: This is a stub implementation. SearchService is not yet implemented.
+ * This tool will throw an error until the SearchService is available.
+ *
+ * @returns Configured search history tool (stub)
+ */
+export declare function createSearchHistoryTool(): Tool;

package/dist/infra/cipher/tools/implementations/search-history-tool.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for search history tool.
+ */
+const SearchHistoryInputSchema = z
+    .object({
+    limit: z.number().optional().default(20).describe('Maximum number of results to return (default: 20)'),
+    mode: z
+        .enum(['messages', 'sessions'])
+        .describe('Search mode: "messages" searches for individual messages, "sessions" finds sessions containing the query'),
+    offset: z.number().optional().default(0).describe('Offset for pagination (default: 0)'),
+    query: z.string().describe('The search query to find in conversation history'),
+    role: z.enum(['user', 'assistant', 'system', 'tool']).optional().describe('Filter by message role (optional)'),
+    sessionId: z.string().optional().describe('Limit search to a specific session (optional)'),
+})
+    .strict();
+/**
+ * Creates the search history tool.
+ *
+ * NOTE: This is a stub implementation. SearchService is not yet implemented.
+ * This tool will throw an error until the SearchService is available.
+ *
+ * @returns Configured search history tool (stub)
+ */
+export function createSearchHistoryTool() {
+    return {
+        description: 'Search conversation history. Supports searching messages or sessions. Can filter by role and session.',
+        async execute(_input, _context) {
+            // Stub implementation - SearchService not yet available
+            throw new Error('Search history tool is not yet implemented. This feature requires the SearchService which is not currently available.');
+        },
+        id: ToolName.SEARCH_HISTORY,
+        inputSchema: SearchHistoryInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/write-file-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../../core/interfaces/cipher/i-file-system.js';
+/**
+ * Creates the write file tool.
+ *
+ * Writes content to a file, overwriting if it exists.
+ * Can optionally create parent directories.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured write file tool
+ */
+export declare function createWriteFileTool(fileSystemService: IFileSystem): Tool;

package/dist/infra/cipher/tools/implementations/write-file-tool.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+import { sanitizeFolderName } from '../../../../utils/file-helpers.js';
+/**
+ * Input schema for write file tool.
+ */
+const WriteFileInputSchema = z
+    .object({
+    content: z.string().describe('Content to write to the file'),
+    createDirs: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Create parent directories if they don't exist (default: false)"),
+    encoding: z
+        .enum(['utf8', 'ascii', 'latin1', 'utf16le', 'base64', 'hex'])
+        .optional()
+        .default('utf8')
+        .describe('File encoding (default: utf8)'),
+    filePath: z.string().describe('Absolute path where the file should be written'),
+})
+    .strict();
+/**
+ * Creates the write file tool.
+ *
+ * Writes content to a file, overwriting if it exists.
+ * Can optionally create parent directories.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured write file tool
+ */
+export function createWriteFileTool(fileSystemService) {
+    return {
+        description: 'Write content to a file. Overwrites existing files. Can optionally create parent directories.',
+        async execute(input, _context) {
+            const { content, createDirs, encoding, filePath } = input;
+            // Call file system service
+            const result = await fileSystemService.writeFile(sanitizeFolderName(filePath), content, {
+                createDirs,
+                encoding: encoding,
+            });
+            // Return formatted result
+            return {
+                bytesWritten: result.bytesWritten,
+                path: result.path,
+                success: result.success,
+            };
+        },
+        id: ToolName.WRITE_FILE,
+        inputSchema: WriteFileInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/write-memory-tool.d.ts

@@ -0,0 +1,13 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { MemoryManager } from '../../memory/memory-manager.js';
+/**
+ * Creates the write memory tool.
+ *
+ * Stores content in the agent's memory as a scratch pad for maintaining context
+ * across tool invocations. Memories persist across sessions and can be tagged
+ * for organization.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured write memory tool
+ */
+export declare function createWriteMemoryTool(memoryManager: MemoryManager): Tool;

package/dist/infra/cipher/tools/implementations/write-memory-tool.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for write memory tool.
+ */
+const WriteMemoryInputSchema = z
+    .object({
+    content: z
+        .string()
+        .min(1, 'Memory content cannot be empty')
+        .max(10_000, 'Memory content cannot exceed 10,000 characters')
+        .describe('The content to store in memory'),
+    pinned: z
+        .boolean()
+        .optional()
+        .describe('Whether to pin this memory for auto-loading (default: false)'),
+})
+    .strict();
+/**
+ * Creates the write memory tool.
+ *
+ * Stores content in the agent's memory as a scratch pad for maintaining context
+ * across tool invocations. Memories persist across sessions and can be tagged
+ * for organization.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured write memory tool
+ */
+export function createWriteMemoryTool(memoryManager) {
+    return {
+        description: 'Write content to agent memory as a scratch pad. Use this to store intermediate results, findings, or context that should persist across tool calls. Memories can be tagged and pinned for easy retrieval.',
+        async execute(input, _context) {
+            const { content, pinned } = input;
+            // Create memory with agent source
+            const memory = await memoryManager.create({
+                content,
+                metadata: {
+                    pinned: pinned ?? false,
+                    source: 'agent',
+                },
+            });
+            // Return formatted result
+            return {
+                content: memory.content,
+                createdAt: new Date(memory.createdAt).toISOString(),
+                id: memory.id,
+            };
+        },
+        id: ToolName.WRITE_MEMORY,
+        inputSchema: WriteMemoryInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/write-todos-tool.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+/**
+ * Creates the write todos tool.
+ *
+ * Manages a structured task list for planning-based execution.
+ * Validates that only one task is in_progress at any time.
+ *
+ * @returns Configured write todos tool
+ */
+export declare function createWriteTodosTool(): Tool;

package/dist/infra/cipher/tools/implementations/write-todos-tool.js

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { TODO_STATUSES } from '../../../../core/domain/cipher/todos/types.js';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Schema for a single todo item.
+ */
+const TodoSchema = z.object({
+    activeForm: z
+        .string()
+        .min(1)
+        .describe('Present continuous form shown during execution (e.g., "Running tests")'),
+    content: z.string().min(1).describe('Imperative description of the task (e.g., "Run tests")'),
+    status: z
+        .enum(TODO_STATUSES)
+        .describe('Task status: pending, in_progress (only ONE at a time), completed, or cancelled'),
+});
+/**
+ * Input schema for write todos tool.
+ */
+const WriteTodosInputSchema = z
+    .object({
+    todos: z.array(TodoSchema).min(1).describe('List of todo items to track'),
+})
+    .strict();
+/**
+ * Tool description with detailed usage guidance.
+ * This helps the LLM understand when to use the tool and how.
+ */
+const TOOL_DESCRIPTION = `Use this tool to create and manage a structured task list for the current session. This helps track progress, organize complex tasks, and demonstrate thoroughness to the user.
+
+## When to Use This Tool
+Use this tool proactively in these scenarios:
+
+1. **Complex multi-step tasks** - When a task requires 3 or more distinct steps
+2. **Non-trivial and complex tasks** - Tasks that require careful planning or multiple operations
+3. **User explicitly requests todo list** - When the user directly asks to use the todo list
+4. **User provides multiple tasks** - When users provide a list of things to be done
+5. **After receiving new instructions** - Immediately capture user requirements as todos
+6. **When you start working on a task** - Mark it as in_progress BEFORE beginning work
+7. **After completing a task** - Mark it as completed and add any follow-up tasks
+
+## When NOT to Use This Tool
+Skip using this tool when:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking provides no organizational benefit
+3. The task can be completed in less than 3 trivial steps
+4. The task is purely conversational or informational
+
+## Task States
+- **pending**: Task not yet started
+- **in_progress**: Currently working on (limit to ONE task at a time)
+- **completed**: Task finished successfully
+- **cancelled**: Task no longer needed
+
+## Important Rules
+- ONLY ONE task can be "in_progress" at any time
+- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+- Task descriptions need both forms:
+  - content: Imperative form (e.g., "Run tests")
+  - activeForm: Present continuous form (e.g., "Running tests")`;
+/**
+ * Validates that only one todo is in_progress.
+ *
+ * @param todos - Array of todos to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validateSingleInProgress(todos) {
+    const inProgressCount = todos.filter((todo) => todo.status === 'in_progress').length;
+    if (inProgressCount > 1) {
+        return `Invalid parameters: Only one task can be "in_progress" at a time. Found ${inProgressCount} tasks in progress.`;
+    }
+    return null;
+}
+/**
+ * Formats the todo list for LLM response.
+ *
+ * @param todos - Array of todos
+ * @returns Formatted string representation
+ */
+function formatTodosForLLM(todos) {
+    const lines = ['Todo list updated:'];
+    for (const todo of todos) {
+        const statusIcon = getStatusIcon(todo.status);
+        lines.push(`${statusIcon} [${todo.status}] ${todo.content}`);
+    }
+    const stats = getTodoStats(todos);
+    const progressLines = [
+        '',
+        `Progress: ${stats.completed}/${stats.total} completed`,
+    ];
+    if (stats.inProgress > 0) {
+        const currentTask = todos.find((t) => t.status === 'in_progress');
+        if (currentTask) {
+            progressLines.push(`Currently: ${currentTask.activeForm}`);
+        }
+    }
+    return [...lines, ...progressLines].join('\n');
+}
+/**
+ * Gets icon for todo status.
+ *
+ * @param status - Todo status
+ * @returns Status icon
+ */
+function getStatusIcon(status) {
+    switch (status) {
+        case 'cancelled': {
+            return '⊘';
+        }
+        case 'completed': {
+            return '✓';
+        }
+        case 'in_progress': {
+            return '→';
+        }
+        case 'pending': {
+            return '○';
+        }
+    }
+}
+/**
+ * Gets statistics about the todo list.
+ *
+ * @param todos - Array of todos
+ * @returns Statistics object
+ */
+function getTodoStats(todos) {
+    return {
+        cancelled: todos.filter((t) => t.status === 'cancelled').length,
+        completed: todos.filter((t) => t.status === 'completed').length,
+        inProgress: todos.filter((t) => t.status === 'in_progress').length,
+        pending: todos.filter((t) => t.status === 'pending').length,
+        total: todos.length,
+    };
+}
+/**
+ * Creates the write todos tool.
+ *
+ * Manages a structured task list for planning-based execution.
+ * Validates that only one task is in_progress at any time.
+ *
+ * @returns Configured write todos tool
+ */
+export function createWriteTodosTool() {
+    return {
+        description: TOOL_DESCRIPTION,
+        async execute(input, _context) {
+            const { todos } = input;
+            // Validate only one in_progress
+            const validationError = validateSingleInProgress(todos);
+            if (validationError) {
+                return validationError;
+            }
+            // Format response for LLM
+            const llmContent = formatTodosForLLM(todos);
+            // Return both LLM content and display content
+            return {
+                llmContent,
+                returnDisplay: { todos },
+            };
+        },
+        id: ToolName.WRITE_TODOS,
+        inputSchema: WriteTodosInputSchema,
+    };
+}

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

@@ -0,0 +1,18 @@
+export { ToolError, ToolExecutionError, ToolNotFoundError, ToolProviderNotInitializedError, ToolValidationError, } from '../../../core/domain/cipher/errors/tool-error.js';
+export { ToolName } from '../../../core/domain/cipher/tools/constants.js';
+export type { KnownTool } from '../../../core/domain/cipher/tools/constants.js';
+export type { JSONSchema7, Tool, ToolExecutionContext, ToolSet } from '../../../core/domain/cipher/tools/types.js';
+export type { IToolProvider } from '../../../core/interfaces/cipher/i-tool-provider.js';
+export { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-tool.js';
+export { createDetectDomainsTool } from './implementations/detect-domains-tool.js';
+export { createEditFileTool } from './implementations/edit-file-tool.js';
+export { createGlobFilesTool } from './implementations/glob-files-tool.js';
+export { createGrepContentTool } from './implementations/grep-content-tool.js';
+export { createReadFileTool } from './implementations/read-file-tool.js';
+export { createSearchHistoryTool } from './implementations/search-history-tool.js';
+export { createWriteFileTool } from './implementations/write-file-tool.js';
+export { ToolManager } from './tool-manager.js';
+export { ToolProvider } from './tool-provider.js';
+export type { ToolFactory, ToolRegistryEntry, ToolServices } from './tool-registry.js';
+export { TOOL_REGISTRY } from './tool-registry.js';
+export { convertZodToJsonSchema } from './utils/schema-converter.js';

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

@@ -0,0 +1,19 @@
+// Errors
+export { ToolError, ToolExecutionError, ToolNotFoundError, ToolProviderNotInitializedError, ToolValidationError, } from '../../../core/domain/cipher/errors/tool-error.js';
+// Constants
+export { ToolName } from '../../../core/domain/cipher/tools/constants.js';
+// Tool implementations (for direct access if needed)
+export { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-tool.js';
+export { createDetectDomainsTool } from './implementations/detect-domains-tool.js';
+export { createEditFileTool } from './implementations/edit-file-tool.js';
+export { createGlobFilesTool } from './implementations/glob-files-tool.js';
+export { createGrepContentTool } from './implementations/grep-content-tool.js';
+export { createReadFileTool } from './implementations/read-file-tool.js';
+export { createSearchHistoryTool } from './implementations/search-history-tool.js';
+export { createWriteFileTool } from './implementations/write-file-tool.js';
+// Registry and provider
+export { ToolManager } from './tool-manager.js';
+export { ToolProvider } from './tool-provider.js';
+export { TOOL_REGISTRY } from './tool-registry.js';
+// Utilities
+export { convertZodToJsonSchema } from './utils/schema-converter.js';