wave-agent-sdk 0.4.0 → 0.6.1

package/src/tools/lsTool.ts

@@ -18,7 +18,7 @@ export const lsTool: ToolPlugin = {
     type: "function",
     function: {
       name: LS_TOOL_NAME,
-      description: `Lists files and directories in a given path. The path parameter must be an absolute path, not a relative path. You can optionally provide an array of glob patterns to ignore with the ignore parameter. You should generally prefer the ${GLOB_TOOL_NAME} and ${GREP_TOOL_NAME} tools, if you know which directories to search.`,
+      description: "Lists files and directories in a given path.",
       parameters: {
         type: "object",
         properties: {
@@ -39,6 +39,8 @@ export const lsTool: ToolPlugin = {
       },
     },
   },
+  prompt: () => `
+Lists files and directories in a given path. The path parameter must be an absolute path, not a relative path. You can optionally provide an array of glob patterns to ignore with the ignore parameter. You should generally prefer the ${GLOB_TOOL_NAME} and ${GREP_TOOL_NAME} tools, if you know which directories to search.`,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,

package/src/tools/multiEditTool.ts

@@ -2,11 +2,7 @@ import { readFile, writeFile } from "fs/promises";
 import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
-import {
-  findIndentationInsensitiveMatch,
-  escapeRegExp,
-  saveEditErrorSnapshot,
-} from "../utils/editUtils.js";
+import { escapeRegExp, analyzeEditMismatch } from "../utils/editUtils.js";
 import {
   MULTI_EDIT_TOOL_NAME,
   EDIT_TOOL_NAME,
@@ -185,23 +181,16 @@ export const multiEditTool: ToolPlugin = {
           continue;
         }
 
-        // Check if old_string exists (with smart indentation matching)
-        const matchedOldString = findIndentationInsensitiveMatch(
-          currentContent,
-          edit.old_string,
-        );
+        // Check if old_string exists
+        const matchedOldString = currentContent.includes(edit.old_string)
+          ? edit.old_string
+          : null;
 
         if (!matchedOldString) {
-          await saveEditErrorSnapshot(
-            resolvedPath,
-            edit.old_string,
-            currentContent,
-            MULTI_EDIT_TOOL_NAME,
-          );
           return {
             success: false,
             content: "",
-            error: `Edit operation ${i + 1}: old_string not found in current content`,
+            error: `Edit operation ${i + 1}: ${analyzeEditMismatch(currentContent, edit.old_string)}`,
           };
         }
 
@@ -209,7 +198,7 @@ export const multiEditTool: ToolPlugin = {
 
         if (replaceAll) {
           // Replace all matches
-          const regex = new RegExp(escapeRegExp(matchedOldString), "g");
+          const regex = new RegExp(escapeRegExp(edit.old_string), "g");
           currentContent = currentContent.replace(regex, edit.new_string);
           replacementCount = (currentContent.match(regex) || []).length;
           appliedEdits.push(

package/src/tools/readTool.ts

@@ -131,11 +131,27 @@ async function processImageFile(
  */
 export const readTool: ToolPlugin = {
   name: READ_TOOL_NAME,
+  prompt:
+    () => `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume 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.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- 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
+- Any lines longer than 2000 characters will be truncated
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool allows Agent to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Agent is a multimodal LLM.
+- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
+- 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.
+- 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
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+- Binary document formats (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX) are not supported and will return an error.`,
   config: {
     type: "function",
     function: {
       name: READ_TOOL_NAME,
-      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 Agent to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Agent is a multimodal LLM.\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.\n- Binary document formats (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX) are not supported and will return an error.`,
+      description: "Read a file from the local filesystem.",
       parameters: {
         type: "object",
         properties: {

package/src/tools/taskManagementTools.ts

@@ -0,0 +1,498 @@
+import { ToolPlugin, ToolContext, ToolResult } from "./types.js";
+import { Task, TaskStatus } from "../types/tasks.js";
+import {
+  TASK_CREATE_TOOL_NAME,
+  TASK_GET_TOOL_NAME,
+  TASK_UPDATE_TOOL_NAME,
+  TASK_LIST_TOOL_NAME,
+} from "../constants/tools.js";
+
+export const taskCreateTool: ToolPlugin = {
+  name: TASK_CREATE_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TASK_CREATE_TOOL_NAME,
+      description: "Create a new task in the task list",
+      parameters: {
+        type: "object",
+        properties: {
+          subject: {
+            type: "string",
+            description: "A brief title for the task",
+          },
+          description: {
+            type: "string",
+            description: "A detailed description of what needs to be done",
+          },
+          status: {
+            type: "string",
+            enum: ["pending", "in_progress", "completed", "deleted"],
+            description: "Initial status of the task. Defaults to 'pending'.",
+          },
+          activeForm: {
+            type: "string",
+            description:
+              'Present continuous form shown in spinner when in_progress (e.g., "Running tests")',
+          },
+          owner: {
+            type: "string",
+            description: "Optional owner of the task.",
+          },
+          blocks: {
+            type: "array",
+            items: { type: "string" },
+            description: "List of task IDs that this task blocks.",
+          },
+          blockedBy: {
+            type: "array",
+            items: { type: "string" },
+            description: "List of task IDs that block this task.",
+          },
+          metadata: {
+            type: "object",
+            description: "Arbitrary metadata to attach to the task",
+          },
+        },
+        required: ["subject", "description"],
+      },
+    },
+  },
+  prompt:
+    () => `Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+- Plan mode - When using plan mode, create a task list to track the work
+- User explicitly requests todo list - When the user directly asks you to use the todo list
+- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+- After receiving new instructions - Immediately capture user requirements as tasks
+- When you start working on a task - Mark it as in_progress BEFORE beginning work
+- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+- There is only a single, straightforward task
+- The task is trivial and tracking it provides no organizational benefit
+- The task can be completed in less than 3 trivial steps
+- The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task Fields
+
+- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+- **description**: Detailed description of what needs to be done, including context and acceptance criteria
+- **activeForm**: Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.
+
+**IMPORTANT**: Always provide activeForm when creating tasks. The subject should be imperative ("Run tests") while activeForm should be present continuous ("Running tests"). All tasks are created with status \`pending\`.
+
+## Tips
+
+- Create tasks with clear, specific subjects that describe the outcome
+- Include enough detail in the description for another agent to understand and complete the task
+- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
+- Check TaskList first to avoid creating duplicate tasks`,
+  execute: async (args, context: ToolContext): Promise<ToolResult> => {
+    const taskManager = context.taskManager;
+    const task: Omit<Task, "id"> = {
+      subject: args.subject as string,
+      description: args.description as string,
+      status: (args.status as TaskStatus) || "pending",
+      activeForm: args.activeForm as string,
+      owner: args.owner as string,
+      blocks: (args.blocks as string[]) || [],
+      blockedBy: (args.blockedBy as string[]) || [],
+      metadata: (args.metadata as Record<string, unknown>) || {},
+    };
+
+    const taskId = await taskManager.createTask(task);
+
+    return {
+      success: true,
+      content: `Task created with ID: ${taskId}`,
+      shortResult: `Created task ${taskId}: ${task.subject}`,
+    };
+  },
+};
+
+export const taskGetTool: ToolPlugin = {
+  name: TASK_GET_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TASK_GET_TOOL_NAME,
+      description: "Get a task by ID from the task list",
+      parameters: {
+        type: "object",
+        properties: {
+          taskId: {
+            type: "string",
+            description: "The ID of the task to retrieve",
+          },
+        },
+        required: ["taskId"],
+      },
+    },
+  },
+  prompt: () => `Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements
+
+## Output
+
+Returns full task details:
+- **subject**: Task title
+- **description**: Detailed requirements and context
+- **status**: 'pending', 'in_progress', or 'completed'
+- **blocks**: Tasks waiting on this one to complete
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+
+- After fetching a task, verify its blockedBy list is empty before beginning work.
+- Use TaskList to see all tasks in summary form.`,
+  execute: async (args, context: ToolContext): Promise<ToolResult> => {
+    const taskManager = context.taskManager;
+    const taskId = args.taskId as string;
+
+    const task = await taskManager.getTask(taskId);
+    if (!task) {
+      return {
+        success: false,
+        content: `Task with ID ${taskId} not found.`,
+      };
+    }
+
+    return {
+      success: true,
+      content: JSON.stringify(task, null, 2),
+    };
+  },
+};
+
+export const taskUpdateTool: ToolPlugin = {
+  name: TASK_UPDATE_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TASK_UPDATE_TOOL_NAME,
+      description: "Update a task in the task list",
+      parameters: {
+        type: "object",
+        properties: {
+          taskId: {
+            type: "string",
+            description: "The ID of the task to update",
+          },
+          subject: {
+            type: "string",
+            description: "New subject for the task",
+          },
+          description: {
+            type: "string",
+            description: "New description for the task",
+          },
+          activeForm: {
+            type: "string",
+            description:
+              'Present continuous form shown in spinner when in_progress (e.g., "Running tests")',
+          },
+          status: {
+            type: "string",
+            enum: ["pending", "in_progress", "completed", "deleted"],
+            description: "New status for the task",
+          },
+          addBlocks: {
+            type: "array",
+            items: { type: "string" },
+            description: "Task IDs that this task blocks",
+          },
+          addBlockedBy: {
+            type: "array",
+            items: { type: "string" },
+            description: "Task IDs that block this task",
+          },
+          owner: {
+            type: "string",
+            description: "New owner for the task",
+          },
+          metadata: {
+            type: "object",
+            description:
+              "Metadata keys to merge into the task. Set a key to null to delete it.",
+          },
+        },
+        required: ["taskId"],
+      },
+    },
+  },
+  prompt: () => `Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to \`deleted\` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: \`pending\` → \`in_progress\` → \`completed\`
+
+Use \`deleted\` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using \`TaskGet\` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+\`\`\`json
+{"taskId": "1", "status": "in_progress"}
+\`\`\`
+
+Mark task as completed after finishing work:
+\`\`\`json
+{"taskId": "1", "status": "completed"}
+\`\`\`
+
+Delete a task:
+\`\`\`json
+{"taskId": "1", "status": "deleted"}
+\`\`\`
+
+Claim a task by setting owner:
+\`\`\`json
+{"taskId": "1", "owner": "my-name"}
+\`\`\`
+
+Set up task dependencies:
+\`\`\`json
+{"taskId": "2", "addBlockedBy": ["1"]}
+\`\`\`
+`,
+  execute: async (args, context: ToolContext): Promise<ToolResult> => {
+    const taskManager = context.taskManager;
+    const taskId = args.taskId as string;
+
+    const existingTask = await taskManager.getTask(taskId);
+    if (!existingTask) {
+      return {
+        success: false,
+        content: `Task with ID ${taskId} not found.`,
+      };
+    }
+
+    const updatedFields: string[] = [];
+
+    const updatedTask: Task = {
+      ...existingTask,
+    };
+
+    if (args.subject !== undefined && args.subject !== existingTask.subject) {
+      updatedTask.subject = args.subject as string;
+      updatedFields.push("subject");
+    }
+    if (
+      args.description !== undefined &&
+      args.description !== existingTask.description
+    ) {
+      updatedTask.description = args.description as string;
+      updatedFields.push("description");
+    }
+    if (args.status !== undefined && args.status !== existingTask.status) {
+      updatedTask.status = args.status as TaskStatus;
+      updatedFields.push("status");
+    }
+    if (
+      args.activeForm !== undefined &&
+      args.activeForm !== existingTask.activeForm
+    ) {
+      updatedTask.activeForm = args.activeForm as string;
+      updatedFields.push("activeForm");
+    }
+    if (args.owner !== undefined && args.owner !== existingTask.owner) {
+      updatedTask.owner = args.owner as string;
+      updatedFields.push("owner");
+    }
+
+    if (args.metadata !== undefined) {
+      const newMetadata = { ...(existingTask.metadata || {}) };
+      for (const [key, value] of Object.entries(
+        args.metadata as Record<string, unknown>,
+      )) {
+        if (value === null) {
+          delete newMetadata[key];
+        } else {
+          newMetadata[key] = value;
+        }
+      }
+      updatedTask.metadata = newMetadata;
+      updatedFields.push("metadata");
+    }
+
+    if (args.addBlocks !== undefined) {
+      const blocksToAdd = (args.addBlocks as string[]).filter(
+        (id) => !updatedTask.blocks.includes(id),
+      );
+      if (blocksToAdd.length > 0) {
+        updatedTask.blocks = [...updatedTask.blocks, ...blocksToAdd];
+        updatedFields.push("blocks");
+
+        // Also update the blockedBy of the target tasks
+        for (const targetId of blocksToAdd) {
+          const targetTask = await taskManager.getTask(targetId);
+          if (targetTask && !targetTask.blockedBy.includes(taskId)) {
+            await taskManager.updateTask({
+              ...targetTask,
+              blockedBy: [...targetTask.blockedBy, taskId],
+            });
+          }
+        }
+      }
+    }
+
+    if (args.addBlockedBy !== undefined) {
+      const blockedByToAdd = (args.addBlockedBy as string[]).filter(
+        (id) => !updatedTask.blockedBy.includes(id),
+      );
+      if (blockedByToAdd.length > 0) {
+        updatedTask.blockedBy = [...updatedTask.blockedBy, ...blockedByToAdd];
+        updatedFields.push("blockedBy");
+
+        // Also update the blocks of the target tasks
+        for (const targetId of blockedByToAdd) {
+          const targetTask = await taskManager.getTask(targetId);
+          if (targetTask && !targetTask.blocks.includes(taskId)) {
+            await taskManager.updateTask({
+              ...targetTask,
+              blocks: [...targetTask.blocks, taskId],
+            });
+          }
+        }
+      }
+    }
+
+    await taskManager.updateTask(updatedTask);
+
+    let content = `Updated task #${taskId} ${updatedFields.join(", ")}`;
+    if (updatedTask.status === "completed") {
+      content += `\n\nTask completed. Call TaskList now to find your next available task or see if your work unblocked others.`;
+    }
+
+    return {
+      success: true,
+      content,
+      shortResult: `Updated task ${taskId}`,
+    };
+  },
+};
+
+export const taskListTool: ToolPlugin = {
+  name: TASK_LIST_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TASK_LIST_TOOL_NAME,
+      description: "List all tasks in the task list",
+      parameters: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            enum: ["pending", "in_progress", "completed", "deleted"],
+            description: "Optional filter by status.",
+          },
+        },
+      },
+    },
+  },
+  prompt: () => `Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task
+- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+
+## Output
+
+Returns a summary of each task:
+- **id**: Task identifier (use with TaskGet, TaskUpdate)
+- **subject**: Brief description of the task
+- **status**: 'pending', 'in_progress', or 'completed'
+- **owner**: Agent ID if assigned, empty if available
+- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+
+Use TaskGet with a specific task ID to view full details including description and comments.`,
+  execute: async (args, context: ToolContext): Promise<ToolResult> => {
+    const taskManager = context.taskManager;
+
+    let tasks = await taskManager.listTasks();
+    if (args.status) {
+      tasks = tasks.filter((t) => t.status === args.status);
+    }
+
+    if (tasks.length === 0) {
+      return {
+        success: true,
+        content: "No tasks found.",
+      };
+    }
+
+    // Sort by ID numerically
+    tasks.sort((a, b) => parseInt(a.id, 10) - parseInt(b.id, 10));
+
+    const content = tasks
+      .map((t) => `[${t.id}] ${t.subject} (${t.status})`)
+      .join("\n");
+
+    return {
+      success: true,
+      content,
+    };
+  },
+};