wave-agent-sdk 0.0.1 → 0.0.2

package/dist/utils/configValidator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Configuration validator utilities for Agent Constructor Configuration
+ * Validates configuration values for correctness and security
+ */
+import { GatewayConfig } from "../types.js";
+export declare class ConfigValidator {
+    /**
+     * Validates gateway configuration
+     * @param config - Configuration to validate
+     * @throws ConfigurationError with descriptive message if invalid
+     */
+    static validateGatewayConfig(config: GatewayConfig): void;
+    /**
+     * Validates token limit value
+     * @param tokenLimit - Token limit to validate
+     * @throws ConfigurationError if invalid
+     */
+    static validateTokenLimit(tokenLimit: number): void;
+    /**
+     * 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;
+}
+/**
+ * Static configuration validator instance
+ * Implements ConfigurationValidator interface from types.ts
+ */
+export declare const configValidator: {
+    validateGatewayConfig: typeof ConfigValidator.validateGatewayConfig;
+    validateTokenLimit: typeof ConfigValidator.validateTokenLimit;
+    validateModelConfig: typeof ConfigValidator.validateModelConfig;
+};
+//# sourceMappingURL=configValidator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configValidator.d.ts","sourceRoot":"","sources":["../../src/utils/configValidator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAqC,MAAM,aAAa,CAAC;AAE/E,qBAAa,eAAe;IAC1B;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IA+CzD;;;;OAIG;IACH,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IA0BnD;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAyBxE;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;CAI3B,CAAC"}

package/dist/utils/configValidator.js

@@ -0,0 +1,78 @@
+/**
+ * Configuration validator utilities for Agent Constructor Configuration
+ * Validates configuration values for correctness and security
+ */
+import { 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) {
+        // 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) {
+        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, fastModel) {
+        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/dist/utils/constants.d.ts

@@ -22,6 +22,16 @@ export declare const USER_MEMORY_FILE: string;
  * AI related constants
  */
 export declare const DEFAULT_TOKEN_LIMIT = 64000;
+/**
+ * @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 declare const FAST_MODEL_ID: string;
+/**
+ * @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 declare const AGENT_MODEL_ID: string;
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAmC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAA0C,CAAC;AAE3E;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAA8C,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,eAAO,MAAM,aAAa,QAAoD,CAAC;AAE/E,eAAO,MAAM,cAAc,QAC2B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAmC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAA0C,CAAC;AAE3E;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAA8C,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAoD,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAC2B,CAAC"}

package/dist/utils/constants.js

@@ -24,5 +24,15 @@ export const USER_MEMORY_FILE = path.join(DATA_DIRECTORY, "user-memory.md");
  * AI related constants
  */
 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -18,18 +18,6 @@
     "src",
     "README.md"
   ],
-  "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",
-    "test": "vitest run",
-    "lint": "eslint --cache",
-    "format": "prettier --write .",
-    "release:patch": "pnpm version patch && npm publish",
-    "release:minor": "pnpm version minor && npm publish",
-    "release:major": "pnpm version major && npm publish",
-    "prepublishOnly": "npm run build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.18.2",
     "@vscode/ripgrep": "^1.15.14",
@@ -47,5 +35,13 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "license": "MIT"
-}
+  "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",
+    "test": "vitest run",
+    "lint": "eslint --cache",
+    "format": "prettier --write ."
+  }
+}

package/src/agent.ts

@@ -13,10 +13,32 @@ import {
 } from "./managers/backgroundBashManager.js";
 import { SlashCommandManager } from "./managers/slashCommandManager.js";
 import type { SlashCommand, CustomSlashCommand } from "./types.js";
-import type { Message, Logger, McpServerStatus } from "./types.js";
+import type {
+  Message,
+  Logger,
+  McpServerStatus,
+  GatewayConfig,
+  ModelConfig,
+} from "./types.js";
 import { HookManager } from "./hooks/index.js";
