wave-agent-sdk 0.5.0 → 0.6.0

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,
+    };
+  },
+};

package/src/tools/taskOutputTool.ts

@@ -10,38 +10,47 @@ export const taskOutputTool: ToolPlugin = {
     type: "function",
     function: {
       name: TASK_OUTPUT_TOOL_NAME,
-      description:
-        "Retrieves output from a running or completed background task",
+      description: "Retrieves output from a running or completed task",
       parameters: {
         type: "object",
         properties: {
           task_id: {
             type: "string",
-            description:
-              "The ID of the background task to retrieve output from",
-          },
-          filter: {
-            type: "string",
-            description:
-              "Optional regular expression to filter the output lines.",
+            description: "The task ID to get output from",
           },
           block: {
             type: "boolean",
-            description:
-              "If true, wait for the task to complete before returning output. If false, return current output immediately.",
+            default: true,
+            description: "Whether to wait for completion",
+          },
+          timeout: {
+            type: "number",
+            minimum: 0,
+            maximum: 600000,
+            default: 30000,
+            description: "Max wait time in ms",
           },
         },
         required: ["task_id"],
       },
     },
   },
+  prompt:
+    () => `- Retrieves output from a running or completed task (background shell, agent, or remote session)
+- Takes a task_id parameter identifying the task
+- Returns the task output along with status information
+- Use block=true (default) to wait for task completion
+- Use block=false for non-blocking check of current status
+- Task IDs can be found using the /tasks command
+- Works with all task types: background shells, async agents, and remote sessions`,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolResult> => {
     const taskId = args.task_id as string;
     const filter = args.filter as string | undefined;
-    const block = args.block as boolean | undefined;
+    const block = (args.block as boolean | undefined) ?? true;
+    const timeout = (args.timeout as number | undefined) ?? 30000;
 
     if (!taskId || typeof taskId !== "string") {
       return {
@@ -91,6 +100,7 @@ export const taskOutputTool: ToolPlugin = {
       return new Promise((resolve) => {
         let timeoutHandle: NodeJS.Timeout | null = null;
         let isAborted = false;
+        const startTime = Date.now();
 
         const cleanup = () => {
           if (timeoutHandle) {
@@ -122,6 +132,18 @@ export const taskOutputTool: ToolPlugin = {
         const check = () => {
           if (isAborted) return;
 
+          if (Date.now() - startTime > timeout) {
+            if (context.abortSignal) {
+              context.abortSignal.removeEventListener("abort", onAbort);
+            }
+            resolve({
+              success: true,
+              content: "Retrieval timed out",
+              shortResult: `${taskId}: timeout`,
+            });
+            return;
+          }
+
           const task = backgroundTaskManager.getTask(taskId);
           if (!task) {
             if (context.abortSignal) {

package/src/tools/taskStopTool.ts

@@ -7,7 +7,7 @@ export const taskStopTool: ToolPlugin = {
     type: "function",
     function: {
       name: TASK_STOP_TOOL_NAME,
-      description: "Stops a running background task",
+      description: "Stop a running background task by ID",
       parameters: {
         type: "object",
         properties: {
@@ -20,6 +20,12 @@ export const taskStopTool: ToolPlugin = {
       },
     },
   },
+  prompt: () => `
+- Stops a running background task by its ID
+- Takes a task_id parameter identifying the task to stop
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running task
+`,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,

package/src/tools/taskTool.ts

@@ -58,6 +58,11 @@ export function createTaskTool(subagentManager: SubagentManager): ToolPlugin {
       };
     },
 
+    prompt: () => `
+- When doing file search, prefer to use the ${TASK_TOOL_NAME} tool in order to reduce context usage.
+- You should proactively use the ${TASK_TOOL_NAME} tool with specialized agents when the task at hand matches the agent's description.
+- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the ${TASK_TOOL_NAME} tool with subagent_type=Explore instead of running search commands directly.`,
+
     execute: async (
       args: Record<string, unknown>,
       context: ToolContext,
@@ -140,8 +145,9 @@ export function createTaskTool(subagentManager: SubagentManager): ToolPlugin {
                   // Resolve the tool execution early so the main agent can continue
                   resolve({
                     success: true,
-                    content: `Task moved to background with ID: ${taskId}. Use TaskOutput to monitor progress.`,
+                    content: `Task moved to background with ID: ${taskId}.`,
                     shortResult: "Task backgrounded",
+                    isManuallyBackgrounded: true,
                   });
                 },
               });

package/src/tools/types.ts

@@ -19,6 +19,10 @@ export interface ToolPlugin {
     params: Record<string, unknown>,
     context: ToolContext,
   ) => string;
+  /**
+   * Optional function to provide a prompt to be added to the system prompt
+   */
+  prompt?: (context: ToolContext) => string;
 }
 
 export interface ToolResult {
@@ -34,6 +38,8 @@ export interface ToolResult {
     data: string; // base64 encoded image data
     mediaType?: string; // Image media type, such as "image/png"
   }>;
+  // Whether the tool was manually backgrounded by the user (e.g. via Ctrl-B)
+  isManuallyBackgrounded?: boolean;
 }
 
 export interface ToolContext {
@@ -57,4 +63,8 @@ export interface ToolContext {
   messageId?: string;
   /** Foreground task manager for backgrounding tasks */
   foregroundTaskManager?: import("../types/processes.js").IForegroundTaskManager;
+  /** Task manager instance for task management */
+  taskManager: import("../services/taskManager.js").TaskManager;
+  /** Current session ID */
+  sessionId?: string;
 }

package/src/tools/writeTool.ts

@@ -13,8 +13,7 @@ export const writeTool: ToolPlugin = {
     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.\n- IMPORTANT: Always provide file_path parameter before content parameter when calling this tool.",
+      description: "Writes a file to the local filesystem.",
       parameters: {
         type: "object",
         properties: {
@@ -33,6 +32,14 @@ export const writeTool: ToolPlugin = {
       },
     },
   },
+  prompt: () => `
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- 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.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
+- IMPORTANT: Always provide file_path parameter before content parameter when calling this tool.`,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,

package/src/types/index.ts

@@ -33,3 +33,4 @@ export * from "./plugins.js";
 export * from "./marketplace.js";
 export * from "./memoryRule.js";
 export * from "./history.js";
+export * from "./tasks.js";