wave-agent-sdk 0.4.0 → 0.6.1

package/src/tools/taskOutputTool.ts

@@ -0,0 +1,196 @@
+import { TASK_OUTPUT_TOOL_NAME } from "../constants/tools.js";
+import { ToolContext, ToolPlugin, ToolResult } from "./types.js";
+import { stripAnsiColors } from "../utils/stringUtils.js";
+
+const MAX_OUTPUT_LENGTH = 30000;
+
+export const taskOutputTool: ToolPlugin = {
+  name: TASK_OUTPUT_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TASK_OUTPUT_TOOL_NAME,
+      description: "Retrieves output from a running or completed task",
+      parameters: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The task ID to get output from",
+          },
+          block: {
+            type: "boolean",
+            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) ?? true;
+    const timeout = (args.timeout as number | undefined) ?? 30000;
+
+    if (!taskId || typeof taskId !== "string") {
+      return {
+        success: false,
+        content: "",
+        error: "task_id parameter is required and must be a string",
+      };
+    }
+
+    const backgroundTaskManager = context?.backgroundTaskManager;
+    if (!backgroundTaskManager) {
+      return {
+        success: false,
+        content: "",
+        error: "Background task manager not available",
+      };
+    }
+
+    const getResult = () => {
+      const output = backgroundTaskManager.getOutput(taskId, filter);
+      if (!output) return null;
+
+      let content = "";
+      if (output.stdout) {
+        content += stripAnsiColors(output.stdout);
+      }
+      if (output.stderr) {
+        content += (content ? "\n" : "") + stripAnsiColors(output.stderr);
+      }
+
+      const finalContent = content || "No output available";
+      const processedContent =
+        finalContent.length > MAX_OUTPUT_LENGTH
+          ? finalContent.substring(0, MAX_OUTPUT_LENGTH) +
+            "\n\n... (output truncated)"
+          : finalContent;
+
+      return {
+        success: true,
+        content: processedContent,
+        shortResult: `${taskId}: ${output.status}`,
+      };
+    };
+
+    if (block) {
+      // Polling for completion
+      return new Promise((resolve) => {
+        let timeoutHandle: NodeJS.Timeout | null = null;
+        let isAborted = false;
+        const startTime = Date.now();
+
+        const cleanup = () => {
+          if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            timeoutHandle = null;
+          }
+        };
+
+        const onAbort = () => {
+          isAborted = true;
+          cleanup();
+          resolve({
+            success: false,
+            content: "",
+            error: "Task output retrieval was aborted",
+          });
+        };
+
+        if (context.abortSignal) {
+          if (context.abortSignal.aborted) {
+            onAbort();
+            return;
+          }
+          context.abortSignal.addEventListener("abort", onAbort, {
+            once: true,
+          });
+        }
+
+        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) {
+              context.abortSignal.removeEventListener("abort", onAbort);
+            }
+            resolve({
+              success: false,
+              content: "",
+              error: `Task with ID ${taskId} not found`,
+            });
+            return;
+          }
+
+          if (task.status !== "running") {
+            if (context.abortSignal) {
+              context.abortSignal.removeEventListener("abort", onAbort);
+            }
+            const result = getResult();
+            resolve(
+              result || {
+                success: false,
+                content: "",
+                error: "Task not found",
+              },
+            );
+          } else {
+            timeoutHandle = setTimeout(check, 500);
+          }
+        };
+        check();
+      });
+    }
+
+    const result = getResult();
+    if (!result) {
+      return {
+        success: false,
+        content: "",
+        error: `Task with ID ${taskId} not found`,
+      };
+    }
+
+    return result;
+  },
+  formatCompactParams: (params: Record<string, unknown>) => {
+    const taskId = params.task_id as string;
+    const block = params.block as boolean;
+    return `${taskId}${block ? " (blocking)" : ""}`;
+  },
+};

package/src/tools/taskStopTool.ts

