@defai.digital/provider-adapters 13.0.3

package/dist/resilient-registry.js

@@ -0,0 +1,296 @@
+/**
+ * Resilient Provider Registry
+ *
+ * Wraps the provider registry with production-grade resilience patterns:
+ * - Circuit Breaker: Prevents cascade failures
+ * - Rate Limiter: Prevents API limit violations
+ * - Metrics: Records request metrics for observability
+ */
+import { createProviderRegistry as createBaseRegistry } from './registry.js';
+import { createCircuitBreaker, createRateLimiter, createMetricsCollector, } from '@defai.digital/resilience-domain';
+import { CIRCUIT_FAILURE_THRESHOLD, CIRCUIT_RESET_TIMEOUT, CIRCUIT_FAILURE_WINDOW, CIRCUIT_QUEUE_TIMEOUT, RATE_LIMIT_RPM_DEFAULT, RETRY_DELAY_DEFAULT, } from '@defai.digital/contracts';
+const DEFAULT_CONFIG = {
+    circuitBreaker: {
+        failureThreshold: CIRCUIT_FAILURE_THRESHOLD,
+        resetTimeoutMs: CIRCUIT_RESET_TIMEOUT,
+        halfOpenMaxAttempts: 1,
+        failureWindowMs: CIRCUIT_FAILURE_WINDOW,
+    },
+    rateLimiter: {
+        requestsPerMinute: RATE_LIMIT_RPM_DEFAULT,
+        maxQueueSize: 100,
+        queueTimeoutMs: CIRCUIT_QUEUE_TIMEOUT,
+        burstMultiplier: 1.5,
+    },
+    enableMetrics: true,
+};
+/**
+ * Resilient provider registry that wraps calls with circuit breaker and rate limiting
+ */
+export class ResilientProviderRegistry {
+    baseRegistry;
+    resilientProviders = new Map();
+    rateLimiter;
+    metrics;
+    config;
+    constructor(baseRegistry, config) {
+        this.baseRegistry = baseRegistry;
+        // Deep merge config to preserve nested defaults
+        this.config = {
+            circuitBreaker: {
+                ...DEFAULT_CONFIG.circuitBreaker,
+                ...config?.circuitBreaker,
+            },
+            rateLimiter: {
+                ...DEFAULT_CONFIG.rateLimiter,
+                ...config?.rateLimiter,
+            },
+            enableMetrics: config?.enableMetrics ?? DEFAULT_CONFIG.enableMetrics,
+        };
+        // Create global rate limiter
+        this.rateLimiter = createRateLimiter(this.config.rateLimiter);
+        // Create metrics collector
+        this.metrics = this.config.enableMetrics ? createMetricsCollector() : null;
+        // Initialize circuit breakers for each provider
+        this.initializeProviders();
+    }
+    initializeProviders() {
+        for (const providerId of this.baseRegistry.getProviderIds()) {
+            const provider = this.baseRegistry.get(providerId);
+            if (provider) {
+                this.resilientProviders.set(providerId, {
+                    provider,
+                    circuitBreaker: createCircuitBreaker(this.config.circuitBreaker),
+                });
+            }
+        }
+    }
+    /**
+     * Executes a completion request with resilience patterns
+     */
+    async complete(request) {
+        const startTime = Date.now();
+        const provider = this.baseRegistry.getByModel(request.model);
+        if (provider === undefined) {
+            const error = {
+                category: 'not_found',
+                message: `No provider found for model: ${request.model}`,
+                shouldRetry: false,
+                shouldFallback: true,
+                retryAfterMs: null,
+                originalError: undefined,
+            };
+            return {
+                success: false,
+                requestId: request.requestId,
+                error,
+                latencyMs: 0,
+            };
+        }
+        const resilient = this.resilientProviders.get(provider.providerId);
+        if (!resilient) {
+            // Fallback to direct call if no circuit breaker setup
+            return provider.complete(request);
+        }
+        // Check rate limit
+        const rateLimitResult = await this.rateLimiter.acquire();
+        if (!rateLimitResult.acquired) {
+            const error = {
+                category: 'rate_limit',
+                message: rateLimitResult.reason === 'queue-full'
+                    ? 'Rate limit queue is full'
+                    : rateLimitResult.reason === 'timeout'
+                        ? 'Rate limit queue timeout'
+                        : 'Rate limit exceeded',
+                shouldRetry: true,
+                shouldFallback: false,
+                retryAfterMs: rateLimitResult.retryAfterMs ?? RETRY_DELAY_DEFAULT,
+                originalError: undefined,
+            };
+            return {
+                success: false,
+                requestId: request.requestId,
+                error,
+                latencyMs: Date.now() - startTime,
+            };
+        }
+        // Execute with circuit breaker protection
+        try {
+            const response = await resilient.circuitBreaker.execute(async () => {
+                const result = await provider.complete(request);
+                // Throw error for failed responses that should trip the circuit breaker
+                // This ensures the circuit breaker tracks provider failures, not just exceptions
+                if (!result.success && result.error?.shouldFallback) {
+                    const error = new Error(result.error.message);
+                    error.response = result;
+                    throw error;
+                }
+                return result;
+            });
+            // Record success metrics
+            if (this.metrics && response.success) {
+                this.metrics.recordRequest({
+                    timestamp: new Date().toISOString(),
+                    providerId: provider.providerId,
+                    operation: 'complete',
+                    success: true,
+                    durationMs: response.latencyMs,
+                    inputTokens: response.usage?.inputTokens,
+                    outputTokens: response.usage?.outputTokens,
+                });
+            }
+            else if (this.metrics && !response.success) {
+                this.metrics.recordRequest({
+                    timestamp: new Date().toISOString(),
+                    providerId: provider.providerId,
+                    operation: 'complete',
+                    success: false,
+                    durationMs: response.latencyMs,
+                    errorCode: response.error?.category,
+                });
+                if (response.error) {
+                    this.metrics.recordError({
+                        timestamp: new Date().toISOString(),
+                        code: response.error.category,
+                        message: response.error.message,
+                        providerId: provider.providerId,
+                        operation: 'complete',
+                        recoverable: response.error.shouldRetry,
+                    });
+                }
+            }
+            return response;
+        }
+        catch (error) {
+            const latencyMs = Date.now() - startTime;
+            // Check if this is a provider failure (has attached response)
+            // We know it's a CompletionFailure because we only throw when success: false
+            const errorWithResponse = error;
+            if (errorWithResponse.response !== undefined && !errorWithResponse.response.success) {
+                // Return the original failed response - circuit breaker already recorded the failure
+                const response = errorWithResponse.response;
+                // Record failure metrics
+                if (this.metrics) {
+                    this.metrics.recordRequest({
+                        timestamp: new Date().toISOString(),
+                        providerId: provider.providerId,
+                        operation: 'complete',
+                        success: false,
+                        durationMs: response.latencyMs,
+                        errorCode: response.error.category,
+                    });
+                    this.metrics.recordError({
+                        timestamp: new Date().toISOString(),
+                        code: response.error.category,
+                        message: response.error.message,
+                        providerId: provider.providerId,
+                        operation: 'complete',
+                        recoverable: response.error.shouldRetry,
+                    });
+                }
+                return response;
+            }
+            // Record failure metrics for circuit breaker errors
+            if (this.metrics) {
+                this.metrics.recordRequest({
+                    timestamp: new Date().toISOString(),
+                    providerId: provider.providerId,
+                    operation: 'complete',
+                    success: false,
+                    durationMs: latencyMs,
+                    errorCode: 'circuit_open',
+                });
+            }
+            // Circuit breaker is open
+            const classifiedError = {
+                category: 'server',
+                message: error instanceof Error ? error.message : 'Circuit breaker is open',
+                shouldRetry: true,
+                shouldFallback: true,
+                retryAfterMs: CIRCUIT_RESET_TIMEOUT,
+                originalError: error instanceof Error ? error : undefined,
+            };
+            return {
+                success: false,
+                requestId: request.requestId,
+                error: classifiedError,
+                latencyMs,
+            };
+        }
+    }
+    /**
+     * Gets provider health status including circuit breaker state
+     */
+    getProviderHealth(providerId) {
+        const resilient = this.resilientProviders.get(providerId);
+        return {
+            provider: resilient?.provider,
+            circuitState: resilient?.circuitBreaker.state,
+        };
+    }
+    /**
+     * Gets metrics snapshot
+     */
+    getMetrics() {
+        return this.metrics?.getStats();
+    }
+    /**
+     * Gets rate limiter stats
+     */
+    getRateLimiterStats() {
+        return this.rateLimiter.getStats();
+    }
+    /**
+     * Resets circuit breaker for a provider
+     */
+    resetCircuitBreaker(providerId) {
+        const resilient = this.resilientProviders.get(providerId);
+        resilient?.circuitBreaker.reset();
+    }
+    /**
+     * Resets all circuit breakers
+     */
+    resetAllCircuitBreakers() {
+        for (const resilient of this.resilientProviders.values()) {
+            resilient.circuitBreaker.reset();
+        }
+    }
+    /**
+     * Checks health of all providers
+     */
+    async checkAllHealth() {
+        return this.baseRegistry.checkAllHealth();
+    }
+    /**
+     * Gets all provider IDs
+     */
+    getProviderIds() {
+        return this.baseRegistry.getProviderIds();
+    }
+    /**
+     * Gets all models
+     */
+    getAllModels() {
+        return this.baseRegistry.getAllModels();
+    }
+    /**
+     * Checks if model exists
+     */
+    hasModel(model) {
+        return this.baseRegistry.hasModel(model);
+    }
+    /**
+     * Gets the underlying base registry
+     */
+    get base() {
+        return this.baseRegistry;
+    }
+}
+/**
+ * Creates a resilient provider registry with default providers
+ */
+export function createResilientProviderRegistry(config) {
+    const baseRegistry = createBaseRegistry();
+    return new ResilientProviderRegistry(baseRegistry, config);
+}
+//# sourceMappingURL=resilient-registry.js.map

