wave-agent-sdk 0.0.6 → 0.0.8

package/src/utils/convertMessagesForAPI.ts

@@ -6,6 +6,7 @@ import {
   ChatCompletionContentPart,
   ChatCompletionMessageParam,
 } from "openai/resources.js";
+import { logger } from "./globalLogger.js";
 
 /**
  * Safely handle tool call parameters, ensuring a legal JSON string is returned
@@ -21,8 +22,8 @@ function safeToolArguments(args: string): string {
     // Try to parse as JSON to validate format
     JSON.parse(args);
     return args;
-  } catch {
-    // logger.error(`Invalid tool arguments: ${args}`);
+  } catch (error) {
+    logger.error(`Invalid tool arguments: ${args}`, error);
     // If not valid JSON, return a fallback empty object
     return "{}";
   }
@@ -75,8 +76,8 @@ export function convertMessagesForAPI(
 
       if (toolBlocks.length > 0) {
         toolBlocks.forEach((toolBlock) => {
-          // Only add completed tool blocks (i.e., not running)
-          if (toolBlock.id && !toolBlock.isRunning) {
+          // Only add completed tool blocks (i.e., stage is 'end')
+          if (toolBlock.id && toolBlock.stage === "end") {
             completedToolIds.add(toolBlock.id);
 
             // Check for image data
@@ -163,6 +164,7 @@ export function convertMessagesForAPI(
           role: "assistant",
           content,
           tool_calls,
+          ...(message.metadata ? { ...message.metadata } : {}),
         };
 
         recentMessages.unshift(assistantMessage);
@@ -176,15 +178,7 @@ export function convertMessagesForAPI(
         if (block.type === "text" && block.content) {
           contentParts.push({
             type: "text",
-            text: block.content,
-          });
-        }
-
-        // Handle custom command blocks - pass full content as text to AI
-        if (block.type === "custom_command" && block.content) {
-          contentParts.push({
-            type: "text",
-            text: block.content,
+            text: block.customCommandContent || block.content,
           });
         }
 
@@ -202,7 +196,7 @@ export function convertMessagesForAPI(
               try {
                 finalImageUrl = convertImageToBase64(imageUrl);
               } catch (error) {
-                console.error(
+                logger.error(
                   "Failed to convert image path to base64:",
                   imageUrl,
                   error,

package/src/utils/customCommands.ts

@@ -1,8 +1,15 @@
-import { existsSync, readdirSync } from "fs";
+import { existsSync, readdirSync, statSync } from "fs";
 import { join, extname, basename } from "path";
 import { homedir } from "os";
 import type { CustomSlashCommand } from "../types/index.js";
 import { parseMarkdownFile } from "./markdownParser.js";
+import {
+  generateCommandId,
+  getCommandSegments,
+  getNamespace,
+  getDepth,
+} from "./commandPathResolver.js";
+import { logger } from "./globalLogger.js";
 
 /**
  * Get the project-specific commands directory
@@ -19,43 +26,104 @@ export function getUserCommandsDir(): string {
 }
 
 /**
- * Scan a directory for markdown command files
+ * Scan a directory for markdown command files with nested directory support
+ * @param dirPath - Root commands directory path
+ * @param maxDepth - Maximum nesting depth to scan (default: 1)
  */
