wave-agent-sdk 0.0.7 → 0.0.10

package/src/utils/fileUtils.ts

@@ -0,0 +1,160 @@
+import fs from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+
+/**
+ * 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 { 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 last non-empty line.
+ *
+ * This version supports files that end with:
+ *   - "\n" (Unix-style, including modern macOS)
+ *   - "\r\n" (Windows-style)
+ *   - "\r" (older Mac-style, HL7, etc.)
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {number} [minLength=1] - Minimum length for the returned line.
+ * @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,
+  minLength = 1,
+): Promise<string> {
+  let fileHandle;
+  try {
+    const stats = await fs.stat(filePath);
+    const fileSize = stats.size;
+
+    if (fileSize === 0) return "";
+
+    fileHandle = await fs.open(filePath, "r");
+    const bufferSize = 8 * 1024; // 8KB buffer is usually enough for the last line
+    const buffer = Buffer.alloc(bufferSize);
+
+    let lineEnd: number | null = null;
+    let lineStart: number | null = null;
+    let currentPosition = fileSize;
+
+    while (currentPosition > 0 && lineStart === null) {
+      const readSize = Math.min(bufferSize, currentPosition);
+      currentPosition -= readSize;
+
+      const { bytesRead } = await fileHandle.read(
+        buffer,
+        0,
+        readSize,
+        currentPosition,
+      );
+
+      for (let i = bytesRead - 1; i >= 0; i--) {
+        const charCode = buffer[i];
+        if (lineEnd === null) {
+          // Still looking for the end of the last non-empty line (skip trailing newlines and whitespace)
+          if (charCode > 32) {
+            lineEnd = currentPosition + i + 1;
+          }
+        } else {
+          // Looking for the start of the line (the newline before it)
+          if (charCode === 10 || charCode === 13) {
+            lineStart = currentPosition + i + 1;
+            break;
+          }
+        }
+      }
+    }
+
+    if (lineEnd === null) return "";
+    if (lineStart === null) lineStart = 0;
+
+    const length = lineEnd - lineStart;
+    if (length < minLength) return "";
+
+    const resultBuffer = Buffer.alloc(length);
+    await fileHandle.read(resultBuffer, 0, length, lineStart);
+    const result = resultBuffer.toString("utf8").trim();
+    return result.length >= minLength ? result : "";
+  } catch {
+    // If reading fails (e.g., file doesn't exist), return empty string
+    return "";
+  } finally {
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}
+
+/**
+ * Ensures that a pattern is present in the global git ignore file.
+ *
+ * @param {string} pattern - The pattern to add to global git ignore.
+ */
+export async function ensureGlobalGitIgnore(pattern: string): Promise<void> {
+  try {
+    let globalIgnorePath: string;
+    try {
+      globalIgnorePath = execSync("git config --get core.excludesfile", {
+        encoding: "utf8",
+      }).trim();
+    } catch {
+      // If not set, use default paths
+      const xdgConfigHome =
+        process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+      globalIgnorePath = path.join(xdgConfigHome, "git", "ignore");
+    }
+
+    if (!globalIgnorePath) return;
+
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(globalIgnorePath), { recursive: true });
+
+    let content = "";
+    try {
+      content = await fs.readFile(globalIgnorePath, "utf8");
+    } catch {
+      // File doesn't exist
+    }
+
+    const lines = content.split("\n").map((line) => line.trim());
+    if (!lines.includes(pattern)) {
+      const newContent =
+        content.endsWith("\n") || content === ""
+          ? `${content}${pattern}\n`
+          : `${content}\n${pattern}\n`;
+      await fs.writeFile(globalIgnorePath, newContent, "utf8");
+    }
+  } catch {
+    // Ignore errors
+  }
+}

package/src/utils/globalLogger.ts

@@ -0,0 +1,128 @@
+/**
+ * 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;
+}
+
+/**
+ * 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/largeOutputHandler.ts

@@ -0,0 +1,55 @@
+import { writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import { logger } from "./globalLogger.js";
+import {
+  estimateTokenCount,
+  getTokenUsageDescription,
+} from "./tokenEstimator.js";
+
+// Token threshold for writing output to temp file (20k tokens)
+export const LARGE_OUTPUT_TOKEN_THRESHOLD = 20000;
+
+/**
+ * Handle large command output by writing to temporary file when token threshold is exceeded
+ *
+ * Uses token-based threshold (20k tokens) to determine when output should be written to temp file.
+ * This provides accurate estimation of actual token cost for LLM processing.
+ *
+ * @param output - The command output string
+ * @returns Object containing processed content and optional file path
+ */
+export async function handleLargeOutput(output: string): Promise<{
+  content: string;
+  filePath?: string;
+}> {
+  const estimatedTokens = estimateTokenCount(output);
+
+  // Check token threshold
+  if (estimatedTokens <= LARGE_OUTPUT_TOKEN_THRESHOLD) {
+    return { content: output };
+  }
+
+  try {
+    // Create temp file for large output
+    const tempFileName = `bash-output-${Date.now()}-${Math.random().toString(36).substr(2, 9)}.txt`;
+    const tempFilePath = join(tmpdir(), tempFileName);
+
+    await writeFile(tempFilePath, output, "utf8");
+
+    const sizeKB = Math.round(output.length / 1024);
+    const tokenDescription = getTokenUsageDescription(
+      output,
+      LARGE_OUTPUT_TOKEN_THRESHOLD,
+    );
+
+    return {
+      content: `Large output (${sizeKB} KB, ${tokenDescription}) written to temporary file. Use the Read tool to access the full content.`,
+      filePath: tempFilePath,
+    };
+  } catch (error) {
+    logger.warn(`Failed to write large output to temp file: ${error}`);
+    // Fallback to direct output if temp file creation fails
+    return { content: output };
+  }
+}

