byterover-cli 1.5.0 → 1.7.0

package/dist/agent/infra/tools/implementations/spec-analyze-tool.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { ToolName } from '../../../core/domain/tools/constants.js';
+/**
+ * Domain category for knowledge classification.
+ * Domains are created dynamically based on content semantics.
+ */
+const DomainCategory = z
+    .string()
+    .min(1)
+    .describe('Domain category name. Create semantically meaningful domain names based on content (e.g., authentication, api_design, data_models). Use snake_case format.');
+/**
+ * Text segment schema - represents a portion of the input data related to a domain
+ */
+const TextSegmentSchema = z
+    .string()
+    .min(1)
+    .describe('A segment of text from the input data that relates to this domain category');
+/**
+ * Input schema for detect domains tool
+ */
+const DetectDomainsInputSchema = z
+    .object({
+    /** Detected domains with metadata and related text segments */
+    domains: z
+        .array(z.object({
+        category: DomainCategory.describe('Semantically meaningful domain category name (snake_case, e.g., authentication, api_design)'),
+        textSegments: z
+            .array(TextSegmentSchema)
+            .min(1)
+            .describe('Array of text segments from the input data that relate to this domain. Each segment should be a meaningful excerpt that demonstrates why this domain is relevant.'),
+    }))
+        .describe('Array of detected domains with their related text segments from the input data'),
+});
+/**
+ * Execute function for detect domains tool with typed input
+ */
+async function executeDetectDomains(input, _context) {
+    const { domains } = input;
+    return {
+        domains,
+    };
+}
+/**
+ * Creates the detect domains tool.
+ *
+ * @returns Configured detect domains tool
+ */
+export function createSpecAnalyzeTool() {
+    return {
+        description: `Use this tool to analyze input data and detect which knowledge domains are present. For each detected domain, you must also extract the specific text segments from the input data that relate to that domain.
+
+This tool should be the first tool to call when you want to understand new data, unless you already know what you are looking for.
+
+**Dynamic Domain Creation:**
+Domains are created dynamically based on the semantics of the content. Choose domain names that:
+- Are descriptive and semantically meaningful
+- Use snake_case format (1-3 words)
+- Group related concepts together
+- Examples: \`authentication\`, \`api_design\`, \`data_models\`, \`error_handling\`, \`ui_components\`, \`testing_patterns\`
+
+**For each domain you detect:**
+1. Create a semantically meaningful domain category name based on the content
+2. Extract relevant text segments from the input data that demonstrate why this domain is relevant
+3. Each text segment should be a meaningful excerpt (not just keywords) that shows the connection to the domain
+4. Only include domains that are actually present in the data
+
+**Domain Naming Guidelines:**
+- Use noun-based names that describe the category (e.g., \`authentication\` not \`how_to_authenticate\`)
+- Avoid overly generic names (e.g., \`misc\`, \`other\`, \`general\`)
+- Avoid overly specific names that only fit one topic
+- Consolidate related concepts under the same domain
+
+The text segments will be used later to create organized knowledge topics, so they should be substantial enough to provide context.`,
+        execute: executeDetectDomains,
+        id: ToolName.SPEC_ANALYZE,
+        inputSchema: DetectDomainsInputSchema,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { IFileSystem } from '../../../core/interfaces/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/agent/infra/tools/implementations/write-file-tool.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { sanitizeFolderName } from '../../../../server/utils/file-helpers.js';
+import { ToolName } from '../../../core/domain/tools/constants.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/agent/infra/tools/implementations/write-memory-tool.d.ts

@@ -0,0 +1,13 @@
+import type { Tool } from '../../../core/domain/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/agent/infra/tools/implementations/write-memory-tool.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { ToolName } from '../../../core/domain/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/agent/infra/tools/implementations/write-todos-tool.d.ts

@@ -0,0 +1,13 @@
+import type { Tool } from '../../../core/domain/tools/types.js';
+import type { ITodoStorage } from '../../../core/interfaces/i-todo-storage.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.
+ * Stores todos in session-based storage.
+ *
+ * @param todoStorage - Storage service for persisting todos
+ * @returns Configured write todos tool
+ */
+export declare function createWriteTodosTool(todoStorage: ITodoStorage): Tool;

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

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { TODO_STATUSES } from '../../../core/domain/todos/types.js';
+import { ToolName } from '../../../core/domain/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")'),
+    id: z.string().min(1).describe('Unique identifier for the todo item'),
+    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.`;
+/**
+ * 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.
+ * Uses opencode-style status icons: [✓] for completed, [ ] for others.
+ *
+ * @param todos - Array of todos
+ * @returns Formatted string representation
+ */
+function formatTodosForLLM(todos) {
+    const lines = ['Todo list updated:'];
+    for (const todo of todos) {
+        const checkbox = todo.status === 'completed' ? '[✓]' : '[ ]';
+        const statusLabel = todo.status === 'in_progress' ? ' (in_progress)' : '';
+        lines.push(`${checkbox} ${todo.content}${statusLabel}`);
+    }
+    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 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.
+ * Stores todos in session-based storage.
+ *
+ * @param todoStorage - Storage service for persisting todos
+ * @returns Configured write todos tool
+ */
+export function createWriteTodosTool(todoStorage) {
+    return {
+        description: TOOL_DESCRIPTION,
+        async execute(input, context) {
+            const { todos } = input;
+            // Validate only one in_progress
+            const validationError = validateSingleInProgress(todos);
+            if (validationError) {
+                return validationError;
+            }
+            // Store todos in session storage
+            const sessionId = context?.sessionId ?? 'default';
+            await todoStorage.update(sessionId, todos);
+            // Format response for LLM
+            const llmContent = formatTodosForLLM(todos);
+            // Calculate incomplete count for smart title
+            const incompleteCount = todos.filter((t) => t.status !== 'completed').length;
+            // Return both LLM content and display content with metadata
+            return {
+                llmContent,
+                metadata: { todos },
+                returnDisplay: { todos },
+                title: `${incompleteCount} todos`,
+            };
+        },
+        id: ToolName.WRITE_TODOS,
+        inputSchema: WriteTodosInputSchema,
+    };
+}

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

@@ -0,0 +1,19 @@
+export { ToolError, ToolExecutionError, ToolNotFoundError, ToolProviderNotInitializedError, ToolValidationError, } from '../../core/domain/errors/tool-error.js';
+export { ToolName } from '../../core/domain/tools/constants.js';
+export type { KnownTool } from '../../core/domain/tools/constants.js';
+export type { JSONSchema7, Tool, ToolExecutionContext, ToolSet } from '../../core/domain/tools/types.js';
+export type { IToolProvider } from '../../core/interfaces/i-tool-provider.js';
+export { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-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 { createSearchKnowledgeTool } from './implementations/search-knowledge-tool.js';
+export { createSpecAnalyzeTool } from './implementations/spec-analyze-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/agent/infra/tools/index.js

@@ -0,0 +1,20 @@
+// Errors
+export { ToolError, ToolExecutionError, ToolNotFoundError, ToolProviderNotInitializedError, ToolValidationError, } from '../../core/domain/errors/tool-error.js';
+// Constants
+export { ToolName } from '../../core/domain/tools/constants.js';
+// Tool implementations (for direct access if needed)
+export { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-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 { createSearchKnowledgeTool } from './implementations/search-knowledge-tool.js';
+export { createSpecAnalyzeTool } from './implementations/spec-analyze-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';

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

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

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

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

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

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