wave-agent-sdk 0.0.1 → 0.0.3

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[];
@@ -258,3 +267,78 @@ export const SKILL_DEFAULTS = {
   SCAN_TIMEOUT: 5000,
   LOAD_TIMEOUT: 2000,
 } as const;
+
+// Configuration types for Agent Constructor Configuration feature
+export interface GatewayConfig {
+  apiKey: string;
+  baseURL: string;
+}
+
+export interface ModelConfig {
+  agentModel: string;
+  fastModel: string;
+}
+
+export interface ConfigurationResolver {
+  /**
+   * Resolves gateway configuration from constructor args and environment
+   * @param apiKey - API key from constructor (optional)
+   * @param baseURL - Base URL from constructor (optional)
+   * @returns Resolved gateway configuration
+   * @throws Error if required configuration is missing after fallbacks
+   */
+  resolveGatewayConfig(apiKey?: string, baseURL?: string): GatewayConfig;
+
+  /**
+   * Resolves model configuration with fallbacks
+   * @param agentModel - Agent model from constructor (optional)
+   * @param fastModel - Fast model from constructor (optional)
+   * @returns Resolved model configuration with defaults
+   */
+  resolveModelConfig(agentModel?: string, fastModel?: string): ModelConfig;
+
+  /**
+   * Resolves token limit with fallbacks
+   * @param constructorLimit - Token limit from constructor (optional)
+   * @returns Resolved token limit
+   */
+  resolveTokenLimit(constructorLimit?: number): number;
+}
+
+export interface ConfigurationValidator {
+  /**
+   * Validates gateway configuration
+   * @param config - Configuration to validate
+   * @throws Error with descriptive message if invalid
+   */
+  validateGatewayConfig(config: GatewayConfig): void;
+
+  /**
+   * Validates token limit value
+   * @param tokenLimit - Token limit to validate
+   * @throws Error if invalid
+   */
+  validateTokenLimit(tokenLimit: number): void;
+}
+
+export class ConfigurationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly provided?: unknown,
+  ) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+}
+
+// Standard error messages
+export const CONFIG_ERRORS = {
+  MISSING_API_KEY:
+    "Gateway configuration requires apiKey. Provide via constructor or AIGW_TOKEN environment variable.",
+  MISSING_BASE_URL:
+    "Gateway configuration requires baseURL. Provide via constructor or AIGW_URL environment variable.",
+  INVALID_TOKEN_LIMIT: "Token limit must be a positive integer.",
+  EMPTY_API_KEY: "API key cannot be empty string.",
+  EMPTY_BASE_URL: "Base URL cannot be empty string.",
+} as const;

package/src/utils/configResolver.ts

@@ -0,0 +1,142 @@
+/**
+ * Configuration resolver utilities for Agent Constructor Configuration
+ * Resolves configuration from constructor arguments with environment fallbacks
+ */
+
+import {
+  GatewayConfig,
+  ModelConfig,
+  ConfigurationError,
+  CONFIG_ERRORS,
+} from "../types.js";
+
+export class ConfigResolver {
+  /**
+   * Resolves gateway configuration from constructor args and environment
+   * @param apiKey - API key from constructor (optional)
+   * @param baseURL - Base URL from constructor (optional)
+   * @returns Resolved gateway configuration
+   * @throws ConfigurationError if required configuration is missing after fallbacks
+   */
+  static resolveGatewayConfig(
+    apiKey?: string,
+    baseURL?: string,
+  ): GatewayConfig {
+    // Resolve API key: constructor > environment variable
+    // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
+    let resolvedApiKey: string;
+    if (apiKey !== undefined) {
+      resolvedApiKey = apiKey;
+    } else {
+      resolvedApiKey = process.env.AIGW_TOKEN || "";
+    }
+
+    if (!resolvedApiKey && apiKey === undefined) {
+      throw new ConfigurationError(CONFIG_ERRORS.MISSING_API_KEY, "apiKey", {
+        constructor: apiKey,
+        environment: process.env.AIGW_TOKEN,
+      });
+    }
+
+    if (resolvedApiKey.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_API_KEY,
+        "apiKey",
+        resolvedApiKey,
+      );
+    }
+
+    // Resolve base URL: constructor > environment variable
+    // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
+    let resolvedBaseURL: string;
+    if (baseURL !== undefined) {
+      resolvedBaseURL = baseURL;
+    } else {
+      resolvedBaseURL = process.env.AIGW_URL || "";
+    }
+
+    if (!resolvedBaseURL && baseURL === undefined) {
+      throw new ConfigurationError(CONFIG_ERRORS.MISSING_BASE_URL, "baseURL", {
+        constructor: baseURL,
+        environment: process.env.AIGW_URL,
+      });
+    }
+
+    if (resolvedBaseURL.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_BASE_URL,
+        "baseURL",
+        resolvedBaseURL,
+      );
+    }
+
+    return {
+      apiKey: resolvedApiKey,
+      baseURL: resolvedBaseURL,
+    };
+  }
+
+  /**
+   * Resolves model configuration with fallbacks
+   * @param agentModel - Agent model from constructor (optional)
+   * @param fastModel - Fast model from constructor (optional)
+   * @returns Resolved model configuration with defaults
+   */
+  static resolveModelConfig(
+    agentModel?: string,
+    fastModel?: string,
+  ): ModelConfig {
+    // Default values as per data-model.md
+    const DEFAULT_AGENT_MODEL = "claude-sonnet-4-20250514";
+    const DEFAULT_FAST_MODEL = "gemini-2.5-flash";
+
+    // Resolve agent model: constructor > environment > default
+    const resolvedAgentModel =
+      agentModel || process.env.AIGW_MODEL || DEFAULT_AGENT_MODEL;
+
+    // Resolve fast model: constructor > environment > default
+    const resolvedFastModel =
+      fastModel || process.env.AIGW_FAST_MODEL || DEFAULT_FAST_MODEL;
+
+    return {
+      agentModel: resolvedAgentModel,
+      fastModel: resolvedFastModel,
+    };
+  }
+
+  /**
+   * Resolves token limit with fallbacks
+   * @param constructorLimit - Token limit from constructor (optional)
+   * @returns Resolved token limit
+   */
+  static resolveTokenLimit(constructorLimit?: number): number {
+    const DEFAULT_TOKEN_LIMIT = 64000;
+
+    // If constructor value provided, use it
+    if (constructorLimit !== undefined) {
+      return constructorLimit;
+    }
+
+    // Try environment variable
+    const envTokenLimit = process.env.TOKEN_LIMIT;
+    if (envTokenLimit) {
+      const parsed = parseInt(envTokenLimit, 10);
+      if (!isNaN(parsed)) {
+        return parsed;
+      }
+    }
+
+    // Use default
+    return DEFAULT_TOKEN_LIMIT;
+  }
+}
+
+/**
+ * Static configuration resolver instance
+ * Implements ConfigurationResolver interface from types.ts
+ */
+export const configResolver = {
+  resolveGatewayConfig: ConfigResolver.resolveGatewayConfig,
+  resolveModelConfig: ConfigResolver.resolveModelConfig,
+  resolveTokenLimit: ConfigResolver.resolveTokenLimit,
+};

