wave-agent-sdk 0.0.1 → 0.0.2

package/src/utils/configResolver.ts

@@ -0,0 +1,142 @@
+/**
+ * Configuration resolver utilities for Agent Constructor Configuration
+ * Resolves configuration from constructor arguments with environment fallbacks
+ */
+
+import {
+  GatewayConfig,
+  ModelConfig,
+  ConfigurationError,
+  CONFIG_ERRORS,
+} from "../types.js";
+
+export 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 {
+    // Resolve API key: constructor > environment variable
+    // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
+    let resolvedApiKey: string;
+    if (apiKey !== undefined) {
+      resolvedApiKey = apiKey;
+    } else {
+      resolvedApiKey = process.env.AIGW_TOKEN || "";
+    }
+
+    if (!resolvedApiKey && apiKey === undefined) {
+      throw new ConfigurationError(CONFIG_ERRORS.MISSING_API_KEY, "apiKey", {
+        constructor: apiKey,
+        environment: process.env.AIGW_TOKEN,
+      });
+    }
+
+    if (resolvedApiKey.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_API_KEY,
+        "apiKey",
+        resolvedApiKey,
+      );
+    }
+
+    // Resolve base URL: constructor > environment variable
+    // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
+    let resolvedBaseURL: string;
+    if (baseURL !== undefined) {
+      resolvedBaseURL = baseURL;
+    } else {
+      resolvedBaseURL = process.env.AIGW_URL || "";
+    }
+
+    if (!resolvedBaseURL && baseURL === undefined) {
+      throw new ConfigurationError(CONFIG_ERRORS.MISSING_BASE_URL, "baseURL", {
+        constructor: baseURL,
+        environment: process.env.AIGW_URL,
+      });
+    }
+
+    if (resolvedBaseURL.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_BASE_URL,
+        "baseURL",
+        resolvedBaseURL,
+      );
+    }
+
+    return {
+      apiKey: resolvedApiKey,
+      baseURL: resolvedBaseURL,
+    };
+  }
+
+  /**
+   * 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 {
+    // Default values as per data-model.md
+    const DEFAULT_AGENT_MODEL = "claude-sonnet-4-20250514";
+    const DEFAULT_FAST_MODEL = "gemini-2.5-flash";
+
+    // Resolve agent model: constructor > environment > default
+    const resolvedAgentModel =
+      agentModel || process.env.AIGW_MODEL || DEFAULT_AGENT_MODEL;
+
+    // Resolve fast model: constructor > environment > default
+    const resolvedFastModel =
+      fastModel || process.env.AIGW_FAST_MODEL || DEFAULT_FAST_MODEL;
+
+    return {
+      agentModel: resolvedAgentModel,
+      fastModel: resolvedFastModel,
+    };
+  }
+
+  /**
+   * Resolves token limit with fallbacks
+   * @param constructorLimit - Token limit from constructor (optional)
+   * @returns Resolved token limit
+   */
+  static resolveTokenLimit(constructorLimit?: number): number {
+    const DEFAULT_TOKEN_LIMIT = 64000;
+
+    // If constructor value provided, use it
+    if (constructorLimit !== undefined) {
+      return constructorLimit;
+    }
+
+    // Try environment variable
+    const envTokenLimit = process.env.TOKEN_LIMIT;
+    if (envTokenLimit) {
+      const parsed = parseInt(envTokenLimit, 10);
+      if (!isNaN(parsed)) {
+        return parsed;
+      }
+    }
+
+    // Use default
+    return DEFAULT_TOKEN_LIMIT;
+  }
+}
+
+/**
+ * Static configuration resolver instance
+ * Implements ConfigurationResolver interface from types.ts
+ */
+export const configResolver = {
+  resolveGatewayConfig: ConfigResolver.resolveGatewayConfig,
+  resolveModelConfig: ConfigResolver.resolveModelConfig,
+  resolveTokenLimit: ConfigResolver.resolveTokenLimit,
+};

package/src/utils/configValidator.ts