package/src/utils/markdownParser.ts

@@ -37,18 +37,7 @@ function parseFrontmatter(content: string): {
       const key = trimmedLine.slice(0, colonIndex).trim();
       const value = trimmedLine.slice(colonIndex + 1).trim();
 
-      // Handle array values for allowed-tools
-      if (key === "allowed-tools" && value) {
-        // Simple array parsing: "tool1, tool2, tool3" or "[tool1, tool2]"
-        let arrayValue = value;
-        if (arrayValue.startsWith("[") && arrayValue.endsWith("]")) {
-          arrayValue = arrayValue.slice(1, -1);
-        }
-        frontmatter[key] = arrayValue
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean);
-      } else if (value) {
+      if (value) {
         frontmatter[key] = value;
       }
     }
@@ -73,13 +62,6 @@ export function parseMarkdownFile(filePath: string): ParsedMarkdownFile {
     if (frontmatter) {
       config = {};
 
-      if (
-        frontmatter["allowed-tools"] &&
-        Array.isArray(frontmatter["allowed-tools"])
-      ) {
-        config.allowedTools = frontmatter["allowed-tools"] as string[];
-      }
-
       if (frontmatter.model && typeof frontmatter.model === "string") {
         config.model = frontmatter.model;
       }

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)
@@ -36,12 +47,6 @@ export type AgentToolBlockUpdateParams = Omit<
   "messages"
 >;
 
-export interface AddDiffBlockParams {
-  messages: Message[];
-  path: string;
-  diffResult: Array<{ value: string; added?: boolean; removed?: boolean }>;
-}
-
 export interface AddErrorBlockParams {
   messages: Message[];
   error: string;
@@ -74,17 +79,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 +132,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 +180,7 @@ export const addAssistantMessageToMessages = (
   content?: string,
   toolCalls?: ChatCompletionMessageFunctionToolCall[],
   usage?: Usage,
+  additionalFields?: Record<string, unknown>,
 ): Message[] => {
   const blocks: Message["blocks"] = [];
 
@@ -191,7 +198,7 @@ export const addAssistantMessageToMessages = (
         result: "",
         id: toolCall.id || "",
         name: toolCall.function?.name || "",
-        isRunning: false,
+        stage: "start",
       });
     });
   }
@@ -200,33 +207,12 @@ export const addAssistantMessageToMessages = (
     role: "assistant",
     blocks,
     usage, // Include usage data if provided
+    ...(additionalFields ? { additionalFields: { ...additionalFields } } : {}),
   };
 
   return [...messages, initialAssistantMessage];
 };
 
-// Update File Operation Block of the last assistant message
-export const addDiffBlockToMessage = ({
-  messages,
-  path,
-  diffResult,
-}: AddDiffBlockParams): Message[] => {
-  const newMessages = [...messages];
-  // Find the last assistant message
-  for (let i = newMessages.length - 1; i >= 0; i--) {
-    if (newMessages[i].role === "assistant") {
-      // Directly add diff block instead of replacing existing blocks
-      newMessages[i].blocks.push({
-        type: "diff",
-        path: path,
-        diffResult: diffResult,
-      });
-      break;
-    }
-  }
-  return newMessages;
-};
-
 // Update Tool Block of the last assistant message
 export const updateToolBlockInMessage = ({
   messages,
@@ -235,11 +221,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 +245,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;
@@ -434,7 +425,7 @@ export const addCommandOutputMessage = ({
   command,
 }: AddCommandOutputParams): Message[] => {
   const outputMessage: Message = {
-    role: "assistant",
+    role: "user",
     blocks: [
       {
         type: "command_output",
@@ -456,10 +447,10 @@ export const updateCommandOutputInMessage = ({
   output,
 }: UpdateCommandOutputParams): Message[] => {
   const newMessages = [...messages];
-  // Find the last assistant message with a command_output block for this command
+  // Find the last user message with a command_output block for this command
   for (let i = newMessages.length - 1; i >= 0; i--) {
     const msg = newMessages[i];
-    if (msg.role === "assistant") {
+    if (msg.role === "user") {
       const commandBlock = msg.blocks.find(
         (block) =>
           block.type === "command_output" &&
@@ -482,10 +473,10 @@ export const completeCommandInMessage = ({
   exitCode,
 }: CompleteCommandParams): Message[] => {
   const newMessages = [...messages];
-  // Find the last assistant message with a command_output block for this command
+  // Find the last user message with a command_output block for this command
   for (let i = newMessages.length - 1; i >= 0; i--) {
     const msg = newMessages[i];
-    if (msg.role === "assistant") {
+    if (msg.role === "user") {
       const commandBlock = msg.blocks.find(
         (block) =>
           block.type === "command_output" &&
@@ -508,14 +499,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 +515,8 @@ export const addSubagentBlockToMessage = ({
   subagentId,
   subagentName,
   status,
-  subagentMessages = [],
+  sessionId,
+  configuration,
 }: AddSubagentBlockParams): Message[] => {
   const newMessages = [...messages];
 
@@ -545,7 +538,8 @@ export const addSubagentBlockToMessage = ({
     subagentId,
     subagentName,
     status,
-    messages: subagentMessages,
+    sessionId,
+    configuration,
   });
 
   return newMessages;
@@ -556,7 +550,7 @@ export const updateSubagentBlockInMessage = (
   subagentId: string,
   updates: Partial<{
     status: "active" | "completed" | "error" | "aborted";
-    messages: Message[];
+    sessionId: string;
   }>,
 ): Message[] => {
   const newMessages = [...messages];
@@ -570,8 +564,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;
         }