@acmecloud/core 1.0.2

package/src/tools/index.ts

@@ -0,0 +1,1112 @@
+import { tool as createTool } from "ai";
+import { z } from "zod";
+import * as fs from "fs/promises";
+import { existsSync, createReadStream } from "fs";
+import { exec } from "child_process";
+import { promisify } from "util";
+import path from "path";
+import { pathToFileURL } from "url";
+import { createInterface } from "readline";
+import TurndownService from "turndown";
+import * as diff from "diff";
+import { replaceCode } from "./edit.js";
+import { getLspClientForFile } from "./lsp-client.js";
+import { executeBatch, BATCH_WHITELIST } from "./batch.js";
+import { executeBrowserAction } from "./browser.js";
+
+const execAsync = promisify(exec);
+
+// ── Constants (from opencode patterns) ──
+const DEFAULT_READ_LIMIT = 2000;
+const MAX_LINE_LENGTH = 2000;
+const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`;
+const COMMAND_TIMEOUT = 120_000; // 2 minutes
+
+// Directories to ignore in list_dir (from opencode's ls.ts)
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  "__pycache__",
+  ".git",
+  "dist",
+  "build",
+  "target",
+  "vendor",
+  "bin",
+  "obj",
+  ".idea",
+  ".vscode",
+  ".cache",
+  "coverage",
+  ".venv",
+  "venv",
+  "env",
+  "tmp",
+  "temp",
+  "logs",
+  ".zig-cache",
+  "zig-out",
+]);
+
+// ── Tool Definitions ──
+interface ToolDef {
+  description: string;
+  parameters: z.ZodType<any>;
+}
+
+export const toolDefinitions: Record<string, ToolDef> = {
+  read_file: {
+    description: [
+      "Read a file from the local filesystem with line-based access.",
+      "",
+      "Parameters:",
+      "- filePath: Required. Absolute or relative path to the file.",
+      "- offset: Line number to start from (1-indexed, default: 1).",
+      "- limit: Max lines to read (default: 2000).",
+      "- infoOnly: If true, only return file info (line count, size) without content.",
+      "",
+      "Tips:",
+      "- Use infoOnly=true first to check file size and line count before reading.",
+      "- For large files, read in chunks using offset and limit.",
+      "- Lines are numbered starting from 1.",
+      "- Lines longer than 2000 chars are truncated.",
+      "- You can read multiple files in parallel using the batch tool.",
+    ].join("\n"),
+    parameters: z.object({
+      filePath: z.string().describe("The path to the file to read. Required."),
+      offset: z
+        .number()
+        .optional()
+        .describe("Line number to start from (1-indexed, default: 1)"),
+      limit: z
+        .number()
+        .optional()
+        .describe("Max number of lines to read (default: 2000)"),
+      infoOnly: z
+        .boolean()
+        .optional()
+        .describe("If true, only return file info without content"),
+    }),
+  },
+  webfetch: {
+    description: [
+      "Fetch content from a URL.",
+      "Best used for reading online documentation, API references, or web pages.",
+      "Automatically converts HTML to clean Markdown by default to save tokens.",
+    ].join("\n"),
+    parameters: z.object({
+      url: z
+        .string()
+        .url()
+        .optional()
+        .describe(
+          "The URL to fetch content from (must start with http:// or https://). Do NOT omit this.",
+        ),
+      format: z
+        .enum(["markdown", "text", "html"])
+        .optional()
+        .describe("Format to return (default: markdown)"),
+    }),
+  },
+  websearch: {
+    description: [
+      "Perform a web search using the Exa search engine.",
+      "Best used for finding general information, recent news, or broad topics.",
+    ].join("\n"),
+    parameters: z.object({
+      query: z
+        .string()
+        .optional()
+        .describe("The search query. Do NOT omit this."),
+      numResults: z
+        .number()
+        .optional()
+        .describe("Number of results to return (default: 8)"),
+    }),
+  },
+  codesearch: {
+    description: [
+      "Search for code snippets, API documentation, and technical references.",
+      'Uses Exa optimized for coding queries. E.g., "React useState examples", "TypeScript omit utility".',
+    ].join("\n"),
+    parameters: z.object({
+      query: z
+        .string()
+        .optional()
+        .describe("The technical search query. Do NOT omit this."),
+    }),
+  },
+  grep_search: {
+    description: [
+      "Search for a regex pattern within files in a directory using ripgrep.",
+      "Returns the file paths and line numbers of the matches.",
+      "Requires the pattern to search for.",
+    ].join("\n"),
+    parameters: z.object({
+      pattern: z
+        .string()
+        .optional()
+        .describe(
+          "The regex pattern to search for in file contents. Do NOT omit this.",
+        ),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "The directory to search in. Defaults to the current working directory.",
+        ),
+      include: z
+        .string()
+        .optional()
+        .describe(
+          'File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")',
+        ),
+    }),
+  },
+  edit_file: {
+    description: [
+      "Edit a specific chunk of code in an existing file using fuzzy replacement.",
+      "You provide the exact old code text block to replace (oldString), and the new code to replace it with (newString).",
+      "This tool is vastly safer and more token-efficient than replacing the whole file with write_file.",
+      "Automatic Safety: After editing, the tool automatically runs LSP diagnostic checks and reports any new errors or warnings introduced by the change.",
+      "Requires an absolute path or a path relative to CWD.",
+    ].join("\n"),
+    parameters: z.object({
+      filePath: z
+        .string()
+        .optional()
+        .describe("The path to the file to modify. Do NOT omit this."),
+      oldString: z
+        .string()
+        .optional()
+        .describe(
+          "The block of text or code to replace. Provide enough surrounding code so the match is unique in the file. Do NOT omit this.",
+        ),
+      newString: z
+        .string()
+        .optional()
+        .describe(
+          "The new block of text or code to replace it with. Must be different from oldString. Do NOT omit this.",
+        ),
+      replaceAll: z
+        .boolean()
+        .optional()
+        .describe(
+          "If true, replaces all occurrences instead of throwing an error when multiple matches are found (default: false)",
+        ),
+    }),
+  },
+  lsp: {
+    description: [
+      "Language Server Protocol integration for Deep Code Understanding.",
+      "Supported languages: TypeScript/JavaScript, Python, Go, Rust.",
+      "Allows you to find where a variable/function is defined, where it gets used, or what its type signature is.",
+    ].join("\n"),
+    parameters: z.object({
+      operation: z
+        .enum(["goToDefinition", "findReferences", "hover"])
+        .optional()
+        .describe("The LSP operation to perform. Do NOT omit this."),
+      filePath: z
+        .string()
+        .optional()
+        .describe(
+          "The path to the file you want to interrogate. Do NOT omit this.",
+        ),
+      line: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("The line number in editors (1-based). Do NOT omit this."),
+      character: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(
+          "The character column offset in editors (1-based). Do NOT omit this.",
+        ),
+    }),
+  },
+  write_file: {
+    description: [
+      "Write content to a file. Creates parent directories if needed.",
+      "The filePath parameter must be provided.",
+      "Use absolute or relative paths (resolved against CWD).",
+    ].join("\n"),
+    parameters: z.object({
+      filePath: z
+        .string()
+        .min(1)
+        .describe("The path to the file to write (required)"),
+      content: z
+        .string()
+        .optional()
+        .describe("The content to write into the file. Do NOT omit this."),
+    }),
+  },
+  run_command: {
+    description: [
+      "Run a shell command on the host machine.",
+      "The working directory defaults to the current project directory.",
+      `Platform: ${process.platform}. Use platform-appropriate commands (e.g., 'Get-Content' instead of 'cat' on Windows).`,
+      "On Windows, commands are executed via PowerShell for maximum compatibility.",
+      "Commands that take longer than 2 minutes will be killed.",
+      "Dangerous commands (e.g. destructive actions, system changes) will require manual user approval.",
+      "Use this for system operations, builds, tests, and git commands.",
+    ].join("\n"),
+    parameters: z.object({
+      command: z
+        .string()
+        .describe("The shell command to execute. Do NOT omit this."),
+      description: z
+        .string()
+        .optional()
+        .describe("Brief description of what this command does (5-10 words)"),
+      riskLevel: z
+        .enum(["low", "medium", "high"])
+        .describe(
+          "Self-assessed risk level of the command. low: read-only/no-side-effect, medium: build/complex-read, high: destructive/system-change.",
+        ),
+      cwd: z
+        .string()
+        .optional()
+        .describe("Working directory to run the command in"),
+    }),
+  },
+  list_dir: {
+    description: [
+      "List directory contents as a tree structure.",
+      "Automatically ignores common non-essential directories (node_modules, .git, dist, etc.).",
+      'Use this tool instead of running "ls" or "dir" commands.',
+      "The path defaults to the current working directory if not specified.",
+    ].join("\n"),
+    parameters: z.object({
+      path: z
+        .string()
+        .optional()
+        .describe("The path to the directory to list (defaults to CWD)"),
+    }),
+  },
+  switch_mode: {
+    description: [
+      "Switch the agent mode to plan or code mode.",
+      "Use this when transitioning phases as instructed by your system prompt.",
+    ].join("\n"),
+    parameters: z.object({
+      mode: z
+        .enum(["plan", "code"])
+        .optional()
+        .describe("The target mode to switch to. Do NOT omit this."),
+      contextFile: z
+        .string()
+        .optional()
+        .describe(
+          "The task checklist or design document to focus on (usually for code mode).",
+        ),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          "Explanation for why the mode is being switched. Do NOT omit this.",
+        ),
+    }),
+  },
+  batch: {
+    description: [
+      "Execute multiple read-only tools in parallel and return their combined output.",
+      "Use this to speed up research, dependency analysis, or searching across multiple locations.",
+      `Allowed tools: ${Array.from(BATCH_WHITELIST).join(", ")}.`,
+      "",
+      "IMPORTANT: Each call MUST have 'name' (tool name) and 'arguments' (tool parameters object).",
+      "Example format:",
+      `{ "calls": [`,
+      `  { "name": "read_file", "arguments": { "filePath": "/path/to/file.ts" } },`,
+      `  { "name": "list_dir", "arguments": { "path": "/path/to/dir" } }`,
+      `] }`,
+    ].join("\n"),
+    parameters: z.object({
+      calls: z
+        .array(
+          z.object({
+            name: z
+              .string()
+              .describe("The tool name, e.g. 'read_file', 'list_dir'"),
+            arguments: z
+              .record(z.string(), z.any())
+              .describe(
+                'The tool arguments as an object, e.g. { "filePath": "/path/to/file" }',
+              ),
+          }),
+        )
+        .describe("List of tool calls to execute in parallel."),
+    }),
+  },
+  browser_action: {
+    description: [
+      "Perform actions in a headless browser (headless Chromium).",
+      "Actions: navigate, screenshot, click, type, scroll.",
+      "Visual Feedback: If a vision model is configured, screenshots will be automatically analyzed and described.",
+      "Use this to test web applications, check UI layouts, or read web-only content.",
+    ].join("\n"),
+    parameters: z.object({
+      action: z.enum(["navigate", "screenshot", "click", "type", "scroll"]),
+      url: z.string().optional().describe("URL to navigate to."),
+      selector: z.string().optional().describe("CSS selector for click/type."),
+      text: z.string().optional().describe("Text to type."),
+    }),
+  },
+};
+
+/**
+ * Identify dangerous or destructive commands that should require user approval.
+ */
+export function isCommandSafe(command: string): boolean {
+  const lower = command.toLowerCase().trim();
+
+  const dangerousPatterns = [
+    // Destructive (Linux/Unix)
+    /\brm\b.*(-rf|-r\b|-f\b)/i,
+    /\bmkfs\b/i,
+    /\bdd\b.*\bof=\/dev\/(sd[a-z]|nvme|mmcblk)/i,
+
+    // Destructive (Windows)
+    /\bdel\b.*\s+\/[sq]+\b/i,
+    /\brd\b.*\s+\/[sq]+\b/i,
+    /\bformat\b\s+[a-z]:/i,
+    /\bsc\s+delete\b/i,
+    /\bbcdedit\b/i,
+
+    // System configuration/control
+    /\breg\b\s+(delete|add)\b/i,
+    /\bshutdown\b/i,
+    /\breboot\b/i,
+    /\bnet\s+(user|localgroup|share)\b/i,
+    /\bnetsh\b/i,
+    /\bkill\b/i,
+    /\btaskkill\b/i,
+    /\bstop-service\b/i,
+    /\bremove-item\b.*(-recurse|-force|-confirm)/i,
+    /\b(clear-disk|initialize-disk|format-volume|remove-partition)\b/i,
+    /\bset-executionpolicy\b.*\b(unrestricted|bypass)\b/i,
+
+    // Permission/Ownership changes
+    /\bchmod\b.*\b777\b/,
+    /\bchown\b/i,
+    /\bicacls\b/i,
+    /\btakeown\b/i,
+
+    // Shell piping (Remote execution risk)
+    /\|\s*(bash|sh|powershell|pwsh|cmd)(\s|$)/i,
+    />\s*(bash|sh|powershell|pwsh|cmd)(\s|$)/i,
+    /\bcurl\b.*\s+\|\s*(bash|sh|powershell|pwsh|cmd)\b/i,
+    /\bwget\b.*\s+\|\s*(bash|sh|powershell|pwsh|cmd)\b/i,
+    /\biex\b/i, // PowerShell Invoke-Expression
+
+    // Cloud & Operations Tools (Destructive)
+    /\bdocker\b.*\s+(rm|stop|rmi|prune|kill)\b/i,
+    /\bkubectl\b.*\s+(delete|scale|patch|edit)\b/i,
+    /\bterraform\b.*\s+(destroy|apply)\b/i,
+    /\bgcloud\b.*\s+(delete|remove|stop)\b/i,
+    /\baws\b.*\s+(delete|terminate|stop)\b/i,
+
+    // Credential/Identity Access
+    /\.ssh\//,
+    /\.aws\//,
+    /\.kube\//,
+    /\.env\b/i,
+    /\b(npm|git|gh)\b.*\s+(login|auth|config)\b/i,
+  ];
+
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(lower)) return false;
+  }
+
+  return true;
+}
+export const toolExecutors: Record<string, (args: any) => Promise<string>> = {
+  read_file: async (args) => {
+    try {
+      const filePath = args.filePath || args.path;
+      if (!filePath)
+        return `Error: The "filePath" argument is required. Please provide the file path.`;
+
+      const resolved = path.resolve(process.cwd(), filePath);
+
+      // Check if file exists
+      try {
+        const stat = await fs.stat(resolved);
+        if (stat.isDirectory()) {
+          // If it's a directory, delegate to list_dir
+          return toolExecutors.list_dir!({ path: filePath });
+        }
+
+        // infoOnly mode: just return file info
+        if (args.infoOnly) {
+          const stream = createReadStream(resolved, { encoding: "utf8" });
+          const rl = createInterface({ input: stream, crlfDelay: Infinity });
+          let totalLines = 0;
+          try {
+            for await (const _ of rl) {
+              totalLines++;
+            }
+          } finally {
+            rl.close();
+            stream.destroy();
+          }
+          return `<file-info>
+<path>${resolved}</path>
+<size>${stat.size} bytes</size>
+<lines>${totalLines}</lines>
+</file-info>`;
+        }
+      } catch {
+        // Try to suggest similar files
+        const dir = path.dirname(resolved);
+        const base = path.basename(resolved).toLowerCase();
+        try {
+          const entries = await fs.readdir(dir);
+          const suggestions = entries
+            .filter(
+              (e) =>
+                e.toLowerCase().includes(base) ||
+                base.includes(e.toLowerCase()),
+            )
+            .slice(0, 3);
+          if (suggestions.length > 0) {
+            return `Error: File not found: ${resolved}\n\nDid you mean one of these?\n${suggestions.map((s) => path.join(dir, s)).join("\n")}`;
+          }
+        } catch {
+          /* ignore */
+        }
+        return `Error: File not found: ${resolved}`;
+      }
+
+      // Read file with line numbers (opencode pattern)
+      const limit = args.limit ?? DEFAULT_READ_LIMIT;
+      const offset = args.offset ?? 1;
+      const start = offset - 1;
+
+      const stream = createReadStream(resolved, { encoding: "utf8" });
+      const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+      const lines: string[] = [];
+      let totalLines = 0;
+      let hasMore = false;
+
+      try {
+        for await (const text of rl) {
+          totalLines++;
+          if (totalLines <= start) continue;
+
+          if (lines.length >= limit) {
+            hasMore = true;
+            continue;
+          }
+
+          const line =
+            text.length > MAX_LINE_LENGTH
+              ? text.substring(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX
+              : text;
+          lines.push(line);
+        }
+      } finally {
+        rl.close();
+        stream.destroy();
+      }
+
+      // Format output with line numbers (opencode-style)
+      const numbered = lines.map((line, i) => `${i + offset}: ${line}`);
+      const lastLine = offset + lines.length - 1;
+
+      let output = `<path>${resolved}</path>\n<content>\n`;
+      output += numbered.join("\n");
+
+      if (hasMore) {
+        output += `\n\n(Showing lines ${offset}-${lastLine} of ${totalLines}. Use offset=${lastLine + 1} to continue.)`;
+      } else {
+        output += `\n\n(End of file - total ${totalLines} lines)`;
+      }
+      output += "\n</content>";
+
+      return output;
+    } catch (err: any) {
+      return `Error reading file: ${err.message}`;
+    }
+  },
+
+  webfetch: async (args) => {
+    try {
+      const url = args.url;
+      if (!url) return 'Error: The "url" argument is required';
+      const format = args.format || "markdown";
+      if (!url?.startsWith("http://") && !url?.startsWith("https://")) {
+        return "Error: URL must start with http:// or https://";
+      }
+
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout
+
+      const headers = {
+        "User-Agent":
+          "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
+        Accept:
+          format === "markdown"
+            ? "text/markdown, text/html, */*"
+            : "text/html, */*",
+        "Accept-Language": "en-US,en;q=0.9",
+      };
+
+      let response = await fetch(url, { signal: controller.signal, headers });
+
+      // Handle Cloudflare challenge fingerprint mismatch
+      if (
+        response.status === 403 &&
+        response.headers.get("cf-mitigated") === "challenge"
+      ) {
+        response = await fetch(url, {
+          signal: controller.signal,
+          headers: { ...headers, "User-Agent": "acmecode" },
+        });
+      }
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        return `Error: Request failed with status ${response.status} ${response.statusText}`;
+      }
+
+      const contentType = response.headers.get("content-type") || "";
+      const mime = contentType.split(";")[0]?.trim().toLowerCase();
+
+      if (
+        mime.startsWith("image/") ||
+        mime.startsWith("video/") ||
+        mime.startsWith("audio/")
+      ) {
+        return `Error: Cannot fetch binary media files (${mime})`;
+      }
+
+      // Ensure response isn't massive (limit 5MB)
+      const contentLength = response.headers.get("content-length");
+      if (contentLength && parseInt(contentLength) > 5 * 1024 * 1024) {
+        return "Error: Response too large (exceeds 5MB)";
+      }
+
+      const content = await response.text();
+
+      if (format === "markdown" && contentType.includes("text/html")) {
+        const turndownService = new TurndownService({
+          headingStyle: "atx",
+          codeBlockStyle: "fenced",
+        });
+        turndownService.remove([
+          "script",
+          "style",
+          "meta",
+          "link",
+          "noscript",
+          "iframe",
+        ]);
+        const markdown = turndownService.turndown(content);
+        return `<source>${url}</source>\n<content>\n${markdown}\n</content>`;
+      }
+
+      return `<source>${url}</source>\n<content>\n${content.slice(0, 100000)}\n</content>`; // Cap raw text
+    } catch (err: any) {
+      if (err.name === "AbortError")
+        return "Error: Request timed out after 30 seconds";
+      return `Error fetching URL: ${err.message}`;
+    }
+  },
+
+  websearch: async (args) => {
+    try {
+      if (!args.query) return 'Error: The "query" argument is required';
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 25000); // 25s timeout
+
+      const payload = {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "web_search_exa",
+          arguments: {
+            query: args.query,
+            type: "auto",
+            numResults: args.numResults || 8,
+            livecrawl: "fallback",
+          },
+        },
+      };
+
+      const response = await fetch("https://mcp.exa.ai/mcp", {
+        method: "POST",
+        headers: {
+          accept: "application/json, text/event-stream",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok)
+        return `Error: Search failed with status ${response.status} ${await response.text()}`;
+
+      const responseText = await response.text();
+      for (const line of responseText.split("\n")) {
+        if (line.startsWith("data: ")) {
+          const data = JSON.parse(line.substring(6));
+          if (data.result?.content?.[0]?.text) {
+            return data.result.content[0].text;
+          }
+        }
+      }
+      return "No search results found.";
+    } catch (err: any) {
+      if (err.name === "AbortError") return "Error: Search request timed out";
+      return `Error performing web search: ${err.message}`;
+    }
+  },
+
+  codesearch: async (args) => {
+    try {
+      if (!args.query) return 'Error: The "query" argument is required';
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 30000);
+
+      const payload = {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "get_code_context_exa",
+          arguments: {
+            query: args.query,
+            tokensNum: 5000,
+          },
+        },
+      };
+
+      const response = await fetch("https://mcp.exa.ai/mcp", {
+        method: "POST",
+        headers: {
+          accept: "application/json, text/event-stream",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok)
+        return `Error: Code search failed with status ${response.status} ${await response.text()}`;
+
+      const responseText = await response.text();
+      for (const line of responseText.split("\n")) {
+        if (line.startsWith("data: ")) {
+          const data = JSON.parse(line.substring(6));
+          if (data.result?.content?.[0]?.text) {
+            return data.result.content[0].text;
+          }
+        }
+      }
+      return "No code snippets or documentation found.";
+    } catch (err: any) {
+      if (err.name === "AbortError")
+        return "Error: Code search request timed out";
+      return `Error performing code search: ${err.message}`;
+    }
+  },
+
+  grep_search: async (args) => {
+    try {
+      if (!args.pattern) return "Error: pattern is required";
+      const searchPath = path.resolve(process.cwd(), args.path || ".");
+
+      // Assuming rg (ripgrep) is available in PATH
+      const rgArgs = [
+        "-nH",
+        "--hidden",
+        "--no-messages",
+        "--glob",
+        "!.git/*",
+        "--glob",
+        "!node_modules/*",
+        "--field-match-separator=|",
+        "--regexp",
+        args.pattern,
+      ];
+      if (args.include) {
+        rgArgs.push("--glob", args.include);
+      }
+      rgArgs.push(searchPath);
+
+      const { stdout } = await execAsync(
+        `rg ${rgArgs.map((arg) => `"${arg.replace(/"/g, '\\"')}"`).join(" ")}`,
+        {
+          cwd: searchPath,
+          maxBuffer: 1024 * 1024 * 5, // 5MB limit
+        },
+      ).catch((e) => {
+        // Exit code 1 means no matches, 2 means error.
+        if (e.code === 1) return { stdout: "" };
+        throw e;
+      });
+
+      if (!stdout.trim())
+        return `No files found matching pattern: ${args.pattern}`;
+
+      const lines = stdout.trim().split(/\r?\n/);
+      const matches: string[] = [];
+
+      let currentFile = "";
+      for (const line of lines) {
+        if (!line) continue;
+        const parts = line.split("|");
+        if (parts.length < 3) continue;
+
+        const filePath = parts[0];
+        const lineNum = parts[1];
+        const lineText = parts.slice(2).join("|");
+
+        if (currentFile !== filePath) {
+          if (currentFile !== "") matches.push("");
+          currentFile = filePath!;
+          matches.push(`${filePath}:`);
+        }
+
+        const truncatedText =
+          lineText!.length > 2000
+            ? lineText!.substring(0, 2000) + "..."
+            : lineText;
+        matches.push(`  Line ${lineNum}: ${truncatedText}`);
+
+        if (matches.length > 200) {
+          matches.push("");
+          matches.push(`(Results truncated. Showing first 200 matches.)`);
+          break;
+        }
+      }
+
+      return matches.join("\n");
+    } catch (err: any) {
+      return `Error running grep search: ${err.message}`;
+    }
+  },
+
+  edit_file: async (args) => {
+    try {
+      const filePath = args.filePath;
+      if (!filePath) return 'Error: The "filePath" argument is required';
+      if (args.oldString === undefined)
+        return 'Error: The "oldString" argument is required';
+      if (args.newString === undefined)
+        return 'Error: The "newString" argument is required';
+      if (args.oldString === args.newString)
+        return "Error: No changes to apply (oldString and newString are identical)";
+
+      const resolved = path.resolve(process.cwd(), filePath);
+
+      // Check if file exists
+      try {
+        const stat = await fs.stat(resolved);
+        if (stat.isDirectory())
+          return `Error: Path is a directory, not a file: ${resolved}`;
+      } catch {
+        return `Error: File not found: ${resolved}`;
+      }
+
+      const contentOld = await fs.readFile(resolved, "utf8");
+      const contentNew = replaceCode(
+        contentOld,
+        args.oldString,
+        args.newString,
+        args.replaceAll,
+      );
+
+      await fs.writeFile(resolved, contentNew, "utf8");
+
+      const patch = diff.createTwoFilesPatch(
+        path.basename(resolved),
+        path.basename(resolved),
+        contentOld,
+        contentNew,
+        "original",
+        "modified",
+        { context: 5 },
+      );
+
+      // Calculate additions/deletions
+      let additions = 0;
+      let deletions = 0;
+      const lineDiffs = diff.diffLines(contentOld, contentNew);
+      for (const change of lineDiffs) {
+        if (change.added) additions += change.count || 0;
+        if (change.removed) deletions += change.count || 0;
+      }
+
+      let output = `Edit applied to ${path.basename(resolved)} (+${additions} -${deletions})\n\n`;
+      output += `\`\`\`diff\n${patch}\`\`\``;
+
+      // LSP Diagnostics Check
+      try {
+        const workspaceRoot = process.cwd();
+        const client = await getLspClientForFile(workspaceRoot, resolved);
+        // openFile waits for publishDiagnostics (or times out), so diagnostics are ready after this
+        await client.openFile(resolved);
+
+        const uri = pathToFileURL(resolved).href;
+
+        const normalizeUri = (u: string) =>
+          decodeURIComponent(u)
+            .toLowerCase()
+            .replace(/^file:\/\/\/([a-z]):/, "file:///$1:");
+        const targetNorm = normalizeUri(uri);
+
+        let diagnostics: any[] = client.diagnostics.get(uri) || [];
+        if (diagnostics.length === 0) {
+          for (const [key, val] of client.diagnostics.entries()) {
+            if (normalizeUri(key) === targetNorm) {
+              diagnostics = val;
+              break;
+            }
+          }
+        }
+
+        const errors = diagnostics.filter((d) => d.severity === 1); // 1 is Error
+
+        if (errors.length > 0) {
+          output += `\n\n⚠️  LSP Errors detected after edit (please fix cases where your edit broke the code):\n`;
+          for (const err of errors) {
+            const line = err.range.start.line + 1;
+            const char = err.range.start.character + 1;
+            output += `- [Line ${line}, Col ${char}]: ${err.message}\n`;
+          }
+        }
+      } catch (lspErr) {
+        // LSP failure shouldn't fail the edit itself
+        console.error(`[EditTool] LSP check failed:`, lspErr);
+      }
+
+      return output;
+    } catch (err: any) {
+      return `Error editing file: ${err.message}`;
+    }
+  },
+
+  lsp: async (args) => {
+    try {
+      if (!args.operation) return 'Error: The "operation" argument is required';
+      if (!args.filePath) return 'Error: The "filePath" argument is required';
+      if (!args.line) return 'Error: The "line" argument is required';
+      if (!args.character) return 'Error: The "character" argument is required';
+
+      const workspaceRoot = process.cwd(); // Assume agent runs in workspace root
+      const resolved = path.resolve(workspaceRoot, args.filePath);
+
+      // Validate file bounds before attempting
+      const fileExists = existsSync(resolved);
+      if (!fileExists) return `Error: File not found: ${resolved}`;
+
+      const client = await getLspClientForFile(workspaceRoot, resolved);
+
+      // Notify Server we are looking at this file (updates diagnostics)
+      await client.openFile(resolved);
+
+      const position = {
+        line: args.line - 1, // LSP is 0-based index
+        character: args.character - 1,
+      };
+
+      const uri = pathToFileURL(resolved).href;
+
+      let result: any;
+      switch (args.operation) {
+        case "goToDefinition":
+          result = await client.connection.sendRequest(
+            "textDocument/definition",
+            {
+              textDocument: { uri },
+              position,
+            },
+          );
+          break;
+        case "findReferences":
+          result = await client.connection.sendRequest(
+            "textDocument/references",
+            {
+              textDocument: { uri },
+              position,
+              context: { includeDeclaration: true },
+            },
+          );
+          break;
+        case "hover":
+          result = await client.connection.sendRequest("textDocument/hover", {
+            textDocument: { uri },
+            position,
+          });
+          break;
+      }
+
+      if (!result || (Array.isArray(result) && result.length === 0)) {
+        return `No results found for ${args.operation} at ${args.filePath}:${args.line}:${args.character}`;
+      }
+
+      return JSON.stringify(result, null, 2);
+    } catch (err: any) {
+      return `Error running LSP operation: ${err.message}`;
+    }
+  },
+
+  write_file: async (args) => {
+    try {
+      const filePath = args.filePath || args.path;
+      if (!filePath) return `Error: The "filePath" argument is required`;
+      if (args.content === undefined)
+        return `Error: The "content" argument is required`;
+      const resolved = path.resolve(process.cwd(), filePath);
+      await fs.mkdir(path.dirname(resolved), { recursive: true });
+      const existed = existsSync(resolved);
+      await fs.writeFile(resolved, args.content, "utf8");
+      const lineCount = (args.content.match(/\n/g) || []).length + 1;
+      return `Wrote file successfully: ${resolved} (${lineCount} lines, ${existed ? "updated" : "created"})`;
+    } catch (err: any) {
+      return `Error writing file: ${err.message}`;
+    }
+  },
+
+  run_command: async (args) => {
+    const decodeOutput = (buf: any): string => {
+      if (!buf) return "";
+      if (typeof buf === "string") return buf;
+      if (process.platform === "win32") {
+        try {
+          return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+        } catch {
+          return new TextDecoder("gbk").decode(buf);
+        }
+      }
+      return new TextDecoder("utf-8").decode(buf);
+    };
+
+    try {
+      if (!args.command) return 'Error: The "command" argument is required';
+      const cwd = args.cwd || process.cwd();
+      const shell = process.platform === "win32" ? "powershell.exe" : undefined;
+      const { stdout, stderr } = await execAsync(args.command, {
+        cwd,
+        timeout: COMMAND_TIMEOUT,
+        maxBuffer: 1024 * 1024 * 10, // 10MB
+        windowsHide: true,
+        encoding: "buffer",
+        shell,
+      });
+
+      const outStr = decodeOutput(stdout);
+      const errStr = decodeOutput(stderr);
+
+      let output = `> ${args.command}\n`;
+      if (outStr.trim()) output += outStr.trim();
+      if (errStr.trim())
+        output += (output ? "\n\nStderr:\n" : "Stderr:\n") + errStr.trim();
+      return output || `> ${args.command}\n(Command completed with no output)`;
+    } catch (err: any) {
+      const outStr = decodeOutput(err.stdout);
+      const errStr = decodeOutput(err.stderr) || err.message;
+      if (err.killed)
+        return `> ${args.command}\nCommand timed out after ${COMMAND_TIMEOUT / 1000}s and was killed.\nPartial output:\n${outStr}`;
+      return `> ${args.command}\nCommand failed (exit code ${err.code || "?"}):\n${errStr}`;
+    }
+  },
+
+  list_dir: async (args) => {
+    try {
+      const targetPath = args.path || ".";
+      const dirPath = path.resolve(process.cwd(), targetPath);
+
+      // Build tree structure (opencode pattern)
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+
+      const lines: string[] = [`${dirPath}/`];
+
+      for (const entry of entries) {
+        if (IGNORE_DIRS.has(entry.name)) continue;
+        if (
+          entry.name.startsWith(".") &&
+          ![
+            ".env",
+            ".acmecode.md",
+            ".acmecode",
+            ".github",
+            ".vscode",
+            ".cursor",
+          ].includes(entry.name)
+        )
+          continue;
+
+        if (entry.isDirectory()) {
+          lines.push(`  ${entry.name}/`);
+          // Read one level deep for subdirectories
+          try {
+            const subEntries = await fs.readdir(
+              path.join(dirPath, entry.name),
+              { withFileTypes: true },
+            );
+            subEntries.sort((a, b) => a.name.localeCompare(b.name));
+            for (const sub of subEntries.slice(0, 20)) {
+              if (IGNORE_DIRS.has(sub.name)) continue;
+              lines.push(`    ${sub.name}${sub.isDirectory() ? "/" : ""}`);
+            }
+            if (subEntries.length > 20) {
+              lines.push(`    ... and ${subEntries.length - 20} more`);
+            }
+          } catch {
+            /* skip unreadable subdirs */
+          }
+        } else {
+          lines.push(`  ${entry.name}`);
+        }
+      }
+
+      return lines.join("\n");
+    } catch (err: any) {
+      return `Error listing directory: ${err.message}`;
+    }
+  },
+
+  switch_mode: async (args) => {
+    if (!args.mode)
+      return JSON.stringify({ error: 'The "mode" argument is required' });
+    // We return a JSON string containing the mode switch request,
+    // which the agent loop will intercept and translate into a 'mode-changed' event.
+    return JSON.stringify({
+      switched_mode: args.mode,
+      contextFile: args.contextFile,
+      reason: args.reason,
+    });
+  },
+  batch: async (args) => {
+    return executeBatch(args, toolExecutors);
+  },
+};
+
+// Create AI SDK tool objects (with execute) for the agent
+const tool = (options: any): any => createTool(options);
+
+export const builtInTools: Record<string, any> = Object.fromEntries(
+  Object.entries(toolDefinitions).map(([name, def]) => [
+    name,
+    tool({
+      description: def.description,
+      parameters: def.parameters,
+      execute: toolExecutors[name],
+    }),
+  ]),
+);