package/dist/resilient-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient-registry.js","sourceRoot":"","sources":["../src/resilient-registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Provider adapter types (CLI-based)
+ *
+ * DESIGN: AutomatosX does NOT manage credentials.
+ * Each provider CLI handles its own authentication:
+ * - claude, gemini, codex: Official CLIs with built-in auth
+ * - qwen: Qwen CLI with DashScope auth
+ * - ax-glm: GLM CLI wrapper (handles ZAI_API_KEY)
+ * - ax-grok: Grok CLI wrapper (handles XAI_API_KEY)
+ *
+ * INV-MEM-003: Adapters must not accept domain objects directly
+ */
+/**
+ * Message role in a conversation
+ */
+export type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A message in a conversation
+ */
+export interface Message {
+    role: MessageRole;
+    content: string;
+}
+/**
+ * Request to generate a completion
+ */
+export interface CompletionRequest {
+    /**
+     * Unique request identifier
+     */
+    requestId: string;
+    /**
+     * The model to use for completion
+     */
+    model: string;
+    /**
+     * Messages to send to the model
+     */
+    messages: Message[];
+    /**
+     * Maximum tokens to generate
+     */
+    maxTokens?: number | undefined;
+    /**
+     * Temperature for sampling (0-1)
+     */
+    temperature?: number | undefined;
+    /**
+     * Stop sequences
+     */
+    stopSequences?: string[] | undefined;
+    /**
+     * System prompt (if not included in messages)
+     */
+    systemPrompt?: string | undefined;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number | undefined;
+}
+/**
+ * Token usage information
+ */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+/**
+ * Successful completion response
+ */
+export interface CompletionSuccess {
+    success: true;
+    requestId: string;
+    content: string;
+    model: string;
+    usage: TokenUsage;
+    stopReason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'unknown';
+    latencyMs: number;
+    cached: boolean;
+}
+/**
+ * Failed completion response
+ */
+export interface CompletionFailure {
+    success: false;
+    requestId: string;
+    error: ClassifiedError;
+    latencyMs: number;
+}
+/**
+ * Completion response (discriminated union)
+ */
+export type CompletionResponse = CompletionSuccess | CompletionFailure;
+/**
+ * Error categories for classification
+ */
+export type ErrorCategory = 'authentication' | 'quota' | 'rate_limit' | 'validation' | 'network' | 'server' | 'timeout' | 'not_found' | 'configuration' | 'unknown';
+/**
+ * Classified error with retry/fallback guidance
+ */
+export interface ClassifiedError {
+    category: ErrorCategory;
+    message: string;
+    shouldRetry: boolean;
+    shouldFallback: boolean;
+    retryAfterMs: number | null;
+    originalError: unknown;
+}
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    providerId: string;
+    timestamp: number;
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    latencyMs: number;
+    details: {
+        cliAvailable: boolean;
+        cliCommand: string;
+        version?: string | undefined;
+    };
+}
+/**
+ * Model configuration
+ */
+export interface ModelConfig {
+    modelId: string;
+    name: string;
+    contextWindow: number;
+    capabilities: ('text' | 'code' | 'vision')[];
+    isDefault?: boolean | undefined;
+}
+/**
+ * CLI provider configuration
+ * No API keys - CLIs handle their own authentication
+ */
+export interface CLIProviderConfig {
+    /**
+     * Provider identifier (e.g., 'claude', 'gemini')
+     */
+    providerId: string;
+    /**
+     * CLI command name (e.g., 'claude', 'gemini')
+     */
+    command: string;
+    /**
+     * Default CLI arguments
+     */
+    args: readonly string[];
+    /**
+     * Environment variables to set (non-secret)
+     */
+    env: Readonly<Record<string, string>>;
+    /**
+     * Expected output format
+     */
+    outputFormat: 'json' | 'stream-json' | 'text';
+    /**
+     * Default timeout in milliseconds
+     */
+    timeout: number;
+    /**
+     * Available models
+     */
+    models: readonly ModelConfig[];
+    /**
+     * How the prompt is passed to the CLI
+     * - 'stdin': Write prompt to stdin (default for claude, gemini, codex)
+     * - 'arg': Pass prompt as command-line argument (for ax-glm, ax-grok)
+     */
+    promptStyle?: 'stdin' | 'arg' | undefined;
+}
+/**
+ * LLM Provider interface (CLI-based)
+ */
+export interface LLMProvider {
+    /**
+     * Provider identifier (e.g., 'claude', 'gemini', 'ax-glm', 'ax-grok')
+     */
+    readonly providerId: string;
+    /**
+     * Provider configuration
+     */
+    readonly config: CLIProviderConfig;
+    /**
+     * Generates a completion
+     */
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    /**
+     * Checks if the provider is available and healthy
+     */
+    checkHealth(): Promise<HealthCheckResult>;
+    /**
+     * Checks if a model is supported
+     */
+    supportsModel(model: string): boolean;
+    /**
+     * Gets available models
+     */
+    getModels(): readonly ModelConfig[];
+    /**
+     * Checks if the provider is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Estimates token count for text (approximate)
+     */
+    estimateTokens(text: string): number;
+}
+/**
+ * Result of spawning a CLI process
+ */
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+}
+/**
+ * Options for spawning a CLI process
+ */
+export interface SpawnOptions {
+    command: string;
+    args: readonly string[];
+    stdin: string;
+    env: Readonly<Record<string, string | undefined>>;
+    timeout: number;
+    cwd?: string | undefined;
+}
+/**
+ * Parsed output from CLI
+ */
+export interface ParsedOutput {
+    content: string;
+    metadata?: Record<string, unknown> | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Provider adapter types (CLI-based)
+ *
+ * DESIGN: AutomatosX does NOT manage credentials.
+ * Each provider CLI handles its own authentication:
+ * - claude, gemini, codex: Official CLIs with built-in auth
+ * - qwen: Qwen CLI with DashScope auth
+ * - ax-glm: GLM CLI wrapper (handles ZAI_API_KEY)
+ * - ax-grok: Grok CLI wrapper (handles XAI_API_KEY)
+ *
+ * INV-MEM-003: Adapters must not accept domain objects directly
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@defai.digital/provider-adapters",
+  "version": "13.0.3",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "DEFAI Private Limited",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/defai-digital/automatosx.git",
+    "directory": "packages/adapters/providers"
+  },
+  "homepage": "https://github.com/defai-digital/automatosx#readme",
+  "bugs": {
+    "url": "https://github.com/defai-digital/automatosx/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@defai.digital/contracts": "13.0.3",
+    "@defai.digital/routing-engine": "13.0.3",
+    "@defai.digital/resilience-domain": "13.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist"
+  }
+}