-function scanCommandsDirectory(dirPath: string): CustomSlashCommand[] {
+function scanCommandsDirectory(
+  dirPath: string,
+  maxDepth: number = 1,
+): CustomSlashCommand[] {
   if (!existsSync(dirPath)) {
     return [];
   }
 
+  return scanCommandsDirectoryRecursive(dirPath, dirPath, 0, maxDepth);
+}
+
+/**
+ * Recursively scan directory for commands with depth control
+ * @param currentPath - Current directory being scanned
+ * @param rootPath - Root commands directory (for relative path calculation)
+ * @param currentDepth - Current nesting depth
+ * @param maxDepth - Maximum allowed depth
+ */
+function scanCommandsDirectoryRecursive(
+  currentPath: string,
+  rootPath: string,
+  currentDepth: number,
+  maxDepth: number,
+): CustomSlashCommand[] {
   const commands: CustomSlashCommand[] = [];
 
   try {
-    const files = readdirSync(dirPath);
+    const entries = readdirSync(currentPath);
 
-    for (const file of files) {
-      if (extname(file) !== ".md") {
-        continue;
-      }
+    for (const entryName of entries) {
+      const fullPath = join(currentPath, entryName);
 
-      const filePath = join(dirPath, file);
-      const commandName = basename(file, ".md");
+      let isDirectory = false;
+      let isFile = false;
 
       try {
-        const { content, config } = parseMarkdownFile(filePath);
-
-        commands.push({
-          id: commandName,
-          name: commandName,
-          description: config?.description, // Use description from frontmatter
-          filePath,
-          content,
-          config,
-        });
+        const stats = statSync(fullPath);
+        isDirectory = stats.isDirectory();
+        isFile = stats.isFile();
       } catch (error) {
-        console.warn(`Failed to load custom command from ${filePath}:`, error);
+        // Skip entries that cannot be stat'd
+        logger.warn(`Cannot access ${fullPath}:`, error);
+        continue;
+      }
+
+      if (isDirectory) {
+        // Skip subdirectories if we're at max depth
+        if (currentDepth >= maxDepth) {
+          logger.warn(
+            `Skipping directory ${fullPath}: exceeds maximum nesting depth of ${maxDepth}`,
+          );
+          continue;
+        }
+
+        // Recursively scan subdirectory
+        const nestedCommands = scanCommandsDirectoryRecursive(
+          fullPath,
+          rootPath,
+          currentDepth + 1,
+          maxDepth,
+        );
+        commands.push(...nestedCommands);
+      } else if (isFile && extname(entryName) === ".md") {
+        // Process markdown file
+        try {
+          const commandId = generateCommandId(fullPath, rootPath);
+          const segments = getCommandSegments(fullPath, rootPath);
+          const namespace = getNamespace(segments);
+          const depth = getDepth(segments);
+
+          const { content, config } = parseMarkdownFile(fullPath);
+
+          commands.push({
+            id: commandId,
+            name: basename(entryName, ".md"),
+            description: config?.description,
+            filePath: fullPath,
+            content,
+            config,
+
+            // Nested command metadata
+            namespace,
+            isNested: depth > 0,
+            depth,
+            segments,
+          });
+        } catch (error) {
+          logger.warn(`Failed to load custom command from ${fullPath}:`, error);
+        }
       }
+      // Skip non-markdown files silently
     }
   } catch (error) {
-    console.warn(`Failed to scan commands directory ${dirPath}:`, error);
+    logger.warn(`Failed to scan commands directory ${currentPath}:`, error);
   }
 
   return commands;

package/src/utils/fileUtils.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+
+/**
+ * Reads the first line of a file efficiently using Node.js readline.
+ *
+ * @param {string} filePath - The path to the file.
+ * @return {Promise<string>} - The first non-empty line of the file, or an empty string otherwise.
+ */
+export async function readFirstLine(filePath: string): Promise<string> {
+  const { createReadStream } = fs;
+  const { createInterface } = await import("node:readline");
+
+  const fileStream = createReadStream(filePath);
+  const rl = createInterface({
+    input: fileStream,
+    crlfDelay: Infinity, // Handle \r\n properly
+  });
+
+  try {
+    for await (const line of rl) {
+      const trimmedLine = line.trim();
+      if (trimmedLine.length > 0) {
+        return trimmedLine;
+      }
+    }
+    return "";
+  } catch {
+    // If reading fails (e.g., file doesn't exist), return empty string
+    return "";
+  } finally {
+    rl.close();
+    fileStream.destroy();
+  }
+}
+
+/**
+ * Reads a file from the end and returns the first non-empty line.
+ *
+ * @param {string} filePath - The path to the file.
+ * @return {Promise<string>} - The last non-empty line of the file, or an empty string if no non-empty lines found.
+ */
+export async function getLastLine(filePath: string): Promise<string> {
+  const { exec } = await import("child_process");
+  const { promisify } = await import("util");
+  const execAsync = promisify(exec);
+
+  try {
+    // Use tail with multiple lines to handle cases where the last line might be empty
+    const { stdout } = await execAsync(`tail -n 3 "${filePath}"`);
+    const lines = stdout.split(/\r?\n/);
+
+    // Find the first non-empty line working backwards
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (line.length > 0) {
+        return line;
+      }
+    }
+
+    return "";
+  } catch {
+    // If tail fails (e.g., file doesn't exist), return empty string
+    return "";
+  }
+}

package/src/utils/globalLogger.ts

@@ -0,0 +1,145 @@
+/**
+ * Global Logger Registry for Agent SDK
+ *
+ * Provides zero-overhead logging access for utility functions and services
+ * without requiring parameter passing. Maintains singleton logger instance
+ * accessible across all SDK modules.
+ *
+ * Features:
+ * - Zero overhead when no logger configured (single null check)
+ * - Thread-safe in Node.js single-threaded environment
+ * - Maintains backward compatibility with existing Logger interface
+ * - Direct function delegation when configured
+ */
+
+import type { Logger } from "../types/core.js";
+
+/**
+ * Module-level storage for the global logger instance
+ * null = unconfigured (logging calls are no-ops)
+ * Logger = configured (calls are forwarded)
+ */
+let globalLogger: Logger | null = null;
+
+// =============================================================================
+// Registry Management API
+// =============================================================================
+
+/**
+ * Configure the global logger instance used by utility functions and services
+ *
+ * @param logger - Logger instance implementing the Logger interface, or null to disable logging
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * import { setGlobalLogger } from './utils/globalLogger.js';
+ *
+ * // Configure logger
+ * setGlobalLogger(myLogger);
+ *
+ * // Disable logging
+ * setGlobalLogger(null);
+ * ```
+ */
+export function setGlobalLogger(logger: Logger | null): void {
+  globalLogger = logger;
+}
+
+/**
+ * Retrieve the current global logger instance
+ *
+ * @returns Current logger instance or null if unconfigured
+ *
+ * @example
+ * ```typescript
+ * const currentLogger = getGlobalLogger();
+ * if (currentLogger) {
+ *   currentLogger.info('Direct logger access');
+ * }
+ * ```
+ */
+export function getGlobalLogger(): Logger | null {
+  return globalLogger;
+}
+
+/**
+ * Reset global logger to unconfigured state
+ * Equivalent to setGlobalLogger(null)
+ *
+ * @example
+ * ```typescript
+ * clearGlobalLogger(); // All subsequent logging calls become no-ops
+ * ```
+ */
+export function clearGlobalLogger(): void {
+  globalLogger = null;
+}
+
+/**
+ * Check if global logger is currently configured
+ *
+ * @returns true if logger configured, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isLoggerConfigured()) {
+ *   // Perform expensive logging operation
+ *   const debugInfo = generateDebugInfo();
+ *   logger.debug(debugInfo);
+ * }
+ * ```
+ */
+export function isLoggerConfigured(): boolean {
+  return globalLogger !== null;
+}
+
+// =============================================================================
+// Zero-Overhead Logging API
+// =============================================================================
+
+/**
+ * Zero-overhead logging interface
+ *
+ * Performance characteristics:
+ * - Unconfigured: Single null check + early return (near-zero cost)
+ * - Configured: Null check + function delegation
+ * - No object creation or intermediate allocations
+ */
+export const logger = {
+  /**
+   * Log debug-level message through global logger
+   * No-op when global logger is null (zero overhead)
+   */
+  debug: (...args: unknown[]): void => {
+    if (globalLogger === null) return;
+    globalLogger.debug(...args);
+  },
+
+  /**
+   * Log info-level message through global logger
+   * No-op when global logger is null (zero overhead)
+   */
+  info: (...args: unknown[]): void => {
+    if (globalLogger === null) return;
+    globalLogger.info(...args);
+  },
+
+  /**
+   * Log warning-level message through global logger
+   * No-op when global logger is null (zero overhead)
+   */
+  warn: (...args: unknown[]): void => {
+    if (globalLogger === null) return;
+    globalLogger.warn(...args);
+  },
+
+  /**
+   * Log error-level message through global logger
+   * No-op when global logger is null (zero overhead)
+   */
+  error: (...args: unknown[]): void => {
+    if (globalLogger === null) return;
+    globalLogger.error(...args);
+  },
+} as const;

package/src/utils/hookMatcher.ts

@@ -7,18 +7,7 @@
 
 import { minimatch } from "minimatch";
 
-export interface IHookMatcher {
-  // Test if pattern matches tool name
-  matches(pattern: string, toolName: string): boolean;
-
-  // Validate pattern syntax
-  isValidPattern(pattern: string): boolean;
-
-  // Get pattern type for optimization
-  getPatternType(pattern: string): "exact" | "glob" | "regex" | "alternatives";
-}
-
-export class HookMatcher implements IHookMatcher {
+export class HookMatcher {
   /**
    * Test if pattern matches tool name
    * Supports multiple matching strategies:

package/src/utils/mcpUtils.ts

@@ -2,6 +2,36 @@ import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "../tools/types.js";
 import type { McpTool, McpServerStatus } from "../types/index.js";
 
+/**
+ * Recursively clean schema to remove unsupported fields
+ */
+function cleanSchema(schema: unknown): unknown {
+  if (typeof schema !== "object" || schema === null) {
+    return schema;
+  }
+
+  if (Array.isArray(schema)) {
+    return schema.map(cleanSchema);
+  }
+
+  const newSchema: Record<string, unknown> = {};
+  const obj = schema as Record<string, unknown>;
+
+  for (const key in obj) {
+    // Remove $schema as OpenAI API doesn't accept it
+    // Remove exclusiveMinimum/exclusiveMaximum as some models (e.g. Gemini) don't support them
+    if (
+      key === "$schema" ||
+      key === "exclusiveMinimum" ||
+      key === "exclusiveMaximum"
+    ) {
+      continue;
+    }
+    newSchema[key] = cleanSchema(obj[key]);
+  }
+  return newSchema;
+}
+
 /**
  * Convert MCP tool to OpenAI function tool format
  */
@@ -9,9 +39,10 @@ export function mcpToolToOpenAITool(
   mcpTool: McpTool,
   serverName: string,
 ): ChatCompletionFunctionTool {
-  // Remove $schema field if it exists, as OpenAI API doesn't accept it
-  const cleanInputSchema = { ...mcpTool.inputSchema };
-  delete cleanInputSchema.$schema;
+  const cleanInputSchema = cleanSchema(mcpTool.inputSchema) as Record<
+    string,
+    unknown
+  >;
 
   return {
     type: "function",