@@ -0,0 +1,133 @@
+/**
+ * Configuration validator utilities for Agent Constructor Configuration
+ * Validates configuration values for correctness and security
+ */
+
+import { GatewayConfig, ConfigurationError, CONFIG_ERRORS } from "../types.js";
+
+export class ConfigValidator {
+  /**
+   * Validates gateway configuration
+   * @param config - Configuration to validate
+   * @throws ConfigurationError with descriptive message if invalid
+   */
+  static validateGatewayConfig(config: GatewayConfig): void {
+    // Validate API key
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_API_KEY,
+        "apiKey",
+        config.apiKey,
+      );
+    }
+
+    if (config.apiKey.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_API_KEY,
+        "apiKey",
+        config.apiKey,
+      );
+    }
+
+    // Validate base URL
+    if (!config.baseURL || typeof config.baseURL !== "string") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_BASE_URL,
+        "baseURL",
+        config.baseURL,
+      );
+    }
+
+    if (config.baseURL.trim() === "") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.EMPTY_BASE_URL,
+        "baseURL",
+        config.baseURL,
+      );
+    }
+
+    // Basic URL format validation
+    try {
+      new URL(config.baseURL);
+    } catch {
+      throw new ConfigurationError(
+        `Base URL must be a valid URL format. Received: ${config.baseURL}`,
+        "baseURL",
+        config.baseURL,
+      );
+    }
+  }
+
+  /**
+   * Validates token limit value
+   * @param tokenLimit - Token limit to validate
+   * @throws ConfigurationError if invalid
+   */
+  static validateTokenLimit(tokenLimit: number): void {
+    if (typeof tokenLimit !== "number") {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.INVALID_TOKEN_LIMIT,
+        "tokenLimit",
+        tokenLimit,
+      );
+    }
+
+    if (!Number.isInteger(tokenLimit)) {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.INVALID_TOKEN_LIMIT,
+        "tokenLimit",
+        tokenLimit,
+      );
+    }
+
+    if (tokenLimit <= 0) {
+      throw new ConfigurationError(
+        CONFIG_ERRORS.INVALID_TOKEN_LIMIT,
+        "tokenLimit",
+        tokenLimit,
+      );
+    }
+  }
+
+  /**
+   * Validates model configuration (basic validation)
+   * @param agentModel - Agent model string
+   * @param fastModel - Fast model string
+   * @throws ConfigurationError if invalid
+   */
+  static validateModelConfig(agentModel: string, fastModel: string): void {
+    if (
+      !agentModel ||
+      typeof agentModel !== "string" ||
+      agentModel.trim() === ""
+    ) {
+      throw new ConfigurationError(
+        "Agent model must be a non-empty string.",
+        "agentModel",
+        agentModel,
+      );
+    }
+
+    if (
+      !fastModel ||
+      typeof fastModel !== "string" ||
+      fastModel.trim() === ""
+    ) {
+      throw new ConfigurationError(
+        "Fast model must be a non-empty string.",
+        "fastModel",
+        fastModel,
+      );
+    }
+  }
+}
+
+/**
+ * Static configuration validator instance
+ * Implements ConfigurationValidator interface from types.ts
+ */
+export const configValidator = {
+  validateGatewayConfig: ConfigValidator.validateGatewayConfig,
+  validateTokenLimit: ConfigValidator.validateTokenLimit,
+  validateModelConfig: ConfigValidator.validateModelConfig,
+};

package/src/utils/constants.ts

@@ -31,7 +31,17 @@ export const USER_MEMORY_FILE = path.join(DATA_DIRECTORY, "user-memory.md");
  */
 export const DEFAULT_TOKEN_LIMIT = 64000; // Default token limit
 
+/**
+ * @deprecated These constants are now legacy. Use ModelConfig through Agent constructor instead.
+ * They are maintained for backward compatibility with existing code that might still reference them,
+ * but the actual AI services now use configuration injection.
+ */
 export const FAST_MODEL_ID = process.env.AIGW_FAST_MODEL || "gemini-2.5-flash";
 
+/**
+ * @deprecated These constants are now legacy. Use ModelConfig through Agent constructor instead.
+ * They are maintained for backward compatibility with existing code that might still reference them,
+ * but the actual AI services now use configuration injection.
+ */
 export const AGENT_MODEL_ID =
   process.env.AIGW_MODEL || "claude-sonnet-4-20250514";