wave-agent-sdk 0.0.6 → 0.0.8

package/src/utils/messageOperations.ts

@@ -1,19 +1,22 @@
 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";
 
-// Parameter interfaces for message operations
-export interface AddUserMessageParams {
-  messages: Message[];
+// Base user message parameters interface
+export interface UserMessageParams {
   content: string;
   images?: Array<{ path: string; mimeType: string }>;
-  customCommandBlock?: {
-    type: "custom_command";
-    commandName: string;
-    content: string;
-    originalInput?: string;
-  };
+  customCommandContent?: string;
+  source?: MessageSource;
+}
+
+// Parameter interfaces for message operations
+export interface AddUserMessageParams extends UserMessageParams {
+  messages: Message[];
 }
 
 export interface UpdateToolBlockParams {
@@ -23,25 +26,26 @@ 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)
-export interface AgentToolBlockUpdateParams {
-  toolId: string;
-  args?: string;
-  result?: string;
-  success?: boolean;
-  error?: string;
-  isRunning?: boolean;
-  name?: string;
-  shortResult?: string;
-  compactParams?: string;
-}
+export type AgentToolBlockUpdateParams = Omit<
+  UpdateToolBlockParams,
+  "messages"
+>;
 
 export interface AddDiffBlockParams {
   messages: Message[];
@@ -81,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();
     })
@@ -133,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
   }
@@ -145,16 +150,19 @@ export const addUserMessageToMessages = ({
   messages,
   content,
   images,
-  customCommandBlock,
+  customCommandContent,
+  source,
 }: AddUserMessageParams): Message[] => {
   const blocks: Message["blocks"] = [];
 
-  // If there's a custom command block, use it instead of text content
-  if (customCommandBlock) {
-    blocks.push(customCommandBlock);
-  } else {
-    blocks.push({ type: "text", content });
-  }
+  // Create text block with optional customCommandContent and source
+  const textBlock = {
+    type: "text" as const,
+    content,
+    ...(customCommandContent && { customCommandContent }),
+    ...(source && { source }),
+  };
+  blocks.push(textBlock);
 
   // If there are images, add image block
   if (images && images.length > 0) {
@@ -178,6 +186,7 @@ export const addAssistantMessageToMessages = (
   content?: string,
   toolCalls?: ChatCompletionMessageFunctionToolCall[],
   usage?: Usage,
+  metadata?: Record<string, unknown>,
 ): Message[] => {
   const blocks: Message["blocks"] = [];
 
@@ -195,7 +204,7 @@ export const addAssistantMessageToMessages = (
         result: "",
         id: toolCall.id || "",
         name: toolCall.function?.name || "",
-        isRunning: false,
+        stage: "start",
       });
     });
   }
@@ -204,6 +213,7 @@ export const addAssistantMessageToMessages = (
     role: "assistant",
     blocks,
     usage, // Include usage data if provided
+    ...(metadata ? { metadata: { ...metadata } } : {}),
   };
 
   return [...messages, initialAssistantMessage];
