wave-agent-sdk 0.2.1 → 0.5.0

package/src/tools/taskStopTool.ts

@@ -0,0 +1,72 @@
+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: "Stops a running background task",
+      parameters: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The ID of the background task to stop",
+          },
+        },
+        required: ["task_id"],
+      },
+    },
+  },
+  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"],
           },
@@ -57,80 +62,131 @@ export function createTaskTool(subagentManager: SubagentManager): ToolPlugin {
       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}. Use TaskOutput to monitor progress.`,
+                    shortResult: "Task backgrounded",
+                  });
+                },
+              });
+            }
+
+            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

@@ -39,6 +39,7 @@ export interface ToolResult {
 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;
@@ -50,4 +51,10 @@ export interface ToolContext {
   mcpManager?: import("../managers/mcpManager.js").McpManager;
   /** LSP manager instance for code intelligence */
   lspManager?: import("../types/lsp.js").ILspManager;
+  /** Reversion manager instance for file snapshots */
+  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;
 }

package/src/tools/writeTool.ts

@@ -126,9 +126,23 @@ export const writeTool: ToolPlugin = {
         }
       }
 
+      // Record snapshot for reversion
+      let snapshotId: string | undefined;
+      if (context.reversionManager && context.messageId) {
+        snapshotId = await context.reversionManager.recordSnapshot(
+          context.messageId,
+          resolvedPath,
+          isExistingFile ? "modify" : "create",
+        );
+      }
+
       // Write file
       try {
         await writeFile(resolvedPath, content, "utf-8");
+        // Commit snapshot on success
+        if (context.reversionManager && snapshotId) {
+          await context.reversionManager.commitSnapshot(snapshotId);
+        }
       } catch (writeError) {
         return {
           success: false,

package/src/types/commands.ts

@@ -29,4 +29,7 @@ export interface CustomSlashCommand {
   isNested: boolean; // Whether command is in a subdirectory
   depth: number; // 0 = root, 1 = nested
   segments: string[]; // Path components for ID generation (e.g., ["openspec", "apply"])
+
+  // Plugin support
+  pluginPath?: string; // Absolute path to the plugin root directory (only set for plugin commands)
 }

package/src/types/configuration.ts

@@ -9,6 +9,8 @@
 import type { HookEvent, HookEventConfig } from "./hooks.js";
 import type { PermissionMode } from "./permissions.js";
 
+export type Scope = "user" | "project" | "local";
+
 /**
  * Root configuration structure for all Wave Agent settings including hooks and environment variables
  */
@@ -28,6 +30,8 @@ export interface WaveConfiguration {
   };
   /** New field for scoped plugin management */
   enabledPlugins?: Record<string, boolean>;
+  /** Preferred language for agent communication */
+  language?: string;
 }
 
 /**

package/src/types/environment.ts

@@ -1,3 +1,5 @@
+import type { Scope } from "./configuration.js";
+
 /**
  * Environment Variable System Types
  *
@@ -100,5 +102,5 @@ export interface EnvironmentConflict {
   /** Final resolved value (which source won) */
   resolvedValue: string;
   /** Which source provided the final value */
-  source: "user" | "project";
+  source: Scope;
 }

package/src/types/history.ts

@@ -0,0 +1,4 @@
+export interface PromptEntry {
+  prompt: string;
+  timestamp: number;
+}

package/src/types/index.ts

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

package/src/types/marketplace.ts

@@ -1,3 +1,5 @@
+import { Scope } from "./configuration.js";
+
 export interface MarketplaceOwner {
   name: string;
   email?: string;
@@ -34,6 +36,7 @@ export type MarketplaceSource =
 export interface KnownMarketplace {
   name: string;
   source: MarketplaceSource;
+  isBuiltin?: boolean;
 }
 
 export interface KnownMarketplacesRegistry {
@@ -45,6 +48,8 @@ export interface InstalledPlugin {
   marketplace: string;
   version: string;
   cachePath: string;
+  scope?: Scope;
+  projectPath?: string;
 }
 
 export interface InstalledPluginsRegistry {

package/src/types/messaging.ts

@@ -12,6 +12,7 @@ export enum MessageSource {
 }
 
 export interface Message {
+  id?: string; // Unique identifier for the message
   role: "user" | "assistant";
   blocks: MessageBlock[];
   usage?: Usage; // Usage data for this message's AI operation (assistant messages only)
@@ -27,7 +28,8 @@ export type MessageBlock =
   | CompressBlock
   | MemoryBlock
   | SubagentBlock
-  | ReasoningBlock;
+  | ReasoningBlock
+  | FileHistoryBlock;
 
 export interface TextBlock {
   type: "text";
@@ -101,9 +103,15 @@ export interface SubagentBlock {
   status: "active" | "completed" | "error" | "aborted";
   sessionId: string;
   configuration: SubagentConfiguration;
+  runInBackground?: boolean;
 }
 
 export interface ReasoningBlock {
   type: "reasoning";
   content: string;
 }
+
+export interface FileHistoryBlock {
+  type: "file_history";
+  snapshots: import("./reversion.js").FileSnapshot[];
+}

package/src/types/processes.ts

@@ -5,14 +5,43 @@
 
 import type { ChildProcess } from "child_process";
 
-export interface BackgroundShell {
+export type BackgroundTaskStatus =
+  | "running"
+  | "completed"
+  | "failed"
+  | "killed";
+export type BackgroundTaskType = "shell" | "subagent";
+
+export interface BackgroundTask {
   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;
 }
+
+export interface BackgroundShell extends BackgroundTask {
+  type: "shell";
+  process: ChildProcess;
+}
+
+export interface ForegroundTask {
+  id: string;
+  backgroundHandler: () => Promise<void>;
+}
+
+export interface IForegroundTaskManager {
+  registerForegroundTask(task: ForegroundTask): void;
+  unregisterForegroundTask(id: string): void;
+}
+
+export interface IForegroundTaskManager {
+  registerForegroundTask(task: ForegroundTask): void;
+  unregisterForegroundTask(id: string): void;
+}

package/src/types/reversion.ts

@@ -0,0 +1,29 @@
+/**
+ * Represents the state of a file before an agent operation.
+ */
+export interface FileSnapshot {
+  /** The ID of the message/turn this snapshot is associated with. */
+  messageId: string;
+  /** Absolute path to the file. */
+  filePath: string;
+  /** Path to the stored snapshot file. */
+  snapshotPath?: string;
+  /** When the snapshot was taken. */
+  timestamp: number;
+  /** The operation that triggered this snapshot. */
+  operation: "create" | "modify" | "delete";
+}
+
+/**
+ * A point in the conversation history that can be reverted to.
+ */
+export interface Checkpoint {
+  /** The index of the user message in the history. */
+  index: number;
+  /** The unique ID of the user message. */
+  messageId: string;
+  /** A short snippet of the message content for the UI. */
+  preview: string;
+  /** When the message was sent. */
+  timestamp: number;
+}

package/src/utils/builtinSubagents.ts

@@ -1,3 +1,4 @@
+import { GENERAL_PURPOSE_SYSTEM_PROMPT } from "../constants/prompts.js";
 import type { SubagentConfiguration } from "./subagentParser.js";
 
 /**
@@ -7,10 +8,27 @@ import type { SubagentConfiguration } from "./subagentParser.js";
 export function getBuiltinSubagents(): SubagentConfiguration[] {
   return [
     createExploreSubagent(),
+    createGeneralPurposeSubagent(),
     // Add more built-in subagents here as needed
   ];
 }
 
+/**
+ * Create the General-Purpose built-in subagent configuration
+ * Specialized for multi-step research and implementation tasks
+ */
+function createGeneralPurposeSubagent(): SubagentConfiguration {
+  return {
+    name: "general-purpose",
+    description:
+      "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
+    systemPrompt: GENERAL_PURPOSE_SYSTEM_PROMPT,
+    filePath: "<builtin:general-purpose>",
+    scope: "builtin",
+    priority: 3,
+  };
+}
+
 /**
  * Create the Explore built-in subagent configuration
  * Specialized for codebase exploration and file search tasks

package/src/utils/constants.ts

@@ -12,9 +12,9 @@ import os from "os";
 export const DATA_DIRECTORY = path.join(os.homedir(), ".wave");
 
 /**
- * Bash command history file path
+ * Prompt history file path
  */
-export const BASH_HISTORY_FILE = path.join(DATA_DIRECTORY, "bash-history.json");
+export const PROMPT_HISTORY_FILE = path.join(DATA_DIRECTORY, "history.jsonl");
 
 /**
  * Error log directory path