@auto-engineer/ai-gateway 0.11.14 → 0.11.16

package/src/core/types.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+export enum AIProvider {
+  OpenAI = 'openai',
+  Anthropic = 'anthropic',
+  Google = 'google',
+  XAI = 'xai',
+  Custom = 'custom',
+}
+
+export interface CustomProviderConfig {
+  name: string;
+  baseUrl: string;
+  apiKey: string;
+  defaultModel: string;
+}
+
+export interface AIConfig {
+  openai?: {
+    apiKey: string;
+  };
+  anthropic?: {
+    apiKey: string;
+  };
+  google?: {
+    apiKey: string;
+  };
+  xai?: {
+    apiKey: string;
+  };
+  custom?: CustomProviderConfig;
+}
+
+export interface AIContext {
+  config: AIConfig;
+  defaultProvider?: AIProvider;
+}
+
+export interface AIOptions {
+  provider?: AIProvider;
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  streamCallback?: (token: string) => void;
+  includeTools?: boolean;
+}
+
+export interface StructuredAIOptions<T> extends Omit<AIOptions, 'streamCallback'> {
+  schema: z.ZodSchema<T>;
+  schemaName?: string;
+  schemaDescription?: string;
+}
+
+export interface StreamStructuredAIOptions<T> extends StructuredAIOptions<T> {
+  onPartialObject?: (partialObject: unknown) => void;
+}
+
+export interface AIToolValidationError extends Error {
+  cause?: {
+    issues?: unknown[];
+    [key: string]: unknown;
+  };
+  issues?: unknown[];
+  errors?: unknown[];
+  zodIssues?: unknown[];
+  validationDetails?: {
+    cause?: {
+      issues?: unknown[];
+    };
+    issues?: unknown[];
+    errors?: unknown[];
+  };
+  schemaDescription?: string;
+  [key: string]: unknown;
+}
+
+export type RegisteredToolForAI = {
+  parameters: z.ZodSchema;
+  description: string;
+  execute?: (args: Record<string, unknown>) => Promise<string>;
+};

package/src/core/utils/errors.ts

@@ -0,0 +1,91 @@
+import { AIProvider } from '../types';
+import { makeLogger } from './log';
+
+const debugError = makeLogger('auto:ai-gateway:error');
+
+const ERROR_PATTERNS = [
+  {
+    patterns: ['rate limit', '429'],
+    statusCode: 429,
+    icon: '⚠️',
+    message: 'RATE LIMIT ERROR detected for %s',
+    checkRetryAfter: true,
+  },
+  {
+    patterns: ['401', 'unauthorized'],
+    statusCode: 401,
+    icon: '🔐',
+    message: 'AUTHENTICATION ERROR - Check your %s API key',
+  },
+  {
+    patterns: ['quota', 'credits', 'insufficient'],
+    icon: '💳',
+    message: 'QUOTA/CREDITS ERROR - Insufficient credits for %s',
+  },
+  {
+    patterns: ['model', 'not found'],
+    icon: '🤖',
+    message: 'MODEL ERROR - Model might not be available for %s',
+  },
+  {
+    patterns: ['timeout', 'timed out'],
+    icon: '⏱️',
+    message: 'TIMEOUT ERROR - Request timed out for %s',
+  },
+  {
+    patterns: ['ECONNREFUSED', 'ENOTFOUND', 'network'],
+    icon: '🌐',
+    message: 'NETWORK ERROR - Connection failed to %s',
+  },
+];
+
+function checkErrorType(message: string, errorAny: Record<string, unknown>, provider: AIProvider): void {
+  for (const errorType of ERROR_PATTERNS) {
+    const hasPattern = errorType.patterns.some((pattern) => message.includes(pattern));
+    const hasStatusCode = errorType.statusCode !== undefined && errorAny.status === errorType.statusCode;
+
+    if (hasPattern || hasStatusCode) {
+      debugError(`${errorType.icon} ${errorType.message}`, provider);
+
+      if (errorType.checkRetryAfter === true && errorAny.retryAfter !== undefined) {
+        debugError('Retry after: %s seconds', String(errorAny.retryAfter));
+      }
+      return;
+    }
+  }
+}
+
+function extractErrorDetails(errorAny: Record<string, unknown>): void {
+  if (errorAny.response !== undefined && typeof errorAny.response === 'object' && errorAny.response !== null) {
+    const response = errorAny.response as Record<string, unknown>;
+    debugError('Response status: %s', String(response.status ?? 'unknown'));
+    debugError('Response status text: %s', String(response.statusText ?? 'unknown'));
+    if (response.data !== undefined) {
+      debugError('Response data: %o', response.data);
+    }
+  }
+
+  if (errorAny.code !== undefined) {
+    debugError('Error code: %s', String(errorAny.code));
+  }
+
+  if (errorAny.type !== undefined) {
+    debugError('Error type: %s', String(errorAny.type));
+  }
+}
+
+export function extractAndLogError(error: unknown, provider: AIProvider, operation: string): void {
+  debugError('%s failed for provider %s', operation, provider);
+
+  if (error instanceof Error) {
+    debugError('Error message: %s', error.message);
+    debugError('Error name: %s', error.name);
+    debugError('Error stack: %s', error.stack);
+    const errorAny = error as unknown as Record<string, unknown>;
+    checkErrorType(error.message, errorAny, provider);
+    extractErrorDetails(errorAny);
+    debugError('Full error object: %O', error);
+  } else {
+    debugError('Unknown error type: %O', error);
+  }
+}

