wave-agent-sdk 0.0.7 → 0.0.10

package/src/utils/pathEncoder.ts

@@ -0,0 +1,394 @@
+/**
+ * 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}`);
+    }
+  }
+
+  /**
+   * Get project directory info without creating the directory
+   */
+  async getProjectDirectory(
+    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);
+    }
+
+    return {
+      originalPath: resolvedPath,
+      encodedName,
+      encodedPath,
+      pathHash,
+      isSymbolicLink,
+    };
+  }
+
+  /**
+   * Create project directory entity from original path
+   */
+  async createProjectDirectory(
+    originalPath: string,
+    baseSessionDir: string,
+  ): Promise<ProjectDirectory> {
+    const projectDirectory = await this.getProjectDirectory(
+      originalPath,
+      baseSessionDir,
+    );
+
+    // Ensure the encoded directory exists
+    try {
+      await mkdir(projectDirectory.encodedPath, { recursive: true });
+    } catch {
+      // Ignore errors if directory already exists
+    }
+
+    return projectDirectory;
+  }
+
+  /**
+   * 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;
@@ -8,7 +9,7 @@ export interface SubagentConfiguration {
   model?: string;
   systemPrompt: string;
   filePath: string;
-  scope: "project" | "user";
+  scope: "project" | "user" | "builtin";
   priority: number;
 }
 
@@ -100,11 +101,11 @@ function validateConfiguration(
     throw new Error(`Missing required field 'description' in ${filePath}`);
   }
 
-  // Validate name pattern
-  const namePattern = /^[a-z][a-z0-9-]*$/;
+  // Validate name pattern - allow letters (upper/lowercase), numbers, and hyphens
+  const namePattern = /^[a-zA-Z][a-zA-Z0-9-]*$/;
   if (!namePattern.test(config.name)) {
     throw new Error(
-      `Invalid subagent name '${config.name}' in ${filePath}. Must start with a letter and contain only lowercase letters, numbers, and hyphens.`,
+      `Invalid subagent name '${config.name}' in ${filePath}. Must start with a letter and contain only letters, numbers, and hyphens.`,
     );
   }
 
@@ -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)}`,
           );
         }
@@ -186,7 +187,7 @@ function scanSubagentDirectory(
 }
 
 /**
- * Load all subagent configurations from project and user directories
+ * Load all subagent configurations from project and user directories, plus built-in subagents
  */
 export async function loadSubagentConfigurations(
   workdir: string,
@@ -194,14 +195,17 @@ export async function loadSubagentConfigurations(
   const projectDir = join(workdir, ".wave", "agents");
   const userDir = join(process.env.HOME || "~", ".wave", "agents");
 
+  // Load configurations from all sources
+  const { getBuiltinSubagents } = await import("./builtinSubagents.js");
+  const builtinConfigs = getBuiltinSubagents();
   const projectConfigs = scanSubagentDirectory(projectDir, "project");
   const userConfigs = scanSubagentDirectory(userDir, "user");
 
-  // Merge configurations, with project configs taking precedence
+  // Merge configurations, with project configs taking highest precedence
   const configMap = new Map<string, SubagentConfiguration>();
 
-  // Process in reverse priority order (user first, then project)
-  for (const config of [...userConfigs, ...projectConfigs]) {
+  // Process in reverse priority order (built-in first, then user, then project)
+  for (const config of [...builtinConfigs, ...userConfigs, ...projectConfigs]) {
     configMap.set(config.name, config);
   }
 

package/src/utils/tokenCalculation.ts

@@ -0,0 +1,43 @@
+import type { Usage } from "../types/index.js";
+
+/**
+ * Calculate comprehensive total tokens including cache-related tokens
+ *
+ * This function computes the true total token cost by including:
+ * - Base total_tokens (prompt + completion)
+ * - Cache read tokens (cost savings indicator)
+ * - Cache creation tokens (cache investment)
+ *
+ * For accurate cost tracking with Claude models that support cache control.
+ *
+ * @param usage - Usage statistics from AI operation
+ * @returns Comprehensive total including all cache-related tokens
+ */
+export function calculateComprehensiveTotalTokens(usage: Usage): number {
+  const baseTokens = usage.total_tokens;
+  const cacheReadTokens = usage.cache_read_input_tokens || 0;
+  const cacheCreateTokens = usage.cache_creation_input_tokens || 0;
+
+  return baseTokens + cacheReadTokens + cacheCreateTokens;
+}
+
+/**
+ * Extract the latest total tokens from the last message with usage data
+ * Uses comprehensive calculation that includes cache tokens for accurate tracking
+ *
+ * @param messages - Array of messages to search
+ * @returns Comprehensive total tokens from the most recent usage data, or 0 if none found
+ */
+export function extractLatestTotalTokens(
+  messages: Array<{ usage?: Usage }>,
+): number {
+  // Find the last message with usage data (iterate backwards for efficiency)
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.usage) {
+      return calculateComprehensiveTotalTokens(message.usage);
+    }
+  }
+
+  return 0; // No usage data found
+}

package/src/utils/tokenEstimator.ts

@@ -0,0 +1,68 @@
+/**
+ * Simple token estimation utility for text content
+ *
+ * This provides a fast approximation of token count without requiring
+ * actual tokenization, which would be expensive for large content.
+ */
+
+/**
+ * Estimate the number of tokens in a text string
+ *
+ * Uses a simple heuristic based on character count and common patterns:
+ * - Average token length varies by language and content type
+ * - English text: ~4-5 characters per token
+ * - Code/structured text: ~3-4 characters per token
+ * - Numbers/symbols: ~2-3 characters per token
+ *
+ * This function uses a conservative estimate of 4 characters per token
+ * which works well for mixed content (text + code + symbols).
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated number of tokens
+ */
+export function estimateTokenCount(text: string): number {
+  if (!text || text.length === 0) {
+    return 0;
+  }
+
+  // Base estimation: 4 characters per token (conservative)
+  const baseEstimate = Math.ceil(text.length / 4);
+
+  // Adjust for whitespace (spaces don't contribute much to token count)
+  const whitespaceCount = (text.match(/\s/g) || []).length;
+  const adjustedEstimate = Math.ceil((text.length - whitespaceCount * 0.5) / 4);
+
+  // Use the more conservative (higher) estimate
+  return Math.max(baseEstimate, adjustedEstimate);
+}
+
+/**
+ * Check if estimated token count exceeds a threshold
+ *
+ * @param text - The text to check
+ * @param threshold - Token threshold (default: 20,000)
+ * @returns True if estimated tokens exceed threshold
+ */
+export function exceedsTokenThreshold(
+  text: string,
+  threshold: number = 20000,
+): boolean {
+  return estimateTokenCount(text) > threshold;
+}
+
+/**
+ * Get a human-readable description of estimated token usage
+ *
+ * @param text - The text to analyze
+ * @param threshold - Token threshold for comparison
+ * @returns Description string with token count and threshold info
+ */
+export function getTokenUsageDescription(
+  text: string,
+  threshold: number = 20000,
+): string {
+  const estimatedTokens = estimateTokenCount(text);
+  const exceedsThreshold = estimatedTokens > threshold;
+
+  return `${estimatedTokens.toLocaleString()} tokens (${exceedsThreshold ? "exceeds" : "within"} ${threshold.toLocaleString()} limit)`;
+}

package/dist/utils/configResolver.d.ts

@@ -1,38 +0,0 @@
-/**
- * Configuration resolver utilities for Agent Constructor Configuration
- * Resolves configuration from constructor arguments with environment fallbacks
- */
-import { GatewayConfig, ModelConfig } from "../types/index.js";
-export declare class ConfigResolver {
-    /**
-     * Resolves gateway configuration from constructor args and environment
-     * @param apiKey - API key from constructor (optional)
-     * @param baseURL - Base URL from constructor (optional)
-     * @returns Resolved gateway configuration
-     * @throws ConfigurationError if required configuration is missing after fallbacks
-     */
-    static resolveGatewayConfig(apiKey?: string, baseURL?: string): GatewayConfig;
-    /**
-     * Resolves model configuration with fallbacks
-     * @param agentModel - Agent model from constructor (optional)
-     * @param fastModel - Fast model from constructor (optional)
-     * @returns Resolved model configuration with defaults
-     */
-    static resolveModelConfig(agentModel?: string, fastModel?: string): ModelConfig;
-    /**
-     * Resolves token limit with fallbacks
-     * @param constructorLimit - Token limit from constructor (optional)
-     * @returns Resolved token limit
-     */
-    static resolveTokenLimit(constructorLimit?: number): number;
-}
-/**
- * Static configuration resolver instance
- * Implements ConfigurationResolver interface from types.ts
- */
-export declare const configResolver: {
-    resolveGatewayConfig: typeof ConfigResolver.resolveGatewayConfig;
-    resolveModelConfig: typeof ConfigResolver.resolveModelConfig;
-    resolveTokenLimit: typeof ConfigResolver.resolveTokenLimit;
-};
-//# sourceMappingURL=configResolver.d.ts.map

package/dist/utils/configResolver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"configResolver.d.ts","sourceRoot":"","sources":["../../src/utils/configResolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EAGZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,cAAc;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CACzB,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,aAAa;IAuDhB;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CACvB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW;IAmBd;;;;OAIG;IACH,MAAM,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM;CAoB5D;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;CAI1B,CAAC"}