wave-agent-sdk 0.0.2 → 0.0.4

package/src/tools/skillTool.ts

@@ -0,0 +1,82 @@
+import type { ToolPlugin, ToolResult } from "./types.js";
+import type { SkillManager } from "../managers/skillManager.js";
+
+/**
+ * Create a skill tool plugin that uses the provided SkillManager
+ * Note: SkillManager should be initialized before calling this function
+ */
+export function createSkillTool(skillManager: SkillManager): ToolPlugin {
+  const getToolDescription = (): string => {
+    const availableSkills = skillManager.getAvailableSkills();
+
+    if (availableSkills.length === 0) {
+      return "Invoke a Wave skill by name. Skills are user-defined automation templates that can be personal or project-specific. No skills are currently available.";
+    }
+
+    const skillList = availableSkills
+      .map(
+        (skill) => `• **${skill.name}** (${skill.type}): ${skill.description}`,
+      )
+      .join("\n");
+
+    return `Invoke a Wave skill by name. Skills are user-defined automation templates that can be personal or project-specific.\n\nAvailable skills:\n${skillList}`;
+  };
+
+  return {
+    name: "skill",
+    config: {
+      type: "function",
+      function: {
+        name: "skill",
+        description: getToolDescription(),
+        parameters: {
+          type: "object",
+          properties: {
+            skill_name: {
+              type: "string",
+              description: "Name of the skill to invoke",
+              enum: skillManager
+                .getAvailableSkills()
+                .map((skill) => skill.name),
+            },
+          },
+          required: ["skill_name"],
+        },
+      },
+    },
+    execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
+      try {
+        // Validate arguments
+        const skillName = args.skill_name as string;
+        if (!skillName || typeof skillName !== "string") {
+          return {
+            success: false,
+            content: "",
+            error: "skill_name parameter is required and must be a string",
+          };
+        }
+
+        // Execute the skill
+        const result = await skillManager.executeSkill({
+          skill_name: skillName,
+        });
+
+        return {
+          success: true,
+          content: result.content,
+          shortResult: `Invoked skill: ${skillName}`,
+        };
+      } catch (error) {
+        return {
+          success: false,
+          content: "",
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+    formatCompactParams: (params: Record<string, unknown>) => {
+      const skillName = params.skill_name as string;
+      return skillName || "unknown-skill";
+    },
+  };
+}

package/src/tools/taskTool.ts

@@ -0,0 +1,128 @@
+import type { ToolPlugin, ToolResult } from "./types.js";
+import type { SubagentManager } from "../managers/subagentManager.js";
+
+/**
+ * Create a task tool plugin that uses the provided SubagentManager
+ * Note: SubagentManager should be initialized before calling this function
+ */
+export function createTaskTool(subagentManager: SubagentManager): ToolPlugin {
+  // Get available subagents from the initialized subagent manager
+  const availableSubagents = subagentManager.getConfigurations();
+  const subagentList = availableSubagents
+    .map((config) => `- ${config.name}: ${config.description}`)
+    .join("\n");
+
+  const description = `Delegate a task to a specialized subagent. Use this when you need specialized expertise or want to break down complex work into focused subtasks.
+
+Available subagents:
+${subagentList || "No subagents configured"}`;
+
+  return {
+    name: "Task",
+    config: {
+      type: "function",
+      function: {
+        name: "Task",
+        description,
+        parameters: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description:
+                "A clear, concise description of what needs to be accomplished",
+            },
+            prompt: {
+              type: "string",
+              description:
+                "The specific instructions or prompt to send to the subagent",
+            },
+            subagent_type: {
+              type: "string",
+              description: `The type or name of subagent to use. Available options: ${availableSubagents.map((c) => c.name).join(", ") || "none"}`,
+            },
+          },
+          required: ["description", "prompt", "subagent_type"],
+        },
+      },
+    },
+
+    execute: async (args: Record<string, unknown>): 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,
+        );
+        const response = await subagentManager.executeTask(instance, prompt);
+
+        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",
+        };
+      }
+    },
+
+    formatCompactParams: (params: Record<string, unknown>) => {
+      const subagent_type = params.subagent_type as string;
+      const description = params.description as string;
+      return `${subagent_type || "unknown"}: ${description || "no description"}`;
+    },
+  };
+}

package/src/tools/todoWriteTool.ts

