wave-agent-sdk 0.0.7 → 0.0.8

package/dist/services/hook.js

@@ -6,9 +6,9 @@
  */
 import { spawn } from "child_process";
 import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
+import { getUserConfigPath, getProjectConfigPath, getUserConfigPaths, getProjectConfigPaths, hasAnyConfig, getConfigurationInfo, } from "../utils/configPaths.js";
 import { getSessionFilePath, isValidHookEvent, } from "../types/hooks.js";
+import { isValidEnvironmentVars, } from "../types/environment.js";
 // =============================================================================
 // Hook Execution Functions
 // =============================================================================
@@ -39,12 +39,16 @@ function buildHookJsonInput(context) {
         context.userPrompt !== undefined) {
         jsonInput.user_prompt = context.userPrompt;
     }
+    // Add subagent_type if present
+    if (context.subagentType !== undefined) {
+        jsonInput.subagent_type = context.subagentType;
+    }
     return jsonInput;
 }
 /**
  * Execute a single hook command
  */
-export async function executeCommand(command, context, options) {
+export async function executeCommand(command, context, options, additionalEnvVars) {
     const defaultTimeout = 10000; // 10 seconds
     const maxTimeout = 300000; // 5 minutes
     const skipExecution = process.env.NODE_ENV === "test" &&
@@ -75,6 +79,7 @@ export async function executeCommand(command, context, options) {
             cwd: context.projectDir,
             env: {
                 ...process.env,
+                ...additionalEnvVars, // Merge additional environment variables from Wave configuration
                 HOOK_EVENT: context.event,
                 HOOK_TOOL_NAME: context.toolName || "",
                 HOOK_PROJECT_DIR: context.projectDir,
@@ -148,10 +153,10 @@ export async function executeCommand(command, context, options) {
 /**
  * Execute multiple commands in sequence
  */
-export async function executeCommands(commands, context, options) {
+export async function executeCommands(commands, context, options, additionalEnvVars) {
     const results = [];
     for (const command of commands) {
-        const result = await executeCommand(command, context, options);
+        const result = await executeCommand(command, context, options, additionalEnvVars);
         results.push(result);
         // Stop on first failure unless continueOnFailure is set
         if (!result.success && !options?.continueOnFailure) {
@@ -182,53 +187,381 @@ export function isCommandSafe(command) {
     return !dangerousPatterns.some((pattern) => pattern.test(trimmed.toLowerCase()));
 }
 // =============================================================================
-// Hook Settings Functions
+// Environment Variable Functions
+// =============================================================================
+/**
+ * Validate environment variable configuration
+ */
+export function validateEnvironmentConfig(env, configPath) {
+    const result = {
+        isValid: true,
+        errors: [],
+        warnings: [],
+    };
+    // Check if env is defined
+    if (env === undefined || env === null) {
+        return result; // undefined/null env is valid (means no env vars)
+    }
+    // Validate that env is a Record<string, string>
+    if (!isValidEnvironmentVars(env)) {
+        result.isValid = false;
+        result.errors.push(`Invalid env field format${configPath ? ` in ${configPath}` : ""}. Environment variables must be a Record<string, string>.`);
+        return result;
+    }
+    // Additional validation for environment variable names
+    const envVars = env;
+    for (const [key, value] of Object.entries(envVars)) {
+        // Check for valid environment variable naming convention
+        if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) {
+            result.warnings.push(`Environment variable '${key}' does not follow standard naming convention (alphanumeric and underscores only).`);
+        }
+        // Check for empty values
+        if (value === "") {
+            result.warnings.push(`Environment variable '${key}' has an empty value.`);
+        }
+        // Check for reserved variable names that might cause conflicts
+        const reservedNames = [
+            "PATH",
+            "HOME",
+            "USER",
+            "PWD",
+            "SHELL",
+            "TERM",
+            "NODE_ENV",
+        ];
+        if (reservedNames.includes(key.toUpperCase())) {
+            result.warnings.push(`Environment variable '${key}' overrides a system variable, which may cause unexpected behavior.`);
+        }
+    }
+    return result;
+}
+/**
+ * Merge environment configurations with project taking precedence over user
+ */
+export function mergeEnvironmentConfig(userEnv, projectEnv, options = {}) {
+    const userVars = userEnv || {};
+    const projectVars = projectEnv || {};
+    const mergedVars = {};
+    const conflicts = [];
+    // Start with user environment variables
+    Object.assign(mergedVars, userVars);
+    // Override with project environment variables and track conflicts
+    for (const [key, projectValue] of Object.entries(projectVars)) {
+        const userValue = userVars[key];
+        if (userValue !== undefined &&
+            userValue !== projectValue &&
+            options.includeConflictWarnings !== false) {
+            // Conflict detected - project value takes precedence
+            conflicts.push({
+                key,
+                userValue,
+                projectValue,
+                resolvedValue: projectValue,
+            });
+        }
+        mergedVars[key] = projectValue;
+    }
+    return {
+        userVars,
+        projectVars,
+        mergedVars,
+        conflicts,
+    };
+}
+// =============================================================================
+// Hook Settings Functions (using centralized config path utilities)
 // =============================================================================
 /**
- * Get the user-specific hooks configuration file path
+ * Get the user-specific hooks configuration file path (legacy function)
+ * @deprecated Use getUserConfigPaths() from configPaths.ts for better priority support
  */
 export function getUserHooksConfigPath() {
-    return join(homedir(), ".wave", "settings.json");
+    return getUserConfigPath();
 }
 /**
- * Get the project-specific hooks configuration file path
+ * Get the project-specific hooks configuration file path (legacy function)
+ * @deprecated Use getProjectConfigPaths() from configPaths.ts for better priority support
  */
 export function getProjectHooksConfigPath(workdir) {
-    return join(workdir, ".wave", "settings.json");
+    return getProjectConfigPath(workdir);
 }
 /**
- * Load hooks configuration from a JSON file
+ * Get the user-specific hooks configuration file paths in priority order
+ * @deprecated Use getUserConfigPaths() from configPaths.ts directly
  */
-export function loadHooksConfigFromFile(filePath) {
+export function getUserHooksConfigPaths() {
+    return getUserConfigPaths();
+}
+/**
+ * Get the project-specific hooks configuration file paths in priority order
+ * @deprecated Use getProjectConfigPaths() from configPaths.ts directly
+ */
+export function getProjectHooksConfigPaths(workdir) {
+    return getProjectConfigPaths(workdir);
+}
+/**
+ * Load Wave configuration from a JSON file with graceful fallback
+ * This version is optimized for live reload scenarios where invalid config should not crash the system
+ */
+export function loadWaveConfigFromFileWithFallback(filePath, previousValidConfig) {
+    if (!existsSync(filePath)) {
+        return { config: null, usedFallback: false };
+    }
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        const config = JSON.parse(content);
+        // Validate basic structure
+        if (!config || typeof config !== "object") {
+            const error = `Invalid configuration structure in ${filePath}`;
+            return {
+                config: previousValidConfig || null,
+                error,
+                usedFallback: !!previousValidConfig,
+            };
+        }
+        // Validate environment variables if present
+        if (config.env !== undefined) {
+            const envValidation = validateEnvironmentConfig(config.env, filePath);
+            if (!envValidation.isValid) {
+                const error = `Environment variable validation failed in ${filePath}: ${envValidation.errors.join(", ")}`;
+                return {
+                    config: previousValidConfig || null,
+                    error,
+                    usedFallback: !!previousValidConfig,
+                };
+            }
+            // Log warnings if any
+            if (envValidation.warnings.length > 0) {
+                console.warn(`Environment variable warnings in ${filePath}:\n- ${envValidation.warnings.join("\n- ")}`);
+            }
+        }
+        // Return valid configuration
+        return {
+            config: {
+                hooks: config.hooks || undefined,
+                env: config.env || undefined,
+            },
+            usedFallback: false,
+        };
+    }
+    catch (error) {
+        let errorMessage;
+        if (error instanceof SyntaxError) {
+            errorMessage = `Invalid JSON syntax in ${filePath}: ${error.message}`;
+        }
+        else {
+            errorMessage = `Error loading configuration from ${filePath}: ${error.message}`;
+        }
+        return {
+            config: previousValidConfig || null,
+            error: errorMessage,
+            usedFallback: !!previousValidConfig,
+        };
+    }
+}
+/**
+ * Load Wave configuration from multiple file paths in priority order
+ * Returns the first valid configuration found, or null if none exist
+ */
+export function loadWaveConfigFromFiles(filePaths) {
+    for (const filePath of filePaths) {
+        const config = loadWaveConfigFromFile(filePath);
+        if (config !== null) {
+            return config;
+        }
+    }
+    return null;
+}
+/**
+ * Load Wave configuration from multiple file paths with graceful fallback
+ * Returns the first valid configuration found with fallback support
+ */
+export function loadWaveConfigFromFilesWithFallback(filePaths, previousValidConfig) {
+    let lastError;
+    for (const filePath of filePaths) {
+        const result = loadWaveConfigFromFileWithFallback(filePath, previousValidConfig);
+        if (result.config !== null && !result.usedFallback) {
+            // Found a valid config at this path
+            return {
+                config: result.config,
+                error: result.error,
+                usedFallback: result.usedFallback,
+                usedPath: filePath,
+            };
+        }
+        if (result.error) {
+            lastError = result.error;
+        }
+    }
+    // No valid config found in any path
+    return {
+        config: previousValidConfig || null,
+        error: lastError,
+        usedFallback: !!previousValidConfig,
+    };
+}
+/**
+ * Load and merge Wave configuration with graceful fallback for live reload
+ * Provides error recovery by falling back to previous valid configuration
+ */
+export function loadMergedWaveConfigWithFallback(workdir, previousValidConfig) {
+    const errors = [];
+    let usedFallback = false;
+    // Load user config with fallback (check .local.json first, then .json)
+    const userResult = loadWaveConfigFromFilesWithFallback(getUserHooksConfigPaths(), previousValidConfig);
+    if (userResult.error) {
+        errors.push(`User config: ${userResult.error}`);
+    }
+    if (userResult.usedFallback) {
+        usedFallback = true;
+    }
+    // Load project config with fallback (check .local.json first, then .json)
+    const projectResult = loadWaveConfigFromFilesWithFallback(getProjectHooksConfigPaths(workdir), previousValidConfig);
+    if (projectResult.error) {
+        errors.push(`Project config: ${projectResult.error}`);
+    }
+    if (projectResult.usedFallback) {
+        usedFallback = true;
+    }
+    const userConfig = userResult.config;
+    const projectConfig = projectResult.config;
+    // If both configs failed and no fallback available
+    if (!userConfig && !projectConfig && errors.length > 0) {
+        return {
+            config: previousValidConfig || null,
+            errors,
+            usedFallback: !!previousValidConfig,
+        };
+    }
+    // No configuration found at all
+    if (!userConfig && !projectConfig) {
+        return { config: null, errors, usedFallback };
+    }
+    // Only one configuration found
+    if (!userConfig)
+        return { config: projectConfig, errors, usedFallback };
+    if (!projectConfig)
+        return { config: userConfig, errors, usedFallback };
+    // Merge configurations (project overrides user)
+    try {
+        const mergedHooks = {};
+        // Merge environment variables using the new mergeEnvironmentConfig function
+        const environmentContext = mergeEnvironmentConfig(userConfig.env, projectConfig.env, { includeConflictWarnings: true });
+        // Merge hooks (combine arrays, project configs come after user configs)
+        const allEvents = new Set([
+            ...Object.keys(userConfig.hooks || {}),
+            ...Object.keys(projectConfig.hooks || {}),
+        ]);
+        for (const event of allEvents) {
+            if (!isValidHookEvent(event))
+                continue;
+            const userEventConfigs = userConfig.hooks?.[event] || [];
+            const projectEventConfigs = projectConfig.hooks?.[event] || [];
+            // Project configurations take precedence
+            mergedHooks[event] = [...userEventConfigs, ...projectEventConfigs];
+        }
+        const mergedConfig = {
+            hooks: Object.keys(mergedHooks).length > 0 ? mergedHooks : undefined,
+            env: Object.keys(environmentContext.mergedVars).length > 0
+                ? environmentContext.mergedVars
+                : undefined,
+        };
+        return { config: mergedConfig, errors, usedFallback };
+    }
+    catch (error) {
+        errors.push(`Merge error: ${error.message}`);
+        return {
+            config: previousValidConfig || null,
+            errors,
+            usedFallback: !!previousValidConfig,
+        };
+    }
+}
+/**
+ * Load Wave configuration from a JSON file
+ * Supports both hooks and environment variables with proper validation
+ */
+export function loadWaveConfigFromFile(filePath) {
     if (!existsSync(filePath)) {
         return null;
     }
-    const content = readFileSync(filePath, "utf-8");
-    const config = JSON.parse(content);
-    // Validate basic structure
-    if (!config || typeof config !== "object" || !config.hooks) {
-        throw new Error(`Invalid hooks configuration structure in ${filePath}`);
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        const config = JSON.parse(content);
+        // Validate basic structure
+        if (!config || typeof config !== "object") {
+            throw new Error(`Invalid configuration structure in ${filePath}`);
+        }
+        // Validate environment variables if present
+        if (config.env !== undefined) {
+            const envValidation = validateEnvironmentConfig(config.env, filePath);
+            if (!envValidation.isValid) {
+                throw new Error(`Environment variable validation failed in ${filePath}: ${envValidation.errors.join(", ")}`);
+            }
+            // Log warnings if any
+            if (envValidation.warnings.length > 0) {
+                console.warn(`Environment variable warnings in ${filePath}:\n- ${envValidation.warnings.join("\n- ")}`);
+            }
+        }
+        return {
+            hooks: config.hooks || undefined,
+            env: config.env || undefined,
+        };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON syntax in ${filePath}: ${error.message}`);
+        }
+        // Re-throw validation errors and other errors as-is
+        throw error;
+    }
+}
+/**
+ * Load hooks configuration from a JSON file (legacy function)
+ */
+export function loadHooksConfigFromFile(filePath) {
+    const waveConfig = loadWaveConfigFromFile(filePath);
+    if (!waveConfig) {
+        return null;
     }
-    return config.hooks;
+    return waveConfig.hooks || null;
+}
+/**
+ * Load user-specific Wave configuration
+ * Checks .local.json first, then falls back to .json
+ */
+export function loadUserWaveConfig() {
+    return loadWaveConfigFromFiles(getUserHooksConfigPaths());
 }
 /**
- * Load user-specific hooks configuration
+ * Load project-specific Wave configuration
+ * Checks .local.json first, then falls back to .json
+ */
+export function loadProjectWaveConfig(workdir) {
+    return loadWaveConfigFromFiles(getProjectHooksConfigPaths(workdir));
+}
+/**
+ * Load user-specific hooks configuration (legacy function)
  */
 export function loadUserHooksConfig() {
-    return loadHooksConfigFromFile(getUserHooksConfigPath());
+    const waveConfig = loadUserWaveConfig();
+    return waveConfig?.hooks || null;
 }
 /**
- * Load project-specific hooks configuration
+ * Load project-specific hooks configuration (legacy function)
  */
 export function loadProjectHooksConfig(workdir) {
-    return loadHooksConfigFromFile(getProjectHooksConfigPath(workdir));
+    const waveConfig = loadProjectWaveConfig(workdir);
+    return waveConfig?.hooks || null;
 }
 /**
- * Load and merge hooks configuration from both user and project sources
+ * Load and merge Wave configuration from both user and project sources
+ * Project configuration takes precedence over user configuration
+ * Checks .local.json files first, then falls back to .json files
  */
-export function loadMergedHooksConfig(workdir) {
-    const userConfig = loadUserHooksConfig();
-    const projectConfig = loadProjectHooksConfig(workdir);
+export function loadMergedWaveConfig(workdir) {
+    const userConfig = loadUserWaveConfig();
+    const projectConfig = loadProjectWaveConfig(workdir);
     // No configuration found
     if (!userConfig && !projectConfig) {
         return null;
@@ -239,38 +572,55 @@ export function loadMergedHooksConfig(workdir) {
     if (!projectConfig)
         return userConfig;
     // Merge configurations (project overrides user)
-    const merged = {};
-    // Combine all hook events
+    const mergedHooks = {};
+    // Merge environment variables using the new mergeEnvironmentConfig function
+    const environmentContext = mergeEnvironmentConfig(userConfig.env, projectConfig.env, { includeConflictWarnings: true });
+    // Log environment variable conflicts if any
+    if (environmentContext.conflicts.length > 0) {
+        console.warn(`Environment variable conflicts detected (project values take precedence):\n${environmentContext.conflicts
+            .map((conflict) => `- ${conflict.key}: "${conflict.userValue}" → "${conflict.projectValue}"`)
+            .join("\n")}`);
+    }
+    // Merge hooks (combine arrays, project configs come after user configs)
     const allEvents = new Set([
-        ...Object.keys(userConfig),
-        ...Object.keys(projectConfig),
+        ...Object.keys(userConfig.hooks || {}),
+        ...Object.keys(projectConfig.hooks || {}),
     ]);
     for (const event of allEvents) {
         if (!isValidHookEvent(event))
             continue;
-        const userEventConfigs = userConfig[event] || [];
-        const projectEventConfigs = projectConfig[event] || [];
+        const userEventConfigs = userConfig.hooks?.[event] || [];
+        const projectEventConfigs = projectConfig.hooks?.[event] || [];
         // Project configurations take precedence
-        merged[event] = [...userEventConfigs, ...projectEventConfigs];
+        mergedHooks[event] = [...userEventConfigs, ...projectEventConfigs];
     }
-    return merged;
+    return {
+        hooks: Object.keys(mergedHooks).length > 0 ? mergedHooks : undefined,
+        env: Object.keys(environmentContext.mergedVars).length > 0
+            ? environmentContext.mergedVars
+            : undefined,
+    };
+}
+/**
+ * Load and merge hooks configuration from both user and project sources (legacy function)
+ */
+export function loadMergedHooksConfig(workdir) {
+    const waveConfig = loadMergedWaveConfig(workdir);
+    return waveConfig?.hooks || null;
 }
 /**
  * Check if hooks configuration exists (user or project)
+ * Checks both .local.json and .json variants
+ * @deprecated Use hasAnyConfig() from configPaths.ts for better functionality
  */
 export function hasHooksConfiguration(workdir) {
-    return (existsSync(getUserHooksConfigPath()) ||
-        existsSync(getProjectHooksConfigPath(workdir)));
+    return hasAnyConfig(workdir);
 }
 /**
  * Get hooks configuration information for debugging
+ * Includes both .local.json and .json variants
+ * @deprecated Use getConfigurationInfo() from configPaths.ts for better functionality
  */
 export function getHooksConfigurationInfo(workdir) {
-    const userPath = getUserHooksConfigPath();
-    const projectPath = getProjectHooksConfigPath(workdir);
-    return {
-        hasUser: existsSync(userPath),
-        hasProject: existsSync(projectPath),
-        paths: [userPath, projectPath],
-    };
+    return getConfigurationInfo(workdir);
 }

package/dist/services/jsonlHandler.d.ts

@@ -0,0 +1,62 @@
+/**
+ * JSONL file operations service
+ * Handles reading and writing JSONL (JSON Lines) session files for improved performance
+ */
+import type { Message } from "../types/index.js";
+import type { SessionMessage, SessionMetadataLine } from "../types/session.js";
+/**
+ * JSONL write options
+ */
+export interface JsonlWriteOptions {
+    atomic?: boolean;
+}
+/**
+ * JSONL handler class for message persistence operations
+ */
+export declare class JsonlHandler {
+    private readonly defaultWriteOptions;
+    constructor();
+    /**
+     * Create a new session file with metadata header
+     */
+    createSession(filePath: string, sessionId: string, workdir: string, sessionType?: "main" | "subagent", parentSessionId?: string, subagentType?: string): Promise<void>;
+    /**
+     * Append a single message to JSONL file
+     */
+    appendMessage(filePath: string, message: Message): Promise<void>;
+    /**
+     * Append multiple messages to JSONL file
+     */
+    appendMessages(filePath: string, messages: Message[]): Promise<void>;
+    /**
+     * Append messages to JSONL file
+     */
+    append(filePath: string, messages: SessionMessage[], options?: JsonlWriteOptions): Promise<void>;
+    /**
+     * Read all messages from JSONL file
+     * Includes metadata handling for backward compatibility
+     */
+    read(filePath: string): Promise<SessionMessage[]>;
+    /**
+     * Get the last message from JSONL file using efficient file reading
+     */
+    getLastMessage(filePath: string): Promise<SessionMessage | null>;
+    /**
+     * Read session metadata from first line (streaming - only reads first line)
+     */
+    readMetadata(filePath: string): Promise<SessionMetadataLine | null>;
+    /**
+     * Check if a session file has metadata (first line check only)
+     * Very efficient - only reads first line
+     */
+    hasMetadata(filePath: string): Promise<boolean>;
+    /**
+     * Validate messages before writing
+     */
+    private validateMessages;
+    /**
+     * Ensure directory exists for the given file path
+     */
+    private ensureDirectory;
+}
+//# sourceMappingURL=jsonlHandler.d.ts.map

package/dist/services/jsonlHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonlHandler.d.ts","sourceRoot":"","sources":["../../src/services/jsonlHandler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAEhC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA8B;;IAQlE;;OAEG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,MAAM,GAAG,UAAmB,EACzC,eAAe,CAAC,EAAE,MAAM,EACxB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAkBhB;;OAEG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAItE;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAc1E;;OAEG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAyChB;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAqDvD;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAwCtE;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAkCzE;;;OAGG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;OAEG;YACW,eAAe;CAU9B"}