byterover-cli 1.5.0 → 1.7.0

package/dist/agent/infra/sandbox/curate-service.js

@@ -0,0 +1,142 @@
+/**
+ * Curate service implementation for sandbox integration.
+ * Wraps the curate-tool logic for use in the sandbox's tools.* SDK.
+ */
+import { executeCurate } from '../tools/implementations/curate-tool.js';
+/**
+ * Default base path for knowledge storage.
+ */
+const DEFAULT_BASE_PATH = '.brv/context-tree';
+/**
+ * Validate operations and return early failures for common mistakes.
+ * This provides better error messages before the operation is attempted.
+ */
+function validateOperations(operations) {
+    const failures = [];
+    for (const op of operations) {
+        if (op.type === 'MERGE') {
+            // MERGE requires mergeTarget and mergeTargetTitle
+            if (!op.mergeTarget) {
+                failures.push({
+                    message: 'MERGE operation requires mergeTarget (the destination path). Did you mean to use UPDATE instead? Use UPDATE to modify an existing file with new content, MERGE is only for combining two existing files.',
+                    path: op.path,
+                    status: 'failed',
+                    type: 'MERGE',
+                });
+                continue;
+            }
+            if (!op.mergeTargetTitle) {
+                failures.push({
+                    message: 'MERGE operation requires mergeTargetTitle (the destination file title). MERGE combines source file into target file. Did you mean to use UPDATE instead?',
+                    path: op.path,
+                    status: 'failed',
+                    type: 'MERGE',
+                });
+                continue;
+            }
+            // Warn if content is provided (it will be ignored) - add to failures with warning message
+            if (op.content) {
+                failures.push({
+                    message: 'MERGE operation ignores the content field. MERGE reads content from existing files and combines them. If you want to update a file with new content, use UPDATE instead.',
+                    path: op.path,
+                    status: 'failed',
+                    type: 'MERGE',
+                });
+                continue;
+            }
+        }
+        // ADD, UPDATE, and UPSERT require content
+        if ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.content) {
+            failures.push({
+                message: `${op.type} operation requires content with rawConcept and/or narrative.`,
+                path: op.path,
+                status: 'failed',
+                type: op.type,
+            });
+        }
+        // ADD, UPDATE, and UPSERT require title
+        if ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {
+            failures.push({
+                message: `${op.type} operation requires a title (becomes the .md filename).`,
+                path: op.path,
+                status: 'failed',
+                type: op.type,
+            });
+        }
+    }
+    return failures;
+}
+/**
+ * Curate service implementation.
+ * Provides curate and domain detection operations for the sandbox.
+ */
+export class CurateService {
+    /**
+     * Execute curate operations on knowledge topics.
+     *
+     * @param operations - Array of curate operations to apply
+     * @param options - Curate options
+     * @returns Curate result with applied operations and summary
+     */
+    async curate(operations, options) {
+        const basePath = options?.basePath ?? DEFAULT_BASE_PATH;
+        // Pre-validate operations to catch common mistakes early
+        const validationFailures = validateOperations(operations);
+        if (validationFailures.length > 0) {
+            // Return early with validation failures and helpful messages
+            return {
+                applied: validationFailures,
+                summary: {
+                    added: 0,
+                    deleted: 0,
+                    failed: validationFailures.length,
+                    merged: 0,
+                    updated: 0,
+                },
+            };
+        }
+        // Call the underlying executeCurate function from curate-tool
+        const result = await executeCurate({
+            basePath,
+            operations,
+        });
+        return result;
+    }
+    /**
+     * Detect and validate domains from input data.
+     * This is a pass-through validation that ensures domain names are valid.
+     *
+     * @param domains - Array of detected domains with text segments
+     * @returns Validated domains
+     */
+    async detectDomains(domains) {
+        // Validate domain names (must be valid for filesystem)
+        const validatedDomains = domains.filter((domain) => {
+            // Check for empty category
+            if (!domain.category || domain.category.length === 0) {
+                return false;
+            }
+            // Check for invalid characters in domain name
+            // Allow only letters, numbers, underscores, and hyphens
+            if (!/^[\w-]+$/.test(domain.category)) {
+                return false;
+            }
+            // Ensure text segments array is non-empty
+            if (!domain.textSegments || domain.textSegments.length === 0) {
+                return false;
+            }
+            return true;
+        });
+        return {
+            domains: validatedDomains,
+        };
+    }
+}
+/**
+ * Creates a curate service instance.
+ *
+ * @returns CurateService instance
+ */
+export function createCurateService() {
+    return new CurateService();
+}

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

