@metabob/minibob 0.1.2

package/src/tools.ts

@@ -0,0 +1,924 @@
+/**
+ * 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 type { ToolDefinition, ToolHandler, ToolResult } from "./types"
+
+// Re-export ToolDefinition for consumers that import from tools.ts
+export type { ToolDefinition } from "./types"
+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: string): void {
+  // 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: string, workingDirectory: string): string {
+  // 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: Record<string, ToolDefinition> = {
+  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"],
+    },
+  },
+}
+
+// =============================================================================
+// TOOL HANDLERS
+// =============================================================================
+
+/**
+ * Options for creating tool handlers
+ */
+export interface ToolHandlerOptions {
+  workingDirectory: string
+  onActivityExecute?: (templateId: string, variables: Record<string, unknown>, reason?: string) => Promise<unknown>
+  onSearchActivities?: (category?: string, verbose?: boolean) => Promise<{ count: number; activities: unknown[] }>
+  onCreateActivity?: (params: {
+    goalDescription: string
+    templateName: string
+    category: string
+    variables: Record<string, unknown>
+  }) => Promise<{ templateId: string }>
+  onImpulseCreate?: (impulse: { id: string; type: string; content?: string; budget: number; priority: string }) => void
+  /**
+   * Custom domain-specific tools injected by the host application.
+   * Each entry provides a tool definition (for LLM function calling) and a handler.
+   * Custom tools are merged with built-in tools; custom names must not collide with
+   * built-in names (bash, read, write, edit, glob, grep, list, git, activity,
+   * search_activities, create_activity_goal_seeking, impulse_create).
+   */
+  customTools?: Record<string, { definition: ToolDefinition; handler: ToolHandler }>
+}
+
+/**
+ * Create tool handlers with working directory context
+ */
+export function createToolHandlers(options: string | ToolHandlerOptions): Record<string, ToolHandler> {
+  // Support backward compatibility - if string passed, convert to options
+  const opts: ToolHandlerOptions = typeof options === "string" 
+    ? { workingDirectory: options }
+    : options
+
+  const workingDirectory = opts.workingDirectory
+  const resolvePath = (path: string): string => {
+    if (path.startsWith("/")) return path
+    return `${workingDirectory}/${path}`
+  }
+
+  return {
+    bash: async (params): Promise<ToolResult> => {
+      const command = params.command as string
+      const cwd = (params.cwd as string) ?? workingDirectory
+      const timeout = (params.timeout as number) ?? 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<never>((_, 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): Promise<ToolResult> => {
+      // Validate path parameter exists and is a string
+      if (!params.path || typeof params.path !== 'string') {
+        return {
+          success: false,
+          error: `Invalid path parameter: expected string, got ${typeof params.path}. Params: ${JSON.stringify(params)}`,
+        }
+      }
+
+      const filePath = params.path as string
+      const offset = (params.offset as number) ?? 0
+      const limit = (params.limit as number) ?? 2000
+
+      try {
+        // SECURITY: Validate path is within working directory
+        const validatedPath = validatePath(filePath, workingDirectory)
+
+        // Debug logging
+        console.log(`[read] Attempting to read file:`, {
+          originalPath: filePath,
+          validatedPath,
+          validatedPathType: typeof validatedPath,
+          workingDirectory
+        })
+
+        let file
+        try {
+          file = Bun.file(validatedPath)
+        } catch (bunError) {
+          return {
+            success: false,
+            error: `Bun.file() failed for '${validatedPath}': ${bunError instanceof Error ? bunError.message : String(bunError)}`,
+          }
+        }
+
+        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) {
+        // Provide detailed error information for debugging
+        const errorMsg = error instanceof Error ? error.message : String(error)
+        return {
+          success: false,
+          error: `Failed to read file '${filePath}': ${errorMsg}`,
+        }
+      }
+    },
+
+    write: async (params): Promise<ToolResult> => {
+      const filePath = params.path as string
+      const content = params.content as string
+
+      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 ${filePath}`,
+        }
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        }
+      }
+    },
+
+    edit: async (params): Promise<ToolResult> => {
+      const filePath = params.path as string
+      const oldString = params.oldString as string
+      const newString = params.newString as string
+      const replaceAll = (params.replaceAll as boolean) ?? 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: ${filePath}`,
+          }
+        }
+
+        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): Promise<ToolResult> => {
+      const pattern = params.pattern as string
+      const cwd = (params.cwd as string) ?? workingDirectory
+
+      try {
+        const glob = new Bun.Glob(pattern)
+        const files: string[] = []
+        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): Promise<ToolResult> => {
+      const pattern = params.pattern as string
+      const include = params.include as string | undefined
+      const cwd = (params.cwd as string) ?? 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): Promise<ToolResult> => {
+      const filePath = params.path as string
+
+      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): Promise<ToolResult> => {
+      const command = params.command as string
+      const args = (params.args as string[]) ?? []
+
+      // Default to /repos if REPOS_PATH is set and no cwd provided
+      const defaultCwd = process.env.REPOS_PATH
+        ? process.env.REPOS_PATH
+        : workingDirectory
+      const cwd = (params.cwd as string) ?? defaultCwd
+
+      try {
+        const gitArgs = ["git", command, ...args]
+        const proc = Bun.spawn(gitArgs, {
+          cwd,
+          stdout: "pipe",
+          stderr: "pipe",
+          env: {
+            ...process.env,
+            // Ensure git uses credentials from mounted config
+            GIT_CONFIG_GLOBAL: "/root/.gitconfig",
+          },
+        })
+
+        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): Promise<ToolResult> => {
+      if (!opts.onActivityExecute) {
+        return {
+          success: false,
+          error: "Activity execution not configured (onActivityExecute callback required)",
+        }
+      }
+
+      try {
+        const templateId = params.templateId as string
+        const variables = (params.variables as Record<string, unknown>) ?? {}
+        const reason = params.reason as string | undefined
+
+        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): Promise<ToolResult> => {
+      if (!opts.onSearchActivities) {
+        return {
+          success: false,
+          error: "Activity search not configured (onSearchActivities callback required)",
+        }
+      }
+
+      try {
+        const category = params.category as string | undefined
+        const verbose = (params.verbose as boolean) ?? 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): Promise<ToolResult> => {
+      if (!opts.onCreateActivity) {
+        return {
+          success: false,
+          error: "Activity creation not configured (onCreateActivity callback required)",
+        }
+      }
+
+      try {
+        const goalDescription = params.goalDescription as string
+        const templateName = params.templateName as string
+        const category = params.category as string
+        const variables = (params.variables as Record<string, unknown>) ?? {}
+
+        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): Promise<ToolResult> => {
+      if (!opts.onImpulseCreate) {
+        return {
+          success: false,
+          error: "Impulse creation not configured (onImpulseCreate callback required)",
+        }
+      }
+
+      try {
+        const id = params.id as string
+        const type = params.type as string
+        const content = params.content as string | undefined
+        const budget = params.budget as number
+        const priority = params.priority as string
+
+        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?: ToolDefinition[]): ToolDefinition[] {
+  const base = Object.values(toolDefinitions)
+  if (extraDefinitions && extraDefinitions.length > 0) {
+    return [...base, ...extraDefinitions]
+  }
+  return base
+}