package/src/utils/configValidator.ts

@@ -0,0 +1,133 @@
+/**
+ * Configuration validator utilities for Agent Constructor Configuration
+ * Validates configuration values for correctness and security
+ */
+
+import { GatewayConfig, ConfigurationError, CONFIG_ERRORS } from "../types.js";
+
+export class ConfigValidator {
+  /**
+   * Validates gateway configuration
+   * @param config - Configuration to validate
+   * @throws ConfigurationError with descriptive message if invalid
+   */
+  static validateGatewayConfig(config: GatewayConfig): void {
+    // Validate API key
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_API_KEY,
+        "apiKey",
+        config.apiKey,
+      );
+    }
+
+    if (config.apiKey.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_API_KEY,
+        "apiKey",
+        config.apiKey,
+      );
+    }
+
+    // Validate base URL
+    if (!config.baseURL || typeof config.baseURL !== "string") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_BASE_URL,
+        "baseURL",
+        config.baseURL,
+      );
+    }
+
+    if (config.baseURL.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_BASE_URL,
+        "baseURL",
+        config.baseURL,
+      );
+    }
+
+    // Basic URL format validation
+    try {
+      new URL(config.baseURL);
+    } catch {
+      throw new ConfigurationError(
+        `Base URL must be a valid URL format. Received: ${config.baseURL}`,
+        "baseURL",
+        config.baseURL,
+      );
+    }
+  }
+
+  /**
+   * Validates token limit value
+   * @param tokenLimit - Token limit to validate
+   * @throws ConfigurationError if invalid
+   */
+  static validateTokenLimit(tokenLimit: number): void {
+    if (typeof tokenLimit !== "number") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.INVALID_TOKEN_LIMIT,
+        "tokenLimit",
+        tokenLimit,
+      );
+    }
+
+    if (!Number.isInteger(tokenLimit)) {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.INVALID_TOKEN_LIMIT,
+        "tokenLimit",
+        tokenLimit,
+      );
+    }
+
+    if (tokenLimit <= 0) {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.INVALID_TOKEN_LIMIT,
+        "tokenLimit",
+        tokenLimit,
+      );
+    }
+  }
+
+  /**
+   * Validates model configuration (basic validation)
+   * @param agentModel - Agent model string
+   * @param fastModel - Fast model string
+   * @throws ConfigurationError if invalid
+   */
+  static validateModelConfig(agentModel: string, fastModel: string): void {
+    if (
+      !agentModel ||
+      typeof agentModel !== "string" ||
+      agentModel.trim() === ""
+    ) {
+      throw new ConfigurationError(
+        "Agent model must be a non-empty string.",
+        "agentModel",
+        agentModel,
+      );
+    }
+
+    if (
+      !fastModel ||
+      typeof fastModel !== "string" ||
+      fastModel.trim() === ""
+    ) {
+      throw new ConfigurationError(
+        "Fast model must be a non-empty string.",
+        "fastModel",
+        fastModel,
+      );
+    }
+  }
+}
+
+/**
+ * Static configuration validator instance
+ * Implements ConfigurationValidator interface from types.ts
+ */
+export const configValidator = {
+  validateGatewayConfig: ConfigValidator.validateGatewayConfig,
+  validateTokenLimit: ConfigValidator.validateTokenLimit,
+  validateModelConfig: ConfigValidator.validateModelConfig,
+};

package/src/utils/constants.ts

@@ -31,7 +31,17 @@ export const USER_MEMORY_FILE = path.join(DATA_DIRECTORY, "user-memory.md");
  */
 export const DEFAULT_TOKEN_LIMIT = 64000; // Default token limit
 
+/**
+ * @deprecated These constants are now legacy. Use ModelConfig through Agent constructor instead.
+ * They are maintained for backward compatibility with existing code that might still reference them,
+ * but the actual AI services now use configuration injection.
+ */
 export const FAST_MODEL_ID = process.env.AIGW_FAST_MODEL || "gemini-2.5-flash";
 
+/**
+ * @deprecated These constants are now legacy. Use ModelConfig through Agent constructor instead.
+ * They are maintained for backward compatibility with existing code that might still reference them,
+ * but the actual AI services now use configuration injection.
+ */
 export const AGENT_MODEL_ID =
   process.env.AIGW_MODEL || "claude-sonnet-4-20250514";

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.`;
+}