@@ -0,0 +1,2 @@
+export * from './local-sandbox.js';
+export * from './sandbox-service.js';

package/dist/agent/infra/sandbox/index.js

@@ -0,0 +1,2 @@
+export * from './local-sandbox.js';
+export * from './sandbox-service.js';

package/dist/agent/infra/sandbox/local-sandbox.d.ts

@@ -0,0 +1,45 @@
+import type { EnvironmentContext } from '../../core/domain/environment/types.js';
+import type { REPLResult, SandboxConfig } from '../../core/domain/sandbox/types.js';
+import type { ToolsSDK } from './tools-sdk.js';
+/**
+ * Configuration options for LocalSandbox.
+ */
+export interface LocalSandboxOptions {
+    /** Environment context for env.* properties */
+    environmentContext?: EnvironmentContext;
+    /** Initial context variables to inject */
+    initialContext?: Record<string, unknown>;
+    /** Tools SDK for file system operations (injected as `tools` in context) */
+    toolsSDK?: ToolsSDK;
+}
+/**
+ * Local sandbox for code execution using Node.js vm module.
+ * Provides isolated JavaScript/TypeScript execution with security controls.
+ */
+export declare class LocalSandbox {
+    private context;
+    private errorBuffer;
+    private outputBuffer;
+    constructor(options?: LocalSandboxOptions);
+    /**
+     * Execute code in the sandbox.
+     * Supports both synchronous and asynchronous code execution.
+     *
+     * @param code - JavaScript or TypeScript code to execute
+     * @param config - Execution configuration
+     * @returns Execution result
+     */
+    execute(code: string, config?: SandboxConfig): Promise<REPLResult>;
+    /**
+     * Get current context state.
+     *
+     * @returns Copy of current context
+     */
+    getContext(): Record<string, unknown>;
+    /**
+     * Update context with new values.
+     *
+     * @param updates - Key-value pairs to add to context
+     */
+    updateContext(updates: Record<string, unknown>): void;
+}

package/dist/agent/infra/sandbox/local-sandbox.js

