otherwise-cli 0.1.0

package/src/agent/tools.js

@@ -0,0 +1,4372 @@
+import {
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  existsSync,
+  mkdirSync,
+  lstatSync,
+  realpathSync,
+} from "fs";
+import { execSync, spawn } from "child_process";
+import { homedir, tmpdir } from "os";
+import { join, dirname, resolve, normalize, isAbsolute, relative } from "path";
+import {
+  createScheduledTask,
+  getScheduledTasks,
+  deleteScheduledTask,
+} from "../storage/db.js";
+import cron from "node-cron";
+import {
+  reloadTask,
+  cancelTask,
+  scheduleOneTimeTask,
+  cancelOneTimeTask,
+} from "../scheduler/cron.js";
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+import {
+  getBrowserPage,
+  closeBrowser,
+  isBrowserActive,
+  findElement,
+  extractPageContent,
+  executeActionSequence,
+  fetchHtmlWithBrowser,
+} from "../browser/session.js";
+
+/** Proxy URL for web search requests (fetch + browser). Use WEBSEARCH_PROXY or HTTPS_PROXY. */
+function getWebSearchProxy() {
+  return (
+    process.env.WEBSEARCH_PROXY ||
+    process.env.HTTPS_PROXY ||
+    process.env.HTTP_PROXY ||
+    null
+  );
+}
+
+// ============================================
+// Security Configuration
+// ============================================
+
+/**
+ * Sensitive paths that should NEVER be accessed
+ * These are blocked regardless of sandbox settings
+ */
+const BLOCKED_PATHS = [
+  // SSH keys and credentials
+  "/.ssh/",
+  "/.gnupg/",
+  "/.aws/",
+  "/.azure/",
+  "/.gcloud/",
+  "/.config/gcloud/",
+
+  // System files
+  "/etc/passwd",
+  "/etc/shadow",
+  "/etc/sudoers",
+  "/etc/ssh/",
+
+  // Secrets and tokens
+  "/.npmrc",
+  "/.pypirc",
+  "/.netrc",
+  "/.env",
+  "/credentials",
+  "/secrets/",
+  "/tokens/",
+
+  // Browser data
+  "/.mozilla/",
+  "/.chrome/",
+  "/.config/google-chrome/",
+  "/Library/Keychains/",
+
+  // macOS specific
+  "/Library/Keychains/",
+  "/private/etc/",
+];
+
+/**
+ * Patterns that indicate dangerous commands (regex)
+ * More comprehensive than simple string matching
+ */
+const DANGEROUS_COMMAND_PATTERNS = [
+  // Recursive deletion of root or system directories
+  /rm\s+(-[rfvI]+\s+)*[\/~]\s*$/i,
+  /rm\s+(-[rfvI]+\s+)*\/\s/i,
+  /rm\s+(-[rfvI]+\s+)*\/\*/i,
+  /rm\s+(-[rfvI]+\s+)*~\//i,
+
+  // Format/destroy disks
+  /mkfs/i,
+  /dd\s+.*of\s*=\s*\/dev\//i,
+  /wipefs/i,
+  /fdisk/i,
+  /parted/i,
+
+  // Fork bomb
+  /:\(\)\s*\{/,
+  /\.\s*\/dev\/null/,
+
+  // System modification
+  /chmod\s+(-[rwxR]+\s+)*777\s+\//i,
+  /chown\s+.*\/$/i,
+
+  // Dangerous redirections
+  />\s*\/dev\/sd/i,
+  />\s*\/dev\/nv/i,
+  />\s*\/etc\//i,
+
+  // Privilege escalation attempts
+  /sudo\s+su/i,
+  /sudo\s+-i/i,
+  /sudo\s+bash/i,
+  /sudo\s+sh/i,
+
+  // Network attacks
+  /curl\s+.*\|\s*(sudo\s+)?bash/i,
+  /wget\s+.*\|\s*(sudo\s+)?bash/i,
+  /curl\s+.*\|\s*(sudo\s+)?sh/i,
+  /wget\s+.*\|\s*(sudo\s+)?sh/i,
+
+  // Python/Ruby/Node one-liners for system commands
+  /python[23]?\s+-c\s+["']import\s+os;?\s*os\.(system|popen|exec)/i,
+  /ruby\s+-e\s+["'`].*system/i,
+  /node\s+-e\s+["'`].*exec/i,
+
+  // Encoded command execution
+  /base64\s+-d.*\|.*bash/i,
+  /echo\s+.*\|\s*base64\s+-d\s*\|/i,
+
+  // Modifying shell configs
+  />\s*~\/\.(bashrc|zshrc|profile|bash_profile)/i,
+  /echo\s+.*>>\s*~\/\.(bashrc|zshrc|profile)/i,
+
+  // Cron manipulation
+  /crontab\s+-r/i,
+  /rm\s+.*cron/i,
+];
+
+/**
+ * Default timeout for tool execution (ms)
+ */
+const DEFAULT_TOOL_TIMEOUT = 30000;
+
+// ============================================
+// Working Directory State Management
+// ============================================
+
+/**
+ * Current working directory for the agent session
+ * This persists across tool calls within a session
+ */
+let currentWorkingDirectory = process.cwd();
+
+/**
+ * Get the current working directory
+ * @returns {string} - The current working directory path
+ */
+export function getAgentWorkingDirectory() {
+  return currentWorkingDirectory;
+}
+
+/**
+ * Set the current working directory
+ * @param {string} path - The new working directory path
+ */
+export function setAgentWorkingDirectory(path) {
+  currentWorkingDirectory = path;
+}
+
+/**
+ * Reset working directory to process cwd (for new sessions)
+ */
+export function resetAgentWorkingDirectory() {
+  currentWorkingDirectory = process.cwd();
+}
+
+/**
+ * Per-tool timeout overrides
+ */
+const TOOL_TIMEOUTS = {
+  execute_command: 30000,
+  web_search: 25000,
+  fetch_url: 15000,
+  browser_navigate: 45000, // Increased for retry logic
+  browser_click: 25000, // Element detection tries multiple strategies (2s each) + click action
+  browser_type: 25000, // Element detection + typing
+  browser_read: 10000,
+  browser_screenshot: 15000,
+  browser_launch: 20000, // Browser startup can be slow
+  browser_close: 5000,
+  browser_interact: 120000, // Composite tool: can execute multiple actions (2 min max)
+  read_file: 5000,
+  write_file: 5000,
+  list_directory: 5000,
+  search_files: 15000,
+};
+
+/** Max chars of page content to auto-append after navigate/click/type (avoids extra browser_read round-trip). */
+const BROWSER_AUTO_READ_MAX_LENGTH = 6000;
+
+/**
+ * Extract page content and truncate for inclusion in tool output.
+ * Returns empty string on error so the main result is still useful.
+ */
+async function getTruncatedPageContent(
+  page,
+  maxLen = BROWSER_AUTO_READ_MAX_LENGTH,
+) {
+  try {
+    const content = await extractPageContent(page);
+    if (content.length <= maxLen) return content;
+    return (
+      content.substring(0, maxLen) +
+      "\n\n... (truncated; use browser_read for full content)"
+    );
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Retry configuration for operations that may fail transiently
+ */
+const RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 10000,
+};
+
+/**
+ * Sleep for a specified duration
+ * @param {number} ms - Milliseconds to sleep
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============================================
+// Search Query Refinement & Date Injection
+// ============================================
+
+const TIME_SENSITIVE_PATTERNS = [
+  /\b(weather|forecast|temperature|temp)\b/i,
+  /\b(today|tonight|tomorrow|this week|this weekend|right now|currently)\b/i,
+  /\b(latest|breaking|recent|current|live)\b/i,
+  /\b(stock price|share price|market|trading)\b/i,
+  /\b(score|scores|game|match|playing)\b/i,
+  /\b(open now|hours|is .+ open|closed)\b/i,
+  /\b(news|headlines)\b/i,
+  /\b(price of|cost of|how much)\b/i,
+];
+
+const HAS_DATE_PATTERN =
+  /\b(20\d{2}|january|february|march|april|may|june|july|august|september|october|november|december|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\b/i;
+
+function refineSearchQuery(query) {
+  const trimmed = (query || "").trim();
+  if (!trimmed) return trimmed;
+
+  const isTimeSensitive = TIME_SENSITIVE_PATTERNS.some((p) => p.test(trimmed));
+  if (!isTimeSensitive) return trimmed;
+
+  if (HAS_DATE_PATTERN.test(trimmed)) return trimmed;
+
+  const now = new Date();
+  const month = now.toLocaleString("en-US", { month: "long" });
+  const year = now.getFullYear();
+  return `${trimmed} ${month} ${year}`;
+}
+
+// ============================================
+// Search Result Cache (TTL-based)
+// ============================================
+
+class SearchCache {
+  constructor(ttlMs = 5 * 60 * 1000, maxEntries = 50) {
+    this._cache = new Map();
+    this._ttl = ttlMs;
+    this._max = maxEntries;
+  }
+  _normalizeKey(query) {
+    return (query || "").trim().toLowerCase().replace(/\s+/g, " ");
+  }
+  get(query) {
+    const key = this._normalizeKey(query);
+    const entry = this._cache.get(key);
+    if (!entry) return null;
+    if (Date.now() - entry.ts > this._ttl) {
+      this._cache.delete(key);
+      return null;
+    }
+    return entry.data;
+  }
+  set(query, data) {
+    const key = this._normalizeKey(query);
+    if (this._cache.size >= this._max) {
+      const oldest = this._cache.keys().next().value;
+      this._cache.delete(oldest);
+    }
+    this._cache.set(key, { data, ts: Date.now() });
+  }
+}
+
+const searchCache = new SearchCache();
+
+/**
+ * Execute a function with exponential backoff retry
+ * @param {Function} fn - Async function to execute
+ * @param {object} options - Retry options
+ * @returns {Promise<any>} - Result of the function
+ */
+async function withRetry(fn, options = {}) {
+  const maxRetries = options.maxRetries || RETRY_CONFIG.maxRetries;
+  const baseDelay = options.baseDelayMs || RETRY_CONFIG.baseDelayMs;
+  const maxDelay = options.maxDelayMs || RETRY_CONFIG.maxDelayMs;
+  const retryOn = options.retryOn || (() => true); // Default: retry on all errors
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+
+      // Check if we should retry this error
+      if (!retryOn(err) || attempt === maxRetries) {
+        throw err;
+      }
+
+      // Calculate delay with exponential backoff and jitter
+      const delay = Math.min(
+        baseDelay * Math.pow(2, attempt) + Math.random() * 1000,
+        maxDelay,
+      );
+
+      console.log(
+        `[Retry] Attempt ${attempt + 1} failed: ${err.message}. Retrying in ${Math.round(delay)}ms...`,
+      );
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+// ============================================
+// Memory Search Utilities
+// ============================================
+
+/**
+ * Cosine similarity between two vectors
+ * @param {Array<number>} a - First vector
+ * @param {Array<number>} b - Second vector
+ * @returns {number} Similarity score between 0 and 1
+ */
+function cosineSimilarity(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dotProduct = 0,
+    normA = 0,
+    normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+/**
+ * Generate embedding for a query string using OpenAI or Google API
+ * @param {string} query - Text to embed
+ * @param {object} config - Config with API keys
+ * @returns {Array<number>|null} Embedding vector or null if unavailable
+ */
+async function generateQueryEmbedding(query, config) {
+  // Try OpenAI first
+  if (config.apiKeys?.openai) {
+    try {
+      const response = await fetch("https://api.openai.com/v1/embeddings", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${config.apiKeys.openai}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: "text-embedding-3-small",
+          input: query,
+        }),
+      });
+      if (response.ok) {
+        const data = await response.json();
+        return data.data[0].embedding;
+      }
+    } catch (err) {
+      console.warn("[Memory] OpenAI embedding failed:", err.message);
+    }
+  }
+
+  // Fallback to Google
+  if (config.apiKeys?.google) {
+    try {
+      const response = await fetch(
+        `https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=${config.apiKeys.google}`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            content: { parts: [{ text: query }] },
+          }),
+        },
+      );
+      if (response.ok) {
+        const data = await response.json();
+        return data.embedding.values;
+      }
+    } catch (err) {
+      console.warn("[Memory] Google embedding failed:", err.message);
+    }
+  }
+
+  return null; // No embedding available, will use text search
+}
+
+/**
+ * Tool definitions with metadata and execution functions
+ */
+export const TOOLS = {
+  // ============================================
+  // Filesystem Tools
+  // ============================================
+
+  read_file: {
+    description: "Read the contents of a file",
+    parameters: {
+      path: {
+        type: "string",
+        description: "Path to the file to read",
+        required: true,
+      },
+    },
+    execute: async ({ path: inputPath }, config) => {
+      try {
+        const resolvedPath = resolvePath(inputPath);
+
+        // Check for path traversal attempts
+        if (hasPathTraversal(inputPath, resolvedPath)) {
+          return `Error: Path traversal detected`;
+        }
+
+        // Check permissions (throws on failure)
+        checkReadPermission(resolvedPath, config);
+
+        if (!existsSync(resolvedPath)) {
+          return `Error: File not found: ${inputPath}`;
+        }
+
+        const content = readFileSync(resolvedPath, "utf-8");
+        return content;
+      } catch (err) {
+        return `Error reading file: ${err.message}`;
+      }
+    },
+  },
+
+  write_file: {
+    description: "Write content to a file (creates directories if needed)",
+    parameters: {
+      path: {
+        type: "string",
+        description: "Path to the file to write",
+        required: true,
+      },
+      content: {
+        type: "string",
+        description: "Content to write",
+        required: true,
+      },
+    },
+    execute: async ({ path: inputPath, content }, config, snapshotFn) => {
+      try {
+        const resolvedPath = resolvePath(inputPath);
+
+        // Check for path traversal attempts
+        if (hasPathTraversal(inputPath, resolvedPath)) {
+          return `Error: Path traversal detected`;
+        }
+
+        // Check permissions (throws on failure)
+        checkWritePermission(resolvedPath, config);
+
+        // Also check the directory for write permission
+        const dir = dirname(resolvedPath);
+        checkWritePermission(dir, config);
+
+        // Whether we will create the parent dir (for undo on regeneration)
+        const dirExisted = existsSync(dir);
+        const createdDir = dirExisted ? null : dir;
+
+        // Capture snapshot BEFORE writing (for undo on regeneration)
+        if (snapshotFn) {
+          const fileExisted = existsSync(resolvedPath);
+          let oldContent = null;
+          if (fileExisted) {
+            try {
+              oldContent = readFileSync(resolvedPath, "utf-8");
+            } catch (readErr) {
+              // If we can't read (e.g., binary file), skip snapshotting
+              console.warn(
+                "[write_file] Could not read file for snapshot:",
+                readErr.message,
+              );
+            }
+          }
+          snapshotFn({
+            path: resolvedPath,
+            existed: fileExisted,
+            content: oldContent,
+            createdDir,
+          });
+        }
+
+        // Create directory if it doesn't exist
+        if (!dirExisted) {
+          mkdirSync(dir, { recursive: true });
+        }
+
+        writeFileSync(resolvedPath, content, "utf-8");
+        return { path: inputPath, content };
+      } catch (err) {
+        return `Error writing file: ${err.message}`;
+      }
+    },
+  },
+
+  edit_file: {
+    description:
+      "Edit a file by replacing specific text. Use this for precise edits instead of rewriting entire files.",
+    parameters: {
+      path: {
+        type: "string",
+        description: "Path to the file to edit",
+        required: true,
+      },
+      old_string: {
+        type: "string",
+        description:
+          "The exact text to find and replace (must match exactly including whitespace)",
+        required: true,
+      },
+      new_string: {
+        type: "string",
+        description: "The text to replace it with",
+        required: true,
+      },
+      replace_all: {
+        type: "boolean",
+        description:
+          "Replace all occurrences (default: false, only replaces first match)",
+        required: false,
+      },
+    },
+    execute: async (
+      { path: inputPath, old_string, new_string, replace_all = false },
+      config,
+      snapshotFn,
+    ) => {
+      try {
+        const resolvedPath = resolvePath(inputPath);
+
+        // Check for path traversal attempts
+        if (hasPathTraversal(inputPath, resolvedPath)) {
+          return `Error: Path traversal detected`;
+        }
+
+        // Check permissions (throws on failure)
+        checkReadPermission(resolvedPath, config);
+        checkWritePermission(resolvedPath, config);
+
+        if (!existsSync(resolvedPath)) {
+          return `Error: File not found: ${inputPath}`;
+        }
+
+        // Read current content
+        const originalContent = readFileSync(resolvedPath, "utf-8");
+
+        // Check if old_string exists in file
+        if (!originalContent.includes(old_string)) {
+          // Provide helpful error with context
+          const lines = originalContent.split("\n");
+          const preview = lines.slice(0, 10).join("\n");
+          return `Error: Could not find the text to replace in ${inputPath}.\n\nSearched for:\n---\n${old_string.substring(0, 200)}${old_string.length > 200 ? "..." : ""}\n---\n\nFile preview (first 10 lines):\n---\n${preview}\n---\n\nMake sure the old_string matches exactly, including whitespace and indentation.`;
+        }
+
+        // Capture snapshot BEFORE writing (for undo on regeneration)
+        if (snapshotFn) {
+          snapshotFn({
+            path: resolvedPath,
+            existed: true, // edit_file only works on existing files
+            content: originalContent,
+          });
+        }
+
+        // Count occurrences
+        const occurrences = (
+          originalContent.match(new RegExp(escapeRegExp(old_string), "g")) || []
+        ).length;
+
+        // Perform replacement
+        let newContent;
+        if (replace_all) {
+          newContent = originalContent.split(old_string).join(new_string);
+        } else {
+          // Replace only first occurrence
+          const index = originalContent.indexOf(old_string);
+          newContent =
+            originalContent.substring(0, index) +
+            new_string +
+            originalContent.substring(index + old_string.length);
+        }
+
+        // Write the modified content
+        writeFileSync(resolvedPath, newContent, "utf-8");
+
+        // Generate a simple diff for the result
+        const replacedCount = replace_all ? occurrences : 1;
+        const remainingOccurrences = occurrences - replacedCount;
+
+        // Create a unified diff-like output
+        const diffResult = generateSimpleDiff(
+          old_string,
+          new_string,
+          inputPath,
+        );
+
+        let resultMessage = `Successfully edited ${inputPath}\n`;
+        resultMessage += `Replaced ${replacedCount} occurrence${replacedCount > 1 ? "s" : ""}`;
+        if (remainingOccurrences > 0) {
+          resultMessage += ` (${remainingOccurrences} more occurrence${remainingOccurrences > 1 ? "s" : ""} remain)`;
+        }
+        resultMessage += `\n\n${diffResult}`;
+
+        return resultMessage;
+      } catch (err) {
+        return `Error editing file: ${err.message}`;
+      }
+    },
+  },
+
+  list_directory: {
+    description: "List files and directories in a path",
+    parameters: {
+      path: {
+        type: "string",
+        description: "Directory path to list",
+        required: true,
+      },
+    },
+    execute: async ({ path: inputPath }, config) => {
+      try {
+        const resolvedPath = resolvePath(inputPath);
+
+        // Check for path traversal attempts
+        if (hasPathTraversal(inputPath, resolvedPath)) {
+          return `Error: Path traversal detected`;
+        }
+
+        // Check permissions (throws on failure)
+        checkReadPermission(resolvedPath, config);
+
+        if (!existsSync(resolvedPath)) {
+          return `Error: Directory not found: ${inputPath}`;
+        }
+
+        const entries = readdirSync(resolvedPath);
+        const detailed = entries.map((name) => {
+          const fullPath = join(resolvedPath, name);
+          try {
+            const stat = statSync(fullPath);
+            return {
+              name,
+              type: stat.isDirectory() ? "directory" : "file",
+              size: stat.isFile() ? stat.size : null,
+            };
+          } catch {
+            return { name, type: "unknown" };
+          }
+        });
+
+        // Filter out entries that would lead to blocked paths
+        const filtered = detailed.filter((entry) => {
+          const fullPath = join(resolvedPath, entry.name);
+          return !isBlockedPath(fullPath);
+        });
+
+        return JSON.stringify(filtered, null, 2);
+      } catch (err) {
+        return `Error listing directory: ${err.message}`;
+      }
+    },
+  },
+
+  search_files: {
+    description: "Search for files by name pattern",
+    parameters: {
+      query: {
+        type: "string",
+        description: "Search pattern (supports * wildcard)",
+        required: true,
+      },
+      path: {
+        type: "string",
+        description: "Directory to search in (default: current)",
+        required: false,
+      },
+      maxdepth: {
+        type: "number",
+        description: "Maximum directory depth to search (default: 5, max: 10)",
+        required: false,
+      },
+    },
+    execute: async ({ query, path: inputPath, maxdepth }, config) => {
+      try {
+        const searchPath = resolvePath(inputPath || ".");
+
+        // Check for path traversal attempts
+        if (inputPath && hasPathTraversal(inputPath, searchPath)) {
+          return `Error: Path traversal detected`;
+        }
+
+        // Check permissions (throws on failure)
+        checkReadPermission(searchPath, config);
+
+        // Sanitize query to prevent command injection
+        // Only allow alphanumeric, dots, underscores, hyphens, and wildcards
+        const sanitizedQuery = query.replace(/[^a-zA-Z0-9._\-*?]/g, "");
+        if (sanitizedQuery !== query) {
+          console.warn(
+            `[search_files] Query sanitized: "${query}" -> "${sanitizedQuery}"`,
+          );
+        }
+
+        // Limit maxdepth to prevent timeout on large directory trees
+        const depth = Math.min(Math.max(1, maxdepth || 5), 10);
+
+        // Use find command with sanitized input and depth limit
+        // -maxdepth prevents searching deep nested directories (e.g., node_modules)
+        const timeout = getToolTimeout("search_files");
+        const result = execSync(
+          `find "${searchPath}" -maxdepth ${depth} -name "${sanitizedQuery}" -type f 2>/dev/null | head -50`,
+          { encoding: "utf-8", timeout, killSignal: "SIGKILL" },
+        );
+
+        // Filter results to exclude blocked paths
+        const lines = result
+          .trim()
+          .split("\n")
+          .filter((line) => {
+            return line && !isBlockedPath(line);
+          });
+
+        const resultText =
+          lines.join("\n") || "No files found matching the pattern.";
+        return depth < 10
+          ? `${resultText}\n\n(Searched up to ${depth} levels deep. Use maxdepth parameter to search deeper.)`
+          : resultText;
+      } catch (err) {
+        if (
+          err.killed ||
+          err.signal === "SIGKILL" ||
+          err.code === "ETIMEDOUT"
+        ) {
+          return `Error: Search timed out. Try searching a more specific directory or reducing maxdepth.`;
+        }
+        return `Error searching: ${err.message}`;
+      }
+    },
+  },
+
+  // ============================================
+  // Shell Tools
+  // ============================================
+
+  set_working_directory: {
+    description:
+      "Change the current working directory for future commands. This persists across tool calls.",
+    parameters: {
+      path: {
+        type: "string",
+        description:
+          "Path to the directory to switch to (absolute or relative)",
+        required: true,
+      },
+    },
+    execute: async ({ path: inputPath }, config) => {
+      try {
+        // Resolve the path (handles ~, relative paths, etc.)
+        let resolvedPath;
+        if (inputPath.startsWith("~")) {
+          resolvedPath = join(homedir(), inputPath.slice(1));
+        } else if (isAbsolute(inputPath)) {
+          resolvedPath = normalize(inputPath);
+        } else {
+          // Relative path - resolve from current working directory
+          resolvedPath = resolve(currentWorkingDirectory, inputPath);
+        }
+
+        // Check if path exists and is a directory
+        if (!existsSync(resolvedPath)) {
+          return `Error: Directory not found: ${inputPath}`;
+        }
+
+        const stat = statSync(resolvedPath);
+        if (!stat.isDirectory()) {
+          return `Error: Path is not a directory: ${inputPath}`;
+        }
+
+        // Check for blocked paths
+        if (isBlockedPath(resolvedPath)) {
+          return `Error: Access denied - cannot switch to sensitive directory`;
+        }
+
+        // Check read permission
+        checkReadPermission(resolvedPath, config);
+
+        // Update the working directory state
+        const previousDir = currentWorkingDirectory;
+        currentWorkingDirectory = resolvedPath;
+
+        return `Changed working directory:\n  From: ${previousDir}\n  To: ${resolvedPath}\n\nFuture commands will run in this directory.`;
+      } catch (err) {
+        return `Error changing directory: ${err.message}`;
+      }
+    },
+  },
+
+  get_working_directory: {
+    description: "Get the current working directory",
+    parameters: {},
+    execute: async (params, config) => {
+      return `Current working directory: ${currentWorkingDirectory}`;
+    },
+  },
+
+  execute_command: {
+    description: "Execute a shell command in the current working directory",
+    parameters: {
+      command: {
+        type: "string",
+        description: "Command to execute",
+        required: true,
+      },
+    },
+    execute: async ({ command }, config, shellUndoFn) => {
+      if (!config.permissions?.shell) {
+        return "Error: Shell commands are disabled in configuration.";
+      }
+
+      // Validate command against dangerous patterns
+      const validation = validateCommand(command);
+      if (!validation.valid) {
+        console.warn(
+          `[execute_command] Blocked: ${validation.reason} - Command: ${command.substring(0, 100)}`,
+        );
+        return `Error: This command is blocked for safety reasons (${validation.reason}).`;
+      }
+
+      try {
+        const timeout = getToolTimeout("execute_command");
+        const result = execSync(command, {
+          encoding: "utf-8",
+          timeout,
+          maxBuffer: 1024 * 1024, // 1MB output limit
+          cwd: currentWorkingDirectory, // Use the agent's working directory
+          // Run in a restricted environment
+          env: {
+            ...process.env,
+            // Prevent some shell behaviors
+            HISTFILE: "/dev/null",
+            HISTSIZE: "0",
+          },
+        });
+        // Record reversible command for undo on regeneration (Strategy 1)
+        if (shellUndoFn) {
+          const entry = parseReversibleCommand(command);
+          if (entry) {
+            shellUndoFn(entry);
+          }
+        }
+        return result || "(Command completed with no output)";
+      } catch (err) {
+        // Check if it was a timeout
+        if (err.killed) {
+          return `Error: Command timed out after ${getToolTimeout("execute_command") / 1000} seconds`;
+        }
+        return `Command failed: ${err.message}\n${err.stderr || ""}`;
+      }
+    },
+  },
+
+  // ============================================
+  // Email Tools (MyMX for receiving, Resend for sending)
+  // ============================================
+
+  check_email: {
+    description:
+      "List recently received emails. With MyMX, emails are automatically received via webhooks and stored as chats.",
+    parameters: {
+      limit: {
+        type: "number",
+        description: "Max emails to show (default: 10)",
+        required: false,
+      },
+    },
+    execute: async ({ limit = 10 }, config) => {
+      if (!config.permissions?.email) {
+        return "Error: Email access is disabled in configuration.";
+      }
+
+      try {
+        const { checkEmail } = await import("../email/client.js");
+        return await checkEmail(config);
+      } catch (err) {
+        return err.message;
+      }
+    },
+  },
+
+  send_email: {
+    description:
+      "Send an email via Resend API. Requires Resend to be configured in Settings → Email Integration.",
+    parameters: {
+      to: {
+        type: "string",
+        description: "Recipient email address",
+        required: true,
+      },
+      subject: { type: "string", description: "Email subject", required: true },
+      body: {
+        type: "string",
+        description: "Email body content (plain text)",
+        required: true,
+      },
+    },
+    execute: async ({ to, subject, body }, config) => {
+      if (!config.permissions?.email) {
+        return "Error: Email access is disabled in configuration.";
+      }
+
+      try {
+        const { sendEmail } = await import("../email/client.js");
+        const result = await sendEmail(config, to, subject, body);
+        return `✅ Email sent successfully to ${to}\nMessage ID: ${result.messageId}`;
+      } catch (err) {
+        return `Error sending email: ${err.message}`;
+      }
+    },
+  },
+
+  // ============================================
+  // Scheduling Tools
+  // ============================================
+
+  schedule_task: {
+    description:
+      "Schedule a RECURRING task at specified times (cron syntax). For one-time 'in X minutes', use schedule_task_once instead.",
+    parameters: {
+      cron_expression: {
+        type: "string",
+        description:
+          'Cron expression: minute hour day month weekday (e.g. "0 9 * * *" = 9am daily, "*/15 * * * *" = every 15 min)',
+        required: true,
+      },
+      task_description: {
+        type: "string",
+        description: "What the task should do",
+        required: true,
+      },
+    },
+    execute: async ({ cron_expression, task_description }, config) => {
+      try {
+        if (!cron.validate(cron_expression)) {
+          return `Error: Invalid cron expression "${cron_expression}". Use format: minute hour day month weekday (e.g. "0 9 * * *" for 9am daily).`;
+        }
+        const id = createScheduledTask(cron_expression, task_description);
+        const ok = reloadTask(id, config);
+        if (!ok) {
+          return `Task was saved (ID: ${id}) but failed to schedule. Check server logs.`;
+        }
+        return `Recurring task scheduled (ID: ${id}). Will run according to: ${cron_expression}`;
+      } catch (err) {
+        return `Error scheduling task: ${err.message}`;
+      }
+    },
+  },
+
+  schedule_task_once: {
+    description:
+      "Schedule a ONE-TIME task to run once after N minutes. Use this for 'in 5 minutes' or 'run once in 10 minutes'. Does not persist if CLI restarts.",
+    parameters: {
+      run_in_minutes: {
+        type: "number",
+        description:
+          "How many minutes from now to run the task (e.g. 5 for 'in 5 minutes')",
+        required: true,
+      },
+      task_description: {
+        type: "string",
+        description: "What the task should do",
+        required: true,
+      },
+    },
+    execute: async ({ run_in_minutes, task_description }, config) => {
+      try {
+        const minutes = Math.max(
+          1,
+          Math.min(1440, Number(run_in_minutes) || 1),
+        ); // 1 min to 24h
+        const id = scheduleOneTimeTask(task_description, minutes, config);
+        return `One-time task scheduled (ID: ${id}). Will run once in ${minutes} minute(s).`;
+      } catch (err) {
+        return `Error scheduling one-time task: ${err.message}`;
+      }
+    },
+  },
+
+  list_scheduled_tasks: {
+    description: "List all scheduled tasks",
+    parameters: {},
+    execute: async (params, config) => {
+      try {
+        const tasks = getScheduledTasks(false);
+        if (tasks.length === 0) {
+          return "No scheduled tasks.";
+        }
+        return JSON.stringify(tasks, null, 2);
+      } catch (err) {
+        return `Error listing tasks: ${err.message}`;
+      }
+    },
+  },
+
+  cancel_task: {
+    description: "Cancel a scheduled task",
+    parameters: {
+      task_id: {
+        type: "number",
+        description: "ID of the task to cancel",
+        required: true,
+      },
+    },
+    execute: async ({ task_id }, config) => {
+      try {
+        // Stop the running cron job first
+        cancelTask(task_id);
+        // Then remove from database
+        deleteScheduledTask(task_id);
+        return `Task ${task_id} cancelled successfully.`;
+      } catch (err) {
+        return `Error cancelling task: ${err.message}`;
+      }
+    },
+  },
+
+  // ============================================
+  // Web Tools
+  // ============================================
+
+  web_search: {
+    description:
+      "Search the web for current information. Returns titles, URLs, summaries, and enriched page content for top results. For comprehensive data (like earnings reports, event lists), use numResults=10+ and consider making multiple searches with different date/keyword variations.",
+    parameters: {
+      query: {
+        type: "string",
+        description:
+          "Search query - be specific with dates, company names, or keywords",
+        required: true,
+      },
+      numResults: {
+        type: "number",
+        description:
+          "Number of results (default: 8, max: 15). Use higher values for comprehensive data gathering.",
+        required: false,
+      },
+    },
+    execute: async ({ query, numResults = 8 }, config) => {
+      try {
+        const maxResults = Math.min(numResults, 15);
+
+        // Refine query with date injection for time-sensitive searches
+        const refinedQuery = refineSearchQuery(query);
+        if (refinedQuery !== query) {
+          console.log("[WebSearch] Refined query:", refinedQuery);
+        }
+
+        // Check cache first
+        const cacheKey = `${refinedQuery}:${maxResults}`;
+        const cached = searchCache.get(cacheKey);
+        if (cached) {
+          console.log("[WebSearch] Cache hit for:", refinedQuery);
+          return cached;
+        }
+
+        // Try backend route if available (unified search with Exa/Tavily/Marginalia)
+        const backendUrl = config?.remote?.backendUrl;
+        let results = null;
+        if (backendUrl) {
+          try {
+            const resp = await fetchWithTimeout(
+              `${backendUrl.replace(/\/$/, "")}/api/web-search`,
+              {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                  query: refinedQuery,
+                  numResults: maxResults,
+                  maxPages: maxResults,
+                  enrichTop: Math.min(3, maxResults),
+                }),
+              },
+              12000,
+            );
+            const data = await resp.json();
+            if (data.success && data.pages?.length) {
+              results = data.pages.map((p) => ({
+                url: p.url,
+                title: p.title || p.searchTitle || "",
+                snippet: p.searchSnippet || p.excerpt || "",
+                source: p.source || "",
+                content: p.content || p.excerpt || "",
+                engines: p.engines || [],
+              }));
+              console.log(
+                "[WebSearch] Backend returned",
+                results.length,
+                "enriched results",
+              );
+            }
+          } catch (e) {
+            console.log(
+              "[WebSearch] Backend unavailable, falling back to direct scraping:",
+              e?.message,
+            );
+          }
+        }
+
+        // Fallback to direct scraping if backend unavailable or returned nothing
+        if (!results || results.length === 0) {
+          results = await performWebSearch(refinedQuery, maxResults);
+        }
+
+        if (results.length === 0) {
+          return (
+            `No results found for: "${query}"\n\nSuggestions:\n` +
+            `1. Try more specific keywords or add dates (e.g., "January 2026")\n` +
+            `2. Try alternative sources (e.g., "earnings calendar site:yahoo.com")\n` +
+            `3. Break down the query into smaller parts`
+          );
+        }
+
+        // Auto-enrich top 3 results with page content if not already enriched
+        const enrichCount = Math.min(3, results.length);
+        const enrichPromises = [];
+        for (let i = 0; i < enrichCount; i++) {
+          const r = results[i];
+          if (r.content && r.content.length > 200) continue;
+          enrichPromises.push(
+            fetchUrlContent(r.url, 8000)
+              .then((content) => {
+                if (content && content.length > 100) {
+                  r.content = content.slice(0, 4000);
+                  if (!r.snippet || r.snippet.length < 50) {
+                    r.snippet = extractBestSnippet(content, refinedQuery, 400);
+                  }
+                }
+              })
+              .catch(() => {}),
+          );
+        }
+        if (enrichPromises.length > 0) {
+          await Promise.allSettled(enrichPromises);
+        }
+
+        // Fix empty snippets from enriched content
+        for (const r of results) {
+          if ((!r.snippet || r.snippet.length < 20) && r.content) {
+            r.snippet = extractBestSnippet(
+              r.content,
+              refinedQuery,
+              400,
+            );
+          }
+        }
+
+        // Format results with enriched content
+        let output = `Search results for "${query}" (${results.length} results):\n\n`;
+        output += results
+          .map((r, i) => {
+            let entry = `${i + 1}. ${r.title}\n   Source: ${r.source}\n   URL: ${r.url}\n   Summary: ${r.snippet || "No summary available"}`;
+            if (i < enrichCount && r.content && r.content.length > 200) {
+              entry += `\n   Content preview: ${r.content.slice(0, 1500)}`;
+            }
+            return entry;
+          })
+          .join("\n\n");
+
+        if (
+          query.toLowerCase().includes("earnings") ||
+          query.toLowerCase().includes("quarterly") ||
+          query.toLowerCase().includes("reports") ||
+          query.toLowerCase().includes("calendar")
+        ) {
+          output +=
+            "\n\n💡 TIP: For complete earnings/calendar data, consider:\n";
+          output +=
+            '- Searching for specific dates (e.g., "earnings January 27 2026")\n';
+          output +=
+            '- Using financial aggregator sites in your query (e.g., "site:yahoo.com/calendar" or "site:zacks.com")\n';
+          output += "- Fetching promising URLs for detailed company lists\n";
+          output += "- Making multiple searches for different days of the week";
+        }
+
+        // Cache the result
+        searchCache.set(cacheKey, output);
+
+        return output;
+      } catch (err) {
+        return `Error searching: ${err.message}\n\nTIP: Try rephrasing your query or breaking it into smaller parts.`;
+      }
+    },
+  },
+
+  fetch_url: {
+    description:
+      "Fetch full text content from a URL. Use this to get detailed data from earnings calendars, company lists, or news articles. Extracts and formats the text content.",
+    parameters: {
+      url: {
+        type: "string",
+        description:
+          "URL to fetch - works best with news sites, financial data pages, and text-heavy content",
+        required: true,
+      },
+    },
+    execute: async ({ url }, config) => {
+      try {
+        const content = await fetchUrlContent(url, 15000); // Slightly longer timeout
+
+        if (!content || content.length < 100) {
+          return (
+            `No substantial content extracted from URL.\n\n` +
+            `This might happen if:\n` +
+            `1. The page requires JavaScript to render content\n` +
+            `2. The site blocks automated access\n` +
+            `3. The content is behind a login\n\n` +
+            `TIP: Try web_search for related content from other sources.`
+          );
+        }
+
+        // Add summary of content length
+        const wordCount = content.split(/\s+/).length;
+        return (
+          `Fetched content from: ${url}\n` +
+          `Content length: ~${wordCount} words\n\n` +
+          `---\n\n${content}`
+        );
+      } catch (err) {
+        return (
+          `Error fetching URL: ${err.message}\n\n` +
+          `TIP: This site may block automated access. Try:\n` +
+          `1. web_search for similar content from other sources\n` +
+          `2. A different URL from the search results`
+        );
+      }
+    },
+  },
+
+  // ============================================
+  // Browser Control Tools
+  // ============================================
+
+  browser_launch: {
+    description:
+      "Launch a browser for interactive web navigation. Call this before using other browser tools.",
+    parameters: {
+      headless: {
+        type: "boolean",
+        description: "Run browser invisibly (default: true)",
+        required: false,
+      },
+    },
+    execute: async ({ headless }, config) => {
+      try {
+        // Override config headless setting if parameter provided
+        const browserConfig = { ...config };
+        if (headless !== undefined) {
+          browserConfig.browserHeadless = headless;
+        }
+
+        const page = await getBrowserPage(browserConfig);
+        return `Browser launched successfully. Ready for navigation.`;
+      } catch (err) {
+        return `Error launching browser: ${err.message}`;
+      }
+    },
+  },
+
+  browser_navigate: {
+    description:
+      "Navigate the browser to a URL. Automatically retries on network errors with exponential backoff. By default returns page content (title, URL, interactive elements, text) so you often don't need a separate browser_read; use readAfter: false to skip.",
+    parameters: {
+      url: {
+        type: "string",
+        description: "URL to navigate to",
+        required: true,
+      },
+      readAfter: {
+        type: "boolean",
+        description:
+          "Include page content in the result after navigation (default: true). Set false to only get title/URL.",
+        required: false,
+      },
+    },
+    execute: async ({ url, readAfter = true }, config) => {
+      // Ensure URL has protocol
+      let fullUrl = url;
+      if (!url.startsWith("http://") && !url.startsWith("https://")) {
+        fullUrl = "https://" + url;
+      }
+
+      // Check for commonly blocked sites and suggest alternatives
+      const blockedSiteAlternatives = {
+        "nasdaq.com":
+          'TIP: nasdaq.com often blocks automated browsers. Try using web_search for "NASDAQ earnings calendar [date]" or fetch_url with a financial news article instead.',
+        "bloomberg.com":
+          "TIP: bloomberg.com has strict bot detection. Try web_search or fetch_url with a news aggregator.",
+        "linkedin.com":
+          "TIP: linkedin.com blocks automated access. Try web_search for LinkedIn profile information.",
+      };
+
+      const domain = fullUrl
+        .replace(/^https?:\/\//, "")
+        .split("/")[0]
+        .replace("www.", "");
+      const alternative = Object.entries(blockedSiteAlternatives).find(([d]) =>
+        domain.includes(d),
+      );
+
+      try {
+        const page = await getBrowserPage(config);
+
+        // Use retry logic with exponential backoff
+        const result = await withRetry(
+          async (attempt) => {
+            console.log(
+              `[Browser] Navigating to: ${fullUrl} (attempt ${attempt + 1})`,
+            );
+
+            // Try different wait strategies on retries
+            const waitStrategy =
+              attempt === 0
+                ? "domcontentloaded"
+                : attempt === 1
+                  ? "load"
+                  : "networkidle";
+
+            await page.goto(fullUrl, {
+              waitUntil: waitStrategy,
+              timeout: 20000,
+            });
+
+            // Wait a bit for dynamic content (reduced for speed; auto-read still gets content)
+            await page.waitForTimeout(1000);
+
+            const title = await page.title();
+            const currentUrl = page.url();
+
+            // Check for bot/block pages only with specific signals (avoid false positives on normal content)
+            const pageContent = await page.content();
+            const lower = pageContent.toLowerCase();
+            const isBlockPage =
+              lower.includes("checking your browser") ||
+              lower.includes("cf-browser-verification") ||
+              /access\s+denied/i.test(pageContent) ||
+              lower.includes("unusual traffic from your computer") ||
+              lower.includes("please complete the security check") ||
+              lower.includes("g-recaptcha") ||
+              (lower.includes("challenge-platform") &&
+                lower.includes("cloudflare")) ||
+              // Short page with clear block wording (avoids "blocked" in article text)
+              (pageContent.length < 8000 &&
+                /(you have been blocked|your (access|request) (has been )?blocked|blocked (by|from) )/i.test(
+                  pageContent,
+                ));
+            if (isBlockPage) {
+              throw new Error(
+                "Bot detection triggered - site is blocking automated access",
+              );
+            }
+
+            return { title, currentUrl };
+          },
+          {
+            maxRetries: 2,
+            baseDelayMs: 2000,
+            // Retry on network and HTTP2 errors
+            retryOn: (err) => {
+              const retryableErrors = [
+                "ERR_HTTP2",
+                "ERR_CONNECTION",
+                "ERR_TIMED_OUT",
+                "ETIMEDOUT",
+                "ECONNRESET",
+                "Navigation timeout",
+                "net::ERR_",
+              ];
+              return retryableErrors.some((e) => err.message.includes(e));
+            },
+          },
+        );
+
+        let out = `Navigated to: ${result.title}\nURL: ${result.currentUrl}`;
+        if (readAfter) {
+          const content = await getTruncatedPageContent(page);
+          if (content) out += `\n\n--- Page content ---\n${content}`;
+        }
+        return out;
+      } catch (err) {
+        let errorMsg = `Error navigating: ${err.message}`;
+
+        // Add helpful alternative suggestion
+        if (alternative) {
+          errorMsg += `\n\n${alternative[1]}`;
+        } else if (
+          err.message.includes("Bot detection") ||
+          err.message.includes("ERR_HTTP2")
+        ) {
+          errorMsg +=
+            "\n\nThis site may be blocking automated browsers. Consider using:\n";
+          errorMsg +=
+            "1. web_search to find the information from other sources\n";
+          errorMsg +=
+            "2. fetch_url to get content from a news article about this topic\n";
+          errorMsg +=
+            "3. A more specific search query to find direct links to the data";
+        }
+
+        return errorMsg;
+      }
+    },
+  },
+
+  browser_click: {
+    description:
+      'Click an element on the current page. For links, waits for navigation and returns the new URL. By default returns page content so you often don\'t need a separate browser_read. Prefer a[href="/path"] from browser_read output for reliable link clicks. Supports CSS, :has-text(), or link text. Auto-retries with force for overlays.',
+    parameters: {
+      selector: {
+        type: "string",
+        description:
+          "CSS selector, Playwright selector (:has-text(), :text()), text content, or element name to click",
+        required: true,
+      },
+      force: {
+        type: "boolean",
+        description:
+          "Force click even if element is covered or not visible (default: false)",
+        required: false,
+      },
+      readAfter: {
+        type: "boolean",
+        description:
+          "Include page content in the result after click (default: true). Set false to only get title/URL.",
+        required: false,
+      },
+    },
+    execute: async ({ selector, force = false, readAfter = true }, config) => {
+      try {
+        const page = await getBrowserPage(config);
+
+        console.log("[Browser] Clicking:", selector, force ? "(forced)" : "");
+        const element = await findElement(page, selector);
+        await element.scrollIntoViewIfNeeded();
+
+        const clickOptions = { timeout: 5000, force };
+        const performClick = async () => {
+          try {
+            await element.click(clickOptions);
+          } catch (clickErr) {
+            if (!force) {
+              const retryWithForce =
+                clickErr.message.includes("intercepts pointer events") ||
+                clickErr.message.includes("element is not visible") ||
+                clickErr.message.includes("element is outside the viewport");
+              if (retryWithForce) {
+                console.log(
+                  "[Browser] Element not clickable (overlay/not visible/viewport), retrying with force: true",
+                );
+                await element.click({ ...clickOptions, force: true });
+                return;
+              }
+            }
+            throw clickErr;
+          }
+        };
+
+        // If it's a link, wait for navigation so we return the new page and agent knows the click worked
+        const isLink = await element
+          .evaluate(
+            (el) =>
+              el.tagName === "A" &&
+              el.getAttribute("href") &&
+              !el.getAttribute("href").startsWith("#"),
+          )
+          .catch(() => false);
+
+        if (isLink) {
+          await Promise.all([
+            page
+              .waitForNavigation({
+                waitUntil: "domcontentloaded",
+                timeout: 6000,
+              })
+              .catch(() => null),
+            performClick(),
+          ]);
+          const title = await page.title();
+          const url = page.url();
+          let out = `Clicked "${selector}". Navigated to: ${title}\nURL: ${url}`;
+          if (readAfter) {
+            const content = await getTruncatedPageContent(page);
+            if (content) out += `\n\n--- Page content ---\n${content}`;
+          }
+          return out;
+        }
+
+        await performClick();
+        await page.waitForTimeout(400);
+        const title = await page.title();
+        let out = `Clicked "${selector}". Current page: ${title}`;
+        if (readAfter) {
+          const content = await getTruncatedPageContent(page);
+          if (content) out += `\n\n--- Page content ---\n${content}`;
+        }
+        return out;
+      } catch (err) {
+        // Provide more helpful error messages
+        if (err.message.includes("element is not visible")) {
+          return `Error: Element "${selector}" exists but is not visible. Try using force: true or scrolling to the element first.`;
+        }
+        if (err.message.includes("element is outside of the viewport")) {
+          return `Error: Element "${selector}" is outside the viewport. Try scrolling to it first.`;
+        }
+        if (err.message.includes("intercepts pointer events")) {
+          return `Error: Another element is covering "${selector}". Try using force: true or closing any modals/popups first.`;
+        }
+        if (err.message.includes("Could not find element")) {
+          return `Error: ${err.message}\n\nTip: Try using different selector strategies:\n- Text: "Submit" or "button:Submit"\n- Playwright: 'button:has-text("Submit")'\n- CSS: "#submit-btn" or ".submit-button"`;
+        }
+        return `Error clicking element: ${err.message}`;
+      }
+    },
+  },
+
+  browser_type: {
+    description:
+      "Type text into an input field on the current page. By default returns page content after typing so you often don't need a separate browser_read.",
+    parameters: {
+      selector: {
+        type: "string",
+        description:
+          "CSS selector, placeholder text, or label of the input field",
+        required: true,
+      },
+      text: { type: "string", description: "Text to type", required: true },
+      submit: {
+        type: "boolean",
+        description: "Press Enter after typing to submit (default: false)",
+        required: false,
+      },
+      readAfter: {
+        type: "boolean",
+        description:
+          "Include page content in the result after typing (default: true). Set false to only get title.",
+        required: false,
+      },
+    },
+    execute: async (
+      { selector, text, submit = false, readAfter = true },
+      config,
+    ) => {
+      try {
+        const page = await getBrowserPage(config);
+
+        console.log("[Browser] Typing into:", selector);
+        const element = await findElement(page, selector);
+
+        // Clear existing content and type new text
+        await element.fill(text);
+
+        if (submit) {
+          await element.press("Enter");
+          await page.waitForTimeout(1500); // Wait for form submission
+        }
+
+        const title = await page.title();
+        let out = `Typed "${text}" into "${selector}"${submit ? " and submitted" : ""}. Current page: ${title}`;
+        if (readAfter) {
+          const content = await getTruncatedPageContent(page);
+          if (content) out += `\n\n--- Page content ---\n${content}`;
+        }
+        return out;
+      } catch (err) {
+        return `Error typing: ${err.message}`;
+      }
+    },
+  },
+
+  browser_read: {
+    description:
+      'Read and extract full content from the current page. Returns page title, URL, interactive elements (with href for links so you can click via a[href="..."]), and text content. Use when you need full content or when navigate/click/type didn\'t include content (e.g. readAfter was false). For scoped read use a simple CSS selector (e.g. "#section_id"); Playwright selectors like :has-text() are not supported for the selector param.',
+    parameters: {
+      selector: {
+        type: "string",
+        description:
+          "Optional CSS selector to scope content extraction (e.g. #section_id). Standard CSS only; no :has-text() etc.",
+        required: false,
+      },
+    },
+    execute: async ({ selector }, config) => {
+      try {
+        const page = await getBrowserPage(config);
+
+        console.log(
+          "[Browser] Reading page content",
+          selector ? `(selector: ${selector})` : "",
+        );
+        const content = await extractPageContent(page, selector);
+
+        return content;
+      } catch (err) {
+        return `Error reading page: ${err.message}`;
+      }
+    },
+  },
+
+  browser_screenshot: {
+    description: "Take a screenshot of the current page",
+    parameters: {
+      path: {
+        type: "string",
+        description:
+          "File path to save screenshot (default: screenshot.png in current directory)",
+        required: false,
+      },
+      fullPage: {
+        type: "boolean",
+        description: "Capture full scrollable page (default: false)",
+        required: false,
+      },
+    },
+    execute: async ({ path, fullPage = false }, config) => {
+      try {
+        const page = await getBrowserPage(config);
+
+        const screenshotPath = path || `screenshot-${Date.now()}.png`;
+        const resolvedPath = resolve(screenshotPath);
+
+        console.log("[Browser] Taking screenshot:", resolvedPath);
+        await page.screenshot({
+          path: resolvedPath,
+          fullPage,
+        });
+
+        return `Screenshot saved to: ${resolvedPath}`;
+      } catch (err) {
+        return `Error taking screenshot: ${err.message}`;
+      }
+    },
+  },
+
+  browser_close: {
+    description:
+      "Close the browser and free resources. Call when done with browser tasks.",
+    parameters: {},
+    execute: async (params, config) => {
+      try {
+        if (!isBrowserActive()) {
+          return "Browser is not currently running.";
+        }
+
+        await closeBrowser();
+        return "Browser closed successfully.";
+      } catch (err) {
+        return `Error closing browser: ${err.message}`;
+      }
+    },
+  },
+
+  browser_interact: {
+    description: `Execute multiple browser actions in a single call. Reduces latency by batching operations. By default appends final page content so you often don't need a separate browser_read. Use a trailing read action or readAfter for content.
+
+Supported action types:
+- click: { type: "click", selector: "...", force?: boolean, waitForNavigation?: boolean }
+- type: { type: "type", selector: "...", text: "...", clear?: boolean, submit?: boolean, delay?: number }
+- fill: { type: "fill", selector: "...", text: "...", submit?: boolean }
+- wait: { type: "wait", selector?: "...", ms?: number, url?: "...", load?: "domcontentloaded|networkidle" }
+- scroll: { type: "scroll", selector?: "...", direction?: "up|down|top|bottom", amount?: number }
+- hover: { type: "hover", selector: "..." }
+- select: { type: "select", selector: "...", value: "..." }
+- check: { type: "check", selector: "...", uncheck?: boolean }
+- press: { type: "press", key: "Enter|Tab|...", selector?: "..." }
+- navigate: { type: "navigate", url: "...", waitUntil?: "domcontentloaded|networkidle" }
+- read: { type: "read", selector?: "...", maxLength?: number } - Extract page content (use at end of sequence)
+- evaluate: { type: "evaluate", script: "return document.title" }
+- screenshot: { type: "screenshot", path?: "...", fullPage?: boolean }
+
+Each action can have:
+- continueOnError: boolean - If true, continue sequence even if this action fails
+- delayAfter: number - Wait N ms after this action completes
+- waitForNavigation: boolean - For click actions, wait for page navigation to complete`,
+    parameters: {
+      actions: {
+        type: "array",
+        description:
+          "Array of action objects to execute in sequence (can be JSON string or array)",
+        required: true,
+      },
+      readAfter: {
+        type: "boolean",
+        description:
+          "Append final page content to the result after all actions (default: true). Set false to only get URL/title and action results.",
+        required: false,
+      },
+    },
+    execute: async (args, config) => {
+      const readAfter = args.readAfter !== false;
+      // Parse actions from args - handle both direct array and JSON string
+      let actions = args.actions;
+
+      // If args itself is a string, try to parse it
+      if (typeof args === "string") {
+        try {
+          const parsed = JSON.parse(args);
+          actions = parsed.actions || parsed;
+        } catch (e) {
+          return `Error: Could not parse arguments as JSON: ${e.message}`;
+        }
+      }
+
+      // If actions is a string, try to parse it as JSON
+      if (typeof actions === "string") {
+        try {
+          actions = JSON.parse(actions);
+        } catch (e) {
+          return `Error: Could not parse actions as JSON array: ${e.message}\nReceived: ${actions.substring(0, 200)}`;
+        }
+      }
+
+      // Validate actions array
+      if (!actions || !Array.isArray(actions)) {
+        return `Error: actions must be a non-empty array of action objects. Received type: ${typeof actions}, value: ${JSON.stringify(actions).substring(0, 200)}`;
+      }
+
+      if (actions.length === 0) {
+        return "Error: actions array is empty";
+      }
+
+      try {
+        const page = await getBrowserPage(config);
+
+        console.log(
+          `[Browser] Executing ${actions.length} actions in sequence`,
+        );
+        const result = await executeActionSequence(page, actions);
+
+        // Format the result for readability
+        let output = `**Browser Interaction Results**\n`;
+        output += `Completed: ${result.completed}/${result.total} actions\n\n`;
+
+        result.results.forEach((r, i) => {
+          const status = r.success ? "✓" : "✗";
+          output += `${i + 1}. ${status} ${r.action}: ${r.message || r.error || "done"}\n`;
+          if (r.result !== undefined) {
+            output += `   Result: ${JSON.stringify(r.result).substring(0, 200)}\n`;
+          }
+        });
+
+        output += `\n**Final State:**\n`;
+        output += `URL: ${result.finalState.url}\n`;
+        output += `Title: ${result.finalState.title}\n`;
+
+        if (readAfter) {
+          const page = await getBrowserPage(config);
+          const content = await getTruncatedPageContent(page);
+          if (content) output += `\n--- Page content ---\n${content}`;
+        }
+
+        if (result.lastError) {
+          output += `\n⚠️ Last Error: ${result.lastError}`;
+        }
+
+        return output;
+      } catch (err) {
+        return `Error executing browser actions: ${err.message}`;
+      }
+    },
+  },
+
+  // ============================================
+  // Memory Tools
+  // ============================================
+
+  search_memory: {
+    description:
+      "Search through your chat memory/history to find past conversations. Searches both local CLI history and Supabase cloud chats (when authenticated). Use simple, specific keywords (names, topics, single words). Returns matching chats with context snippets showing where the match was found. Use read_memory to get full content.",
+    parameters: {
+      query: {
+        type: "string",
+        description:
+          "Search query - use SIMPLE keywords like a name, topic, or single word. Avoid long phrases.",
+        required: true,
+      },
+      limit: {
+        type: "number",
+        description: "Max results to return (default: 10)",
+        required: false,
+      },
+    },
+    execute: async ({ query, limit = 10 }, config) => {
+      const { getAllEmbeddings, searchChatsText, getChat } =
+        await import("../storage/db.js");
+
+      const allResults = [];
+
+      // --- 1. Search Supabase (cloud/CLI tier chats) when authenticated ---
+      if (config.accessToken) {
+        try {
+          const { verifyToken, searchChatsInSupabase } =
+            await import("../storage/supabase.js");
+          const user = await verifyToken(config.accessToken);
+          if (user?.id) {
+            const supaResults = await searchChatsInSupabase(
+              user.id,
+              query,
+              limit,
+            );
+            for (const r of supaResults) {
+              const dateStr = r.updated_at
+                ? new Date(r.updated_at).toLocaleDateString()
+                : "Unknown date";
+              const snippetLine = r.snippet ? `\n  ${r.snippet}` : "";
+              allResults.push({
+                source: "cloud",
+                score: r.similarity,
+                line: `- [Cloud Chat ${r.chatId}] "${r.title || "Untitled"}" (${dateStr}) - match: ${r.matchSource}${snippetLine}`,
+              });
+            }
+          }
+        } catch (err) {
+          console.warn("[search_memory] Supabase search failed:", err.message);
+        }
+      }
+
+      // --- 2. Search local SQLite (vector search first, then text) ---
+      try {
+        const allEmbeddings = getAllEmbeddings();
+        if (allEmbeddings.length > 0) {
+          const queryEmbed = await generateQueryEmbedding(query, config);
+          if (queryEmbed) {
+            const scored = allEmbeddings
+              .map((e) => ({
+                chatId: e.chat_id,
+                similarity: cosineSimilarity(queryEmbed, e.embedding),
+              }))
+              .sort((a, b) => b.similarity - a.similarity)
+              .slice(0, limit);
+
+            const relevant = scored.filter((s) => s.similarity > 0.2);
+            for (const s of relevant) {
+              const chat = getChat(s.chatId);
+              if (!chat) continue;
+              const dateStr = chat.updated_at
+                ? new Date(chat.updated_at).toLocaleDateString()
+                : "Unknown date";
+              allResults.push({
+                source: "local",
+                score: s.similarity,
+                line: `- [Local Chat ${s.chatId}] "${chat.title || "Untitled"}" (${dateStr}) - relevance: ${(s.similarity * 100).toFixed(0)}%`,
+              });
+            }
+          }
+        }
+
+        if (!allResults.some((r) => r.source === "local")) {
+          const textResults = searchChatsText(query, limit);
+          for (const r of textResults) {
+            const dateStr = r.updated_at
+              ? new Date(r.updated_at).toLocaleDateString()
+              : "Unknown date";
+            const matchInfo =
+              r.match_count > 1 ? ` (${r.match_count} matches)` : "";
+            const snippet = r.matching_snippet || "";
+            allResults.push({
+              source: "local",
+              score: r.match_count > 1 ? 0.7 : 0.5,
+              line: `- [Local Chat ${r.id}] "${r.title || "Untitled"}" (${dateStr})${matchInfo}\n  ${snippet}`,
+            });
+          }
+        }
+      } catch (err) {
+        console.warn("[search_memory] Local search failed:", err.message);
+      }
+
+      // --- 3. Merge and return ---
+      if (allResults.length === 0) {
+        return `No chats found matching "${query}". Try a different keyword - simpler, single words often work better than phrases.`;
+      }
+
+      allResults.sort((a, b) => b.score - a.score);
+      const formatted = allResults.slice(0, limit).map((r) => r.line);
+      return `Found ${formatted.length} chats matching "${query}":\n\n${formatted.join("\n\n")}\n\nUse read_memory with a chat ID to see the full conversation.`;
+    },
+  },
+
+  read_memory: {
+    description:
+      "Read the full contents of a specific chat from your memory. Use search_memory first to find relevant chat IDs.",
+    parameters: {
+      chat_id: {
+        type: "string",
+        description: "The chat ID (UUID) to read (from search_memory results)",
+        required: true,
+      },
+    },
+    execute: async ({ chat_id }, config) => {
+      const { getChatWithMessages } = await import("../storage/db.js");
+
+      try {
+        const chat = getChatWithMessages(chat_id);
+        if (!chat) {
+          return `Error: Chat ${chat_id} not found.`;
+        }
+
+        // Format the conversation header
+        const dateStr = chat.updated_at
+          ? new Date(chat.updated_at).toLocaleDateString()
+          : "Unknown date";
+        const header = `Chat: "${chat.title || "Untitled"}" (ID: ${chat.id})\nDate: ${dateStr}\nMessages: ${chat.messages.length}\n\n`;
+
+        // Format each message
+        const conversation = chat.messages
+          .map((m) => {
+            const role = m.role === "user" ? "User" : "Assistant";
+            const time = m.created_at
+              ? new Date(m.created_at).toLocaleTimeString()
+              : "";
+            // Truncate very long messages to avoid context overflow
+            const content =
+              m.content.length > 2000
+                ? m.content.substring(0, 2000) +
+                  "\n... [truncated - message continues for " +
+                  (m.content.length - 2000) +
+                  " more characters]"
+                : m.content;
+            return `[${time}] ${role}:\n${content}`;
+          })
+          .join("\n\n---\n\n");
+
+        return header + conversation;
+      } catch (err) {
+        return `Error reading chat: ${err.message}`;
+      }
+    },
+  },
+
+  // ============================================
+  // RAG (Document Search) Tools
+  // ============================================
+
+  rag_search: {
+    description:
+      "Search through uploaded documents for relevant information. Use this when the user mentions documents with @ (like @guidebook). Returns relevant excerpts with citations.",
+    parameters: {
+      query: {
+        type: "string",
+        description: "What to search for in the documents",
+        required: true,
+      },
+      documents: {
+        type: "string",
+        description:
+          "Comma-separated list of document names to search (from @mentions)",
+        required: false,
+      },
+      top_k: {
+        type: "number",
+        description: "Number of results to return (default: 8)",
+        required: false,
+      },
+    },
+    // Mark as conditionally available - only enabled when RAG documents are mentioned
+    isConditional: true,
+    execute: async ({ query, documents, top_k = 8 }, config) => {
+      const { getAllRagDocuments, getRagChunksByDocuments } =
+        await import("../storage/db.js");
+
+      try {
+        // Get all RAG documents
+        const allDocs = getAllRagDocuments();
+        if (allDocs.length === 0) {
+          return "No documents have been uploaded yet. Ask the user to upload documents using the Storage dropdown in the sidebar.";
+        }
+
+        // Filter to requested documents if specified
+        let targetDocs = allDocs;
+        if (documents) {
+          const docNames = documents
+            .split(",")
+            .map((d) => d.trim().toLowerCase());
+          targetDocs = allDocs.filter((doc) => {
+            const docNameLower = doc.name.toLowerCase();
+            return docNames.some(
+              (name) =>
+                docNameLower.includes(name) || name.includes(docNameLower),
+            );
+          });
+
+          if (targetDocs.length === 0) {
+            const availableDocs = allDocs.map((d) => d.name).join(", ");
+            return `No documents found matching: ${documents}\n\nAvailable documents: ${availableDocs}`;
+          }
+        }
+
+        // Generate query embedding
+        const queryEmbedding = await generateQueryEmbedding(query, config);
+        if (!queryEmbedding) {
+          return "Error: Could not generate query embedding. Make sure an OpenAI or Google API key is configured.";
+        }
+
+        // Get chunks from target documents
+        const docIds = targetDocs.map((d) => d.id);
+        const chunks = getRagChunksByDocuments(docIds);
+
+        if (chunks.length === 0) {
+          return `No content found in the specified documents. The documents may not have been properly indexed.`;
+        }
+
+        // Build a map of doc IDs to names for faster lookup
+        // Use Number() to ensure consistent types (SQLite can return strings or ints)
+        const docIdToName = new Map();
+        targetDocs.forEach((d) => {
+          docIdToName.set(Number(d.id), d.name);
+        });
+
+        console.log(
+          "[rag_search] Document ID map:",
+          Object.fromEntries(docIdToName),
+        );
+
+        // Score chunks by similarity
+        const scored = chunks.map((chunk) => {
+          // Parse embedding from blob
+          let embedding;
+          if (Buffer.isBuffer(chunk.embedding)) {
+            embedding = Array.from(
+              new Float32Array(
+                chunk.embedding.buffer,
+                chunk.embedding.byteOffset,
+                chunk.embedding.length / 4,
+              ),
+            );
+          } else if (chunk.embedding instanceof Uint8Array) {
+            embedding = Array.from(new Float32Array(chunk.embedding.buffer));
+          } else {
+            embedding = chunk.embedding;
+          }
+
+          const similarity = cosineSimilarity(queryEmbedding, embedding);
+
+          // Find document name for this chunk (ensure both IDs are numbers for comparison)
+          // Note: DB returns docId (camelCase), pageNumber, chunkIndex
+          const chunkDocId = Number(chunk.docId || chunk.doc_id);
+          const docName = docIdToName.get(chunkDocId) || "Unknown Document";
+
+          return {
+            text: chunk.text,
+            docId: chunkDocId,
+            docName,
+            pageNumber: chunk.pageNumber || chunk.page_number,
+            chunkIndex: chunk.chunkIndex || chunk.chunk_index,
+            similarity,
+          };
+        });
+
+        // Sort by similarity and take top results
+        // Use a lower threshold (25%) to catch more potentially relevant content
+        const topResults = scored
+          .filter((s) => s.similarity > 0.25) // Minimum similarity threshold (25%)
+          .sort((a, b) => b.similarity - a.similarity)
+          .slice(0, top_k);
+
+        console.log(
+          "[rag_search] Top results:",
+          topResults.map((r) => ({
+            docName: r.docName,
+            similarity: Math.round(r.similarity * 100),
+            textPreview: r.text.substring(0, 50),
+          })),
+        );
+
+        if (topResults.length === 0) {
+          return `No relevant content found for "${query}" in the specified documents. Try rephrasing your question or using different keywords.`;
+        }
+
+        // Format results with citations - make it very clear this is real document content
+        const docNamesUsed = [
+          ...new Set(topResults.map((r) => r.docName)),
+        ].join(", ");
+        let output = `📚 DOCUMENT SEARCH RESULTS from: ${docNamesUsed}\n`;
+        output += `Found ${topResults.length} relevant sections. USE THIS CONTENT TO ANSWER:\n\n`;
+
+        topResults.forEach((result, i) => {
+          const pageInfo = result.pageNumber
+            ? `, Page ${result.pageNumber}`
+            : "";
+          const relevance = Math.round(result.similarity * 100);
+
+          output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+          output += `📄 SOURCE [${i + 1}]: ${result.docName}${pageInfo}\n`;
+          output += `   Relevance: ${relevance}%\n\n`;
+          output += `   CONTENT:\n`;
+          output += `   ${result.text.trim().split("\n").join("\n   ")}\n\n`;
+        });
+
+        output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
+        output += `⚠️ IMPORTANT: Use the CONTENT above to answer the user's question.\n`;
+        output += `Cite sources as: "According to [${docNamesUsed}, Page X]..." or quote directly.`;
+
+        return output;
+      } catch (err) {
+        console.error("[rag_search] Error:", err);
+        return `Error searching documents: ${err.message}`;
+      }
+    },
+  },
+};
+
+// ============================================
+// Web Search Helpers (exported for server use)
+// ============================================
+
+const WEBSEARCH_DEBUG =
+  process.env.WEBSEARCH_DEBUG === "1" || process.env.WEBSEARCH_DEBUG === "true";
+
+function webSearchDebug(engine, msg, extra = {}) {
+  if (!WEBSEARCH_DEBUG) return;
+  const parts = [`[WebSearch:${engine}]`, msg];
+  if (Object.keys(extra).length) parts.push(JSON.stringify(extra));
+  console.log(parts.join(" "));
+}
+
+/** When an engine returns 0 results: always log first 2.5k chars of HTML; if WEBSEARCH_DEBUG=1, write full HTML to a file and log path. */
+function logZeroResultHtml(engine, html) {
+  const sampleLen = 2500;
+  const sample =
+    html.length <= sampleLen
+      ? html
+      : html.substring(0, sampleLen) + "\n... (truncated)";
+  console.log(
+    "[WebSearch] " +
+      engine +
+      " HTML (first " +
+      Math.min(html.length, sampleLen) +
+      " chars):",
+  );
+  console.log(sample);
+  if (WEBSEARCH_DEBUG && html.length > sampleLen) {
+    const path = join(
+      tmpdir(),
+      `otherwise-websearch-${engine.toLowerCase()}-${Date.now()}.html`,
+    );
+    writeFileSync(path, html, "utf8");
+    console.log("[WebSearch] " + engine + " full HTML written to: " + path);
+  }
+}
+
+// Rotating browser-like User-Agents and full headers to reduce bot detection
+const BROWSER_USER_AGENTS = [
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:133.0) Gecko/20100101 Firefox/133.0",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.2 Safari/605.1.15",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0",
+];
+function getBrowserHeaders(origin) {
+  const ua =
+    BROWSER_USER_AGENTS[Math.floor(Math.random() * BROWSER_USER_AGENTS.length)];
+  return {
+    "User-Agent": ua,
+    Accept:
+      "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Accept-Encoding": "gzip, deflate, br",
+    Referer: origin ? `${origin}/` : undefined,
+    "Sec-Fetch-Dest": "document",
+    "Sec-Fetch-Mode": "navigate",
+    "Sec-Fetch-Site": origin ? "same-origin" : "none",
+    "Sec-Fetch-User": "?1",
+    "Upgrade-Insecure-Requests": "1",
+    "sec-ch-ua":
+      '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": '"Windows"',
+  };
+}
+
+/** Google: use AdsBot UA so Google may serve static HTML instead of JS-only/captcha (bypass technique). */
+function getGoogleSearchHeaders() {
+  return {
+    "User-Agent": "AdsBot-Google (+http://www.google.com/adsbot.html)",
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+  };
+}
+
+/** Bing: use bingbot UA so Bing may treat request as crawler and serve SERP HTML. */
+function getBingSearchHeaders() {
+  return {
+    "User-Agent":
+      "Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)",
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+  };
+}
+
+/** Extract destination URL from Bing click redirect (bing.com/ck/a?....&u=BASE64). Supports URL-safe base64. */
+function resolveBingCkUrl(href) {
+  if (!href || !href.includes("bing.com/ck/a")) return null;
+  try {
+    const u = new URL(href);
+    const uParam = u.searchParams.get("u");
+    if (!uParam) return null;
+    // Bing may use URL-safe base64 (- and _ instead of + and /)
+    const base64 = uParam.replace(/-/g, "+").replace(/_/g, "/");
+    const decoded = Buffer.from(base64, "base64").toString("utf8");
+    if (decoded.startsWith("a1")) return decoded.slice(2); // Bing sometimes prefixes with a1
+    if (/^https?:\/\//i.test(decoded)) return decoded;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Extract destination URL from Yahoo redirect (r.search.yahoo.com/.../RU=encoded/RK=...). */
+function resolveYahooRedirect(href) {
+  if (!href || !href.includes("r.search.yahoo")) return null;
+  try {
+    const match = href.match(/[?/]RU=([^/]+)(?:\/|$)/i);
+    if (!match) return null;
+    const decoded = decodeURIComponent(match[1].replace(/\+/g, " "));
+    if (/^https?:\/\//i.test(decoded)) return decoded;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchWithTimeout(url, options = {}, timeoutMs = 10000) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const useProxy = options && options.useWebSearchProxy && getWebSearchProxy();
+  const opts = { ...options };
+  delete opts.useWebSearchProxy;
+  const fetchOpts = {
+    ...opts,
+    signal: controller.signal,
+    redirect: "follow",
+  };
+  try {
+    const response = useProxy
+      ? await undiciFetch(url, {
+          ...fetchOpts,
+          dispatcher: new ProxyAgent(useProxy),
+        })
+      : await fetch(url, fetchOpts);
+    clearTimeout(timeout);
+    return response;
+  } catch (err) {
+    clearTimeout(timeout);
+    throw err;
+  }
+}
+
+/**
+ * Normalize URL for deduplication (strip fragment, trailing slash, lowercase host)
+ */
+function normalizeUrlForDedup(url) {
+  try {
+    const u = new URL(url);
+    u.hash = "";
+    u.searchParams.sort();
+    let path = u.pathname.replace(/\/+$/, "") || "/";
+    u.pathname = path;
+    u.hostname = u.hostname.toLowerCase();
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Extract the most relevant snippet from page content by scoring paragraphs
+ * against query terms instead of blindly taking the first N chars.
+ */
+function extractBestSnippet(content, query, maxLen = 400) {
+  if (!content || !query) return (content || "").slice(0, maxLen);
+
+  const queryTerms = new Set(
+    query
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((t) => t.length > 1),
+  );
+  if (queryTerms.size === 0) return content.slice(0, maxLen);
+
+  const paragraphs = content
+    .split(/\n{2,}|\r\n{2,}/)
+    .map((p) => p.replace(/\s+/g, " ").trim())
+    .filter((p) => p.length > 30 && p.length < 2000);
+
+  if (paragraphs.length === 0) return content.slice(0, maxLen);
+
+  let bestScore = -1;
+  let bestParagraph = paragraphs[0];
+
+  for (const para of paragraphs) {
+    const lower = para.toLowerCase();
+    // Skip nav/boilerplate-like paragraphs
+    if (/^(menu|navigation|skip to|cookie|accept|sign in|log in)/i.test(para))
+      continue;
+    let score = 0;
+    for (const term of queryTerms) {
+      const idx = lower.indexOf(term);
+      if (idx !== -1) {
+        score += 10;
+        if (idx < 50) score += 5; // Term appears early
+      }
+    }
+    // Prefer mid-length paragraphs (not too short, not too long)
+    if (para.length > 60 && para.length < 800) score += 3;
+    if (score > bestScore) {
+      bestScore = score;
+      bestParagraph = para;
+    }
+  }
+
+  return bestParagraph.slice(0, maxLen);
+}
+
+/**
+ * Run multiple search engines in parallel, aggregate and dedupe results.
+ * Uses Google, Bing, Brave, DuckDuckGo, and Startpage (all no-API scrape);
+ * results appearing in multiple engines are ranked higher.
+ */
+export async function performWebSearch(query, numResults = 8) {
+  console.log(
+    "[WebSearch] Searching for:",
+    query,
+    "(requesting",
+    numResults,
+    "results)",
+  );
+
+  // Per-engine result cap (request more so we have enough after dedupe)
+  const perEngine = Math.min(numResults + 8, 20);
+
+  const engineFns = [
+    { name: "Google", fn: () => searchGoogle(query, perEngine) },
+    { name: "Bing", fn: () => searchBing(query, perEngine) },
+    { name: "Brave", fn: () => searchBrave(query, perEngine) },
+    { name: "DuckDuckGo", fn: () => searchDuckDuckGo(query, perEngine) },
+    { name: "Startpage", fn: () => searchStartpage(query, perEngine) },
+    { name: "Yahoo", fn: () => searchYahoo(query, perEngine) },
+    { name: "Ecosia", fn: () => searchEcosia(query, perEngine) },
+  ];
+
+  const settled = await Promise.allSettled(engineFns.map((e) => e.fn()));
+
+  const byNormalized = new Map(); // normalizedUrl -> { result, engines[], firstSeenOrder }
+
+  let order = 0;
+  for (let i = 0; i < settled.length; i++) {
+    const status = settled[i];
+    const engineName = engineFns[i].name;
+    if (status.status === "rejected") {
+      console.error(
+        "[WebSearch]",
+        engineName,
+        "error:",
+        status.reason?.message,
+      );
+      continue;
+    }
+    const list = status.value || [];
+    console.log("[WebSearch]", engineName, "returned", list.length, "results");
+    for (const r of list) {
+      const key = normalizeUrlForDedup(r.url);
+      const existing = byNormalized.get(key);
+      if (existing) {
+        existing.engines.push(engineName);
+        if (!existing.result.snippet && r.snippet) {
+          existing.result.snippet = r.snippet;
+        }
+        if (!existing.result.title && r.title) {
+          existing.result.title = r.title;
+        }
+      } else {
+        byNormalized.set(key, {
+          result: {
+            url: r.url,
+            title: r.title,
+            snippet: r.snippet,
+            source: r.source,
+          },
+          engines: [engineName],
+          firstSeenOrder: order++,
+        });
+      }
+    }
+  }
+
+  // Relevance scoring: query-term matches in title/snippet + cross-engine count + order
+  const queryTerms = new Set(
+    query
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((t) => t.length > 1),
+  );
+
+  const sorted = [...byNormalized.values()]
+    .sort((a, b) => {
+      const textA = `${a.result.title} ${a.result.snippet}`.toLowerCase();
+      const textB = `${b.result.title} ${b.result.snippet}`.toLowerCase();
+      const termHitsA = [...queryTerms].filter((t) => textA.includes(t)).length;
+      const termHitsB = [...queryTerms].filter((t) => textB.includes(t)).length;
+      const aScore =
+        termHitsA * 500 + a.engines.length * 1000 - a.firstSeenOrder;
+      const bScore =
+        termHitsB * 500 + b.engines.length * 1000 - b.firstSeenOrder;
+      return bScore - aScore;
+    })
+    .slice(0, numResults)
+    .map((x) => ({ ...x.result, engines: x.engines }));
+
+  console.log("[WebSearch] Total unique results after dedupe:", sorted.length);
+  return sorted;
+}
+
+/** Parse DuckDuckGo HTML SERP and return results array. */
+function parseDuckDuckGoResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  function add(url, title, snippet) {
+    if (url.includes("uddg=")) {
+      const uddgMatch = url.match(/uddg=([^&]+)/);
+      if (uddgMatch) url = decodeURIComponent(uddgMatch[1]);
+    }
+    if (!url.startsWith("http") || seenUrls.has(url)) return;
+    seenUrls.add(url);
+    let source = "";
+    try {
+      source = new URL(url).hostname.replace("www.", "");
+    } catch {}
+    results.push({
+      url,
+      title: title || source,
+      snippet: snippet || `From ${source}`,
+      source,
+    });
+  }
+  const resultPattern =
+    /<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([^<]+)<\/a>[\s\S]*?<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+  let match;
+  while (
+    (match = resultPattern.exec(html)) !== null &&
+    results.length < numResults
+  ) {
+    let snippet = match[3].replace(/<[^>]+>/g, " ").trim();
+    snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 250);
+    add(match[1], decodeHtmlEntities(match[2].trim()), snippet);
+  }
+  if (results.length < numResults) {
+    const uddgRegex = /<a[^>]*href="([^"]*uddg=[^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+    let um;
+    while (
+      (um = uddgRegex.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      const title = decodeHtmlEntities(um[2].replace(/<[^>]+>/g, "").trim());
+      if (title.length < 3 || title.length > 300) continue;
+      add(um[1], title, "");
+    }
+  }
+  if (results.length < numResults) {
+    const blocks = html.split(/class="[^"]*result__body[^"]*"[^>]*>/i);
+    for (let i = 1; i < blocks.length && results.length < numResults; i++) {
+      const block = blocks[i].substring(0, 2000);
+      const linkMatch = block.match(/<a[^>]*href="([^"]+)"[^>]*>([^<]+)<\/a>/i);
+      if (linkMatch)
+        add(linkMatch[1], decodeHtmlEntities(linkMatch[2].trim()), "");
+    }
+  }
+  return results;
+}
+
+/** Search DuckDuckGo HTML version. Retries with headless browser if fetch returns 0 results. */
+async function searchDuckDuckGo(query, numResults) {
+  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+  const headers = getBrowserHeaders("https://html.duckduckgo.com");
+  headers["Sec-Fetch-Site"] = "none";
+
+  const response = await fetchWithTimeout(
+    url,
+    { headers, useWebSearchProxy: true },
+    12000,
+  );
+  let html = await response.text();
+
+  let results = parseDuckDuckGoResults(html, numResults);
+
+  if (results.length === 0 && process.env.WEBSEARCH_USE_BROWSER !== "0") {
+    try {
+      console.log("[WebSearch] DuckDuckGo retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      results = parseDuckDuckGoResults(html, numResults);
+    } catch (e) {
+      console.log(
+        "[WebSearch] DuckDuckGo browser fetch failed:",
+        e?.message || e,
+      );
+    }
+  }
+
+  if (results.length === 0) {
+    const uddgCount = (html.match(/uddg=/g) || []).length;
+    const resultACount = (html.match(/result__a/g) || []).length;
+    const resultBodyCount = (html.match(/result__body/g) || []).length;
+    console.log(
+      "[WebSearch] DuckDuckGo: 0 results | htmlLen=",
+      html.length,
+      "| uddg=",
+      uddgCount,
+      "result__a=",
+      resultACount,
+      "result__body=",
+      resultBodyCount,
+    );
+    logZeroResultHtml("DuckDuckGo", html);
+  }
+  console.log("[WebSearch] DuckDuckGo found:", results.length, "results");
+  return results;
+}
+
+/**
+ * Decode HTML entities
+ */
+function decodeHtmlEntities(text) {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex) =>
+      String.fromCharCode(parseInt(hex, 16)),
+    )
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCharCode(dec));
+}
+
+/** Parse Brave SERP HTML and return results array. */
+function parseBraveResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  const blocks = html.split(/data-type="web"/);
+  for (let i = 1; i < blocks.length && results.length < numResults; i++) {
+    const block = blocks[i].substring(0, 3000);
+    const hrefMatch = block.match(/href="(https?:\/\/[^"]+)"/);
+    if (!hrefMatch) continue;
+    const resultUrl = hrefMatch[1];
+    if (resultUrl.includes("brave.com") || seenUrls.has(resultUrl)) continue;
+    const titleMatch = block.match(/title="([^"]{10,300})"/);
+    let title = titleMatch ? decodeHtmlEntities(titleMatch[1].trim()) : "";
+    if (!title) {
+      const innerTitleMatch = block.match(
+        /class="[^"]*title[^"]*"[^>]*>([^<]+)</,
+      );
+      if (innerTitleMatch)
+        title = decodeHtmlEntities(innerTitleMatch[1].trim());
+    }
+    if (!title || title.length < 5) continue;
+    let snippet = "";
+    const snippetMatch = block.match(
+      /class="[^"]*(?:snippet-description|description)[^"]*"[^>]*>([^<]+)/,
+    );
+    if (snippetMatch)
+      snippet = decodeHtmlEntities(snippetMatch[1].trim())
+        .replace(/\s+/g, " ")
+        .slice(0, 300);
+    seenUrls.add(resultUrl);
+    let source = "";
+    try {
+      source = new URL(resultUrl).hostname.replace("www.", "");
+    } catch {}
+    results.push({
+      url: resultUrl,
+      title,
+      snippet: snippet || `From ${source}`,
+      source,
+    });
+  }
+  if (results.length < numResults) {
+    const cardPattern =
+      /class="enrichment-card-item[^"]*"[^>]*href="(https?:\/\/[^"]+)"/g;
+    let cardMatch;
+    while (
+      (cardMatch = cardPattern.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      const cardUrl = cardMatch[1];
+      if (seenUrls.has(cardUrl) || cardUrl.includes("brave.com")) continue;
+      seenUrls.add(cardUrl);
+      let source = "";
+      try {
+        source = new URL(cardUrl).hostname.replace("www.", "");
+      } catch {}
+      const cardContext = html.substring(
+        cardMatch.index,
+        cardMatch.index + 500,
+      );
+      const cardTitleMatch = cardContext.match(/title="([^"]+)"/);
+      const title = cardTitleMatch
+        ? decodeHtmlEntities(cardTitleMatch[1].trim())
+        : `Article from ${source}`;
+      results.push({ url: cardUrl, title, snippet: `From ${source}`, source });
+    }
+  }
+  return results;
+}
+
+/**
+ * Search Brave - reliable, privacy-focused. Retries with headless browser if fetch returns 0 results.
+ */
+async function searchBrave(query, numResults) {
+  const url = `https://search.brave.com/search?q=${encodeURIComponent(query)}&source=web`;
+  const response = await fetchWithTimeout(
+    url,
+    {
+      headers: {
+        "User-Agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+        Accept:
+          "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9",
+        "Accept-Encoding": "gzip, deflate, br",
+      },
+      useWebSearchProxy: true,
+    },
+    12000,
+  );
+  let html = await response.text();
+  console.log("[WebSearch] Brave response:", html.length, "bytes");
+  if (html.length < 5000) return [];
+
+  let results = parseBraveResults(html, numResults);
+
+  if (results.length === 0 && process.env.WEBSEARCH_USE_BROWSER !== "0") {
+    try {
+      console.log("[WebSearch] Brave retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      results = parseBraveResults(html, numResults);
+    } catch (e) {
+      console.log("[WebSearch] Brave browser fetch failed:", e?.message || e);
+    }
+  }
+
+  console.log("[WebSearch] Brave found:", results.length, "results");
+  return results;
+}
+
+/** Parse Startpage SERP HTML and return results array. */
+function parseStartpageResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  const patterns = [
+    /<a[^>]*class="[^"]*result-title[^"]*"[^>]*href="([^"]+)"[^>]*>[\s\S]*?<h2[^>]*>([^<]+)<\/h2>[\s\S]*?<\/a>[\s\S]*?<p[^>]*class="[^"]*description[^"]*"[^>]*>([\s\S]*?)<\/p>/gi,
+    /<a[^>]*class="[^"]*w-gl__result-title[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<p[^>]*class="[^"]*w-gl__description[^"]*"[^>]*>([\s\S]*?)<\/p>/gi,
+    /<a[^>]*href="(https?:\/\/(?!.*startpage)[^"]+)"[^>]*class="[^"]*result[^"]*"[^>]*>([\s\S]*?)<\/a>[\s\S]{0,500}?<p[^>]*>([\s\S]*?)<\/p>/gi,
+  ];
+  for (const pattern of patterns) {
+    if (results.length >= numResults) break;
+    let match;
+    pattern.lastIndex = 0;
+    while (
+      (match = pattern.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      const resultUrl = match[1];
+      let title = match[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      let snippet = match[3].replace(/<[^>]+>/g, " ").trim();
+      snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 300);
+      if (
+        !resultUrl.startsWith("http") ||
+        resultUrl.includes("startpage.com") ||
+        seenUrls.has(resultUrl) ||
+        !title ||
+        title.length < 3
+      )
+        continue;
+      seenUrls.add(resultUrl);
+      let source = "";
+      try {
+        source = new URL(resultUrl).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: resultUrl,
+        title,
+        snippet: snippet || `From ${source}`,
+        source,
+      });
+    }
+  }
+  if (results.length < numResults / 2) {
+    const linkPattern =
+      /<a[^>]*href="(https?:\/\/(?!.*startpage)[^"]+)"[^>]*>([^<]*(?:<[^>]*>[^<]*)*)<\/a>/gi;
+    const descPattern =
+      /<p[^>]*class="[^"]*(?:description|snippet|abstract)[^"]*"[^>]*>([\s\S]*?)<\/p>/gi;
+    const links = [];
+    const descs = [];
+    let m;
+    while ((m = linkPattern.exec(html)) !== null) {
+      const url = m[1];
+      const text = m[2].replace(/<[^>]+>/g, "").trim();
+      if (
+        url &&
+        text &&
+        text.length > 10 &&
+        text.length < 200 &&
+        !seenUrls.has(url)
+      )
+        links.push({ url, title: decodeHtmlEntities(text) });
+    }
+    while ((m = descPattern.exec(html)) !== null) {
+      let d = m[1].replace(/<[^>]+>/g, " ").trim();
+      descs.push(decodeHtmlEntities(d).replace(/\s+/g, " ").slice(0, 300));
+    }
+    for (let i = 0; i < links.length && results.length < numResults; i++) {
+      if (seenUrls.has(links[i].url)) continue;
+      seenUrls.add(links[i].url);
+      let source = "";
+      try {
+        source = new URL(links[i].url).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: links[i].url,
+        title: links[i].title,
+        snippet: descs[i] || `From ${source}`,
+        source,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Search Startpage - reliable, privacy-focused. Retries with headless browser if fetch returns 0 results.
+ */
+async function searchStartpage(query, numResults) {
+  const url = `https://www.startpage.com/sp/search?q=${encodeURIComponent(query)}&cat=web&pl=ext-ff&language=english`;
+  const response = await fetchWithTimeout(
+    url,
+    {
+      headers: {
+        "User-Agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+        Accept:
+          "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9",
+        "Accept-Encoding": "gzip, deflate, br",
+      },
+      useWebSearchProxy: true,
+    },
+    12000,
+  );
+  let html = await response.text();
+  console.log("[WebSearch] Startpage response:", html.length, "bytes");
+  if (html.length < 5000) return [];
+
+  let results = parseStartpageResults(html, numResults);
+
+  if (results.length === 0 && process.env.WEBSEARCH_USE_BROWSER !== "0") {
+    try {
+      console.log("[WebSearch] Startpage retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      results = parseStartpageResults(html, numResults);
+    } catch (e) {
+      console.log(
+        "[WebSearch] Startpage browser fetch failed:",
+        e?.message || e,
+      );
+    }
+  }
+
+  console.log("[WebSearch] Startpage found:", results.length, "results");
+  return results;
+}
+
+/**
+ * Extract destination URL from Google's /url?q=... redirect wrapper
+ */
+function extractGoogleResultUrl(href) {
+  if (!href || !href.includes("url?")) return href;
+  const m = href.match(/[?&]q=([^&]+)/);
+  if (m) return decodeURIComponent(m[1]);
+  return href;
+}
+
+/** Parse Google SERP HTML and return results array (used by fetch and browser fallback). */
+function parseGoogleResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  function addResult(resultUrl, title, snippet, source) {
+    try {
+      resultUrl = decodeURIComponent(resultUrl);
+    } catch {}
+    if (
+      !resultUrl.startsWith("http") ||
+      resultUrl.includes("google.com") ||
+      seenUrls.has(resultUrl)
+    )
+      return false;
+    let s = source;
+    if (!s) {
+      try {
+        s = new URL(resultUrl).hostname.replace("www.", "");
+      } catch {}
+    }
+    const finalTitle =
+      title && title.length >= 2 ? title.slice(0, 300) : s || resultUrl;
+    seenUrls.add(resultUrl);
+    results.push({
+      url: resultUrl,
+      title: finalTitle,
+      snippet: (snippet || `From ${s}`).slice(0, 300),
+      source: s,
+    });
+    return true;
+  }
+  const gBlocks = html.split(/<div[^>]*class="[^"]*\bg\b[^"]*"[^>]*>/i);
+  for (let i = 1; i < gBlocks.length && results.length < numResults; i++) {
+    const block = gBlocks[i].substring(0, 4000);
+    const hrefMatch = block.match(
+      /href="(\/url\?q=([^"]+)|(https?:\/\/[^"]+))"/,
+    );
+    if (!hrefMatch) continue;
+    let resultUrl = hrefMatch[1].startsWith("http")
+      ? hrefMatch[1]
+      : extractGoogleResultUrl(hrefMatch[1]);
+    const titleMatch =
+      block.match(/<h3[^>]*>([\s\S]*?)<\/h3>/i) ||
+      block.match(/class="[^"]*LC20lb[^"]*"[^>]*>([^<]+)/i);
+    const title = titleMatch
+      ? decodeHtmlEntities(titleMatch[1].replace(/<[^>]+>/g, "").trim())
+      : "";
+    const snippetMatch =
+      block.match(/class="[^"]*VwiC3b[^"]*"[^>]*>([\s\S]*?)<\/div>/i) ||
+      block.match(
+        /<span[^>]*class="[^"]*\b(?:st|s)\b[^"]*"[^>]*>([\s\S]*?)<\/span>/i,
+      );
+    let snippet = snippetMatch
+      ? snippetMatch[1].replace(/<[^>]+>/g, " ").trim()
+      : "";
+    snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 300);
+    addResult(resultUrl, title, snippet, "");
+  }
+  if (results.length < numResults && /data-ved=/.test(html)) {
+    const vedBlocks = html.split(/data-ved="[^"]*"/);
+    for (let i = 1; i < vedBlocks.length && results.length < numResults; i++) {
+      const block = vedBlocks[i].substring(0, 3000);
+      const hrefMatch = block.match(
+        /href="(\/url\?q=([^"]+)|(https?:\/\/[^"]+))"/,
+      );
+      if (!hrefMatch) continue;
+      let resultUrl = hrefMatch[1].startsWith("http")
+        ? hrefMatch[1]
+        : extractGoogleResultUrl(hrefMatch[1]);
+      const titleMatch = block.match(/<h3[^>]*>([\s\S]*?)<\/h3>/i);
+      const title = titleMatch
+        ? decodeHtmlEntities(titleMatch[1].replace(/<[^>]+>/g, "").trim())
+        : "";
+      addResult(resultUrl, title, "", "");
+    }
+  }
+  if (results.length < numResults) {
+    const urlQRegex = /href="(\/url\?q=)([^"]+)"/gi;
+    let urlMatch;
+    while (
+      (urlMatch = urlQRegex.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      const qValue = urlMatch[2];
+      let resultUrl = "";
+      try {
+        resultUrl = decodeURIComponent(qValue.replace(/&amp;/g, "&"));
+      } catch {
+        continue;
+      }
+      if (
+        !resultUrl.startsWith("http") ||
+        resultUrl.includes("google.com") ||
+        seenUrls.has(resultUrl)
+      )
+        continue;
+      const after = html.substring(
+        urlMatch.index,
+        Math.min(html.length, urlMatch.index + 1200),
+      );
+      const titleMatch =
+        after.match(/<h3[^>]*>([\s\S]*?)<\/h3>/i) ||
+        after.match(/<span[^>]*>([^<]{5,200})<\/span>/);
+      const title = titleMatch
+        ? decodeHtmlEntities(
+            titleMatch[1].replace(/<[^>]+>/g, "").trim(),
+          ).slice(0, 300)
+        : "";
+      addResult(resultUrl, title, "", "");
+    }
+  }
+  if (results.length < numResults) {
+    const urlQRegex2 = /\/url\?q=([^"&]+)/gi;
+    let urlMatch2;
+    while (
+      (urlMatch2 = urlQRegex2.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      let resultUrl = "";
+      try {
+        resultUrl = decodeURIComponent(urlMatch2[1].replace(/&amp;/g, "&"));
+      } catch {
+        continue;
+      }
+      if (
+        !resultUrl.startsWith("http") ||
+        resultUrl.includes("google.com") ||
+        seenUrls.has(resultUrl)
+      )
+        continue;
+      const after = html.substring(
+        urlMatch2.index,
+        Math.min(html.length, urlMatch2.index + 800),
+      );
+      const textBlock = after.match(/>([^<]{5,200})</);
+      const title = textBlock
+        ? decodeHtmlEntities(textBlock[1].trim()).slice(0, 300)
+        : "";
+      addResult(resultUrl, title, "", "");
+    }
+  }
+  if (results.length < numResults) {
+    const citeRegex = /<cite[^>]*>([^<]+)<\/cite>/gi;
+    let citeMatch;
+    while (
+      (citeMatch = citeRegex.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      const before = html.substring(
+        Math.max(0, citeMatch.index - 1200),
+        citeMatch.index,
+      );
+      const hrefAll = [...before.matchAll(/href="(\/url\?q=([^"]+))"/g)];
+      const hrefMatch = hrefAll[hrefAll.length - 1];
+      if (!hrefMatch) continue;
+      let resultUrl = hrefMatch[1].startsWith("http")
+        ? hrefMatch[1]
+        : extractGoogleResultUrl(hrefMatch[1]);
+      try {
+        resultUrl = decodeURIComponent(resultUrl);
+      } catch {
+        continue;
+      }
+      if (
+        !resultUrl.startsWith("http") ||
+        resultUrl.includes("google.com") ||
+        seenUrls.has(resultUrl)
+      )
+        continue;
+      const h3All = [...before.matchAll(/<h3[^>]*>([\s\S]*?)<\/h3>/gi)];
+      const titleMatch = h3All[h3All.length - 1];
+      const title = titleMatch
+        ? decodeHtmlEntities(
+            titleMatch[1].replace(/<[^>]+>/g, "").trim(),
+          ).slice(0, 300)
+        : "";
+      addResult(resultUrl, title, "", "");
+    }
+  }
+  return results;
+}
+
+/**
+ * Fetch Google results via SerpAPI (no captcha). Set SERPAPI_API_KEY to use.
+ */
+async function fetchSerpApiGoogle(query, numResults) {
+  const apiKey = process.env.SERPAPI_API_KEY;
+  if (!apiKey) return null;
+  const url = `https://serpapi.com/search?engine=google&q=${encodeURIComponent(query)}&num=${Math.min(numResults + 5, 30)}&api_key=${apiKey}`;
+  try {
+    const response = await fetchWithTimeout(url, {}, 15000);
+    if (!response.ok) return null;
+    const data = await response.json();
+    const organic = data.organic_results || [];
+    const results = [];
+    for (const r of organic) {
+      if (results.length >= numResults) break;
+      const link = r.link || r.redirect_link;
+      if (!link || link.includes("google.com")) continue;
+      let source = "";
+      try {
+        source = new URL(link).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: link,
+        title: (r.title || "").slice(0, 300),
+        snippet: (r.snippet || `From ${source}`).slice(0, 300),
+        source,
+      });
+    }
+    if (results.length > 0)
+      console.log(
+        "[WebSearch] Google (SerpAPI) found:",
+        results.length,
+        "results",
+      );
+    return results;
+  } catch (e) {
+    console.log("[WebSearch] SerpAPI Google error:", e?.message || e);
+    return null;
+  }
+}
+
+/**
+ * Fetch Bing results via SerpAPI. Set SERPAPI_API_KEY to use.
+ */
+async function fetchSerpApiBing(query, numResults) {
+  const apiKey = process.env.SERPAPI_API_KEY;
+  if (!apiKey) return null;
+  const url = `https://serpapi.com/search?engine=bing&q=${encodeURIComponent(query)}&count=${Math.min(numResults + 5, 30)}&api_key=${apiKey}`;
+  try {
+    const response = await fetchWithTimeout(url, {}, 15000);
+    if (!response.ok) return null;
+    const data = await response.json();
+    const organic = data.organic_results || [];
+    const results = [];
+    for (const r of organic) {
+      if (results.length >= numResults) break;
+      const link = r.link;
+      if (!link || link.includes("bing.com") || link.includes("microsoft.com"))
+        continue;
+      let source = "";
+      try {
+        source = new URL(link).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: link,
+        title: (r.title || "").slice(0, 300),
+        snippet: (r.snippet || `From ${source}`).slice(0, 300),
+        source,
+      });
+    }
+    if (results.length > 0)
+      console.log(
+        "[WebSearch] Bing (SerpAPI) found:",
+        results.length,
+        "results",
+      );
+    return results;
+  } catch (e) {
+    console.log("[WebSearch] SerpAPI Bing error:", e?.message || e);
+    return null;
+  }
+}
+
+/**
+ * Search Google (no API) - scrape SERP HTML. Uses SerpAPI if SERPAPI_API_KEY set; else proxy if WEBSEARCH_PROXY/HTTPS_PROXY set. Retries with headless browser if fetch returns 0 results.
+ */
+async function searchGoogle(query, numResults) {
+  const serpApiResults = await fetchSerpApiGoogle(query, numResults);
+  if (serpApiResults && serpApiResults.length > 0) return serpApiResults;
+
+  const num = Math.min(numResults + 5, 30);
+  const url = `https://www.google.com/search?q=${encodeURIComponent(query)}&num=${num}&ncr=1`;
+  let headers = getGoogleSearchHeaders();
+  const fetchOptions = { headers, useWebSearchProxy: true };
+
+  let response = await fetchWithTimeout(url, fetchOptions, 15000);
+  let html = await response.text();
+
+  if (
+    /Update your browser|isn't supported anymore/i.test(html) &&
+    html.length < 15000
+  ) {
+    headers = getBrowserHeaders("https://www.google.com");
+    delete headers["Sec-Fetch-Site"];
+    headers["Sec-Fetch-Site"] = "none";
+    response = await fetchWithTimeout(
+      url,
+      { headers, useWebSearchProxy: true },
+      15000,
+    );
+    html = await response.text();
+  }
+
+  const isBlocked =
+    /unusual\s+traffic|we've\s+detected|detected\s+unusual|captcha|blocked|before you continue|consent\.google/i.test(
+      html,
+    ) && html.length < 20000;
+  if (isBlocked) {
+    console.log(
+      "[WebSearch] Google: page appears blocked/captcha (length=",
+      html.length,
+      ")",
+    );
+    logZeroResultHtml("Google", html);
+    return [];
+  }
+
+  let results = parseGoogleResults(html, numResults);
+
+  // Skip browser retry when we already got captcha (browser would get same)
+  const isCaptcha =
+    /recaptcha|captcha-form|solveSimpleChallenge|data-sitekey/i.test(html);
+  if (
+    results.length === 0 &&
+    process.env.WEBSEARCH_USE_BROWSER !== "0" &&
+    !isCaptcha
+  ) {
+    try {
+      console.log("[WebSearch] Google retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      if (/recaptcha|captcha-form|solveSimpleChallenge/i.test(html))
+        return results;
+      results = parseGoogleResults(html, numResults);
+    } catch (e) {
+      console.log("[WebSearch] Google browser fetch failed:", e?.message || e);
+    }
+  }
+
+  if (results.length === 0) {
+    const gCount = (
+      html.match(/<div[^>]*class="[^"]*\bg\b[^"]*"[^>]*>/gi) || []
+    ).length;
+    const urlQCount = (html.match(/\/url\?q=/gi) || []).length;
+    const citeCount = (html.match(/<cite[^>]*>/gi) || []).length;
+    const h3Count = (html.match(/<h3[^>]*>/gi) || []).length;
+    console.log(
+      "[WebSearch] Google: 0 results | htmlLen=",
+      html.length,
+      "status=",
+      response?.status,
+      "| gBlocks=",
+      gCount,
+      "urlQ=",
+      urlQCount,
+      "cite=",
+      citeCount,
+      "h3=",
+      h3Count,
+    );
+    logZeroResultHtml("Google", html);
+  } else {
+    console.log("[WebSearch] Google found:", results.length, "results");
+  }
+  return results;
+}
+
+/** Parse Bing SERP HTML and return results array (used by fetch and browser fallback). */
+function parseBingResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  function addResult(resultUrl, title, snippet) {
+    if (
+      resultUrl.includes("bing.com") ||
+      resultUrl.includes("microsoft.com") ||
+      seenUrls.has(resultUrl)
+    )
+      return false;
+    if (!title || title.length < 2) return false;
+    seenUrls.add(resultUrl);
+    let source = "";
+    try {
+      source = new URL(resultUrl).hostname.replace("www.", "");
+    } catch {}
+    results.push({
+      url: resultUrl,
+      title: title.slice(0, 300),
+      snippet: (snippet || `From ${source}`).slice(0, 300),
+      source,
+    });
+    return true;
+  }
+  function resolveUrl(href) {
+    if (href && href.includes("bing.com/ck/a")) {
+      const resolved = resolveBingCkUrl(href);
+      if (
+        resolved &&
+        !resolved.includes("bing.com") &&
+        !resolved.includes("microsoft.com")
+      )
+        return resolved;
+    }
+    return href;
+  }
+  // Match either double- or single-quoted href (browser-rendered HTML may use either)
+  const linkRegexBing =
+    /<a[^>]*href=["'](https?:\/\/[^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+  // li or div (browser-rendered Bing often uses div for result blocks)
+  const algoRegex = /<(?:li|div)[^>]*class="[^"]*b_(?:algo|ans)[^"]*"[^>]*>/gi;
+  let algoMatch;
+  const blocks = [];
+  while ((algoMatch = algoRegex.exec(html)) !== null)
+    blocks.push({ start: algoMatch.index, end: html.length });
+  for (let i = 0; i < blocks.length && results.length < numResults; i++) {
+    const start = blocks[i].start;
+    const end = i + 1 < blocks.length ? blocks[i + 1].start : html.length;
+    const block = html.substring(start, Math.min(start + 3500, end));
+    linkRegexBing.lastIndex = 0;
+    const allLinks = [...block.matchAll(linkRegexBing)];
+    for (const linkMatch of allLinks) {
+      let resultUrl = resolveUrl(linkMatch[1]);
+      if (resultUrl.includes("bing.com") || resultUrl.includes("microsoft.com"))
+        continue;
+      let title = linkMatch[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      if (title.length < 2) continue;
+      const snippetMatch =
+        block.match(/<p[^>]*>([\s\S]*?)<\/p>/i) ||
+        block.match(
+          /class="[^"]*b_caption[^"]*"[^>]*>[\s\S]*?<p[^>]*>([\s\S]*?)<\/p>/i,
+        );
+      let snippet = snippetMatch
+        ? snippetMatch[1].replace(/<[^>]+>/g, " ").trim()
+        : "";
+      snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 300);
+      if (addResult(resultUrl, title, snippet)) break;
+    }
+  }
+  if (results.length < numResults) {
+    const algoBlocks = html.split(
+      /<(?:li|div)[^>]*class="[^"]*b_algo[^"]*"[^>]*>/i,
+    );
+    for (let i = 1; i < algoBlocks.length && results.length < numResults; i++) {
+      const block = algoBlocks[i].substring(0, 3500);
+      linkRegexBing.lastIndex = 0;
+      const allLinks = [...block.matchAll(linkRegexBing)];
+      for (const linkMatch of allLinks) {
+        let resultUrl = resolveUrl(linkMatch[1]);
+        if (
+          resultUrl.includes("bing.com") ||
+          resultUrl.includes("microsoft.com")
+        )
+          continue;
+        let title = linkMatch[2].replace(/<[^>]+>/g, "").trim();
+        title = decodeHtmlEntities(title);
+        if (title.length < 2) continue;
+        const snippetMatch = block.match(/<p[^>]*>([\s\S]*?)<\/p>/i);
+        let snippet = snippetMatch
+          ? snippetMatch[1].replace(/<[^>]+>/g, " ").trim()
+          : "";
+        snippet = decodeHtmlEntities(snippet)
+          .replace(/\s+/g, " ")
+          .slice(0, 300);
+        if (addResult(resultUrl, title, snippet)) break;
+      }
+    }
+  }
+  if (results.length < numResults) {
+    const h2Pattern =
+      /<h2[^>]*>[\s\S]*?<a[^>]*href=["'](https?:\/\/[^"']+)["'][^>]*>([\s\S]*?)<\/a>[\s\S]*?<\/h2>[\s\S]{0,800}?<p[^>]*>([\s\S]*?)<\/p>/gi;
+    let m;
+    while ((m = h2Pattern.exec(html)) !== null && results.length < numResults) {
+      let resultUrl = resolveUrl(m[1]);
+      if (resultUrl.includes("bing.com") || resultUrl.includes("microsoft.com"))
+        continue;
+      const title = decodeHtmlEntities(m[2].replace(/<[^>]+>/g, "").trim());
+      let snippet = m[3].replace(/<[^>]+>/g, " ").trim();
+      snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 300);
+      addResult(resultUrl, title, snippet);
+    }
+  }
+  if (results.length < numResults) {
+    linkRegexBing.lastIndex = 0;
+    let lm;
+    while (
+      (lm = linkRegexBing.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      let url = resolveUrl(lm[1]);
+      if (
+        url.includes("bing.com") ||
+        url.includes("microsoft.com") ||
+        seenUrls.has(url)
+      )
+        continue;
+      let title = lm[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      if (title.length < 4 || title.length > 250) continue;
+      if (/^(http|www|search|images|video|news|maps)/i.test(title)) continue;
+      addResult(url, title, "", "");
+    }
+  }
+  return results;
+}
+
+/**
+ * Search Bing (no API) - scrape SERP HTML. Uses SerpAPI if SERPAPI_API_KEY set; else proxy if WEBSEARCH_PROXY/HTTPS_PROXY set. Retries with headless browser if fetch returns 0 results.
+ */
+async function searchBing(query, numResults) {
+  const serpApiResults = await fetchSerpApiBing(query, numResults);
+  if (serpApiResults && serpApiResults.length > 0) return serpApiResults;
+
+  const url = `https://www.bing.com/search?q=${encodeURIComponent(query)}&count=${Math.min(numResults + 5, 30)}`;
+  const headers = getBingSearchHeaders();
+
+  const response = await fetchWithTimeout(
+    url,
+    { headers, useWebSearchProxy: true },
+    15000,
+  );
+  let html = await response.text();
+
+  if (html.length < 2000) {
+    console.log(
+      "[WebSearch] Bing: response too short (length=",
+      html.length,
+      ", status=",
+      response.status,
+      ")",
+    );
+    logZeroResultHtml("Bing", html);
+    return [];
+  }
+
+  let results = parseBingResults(html, numResults);
+
+  if (results.length === 0 && process.env.WEBSEARCH_USE_BROWSER !== "0") {
+    try {
+      console.log("[WebSearch] Bing retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      results = parseBingResults(html, numResults);
+    } catch (e) {
+      console.log("[WebSearch] Bing browser fetch failed:", e?.message || e);
+    }
+  }
+
+  if (results.length === 0) {
+    const algoCount = (html.match(/b_algo|b_ans/gi) || []).length;
+    const h2Count = (html.match(/<h2[^>]*>/gi) || []).length;
+    const linkCount = (html.match(/<a[^>]*href="https?:\/\//gi) || []).length;
+    console.log(
+      "[WebSearch] Bing: 0 results | htmlLen=",
+      html.length,
+      "status=",
+      response.status,
+      "| b_algo=",
+      algoCount,
+      "h2=",
+      h2Count,
+      "links=",
+      linkCount,
+    );
+    logZeroResultHtml("Bing", html);
+  } else {
+    console.log("[WebSearch] Bing found:", results.length, "results");
+  }
+  return results;
+}
+
+/** Parse Yahoo SERP HTML and return results array (used by fetch and browser fallback). */
+function parseYahooResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  const linkRegex =
+    /<a[^>]*href=["'](https?:\/\/[^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+  const avoidHosts =
+    /yahoo\.com|bing\.com|google\.com|doubleclick|yimg\.com|search\.yahoo/i;
+  let m;
+  const candidates = [];
+  while ((m = linkRegex.exec(html)) !== null) {
+    let resultUrl = m[1];
+    if (avoidHosts.test(resultUrl)) {
+      const resolved = resolveYahooRedirect(resultUrl);
+      if (resolved && !avoidHosts.test(resolved)) resultUrl = resolved;
+      else continue;
+    }
+    let title = m[2].replace(/<[^>]+>/g, "").trim();
+    title = decodeHtmlEntities(title);
+    if (!title) {
+      try {
+        title = new URL(resultUrl).hostname.replace("www.", "");
+      } catch {
+        continue;
+      }
+    }
+    if (title.length < 2 || title.length > 400) continue;
+    if (
+      /^(Sign in|Mail|News|Sports|Finance|Weather|Settings|Help)$/i.test(title)
+    )
+      continue;
+    candidates.push({ url: resultUrl, title, index: m.index });
+  }
+  if (
+    candidates.length === 0 &&
+    /#web|\.dd\s|class="[^"]*title[^"]*"/.test(html)
+  ) {
+    const altHref =
+      /<a[^>]*class="[^"]*(?:title|dd)[^"]*"[^>]*href=["'](https?:\/\/[^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+    altHref.lastIndex = 0;
+    while (
+      (m = altHref.exec(html)) !== null &&
+      candidates.length < numResults * 2
+    ) {
+      let resultUrl = m[1];
+      if (avoidHosts.test(resultUrl)) {
+        const resolved = resolveYahooRedirect(resultUrl);
+        if (resolved && !avoidHosts.test(resolved)) resultUrl = resolved;
+        else continue;
+      }
+      let title = m[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      if (!title)
+        try {
+          title = new URL(resultUrl).hostname.replace("www.", "");
+        } catch {
+          continue;
+        }
+      if (title.length < 2 || title.length > 400) continue;
+      candidates.push({ url: resultUrl, title, index: m.index });
+    }
+  }
+  for (const c of candidates) {
+    if (seenUrls.has(c.url)) continue;
+    seenUrls.add(c.url);
+    const context = html.substring(
+      c.index,
+      Math.min(html.length, c.index + 600),
+    );
+    const snippetMatch =
+      context.match(/<p[^>]*>([\s\S]*?)<\/p>/i) ||
+      context.match(/class="[^"]*desc[^"]*"[^>]*>([\s\S]*?)<\//);
+    let snippet = snippetMatch
+      ? snippetMatch[1].replace(/<[^>]+>/g, " ").trim()
+      : "";
+    snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 300);
+    let source = "";
+    try {
+      source = new URL(c.url).hostname.replace("www.", "");
+    } catch {}
+    results.push({
+      url: c.url,
+      title: c.title.slice(0, 300),
+      snippet: snippet || `From ${source}`,
+      source,
+    });
+    if (results.length >= numResults) break;
+  }
+  if (results.length < numResults && candidates.length === 0) {
+    const linkRegex2 =
+      /<a[^>]*href=["'](https?:\/\/[^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+    let m2;
+    while (
+      (m2 = linkRegex2.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      let resultUrl = m2[1];
+      if (avoidHosts.test(resultUrl)) {
+        const resolved = resolveYahooRedirect(resultUrl);
+        if (resolved && !avoidHosts.test(resolved)) resultUrl = resolved;
+        else continue;
+      }
+      if (seenUrls.has(resultUrl)) continue;
+      let title = m2[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      if (!title) {
+        try {
+          title = new URL(resultUrl).hostname.replace("www.", "");
+        } catch {
+          continue;
+        }
+      }
+      if (title.length < 1 || title.length > 500) continue;
+      if (
+        /^(Sign in|Mail|News|Sports|Finance|Weather|Settings|Help)$/i.test(
+          title,
+        )
+      )
+        continue;
+      seenUrls.add(resultUrl);
+      let source = "";
+      try {
+        source = new URL(resultUrl).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: resultUrl,
+        title: title.slice(0, 300),
+        snippet: `From ${source}`,
+        source,
+      });
+    }
+  }
+  if (results.length < numResults) {
+    const blocks = html.split(/class="[^"]*(?:algo|srch|dd)[^"]*"[^>]*>/i);
+    for (let i = 1; i < blocks.length && results.length < numResults; i++) {
+      const block = blocks[i].substring(0, 1500);
+      const linkMatch = block.match(
+        /<a[^>]*href=["'](https?:\/\/[^"']+)["'][^>]*>([\s\S]*?)<\/a>/i,
+      );
+      if (!linkMatch) continue;
+      let resultUrl = linkMatch[1];
+      if (avoidHosts.test(resultUrl)) {
+        const resolved = resolveYahooRedirect(resultUrl);
+        if (resolved && !avoidHosts.test(resolved)) resultUrl = resolved;
+        else continue;
+      }
+      let title = linkMatch[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      if (!title) {
+        try {
+          title = new URL(resultUrl).hostname.replace("www.", "");
+        } catch {
+          continue;
+        }
+      }
+      if (title.length < 2) continue;
+      if (seenUrls.has(resultUrl)) continue;
+      seenUrls.add(resultUrl);
+      let source = "";
+      try {
+        source = new URL(resultUrl).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: resultUrl,
+        title: title.slice(0, 300),
+        snippet: `From ${source}`,
+        source,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Search Yahoo (no API) - scrape SERP HTML. Retries with headless browser if fetch returns 0 results.
+ */
+async function searchYahoo(query, numResults) {
+  const url = `https://search.yahoo.com/search?p=${encodeURIComponent(query)}`;
+  const headers = getBrowserHeaders("https://search.yahoo.com");
+  headers["Sec-Fetch-Site"] = "none";
+
+  const response = await fetchWithTimeout(
+    url,
+    { headers, useWebSearchProxy: true },
+    12000,
+  );
+  let html = await response.text();
+  if (html.length < 2000) return [];
+
+  let results = parseYahooResults(html, numResults);
+
+  if (results.length === 0 && process.env.WEBSEARCH_USE_BROWSER !== "0") {
+    try {
+      console.log("[WebSearch] Yahoo retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      results = parseYahooResults(html, numResults);
+    } catch (e) {
+      console.log("[WebSearch] Yahoo browser fetch failed:", e?.message || e);
+    }
+  }
+
+  if (results.length === 0) {
+    const algoCount = (html.match(/class="[^"]*algo[^"]*"/gi) || []).length;
+    const linkCount = (html.match(/<a[^>]*href="https?:\/\//gi) || []).length;
+    console.log(
+      "[WebSearch] Yahoo: 0 results | htmlLen=",
+      html.length,
+      "| algo=",
+      algoCount,
+      "links=",
+      linkCount,
+    );
+    logZeroResultHtml("Yahoo", html);
+  }
+  console.log("[WebSearch] Yahoo found:", results.length, "results");
+  return results;
+}
+
+/** Parse Ecosia SERP HTML and return results array (used by fetch and browser fallback). */
+function parseEcosiaResults(html, numResults) {
+  const results = [];
+  const seenUrls = new Set();
+  const avoidEcosia = /ecosia\.org|duckduckgo\.com/i;
+  const resultBlocks = html.split(
+    /class="[^"]*(?:result|card|organic|abstract)[^"]*"[^>]*>/i,
+  );
+  for (let i = 1; i < resultBlocks.length && results.length < numResults; i++) {
+    const block = resultBlocks[i].substring(0, 2500);
+    const linkMatch = block.match(
+      /<a[^>]*href="(https?:\/\/[^"]+)"[^>]*>([\s\S]*?)<\/a>/i,
+    );
+    if (!linkMatch) continue;
+    const resultUrl = linkMatch[1];
+    if (avoidEcosia.test(resultUrl) || seenUrls.has(resultUrl)) continue;
+    let title = linkMatch[2].replace(/<[^>]+>/g, "").trim();
+    title = decodeHtmlEntities(title);
+    if (!title || title.length < 3) continue;
+    const snippetMatch =
+      block.match(
+        /class="[^"]*(?:snippet|description|abstract)[^"]*"[^>]*>([\s\S]*?)<\//i,
+      ) || block.match(/<p[^>]*>([\s\S]*?)<\/p>/i);
+    let snippet = snippetMatch
+      ? snippetMatch[1].replace(/<[^>]+>/g, " ").trim()
+      : "";
+    snippet = decodeHtmlEntities(snippet).replace(/\s+/g, " ").slice(0, 300);
+    seenUrls.add(resultUrl);
+    let source = "";
+    try {
+      source = new URL(resultUrl).hostname.replace("www.", "");
+    } catch {}
+    results.push({
+      url: resultUrl,
+      title: title.slice(0, 300),
+      snippet: snippet || `From ${source}`,
+      source,
+    });
+  }
+  if (results.length < numResults) {
+    const linkRegex = /<a[^>]*href="(https?:\/\/[^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+    let lm;
+    while (
+      (lm = linkRegex.exec(html)) !== null &&
+      results.length < numResults
+    ) {
+      const resultUrl = lm[1];
+      if (avoidEcosia.test(resultUrl) || seenUrls.has(resultUrl)) continue;
+      let title = lm[2].replace(/<[^>]+>/g, "").trim();
+      title = decodeHtmlEntities(title);
+      if (title.length < 3 || title.length > 250) continue;
+      if (/^(Ecosia|Plant|Privacy|Settings|Donate|Sign)/i.test(title)) continue;
+      seenUrls.add(resultUrl);
+      let source = "";
+      try {
+        source = new URL(resultUrl).hostname.replace("www.", "");
+      } catch {}
+      results.push({
+        url: resultUrl,
+        title: title.slice(0, 300),
+        snippet: `From ${source}`,
+        source,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Search Ecosia (no API) - scrape SERP HTML. Retries with headless browser if fetch returns 0 (e.g. Cloudflare).
+ */
+async function searchEcosia(query, numResults) {
+  const url = `https://www.ecosia.org/search?q=${encodeURIComponent(query)}`;
+  const headers = getBrowserHeaders("https://www.ecosia.org");
+  headers["Sec-Fetch-Site"] = "none";
+
+  const response = await fetchWithTimeout(
+    url,
+    { headers, useWebSearchProxy: true },
+    12000,
+  );
+  let html = await response.text();
+  if (html.length < 2000) return [];
+
+  let results = parseEcosiaResults(html, numResults);
+
+  // Skip browser retry when Cloudflare challenge is present (page never settles, would timeout)
+  const isCloudflareChallenge =
+    /Just a moment|Enable JavaScript and cookies|cf_chl_opt|cF_chl_opt/i.test(
+      html,
+    );
+  if (
+    results.length === 0 &&
+    process.env.WEBSEARCH_USE_BROWSER !== "0" &&
+    !isCloudflareChallenge
+  ) {
+    try {
+      console.log("[WebSearch] Ecosia retrying with headless browser...");
+      html = await fetchHtmlWithBrowser(url);
+      results = parseEcosiaResults(html, numResults);
+    } catch (e) {
+      console.log("[WebSearch] Ecosia browser fetch failed:", e?.message || e);
+    }
+  }
+
+  if (results.length === 0) {
+    const isCloudflare =
+      /Just a moment|Enable JavaScript and cookies|cf_chl_opt|cF_chl_opt/i.test(
+        html,
+      );
+    if (isCloudflare)
+      console.log(
+        "[WebSearch] Ecosia: Cloudflare challenge (page requires JavaScript; try VPN or browser)",
+      );
+    const resultBlockCount = (
+      html.match(/class="[^"]*(?:result|card|organic|abstract)[^"]*"/gi) || []
+    ).length;
+    const linkCount = (html.match(/<a[^>]*href="https?:\/\//gi) || []).length;
+    console.log(
+      "[WebSearch] Ecosia: 0 results | htmlLen=",
+      html.length,
+      "| resultBlocks=",
+      resultBlockCount,
+      "links=",
+      linkCount,
+    );
+    logZeroResultHtml("Ecosia", html);
+  }
+  console.log("[WebSearch] Ecosia found:", results.length, "results");
+  return results;
+}
+
+/**
+ * Fetch and extract text content from a URL
+ * Enhanced to better handle structured data like tables and lists
+ */
+export async function fetchUrlContent(url, timeoutMs = 15000) {
+  console.log("[FetchURL] Fetching:", url);
+
+  const response = await fetchWithTimeout(
+    url,
+    {
+      headers: {
+        "User-Agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+        Accept:
+          "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9",
+        "Cache-Control": "no-cache",
+      },
+    },
+    timeoutMs,
+  );
+
+  const html = await response.text();
+
+  // Extract title
+  const titleMatch = html.match(/<title[^>]*>([^<]*)<\/title>/i);
+  const title = titleMatch ? decodeHtmlEntities(titleMatch[1].trim()) : "";
+
+  // Extract tables and convert to readable format
+  let tables = [];
+  const tablePattern = /<table[^>]*>([\s\S]*?)<\/table>/gi;
+  let tableMatch;
+  while ((tableMatch = tablePattern.exec(html)) !== null && tables.length < 5) {
+    const tableHtml = tableMatch[1];
+    const rows = [];
+
+    // Extract headers
+    const headerPattern = /<th[^>]*>([\s\S]*?)<\/th>/gi;
+    const headers = [];
+    let headerMatch;
+    while ((headerMatch = headerPattern.exec(tableHtml)) !== null) {
+      headers.push(
+        decodeHtmlEntities(headerMatch[1].replace(/<[^>]+>/g, "").trim()),
+      );
+    }
+    if (headers.length > 0) {
+      rows.push(headers.join(" | "));
+      rows.push(headers.map(() => "---").join(" | "));
+    }
+
+    // Extract rows
+    const rowPattern = /<tr[^>]*>([\s\S]*?)<\/tr>/gi;
+    let rowMatch;
+    let rowCount = 0;
+    while ((rowMatch = rowPattern.exec(tableHtml)) !== null && rowCount < 50) {
+      const cellPattern = /<td[^>]*>([\s\S]*?)<\/td>/gi;
+      const cells = [];
+      let cellMatch;
+      while ((cellMatch = cellPattern.exec(rowMatch[1])) !== null) {
+        cells.push(
+          decodeHtmlEntities(cellMatch[1].replace(/<[^>]+>/g, "").trim()),
+        );
+      }
+      if (cells.length > 0) {
+        rows.push(cells.join(" | "));
+        rowCount++;
+      }
+    }
+
+    if (rows.length > 1) {
+      tables.push(rows.join("\n"));
+    }
+  }
+
+  // Extract lists (ul/ol) and convert to readable format
+  let lists = [];
+  const listPattern = /<(?:ul|ol)[^>]*>([\s\S]*?)<\/(?:ul|ol)>/gi;
+  let listMatch;
+  while ((listMatch = listPattern.exec(html)) !== null && lists.length < 10) {
+    const listHtml = listMatch[1];
+    const items = [];
+    const itemPattern = /<li[^>]*>([\s\S]*?)<\/li>/gi;
+    let itemMatch;
+    while (
+      (itemMatch = itemPattern.exec(listHtml)) !== null &&
+      items.length < 30
+    ) {
+      const itemText = decodeHtmlEntities(
+        itemMatch[1]
+          .replace(/<[^>]+>/g, " ")
+          .replace(/\s+/g, " ")
+          .trim(),
+      );
+      if (itemText.length > 5 && itemText.length < 500) {
+        items.push(`• ${itemText}`);
+      }
+    }
+    if (items.length > 2) {
+      lists.push(items.join("\n"));
+    }
+  }
+
+  // Convert main HTML to text (removing scripts, styles, nav, footer)
+  let text = html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<nav[^>]*>[\s\S]*?<\/nav>/gi, "")
+    .replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, "")
+    .replace(/<header[^>]*>[\s\S]*?<\/header>/gi, "")
+    .replace(/<aside[^>]*>[\s\S]*?<\/aside>/gi, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    // Preserve some structure
+    .replace(/<\/h[1-6]>/gi, "\n\n")
+    .replace(/<\/p>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/div>/gi, "\n")
+    .replace(/<\/li>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\n\s*\n\s*\n/g, "\n\n")
+    .replace(/[ \t]+/g, " ")
+    .trim();
+
+  // Limit main text but keep more for data-rich pages
+  const maxTextLength = 12000;
+  if (text.length > maxTextLength) {
+    text = text.slice(0, maxTextLength) + "\n\n... (content truncated)";
+  }
+
+  // Build the output
+  let output = title ? `Title: ${title}\n\n` : "";
+
+  // Include structured data if found
+  if (tables.length > 0) {
+    output += `=== TABLES FOUND (${tables.length}) ===\n\n`;
+    tables.forEach((table, i) => {
+      output += `Table ${i + 1}:\n${table}\n\n`;
+    });
+  }
+
+  if (lists.length > 0 && lists.some((l) => l.split("\n").length > 3)) {
+    output += `=== LISTS FOUND ===\n\n`;
+    lists
+      .filter((l) => l.split("\n").length > 3)
+      .slice(0, 5)
+      .forEach((list, i) => {
+        output += `List ${i + 1}:\n${list}\n\n`;
+      });
+  }
+
+  output += `=== PAGE CONTENT ===\n\n${text}`;
+
+  console.log(
+    "[FetchURL] Extracted",
+    output.length,
+    "chars,",
+    tables.length,
+    "tables,",
+    lists.length,
+    "lists",
+  );
+  return output;
+}
+
+/**
+ * Deep research - search and fetch multiple pages
+ */
+export async function deepWebResearch(query, numPages = 5) {
+  const results = { success: false, query, pages: [] };
+
+  try {
+    const searchResults = await performWebSearch(query, numPages + 2);
+    if (searchResults.length === 0) {
+      results.error = "No search results found";
+      return results;
+    }
+
+    for (const result of searchResults) {
+      if (results.pages.length >= numPages) break;
+      try {
+        const content = await fetchUrlContent(result.url, 10000);
+        if (content && content.length > 100) {
+          results.pages.push({
+            title: result.title,
+            url: result.url,
+            content: content.slice(0, 5000),
+            excerpt: content.slice(0, 500),
+          });
+        }
+      } catch (err) {
+        // Include result even if fetch fails
+        results.pages.push({
+          title: result.title,
+          url: result.url,
+          content: result.snippet || "",
+          excerpt: result.snippet || "",
+        });
+      }
+    }
+
+    results.success = results.pages.length > 0;
+    return results;
+  } catch (err) {
+    console.error("[DeepResearch] Error:", err);
+    return results;
+  }
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+/**
+ * Escape special regex characters in a string
+ * @param {string} string - String to escape
+ * @returns {string} - Escaped string safe for use in RegExp
+ */
+function escapeRegExp(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Generate a simple unified diff-like output for display
+ * @param {string} oldStr - Original text
+ * @param {string} newStr - New text
+ * @param {string} filePath - Path to the file being edited
+ * @returns {string} - Diff-like output
+ */
+function generateSimpleDiff(oldStr, newStr, filePath) {
+  const oldLines = oldStr.split("\n");
+  const newLines = newStr.split("\n");
+
+  let diff = `--- a/${filePath}\n+++ b/${filePath}\n`;
+
+  // Add context with line markers
+  const maxOldLines = Math.min(oldLines.length, 20); // Limit for readability
+  const maxNewLines = Math.min(newLines.length, 20);
+
+  diff += `@@ -1,${oldLines.length} +1,${newLines.length} @@\n`;
+
+  // Show removed lines (old content)
+  for (let i = 0; i < maxOldLines; i++) {
+    diff += `-${oldLines[i]}\n`;
+  }
+  if (oldLines.length > maxOldLines) {
+    diff += `... (${oldLines.length - maxOldLines} more lines removed)\n`;
+  }
+
+  // Show added lines (new content)
+  for (let i = 0; i < maxNewLines; i++) {
+    diff += `+${newLines[i]}\n`;
+  }
+  if (newLines.length > maxNewLines) {
+    diff += `... (${newLines.length - maxNewLines} more lines added)\n`;
+  }
+
+  return diff;
+}
+
+/**
+ * Resolve path with home directory expansion and normalization
+ * @param {string} path - Path to resolve
+ * @returns {string} - Normalized absolute path
+ */
+function resolvePath(path) {
+  if (!path || typeof path !== "string") {
+    throw new Error("Invalid path");
+  }
+
+  let resolved;
+  if (path.startsWith("~")) {
+    resolved = join(homedir(), path.slice(1));
+  } else {
+    resolved = resolve(path);
+  }
+
+  // Normalize to remove . and .. components
+  return normalize(resolved);
+}
+
+/**
+ * Check if a path contains path traversal attempts
+ * @param {string} inputPath - Original user-provided path
+ * @param {string} resolvedPath - Resolved absolute path
+ * @returns {boolean} - True if path traversal detected
+ */
+function hasPathTraversal(inputPath, resolvedPath) {
+  // Check for obvious traversal patterns in input
+  if (inputPath.includes("..")) {
+    // Get the expected directory
+    const baseDir = process.cwd();
+    const inputResolved = resolve(baseDir, inputPath);
+
+    // If resolving .. would take us outside the base, it's traversal
+    if (
+      !inputResolved.startsWith(baseDir) &&
+      !inputPath.startsWith("/") &&
+      !inputPath.startsWith("~")
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a path is in the blocked list
+ * @param {string} path - Resolved absolute path
+ * @returns {boolean} - True if path is blocked
+ */
+function isBlockedPath(path) {
+  const normalizedPath = normalize(path).toLowerCase();
+
+  for (const blocked of BLOCKED_PATHS) {
+    if (normalizedPath.includes(blocked.toLowerCase())) {
+      return true;
+    }
+  }
+
+  // Also check if it's a symlink pointing to a blocked path
+  try {
+    if (existsSync(path)) {
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) {
+        const realPath = realpathSync(path);
+        for (const blocked of BLOCKED_PATHS) {
+          if (realPath.toLowerCase().includes(blocked.toLowerCase())) {
+            return true;
+          }
+        }
+      }
+    }
+  } catch (err) {
+    // If we can't stat, let the actual operation fail
+  }
+
+  return false;
+}
+
+/**
+ * Check if path is allowed for reading
+ * @param {string} path - Resolved absolute path
+ * @param {object} config - Configuration with permissions
+ * @throws {Error} - If path is not allowed
+ */
+function checkReadPermission(path, config) {
+  // Check against blocked paths
+  if (isBlockedPath(path)) {
+    throw new Error(`Access denied: Cannot read sensitive path`);
+  }
+
+  // Check config-based restrictions if provided
+  if (config?.permissions?.fileRead === false) {
+    throw new Error("File read access is disabled in configuration");
+  }
+
+  // Check allowed paths if specified
+  if (config?.permissions?.allowedReadPaths) {
+    const allowed = config.permissions.allowedReadPaths.some((allowedPath) => {
+      const resolvedAllowed = resolvePath(allowedPath);
+      return path.startsWith(resolvedAllowed);
+    });
+
+    if (!allowed) {
+      throw new Error(`Access denied: Path not in allowed read paths`);
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Check if path is allowed for writing
+ * @param {string} path - Resolved absolute path
+ * @param {object} config - Configuration with permissions
+ * @throws {Error} - If path is not allowed
+ */
+function checkWritePermission(path, config) {
+  // Check against blocked paths
+  if (isBlockedPath(path)) {
+    throw new Error(`Access denied: Cannot write to sensitive path`);
+  }
+
+  // Check config-based restrictions if provided
+  if (config?.permissions?.fileWrite === false) {
+    throw new Error("File write access is disabled in configuration");
+  }
+
+  // Check allowed paths if specified
+  if (config?.permissions?.allowedWritePaths) {
+    const allowed = config.permissions.allowedWritePaths.some((allowedPath) => {
+      const resolvedAllowed = resolvePath(allowedPath);
+      return path.startsWith(resolvedAllowed);
+    });
+
+    if (!allowed) {
+      throw new Error(`Access denied: Path not in allowed write paths`);
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validate and sanitize a shell command
+ * @param {string} command - Command to validate
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function validateCommand(command) {
+  if (!command || typeof command !== "string") {
+    return { valid: false, reason: "Invalid command" };
+  }
+
+  // Check against dangerous patterns
+  for (const pattern of DANGEROUS_COMMAND_PATTERNS) {
+    if (pattern.test(command)) {
+      return { valid: false, reason: "Command matches dangerous pattern" };
+    }
+  }
+
+  // Check for null bytes (command injection)
+  if (command.includes("\0")) {
+    return { valid: false, reason: "Command contains null bytes" };
+  }
+
+  // Check for shell escape attempts
+  if (command.includes("$(") || command.includes("`")) {
+    // Allow backticks and $() for legitimate use, but warn
+    console.warn(
+      "[validateCommand] Command contains shell substitution - use with caution",
+    );
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Parse a single reversible shell command for undo on regeneration (Strategy 1).
+ * Returns { op, path?, path_src?, path_dest?, cwd } or null if not reversible.
+ * Paths are resolved against currentWorkingDirectory and must stay within it.
+ */
+function parseReversibleCommand(command) {
+  if (!command || typeof command !== "string") return null;
+  const trimmed = command.trim();
+  if (trimmed.includes("|") || trimmed.includes(";")) return null;
+
+  const cwd = currentWorkingDirectory;
+  const resolveSafe = (arg) => {
+    const resolved = resolve(cwd, arg);
+    if (!resolved.startsWith(cwd) && resolved !== cwd) return null;
+    return resolved;
+  };
+
+  // mkdir [ -p ] path
+  const mkdirMatch = trimmed.match(/^mkdir\s+(-p\s+)?(.+)$/);
+  if (mkdirMatch) {
+    const path = resolveSafe(mkdirMatch[2].trim());
+    if (path == null) return null;
+    return { op: "mkdir", path, cwd };
+  }
+
+  // touch path
+  const touchMatch = trimmed.match(/^touch\s+(.+)$/);
+  if (touchMatch) {
+    const path = resolveSafe(touchMatch[1].trim());
+    if (path == null) return null;
+    return { op: "touch", path, cwd };
+  }
+
+  // cp [ -r ] src dest
+  const cpMatch = trimmed.match(/^cp\s+(-[rR]\s+)?(\S+)\s+(\S+)$/);
+  if (cpMatch) {
+    const pathDest = resolveSafe(cpMatch[3]);
+    if (pathDest == null) return null;
+    return { op: "cp", path_dest: pathDest, cwd };
+  }
+
+  // mv src dest
+  const mvMatch = trimmed.match(/^mv\s+(\S+)\s+(\S+)$/);
+  if (mvMatch) {
+    const pathSrc = resolveSafe(mvMatch[1]);
+    const pathDest = resolveSafe(mvMatch[2]);
+    if (pathSrc == null || pathDest == null) return null;
+    return { op: "mv", path_src: pathSrc, path_dest: pathDest, cwd };
+  }
+
+  return null;
+}
+
+/**
+ * Get timeout for a specific tool
+ * @param {string} toolName - Name of the tool
+ * @returns {number} - Timeout in milliseconds
+ */
+function getToolTimeout(toolName) {
+  return TOOL_TIMEOUTS[toolName] || DEFAULT_TOOL_TIMEOUT;
+}
+
+/**
+ * Tools that support snapshot callbacks for undo on regeneration
+ */
+const SNAPSHOT_TOOLS = ["write_file", "edit_file"];
+
+/**
+ * Execute a tool by name with timeout and error handling
+ * @param {string} name - Tool name
+ * @param {object} args - Tool arguments
+ * @param {object} config - Configuration
+ * @param {function} snapshotFn - Optional callback for capturing file snapshots (for undo on regeneration)
+ * @param {function} shellUndoFn - Optional callback for recording reversible shell commands (Strategy 1)
+ * @param {string|null} toolCallId - Optional ID for this tool call (for snapshot/shell undo traceability)
+ * @returns {Promise<string>} - Tool result or error message
+ */
+export async function executeTool(
+  name,
+  args,
+  config,
+  snapshotFn = null,
+  shellUndoFn = null,
+  toolCallId = null,
+) {
+  const tool = TOOLS[name];
+  if (!tool) {
+    return `Error: Unknown tool "${name}"`;
+  }
+
+  // Validate required parameters
+  for (const [param, spec] of Object.entries(tool.parameters || {})) {
+    if (spec.required && (args[param] === undefined || args[param] === null)) {
+      return `Error: Missing required parameter "${param}" for tool "${name}"`;
+    }
+  }
+
+  // Execute with timeout
+  const timeout = getToolTimeout(name);
+
+  // Only pass snapshotFn to tools that support it; wrap to pass toolCallId (Strategy 3)
+  const shouldPassSnapshot = SNAPSHOT_TOOLS.includes(name) && snapshotFn;
+  const wrappedSnapshotFn =
+    shouldPassSnapshot && toolCallId
+      ? (snapshot) => snapshotFn(snapshot, toolCallId)
+      : snapshotFn;
+  // execute_command gets shellUndoFn for reversible-command undo (Strategy 3: pass toolCallId)
+  const shouldPassShellUndo = name === "execute_command" && shellUndoFn;
+  const wrappedShellUndoFn =
+    shouldPassShellUndo && toolCallId
+      ? (entry) => shellUndoFn(entry, toolCallId)
+      : shellUndoFn;
+
+  const executeArgs = () => {
+    if (shouldPassSnapshot)
+      return tool.execute(args, config, wrappedSnapshotFn);
+    if (shouldPassShellUndo)
+      return tool.execute(args, config, wrappedShellUndoFn);
+    return tool.execute(args, config);
+  };
+
+  try {
+    const result = await Promise.race([
+      executeArgs(),
+      new Promise((_, reject) =>
+        setTimeout(
+          () =>
+            reject(
+              new Error(`Tool "${name}" timed out after ${timeout / 1000}s`),
+            ),
+          timeout,
+        ),
+      ),
+    ]);
+
+    return result;
+  } catch (err) {
+    // Handle permission errors specifically
+    if (err.message.includes("Access denied")) {
+      console.warn(`[executeTool] Permission denied for ${name}:`, err.message);
+      return `Error: ${err.message}`;
+    }
+
+    // Handle timeout
+    if (err.message.includes("timed out")) {
+      console.warn(`[executeTool] Timeout for ${name}:`, err.message);
+      return `Error: ${err.message}`;
+    }
+
+    // Generic error
+    console.error(`[executeTool] Error executing ${name}:`, err);
+    return `Error executing ${name}: ${err.message}`;
+  }
+}
+
+/**
+ * Get tool descriptions for system prompt
+ */
+export function getToolDescriptions() {
+  return Object.entries(TOOLS)
+    .map(([name, tool]) => {
+      const params = Object.entries(tool.parameters || {})
+        .map(
+          ([p, spec]) => `${p}${spec.required ? "" : "?"}: ${spec.description}`,
+        )
+        .join(", ");
+      return `- ${name}(${params}): ${tool.description}`;
+    })
+    .join("\n");
+}
+
+export default {
+  TOOLS,
+  executeTool,
+  getToolDescriptions,
+  getAgentWorkingDirectory,
+  setAgentWorkingDirectory,
+  resetAgentWorkingDirectory,
+};