@@ -239,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
@@ -262,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;
@@ -294,24 +309,23 @@ export const addErrorBlockToMessage = ({
   error,
 }: AddErrorBlockParams): Message[] => {
   const newMessages = [...messages];
-  // Find the last assistant message
-  let assistantMessageFound = false;
-  for (let i = newMessages.length - 1; i >= 0; i--) {
-    if (newMessages[i].role === "assistant") {
-      newMessages[i].blocks = [
-        ...newMessages[i].blocks,
+
+  // Check if the last message is an assistant message
+  const lastMessage = newMessages[newMessages.length - 1];
+  if (lastMessage && lastMessage.role === "assistant") {
+    // Create a new message object with the error block added
+    newMessages[newMessages.length - 1] = {
+      ...lastMessage,
+      blocks: [
+        ...lastMessage.blocks,
         {
           type: "error",
           content: error,
         },
-      ];
-      assistantMessageFound = true;
-      break;
-    }
-  }
-
-  // If no assistant message found, create a new assistant message with only error block
-  if (!assistantMessageFound) {
+      ],
+    };
+  } else {
+    // If the last message is not an assistant message, create a new assistant message
     newMessages.push({
       role: "assistant",
       blocks: [
@@ -513,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 = ({
@@ -528,7 +543,8 @@ export const addSubagentBlockToMessage = ({
   subagentId,
   subagentName,
   status,
-  subagentMessages = [],
+  sessionId,
+  configuration,
 }: AddSubagentBlockParams): Message[] => {
   const newMessages = [...messages];
 
@@ -550,7 +566,8 @@ export const addSubagentBlockToMessage = ({
     subagentId,
     subagentName,
     status,
-    messages: subagentMessages,
+    sessionId,
+    configuration,
   });
 
   return newMessages;
@@ -561,7 +578,7 @@ export const updateSubagentBlockInMessage = (
   subagentId: string,
   updates: Partial<{
     status: "active" | "completed" | "error" | "aborted";
-    messages: Message[];
+    sessionId: string;
   }>,
 ): Message[] => {
   const newMessages = [...messages];
@@ -575,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;
         }

package/src/utils/pathEncoder.ts

@@ -0,0 +1,379 @@
+/**
+ * Path encoding utility for converting working directory paths to filesystem-safe names
+ * Handles cross-platform directory name encoding for project-based session organization
+ */
+
+import { resolve, join } from "path";
+import { createHash } from "crypto";
+import { realpath, mkdir } from "fs/promises";
+import { homedir, platform } from "os";
+
+/**
+ * Project directory information
+ */
+export interface ProjectDirectory {
+  readonly originalPath: string;
+  readonly encodedName: string;
+  readonly encodedPath: string;
+  readonly pathHash?: string; // For collision resolution
+  readonly isSymbolicLink: boolean;
+}
+
+/**
+ * Path encoding configuration options
+ */
+export interface PathEncodingOptions {
+  maxLength?: number; // Default: 200 characters
+  pathSeparatorReplacement?: string; // Default: '-'
+  spaceReplacement?: string; // Default: '_'
+  invalidCharReplacement?: string; // Default: '_'
+  preserveCase?: boolean; // Default: false (convert to lowercase)
+  hashLength?: number; // Default: 8 characters
+}
+
+/**
+ * Platform-specific filesystem constraints
+ */
+export interface FilesystemConstraints {
+  readonly maxDirectoryNameLength: number;
+  readonly maxPathLength: number;
+  readonly invalidCharacters: string[];
+  readonly reservedNames: string[];
+  readonly caseSensitive: boolean;
+}
+
+/**
+ * Path validation result
+ */
+export interface PathValidationResult {
+  readonly isValid: boolean;
+  readonly errors: string[];
+  readonly warnings: string[];
+  readonly suggestedFix?: string;
+}
+
+/**
+ * PathEncoder class for converting working directory paths to filesystem-safe names
+ */
+export class PathEncoder {
+  private readonly options: Required<PathEncodingOptions>;
+  private readonly constraints: FilesystemConstraints;
+
+  constructor(options: PathEncodingOptions = {}) {
+    this.options = {
+      maxLength: options.maxLength ?? 200,
+      pathSeparatorReplacement: options.pathSeparatorReplacement ?? "-",
+      spaceReplacement: options.spaceReplacement ?? "_",
+      invalidCharReplacement: options.invalidCharReplacement ?? "_",
+      preserveCase: options.preserveCase ?? false,
+      hashLength: options.hashLength ?? 8,
+    };
+    this.constraints = this.getFilesystemConstraints();
+  }
+
+  /**
+   * Encode a working directory path to a filesystem-safe directory name
+   */
+  async encode(originalPath: string): Promise<string> {
+    // Resolve symbolic links and normalize path
+    const resolvedPath = await this.resolvePath(originalPath);
+    return this.encodeSync(resolvedPath);
+  }
+
+  /**
+   * Synchronously encode a path to a filesystem-safe directory name
+   * Note: Does not resolve symbolic links - use encode() for full path resolution
+   */
+  encodeSync(pathToEncode: string): string {
+    // Convert to safe directory name
+    let encoded = pathToEncode;
+
+    // Remove leading slash to avoid empty directory names
+    if (encoded.startsWith("/")) {
+      encoded = encoded.substring(1);
+    }
+
+    // Replace path separators with hyphens
+    encoded = encoded.replace(/[/\\]/g, this.options.pathSeparatorReplacement);
+
+    // Replace spaces with underscores
+    encoded = encoded.replace(/\s+/g, this.options.spaceReplacement);
+
+    // Replace invalid characters with underscores
+    const escapedChars = this.constraints.invalidCharacters
+      .map((c) => `\\${c}`)
+      .join("");
+    const invalidChars = new RegExp(`[${escapedChars}]`, "g");
+    encoded = encoded.replace(
+      invalidChars,
+      this.options.invalidCharReplacement,
+    );
+
+    // Convert to lowercase unless preserveCase is true
+    if (!this.options.preserveCase) {
+      encoded = encoded.toLowerCase();
+    }
+
+    // Handle length limit with hash
+    if (encoded.length > this.options.maxLength) {
+      const hash = this.generateHash(pathToEncode, this.options.hashLength);
+      const maxBaseLength =
+        this.options.maxLength - this.options.hashLength - 1; // -1 for separator
+      encoded = `${encoded.substring(0, maxBaseLength)}-${hash}`;
+    }
+
+    return encoded;
+  }
+
+  /**
+   * Decode an encoded directory name back to original path (limited functionality)
+   * Note: This is best-effort as encoding is lossy
+   */
+  async decode(encodedName: string): Promise<string | null> {
+    return this.decodeSync(encodedName);
+  }
+
+  /**
+   * Synchronously decode an encoded directory name back to original path (limited functionality)
+   * Note: This is best-effort as encoding is lossy
+   */
+  decodeSync(encodedName: string): string | null {
+    // This is a simplified version - full reversal is not always possible
+    // due to lossy encoding (case changes, character replacements, hashing)
+
+    // Check if this has a hash suffix
+    const hashPattern = new RegExp(`-[a-f0-9]{${this.options.hashLength}}$`);
+    if (hashPattern.test(encodedName)) {
+      // Cannot reliably decode hashed paths
+      return null;
+    }
+
+    // Attempt basic reversal
+    let decoded = encodedName;
+
+    // Reverse path separator replacement
+    decoded = decoded.replace(
+      new RegExp(this.options.pathSeparatorReplacement, "g"),
+      "/",
+    );
+
+    // Reverse space replacement
+    decoded = decoded.replace(
+      new RegExp(this.options.spaceReplacement, "g"),
+      " ",
+    );
+
+    // Add leading slash
+    decoded = `/${decoded}`;
+
+    return decoded;
+  }
+
+  /**
+   * Resolve symbolic links and normalize path before encoding
+   */
+  async resolvePath(path: string): Promise<string> {
+    try {
+      // Expand tilde to home directory
+      const expandedPath = this.expandTilde(path);
+
+      // Resolve to absolute path
+      const absolutePath = resolve(expandedPath);
+
+      // Resolve symbolic links
+      const resolvedPath = await realpath(absolutePath);
+
+      return resolvedPath;
+    } catch (error) {
+      throw new Error(`Failed to resolve path "${path}": ${error}`);
+    }
+  }
+
+  /**
+   * Create project directory entity from original path
+   */
+  async createProjectDirectory(
+    originalPath: string,
+    baseSessionDir: string,
+  ): Promise<ProjectDirectory> {
+    // Resolve the original path and check for symbolic links
+    const expandedPath = this.expandTilde(originalPath);
+    const absolutePath = resolve(expandedPath);
+
+    let resolvedPath: string;
+    let isSymbolicLink = false;
+
+    try {
+      resolvedPath = await realpath(absolutePath);
+      isSymbolicLink = resolvedPath !== absolutePath;
+    } catch {
+      // If realpath fails, use the absolute path
+      resolvedPath = absolutePath;
+    }
+
+    // Encode the resolved path
+    const encodedName = await this.encode(resolvedPath);
+    const encodedPath = join(baseSessionDir, encodedName);
+
+    // Generate hash if encoding resulted in truncation
+    let pathHash: string | undefined;
+    if (resolvedPath.length > this.options.maxLength) {
+      pathHash = this.generateHash(resolvedPath, this.options.hashLength);
+    }
+
+    // Ensure the encoded directory exists
+    try {
+      await mkdir(encodedPath, { recursive: true });
+    } catch {
+      // Ignore errors if directory already exists
+    }
+
+    return {
+      originalPath: resolvedPath,
+      encodedName,
+      encodedPath,
+      pathHash,
+      isSymbolicLink,
+    };
+  }
+
+  /**
+   * Validate that an encoded name is filesystem-safe
+   */
+  validateEncodedName(encodedName: string): boolean {
+    // Check length
+    if (encodedName.length > this.constraints.maxDirectoryNameLength) {
+      return false;
+    }
+
+    // Check for invalid characters
+    for (const char of this.constraints.invalidCharacters) {
+      if (encodedName.includes(char)) {
+        return false;
+      }
+    }
+
+    // Check for reserved names
+    const lowerName = encodedName.toLowerCase();
+    if (
+      this.constraints.reservedNames.some(
+        (reserved) => reserved.toLowerCase() === lowerName,
+      )
+    ) {
+      return false;
+    }
+
+    // Check for empty or dots-only names
+    if (!encodedName.trim() || /^\.+$/.test(encodedName)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Handle encoding collisions by generating unique names
+   */
+  resolveCollision(baseName: string, existingNames: Set<string>): string {
+    if (!existingNames.has(baseName)) {
+      return baseName;
+    }
+
+    // Try numbered suffixes first
+    for (let i = 1; i <= 999; i++) {
+      const candidate = `${baseName}-${i}`;
+      if (!existingNames.has(candidate)) {
+        return candidate;
+      }
+    }
+
+    // If all numbered suffixes are taken, use hash
+    const hash = this.generateHash(
+      baseName + Date.now(),
+      this.options.hashLength,
+    );
+    return `${baseName}-${hash}`;
+  }
+
+  /**
+   * Get platform-specific filesystem constraints
+   */
+  private getFilesystemConstraints(): FilesystemConstraints {
+    const currentPlatform = platform();
+
+    switch (currentPlatform) {
+      case "win32":
+        return {
+          maxDirectoryNameLength: 255,
+          maxPathLength: 260,
+          invalidCharacters: ["<", ">", ":", '"', "|", "?", "*"],
+          reservedNames: [
+            "CON",
+            "PRN",
+            "AUX",
+            "NUL",
+            "COM1",
+            "COM2",
+            "COM3",
+            "COM4",
+            "COM5",
+            "COM6",
+            "COM7",
+            "COM8",
+            "COM9",
+            "LPT1",
+            "LPT2",
+            "LPT3",
+            "LPT4",
+            "LPT5",
+            "LPT6",
+            "LPT7",
+            "LPT8",
+            "LPT9",
+          ],
+          caseSensitive: false,
+        };
+      case "darwin":
+        return {
+          maxDirectoryNameLength: 255,
+          maxPathLength: 1024,
+          invalidCharacters: [":"],
+          reservedNames: [],
+          caseSensitive: false, // HFS+ is case-insensitive by default
+        };
+      default: // Linux and other Unix-like systems
+        return {
+          maxDirectoryNameLength: 255,
+          maxPathLength: 4096,
+          invalidCharacters: ["\0"],
+          reservedNames: [],
+          caseSensitive: true,
+        };
+    }
+  }
+
+  /**
+   * Generate hash for collision resolution
+   */
+  private generateHash(input: string, length: number): string {
+    return createHash("sha256")
+      .update(input)
+      .digest("hex")
+      .substring(0, length);
+  }
+
+  /**
+   * Expand tilde (~) to home directory
+   */
+  private expandTilde(path: string): string {
+    if (path.startsWith("~/") || path === "~") {
+      return path.replace(/^~/, homedir());
+    }
+    return path;
+  }
+}
+
+/**
+ * Default PathEncoder instance
+ */
+export const pathEncoder = new PathEncoder();

package/src/utils/subagentParser.ts

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync, statSync } from "fs";
 import { join, extname } from "path";
+import { logger } from "./globalLogger.js";
 
 export interface SubagentConfiguration {
   name: string;
@@ -172,7 +173,7 @@ function scanSubagentDirectory(
           configurations.push(config);
         } catch (parseError) {
           // Log error but continue with other files
-          console.warn(
+          logger.warn(
             `Warning: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
           );
         }