@metabob/minibob 0.1.2

package/dist/tools.js

@@ -0,0 +1,771 @@
+/**
+ * minibob Built-in Tools
+ *
+ * Minimal set of tools for activity execution and self-development.
+ *
+ * SECURITY: Path validation, command whitelisting, and input sanitization
+ * enforced to prevent command injection and path traversal attacks.
+ */
+import * as path from "node:path";
+// =============================================================================
+// SECURITY UTILITIES
+// =============================================================================
+/**
+ * Allowed bash commands (whitelist approach)
+ * Only these commands can be executed via the bash tool
+ */
+const ALLOWED_BASH_COMMANDS = new Set([
+    // Version control
+    "git",
+    // Package managers
+    "npm", "pnpm", "yarn", "bun",
+    // Build tools
+    "make", "cmake", "cargo", "go",
+    // File operations (read-only)
+    "ls", "cat", "head", "tail", "find", "grep", "rg", "fd",
+    // Text processing
+    "sed", "awk", "cut", "sort", "uniq", "wc",
+    // Directory operations (safe)
+    "pwd", "cd", "mkdir", "rmdir",
+    // Testing
+    "pytest", "jest", "vitest", "cargo test",
+    // Linting/formatting
+    "eslint", "prettier", "black", "rustfmt",
+    // Type checking
+    "tsc", "mypy", "cargo check",
+]);
+/**
+ * Dangerous command patterns that are always blocked
+ */
+const BLOCKED_COMMAND_PATTERNS = [
+    /rm\s+-rf\s+\//, // rm -rf /
+    /:\(\)\{.*\}/, // Fork bombs
+    />\s*\/dev\/sd[a-z]/, // Writing to raw disk
+    /mkfs/, // Filesystem formatting
+    /dd\s+if=.*of=\/dev/, // Direct disk write
+];
+/**
+ * Validate and sanitize a bash command
+ * @throws Error if command is not allowed
+ */
+function validateBashCommand(command) {
+    // Check blocked patterns first
+    for (const pattern of BLOCKED_COMMAND_PATTERNS) {
+        if (pattern.test(command)) {
+            throw new Error(`Blocked dangerous command pattern: ${pattern.source}`);
+        }
+    }
+    // Extract the first command (before pipes, semicolons, etc.)
+    const firstCommand = command
+        .split(/[|;&]/)[0]?.trim()
+        .split(/\s+/)[0];
+    if (!firstCommand) {
+        throw new Error("Empty command");
+    }
+    // Check if command is in whitelist
+    if (!ALLOWED_BASH_COMMANDS.has(firstCommand)) {
+        throw new Error(`Command '${firstCommand}' not in whitelist. Allowed: ${Array.from(ALLOWED_BASH_COMMANDS).join(", ")}`);
+    }
+}
+/**
+ * Validate a file path is within the working directory
+ * Prevents path traversal attacks (../../etc/passwd)
+ * @returns Canonicalized absolute path
+ * @throws Error if path escapes working directory
+ */
+function validatePath(filePath, workingDirectory) {
+    // Resolve to absolute path
+    const absolutePath = path.isAbsolute(filePath)
+        ? path.resolve(filePath)
+        : path.resolve(workingDirectory, filePath);
+    // Canonicalize (removes .., ., symlinks)
+    const canonicalPath = path.normalize(absolutePath);
+    const canonicalWorkDir = path.normalize(path.resolve(workingDirectory));
+    // Check if path is within working directory
+    if (!canonicalPath.startsWith(canonicalWorkDir)) {
+        throw new Error(`Path traversal blocked: ${filePath} resolves outside working directory (${workingDirectory})`);
+    }
+    return canonicalPath;
+}
+// =============================================================================
+// TOOL DEFINITIONS
+// =============================================================================
+export const toolDefinitions = {
+    bash: {
+        name: "bash",
+        description: "Execute a shell command. Returns stdout and stderr.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "The shell command to execute",
+                },
+                cwd: {
+                    type: "string",
+                    description: "Working directory for the command (optional)",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in milliseconds (default: 60000)",
+                },
+            },
+            required: ["command"],
+        },
+    },
+    read: {
+        name: "read",
+        description: "Read a file from the filesystem. Returns file content with line numbers.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to the file to read",
+                },
+                offset: {
+                    type: "number",
+                    description: "Line number to start reading from (0-based)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of lines to read (default: 2000)",
+                },
+            },
+            required: ["path"],
+        },
+    },
+    write: {
+        name: "write",
+        description: "Write content to a file. Creates directories if needed.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to the file to write",
+                },
+                content: {
+                    type: "string",
+                    description: "Content to write to the file",
+                },
+            },
+            required: ["path", "content"],
+        },
+    },
+    edit: {
+        name: "edit",
+        description: "Edit a file by replacing exact text. The oldString must match exactly.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to the file to edit",
+                },
+                oldString: {
+                    type: "string",
+                    description: "Exact text to find and replace",
+                },
+                newString: {
+                    type: "string",
+                    description: "Text to replace with",
+                },
+                replaceAll: {
+                    type: "boolean",
+                    description: "Replace all occurrences (default: false)",
+                },
+            },
+            required: ["path", "oldString", "newString"],
+        },
+    },
+    glob: {
+        name: "glob",
+        description: "Find files matching a glob pattern.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Glob pattern to match (e.g., '**/*.ts')",
+                },
+                cwd: {
+                    type: "string",
+                    description: "Directory to search from (optional)",
+                },
+            },
+            required: ["pattern"],
+        },
+    },
+    grep: {
+        name: "grep",
+        description: "Search file contents using a regex pattern.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Regex pattern to search for",
+                },
+                include: {
+                    type: "string",
+                    description: "File pattern to include (e.g., '*.ts')",
+                },
+                cwd: {
+                    type: "string",
+                    description: "Directory to search in (optional)",
+                },
+            },
+            required: ["pattern"],
+        },
+    },
+    list: {
+        name: "list",
+        description: "List files and directories in a path.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Directory path to list",
+                },
+            },
+            required: ["path"],
+        },
+    },
+    git: {
+        name: "git",
+        description: "Execute git commands for version control operations.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "Git subcommand (e.g., 'status', 'add', 'commit', 'diff')",
+                    enum: ["status", "add", "commit", "diff", "log", "branch", "checkout", "push", "pull"],
+                },
+                args: {
+                    type: "array",
+                    description: "Arguments for the git command",
+                },
+                cwd: {
+                    type: "string",
+                    description: "Working directory (optional)",
+                },
+            },
+            required: ["command"],
+        },
+    },
+    activity: {
+        name: "activity",
+        description: "Execute an activity template (enables nested activity execution). Template can be loaded from MCP backend or local file.",
+        parameters: {
+            type: "object",
+            properties: {
+                templateId: {
+                    type: "string",
+                    description: "Activity template ID (from MCP) or path (local file)",
+                },
+                variables: {
+                    type: "object",
+                    description: "Variables to pass to the activity",
+                },
+                reason: {
+                    type: "string",
+                    description: "Reason for executing this activity",
+                },
+            },
+            required: ["templateId"],
+        },
+    },
+    search_activities: {
+        name: "search_activities",
+        description: "Search for existing activity templates by category or keyword. Use this BEFORE creating new activities to avoid duplication.",
+        parameters: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "Filter by category (feature, bugfix, refactor, tool, infrastructure)",
+                    enum: ["feature", "bugfix", "refactor", "tool", "infrastructure"],
+                },
+                verbose: {
+                    type: "boolean",
+                    description: "Show full details (default: false, returns compact list)",
+                },
+            },
+            required: [],
+        },
+    },
+    create_activity_goal_seeking: {
+        name: "create_activity_goal_seeking",
+        description: "Create a new activity template for a non-trivial task. The agent will autonomously generate tasks and learn from execution. Use this when no existing activity matches your need.",
+        parameters: {
+            type: "object",
+            properties: {
+                goalDescription: {
+                    type: "string",
+                    description: "High-level goal description (e.g., 'Deploy app to production with health checks')",
+                },
+                templateName: {
+                    type: "string",
+                    description: "Human-readable template name (e.g., 'Deploy Production Application')",
+                },
+                category: {
+                    type: "string",
+                    description: "Template category",
+                    enum: ["feature", "bugfix", "refactor", "tool", "infrastructure"],
+                },
+                variables: {
+                    type: "object",
+                    description: "Context variables for goal decomposition",
+                },
+            },
+            required: ["goalDescription", "templateName", "category"],
+        },
+    },
+    impulse_create: {
+        name: "impulse_create",
+        description: "Create a new impulse for context management.",
+        parameters: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Unique impulse ID",
+                },
+                type: {
+                    type: "string",
+                    description: "Impulse pointer type",
+                    enum: ["memo", "file", "activityOutput", "custom"],
+                },
+                content: {
+                    type: "string",
+                    description: "Content (for memo type) or path (for file type)",
+                },
+                budget: {
+                    type: "number",
+                    description: "Token budget for this impulse",
+                },
+                priority: {
+                    type: "string",
+                    description: "Priority level",
+                    enum: ["critical", "high", "medium", "low"],
+                },
+            },
+            required: ["id", "type", "budget"],
+        },
+    },
+};
+/**
+ * Create tool handlers with working directory context
+ */
+export function createToolHandlers(options) {
+    // Support backward compatibility - if string passed, convert to options
+    const opts = typeof options === "string"
+        ? { workingDirectory: options }
+        : options;
+    const workingDirectory = opts.workingDirectory;
+    const resolvePath = (path) => {
+        if (path.startsWith("/"))
+            return path;
+        return `${workingDirectory}/${path}`;
+    };
+    return {
+        bash: async (params) => {
+            const command = params.command;
+            const cwd = params.cwd ?? workingDirectory;
+            const timeout = params.timeout ?? 60000;
+            try {
+                // SECURITY: Validate command against whitelist
+                validateBashCommand(command);
+                const proc = Bun.spawn(["sh", "-c", command], {
+                    cwd,
+                    stdout: "pipe",
+                    stderr: "pipe",
+                });
+                // Handle timeout
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => {
+                        proc.kill();
+                        reject(new Error(`Command timed out after ${timeout}ms`));
+                    }, timeout);
+                });
+                const exitCode = await Promise.race([proc.exited, timeoutPromise]);
+                const stdout = await new Response(proc.stdout).text();
+                const stderr = await new Response(proc.stderr).text();
+                if (exitCode !== 0) {
+                    return {
+                        success: false,
+                        error: `Command failed with exit code ${exitCode}\nStderr: ${stderr}`,
+                        output: stdout,
+                    };
+                }
+                return {
+                    success: true,
+                    output: stdout + (stderr ? `\nStderr: ${stderr}` : ""),
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        read: async (params) => {
+            const filePath = params.path;
+            const offset = params.offset ?? 0;
+            const limit = params.limit ?? 2000;
+            try {
+                // SECURITY: Validate path is within working directory
+                const validatedPath = validatePath(filePath, workingDirectory);
+                const file = Bun.file(validatedPath);
+                if (!(await file.exists())) {
+                    return {
+                        success: false,
+                        error: `File not found: ${validatedPath}`,
+                    };
+                }
+                const content = await file.text();
+                const lines = content.split("\n");
+                const selectedLines = lines.slice(offset, offset + limit);
+                // Format with line numbers
+                const formatted = selectedLines
+                    .map((line, i) => {
+                    const lineNum = (offset + i + 1).toString().padStart(5, "0");
+                    return `${lineNum}| ${line}`;
+                })
+                    .join("\n");
+                return {
+                    success: true,
+                    output: `<file>\n${formatted}\n</file>`,
+                    metadata: {
+                        totalLines: lines.length,
+                        readLines: selectedLines.length,
+                        offset,
+                    },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        write: async (params) => {
+            const filePath = params.path;
+            const content = params.content;
+            try {
+                // SECURITY: Validate path is within working directory
+                const validatedPath = validatePath(filePath, workingDirectory);
+                // Create directory if needed
+                const dir = validatedPath.substring(0, validatedPath.lastIndexOf("/"));
+                if (dir) {
+                    await Bun.$ `mkdir -p ${dir}`.quiet();
+                }
+                await Bun.write(validatedPath, content);
+                return {
+                    success: true,
+                    output: `Wrote ${content.length} bytes to ${path}`,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        edit: async (params) => {
+            const filePath = params.path;
+            const oldString = params.oldString;
+            const newString = params.newString;
+            const replaceAll = params.replaceAll ?? false;
+            try {
+                // SECURITY: Validate path is within working directory
+                const validatedPath = validatePath(filePath, workingDirectory);
+                const file = Bun.file(validatedPath);
+                if (!(await file.exists())) {
+                    return {
+                        success: false,
+                        error: `File not found: ${path}`,
+                    };
+                }
+                const content = await file.text();
+                if (!content.includes(oldString)) {
+                    return {
+                        success: false,
+                        error: `oldString not found in file: "${oldString.substring(0, 50)}..."`,
+                    };
+                }
+                // Check for multiple matches if not replaceAll
+                if (!replaceAll) {
+                    const matches = content.split(oldString).length - 1;
+                    if (matches > 1) {
+                        return {
+                            success: false,
+                            error: `oldString found ${matches} times. Use replaceAll: true or provide more context.`,
+                        };
+                    }
+                }
+                const newContent = replaceAll
+                    ? content.split(oldString).join(newString)
+                    : content.replace(oldString, newString);
+                await Bun.write(validatedPath, newContent);
+                return {
+                    success: true,
+                    output: `Edited ${validatedPath}`,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        glob: async (params) => {
+            const pattern = params.pattern;
+            const cwd = params.cwd ?? workingDirectory;
+            try {
+                const glob = new Bun.Glob(pattern);
+                const files = [];
+                for await (const file of glob.scan({ cwd })) {
+                    files.push(file);
+                    if (files.length >= 100)
+                        break; // Limit results
+                }
+                return {
+                    success: true,
+                    output: files.length > 0 ? files.join("\n") : "No files found",
+                    metadata: { count: files.length },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        grep: async (params) => {
+            const pattern = params.pattern;
+            const include = params.include;
+            const cwd = params.cwd ?? workingDirectory;
+            try {
+                // Use ripgrep if available, fall back to grep
+                const rgArgs = ["rg", "-l", pattern];
+                if (include) {
+                    rgArgs.push("-g", include);
+                }
+                const proc = Bun.spawn(rgArgs, {
+                    cwd,
+                    stdout: "pipe",
+                    stderr: "pipe",
+                });
+                const exitCode = await proc.exited;
+                const stdout = await new Response(proc.stdout).text();
+                if (exitCode !== 0 && exitCode !== 1) {
+                    // Exit code 1 means no matches, which is OK
+                    return {
+                        success: false,
+                        error: `grep failed with exit code ${exitCode}`,
+                    };
+                }
+                const files = stdout.trim().split("\n").filter(Boolean);
+                return {
+                    success: true,
+                    output: files.length > 0 ? `Found ${files.length} files:\n${files.join("\n")}` : "No matches found",
+                    metadata: { count: files.length },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        list: async (params) => {
+            const filePath = params.path;
+            try {
+                // SECURITY: Validate path is within working directory
+                const validatedPath = validatePath(filePath, workingDirectory);
+                const dir = await Bun.$ `ls -la ${validatedPath}`.text();
+                return {
+                    success: true,
+                    output: dir,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        git: async (params) => {
+            const command = params.command;
+            const args = params.args ?? [];
+            const cwd = params.cwd ?? workingDirectory;
+            try {
+                const gitArgs = ["git", command, ...args];
+                const proc = Bun.spawn(gitArgs, {
+                    cwd,
+                    stdout: "pipe",
+                    stderr: "pipe",
+                });
+                const exitCode = await proc.exited;
+                const stdout = await new Response(proc.stdout).text();
+                const stderr = await new Response(proc.stderr).text();
+                if (exitCode !== 0) {
+                    return {
+                        success: false,
+                        error: `git ${command} failed: ${stderr}`,
+                        output: stdout,
+                    };
+                }
+                return {
+                    success: true,
+                    output: stdout || `git ${command} completed successfully`,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        activity: async (params) => {
+            if (!opts.onActivityExecute) {
+                return {
+                    success: false,
+                    error: "Activity execution not configured (onActivityExecute callback required)",
+                };
+            }
+            try {
+                const templateId = params.templateId;
+                const variables = params.variables ?? {};
+                const reason = params.reason;
+                console.log(`[Tool:activity] Executing nested activity: ${templateId}`);
+                const result = await opts.onActivityExecute(templateId, variables, reason);
+                return {
+                    success: true,
+                    output: `Activity "${templateId}" executed successfully\n\nResult:\n${JSON.stringify(result, null, 2)}`,
+                    metadata: { result },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        search_activities: async (params) => {
+            if (!opts.onSearchActivities) {
+                return {
+                    success: false,
+                    error: "Activity search not configured (onSearchActivities callback required)",
+                };
+            }
+            try {
+                const category = params.category;
+                const verbose = params.verbose ?? false;
+                console.log(`[Tool:search_activities] Searching activities:`, { category, verbose });
+                const result = await opts.onSearchActivities(category, verbose);
+                return {
+                    success: true,
+                    output: `Found ${result.count} activities:\n\n${JSON.stringify(result.activities, null, 2)}`,
+                    metadata: { result },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        create_activity_goal_seeking: async (params) => {
+            if (!opts.onCreateActivity) {
+                return {
+                    success: false,
+                    error: "Activity creation not configured (onCreateActivity callback required)",
+                };
+            }
+            try {
+                const goalDescription = params.goalDescription;
+                const templateName = params.templateName;
+                const category = params.category;
+                const variables = params.variables ?? {};
+                console.log(`[Tool:create_activity_goal_seeking] Creating activity:`, {
+                    templateName,
+                    category,
+                    goalDescription: goalDescription.substring(0, 100) + "...",
+                });
+                const result = await opts.onCreateActivity({
+                    goalDescription,
+                    templateName,
+                    category,
+                    variables,
+                });
+                return {
+                    success: true,
+                    output: `Activity template "${templateName}" created successfully\n\nTemplate ID: ${result.templateId}\n\nYou can now execute it with: activity(templateId: "${result.templateId}")`,
+                    metadata: { result },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        impulse_create: async (params) => {
+            if (!opts.onImpulseCreate) {
+                return {
+                    success: false,
+                    error: "Impulse creation not configured (onImpulseCreate callback required)",
+                };
+            }
+            try {
+                const id = params.id;
+                const type = params.type;
+                const content = params.content;
+                const budget = params.budget;
+                const priority = params.priority;
+                const impulse = { id, type, content, budget, priority };
+                opts.onImpulseCreate(impulse);
+                return {
+                    success: true,
+                    output: `Impulse "${id}" created with type ${type} and budget ${budget} tokens`,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        // Merge in any custom tools provided by the host application
+        ...Object.fromEntries(Object.entries(opts.customTools ?? {}).map(([name, { handler }]) => [name, handler])),
+    };
+}
+/**
+ * Get all tool definitions as an array.
+ * @param extraDefinitions Additional tool definitions from custom tools (e.g. Perspective domain tools).
+ */
+export function getAllToolDefinitions(extraDefinitions) {
+    const base = Object.values(toolDefinitions);
+    if (extraDefinitions && extraDefinitions.length > 0) {
+        return [...base, ...extraDefinitions];
+    }
+    return base;
+}
+//# sourceMappingURL=tools.js.map