wave-agent-sdk 0.0.7 → 0.0.10

package/src/tools/multiEditTool.ts

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from "fs/promises";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
-import { diffLines } from "diff";
 
 interface EditOperation {
   old_string: string;
@@ -149,7 +149,7 @@ export const multiEditTool: ToolPlugin = {
         if (edits[0] && edits[0].old_string === "") {
           originalContent = "";
           isNewFile = true;
-          // logger.debug(`Creating new file: ${resolvedPath}`);
+          logger.debug(`Creating new file: ${resolvedPath}`);
         } else {
           return {
             success: false,
@@ -181,7 +181,7 @@ export const multiEditTool: ToolPlugin = {
           return {
             success: false,
             content: "",
-            error: `Edit operation ${i + 1}: old_string not found in current content: "${edit.old_string}"`,
+            error: `Edit operation ${i + 1}: old_string not found in current content`,
           };
         }
 
@@ -216,6 +216,42 @@ export const multiEditTool: ToolPlugin = {
         }
       }
 
+      // Permission check after validation but before real operation
+      if (
+        context.permissionManager &&
+        context.permissionMode &&
+        context.permissionMode !== "bypassPermissions"
+      ) {
+        if (context.permissionManager.isRestrictedTool("MultiEdit")) {
+          try {
+            const permissionContext = context.permissionManager.createContext(
+              "MultiEdit",
+              context.permissionMode,
+              context.canUseToolCallback,
+              { file_path: filePath, edits },
+            );
+            const permissionResult =
+              await context.permissionManager.checkPermission(
+                permissionContext,
+              );
+
+            if (permissionResult.behavior === "deny") {
+              return {
+                success: false,
+                content: "",
+                error: `MultiEdit operation denied by user, reason: ${permissionResult.message || "No reason provided"}`,
+              };
+            }
+          } catch {
+            return {
+              success: false,
+              content: "",
+              error: "Permission check failed",
+            };
+          }
+        }
+      }
+
       // Write file
       try {
         await writeFile(resolvedPath, currentContent, "utf-8");
@@ -227,30 +263,24 @@ export const multiEditTool: ToolPlugin = {
         };
       }
 
-      // Generate diff information
-      const diffResult = diffLines(originalContent, currentContent);
-
       const shortResult = isNewFile
         ? `Created file with ${edits.length} operations`
         : `Applied ${edits.length} edits`;
 
       const detailedContent = `${shortResult}\n\nOperations performed:\n${appliedEdits.map((edit, i) => `${i + 1}. ${edit}`).join("\n")}`;
 
-      // logger.debug(`MultiEdit tool: ${shortResult}`);
+      logger.debug(`MultiEdit tool: ${shortResult}`);
 
       return {
         success: true,
         content: detailedContent,
         shortResult,
         filePath: resolvedPath,
-        originalContent,
-        newContent: currentContent,
-        diffResult,
       };
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
-      // logger.error(`MultiEdit tool error: ${errorMessage}`);
+      logger.error(`MultiEdit tool error: ${errorMessage}`);
       return {
         success: false,
         content: "",

package/src/tools/readTool.ts

@@ -1,10 +1,129 @@
-import { readFile } from "fs/promises";
+import { readFile, stat } from "fs/promises";
+import { extname } from "path";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import {
   isBinaryDocument,
   getBinaryDocumentError,
 } from "../utils/fileFormat.js";
+import { convertImageToBase64 } from "../utils/messageOperations.js";
+
+/**
+ * Supported image file extensions
+ */
+const SUPPORTED_IMAGE_EXTENSIONS = [
+  "png",
+  "jpeg",
+  "jpg",
+  "gif",
+  "webp",
+] as const;
+
+/**
+ * Check if a file path represents an image file
+ * @param filePath - Path to the file
+ * @returns true if the file is a supported image format
+ */
+function isImageFile(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase().substring(1);
+  return (SUPPORTED_IMAGE_EXTENSIONS as readonly string[]).includes(ext);
+}
+
+/**
+ * Validate image file size
+ * @param filePath - Path to the image file
+ * @param maxSizeBytes - Maximum allowed file size in bytes (default: 20MB)
+ * @returns Promise<boolean> - true if file size is within limit
+ */
+async function validateImageFileSize(
+  filePath: string,
+  maxSizeBytes: number = 20 * 1024 * 1024,
+): Promise<boolean> {
+  try {
+    const stats = await stat(filePath);
+    return stats.size <= maxSizeBytes;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get MIME type for image file based on extension
+ * @param filePath - Path to the image file
+ * @returns MIME type string
+ */
+function getImageMimeType(filePath: string): string {
+  const ext = extname(filePath).toLowerCase().substring(1);
+  switch (ext) {
+    case "png":
+      return "image/png";
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "gif":
+      return "image/gif";
+    case "webp":
+      return "image/webp";
+    default:
+      return "image/png"; // Default fallback
+  }
+}
+
+/**
+ * Process an image file and return ToolResult with image data
+ * @param filePath - Path to the image file
+ * @param context - Tool execution context
+ * @returns Promise<ToolResult> with image data
+ */
+async function processImageFile(
+  filePath: string,
+  context: ToolContext,
+): Promise<ToolResult> {
+  try {
+    // Resolve path
+    const actualFilePath = filePath.startsWith("/")
+      ? filePath
+      : resolvePath(filePath, context.workdir);
+
+    // Validate file size
+    const isValidSize = await validateImageFileSize(actualFilePath);
+    if (!isValidSize) {
+      const stats = await stat(actualFilePath);
+      const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+      return {
+        success: false,
+        content: "",
+        error: `Image file exceeds 20MB limit (actual: ${sizeMB}MB)`,
+      };
+    }
+
+    // Convert image to base64
+    const imageDataUrl = convertImageToBase64(actualFilePath);
+    const mimeType = getImageMimeType(actualFilePath);
+
+    // Extract base64 data from data URL (remove data:image/type;base64, prefix)
+    const base64Data = imageDataUrl.split(",")[1] || "";
+
+    return {
+      success: true,
+      content: `Image file processed: ${getDisplayPath(filePath, context.workdir)}\nFormat: ${mimeType}\nSize: Available for AI processing`,
+      shortResult: `Image processed (${mimeType})`,
+      images: [
+        {
+          data: base64Data,
+          mediaType: mimeType,
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      success: false,
+      content: "",
+      error: `Failed to process image: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
 
 /**
  * Read Tool Plugin - Read file content
@@ -16,7 +135,7 @@ export const readTool: ToolPlugin = {
     function: {
       name: "Read",
       description:
-        "Reads a file from the local filesystem. You can access any file directly by using this tool.\nAssume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- The file_path parameter must be an absolute path, not a relative path\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n- Any lines longer than 2000 characters will be truncated\n- Results are returned using cat -n format, with line numbers starting at 1\n- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.\n- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.\n- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.\n- You will regularly be asked to read screenshots. If the user provides a path to a screenshot ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths like /var/folders/123/abc/T/TemporaryItems/NSIRD_screencaptureui_ZfB1tD/Screenshot.png\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n- Binary document formats (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX) are not supported and will return an error.",
+        "Reads a file from the local filesystem. You can access any file directly by using this tool.\nAssume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.\n\nUsage:\n- The file_path parameter must be an absolute path, not a relative path\n- By default, it reads up to 2000 lines starting from the beginning of the file\n- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n- Any lines longer than 2000 characters will be truncated\n- Results are returned using cat -n format, with line numbers starting at 1\n- This tool allows Agent to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Agent is a multimodal LLM.\n- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.\n- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.\n- You will regularly be asked to read screenshots. If the user provides a path to a screenshot ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths like /var/folders/123/abc/T/TemporaryItems/NSIRD_screencaptureui_ZfB1tD/Screenshot.png\n- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n- Binary document formats (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX) are not supported and will return an error.",
       parameters: {
         type: "object",
         properties: {
@@ -64,6 +183,11 @@ export const readTool: ToolPlugin = {
       };
     }
 
+    // Check if this is an image file
+    if (isImageFile(filePath)) {
+      return processImageFile(filePath, context);
+    }
+
     try {
       // Note: New Read tool requires absolute paths, so we don't use resolvePath
       // But for compatibility, if it's not an absolute path, we still try to resolve
@@ -75,7 +199,7 @@ export const readTool: ToolPlugin = {
 
       // Check if file is empty
       if (fileContent.length === 0) {
-        // logger.warn(`File ${filePath} exists but has empty contents`);
+        logger.warn(`File ${filePath} exists but has empty contents`);
         return {
           success: true,
           content:

package/src/tools/skillTool.ts

@@ -23,11 +23,11 @@ export function createSkillTool(skillManager: SkillManager): ToolPlugin {
   };
 
   return {
-    name: "skill",
+    name: "Skill",
     config: {
       type: "function",
       function: {
-        name: "skill",
+        name: "Skill",
         description: getToolDescription(),
         parameters: {
           type: "object",

package/src/tools/todoWriteTool.ts

@@ -1,4 +1,4 @@
-import type { ToolPlugin, ToolResult } from "./types.js";
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 
 interface TodoItem {
   content: string;
@@ -101,6 +101,38 @@ When in doubt, use this tool. Being proactive with task management demonstrates
     },
   },
 
+  formatCompactParams: (
+    params: Record<string, unknown>,
+    context: ToolContext,
+  ) => {
+    void context; // Context not needed for this tool
+    try {
+      const { todos } = params as { todos?: TodoItem[] };
+
+      // Handle invalid or missing tasks array
+      if (!todos || !Array.isArray(todos)) {
+        return "invalid todos";
+      }
+
+      // Handle empty task list
+      if (todos.length === 0) {
+        return "0 tasks";
+      }
+
+      // Count completed tasks
+      const completedCount = todos.filter(
+        (todo) => todo && todo.status === "completed",
+      ).length;
+      const totalCount = todos.length;
+
+      // Format with proper singular/plural
+      const taskWord = totalCount === 1 ? "task" : "tasks";
+      return `${completedCount}/${totalCount} ${taskWord}`;
+    } catch {
+      return "invalid todos";
+    }
+  },
+
   execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
     try {
       // Validate arguments

package/src/tools/types.ts

@@ -3,6 +3,10 @@
  */
 
 import { ChatCompletionFunctionTool } from "openai/resources.js";
+import type {
+  PermissionMode,
+  PermissionCallback,
+} from "../types/permissions.js";
 
 export interface ToolPlugin {
   name: string;
@@ -23,15 +27,7 @@ export interface ToolResult {
   error?: string;
   // Short output, used to display summary information in collapsed state
   shortResult?: string;
-  // Additional properties for file editing tools
-  originalContent?: string;
-  newContent?: string;
-  diffResult?: Array<{
-    count?: number;
-    value: string;
-    added?: boolean;
-    removed?: boolean;
-  }>;
+  // File path for operations that affect files
   filePath?: string;
   // Image data, for supporting multimedia content
   images?: Array<{
@@ -44,4 +40,14 @@ export interface ToolContext {
   abortSignal?: AbortSignal;
   backgroundBashManager?: import("../managers/backgroundBashManager.js").BackgroundBashManager;
   workdir: string;
+  /** Permission mode for this tool execution */
+  permissionMode?: PermissionMode;
+  /** Custom permission callback */
+  canUseToolCallback?: PermissionCallback;
+  /** Permission manager instance for permission checks */
+  permissionManager?: import("../managers/permissionManager.js").PermissionManager;
+  /** MCP manager instance for calling MCP tools */
+  mcpManager?: import("../managers/mcpManager.js").McpManager;
+  /** LSP manager instance for code intelligence */
+  lspManager?: import("../types/lsp.js").ILspManager;
 }

package/src/tools/writeTool.ts

@@ -1,8 +1,8 @@
 import { readFile, writeFile, mkdir } from "fs/promises";
 import { dirname } from "path";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
-import { diffLines } from "diff";
 
 /**
  * File Write Tool Plugin
@@ -14,7 +14,7 @@ export const writeTool: ToolPlugin = {
     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.",
+        "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.",
       parameters: {
         type: "object",
         properties: {
@@ -79,9 +79,6 @@ export const writeTool: ToolPlugin = {
           content: `File ${filePath} already has the same content, no changes needed`,
           shortResult: "No changes needed",
           filePath: resolvedPath,
-          originalContent,
-          newContent: content,
-          diffResult: [],
         };
       }
 
@@ -95,9 +92,45 @@ export const writeTool: ToolPlugin = {
           mkdirError instanceof Error &&
           !mkdirError.message.includes("EEXIST")
         ) {
-          // logger.warn(
-          //   `Failed to create directory ${fileDir}: ${mkdirError.message}`,
-          // );
+          logger.warn(
+            `Failed to create directory ${fileDir}: ${mkdirError.message}`,
+          );
+        }
+      }
+
+      // Permission check after validation but before real operation
+      if (
+        context.permissionManager &&
+        context.permissionMode &&
+        context.permissionMode !== "bypassPermissions"
+      ) {
+        if (context.permissionManager.isRestrictedTool("Write")) {
+          try {
+            const permissionContext = context.permissionManager.createContext(
+              "Write",
+              context.permissionMode,
+              context.canUseToolCallback,
+              { file_path: filePath, content },
+            );
+            const permissionResult =
+              await context.permissionManager.checkPermission(
+                permissionContext,
+              );
+
+            if (permissionResult.behavior === "deny") {
+              return {
+                success: false,
+                content: "",
+                error: `Write operation denied by user, reason: ${permissionResult.message || "No reason provided"}`,
+              };
+            }
+          } catch {
+            return {
+              success: false,
+              content: "",
+              error: "Permission check failed",
+            };
+          }
         }
       }
 
@@ -112,30 +145,24 @@ export const writeTool: ToolPlugin = {
         };
       }
 
-      // Generate diff information
-      const diffResult = diffLines(originalContent, content);
-
       const shortResult = isExistingFile ? "File overwritten" : "File created";
 
       const lines = content.split("\n").length;
       const chars = content.length;
       const detailedContent = `${shortResult} (${lines} lines, ${chars} characters)`;
 
-      // logger.debug(`Write tool: ${shortResult}`);
+      logger.debug(`Write tool: ${shortResult}`);
 
       return {
         success: true,
         content: detailedContent,
         shortResult,
         filePath: resolvedPath,
-        originalContent,
-        newContent: content,
-        diffResult,
       };
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
-      // logger.error(`Write tool error: ${errorMessage}`);
+      logger.error(`Write tool error: ${errorMessage}`);
       return {
         success: false,
         content: "",

package/src/types/commands.ts

@@ -11,7 +11,6 @@ export interface SlashCommand {
 }
 
 export interface CustomSlashCommandConfig {
-  allowedTools?: string[];
   model?: string;
   description?: string;
 }
@@ -23,4 +22,10 @@ export interface CustomSlashCommand {
   filePath: string;
   content: string;
   config?: CustomSlashCommandConfig;
+
+  // Nested command support
+  namespace?: string; // Parent directory for nested commands (e.g., "openspec")
+  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"])
 }

package/src/types/config.ts

@@ -3,9 +3,14 @@
  * Dependencies: None
  */
 
+import OpenAI from "openai";
+
 export interface GatewayConfig {
   apiKey: string;
   baseURL: string;
+  defaultHeaders?: Record<string, string>;
+  fetchOptions?: OpenAI["fetchOptions"];
+  fetch?: OpenAI["fetch"];
 }
 
 export interface ModelConfig {

package/src/types/configuration.ts

@@ -0,0 +1,73 @@
+/**
+ * Configuration Management Types
+ *
+ * Types for centralized configuration loading and validation services.
+ * These support the refactored configuration architecture that separates
+ * configuration management from hook execution.
+ */
+
+import type { WaveConfiguration } from "./hooks.js";
+
+/**
+ * Result of configuration loading operations with detailed status information
+ */
+export interface ConfigurationLoadResult {
+  /** The loaded configuration, or null if loading failed */
+  configuration: WaveConfiguration | null;
+  /** Whether the loading operation was successful */
+  success: boolean;
+  /** Error message if loading failed */
+  error?: string;
+  /** Path of the successfully loaded file */
+  sourcePath?: string;
+  /** Non-critical warnings during loading */
+  warnings: string[];
+}
+
+/**
+ * Result of configuration validation operations
+ */
+export interface ValidationResult {
+  /** Whether the configuration is valid */
+  isValid: boolean;
+  /** Critical errors that prevent configuration use */
+  errors: string[];
+  /** Non-critical warnings about the configuration */
+  warnings: string[];
+}
+
+/**
+ * Configuration file paths organized by category
+ */
+export interface ConfigurationPaths {
+  /** User-specific configuration file paths in priority order */
+  userPaths: string[];
+  /** Project-specific configuration file paths in priority order */
+  projectPaths: string[];
+  /** All configuration paths combined */
+  allPaths: string[];
+  /** Only the paths that actually exist on the filesystem */
+  existingPaths: string[];
+}
+
+/**
+ * Options for configuring the ConfigurationService
+ */
+export interface ConfigurationServiceOptions {
+  /** Working directory for resolving project configurations */
+  workdir: string;
+  /** Optional logger for configuration operations */
+  logger?: Logger;
+  /** Whether to enable validation during loading (default: true) */
+  enableValidation?: boolean;
+}
+
+/**
+ * Minimal logger interface for configuration services
+ */
+interface Logger {
+  error: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+}

package/src/types/core.ts

@@ -3,6 +3,8 @@
  * Dependencies: None (foundation layer)
  */
 
+import type { CompletionUsage } from "openai/resources";
+
 /**
  * Logger interface definition
  * Compatible with OpenAI package Logger interface
@@ -24,6 +26,59 @@ export interface Usage {
   total_tokens: number; // Sum of prompt + completion tokens
   model?: string; // Model used for the operation (e.g., "gpt-4", "gpt-3.5-turbo")
   operation_type?: "agent" | "compress"; // Type of operation that generated usage
+
+  // Cache-related tokens (Claude models only)
+  cache_read_input_tokens?: number; // Tokens read from cache
+  cache_creation_input_tokens?: number; // Tokens used to create cache entries
+  cache_creation?: {
+    ephemeral_5m_input_tokens: number; // Tokens cached for 5 minutes
+    ephemeral_1h_input_tokens: number; // Tokens cached for 1 hour
+  };
+}
+
+/**
+ * Enhanced usage metrics including Claude cache information
+ * Backward compatible with standard OpenAI CompletionUsage
+ */
+export interface ClaudeUsage extends CompletionUsage {
+  // Standard OpenAI usage fields (inherited)
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+
+  // Claude-specific cache extensions
+  /**
+   * Number of tokens read from existing cache
+   * Indicates cost savings from cache hits
+   */
+  cache_read_input_tokens?: number;
+
+  /**
+   * Number of tokens used to create new cache entries
+   * Investment in future cache hits
+   */
+  cache_creation_input_tokens?: number;
+
+  /**
+   * Detailed breakdown of cache creation by duration
+   */
+  cache_creation?: {
+    /** Tokens cached for 5 minute duration */
+    ephemeral_5m_input_tokens: number;
+    /** Tokens cached for 1 hour duration */
+    ephemeral_1h_input_tokens: number;
+  };
+}
+
+/**
+ * Represents a diff change for tool parameter-based diff display
+ * Contains the old content and new content for comparison
+ */
+export interface Change {
+  /** The original content (empty string for additions) */
+  oldContent: string;
+  /** The new content (empty string for deletions) */
+  newContent: string;
 }
 
 export class ConfigurationError extends Error {