@@ -0,0 +1,222 @@
+import { createRequire } from 'node:module';
+import vm from 'node:vm';
+import { ALLOWED_GLOBALS, ALLOWED_PACKAGES, DEFAULT_SANDBOX_TIMEOUT } from '../../core/domain/sandbox/constants.js';
+// Create a require function that works in both ESM and CJS environments
+const esmRequire = createRequire(import.meta.url);
+/**
+ * Detect if code contains TypeScript-specific syntax.
+ */
+function detectTypeScript(code) {
+    const tsPatterns = [
+        /:\s*(string|number|boolean|any|void|never|unknown)\b/, // Type annotations
+        /interface\s+\w+/, // Interface declarations
+        /type\s+\w+\s*=/, // Type aliases
+        /as\s+(string|number|boolean|any|unknown|\w+)/, // Type assertions
+        /:\s*\w+\[\]/, // Array types
+        /<[A-Z]\w*>/, // Generic types (must start with uppercase to avoid JSX false positives)
+    ];
+    return tsPatterns.some((pattern) => pattern.test(code));
+}
+/**
+ * Cached esbuild module for transpilation.
+ */
+let esbuildModule;
+/**
+ * Transpile TypeScript to JavaScript using esbuild.
+ * Uses ESM format which doesn't add require() calls for simple type stripping.
+ */
+function transpileTypeScript(code) {
+    if (!esbuildModule) {
+        // Use esmRequire to load esbuild - works in both ESM and CJS environments
+        esbuildModule = esmRequire('esbuild');
+    }
+    // Use 'esm' format which produces clean JavaScript without module system wrappers
+    // For type-only TypeScript (interfaces, type annotations), this just strips types
+    // without adding any import/require statements
+    const result = esbuildModule.transformSync(code, {
+        format: 'esm',
+        loader: 'ts',
+        target: 'es2022',
+    });
+    return result.code;
+}
+/**
+ * Load whitelisted packages for sandbox.
+ * Packages are loaded lazily and cached.
+ */
+const packageCache = new Map();
+function loadAllowedPackages() {
+    const packages = {};
+    for (const pkgName of ALLOWED_PACKAGES) {
+        if (!packageCache.has(pkgName)) {
+            try {
+                // Use esmRequire to load packages - works in both ESM and CJS environments
+                packageCache.set(pkgName, esmRequire(pkgName));
+            }
+            catch {
+                // Package not installed - skip silently
+                packageCache.set(pkgName, undefined);
+            }
+        }
+        const pkg = packageCache.get(pkgName);
+        if (pkg !== undefined) {
+            // Convert package name to camelCase for easier access
+            // e.g., 'date-fns' -> 'dateFns', 'change-case' -> 'changeCase'
+            const camelCaseName = pkgName.replaceAll(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+            packages[camelCaseName] = pkg;
+            // Also keep original name
+            packages[pkgName.replaceAll('-', '_')] = pkg;
+        }
+    }
+    return packages;
+}
+/**
+ * Local sandbox for code execution using Node.js vm module.
+ * Provides isolated JavaScript/TypeScript execution with security controls.
+ */
+export class LocalSandbox {
+    context;
+    errorBuffer = [];
+    outputBuffer = [];
+    constructor(options = {}) {
+        const { environmentContext, initialContext = {}, toolsSDK } = options;
+        // Create safe console that captures output
+        const safeConsole = {
+            debug: (...args) => this.outputBuffer.push(args.map(String).join(' ')),
+            error: (...args) => this.errorBuffer.push(args.map(String).join(' ')),
+            info: (...args) => this.outputBuffer.push(args.map(String).join(' ')),
+            log: (...args) => this.outputBuffer.push(args.map(String).join(' ')),
+            warn: (...args) => this.errorBuffer.push(args.map(String).join(' ')),
+        };
+        // Load whitelisted packages
+        const packages = loadAllowedPackages();
+        // Build sandbox context with allowed globals
+        const sandbox = {
+            console: safeConsole,
+            packages, // Make packages available as `packages.lodash`, etc.
+            ...packages, // Also spread at top level for convenience: `lodash`, `dateFns`, etc.
+            ...initialContext,
+        };
+        // Inject Tools SDK if provided (for file system operations)
+        if (toolsSDK) {
+            sandbox.tools = toolsSDK;
+        }
+        // Inject environment context as `env` object if provided
+        if (environmentContext) {
+            sandbox.env = {
+                brvStructure: environmentContext.brvStructure,
+                fileTree: environmentContext.fileTree,
+                isGitRepository: environmentContext.isGitRepository,
+                nodeVersion: environmentContext.nodeVersion,
+                osVersion: environmentContext.osVersion,
+                platform: environmentContext.platform,
+                workingDirectory: environmentContext.workingDirectory,
+            };
+        }
+        // Add allowed built-in globals
+        for (const name of ALLOWED_GLOBALS) {
+            if (name !== 'console' && name in globalThis) {
+                sandbox[name] = globalThis[name];
+            }
+        }
+        this.context = vm.createContext(sandbox);
+    }
+    /**
+     * Execute code in the sandbox.
+     * Supports both synchronous and asynchronous code execution.
+     *
+     * @param code - JavaScript or TypeScript code to execute
+     * @param config - Execution configuration
+     * @returns Execution result
+     */
+    async execute(code, config) {
+        this.outputBuffer = [];
+        this.errorBuffer = [];
+        const timeout = config?.timeout ?? DEFAULT_SANDBOX_TIMEOUT;
+        const startTime = performance.now();
+        let returnValue;
+        let processedCode = code;
+        try {
+            // Determine language (auto-detect if not specified)
+            const isTypeScript = config?.language === 'typescript' || (config?.language !== 'javascript' && detectTypeScript(code));
+            // Transpile TypeScript if needed
+            if (isTypeScript) {
+                processedCode = transpileTypeScript(code);
+            }
+            returnValue = vm.runInContext(processedCode, this.context, {
+                displayErrors: true,
+                timeout,
+            });
+            // If the return value is a Promise or thenable, await it with timeout
+            // Use duck-typing to handle Promises from vm context (which may have different constructor)
+            const isPromiseLike = returnValue !== null &&
+                typeof returnValue === 'object' &&
+                typeof returnValue.then === 'function';
+            if (isPromiseLike) {
+                let timeoutId;
+                try {
+                    returnValue = await Promise.race([
+                        returnValue,
+                        new Promise((_, reject) => {
+                            timeoutId = setTimeout(() => reject(new Error('Async execution timeout')), timeout);
+                        }),
+                    ]);
+                }
+                finally {
+                    // Always clear the timeout to prevent resource leaks
+                    if (timeoutId !== undefined) {
+                        clearTimeout(timeoutId);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            this.errorBuffer.push(errorMessage);
+        }
+        const executionTime = performance.now() - startTime;
+        // Extract current context state (excluding functions, built-ins, and injected services)
+        const locals = {};
+        const excludedKeys = new Set(['context', 'env', 'packages', 'tools']);
+        for (const key of Object.keys(this.context)) {
+            const isAllowedGlobal = ALLOWED_GLOBALS.includes(key);
+            const isPackage = key in loadAllowedPackages();
+            const isExcluded = excludedKeys.has(key);
+            if (!isAllowedGlobal && !isPackage && !isExcluded && typeof this.context[key] !== 'function') {
+                try {
+                    // Only include JSON-serializable values
+                    JSON.stringify(this.context[key]);
+                    locals[key] = this.context[key];
+                }
+                catch {
+                    locals[key] = '[Non-serializable]';
+                }
+            }
+        }
+        return {
+            executionTime,
+            locals,
+            returnValue,
+            stderr: this.errorBuffer.join('\n'),
+            stdout: this.outputBuffer.join('\n'),
+        };
+    }
+    /**
+     * Get current context state.
+     *
+     * @returns Copy of current context
+     */
+    getContext() {
+        return { ...this.context };
+    }
+    /**
+     * Update context with new values.
+     *
+     * @param updates - Key-value pairs to add to context
+     */
+    updateContext(updates) {
+        for (const [key, value] of Object.entries(updates)) {
+            this.context[key] = value;
+        }
+    }
+}

package/dist/agent/infra/sandbox/sandbox-service.d.ts

@@ -0,0 +1,76 @@
+import type { EnvironmentContext } from '../../core/domain/environment/types.js';
+import type { REPLResult, SandboxConfig } from '../../core/domain/sandbox/types.js';
+import type { ICurateService } from '../../core/interfaces/i-curate-service.js';
+import type { IFileSystem } from '../../core/interfaces/i-file-system.js';
+import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
+import type { ISearchKnowledgeService } from './tools-sdk.js';
+/**
+ * Sandbox service implementation.
+ * Manages sandbox instances tied to agent sessions.
+ */
+export declare class SandboxService implements ISandboxService {
+    /** Curate service for Tools SDK */
+    private curateService?;
+    /** Environment context for sandbox injection */
+    private environmentContext?;
+    /** File system service for Tools SDK */
+    private fileSystem?;
+    /** Map of agent sessionId to LocalSandbox instance */
+    private sandboxes;
+    /** Search knowledge service for Tools SDK */
+    private searchKnowledgeService?;
+    /** Cached Tools SDK instance (created when fileSystem is set) */
+    private toolsSDK?;
+    /**
+     * Clean up all resources (called on agent shutdown).
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Clear sandbox state for a session.
+     *
+     * @param sessionId - Session identifier
+     */
+    clearSession(sessionId: string): Promise<void>;
+    /**
+     * Execute JavaScript/TypeScript code in a sandbox.
+     *
+     * @param code - Code to execute
+     * @param sessionId - Agent session ID (state persists per session)
+     * @param config - Optional execution configuration
+     * @returns Execution result
+     */
+    executeCode(code: string, sessionId: string, config?: SandboxConfig): Promise<REPLResult>;
+    /**
+     * Set the curate service for Tools SDK injection.
+     * When set, new sandboxes will have access to curate operations via `tools.curate()`.
+     *
+     * @param curateService - Curate service instance
+     */
+    setCurateService(curateService: ICurateService): void;
+    /**
+     * Set the environment context for sandbox injection.
+     * When set, new sandboxes will have access to environment info via `env.*` properties.
+     *
+     * @param environmentContext - Environment context object
+     */
+    setEnvironmentContext(environmentContext: EnvironmentContext): void;
+    /**
+     * Set the file system service for Tools SDK injection.
+     * When set, new sandboxes will have access to file system operations via `tools.*` methods.
+     *
+     * @param fileSystem - File system service instance
+     */
+    setFileSystem(fileSystem: IFileSystem): void;
+    /**
+     * Set the search knowledge service for Tools SDK injection.
+     * When set, new sandboxes will have access to knowledge search via `tools.searchKnowledge()`.
+     *
+     * @param searchKnowledgeService - Search knowledge service instance
+     */
+    setSearchKnowledgeService(searchKnowledgeService: ISearchKnowledgeService): void;
+    /**
+     * Rebuild the Tools SDK instance when services change.
+     * Clears existing sandboxes so new ones get the updated SDK.
+     */
+    private rebuildToolsSDK;
+}

package/dist/agent/infra/sandbox/sandbox-service.js

@@ -0,0 +1,118 @@
+import { LocalSandbox } from './local-sandbox.js';
+import { createToolsSDK } from './tools-sdk.js';
+/**
+ * Sandbox service implementation.
+ * Manages sandbox instances tied to agent sessions.
+ */
+export class SandboxService {
+    /** Curate service for Tools SDK */
+    curateService;
+    /** Environment context for sandbox injection */
+    environmentContext;
+    /** File system service for Tools SDK */
+    fileSystem;
+    /** Map of agent sessionId to LocalSandbox instance */
+    sandboxes = new Map();
+    /** Search knowledge service for Tools SDK */
+    searchKnowledgeService;
+    /** Cached Tools SDK instance (created when fileSystem is set) */
+    toolsSDK;
+    /**
+     * Clean up all resources (called on agent shutdown).
+     */
+    async cleanup() {
+        this.sandboxes.clear();
+    }
+    /**
+     * Clear sandbox state for a session.
+     *
+     * @param sessionId - Session identifier
+     */
+    async clearSession(sessionId) {
+        this.sandboxes.delete(sessionId);
+    }
+    /**
+     * Execute JavaScript/TypeScript code in a sandbox.
+     *
+     * @param code - Code to execute
+     * @param sessionId - Agent session ID (state persists per session)
+     * @param config - Optional execution configuration
+     * @returns Execution result
+     */
+    async executeCode(code, sessionId, config) {
+        // Get or create sandbox for this agent session
+        let sandbox = this.sandboxes.get(sessionId);
+        if (!sandbox) {
+            // First execution for this session - create new sandbox
+            const initialContext = {};
+            if (config?.contextPayload) {
+                initialContext.context = config.contextPayload;
+            }
+            sandbox = new LocalSandbox({
+                environmentContext: this.environmentContext,
+                initialContext,
+                toolsSDK: this.toolsSDK,
+            });
+            this.sandboxes.set(sessionId, sandbox);
+        }
+        else if (config?.contextPayload) {
+            // Update context if provided
+            sandbox.updateContext({ context: config.contextPayload });
+        }
+        return sandbox.execute(code, config);
+    }
+    /**
+     * Set the curate service for Tools SDK injection.
+     * When set, new sandboxes will have access to curate operations via `tools.curate()`.
+     *
+     * @param curateService - Curate service instance
+     */
+    setCurateService(curateService) {
+        this.curateService = curateService;
+        this.rebuildToolsSDK();
+    }
+    /**
+     * Set the environment context for sandbox injection.
+     * When set, new sandboxes will have access to environment info via `env.*` properties.
+     *
+     * @param environmentContext - Environment context object
+     */
+    setEnvironmentContext(environmentContext) {
+        this.environmentContext = environmentContext;
+        // Clear existing sandboxes so new ones get the updated environment
+        this.sandboxes.clear();
+    }
+    /**
+     * Set the file system service for Tools SDK injection.
+     * When set, new sandboxes will have access to file system operations via `tools.*` methods.
+     *
+     * @param fileSystem - File system service instance
+     */
+    setFileSystem(fileSystem) {
+        this.fileSystem = fileSystem;
+        this.rebuildToolsSDK();
+    }
+    /**
+     * Set the search knowledge service for Tools SDK injection.
+     * When set, new sandboxes will have access to knowledge search via `tools.searchKnowledge()`.
+     *
+     * @param searchKnowledgeService - Search knowledge service instance
+     */
+    setSearchKnowledgeService(searchKnowledgeService) {
+        this.searchKnowledgeService = searchKnowledgeService;
+        this.rebuildToolsSDK();
+    }
+    /**
+     * Rebuild the Tools SDK instance when services change.
+     * Clears existing sandboxes so new ones get the updated SDK.
+     */
+    rebuildToolsSDK() {
+        if (this.fileSystem) {
+            this.toolsSDK = createToolsSDK(this.fileSystem, this.searchKnowledgeService, this.curateService);
+            // Clear existing sandboxes so new ones get the updated tools SDK
+            // Note: This means existing sessions lose their state when services are updated
+            // This is acceptable since services are typically set once at startup
+            this.sandboxes.clear();
+        }
+    }
+}