byterover-cli 1.6.0 → 1.7.0

package/dist/agent/infra/tools/implementations/bash-exec-tool.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * Input schema for bash_exec tool.
+ */
+const BashExecInputSchema = z
+    .object({
+    /**
+     * Shell command to execute.
+     */
+    command: z.string().describe('Shell command to execute'),
+    /**
+     * Working directory for command execution (relative to configured base directory).
+     */
+    cwd: z.string().optional().describe('Working directory for command execution'),
+    /**
+     * Human-readable description of what the command does (5-10 words).
+     */
+    description: z.string().optional().describe('Description of what the command does (5-10 words)'),
+    /**
+     * Execute command in background (returns immediately with process handle).
+     */
+    runInBackground: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Execute command in background'),
+    /**
+     * Timeout in milliseconds (max: 600000, default: 300000 = 5 minutes).
+     */
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .max(600_000)
+        .optional()
+        .default(300_000)
+        .describe('Timeout in milliseconds (default: 5 minutes)'),
+})
+    .strict();
+/**
+ * Create bash_exec tool.
+ *
+ * Executes shell commands with security validation and approval for dangerous commands.
+ * Supports both foreground (wait for completion) and background (return immediately) execution.
+ * When a metadata callback is provided, streams output updates in real-time.
+ *
+ * @param processService - Process service for command execution
+ * @returns bash_exec tool instance
+ */
+export function createBashExecTool(processService) {
+    return {
+        description: `Execute a shell command and return its output.`,
+        async execute(input, context) {
+            const { command, cwd, description, runInBackground, timeout } = input;
+            // Stream initial status via metadata callback if available
+            if (context?.metadata) {
+                context.metadata({
+                    description: description ?? `Executing: ${command.slice(0, 50)}${command.length > 50 ? '...' : ''}`,
+                    output: '',
+                    progress: 0,
+                });
+            }
+            // Execute command via process service
+            const result = await processService.executeCommand(command, {
+                cwd,
+                description,
+                runInBackground,
+                timeout,
+            });
+            // Return based on execution mode
+            if ('stdout' in result) {
+                // Stream final output via metadata callback if available
+                if (context?.metadata) {
+                    context.metadata({
+                        description: description ?? 'Command completed',
+                        output: result.stdout + (result.stderr ? `\n[stderr]\n${result.stderr}` : ''),
+                        progress: 100,
+                    });
+                }
+                // Foreground execution result
+                return {
+                    duration: result.duration,
+                    exitCode: result.exitCode,
+                    stderr: result.stderr,
+                    stdout: result.stdout,
+                };
+            }
+            // Stream background process info via metadata callback if available
+            if (context?.metadata) {
+                context.metadata({
+                    description: `Background process started: ${result.processId}`,
+                    output: `Process started with PID ${result.pid}`,
+                    progress: 100,
+                });
+            }
+            // Background execution handle
+            return {
+                command: result.command,
+                description: result.description,
+                message: `Process started in background. Use bash_output with processId="${result.processId}" to retrieve output.`,
+                pid: result.pid,
+                processId: result.processId,
+                startedAt: result.startedAt.toISOString(),
+            };
+        },
+        id: ToolName.BASH_EXEC,
+        inputSchema: BashExecInputSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/bash-output-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { IProcessService } from '../../../core/interfaces/i-process-service.js';
+/**
+ * Create bash_output tool.
+ *
+ * Retrieves output from a background process started by bash_exec.
+ * Reading output clears the buffer (destructive read), so output is only returned once.
+ *
+ * @param processService - Process service for retrieving output
+ * @returns bash_output tool instance
+ */
+export declare function createBashOutputTool(processService: IProcessService): Tool;

package/dist/agent/infra/tools/implementations/bash-output-tool.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * Input schema for bash_output tool.
+ */
+const BashOutputInputSchema = z
+    .object({
+    /**
+     * Unique process identifier from bash_exec.
+     */
+    processId: z.string().describe('Unique process identifier from bash_exec'),
+})
+    .strict();
+/**
+ * Create bash_output tool.
+ *
+ * Retrieves output from a background process started by bash_exec.
+ * Reading output clears the buffer (destructive read), so output is only returned once.
+ *
+ * @param processService - Process service for retrieving output
+ * @returns bash_output tool instance
+ */
+export function createBashOutputTool(processService) {
+    return {
+        description: `Retrieve output from a background process started by bash_exec.`,
+        async execute(input, _context) {
+            const { processId } = input;
+            // Get output from process service
+            const output = await processService.getProcessOutput(processId);
+            // Return output with status
+            return {
+                duration: output.duration,
+                exitCode: output.exitCode,
+                processId,
+                status: output.status,
+                stderr: output.stderr,
+                stdout: output.stdout,
+            };
+        },
+        id: ToolName.BASH_OUTPUT,
+        inputSchema: BashOutputInputSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/batch-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { ToolProviderGetter } from '../tool-provider-getter.js';
+/**
+ * Create batch tool.
+ *
+ * Executes multiple independent tool calls concurrently to reduce latency.
+ * Best used for gathering context (reads, searches, listings).
+ *
+ * @param getToolProvider - Lazy getter for tool provider (avoids circular dependency)
+ * @returns batch tool instance
+ */
+export declare function createBatchTool(getToolProvider: ToolProviderGetter): Tool;

package/dist/agent/infra/tools/implementations/batch-tool.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * Tools that are not allowed in batch execution.
+ * - batch: No nesting of batch calls
+ * - edit_file: Sequential edits for proper conflict handling
+ * - write_todos: Lightweight, call directly
+ */
+const DISALLOWED_TOOLS = new Set(['batch', 'edit_file', 'write_todos']);
+/**
+ * Maximum number of tool calls allowed in a single batch.
+ */
+const MAX_BATCH_SIZE = 10;
+/**
+ * Input schema for batch tool.
+ */
+const BatchInputSchema = z
+    .object({
+    /**
+     * Array of tool calls to execute in parallel.
+     */
+    toolCalls: z
+        .array(z.object({
+        /**
+         * Parameters for the tool.
+         */
+        parameters: z.record(z.unknown()).describe('Parameters for the tool'),
+        /**
+         * The name of the tool to execute.
+         */
+        tool: z.string().describe('The name of the tool to execute'),
+    }))
+        .min(1, 'Provide at least one tool call')
+        .describe('Array of tool calls to execute in parallel'),
+})
+    .strict();
+/**
+ * Create batch tool.
+ *
+ * Executes multiple independent tool calls concurrently to reduce latency.
+ * Best used for gathering context (reads, searches, listings).
+ *
+ * @param getToolProvider - Lazy getter for tool provider (avoids circular dependency)
+ * @returns batch tool instance
+ */
+export function createBatchTool(getToolProvider) {
+    return {
+        description: 'Execute multiple independent tool calls concurrently.',
+        async execute(input, context) {
+            const { toolCalls } = input;
+            const toolProvider = getToolProvider();
+            // Limit to MAX_BATCH_SIZE
+            const activeCalls = toolCalls.slice(0, MAX_BATCH_SIZE);
+            const discardedCalls = toolCalls.slice(MAX_BATCH_SIZE);
+            /**
+             * Execute a single tool call and return the result.
+             */
+            const executeCall = async (call) => {
+                const startTime = Date.now();
+                // Check if tool is disallowed in batch
+                if (DISALLOWED_TOOLS.has(call.tool)) {
+                    return {
+                        durationMs: Date.now() - startTime,
+                        error: `Tool '${call.tool}' is not allowed in batch. Disallowed tools: ${[...DISALLOWED_TOOLS].join(', ')}`,
+                        success: false,
+                        tool: call.tool,
+                    };
+                }
+                // Check if tool exists
+                if (!toolProvider.hasTool(call.tool)) {
+                    const availableTools = toolProvider.getToolNames().filter((name) => !DISALLOWED_TOOLS.has(name));
+                    return {
+                        durationMs: Date.now() - startTime,
+                        error: `Tool '${call.tool}' not found. Available tools: ${availableTools.join(', ')}`,
+                        success: false,
+                        tool: call.tool,
+                    };
+                }
+                try {
+                    const result = await toolProvider.executeTool(call.tool, call.parameters, context?.sessionId, context);
+                    return {
+                        durationMs: Date.now() - startTime,
+                        result,
+                        success: true,
+                        tool: call.tool,
+                    };
+                }
+                catch (error) {
+                    return {
+                        durationMs: Date.now() - startTime,
+                        error: error instanceof Error ? error.message : String(error),
+                        success: false,
+                        tool: call.tool,
+                    };
+                }
+            };
+            // Execute all calls in parallel
+            const results = await Promise.all(activeCalls.map((call) => executeCall(call)));
+            // Add discarded calls as errors
+            for (const call of discardedCalls) {
+                results.push({
+                    durationMs: 0,
+                    error: `Maximum of ${MAX_BATCH_SIZE} tools allowed in batch`,
+                    success: false,
+                    tool: call.tool,
+                });
+            }
+            const successful = results.filter((r) => r.success).length;
+            const failed = results.length - successful;
+            // Stream progress update
+            if (context?.metadata) {
+                context.metadata({
+                    description: 'Batch execution complete',
+                    output: `${successful}/${results.length} tools executed successfully`,
+                    progress: 100,
+                });
+            }
+            // Build output message
+            const outputMessage = failed > 0
+                ? `Executed ${successful}/${results.length} tools successfully. ${failed} failed.`
+                : `All ${successful} tools executed successfully.\n\nKeep using the batch tool for optimal performance!`;
+            return {
+                metadata: {
+                    details: results.map((r) => ({ success: r.success, tool: r.tool })),
+                    failed,
+                    successful,
+                    tools: toolCalls.map((c) => c.tool),
+                    totalCalls: results.length,
+                },
+                results: results.map((r) => ({
+                    durationMs: r.durationMs,
+                    success: r.success,
+                    tool: r.tool,
+                    ...(r.success ? { result: r.result } : { error: r.error }),
+                })),
+                summary: outputMessage,
+            };
+        },
+        id: ToolName.BATCH,
+        inputSchema: BatchInputSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/code-exec-tool.d.ts

@@ -0,0 +1,16 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { ISandboxService } from '../../../core/interfaces/i-sandbox-service.js';
+/**
+ * Create code_exec tool.
+ *
+ * Executes JavaScript/TypeScript code in a sandboxed REPL environment.
+ * Features:
+ * - Auto-detects and transpiles TypeScript
+ * - State persists within the same agent session
+ * - Pre-loaded utility packages (lodash, date-fns, zod, etc.)
+ * - Security: blocks eval, Function, require, process, etc.
+ *
+ * @param sandboxService - Sandbox service for code execution
+ * @returns code_exec tool instance
+ */
+export declare function createCodeExecTool(sandboxService: ISandboxService): Tool;

package/dist/agent/infra/tools/implementations/code-exec-tool.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { DEFAULT_SANDBOX_TIMEOUT, MAX_SANDBOX_TIMEOUT } from '../../../core/domain/sandbox/constants.js';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * Input schema for code_exec tool.
+ */
+const CodeExecInputSchema = z
+    .object({
+    /**
+     * JavaScript or TypeScript code to execute.
+     */
+    code: z.string().describe('JavaScript or TypeScript code to execute'),
+    /**
+     * Context data available as "context" variable in the sandbox.
+     */
+    context: z
+        .union([z.string(), z.record(z.unknown()), z.array(z.unknown())])
+        .optional()
+        .describe('Context data available as "context" variable'),
+    /**
+     * Language: "javascript" or "typescript" (default: auto-detect).
+     */
+    language: z
+        .enum(['javascript', 'typescript'])
+        .optional()
+        .describe('Language: "javascript" or "typescript" (default: auto-detect)'),
+    /**
+     * Timeout in milliseconds (max: 300000, default: 30000 = 30 seconds).
+     */
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_SANDBOX_TIMEOUT)
+        .optional()
+        .default(DEFAULT_SANDBOX_TIMEOUT)
+        .describe('Timeout in milliseconds (default: 30 seconds, max: 5 minutes)'),
+})
+    .strict();
+/**
+ * Create code_exec tool.
+ *
+ * Executes JavaScript/TypeScript code in a sandboxed REPL environment.
+ * Features:
+ * - Auto-detects and transpiles TypeScript
+ * - State persists within the same agent session
+ * - Pre-loaded utility packages (lodash, date-fns, zod, etc.)
+ * - Security: blocks eval, Function, require, process, etc.
+ *
+ * @param sandboxService - Sandbox service for code execution
+ * @returns code_exec tool instance
+ */
+export function createCodeExecTool(sandboxService) {
+    return {
+        description: 'Execute JavaScript or TypeScript code in a sandboxed REPL environment.',
+        async execute(input, context) {
+            const { code, context: contextPayload, language, timeout } = input;
+            // Get sessionId from execution context (automatic - no user input needed)
+            const sessionId = context?.sessionId ?? 'default';
+            // Stream initial status via metadata callback if available
+            if (context?.metadata) {
+                context.metadata({
+                    description: 'Executing code...',
+                    output: '',
+                    progress: 0,
+                });
+            }
+            const result = await sandboxService.executeCode(code, sessionId, {
+                contextPayload,
+                language,
+                timeout,
+            });
+            // Stream completion via metadata callback if available
+            if (context?.metadata) {
+                context.metadata({
+                    description: result.stderr ? 'Execution completed with errors' : 'Execution completed',
+                    output: result.stdout + (result.stderr ? `\n[stderr]\n${result.stderr}` : ''),
+                    progress: 100,
+                });
+            }
+            return {
+                executionTime: result.executionTime,
+                locals: result.locals,
+                returnValue: result.returnValue,
+                stderr: result.stderr,
+                stdout: result.stdout,
+            };
+        },
+        id: ToolName.CODE_EXEC,
+        inputSchema: CodeExecInputSchema,
+    };
+}

package/dist/agent/infra/tools/implementations/create-knowledge-topic-tool.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+/**
+ * Creates the create knowledge topic tool.
+ *
+ * Creates organized knowledge topics within domain folders, where each topic and subtopic
+ * has its own folder containing a context.md file with relevant snippets. This tool should
+ * be used after detecting domains to organize the extracted knowledge into a structured hierarchy.
+ *
+ * @returns Configured create knowledge topic tool
+ */
+export declare function createCreateKnowledgeTopicTool(): Tool;

package/dist/agent/infra/tools/implementations/create-knowledge-topic-tool.js

@@ -0,0 +1,149 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { DirectoryManager } from '../../../../server/core/domain/knowledge/directory-manager.js';
+import { MarkdownWriter } from '../../../../server/core/domain/knowledge/markdown-writer.js';
+import { sanitizeFolderName } from '../../../../server/utils/file-helpers.js';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+const CreateKnowledgeTopicInputSchema = z.object({
+    // Base path for knowledge storage
+    basePath: z.string().default('.brv/context-tree'),
+    domains: z.array(z.string()).describe('Array of domain names (dynamically created based on content)'),
+    // Manual topics (optional)
+    topics: z
+        .array(z.object({
+        domain: z.string().describe('Domain category name (can be any semantically meaningful name)'),
+        name: z.string().describe('Topic name'),
+        relations: z
+            .array(z.string())
+            .optional()
+            .describe('Related topics using domain/topic or domain/topic/subtopic notation'),
+        snippets: z.array(z.string()).describe('Code/text snippets'),
+        subtopics: z
+            .array(z.object({
+            name: z.string().describe('Subtopic name'),
+            relations: z
+                .array(z.string())
+                .optional()
+                .describe('Related topics using domain/topic or domain/topic/subtopic notation'),
+            snippets: z.array(z.string()).describe('Code/text snippets'),
+        }))
+            .describe('Array of subtopics'),
+    }))
+        .describe('Array of topics for each domain'),
+});
+/**
+ * Execute function for create knowledge topic tool
+ */
+async function executeCreateKnowledgeTopic(input, _context) {
+    const { basePath, topics } = input;
+    // Ensure base knowledge structure exists
+    await DirectoryManager.ensureKnowledgeStructure(basePath);
+    const created = [];
+    const updated = [];
+    // Process each topic sequentially (domains/topics must be created in order)
+    /* eslint-disable no-await-in-loop -- Sequential processing required for domain/topic hierarchy */
+    for (const topicData of topics) {
+        const { domain, name: topicName, relations, snippets, subtopics: subtopicData } = topicData;
+        // Create or update domain folder
+        const domainPath = join(basePath, sanitizeFolderName(domain));
+        const domainResult = await DirectoryManager.createOrUpdateDomain(domainPath);
+        // Create or update topic folder
+        const topicPath = join(domainPath, sanitizeFolderName(topicName));
+        const topicResult = await DirectoryManager.createOrUpdateTopic(topicPath);
+        // Generate and write topic context.md
+        const topicContextContent = MarkdownWriter.generateContext({
+            name: topicName,
+            relations,
+            snippets,
+        });
+        const topicContextPath = join(topicPath, 'context.md');
+        await DirectoryManager.writeFileAtomic(topicContextPath, topicContextContent);
+        // Process subtopics in parallel
+        const subtopicResults = await Promise.all(subtopicData.map(async (subtopic) => {
+            // Create subtopic folder
+            const subtopicPath = join(topicPath, sanitizeFolderName(subtopic.name));
+            const subtopicResult = await DirectoryManager.createOrUpdateTopic(subtopicPath);
+            // Generate and write subtopic context.md
+            const subtopicContextContent = MarkdownWriter.generateContext({
+                name: subtopic.name,
+                relations: subtopic.relations,
+                snippets: subtopic.snippets,
+            });
+            const subtopicContextPath = join(subtopicPath, 'context.md');
+            await DirectoryManager.writeFileAtomic(subtopicContextPath, subtopicContextContent);
+            return {
+                existed: !subtopicResult.created,
+                name: subtopic.name,
+            };
+        }));
+        // Separate created vs updated subtopics
+        const createdSubtopics = subtopicResults.filter((r) => !r.existed).map((r) => r.name);
+        const updatedSubtopics = subtopicResults.filter((r) => r.existed).map((r) => r.name);
+        // Track what was created vs updated
+        if (domainResult.created || topicResult.created) {
+            created.push({
+                domain,
+                subtopics: createdSubtopics,
+                topic: topicName,
+            });
+        }
+        else {
+            updated.push({
+                domain,
+                subtopics: updatedSubtopics,
+                topic: topicName,
+            });
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    return {
+        created,
+        updated,
+    };
+}
+/**
+ * Creates the create knowledge topic tool.
+ *
+ * Creates organized knowledge topics within domain folders, where each topic and subtopic
+ * has its own folder containing a context.md file with relevant snippets. This tool should
+ * be used after detecting domains to organize the extracted knowledge into a structured hierarchy.
+ *
+ * @returns Configured create knowledge topic tool
+ */
+export function createCreateKnowledgeTopicTool() {
+    return {
+        description: `Create organized knowledge topics within dynamically-created domain folders. This tool structures knowledge by creating domain, topic, and subtopic folders, each containing a context.md file with relevant snippets and optional relations.
+
+**Dynamic Domain Creation:**
+Domains are created dynamically based on the content being organized. Choose domain names that:
+- Are semantically meaningful and descriptive (e.g., "authentication", "api_design", "data_models")
+- Use snake_case format (1-3 words)
+- Group related concepts together
+- Avoid overly generic names (e.g., "misc", "other") or overly specific names
+
+**Hierarchical Structure:**
+- Domain folders (e.g., .brv/context-tree/authentication/)
+- Topic folders (e.g., .brv/context-tree/authentication/oauth_flow/)
+- Topic context.md files (e.g., .brv/context-tree/authentication/oauth_flow/context.md)
+- Subtopic folders (e.g., .brv/context-tree/authentication/oauth_flow/token_refresh/)
+- Subtopic context.md files (e.g., .brv/context-tree/authentication/oauth_flow/token_refresh/context.md)
+
+**Each topic should include:**
+1. A clear topic name
+2. Relevant code/text snippets that demonstrate the knowledge
+3. Optional relations to other topics using domain/topic or domain/topic/subtopic notation
+4. Subtopics (optional) that break down the topic into smaller pieces
+
+**Relations** enhance knowledge discovery by linking related contexts. Example:
+- relations: ['authentication/session_management', 'api_design/endpoints/validation']
+
+**The tool automatically:**
+- Creates the base knowledge structure if it doesn't exist
+- Creates domain, topic, and subtopic folders as needed
+- Generates context.md files with snippets and relations
+- Handles existing topics gracefully (updates instead of recreating)`,
+        execute: executeCreateKnowledgeTopic,
+        id: ToolName.CREATE_KNOWLEDGE_TOPIC,
+        inputSchema: CreateKnowledgeTopicInputSchema,
+    };
+}