-
+import { configResolver } from "./utils/configResolver.js";
+import { configValidator } from "./utils/configValidator.js";
+
+/**
+ * Configuration options for Agent instances
+ *
+ * IMPORTANT: This interface is used by both Agent constructor and Agent.create()
+ * Any changes to this interface must be compatible with both methods.
+ */
 export interface AgentOptions {
+  // Optional configuration with environment fallbacks
+  apiKey?: string;
+  baseURL?: string;
+  agentModel?: string;
+  fastModel?: string;
+  tokenLimit?: number;
+
+  // Existing options (preserved)
   callbacks?: AgentCallbacks;
   restoreSessionId?: string;
   continueLastSession?: boolean;
@@ -49,14 +71,51 @@ export class Agent {
   private workdir: string; // Working directory
   private systemPrompt?: string; // Custom system prompt
 
-  // Private constructor to prevent direct instantiation
-  private constructor(options: AgentOptions) {
+  // Configuration properties
+  private gatewayConfig: GatewayConfig;
+  private modelConfig: ModelConfig;
+  private tokenLimit: number;
+
+  /**
+   * Agent constructor - handles configuration resolution and validation
+   *
+   * IMPORTANT: Keep this constructor's signature exactly the same as Agent.create()
+   * to maintain API consistency. Both methods should accept the same AgentOptions.
+   *
+   * @param options - Configuration options for the Agent instance
+   */
+  constructor(options: AgentOptions) {
     const { callbacks = {}, logger, workdir, systemPrompt } = options;
 
+    // Resolve configuration from constructor args and environment variables
+    const gatewayConfig = configResolver.resolveGatewayConfig(
+      options.apiKey,
+      options.baseURL,
+    );
+    const modelConfig = configResolver.resolveModelConfig(
+      options.agentModel,
+      options.fastModel,
+    );
+    const tokenLimit = configResolver.resolveTokenLimit(options.tokenLimit);
+
+    // Validate resolved configuration
+    configValidator.validateGatewayConfig(gatewayConfig);
+    configValidator.validateTokenLimit(tokenLimit);
+    configValidator.validateModelConfig(
+      modelConfig.agentModel,
+      modelConfig.fastModel,
+    );
+
     this.callbacks = callbacks;
     this.logger = logger; // Save the passed logger
     this.workdir = workdir || process.cwd(); // Set working directory, default to current working directory
     this.systemPrompt = systemPrompt; // Save custom system prompt
+
+    // Store resolved configuration
+    this.gatewayConfig = gatewayConfig;
+    this.modelConfig = modelConfig;
+    this.tokenLimit = tokenLimit;
+
     this.backgroundBashManager = new BackgroundBashManager({
       callbacks,
       workdir: this.workdir,
@@ -77,7 +136,7 @@ export class Agent {
       logger: this.logger,
     });
 
-    // Initialize AI manager
+    // Initialize AI manager with resolved configuration
     this.aiManager = new AIManager({
       messageManager: this.messageManager,
       toolManager: this.toolManager,
@@ -87,6 +146,9 @@ export class Agent {
       callbacks,
       workdir: this.workdir,
       systemPrompt: this.systemPrompt,
+      gatewayConfig: this.gatewayConfig,
+      modelConfig: this.modelConfig,
+      tokenLimit: this.tokenLimit,
     });
 
     // Initialize command manager
@@ -154,8 +216,17 @@ export class Agent {
     return this.backgroundBashManager.killShell(id);
   }
 
-  /** Static async factory method */
+  /**
+   * Static async factory method for creating Agent instances
+   *
+   * IMPORTANT: Keep this method's signature exactly the same as the constructor
+   * to maintain consistency and avoid confusion for users of the API.
+   *
+   * @param options - Same AgentOptions interface used by constructor
+   * @returns Promise<Agent> - Fully initialized Agent instance
+   */
   static async create(options: AgentOptions): Promise<Agent> {
+    // Create Agent instance - configuration resolution and validation now happens in constructor
     const instance = new Agent(options);
     await instance.initialize({
       restoreSessionId: options.restoreSessionId,

package/src/managers/aiManager.ts

@@ -2,12 +2,11 @@ import { callAgent, compressMessages } from "../services/aiService.js";
 import { getMessagesToCompress } from "../utils/messageOperations.js";
 import { convertMessagesForAPI } from "../utils/convertMessagesForAPI.js";
 import * as memory from "../services/memory.js";
-import type { Logger } from "../types.js";
+import type { Logger, GatewayConfig, ModelConfig } from "../types.js";
 import type { ToolManager } from "./toolManager.js";
 import type { ToolContext, ToolResult } from "../tools/types.js";
 import type { MessageManager } from "./messageManager.js";
 import type { BackgroundBashManager } from "./backgroundBashManager.js";
-import { DEFAULT_TOKEN_LIMIT } from "../utils/constants.js";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
 import type { HookManager } from "../hooks/index.js";
 import type { ExtendedHookExecutionContext } from "../hooks/types.js";
@@ -25,6 +24,10 @@ export interface AIManagerOptions {
   callbacks?: AIManagerCallbacks;
   workdir: string;
   systemPrompt?: string;
+  // Resolved configuration
+  gatewayConfig: GatewayConfig;
+  modelConfig: ModelConfig;
+  tokenLimit: number;
 }
 
 export class AIManager {
@@ -39,6 +42,11 @@ export class AIManager {
   private workdir: string;
   private systemPrompt?: string;
 
+  // Configuration properties
+  private gatewayConfig: GatewayConfig;
+  private modelConfig: ModelConfig;
+  private tokenLimit: number;
+
   constructor(options: AIManagerOptions) {
     this.messageManager = options.messageManager;
     this.toolManager = options.toolManager;
@@ -48,6 +56,11 @@ export class AIManager {
     this.workdir = options.workdir;
     this.systemPrompt = options.systemPrompt;
     this.callbacks = options.callbacks ?? {};
+
+    // Store resolved configuration
+    this.gatewayConfig = options.gatewayConfig;
+    this.modelConfig = options.modelConfig;
+    this.tokenLimit = options.tokenLimit;
   }
 
   private isCompressing: boolean = false;
@@ -125,15 +138,10 @@ export class AIManager {
     // Update token statistics - display latest token usage
     this.messageManager.setlatestTotalTokens(usage.total_tokens);
 
-    // Check if token limit exceeded
-    const tokenLimit = parseInt(
-      process.env.TOKEN_LIMIT || `${DEFAULT_TOKEN_LIMIT}`,
-      10,
-    );
-
-    if (usage.total_tokens > tokenLimit) {
+    // Check if token limit exceeded - use injected configuration
+    if (usage.total_tokens > this.tokenLimit) {
       this.logger?.info(
-        `Token usage exceeded ${tokenLimit}, compressing messages...`,
+        `Token usage exceeded ${this.tokenLimit}, compressing messages...`,
       );
 
       // Check if messages need compression
@@ -149,6 +157,8 @@ export class AIManager {
         this.setIsCompressing(true);
         try {
           const compressedContent = await compressMessages({
+            gatewayConfig: this.gatewayConfig,
+            modelConfig: this.modelConfig,
             messages: recentChatMessages,
             abortSignal: abortController.signal,
           });
@@ -221,6 +231,8 @@ export class AIManager {
 
       // Call AI service (non-streaming)
       const result = await callAgent({
+        gatewayConfig: this.gatewayConfig,
+        modelConfig: this.modelConfig,
         messages: recentMessages,
         sessionId: this.messageManager.getSessionId(),
         abortSignal: abortController.signal,
@@ -432,11 +444,14 @@ export class AIManager {
       if (recursionDepth === 0) {
         this.setIsLoading(false);
 
-        // Save session before executing Stop hooks
-        await this.messageManager.saveSession();
+        // Save session and execute Stop hooks in parallel but maintain order
+        (async () => {
+          // Save session before executing Stop hooks
+          await this.messageManager.saveSession();
 
-        // Execute Stop hooks when AI response cycle completes
-        await this.executeStopHooks();
+          // Execute Stop hooks when AI response cycle completes
+          await this.executeStopHooks();
+        })();
       }
     }
   }

package/src/services/aiService.ts

@@ -5,12 +5,15 @@ import {
   ChatCompletionMessageParam,
   ChatCompletionFunctionTool,
 } from "openai/resources.js";
-import { FAST_MODEL_ID, AGENT_MODEL_ID } from "@/utils/constants.js";
+import type { GatewayConfig, ModelConfig } from "../types.js";
 
 /**
- * Model configuration type, based on OpenAI parameters but excluding messages
+ * OpenAI model configuration type, based on OpenAI parameters but excluding messages
  */
-type ModelConfig = Omit<ChatCompletionCreateParamsNonStreaming, "messages">;
+type OpenAIModelConfig = Omit<
+  ChatCompletionCreateParamsNonStreaming,
+  "messages"
+>;
 
 /**
  * Get specific configuration parameters based on model name
@@ -20,9 +23,9 @@ type ModelConfig = Omit<ChatCompletionCreateParamsNonStreaming, "messages">;
  */
 function getModelConfig(
   modelName: string,
-  baseConfig: Partial<ModelConfig> = {},
-): ModelConfig {
-  const config: ModelConfig = {
+  baseConfig: Partial<OpenAIModelConfig> = {},
+): OpenAIModelConfig {
+  const config: OpenAIModelConfig = {
     model: modelName,
     stream: false,
     ...baseConfig,
@@ -37,13 +40,12 @@ function getModelConfig(
   return config;
 }
 
-// Initialize OpenAI client with environment variables
-const openai = new OpenAI({
-  apiKey: process.env.AIGW_TOKEN,
-  baseURL: process.env.AIGW_URL,
-});
-
 export interface CallAgentOptions {
+  // Resolved configuration
+  gatewayConfig: GatewayConfig;
+  modelConfig: ModelConfig;
+
+  // Existing parameters (preserved)
   messages: ChatCompletionMessageParam[];
   sessionId?: string;
   abortSignal?: AbortSignal;
@@ -67,10 +69,25 @@ export interface CallAgentResult {
 export async function callAgent(
   options: CallAgentOptions,
 ): Promise<CallAgentResult> {
-  const { messages, abortSignal, memory, workdir, tools, model, systemPrompt } =
-    options;
+  const {
+    gatewayConfig,
+    modelConfig,
+    messages,
+    abortSignal,
+    memory,
+    workdir,
+    tools,
+    model,
+    systemPrompt,
+  } = options;
 
   try {
+    // Create OpenAI client with injected configuration
+    const openai = new OpenAI({
+      apiKey: gatewayConfig.apiKey,
+      baseURL: gatewayConfig.baseURL,
+    });
+
     // Build system prompt content
     let systemContent: string;
 
@@ -101,15 +118,15 @@ ${workdir}
     const openaiMessages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] =
       [systemMessage, ...messages];
 
-    // Get model configuration
-    const modelConfig = getModelConfig(model || AGENT_MODEL_ID, {
+    // Get model configuration - use injected modelConfig with optional override
+    const openaiModelConfig = getModelConfig(model || modelConfig.agentModel, {
       temperature: 0,
       max_completion_tokens: 32768,
     });
 
     // Prepare API call parameters
     const createParams: ChatCompletionCreateParamsNonStreaming = {
-      ...modelConfig,
+      ...openaiModelConfig,
       messages: openaiMessages,
     };
 
@@ -160,6 +177,11 @@ ${workdir}
 }
 
 export interface CompressMessagesOptions {
+  // Resolved configuration
+  gatewayConfig: GatewayConfig;
+  modelConfig: ModelConfig;
+
+  // Existing parameters
   messages: ChatCompletionMessageParam[];
   abortSignal?: AbortSignal;
 }
@@ -167,10 +189,16 @@ export interface CompressMessagesOptions {
 export async function compressMessages(
   options: CompressMessagesOptions,
 ): Promise<string> {
-  const { messages, abortSignal } = options;
+  const { gatewayConfig, modelConfig, messages, abortSignal } = options;
+
+  // Create OpenAI client with injected configuration
+  const openai = new OpenAI({
+    apiKey: gatewayConfig.apiKey,
+    baseURL: gatewayConfig.baseURL,
+  });
 
-  // Get model configuration
-  const modelConfig = getModelConfig(FAST_MODEL_ID, {
+  // Get model configuration - use injected fast model
+  const openaiModelConfig = getModelConfig(modelConfig.fastModel, {
     temperature: 0.1,
     max_tokens: 1500,
   });
@@ -178,7 +206,7 @@ export async function compressMessages(
   try {
     const response = await openai.chat.completions.create(
       {
-        ...modelConfig,
+        ...openaiModelConfig,
         messages: [
           {
             role: "system",

package/src/services/session.ts

@@ -76,6 +76,11 @@ export async function saveSession(
     return;
   }
 
+  // Do not save if there are no messages
+  if (messages.length === 0) {
+    return;
+  }
+
   await ensureSessionDir();
 
   // Filter out diff blocks before saving

package/src/types.ts

@@ -258,3 +258,78 @@ export const SKILL_DEFAULTS = {
   SCAN_TIMEOUT: 5000,
   LOAD_TIMEOUT: 2000,
 } as const;
+
+// Configuration types for Agent Constructor Configuration feature
+export interface GatewayConfig {
+  apiKey: string;
+  baseURL: string;
+}
+
+export interface ModelConfig {
+  agentModel: string;
+  fastModel: string;
+}
+
+export interface ConfigurationResolver {
+  /**
+   * 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 Error if required configuration is missing after fallbacks
+   */
+  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
+   */
+  resolveModelConfig(agentModel?: string, fastModel?: string): ModelConfig;
+
+  /**
+   * Resolves token limit with fallbacks
+   * @param constructorLimit - Token limit from constructor (optional)
+   * @returns Resolved token limit
+   */
+  resolveTokenLimit(constructorLimit?: number): number;
+}
+
+export interface ConfigurationValidator {
+  /**
+   * Validates gateway configuration
+   * @param config - Configuration to validate
+   * @throws Error with descriptive message if invalid
+   */
+  validateGatewayConfig(config: GatewayConfig): void;
+
+  /**
+   * Validates token limit value
+   * @param tokenLimit - Token limit to validate
+   * @throws Error if invalid
+   */
+  validateTokenLimit(tokenLimit: number): void;
+}
+
+export class ConfigurationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly provided?: unknown,
+  ) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+}
+
+// Standard error messages
+export const CONFIG_ERRORS = {
+  MISSING_API_KEY:
+    "Gateway configuration requires apiKey. Provide via constructor or AIGW_TOKEN environment variable.",
+  MISSING_BASE_URL:
+    "Gateway configuration requires baseURL. Provide via constructor or AIGW_URL environment variable.",
+  INVALID_TOKEN_LIMIT: "Token limit must be a positive integer.",
+  EMPTY_API_KEY: "API key cannot be empty string.",
+  EMPTY_BASE_URL: "Base URL cannot be empty string.",
+} as const;