wave-agent-sdk 0.0.7 → 0.0.10

package/dist/utils/pathEncoder.js

@@ -0,0 +1,279 @@
+/**
+ * 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";
+/**
+ * PathEncoder class for converting working directory paths to filesystem-safe names
+ */
+export class PathEncoder {
+    constructor(options = {}) {
+        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) {
+        // 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) {
+        // 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) {
+        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) {
+        // 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) {
+        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, baseSessionDir) {
+        // Resolve the original path and check for symbolic links
+        const expandedPath = this.expandTilde(originalPath);
+        const absolutePath = resolve(expandedPath);
+        let resolvedPath;
+        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;
+        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, baseSessionDir) {
+        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) {
+        // 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, existingNames) {
+        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
+     */
+    getFilesystemConstraints() {
+        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
+     */
+    generateHash(input, length) {
+        return createHash("sha256")
+            .update(input)
+            .digest("hex")
+            .substring(0, length);
+    }
+    /**
+     * Expand tilde (~) to home directory
+     */
+    expandTilde(path) {
+        if (path.startsWith("~/") || path === "~") {
+            return path.replace(/^~/, homedir());
+        }
+        return path;
+    }
+}
+/**
+ * Default PathEncoder instance
+ */
+export const pathEncoder = new PathEncoder();

package/dist/utils/subagentParser.d.ts

@@ -5,11 +5,11 @@ export interface SubagentConfiguration {
     model?: string;
     systemPrompt: string;
     filePath: string;
-    scope: "project" | "user";
+    scope: "project" | "user" | "builtin";
     priority: number;
 }
 /**
- * Load all subagent configurations from project and user directories
+ * Load all subagent configurations from project and user directories, plus built-in subagents
  */
 export declare function loadSubagentConfigurations(workdir: string): Promise<SubagentConfiguration[]>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"subagentParser.d.ts","sourceRoot":"","sources":["../../src/utils/subagentParser.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AA+KD;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAmBlC;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAGvC"}
+{"version":3,"file":"subagentParser.d.ts","sourceRoot":"","sources":["../../src/utils/subagentParser.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB;AA+KD;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAsBlC;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAGvC"}

package/dist/utils/subagentParser.js

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync, statSync } from "fs";
 import { join, extname } from "path";
+import { logger } from "./globalLogger.js";
 /**
  * Parse YAML frontmatter from markdown file content
  */
@@ -67,10 +68,10 @@ function validateConfiguration(config, filePath) {
     if (!config.description) {
         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.`);
+        throw new Error(`Invalid subagent name '${config.name}' in ${filePath}. Must start with a letter and contain only letters, numbers, and hyphens.`);
     }
     // Validate model if specified - allow any non-empty string
     if (config.model && typeof config.model !== "string") {
@@ -120,7 +121,7 @@ function scanSubagentDirectory(dirPath, scope) {
                 }
                 catch (parseError) {
                     // Log error but continue with other files
-                    console.warn(`Warning: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+                    logger.warn(`Warning: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
                 }
             }
         }
@@ -131,17 +132,20 @@ function scanSubagentDirectory(dirPath, scope) {
     return configurations;
 }
 /**
- * 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) {
     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();
-    // 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);
     }
     return Array.from(configMap.values()).sort((a, b) => {

package/dist/utils/tokenCalculation.d.ts

@@ -0,0 +1,26 @@
+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 declare function calculateComprehensiveTotalTokens(usage: Usage): number;
+/**
+ * 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 declare function extractLatestTotalTokens(messages: Array<{
+    usage?: Usage;
+}>): number;
+//# sourceMappingURL=tokenCalculation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokenCalculation.d.ts","sourceRoot":"","sources":["../../src/utils/tokenCalculation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAMtE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,GACjC,MAAM,CAUR"}

package/dist/utils/tokenCalculation.js

@@ -0,0 +1,36 @@
+/**
+ * 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) {
+    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) {
+    // 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/dist/utils/tokenEstimator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare function estimateTokenCount(text: string): number;
+/**
+ * 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 declare function exceedsTokenThreshold(text: string, threshold?: number): boolean;
+/**
+ * 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 declare function getTokenUsageDescription(text: string, threshold?: number): string;
+//# sourceMappingURL=tokenEstimator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokenEstimator.d.ts","sourceRoot":"","sources":["../../src/utils/tokenEstimator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcvD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAc,GACxB,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAc,GACxB,MAAM,CAKR"}

package/dist/utils/tokenEstimator.js

@@ -0,0 +1,55 @@
+/**
+ * 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) {
+    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, threshold = 20000) {
+    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, threshold = 20000) {
+    const estimatedTokens = estimateTokenCount(text);
+    const exceedsThreshold = estimatedTokens > threshold;
+    return `${estimatedTokens.toLocaleString()} tokens (${exceedsThreshold ? "exceeds" : "within"} ${threshold.toLocaleString()} limit)`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "0.0.7",
+  "version": "0.0.10",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -21,25 +21,25 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.18.2",
     "@vscode/ripgrep": "^1.15.14",
-    "diff": "^8.0.2",
-    "glob": "^11.0.3",
+    "chokidar": "^5.0.0",
+    "glob": "^13.0.0",
     "minimatch": "^10.0.3",
     "openai": "^5.12.2"
   },
   "devDependencies": {
-    "rimraf": "^6.0.1",
+    "rimraf": "^6.1.2",
     "tsc-alias": "^1.8.16",
     "tsx": "^4.20.4",
     "vitest": "^3.2.4"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=22.0.0"
   },
   "license": "MIT",
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "type-check": "tsc --noEmit --incremental",
-    "dev": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --watch",
+    "watch": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --watch",
     "test": "vitest run",
     "lint": "eslint --cache",
     "format": "prettier --write ."