package/src/core/utils/log.ts

@@ -0,0 +1,65 @@
+export type Logger = (...args: unknown[]) => void;
+
+type DebugFactory = (ns: string) => Logger;
+
+interface ProcessVersions {
+  node?: string;
+}
+interface NodeProcess {
+  versions?: ProcessVersions;
+}
+
+let debugFactory: DebugFactory | null | undefined = undefined;
+let debugPromise: Promise<void> | null = null;
+
+function isNodeEnvironment(): boolean {
+  if (typeof process === 'undefined') return false;
+  const proc = process as NodeProcess;
+  return Boolean(proc.versions?.node);
+}
+
+function loadDebug(): Promise<void> {
+  if (!isNodeEnvironment()) {
+    debugFactory = null; // permanent no-op on edge
+    return Promise.resolve();
+  }
+  if (debugPromise) return debugPromise;
+
+  debugPromise = import('debug')
+    .then((mod) => {
+      const imported = mod as { default?: DebugFactory } | DebugFactory;
+      debugFactory = typeof imported === 'function' ? imported : (imported.default ?? null);
+    })
+    .catch(() => {
+      debugFactory = null;
+    });
+
+  return debugPromise;
+}
+
+export function makeLogger(ns: string): Logger {
+  const queue: unknown[][] = [];
+  let impl: Logger | null = null;
+  const MAX_BUFFERED = 100;
+
+  const logger: Logger = (...args: unknown[]) => {
+    if (impl) {
+      impl(...args);
+    } else if (queue.length < MAX_BUFFERED) {
+      queue.push(args);
+    }
+  };
+
+  void loadDebug().then(() => {
+    try {
+      impl = debugFactory ? debugFactory(ns) : () => {};
+    } catch {
+      impl = () => {};
+    }
+    // flush any buffered logs
+    for (const args of queue) impl(...args);
+    queue.length = 0;
+  });
+
+  return logger;
+}

package/src/core/utils/validation.ts

@@ -0,0 +1,69 @@
+import { AIToolValidationError } from '../types';
+import { makeLogger } from './log';
+
+const debugValidation = makeLogger('auto:ai-gateway:validation');
+
+export function getEnhancedPrompt(prompt: string, lastError: AIToolValidationError): string {
+  const errorDetails = lastError.zodIssues
+    ? JSON.stringify(lastError.zodIssues, null, 2)
+    : lastError.validationDetails?.cause?.issues
+      ? JSON.stringify(lastError.validationDetails.cause.issues, null, 2)
+      : lastError.message;
+
+  debugValidation('Enhancing prompt with validation error details: %o', errorDetails);
+  return `${prompt}\n\n⚠️ IMPORTANT: Your previous response failed validation with the following errors:\n${errorDetails}\n\nPlease fix these errors and ensure your response EXACTLY matches the required schema structure.`;
+}
+
+export function isSchemaError(error: Error): boolean {
+  return (
+    error.message.includes('response did not match schema') ||
+    error.message.includes('TypeValidationError') ||
+    error.name === 'AI_TypeValidationError'
+  );
+}
+
+export function enhanceValidationError(error: AIToolValidationError): AIToolValidationError {
+  const enhancedError = new Error(error.message) as AIToolValidationError;
+  Object.assign(enhancedError, error);
+
+  if (error.cause !== undefined || error.issues !== undefined || error.errors !== undefined) {
+    enhancedError.validationDetails = {
+      cause: error.cause,
+      issues: error.issues,
+      errors: error.errors,
+    };
+  }
+
+  if (
+    error.message.includes('response did not match schema') &&
+    'cause' in error &&
+    typeof error.cause === 'object' &&
+    error.cause !== null &&
+    'issues' in error.cause
+  ) {
+    enhancedError.zodIssues = error.cause.issues as unknown[];
+  }
+  return enhancedError;
+}
+
+export function handleFailedRequest(
+  lastError: AIToolValidationError | undefined,
+  maxRetries: number,
+  attempt: number,
+): { shouldRetry: boolean; enhancedError?: AIToolValidationError } {
+  if (!lastError || !isSchemaError(lastError) || attempt >= maxRetries - 1) {
+    debugValidation(
+      'Not retrying - isLastError: %s, isSchemaError: %s, attempt: %d/%d',
+      !!lastError,
+      lastError ? isSchemaError(lastError) : false,
+      attempt + 1,
+      maxRetries,
+    );
+    return { shouldRetry: false, enhancedError: lastError };
+  }
+
+  debugValidation('Schema validation failed on attempt %d/%d, will retry', attempt + 1, maxRetries);
+  const enhancedError = enhanceValidationError(lastError);
+
+  return { shouldRetry: true, enhancedError };
+}