@@ -0,0 +1,78 @@
+import { TASK_STOP_TOOL_NAME } from "../constants/tools.js";
+import { ToolContext, ToolPlugin, ToolResult } from "./types.js";
+
+export const taskStopTool: ToolPlugin = {
+  name: TASK_STOP_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TASK_STOP_TOOL_NAME,
+      description: "Stop a running background task by ID",
+      parameters: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The ID of the background task to stop",
+          },
+        },
+        required: ["task_id"],
+      },
+    },
+  },
+  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,
+  ): Promise<ToolResult> => {
+    const taskId = args.task_id as string;
+
+    if (!taskId || typeof taskId !== "string") {
+      return {
+        success: false,
+        content: "",
+        error: "task_id parameter is required and must be a string",
+      };
+    }
+
+    const backgroundTaskManager = context?.backgroundTaskManager;
+    if (!backgroundTaskManager) {
+      return {
+        success: false,
+        content: "",
+        error: "Background task manager not available",
+      };
+    }
+
+    const stopped = backgroundTaskManager.stopTask(taskId);
+    if (stopped) {
+      return {
+        success: true,
+        content: `Task ${taskId} has been stopped`,
+        shortResult: `Stopped ${taskId}`,
+      };
+    } else {
+      const task = backgroundTaskManager.getTask(taskId);
+      if (!task) {
+        return {
+          success: false,
+          content: "",
+          error: `Task with ID ${taskId} not found`,
+        };
+      }
+      return {
+        success: false,
+        content: "",
+        error: `Failed to stop task ${taskId} (status: ${task.status})`,
+      };
+    }
+  },
+  formatCompactParams: (params: Record<string, unknown>) => {
+    return params.task_id as string;
+  },
+};

package/src/tools/taskTool.ts

@@ -46,6 +46,11 @@ export function createTaskTool(subagentManager: SubagentManager): ToolPlugin {
                 type: "string",
                 description: `The type or name of subagent to use. Available options: ${availableSubagents.map((c) => c.name).join(", ") || "none"}`,
               },
+              run_in_background: {
+                type: "boolean",
+                description:
+                  "Set to true to run this command in the background. Use TaskOutput to read the output later.",
+              },
             },
             required: ["description", "prompt", "subagent_type"],
           },
