wave-agent-sdk 0.0.7 → 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);
@@ -194,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/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",

package/src/utils/messageOperations.ts

@@ -1,7 +1,10 @@
-import type { Message, Usage, MessageSource } from "../types/index.js";
+import type { Message, Usage } from "../types/index.js";
+import { MessageSource } from "../types/index.js";
+import type { SubagentConfiguration } from "./subagentParser.js";
 import { readFileSync } from "fs";
 import { extname } from "path";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
+import { logger } from "./globalLogger.js";
 
 // Base user message parameters interface
 export interface UserMessageParams {
@@ -23,11 +26,19 @@ export interface UpdateToolBlockParams {
   result?: string;
   success?: boolean;
   error?: string;
-  isRunning?: boolean;
+  /**
+   * Tool execution stage:
+   * - 'start': Tool call initiated during AI streaming
+   * - 'streaming': Tool parameters being received incrementally
+   * - 'running': Tool execution in progress
+   * - 'end': Tool execution completed with final result
+   */
+  stage: "start" | "streaming" | "running" | "end";
   name?: string;
   shortResult?: string;
   images?: Array<{ data: string; mediaType?: string }>;
   compactParams?: string;
+  parametersChunk?: string; // Incremental parameter updates for streaming
 }
 
 // Agent specific interfaces (without messages parameter)
@@ -74,17 +85,18 @@ export interface CompleteCommandParams {
 
 /**
  * Extract text content from user messages in the messages array
+ * Excludes messages with source HOOK to prevent hook-generated content from entering user history
  */
 export const extractUserInputHistory = (messages: Message[]): string[] => {
   return messages
     .filter((message) => message.role === "user")
     .map((message) => {
-      // Extract all text block content and merge
+      // Extract text block content, excluding HOOK-sourced blocks
       const textBlocks = message.blocks.filter(
-        (block) => block.type === "text",
+        (block) => block.type === "text" && block.source !== MessageSource.HOOK,
       );
       return textBlocks
-        .map((block) => block.content)
+        .map((block) => (block as { content: string }).content)
         .join(" ")
         .trim();
     })
@@ -126,8 +138,8 @@ export const convertImageToBase64 = (imagePath: string): string => {
 
     const base64String = imageBuffer.toString("base64");
     return `data:${mimeType};base64,${base64String}`;
-  } catch {
-    // logger.error(`Failed to convert image to base64: ${imagePath}`, error);
+  } catch (error) {
+    logger.error(`Failed to convert image to base64: ${imagePath}`, error);
     // Return an error placeholder or throw error
     return `data:image/png;base64,`; // Empty base64, avoid program crash
   }
@@ -174,6 +186,7 @@ export const addAssistantMessageToMessages = (
   content?: string,
   toolCalls?: ChatCompletionMessageFunctionToolCall[],
   usage?: Usage,
+  metadata?: Record<string, unknown>,
 ): Message[] => {
   const blocks: Message["blocks"] = [];
 
@@ -191,7 +204,7 @@ export const addAssistantMessageToMessages = (
         result: "",
         id: toolCall.id || "",
         name: toolCall.function?.name || "",
-        isRunning: false,
+        stage: "start",
       });
     });
   }
@@ -200,6 +213,7 @@ export const addAssistantMessageToMessages = (
     role: "assistant",
     blocks,
     usage, // Include usage data if provided
+    ...(metadata ? { metadata: { ...metadata } } : {}),
   };
 
   return [...messages, initialAssistantMessage];
@@ -235,11 +249,12 @@ export const updateToolBlockInMessage = ({
   result,
   success,
   error,
-  isRunning,
+  stage,
   name,
   shortResult,
   images,
   compactParams,
+  parametersChunk,
 }: UpdateToolBlockParams): Message[] => {
   const newMessages = [...messages];
   // Find the last assistant message
@@ -258,24 +273,28 @@ export const updateToolBlockInMessage = ({
           toolBlock.images = images; // Add image data update
           if (success !== undefined) toolBlock.success = success;
           if (error !== undefined) toolBlock.error = error;
-          if (isRunning !== undefined) toolBlock.isRunning = isRunning;
+          if (stage !== undefined) toolBlock.stage = stage;
           if (compactParams !== undefined)
             toolBlock.compactParams = compactParams;
+          if (parametersChunk !== undefined)
+            toolBlock.parametersChunk = parametersChunk;
         }
-      } else if (result !== undefined) {
+      } else {
         // If existing block not found, create new one
+        // This handles cases where we're streaming tool parameters before execution
         newMessages[i].blocks.push({
           type: "tool",
           parameters: parameters,
-          result: result,
+          result: result || "",
           shortResult: shortResult,
           images: images, // Add image data
           id: id,
           name: name || "unknown",
           success: success,
           error: error,
-          isRunning: isRunning ?? false,
+          stage: stage ?? "start",
           compactParams: compactParams,
+          parametersChunk: parametersChunk,
         });
       }
       break;
@@ -508,14 +527,15 @@ export interface AddSubagentBlockParams {
   subagentId: string;
   subagentName: string;
   status: "active" | "completed" | "error" | "aborted";
-  subagentMessages?: Message[];
+  sessionId: string;
+  configuration: SubagentConfiguration;
 }
 
 export interface UpdateSubagentBlockParams {
   messages: Message[];
   subagentId: string;
   status: "active" | "completed" | "error" | "aborted";
-  subagentMessages: Message[];
+  sessionId?: string;
 }
 
 export const addSubagentBlockToMessage = ({
@@ -523,7 +543,8 @@ export const addSubagentBlockToMessage = ({
   subagentId,
   subagentName,
   status,
-  subagentMessages = [],
+  sessionId,
+  configuration,
 }: AddSubagentBlockParams): Message[] => {
   const newMessages = [...messages];
 
@@ -545,7 +566,8 @@ export const addSubagentBlockToMessage = ({
     subagentId,
     subagentName,
     status,
-    messages: subagentMessages,
+    sessionId,
+    configuration,
   });
 
   return newMessages;
@@ -556,7 +578,7 @@ export const updateSubagentBlockInMessage = (
   subagentId: string,
   updates: Partial<{
     status: "active" | "completed" | "error" | "aborted";
-    messages: Message[];
+    sessionId: string;
   }>,
 ): Message[] => {
   const newMessages = [...messages];
@@ -570,8 +592,8 @@ export const updateSubagentBlockInMessage = (
           if (updates.status !== undefined) {
             block.status = updates.status;
           }
-          if (updates.messages !== undefined) {
-            block.messages = updates.messages;
+          if (updates.sessionId !== undefined) {
+            block.sessionId = updates.sessionId;
           }
           return newMessages;
         }