package/src/index-custom.specs.ts

@@ -1,14 +1,14 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { AIProvider } from './constants';
-import { getAvailableProviders, getDefaultModel, getDefaultAIProvider } from './index';
+import { AIProvider } from './core/types';
+import { getAvailableProviders, getDefaultModel, getDefaultAIProvider, resetGlobalContext } from './index';
 
 // Mock the config module
-vi.mock('./config', () => ({
+vi.mock('./node/config', () => ({
   configureAIProvider: vi.fn(),
 }));
 
 // Mock the custom provider
-vi.mock('./providers/custom', () => ({
+vi.mock('./core/providers/custom', () => ({
   createCustomProvider: vi.fn(() => ({
     languageModel: vi.fn(),
   })),
@@ -21,15 +21,17 @@ describe('Index Integration with Custom Providers', () => {
     vi.resetModules();
     process.env = { ...originalEnv };
     vi.clearAllMocks();
+    resetGlobalContext();
   });
 
   afterEach(() => {
     process.env = originalEnv;
+    resetGlobalContext();
   });
 
   describe('getAvailableProviders', () => {
     it('should include custom provider when configured', async () => {
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         custom: {
           name: 'litellm',
@@ -47,7 +49,7 @@ describe('Index Integration with Custom Providers', () => {
     });
 
     it('should not include custom provider when not configured', async () => {
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         anthropic: { apiKey: 'sk-anthropic' },
       });
@@ -59,7 +61,7 @@ describe('Index Integration with Custom Providers', () => {
     });
 
     it('should handle multiple providers including custom', async () => {
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         openai: { apiKey: 'sk-openai' },
         anthropic: { apiKey: 'sk-anthropic' },
@@ -86,7 +88,7 @@ describe('Index Integration with Custom Providers', () => {
 
   describe('getDefaultModel', () => {
     it('should return custom provider default model when provider is Custom', async () => {
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         custom: {
           name: 'litellm',
@@ -101,7 +103,7 @@ describe('Index Integration with Custom Providers', () => {
     });
 
     it('should throw error when custom provider not configured but requested', async () => {
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         anthropic: { apiKey: 'sk-anthropic' },
       });
@@ -112,7 +114,7 @@ describe('Index Integration with Custom Providers', () => {
     it('should use environment variable DEFAULT_AI_MODEL for custom provider', async () => {
       process.env.DEFAULT_AI_MODEL = 'env-override-model';
 
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         custom: {
           name: 'custom',
@@ -129,9 +131,10 @@ describe('Index Integration with Custom Providers', () => {
     it('should handle different custom provider models', async () => {
       const testCases = ['gpt-4o', 'claude-3-opus', 'llama3.1:70b', 'mistral-large', 'gemini-1.5-pro'];
 
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
 
       testCases.forEach((testModel) => {
+        resetGlobalContext();
         vi.mocked(configureAIProvider).mockReturnValue({
           custom: {
             name: 'test',
@@ -151,7 +154,7 @@ describe('Index Integration with Custom Providers', () => {
     it('should use custom provider as fallback when available', async () => {
       process.env.DEFAULT_AI_PROVIDER = 'nonexistent';
 
-      const { configureAIProvider } = await import('./config');
+      const { configureAIProvider } = await import('./node/config');
       vi.mocked(configureAIProvider).mockReturnValue({
         custom: {
           name: 'custom',
@@ -183,6 +186,7 @@ describe('Index Integration with Custom Providers', () => {
       ];
 
       testCases.forEach(({ env, expected }) => {
+        resetGlobalContext();
         process.env.DEFAULT_AI_PROVIDER = env;
         const provider = getDefaultAIProvider();
         expect(provider).toBe(expected);

package/src/index.specs.ts

@@ -1,10 +1,11 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { getAvailableProviders, getDefaultAIProvider, getDefaultModel } from './index';
-import { DEFAULT_MODELS, AIProvider } from './constants';
-import type { AIConfig } from './config';
+import { getAvailableProviders, getDefaultAIProvider, getDefaultModel, resetGlobalContext } from './index';
+import { DEFAULT_MODELS } from './core/constants';
+import { AIProvider } from './core/types';
+import type { AIConfig } from './core/types';
 
 // Mock the config module
-vi.mock('./config', () => ({
+vi.mock('./node/config', () => ({
   configureAIProvider: vi.fn(
     () =>
       ({
@@ -22,6 +23,7 @@ describe('Provider Selection Logic', () => {
 
     beforeEach(() => {
       originalProvider = process.env.DEFAULT_AI_PROVIDER;
+      resetGlobalContext();
     });
 
     afterEach(() => {
@@ -30,6 +32,7 @@ describe('Provider Selection Logic', () => {
       } else {
         delete process.env.DEFAULT_AI_PROVIDER;
       }
+      resetGlobalContext();
     });
 
     it('should respect DEFAULT_AI_PROVIDER environment variable when set to anthropic', () => {