@@ -53,84 +58,141 @@ 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,
     ): Promise<ToolResult> => {
-      // Input validation
-      const description = args.description as string;
-      const prompt = args.prompt as string;
-      const subagent_type = args.subagent_type as string;
-
-      if (!description || typeof description !== "string") {
-        return {
-          success: false,
-          content: "",
-          error: "description parameter is required and must be a string",
-          shortResult: "Task delegation failed",
-        };
-      }
-
-      if (!prompt || typeof prompt !== "string") {
-        return {
-          success: false,
-          content: "",
-          error: "prompt parameter is required and must be a string",
-          shortResult: "Task delegation failed",
-        };
-      }
-
-      if (!subagent_type || typeof subagent_type !== "string") {
-        return {
-          success: false,
-          content: "",
-          error: "subagent_type parameter is required and must be a string",
-          shortResult: "Task delegation failed",
-        };
-      }
-
-      try {
-        // Subagent selection logic with explicit name matching only
-        const configuration = await subagentManager.findSubagent(subagent_type);
-
-        if (!configuration) {
-          // Error handling for nonexistent subagents with available subagents listing
-          const allConfigs = subagentManager.getConfigurations();
-          const availableNames = allConfigs.map((c) => c.name).join(", ");
-
-          return {
-            success: false,
-            content: "",
-            error: `No subagent found matching "${subagent_type}". Available subagents: ${availableNames || "none"}`,
-            shortResult: "Subagent not found",
-          };
-        }
-
-        // Create subagent instance and execute task
-        const instance = await subagentManager.createInstance(configuration, {
-          description,
-          prompt,
-          subagent_type,
-        });
-        const response = await subagentManager.executeTask(
-          instance,
-          prompt,
-          context.abortSignal,
-        );
-
-        return {
-          success: true,
-          content: response,
-          shortResult: `Task completed by ${configuration.name}`,
-        };
-      } catch (error) {
-        return {
-          success: false,
-          content: "",
-          error: `Task delegation failed: ${error instanceof Error ? error.message : String(error)}`,
-          shortResult: "Delegation error",
-        };
-      }
+      return new Promise((resolve) => {
+        (async () => {
+          // Input validation
+          const description = args.description as string;
+          const prompt = args.prompt as string;
+          const subagent_type = args.subagent_type as string;
+          const run_in_background = args.run_in_background as boolean;
+
+          if (!description || typeof description !== "string") {
+            return resolve({
+              success: false,
+              content: "",
+              error: "description parameter is required and must be a string",
+              shortResult: "Task delegation failed",
+            });
+          }
+
+          if (!prompt || typeof prompt !== "string") {
+            return resolve({
+              success: false,
+              content: "",
+              error: "prompt parameter is required and must be a string",
+              shortResult: "Task delegation failed",
+            });
+          }
+
+          if (!subagent_type || typeof subagent_type !== "string") {
+            return resolve({
+              success: false,
+              content: "",
+              error: "subagent_type parameter is required and must be a string",
+              shortResult: "Task delegation failed",
+            });
+          }
+
+          try {
+            // Subagent selection logic with explicit name matching only
+            const configuration =
+              await subagentManager.findSubagent(subagent_type);
+
+            if (!configuration) {
+              // Error handling for nonexistent subagents with available subagents listing
+              const allConfigs = subagentManager.getConfigurations();
+              const availableNames = allConfigs.map((c) => c.name).join(", ");
+
+              return resolve({
+                success: false,
+                content: "",
+                error: `No subagent found matching "${subagent_type}". Available subagents: ${availableNames || "none"}`,
+                shortResult: "Subagent not found",
+              });
+            }
+
+            // Create subagent instance and execute task
+            const instance = await subagentManager.createInstance(
+              configuration,
+              {
+                description,
+                prompt,
+                subagent_type,
+              },
+              run_in_background,
+            );
+
+            let isBackgrounded = false;
+
+            // Register for backgrounding if not already in background
+            if (!run_in_background && context.foregroundTaskManager) {
+              context.foregroundTaskManager.registerForegroundTask({
+                id: instance.subagentId,
+                backgroundHandler: async () => {
+                  isBackgrounded = true;
+                  const taskId = await subagentManager.backgroundInstance(
+                    instance.subagentId,
+                  );
+                  // Resolve the tool execution early so the main agent can continue
+                  resolve({
+                    success: true,
+                    content: `Task moved to background with ID: ${taskId}.`,
+                    shortResult: "Task backgrounded",
+                    isManuallyBackgrounded: true,
+                  });
+                },
+              });
+            }
+
+            try {
+              const result = await subagentManager.executeTask(
+                instance,
+                prompt,
+                context.abortSignal,
+                run_in_background,
+              );
+
+              if (isBackgrounded) return;
+
+              if (run_in_background) {
+                return resolve({
+                  success: true,
+                  content: `Task started in background with ID: ${result}`,
+                  shortResult: `Task started in background: ${result}`,
+                });
+              }
+
+              return resolve({
+                success: true,
+                content: result,
+                shortResult: `Task completed by ${configuration.name}`,
+              });
+            } finally {
+              if (!run_in_background && context.foregroundTaskManager) {
+                context.foregroundTaskManager.unregisterForegroundTask(
+                  instance.subagentId,
+                );
+              }
+            }
+          } catch (error) {
+            return resolve({
+              success: false,
+              content: "",
+              error: `Task delegation failed: ${error instanceof Error ? error.message : String(error)}`,
+              shortResult: "Delegation error",
+            });
+          }
+        })();
+      });
     },
 
     formatCompactParams: (params: Record<string, unknown>) => {

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?: () => string;
 }
 
 export interface ToolResult {
@@ -34,11 +38,14 @@ 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 {
   abortSignal?: AbortSignal;
   backgroundBashManager?: import("../managers/backgroundBashManager.js").BackgroundBashManager;
+  backgroundTaskManager?: import("../managers/backgroundTaskManager.js").BackgroundTaskManager;
   workdir: string;
   /** Permission mode for this tool execution */
   permissionMode?: PermissionMode;
@@ -54,4 +61,10 @@ export interface ToolContext {
   reversionManager?: import("../managers/reversionManager.js").ReversionManager;
   /** Current message ID for associating snapshots */
   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";

package/src/types/marketplace.ts

@@ -49,6 +49,7 @@ export interface InstalledPlugin {
   version: string;
   cachePath: string;
   scope?: Scope;
+  projectPath?: string;
 }
 
 export interface InstalledPluginsRegistry {

package/src/types/messaging.ts

@@ -26,7 +26,6 @@ export type MessageBlock =
   | ImageBlock
   | CommandOutputBlock
   | CompressBlock
-  | MemoryBlock
   | SubagentBlock
   | ReasoningBlock
   | FileHistoryBlock;
@@ -67,6 +66,7 @@ export interface ToolBlock {
   error?: string | Error;
   compactParams?: string; // Compact parameter display
   parametersChunk?: string; // Incremental parameter updates for streaming
+  isManuallyBackgrounded?: boolean; // Whether the tool was manually backgrounded by the user
 }
 
 export interface ImageBlock {
@@ -88,14 +88,6 @@ export interface CompressBlock {
   sessionId: string;
 }
 
-export interface MemoryBlock {
-  type: "memory";
-  content: string;
-  isSuccess: boolean;
-  memoryType?: "project" | "user"; // Memory type
-  storagePath?: string; // Storage path text
-}
-
 export interface SubagentBlock {
   type: "subagent";
   subagentId: string;
@@ -103,6 +95,7 @@ export interface SubagentBlock {
   status: "active" | "completed" | "error" | "aborted";
   sessionId: string;
   configuration: SubagentConfiguration;
+  runInBackground?: boolean;
 }
 
 export interface ReasoningBlock {

package/src/types/processes.ts

@@ -5,14 +5,49 @@
 
 import type { ChildProcess } from "child_process";
 
-export interface BackgroundShell {
+export type BackgroundTaskStatus =
+  | "running"
+  | "completed"
+  | "failed"
+  | "killed";
+export type BackgroundTaskType = "shell" | "subagent";
+
+export interface BackgroundTaskBase {
   id: string;
-  process: ChildProcess;
-  command: string;
+  type: BackgroundTaskType;
+  status: BackgroundTaskStatus;
   startTime: number;
-  status: "running" | "completed" | "killed";
+  endTime?: number;
+  command?: string; // for shell
+  description?: string; // for subagent
   stdout: string;
   stderr: string;
   exitCode?: number;
   runtime?: number;
+  /**
+   * Optional callback to be executed when the task is stopped.
+   * This allows tasks to define their own cleanup/abortion logic.
+   */
+  onStop?: () => void | Promise<void>;
+}
+
+export interface BackgroundShell extends BackgroundTaskBase {
+  type: "shell";
+  process: ChildProcess;
+}
+
+export interface BackgroundSubagent extends BackgroundTaskBase {
+  type: "subagent";
+}
+
+export type BackgroundTask = BackgroundShell | BackgroundSubagent;
+
+export interface ForegroundTask {
+  id: string;
+  backgroundHandler: () => Promise<void>;
+}
+
+export interface IForegroundTaskManager {
+  registerForegroundTask(task: ForegroundTask): void;
+  unregisterForegroundTask(id: string): void;
 }