wave-agent-sdk 0.0.1

package/src/tools/multiEditTool.ts

@@ -0,0 +1,268 @@
+import { readFile, writeFile } from "fs/promises";
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import { resolvePath, getDisplayPath } from "../utils/path.js";
+import { diffLines } from "diff";
+
+interface EditOperation {
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+}
+
+/**
+ * Format compact parameter display
+ */
+function formatCompactParams(
+  args: Record<string, unknown>,
+  context: ToolContext,
+): string {
+  const filePath = args.file_path as string;
+  const edits = args.edits as EditOperation[];
+  const editCount = edits ? edits.length : 0;
+  const displayPath = getDisplayPath(filePath || "", context.workdir);
+  return `${displayPath} ${editCount} edits`;
+}
+
+/**
+ * Multi-edit tool plugin
+ */
+export const multiEditTool: ToolPlugin = {
+  name: "MultiEdit",
+  formatCompactParams,
+  config: {
+    type: "function",
+    function: {
+      name: "MultiEdit",
+      description:
+        "This is a tool for making multiple edits to a single file in one operation. It is built on top of the Edit tool and allows you to perform multiple find-and-replace operations efficiently. Prefer this tool over the Edit tool when you need to make multiple edits to the same file.\n\nBefore using this tool:\n\n1. Use the Read tool to understand the file's contents and context\n2. Verify the directory path is correct\n\nTo make multiple file edits, provide the following:\n1. file_path: The absolute path to the file to modify (must be absolute, not relative)\n2. edits: An array of edit operations to perform, where each edit contains:\n   - old_string: The text to replace (must match the file contents exactly, including all whitespace and indentation)\n   - new_string: The edited text to replace the old_string\n   - replace_all: Replace all occurences of old_string. This parameter is optional and defaults to false.\n\nIMPORTANT:\n- All edits are applied in sequence, in the order they are provided\n- Each edit operates on the result of the previous edit\n- All edits must be valid for the operation to succeed - if any edit fails, none will be applied\n- This tool is ideal when you need to make several changes to different parts of the same file\n- For Jupyter notebooks (.ipynb files), use the NotebookEdit instead\n\nCRITICAL REQUIREMENTS:\n1. All edits follow the same requirements as the single Edit tool\n2. The edits are atomic - either all succeed or none are applied\n3. Plan your edits carefully to avoid conflicts between sequential operations\n\nWARNING:\n- The tool will fail if edits.old_string doesn't match the file contents exactly (including whitespace)\n- The tool will fail if edits.old_string and edits.new_string are the same\n- Since edits are applied in sequence, ensure that earlier edits don't affect the text that later edits are trying to find\n\nWhen making edits:\n- Ensure all edits result in idiomatic, correct code\n- Do not leave the code in a broken state\n- Always use absolute file paths (starting with /)\n- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.\n- Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.\n\nIf you want to create a new file, use:\n- A new file path, including dir name if needed\n- First edit: empty old_string and the new file's contents as new_string\n- Subsequent edits: normal edit operations on the created content",
+      parameters: {
+        type: "object",
+        properties: {
+          file_path: {
+            type: "string",
+            description: "The absolute path to the file to modify",
+          },
+          edits: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                old_string: {
+                  type: "string",
+                  description: "The text to replace",
+                },
+                new_string: {
+                  type: "string",
+                  description: "The text to replace it with",
+                },
+                replace_all: {
+                  type: "boolean",
+                  default: false,
+                  description:
+                    "Replace all occurences of old_string (default false).",
+                },
+              },
+              required: ["old_string", "new_string"],
+              additionalProperties: false,
+            },
+            minItems: 1,
+            description:
+              "Array of edit operations to perform sequentially on the file",
+          },
+        },
+        required: ["file_path", "edits"],
+        additionalProperties: false,
+      },
+    },
+  },
+  execute: async (
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> => {
+    const filePath = args.file_path as string;
+    const edits = args.edits as EditOperation[];
+
+    // Validate required parameters
+    if (!filePath || typeof filePath !== "string") {
+      return {
+        success: false,
+        content: "",
+        error: "file_path parameter is required and must be a string",
+      };
+    }
+
+    if (!Array.isArray(edits) || edits.length === 0) {
+      return {
+        success: false,
+        content: "",
+        error: "edits parameter is required and must be a non-empty array",
+      };
+    }
+
+    // Validate each edit operation
+    for (let i = 0; i < edits.length; i++) {
+      const edit = edits[i];
+      if (!edit || typeof edit !== "object") {
+        return {
+          success: false,
+          content: "",
+          error: `Edit operation ${i + 1} must be an object`,
+        };
+      }
+
+      if (typeof edit.old_string !== "string") {
+        return {
+          success: false,
+          content: "",
+          error: `Edit operation ${i + 1}: old_string is required and must be a string`,
+        };
+      }
+
+      if (typeof edit.new_string !== "string") {
+        return {
+          success: false,
+          content: "",
+          error: `Edit operation ${i + 1}: new_string is required and must be a string`,
+        };
+      }
+
+      if (edit.old_string === edit.new_string) {
+        return {
+          success: false,
+          content: "",
+          error: `Edit operation ${i + 1}: old_string and new_string must be different`,
+        };
+      }
+    }
+
+    try {
+      const resolvedPath = resolvePath(filePath, context.workdir);
+
+      // Read file content
+      let originalContent: string;
+      let isNewFile = false;
+
+      try {
+        originalContent = await readFile(resolvedPath, "utf-8");
+      } catch (readError) {
+        // Check if this is a new file creation case (first edit has empty old_string)
+        if (edits[0] && edits[0].old_string === "") {
+          originalContent = "";
+          isNewFile = true;
+          // logger.info(`Creating new file: ${resolvedPath}`);
+        } else {
+          return {
+            success: false,
+            content: "",
+            error: `Failed to read file: ${readError instanceof Error ? readError.message : String(readError)}`,
+          };
+        }
+      }
+
+      let currentContent = originalContent;
+      const appliedEdits: string[] = [];
+
+      // Apply each edit operation in sequence
+      for (let i = 0; i < edits.length; i++) {
+        const edit = edits[i];
+        const replaceAll = edit.replace_all || false;
+
+        // Special handling for the first edit of new file creation
+        if (isNewFile && i === 0 && edit.old_string === "") {
+          currentContent = edit.new_string;
+          appliedEdits.push(
+            `Created file with content (${edit.new_string.length} characters)`,
+          );
+          continue;
+        }
+
+        // Check if old_string exists
+        if (!currentContent.includes(edit.old_string)) {
+          return {
+            success: false,
+            content: "",
+            error: `Edit operation ${i + 1}: old_string not found in current content: "${edit.old_string}"`,
+          };
+        }
+
+        let replacementCount: number;
+
+        if (replaceAll) {
+          // Replace all matches
+          const regex = new RegExp(escapeRegExp(edit.old_string), "g");
+          currentContent = currentContent.replace(regex, edit.new_string);
+          replacementCount = (currentContent.match(regex) || []).length;
+          appliedEdits.push(
+            `Replaced ${replacementCount} instances of "${edit.old_string.substring(0, 50)}${edit.old_string.length > 50 ? "..." : ""}"`,
+          );
+        } else {
+          // Replace only the first match, but first check if it's unique
+          const matches = currentContent.split(edit.old_string).length - 1;
+          if (matches > 1) {
+            return {
+              success: false,
+              content: "",
+              error: `Edit operation ${i + 1}: old_string appears ${matches} times in the current content. Either provide a larger string with more surrounding context to make it unique or use replace_all=true.`,
+            };
+          }
+
+          currentContent = currentContent.replace(
+            edit.old_string,
+            edit.new_string,
+          );
+          appliedEdits.push(
+            `Replaced "${edit.old_string.substring(0, 50)}${edit.old_string.length > 50 ? "..." : ""}"`,
+          );
+        }
+      }
+
+      // Write file
+      try {
+        await writeFile(resolvedPath, currentContent, "utf-8");
+      } catch (writeError) {
+        return {
+          success: false,
+          content: "",
+          error: `Failed to write file: ${writeError instanceof Error ? writeError.message : String(writeError)}`,
+        };
+      }
+
+      // Generate diff information
+      const diffResult = diffLines(originalContent, currentContent);
+
+      const shortResult = isNewFile
+        ? `Created file with ${edits.length} operations`
+        : `Applied ${edits.length} edits`;
+
+      const detailedContent = `${shortResult}\n\nOperations performed:\n${appliedEdits.map((edit, i) => `${i + 1}. ${edit}`).join("\n")}`;
+
+      // logger.info(`MultiEdit tool: ${shortResult}`);
+
+      return {
+        success: true,
+        content: detailedContent,
+        shortResult,
+        filePath: resolvedPath,
+        originalContent,
+        newContent: currentContent,
+        diffResult,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      // logger.error(`MultiEdit tool error: ${errorMessage}`);
+      return {
+        success: false,
+        content: "",
+        error: errorMessage,
+      };
+    }
+  },
+};
+
+/**
+ * Escape regular expression special characters
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/tools/readTool.ts

@@ -0,0 +1,165 @@
+import { readFile } from "fs/promises";
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import { resolvePath, getDisplayPath } from "../utils/path.js";
+
+/**
+ * Read Tool Plugin - Read file content
+ */
+export const readTool: ToolPlugin = {
+  name: "Read",
+  config: {
+    type: "function",
+    function: {
+      name: "Read",
+      description:
+        "Reads a file from the local filesystem. You can access any file directly by using this tool.\nAssume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- The file_path parameter must be an absolute path, not a relative path\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n- Any lines longer than 2000 characters will be truncated\n- Results are returned using cat -n format, with line numbers starting at 1\n- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.\n- This tool can read PDF files (.pdf). PDFs are processed page by page, extracting both text and visual content for analysis.\n- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.\n- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.\n- You will regularly be asked to read screenshots. If the user provides a path to a screenshot ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths like /var/folders/123/abc/T/TemporaryItems/NSIRD_screencaptureui_ZfB1tD/Screenshot.png\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.",
+      parameters: {
+        type: "object",
+        properties: {
+          file_path: {
+            type: "string",
+            description: "The absolute path to the file to read",
+          },
+          offset: {
+            type: "number",
+            description:
+              "The line number to start reading from. Only provide if the file is too large to read at once",
+          },
+          limit: {
+            type: "number",
+            description:
+              "The number of lines to read. Only provide if the file is too large to read at once.",
+          },
+        },
+        required: ["file_path"],
+      },
+    },
+  },
+  execute: async (
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> => {
+    const filePath = args.file_path as string;
+    const offset = args.offset as number;
+    const limit = args.limit as number;
+
+    if (!filePath || typeof filePath !== "string") {
+      return {
+        success: false,
+        content: "",
+        error: "file_path parameter is required and must be a string",
+      };
+    }
+
+    try {
+      // Note: New Read tool requires absolute paths, so we don't use resolvePath
+      // But for compatibility, if it's not an absolute path, we still try to resolve
+      const actualFilePath = filePath.startsWith("/")
+        ? filePath
+        : resolvePath(filePath, context.workdir);
+
+      const fileContent = await readFile(actualFilePath, "utf-8");
+
+      // Check if file is empty
+      if (fileContent.length === 0) {
+        // logger.warn(`File ${filePath} exists but has empty contents`);
+        return {
+          success: true,
+          content:
+            "⚠️ System reminder: This file exists but has empty contents.",
+          shortResult: "Empty file",
+        };
+      }
+
+      const lines = fileContent.split("\n");
+      const totalLines = lines.length;
+
+      // Handle offset and limit
+      let startLine = 1;
+      let endLine = Math.min(totalLines, 2000); // Default maximum read 2000 lines
+
+      if (typeof offset === "number") {
+        startLine = Math.max(1, offset);
+      }
+
+      if (typeof limit === "number") {
+        endLine = Math.min(totalLines, startLine + limit - 1);
+      }
+
+      // If no offset and limit specified, read entire file (maximum 2000 lines)
+      if (typeof offset !== "number" && typeof limit !== "number") {
+        startLine = 1;
+        endLine = Math.min(totalLines, 2000);
+      }
+
+      // Validate line number range
+      if (startLine > totalLines) {
+        return {
+          success: false,
+          content: "",
+          error: `Start line ${startLine} exceeds total lines ${totalLines}`,
+        };
+      }
+
+      // Extract specified line range
+      const selectedLines = lines.slice(startLine - 1, endLine);
+
+      // Format output (cat -n format, with line numbers)
+      const formattedContent = selectedLines
+        .map((line, index) => {
+          const lineNumber = startLine + index;
+          // Truncate overly long lines
+          const truncatedLine =
+            line.length > 2000 ? line.substring(0, 2000) + "..." : line;
+          return `${lineNumber.toString().padStart(6)}\t${truncatedLine}`;
+        })
+        .join("\n");
+
+      // Add file information header
+      let content = `File: ${filePath}\n`;
+      if (startLine > 1 || endLine < totalLines) {
+        content += `Lines ${startLine}-${endLine} of ${totalLines}\n`;
+      } else {
+        content += `Total lines: ${totalLines}\n`;
+      }
+      content += "─".repeat(50) + "\n";
+      content += formattedContent;
+
+      // If only showing partial content, add prompt
+      if (endLine < totalLines) {
+        content += `\n${"─".repeat(50)}\n`;
+        content += `... ${totalLines - endLine} more lines not shown`;
+      }
+
+      return {
+        success: true,
+        content,
+        shortResult: `Read ${selectedLines.length} lines${totalLines > 2000 ? " (truncated)" : ""}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        content: "",
+        error: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+  formatCompactParams: (
+    params: Record<string, unknown>,
+    context: ToolContext,
+  ) => {
+    const filePath = params.file_path as string;
+    const offset = params.offset as number;
+    const limit = params.limit as number;
+
+    let displayPath = getDisplayPath(filePath || "", context.workdir);
+
+    if (typeof offset === "number" || typeof limit === "number") {
+      const offsetStr = typeof offset === "number" ? offset.toString() : "1";
+      const limitStr = typeof limit === "number" ? limit.toString() : "2000";
+      displayPath += ` ${offsetStr}:${limitStr}`;
+    }
+
+    return displayPath;
+  },
+};

package/src/tools/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Tool plugin interface definitions
+ */
+
+import { ChatCompletionFunctionTool } from "openai/resources.js";
+
+export interface ToolPlugin {
+  name: string;
+  config: ChatCompletionFunctionTool;
+  execute: (
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ) => Promise<ToolResult>;
+  formatCompactParams?: (
+    params: Record<string, unknown>,
+    context: ToolContext,
+  ) => string;
+}
+
+export interface ToolResult {
+  success: boolean;
+  content: string;
+  error?: string;
+  // Short output, used to display summary information in collapsed state
+  shortResult?: string;
+  // Additional properties for file editing tools
+  originalContent?: string;
+  newContent?: string;
+  diffResult?: Array<{
+    count?: number;
+    value: string;
+    added?: boolean;
+    removed?: boolean;
+  }>;
+  filePath?: string;
+  // Image data, for supporting multimedia content
+  images?: Array<{
+    data: string; // base64 encoded image data
+    mediaType?: string; // Image media type, such as "image/png"
+  }>;
+}
+
+export interface ToolContext {
+  abortSignal?: AbortSignal;
+  backgroundBashManager?: import("../managers/backgroundBashManager.js").BackgroundBashManager;
+  workdir: string;
+}

package/src/tools/writeTool.ts

@@ -0,0 +1,163 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import { resolvePath, getDisplayPath } from "../utils/path.js";
+import { diffLines } from "diff";
+
+/**
+ * File Write Tool Plugin
+ */
+export const writeTool: ToolPlugin = {
+  name: "Write",
+  config: {
+    type: "function",
+    function: {
+      name: "Write",
+      description:
+        "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",
+      parameters: {
+        type: "object",
+        properties: {
+          file_path: {
+            type: "string",
+            description:
+              "The absolute path to the file to write (must be absolute, not relative)",
+          },
+          content: {
+            type: "string",
+            description: "The content to write to the file",
+          },
+        },
+        required: ["file_path", "content"],
+        additionalProperties: false,
+      },
+    },
+  },
+  execute: async (
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> => {
+    const filePath = args.file_path as string;
+    const content = args.content as string;
+
+    // Validate required parameters
+    if (!filePath || typeof filePath !== "string") {
+      return {
+        success: false,
+        content: "",
+        error: "file_path parameter is required and must be a string",
+      };
+    }
+
+    if (typeof content !== "string") {
+      return {
+        success: false,
+        content: "",
+        error: "content parameter is required and must be a string",
+      };
+    }
+
+    try {
+      const resolvedPath = resolvePath(filePath, context.workdir);
+
+      // Check if file already exists
+      let originalContent = "";
+      let isExistingFile = false;
+
+      try {
+        originalContent = await readFile(resolvedPath, "utf-8");
+        isExistingFile = true;
+      } catch {
+        // File doesn't exist, this is normal for new file creation
+        isExistingFile = false;
+      }
+
+      // Check if overwriting existing file but content is the same
+      if (isExistingFile && originalContent === content) {
+        return {
+          success: true,
+          content: `File ${filePath} already has the same content, no changes needed`,
+          shortResult: "No changes needed",
+          filePath: resolvedPath,
+          originalContent,
+          newContent: content,
+          diffResult: [],
+        };
+      }
+
+      // Ensure directory exists
+      const fileDir = dirname(resolvedPath);
+      try {
+        await mkdir(fileDir, { recursive: true });
+      } catch (mkdirError) {
+        // Ignore directory already exists error
+        if (
+          mkdirError instanceof Error &&
+          !mkdirError.message.includes("EEXIST")
+        ) {
+          // logger.warn(
+          //   `Failed to create directory ${fileDir}: ${mkdirError.message}`,
+          // );
+        }
+      }
+
+      // Write file
+      try {
+        await writeFile(resolvedPath, content, "utf-8");
+      } catch (writeError) {
+        return {
+          success: false,
+          content: "",
+          error: `Failed to write file: ${writeError instanceof Error ? writeError.message : String(writeError)}`,
+        };
+      }
+
+      // Generate diff information
+      const diffResult = diffLines(originalContent, content);
+
+      const shortResult = isExistingFile ? "File overwritten" : "File created";
+
+      const lines = content.split("\n").length;
+      const chars = content.length;
+      const detailedContent = `${shortResult} (${lines} lines, ${chars} characters)`;
+
+      // logger.info(`Write tool: ${shortResult}`);
+
+      return {
+        success: true,
+        content: detailedContent,
+        shortResult,
+        filePath: resolvedPath,
+        originalContent,
+        newContent: content,
+        diffResult,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      // logger.error(`Write tool error: ${errorMessage}`);
+      return {
+        success: false,
+        content: "",
+        error: errorMessage,
+      };
+    }
+  },
+  formatCompactParams: (
+    params: Record<string, unknown>,
+    context: ToolContext,
+  ) => {
+    const filePath = params.file_path as string;
+    const content = params.content as string;
+
+    let displayPath = getDisplayPath(filePath || "", context.workdir);
+
+    if (content) {
+      const lines = content.split("\n").length;
+      const chars = content.length;
+      displayPath += ` ${lines} lines, ${chars} chars`;
+    }
+
+    return displayPath;
+  },
+};