@@ -0,0 +1,232 @@
+import type { ToolPlugin, ToolResult } from "./types.js";
+
+interface TodoItem {
+  content: string;
+  status: "pending" | "in_progress" | "completed";
+  id: string;
+}
+
+/**
+ * TodoWrite tool for creating and managing structured task lists
+ */
+export const todoWriteTool: ToolPlugin = {
+  name: "TodoWrite",
+  config: {
+    type: "function",
+    function: {
+      name: "TodoWrite",
+      description: `Use this tool to create and manage 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:
+
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+3. User explicitly requests todo list - When the user directly asks you to use the todo list
+4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+5. After receiving new instructions - Immediately capture user requirements as todos
+6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
+7. 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:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking it provides no organizational benefit
+3. The task can be completed in less than 3 trivial steps
+4. 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 States and Management
+
+1. **Task States**: Use these states to track progress:
+   - pending: Task not yet started
+   - in_progress: Currently working on (limit to ONE task at a time)
+   - completed: Task finished successfully
+
+2. **Task Management**:
+   - Update task status in real-time as you work
+   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+   - Only have ONE task in_progress at any time
+   - Complete current tasks before starting new ones
+   - Remove tasks that are no longer relevant from the list entirely
+
+3. **Task Completion Requirements**:
+   - 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
+
+4. **Task Breakdown**:
+   - Create specific, actionable items
+   - Break complex tasks into smaller, manageable steps
+   - Use clear, descriptive task names
+
+When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.`,
+      parameters: {
+        type: "object",
+        properties: {
+          todos: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                content: {
+                  type: "string",
+                  minLength: 1,
+                },
+                status: {
+                  type: "string",
+                  enum: ["pending", "in_progress", "completed"],
+                },
+                id: {
+                  type: "string",
+                },
+              },
+              required: ["content", "status", "id"],
+              additionalProperties: false,
+            },
+            description: "The updated todo list",
+          },
+        },
+        required: ["todos"],
+        additionalProperties: false,
+      },
+    },
+  },
+
+  execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
+    try {
+      // Validate arguments
+      const { todos } = args as { todos?: TodoItem[] };
+
+      if (!todos || !Array.isArray(todos)) {
+        return {
+          success: false,
+          content: "",
+          error: "todos parameter must be an array",
+          shortResult: "Invalid todos format",
+        };
+      }
+
+      // Validate each task item
+      for (const [index, todo] of todos.entries()) {
+        if (!todo || typeof todo !== "object") {
+          return {
+            success: false,
+            content: "",
+            error: `Todo item at index ${index} must be an object`,
+            shortResult: "Invalid todo item",
+          };
+        }
+
+        if (
+          !todo.content ||
+          typeof todo.content !== "string" ||
+          todo.content.trim().length === 0
+        ) {
+          return {
+            success: false,
+            content: "",
+            error: `Todo item at index ${index} must have non-empty content`,
+            shortResult: "Invalid todo content",
+          };
+        }
+
+        if (!["pending", "in_progress", "completed"].includes(todo.status)) {
+          return {
+            success: false,
+            content: "",
+            error: `Todo item at index ${index} has invalid status: ${todo.status}`,
+            shortResult: "Invalid todo status",
+          };
+        }
+
+        if (
+          !todo.id ||
+          typeof todo.id !== "string" ||
+          todo.id.trim().length === 0
+        ) {
+          return {
+            success: false,
+            content: "",
+            error: `Todo item at index ${index} must have a non-empty id`,
+            shortResult: "Invalid todo id",
+          };
+        }
+      }
+
+      // Check for duplicate IDs
+      const ids = todos.map((todo) => todo.id);
+      const duplicateIds = ids.filter((id, index) => ids.indexOf(id) !== index);
+      if (duplicateIds.length > 0) {
+        return {
+          success: false,
+          content: "",
+          error: `Duplicate todo IDs found: ${duplicateIds.join(", ")}`,
+          shortResult: "Duplicate todo IDs",
+        };
+      }
+
+      // Check that only one task is in_progress
+      const inProgressTodos = todos.filter(
+        (todo) => todo.status === "in_progress",
+      );
+      if (inProgressTodos.length > 1) {
+        return {
+          success: false,
+          content: "",
+          error: `Only one todo can be in_progress at a time. Found ${inProgressTodos.length} in_progress todos`,
+          shortResult: "Multiple in_progress todos",
+        };
+      }
+
+      const completedCount = todos.filter(
+        (t) => t.status === "completed",
+      ).length;
+      const totalCount = todos.length;
+
+      let shortResult = `${completedCount}/${totalCount} done`;
+
+      if (totalCount > 0) {
+        const symbols = {
+          pending: "[ ]",
+          in_progress: "[>]",
+          completed: "[x]",
+        };
+        const inProgress = todos.filter((t) => t.status === "in_progress");
+        const pending = todos.filter((t) => t.status === "pending");
+
+        if (inProgress.length > 0) {
+          shortResult += `\n${symbols.in_progress} ${inProgress[0].content}`;
+        }
+
+        if (pending.length > 0) {
+          shortResult += `\n${symbols.pending} ${pending[0].content}`;
+          if (pending.length > 1) {
+            shortResult += ` +${pending.length - 1}`;
+          }
+        }
+      }
+
+      return {
+        success: true,
+        content: `Todo list updated: ${completedCount}/${totalCount} completed`,
+        shortResult: shortResult,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        content: "",
+        error: error instanceof Error ? error.message : String(error),
+        shortResult: "Todo list update failed",
+      };
+    }
+  },
+};

package/src/types.ts

@@ -25,7 +25,8 @@ export type MessageBlock =
   | CommandOutputBlock
   | CompressBlock
   | MemoryBlock
-  | CustomCommandBlock;
+  | CustomCommandBlock
+  | SubagentBlock;
 
 export interface TextBlock {
   type: "text";
@@ -98,6 +99,14 @@ export interface CustomCommandBlock {
   originalInput?: string; // Original user input, used for UI display (e.g., "/fix-issue 123 high")
 }
 
+export interface SubagentBlock {
+  type: "subagent";
+  subagentId: string;
+  subagentName: string;
+  status: "active" | "completed" | "error" | "aborted";
+  messages: Message[];
+}
+
 export interface AIRequest {
   content: string;
   files: unknown[];

package/src/utils/fileFormat.ts

@@ -0,0 +1,40 @@
+import { extname } from "path";
+
+/**
+ * List of binary document file extensions that should not be read as text
+ */
+export const BINARY_DOCUMENT_EXTENSIONS = [
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  ".odt",
+  ".ods",
+  ".odp",
+  ".rtf",
+] as const;
+
+/**
+ * Check if a file is a binary document format based on its extension
+ * @param filePath - The path to the file
+ * @returns true if the file is a binary document format, false otherwise
+ */
+export function isBinaryDocument(filePath: string): boolean {
+  const fileExtension = extname(filePath).toLowerCase();
+  return (BINARY_DOCUMENT_EXTENSIONS as readonly string[]).includes(
+    fileExtension,
+  );
+}
+
+/**
+ * Get a human-readable error message for unsupported binary document formats
+ * @param filePath - The path to the file
+ * @returns Error message string
+ */
+export function getBinaryDocumentError(filePath: string): string {
+  const fileExtension = extname(filePath).toLowerCase();
+  return `Reading binary document files with extension '${fileExtension}' is not supported. Supported formats include text files, code files, images, and Jupyter notebooks.`;
+}

package/src/utils/messageOperations.ts

@@ -504,3 +504,83 @@ export const completeCommandInMessage = ({
   }
   return newMessages;
 };
+
+// Subagent block message operations
+export interface AddSubagentBlockParams {
+  messages: Message[];
+  subagentId: string;
+  subagentName: string;
+  status: "active" | "completed" | "error" | "aborted";
+  subagentMessages?: Message[];
+}
+
+export interface UpdateSubagentBlockParams {
+  messages: Message[];
+  subagentId: string;
+  status: "active" | "completed" | "error" | "aborted";
+  subagentMessages: Message[];
+}
+
+export const addSubagentBlockToMessage = ({
+  messages,
+  subagentId,
+  subagentName,
+  status,
+  subagentMessages = [],
+}: AddSubagentBlockParams): Message[] => {
+  const newMessages = [...messages];
+
+  // Find the last assistant message or create one
+  let lastAssistantMessage = newMessages[newMessages.length - 1];
+
+  if (!lastAssistantMessage || lastAssistantMessage.role !== "assistant") {
+    // Create new assistant message if the last message is not from assistant
+    lastAssistantMessage = {
+      role: "assistant",
+      blocks: [],
+    };
+    newMessages.push(lastAssistantMessage);
+  }
+
+  // Add subagent block
+  lastAssistantMessage.blocks.push({
+    type: "subagent",
+    subagentId,
+    subagentName,
+    status,
+    messages: subagentMessages,
+  });
+
+  return newMessages;
+};
+
+export const updateSubagentBlockInMessage = (
+  messages: Message[],
+  subagentId: string,
+  updates: Partial<{
+    status: "active" | "completed" | "error" | "aborted";
+    messages: Message[];
+  }>,
+): Message[] => {
+  const newMessages = [...messages];
+
+  // Find and update the subagent block
+  for (let i = newMessages.length - 1; i >= 0; i--) {
+    const message = newMessages[i];
+    if (message.role === "assistant") {
+      for (const block of message.blocks) {
+        if (block.type === "subagent" && block.subagentId === subagentId) {
+          if (updates.status !== undefined) {
+            block.status = updates.status;
+          }
+          if (updates.messages !== undefined) {
+            block.messages = updates.messages;
+          }
+          return newMessages;
+        }
+      }
+    }
+  }
+
+  return newMessages;
+};