@relayplane/proxy 1.8.5 → 1.8.7

package/dist/standalone-proxy.js

@@ -75,6 +75,8 @@ const index_js_1 = require("./mesh/index.js");
 const response_cache_js_1 = require("./response-cache.js");
 const stats_js_1 = require("./stats.js");
 const rate_limiter_js_1 = require("./rate-limiter.js");
+const ollama_js_1 = require("./ollama.js");
+const cross_provider_cascade_js_1 = require("./cross-provider-cascade.js");
 const budget_js_1 = require("./budget.js");
 const anomaly_js_1 = require("./anomaly.js");
 const alerts_js_1 = require("./alerts.js");
@@ -186,6 +188,10 @@ exports.DEFAULT_ENDPOINTS = {
         baseUrl: 'https://api.perplexity.ai',
         apiKeyEnv: 'PERPLEXITY_API_KEY',
     },
+    ollama: {
+        baseUrl: 'http://localhost:11434',
+        apiKeyEnv: 'OLLAMA_API_KEY', // Not actually required, placeholder for consistency
+    },
 };
 /**
  * Model to provider/model mapping
@@ -726,6 +732,8 @@ const DEFAULT_PROXY_CONFIG = {
 };
 /** Module-level ref to active proxy config (set during startProxy) */
 let _activeProxyConfig = {};
+/** Module-level ref to active Ollama config (set during startProxy) */
+let _activeOllamaConfig;
 function isContentLoggingEnabled() {
     return _activeProxyConfig.dashboard?.showRequestContent !== false;
 }
@@ -1901,10 +1909,14 @@ function resolveExplicitModel(modelName) {
     if (modelName.startsWith('deepseek-') || modelName.startsWith('groq-')) {
         return { provider: 'openrouter', model: modelName };
     }
+    // Ollama models: "ollama/llama3.2" or direct model names when Ollama config exists
+    if (modelName.startsWith('ollama/')) {
+        return { provider: 'ollama', model: modelName.slice('ollama/'.length) };
+    }
     // Provider-prefixed format: "anthropic/claude-3-5-sonnet-latest"
     if (modelName.includes('/')) {
         const [provider, model] = modelName.split('/');
-        const validProviders = ['openai', 'anthropic', 'google', 'xai', 'openrouter', 'deepseek', 'groq', 'local'];
+        const validProviders = ['openai', 'anthropic', 'google', 'xai', 'openrouter', 'deepseek', 'groq', 'local', 'ollama'];
         if (provider && model && validProviders.includes(provider)) {
             return { provider: provider, model };
         }
@@ -1962,6 +1974,57 @@ function checkResponseModelMismatch(responseData, requestedModel, provider, log)
  * Extract a human-readable error message from a provider error payload.
  * Handles Anthropic ({ error: { type, message } }) and OpenAI ({ error: { message } }) formats.
  */
+/**
+ * Convert a native Anthropic messages request body into the OpenAI-compatible
+ * ChatRequest format used by forwardToOpenAICompatible and related helpers.
+ *
+ * This allows cross-provider cascade from Anthropic → OpenRouter (and others)
+ * without losing the original request content. (GH #38)
+ */
+function convertNativeAnthropicBodyToChatRequest(body, mappedModel) {
+    const rawMessages = Array.isArray(body['messages'])
+        ? body['messages']
+        : [];
+    const messages = [];
+    // Prepend system message if present
+    if (body['system'] && typeof body['system'] === 'string') {
+        messages.push({ role: 'system', content: body['system'] });
+    }
+    else if (Array.isArray(body['system'])) {
+        // Anthropic structured system (array of {type, text}) — flatten to text
+        const systemText = body['system']
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('\n');
+        if (systemText)
+            messages.push({ role: 'system', content: systemText });
+    }
+    for (const msg of rawMessages) {
+        const role = msg['role'];
+        const content = msg['content'];
+        if (typeof content === 'string') {
+            messages.push({ role: role, content });
+        }
+        else if (Array.isArray(content)) {
+            // Anthropic content blocks — extract text parts
+            const text = content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text ?? '')
+                .join('');
+            messages.push({ role: role, content: text });
+        }
+        else {
+            messages.push({ role: role, content: String(content ?? '') });
+        }
+    }
+    return {
+        model: mappedModel,
+        messages,
+        max_tokens: body['max_tokens'] ?? 4096,
+        temperature: body['temperature'],
+        stream: false,
+    };
+}
 function extractProviderErrorMessage(payload, statusCode) {
     const err = payload['error'];
     if (typeof err === 'string')
@@ -2047,6 +2110,10 @@ function resolveProviderApiKey(provider, ctx, envApiKey) {
         }
         return { apiKey: envApiKey };
     }
+    // Ollama doesn't need an API key — it's local
+    if (provider === 'ollama') {
+        return { apiKey: 'ollama-local' };
+    }
     const apiKeyEnv = exports.DEFAULT_ENDPOINTS[provider]?.apiKeyEnv ?? `${provider.toUpperCase()}_API_KEY`;
     const apiKey = process.env[apiKeyEnv];
     if (!apiKey) {
@@ -2437,6 +2504,17 @@ async function startProxy(config = {}) {
         }
         catch { /* file missing or parse error = treat as first run */ }
         const userConfig = (0, config_js_1.loadConfig)();
+        (0, rate_limiter_js_1.configureRateLimiter)();
+        // ── Cross-provider cascade: configure from proxy config (GH #38) ──
+        if (proxyConfig.crossProviderCascade?.enabled && (proxyConfig.crossProviderCascade.providers?.length ?? 0) > 1) {
+            cross_provider_cascade_js_1.crossProviderCascade.configure({
+                enabled: true,
+                providers: proxyConfig.crossProviderCascade.providers,
+                triggerStatuses: proxyConfig.crossProviderCascade.triggerStatuses,
+                modelMapping: proxyConfig.crossProviderCascade.modelMapping,
+            });
+            log(`[CROSS-CASCADE] Enabled. Provider order: ${proxyConfig.crossProviderCascade.providers.join(' → ')}`);
+        }
         const isFirstRun = !rawFileHasRouting || !userConfig.first_run_complete;
         if (isFirstRun || proxyConfig.routing?.mode === 'auto') {
             const envAnthropicKey = process.env['ANTHROPIC_API_KEY'];
@@ -2497,7 +2575,37 @@ async function startProxy(config = {}) {
         }
     }
     _activeProxyConfig = proxyConfig;
+    _activeOllamaConfig = proxyConfig.ollama;
     const cooldownManager = new CooldownManager(getCooldownConfig(proxyConfig));
+    // === Ollama provider initialization ===
+    if (_activeOllamaConfig?.enabled !== false && _activeOllamaConfig?.models?.length) {
+        const ollamaUrl = _activeOllamaConfig.baseUrl ?? ollama_js_1.OLLAMA_DEFAULTS.baseUrl;
+        console.log(`[RelayPlane] Ollama provider configured: ${ollamaUrl}`);
+        console.log(`[RelayPlane] Ollama models: ${_activeOllamaConfig.models.join(', ')}`);
+        if (_activeOllamaConfig.routeWhen) {
+            const routeInfo = [];
+            if (_activeOllamaConfig.routeWhen.complexity?.length) {
+                routeInfo.push(`complexity: ${_activeOllamaConfig.routeWhen.complexity.join(', ')}`);
+            }
+            if (_activeOllamaConfig.routeWhen.taskTypes?.length) {
+                routeInfo.push(`taskTypes: ${_activeOllamaConfig.routeWhen.taskTypes.join(', ')}`);
+            }
+            if (routeInfo.length) {
+                console.log(`[RelayPlane] Ollama routing rules: ${routeInfo.join('; ')}`);
+            }
+        }
+        // Async health check (non-blocking)
+        (0, ollama_js_1.checkOllamaHealthCached)(ollamaUrl).then((health) => {
+            if (health.available) {
+                console.log(`[RelayPlane] ✓ Ollama is online (${health.models.length} models available, ${health.responseTimeMs}ms)`);
+            }
+            else {
+                console.warn(`[RelayPlane] ⚠️  Ollama not available: ${health.error} — will fall back to cloud providers`);
+            }
+        }).catch(() => {
+            console.warn('[RelayPlane] ⚠️  Ollama health check failed — will fall back to cloud providers');
+        });
+    }
     // === Startup config validation (Task 4) ===
     try {
         const userConfig = (0, config_js_1.loadConfig)();
@@ -2651,6 +2759,8 @@ async function startProxy(config = {}) {
         anomalyDetector.updateConfig({ ...anomalyDetector.getConfig(), ...(proxyConfig.anomaly ?? {}) });
         alertManager.updateConfig({ ...alertManager.getConfig(), ...(proxyConfig.alerts ?? {}) });
         downgradeConfig = { ...downgrade_js_1.DEFAULT_DOWNGRADE_CONFIG, ...(proxyConfig.downgrade ?? {}) };
+        _activeOllamaConfig = proxyConfig.ollama;
+        (0, ollama_js_1.clearOllamaHealthCache)(); // Invalidate cached health on config change
         log(`Reloaded config from ${configPath}`);
     };
     const scheduleConfigReload = () => {
@@ -2999,6 +3109,9 @@ async function startProxy(config = {}) {
                 console.log('[RelayPlane Health] Provider stats:', JSON.stringify(providerStats));
                 const providers = [];
                 for (const [name, ep] of Object.entries(exports.DEFAULT_ENDPOINTS)) {
+                    // Skip Ollama from normal key-based health check — it's handled separately
+                    if (name === 'ollama')
+                        continue;
                     const hasKey = !!process.env[ep.apiKeyEnv];
                     const stats = providerStats[name.toLowerCase()];
                     const successRate = stats && stats.total > 0 ? stats.success / stats.total : (hasKey ? 1 : 0);
@@ -3018,6 +3131,19 @@ async function startProxy(config = {}) {
                         lastChecked: new Date().toISOString(),
                     });
                 }
+                // Add Ollama status if configured
+                if (_activeOllamaConfig && _activeOllamaConfig.enabled !== false) {
+                    const ollamaStats = providerStats['ollama'];
+                    const ollamaSuccessRate = ollamaStats && ollamaStats.total > 0 ? ollamaStats.success / ollamaStats.total : 0;
+                    const ollamaHealth = await (0, ollama_js_1.checkOllamaHealthCached)(_activeOllamaConfig.baseUrl);
+                    providers.push({
+                        provider: 'ollama',
+                        status: ollamaHealth.available ? 'healthy' : 'down',
+                        latency: ollamaHealth.responseTimeMs ?? 0,
+                        successRate: ollamaHealth.available ? (ollamaSuccessRate || 1) : 0,
+                        lastChecked: new Date().toISOString(),
+                    });
+                }
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ providers }));
                 return;
@@ -3095,6 +3221,21 @@ async function startProxy(config = {}) {
             return;
         }
         // === Mesh stats endpoint ===
+        // === Ollama status endpoint ===
+        if (req.method === 'GET' && pathname === '/v1/ollama/status') {
+            const ollamaBaseUrl = _activeOllamaConfig?.baseUrl ?? ollama_js_1.OLLAMA_DEFAULTS.baseUrl;
+            const health = await (0, ollama_js_1.checkOllamaHealthCached)(ollamaBaseUrl);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                configured: !!_activeOllamaConfig,
+                enabled: _activeOllamaConfig?.enabled !== false,
+                baseUrl: ollamaBaseUrl,
+                health,
+                routeWhen: _activeOllamaConfig?.routeWhen ?? null,
+                configuredModels: _activeOllamaConfig?.models ?? [],
+            }));
+            return;
+        }
         if (req.method === 'GET' && pathname === '/v1/mesh/stats') {
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify(meshHandle.getStats()));
@@ -3432,20 +3573,25 @@ async function startProxy(config = {}) {
             // ── End budget check ──
             // ── Rate limit check ──
             const workspaceId = 'local'; // Local proxy uses single workspace
-            const rateLimit = (0, rate_limiter_js_1.checkLimit)(workspaceId, targetModel);
-            if (!rateLimit.allowed) {
-                console.error(`[RATE LIMIT] ${targetModel} limit reached for workspace: ${workspaceId}`);
+            try {
+                // Pass targetProvider so per-provider limits are applied and limits don't
+                // cascade across providers (e.g. Anthropic hitting its cap won't block OpenAI).
+                await (0, rate_limiter_js_1.acquireSlot)(workspaceId, targetModel, targetProvider);
+            }
+            catch (err) {
+                const rlErr = err;
+                console.error(`[RATE LIMIT] ${targetModel}: ${rlErr.message}`);
                 res.writeHead(429, {
                     'Content-Type': 'application/json',
-                    'Retry-After': String(rateLimit.retryAfter || 60),
-                    'X-RelayPlane-RateLimit-Limit': String(rateLimit.limit),
+                    'Retry-After': String(rlErr.retryAfter ?? 60),
+                    'X-RelayPlane-RateLimit-Limit': String(rlErr.limit),
                     'X-RelayPlane-RateLimit-Remaining': '0',
-                    'X-RelayPlane-RateLimit-Reset': String(Math.ceil(rateLimit.resetAt / 1000))
+                    'X-RelayPlane-RateLimit-Reset': String(Math.ceil(rlErr.resetAt / 1000)),
                 });
                 res.end(JSON.stringify({
-                    error: `Rate limit exceeded for ${targetModel}. Max ${rateLimit.limit} requests per minute.`,
+                    error: rlErr.message,
                     type: 'rate_limit_exceeded',
-                    retry_after: rateLimit.retryAfter || 60
+                    retry_after: rlErr.retryAfter ?? 60,
                 }));
                 return;
             }
@@ -3510,6 +3656,46 @@ async function startProxy(config = {}) {
                         if (proxyConfig.reliability?.cooldowns?.enabled) {
                             cooldownManager.recordFailure(targetProvider, JSON.stringify(errorPayload));
                         }
+                        // ── Cross-provider cascade for /v1/messages path (GH #38) ──
+                        if (!isStreaming &&
+                            cross_provider_cascade_js_1.crossProviderCascade.enabled &&
+                            cross_provider_cascade_js_1.crossProviderCascade.shouldCascade(providerResponse.status)) {
+                            const { result: cascResult, data: cascData } = await cross_provider_cascade_js_1.crossProviderCascade.execute(targetProvider, targetModel || requestedModel, providerResponse.status, async (hop) => {
+                                const apiKeyResult = resolveProviderApiKey(hop.provider, ctx, useAnthropicEnvKey);
+                                if (apiKeyResult.error) {
+                                    return { status: apiKeyResult.error.status, data: apiKeyResult.error.payload };
+                                }
+                                // Respect per-provider rate limits before attempting the hop
+                                try {
+                                    await (0, rate_limiter_js_1.acquireSlot)('local', hop.model, hop.provider);
+                                }
+                                catch {
+                                    return { status: 429, data: { error: `Local rate limit for ${hop.provider}` } };
+                                }
+                                // Convert native Anthropic body to ChatRequest for OpenAI-compatible providers
+                                const chatReq = convertNativeAnthropicBodyToChatRequest(requestBody, hop.model);
+                                const hopResult = await executeNonStreamingProviderRequest(chatReq, hop.provider, hop.model, apiKeyResult.apiKey, ctx);
+                                return { status: hopResult.status, data: hopResult.responseData };
+                            }, log);
+                            if (cascResult.success && cascData) {
+                                // Cascade succeeded — update provider/model and respond
+                                const cascDurationMs = Date.now() - startTime;
+                                const cascProvider = cascResult.provider;
+                                const cascModel = cascResult.model;
+                                logRequest(originalModel ?? 'unknown', cascModel, cascProvider, cascDurationMs, true, `${routingMode}+cross-cascade`, undefined, taskType, complexity);
+                                const cascRpHeaders = buildRelayPlaneResponseHeaders(cascModel, originalModel ?? 'unknown', complexity, cascProvider, `${routingMode}+cross-cascade`);
+                                res.writeHead(200, {
+                                    'Content-Type': 'application/json',
+                                    'X-RelayPlane-Cascade-Provider': cascProvider,
+                                    'X-RelayPlane-Cascade-Model': cascModel,
+                                    ...cascRpHeaders,
+                                });
+                                res.end(JSON.stringify(cascData));
+                                return;
+                            }
+                            // All fallbacks exhausted — fall through to original error response
+                        }
+                        // ── End cross-provider cascade ──
                         const durationMs = Date.now() - startTime;
                         const errMsg = extractProviderErrorMessage(errorPayload, providerResponse.status);
                         logRequest(originalModel ?? 'unknown', targetModel || requestedModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, errMsg, providerResponse.status);
@@ -4011,6 +4197,21 @@ async function startProxy(config = {}) {
                 targetModel = defaultRoute.model;
             }
         }
+        // ── Ollama routing: intercept before cloud dispatch ──
+        if (!useCascade && _activeOllamaConfig && _activeOllamaConfig.enabled !== false) {
+            if (targetProvider === 'ollama' || (0, ollama_js_1.shouldRouteToOllama)(_activeOllamaConfig, complexity, taskType, request.model)) {
+                // Check Ollama availability before routing
+                const ollamaHealth = await (0, ollama_js_1.checkOllamaHealthCached)(_activeOllamaConfig.baseUrl);
+                if (ollamaHealth.available) {
+                    targetProvider = 'ollama';
+                    targetModel = (0, ollama_js_1.resolveOllamaModel)(targetModel, _activeOllamaConfig);
+                    log(`Ollama routing: ${complexity}/${taskType} → ollama/${targetModel}`);
+                }
+                else {
+                    log(`Ollama unavailable (${ollamaHealth.error}), falling back to cloud provider`);
+                }
+            }
+        }
         if (!useCascade) {
             log(`Routing to: ${targetProvider}/${targetModel}`);
         }
@@ -4053,20 +4254,24 @@ async function startProxy(config = {}) {
         // ── End budget check ──
         // ── Rate limit check ──
         const chatWorkspaceId = 'local'; // Local proxy uses single workspace
-        const chatRateLimit = (0, rate_limiter_js_1.checkLimit)(chatWorkspaceId, targetModel);
-        if (!chatRateLimit.allowed) {
-            console.error(`[RATE LIMIT] ${targetModel} limit reached for workspace: ${chatWorkspaceId}`);
+        try {
+            // Pass targetProvider so per-provider limits apply and don't cascade across providers.
+            await (0, rate_limiter_js_1.acquireSlot)(chatWorkspaceId, targetModel, targetProvider);
+        }
+        catch (err) {
+            const chatRlErr = err;
+            console.error(`[RATE LIMIT] ${targetModel}: ${chatRlErr.message}`);
             res.writeHead(429, {
                 'Content-Type': 'application/json',
-                'Retry-After': String(chatRateLimit.retryAfter || 60),
-                'X-RelayPlane-RateLimit-Limit': String(chatRateLimit.limit),
+                'Retry-After': String(chatRlErr.retryAfter ?? 60),
+                'X-RelayPlane-RateLimit-Limit': String(chatRlErr.limit),
                 'X-RelayPlane-RateLimit-Remaining': '0',
-                'X-RelayPlane-RateLimit-Reset': String(Math.ceil(chatRateLimit.resetAt / 1000))
+                'X-RelayPlane-RateLimit-Reset': String(Math.ceil(chatRlErr.resetAt / 1000)),
             });
             res.end(JSON.stringify({
-                error: `Rate limit exceeded for ${targetModel}. Max ${chatRateLimit.limit} requests per minute.`,
+                error: chatRlErr.message,
                 type: 'rate_limit_exceeded',
-                retry_after: chatRateLimit.retryAfter || 60
+                retry_after: chatRlErr.retryAfter ?? 60,
             }));
             return;
         }
@@ -4175,7 +4380,7 @@ async function startProxy(config = {}) {
                 }
             }
             else {
-                await handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity, chatAgentFingerprint, chatExplicitAgentId);
+                await handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity, chatAgentFingerprint, chatExplicitAgentId, useAnthropicEnvKey);
             }
         }
     });
@@ -4308,6 +4513,24 @@ async function executeNonStreamingProviderRequest(request, targetProvider, targe
             }
             break;
         }
+        case 'ollama': {
+            const ollamaResult = await (0, ollama_js_1.forwardToOllama)(targetModel, request.messages, {
+                temperature: request.temperature,
+                max_tokens: request.max_tokens,
+                tools: request.tools,
+                baseUrl: _activeOllamaConfig?.baseUrl,
+                timeoutMs: _activeOllamaConfig?.timeoutMs,
+            });
+            if (!ollamaResult.success) {
+                return {
+                    responseData: { error: ollamaResult.error },
+                    ok: false,
+                    status: ollamaResult.error?.status ?? 502,
+                };
+            }
+            responseData = ollamaResult.data;
+            break;
+        }
         default: {
             providerResponse = await forwardToOpenAI(request, targetModel, apiKey);
             responseData = (await providerResponse.json());
@@ -4337,6 +4560,44 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
             case 'groq':
                 providerResponse = await forwardToOpenAICompatibleStream(request, targetModel, apiKey);
                 break;
+            case 'ollama': {
+                // Ollama streaming uses its own handler that converts NDJSON → SSE
+                const ollamaStream = await (0, ollama_js_1.forwardToOllamaStream)(targetModel, request.messages, {
+                    temperature: request.temperature,
+                    max_tokens: request.max_tokens,
+                    tools: request.tools,
+                    baseUrl: _activeOllamaConfig?.baseUrl,
+                    timeoutMs: _activeOllamaConfig?.timeoutMs,
+                });
+                if (!ollamaStream.success || !ollamaStream.stream) {
+                    const durationMs = Date.now() - startTime;
+                    const errMsg = ollamaStream.error?.message ?? 'Ollama stream failed';
+                    logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, errMsg, ollamaStream.error?.status);
+                    res.writeHead(ollamaStream.error?.status ?? 502, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: ollamaStream.error }));
+                    return;
+                }
+                // Write SSE headers and pipe converted stream
+                const relayHeaders = buildRelayPlaneResponseHeaders(targetModel, request.model, complexity, 'ollama', routingMode);
+                res.writeHead(200, {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                    'Connection': 'keep-alive',
+                    ...relayHeaders,
+                });
+                for await (const chunk of ollamaStream.stream) {
+                    res.write(chunk);
+                }
+                const durationMs = Date.now() - startTime;
+                logRequest(request.model ?? 'unknown', targetModel, 'ollama', durationMs, true, routingMode, false, taskType, complexity, agentFingerprint, agentId);
+                updateLastHistoryEntry(0, 0, 0, targetModel, undefined, undefined, agentFingerprint, agentId);
+                if (recordTelemetry) {
+                    sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, true, 0, request.model ?? undefined);
+                    meshCapture(targetModel, 'ollama', taskType, 0, 0, 0, durationMs, true);
+                }
+                res.end();
+                return;
+            }
             default:
                 providerResponse = await forwardToOpenAIStream(request, targetModel, apiKey);
         }
@@ -4524,7 +4785,9 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
 /**
  * Handle non-streaming request
  */
-async function handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity = 'simple', agentFingerprint, agentId) {
+async function handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity = 'simple', agentFingerprint, agentId, 
+/** Anthropic env API key — required for cross-provider cascade API key resolution (GH #38) */
+anthropicEnvKeyForCascade) {
     let responseData;
     try {
         const result = await executeNonStreamingProviderRequest(request, targetProvider, targetModel, apiKey, ctx);
@@ -4533,16 +4796,59 @@ async function handleNonStreamingRequest(res, request, targetProvider, targetMod
             if (cooldownsEnabled) {
                 cooldownManager.recordFailure(targetProvider, JSON.stringify(responseData));
             }
-            const durationMs = Date.now() - startTime;
-            const nsErrMsg = extractProviderErrorMessage(responseData, result.status);
-            logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, nsErrMsg, result.status);
-            if (recordTelemetry) {
-                sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
-                meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, nsErrMsg);
+            // ── Cross-provider cascade (GH #38) ──
+            if (cross_provider_cascade_js_1.crossProviderCascade.enabled && cross_provider_cascade_js_1.crossProviderCascade.shouldCascade(result.status)) {
+                const { result: cascResult, data: cascData } = await cross_provider_cascade_js_1.crossProviderCascade.execute(targetProvider, targetModel, result.status, async (hop) => {
+                    const apiKeyResult = resolveProviderApiKey(hop.provider, ctx, anthropicEnvKeyForCascade);
+                    if (apiKeyResult.error) {
+                        return { status: apiKeyResult.error.status, data: apiKeyResult.error.payload };
+                    }
+                    // Respect per-provider rate limits before attempting the hop
+                    try {
+                        await (0, rate_limiter_js_1.acquireSlot)('local', hop.model, hop.provider);
+                    }
+                    catch {
+                        // Rate-limited locally — treat as 429 so cascade continues
+                        return { status: 429, data: { error: `Local rate limit for ${hop.provider}` } };
+                    }
+                    const hopResult = await executeNonStreamingProviderRequest({ ...request, model: hop.model }, hop.provider, hop.model, apiKeyResult.apiKey, ctx);
+                    return { status: hopResult.status, data: hopResult.responseData };
+                }, log);
+                if (cascResult.success && cascData) {
+                    // Update tracking variables to reflect the actual provider/model used
+                    targetProvider = cascResult.provider;
+                    targetModel = cascResult.model;
+                    responseData = cascData;
+                    // Fall through to success handling below (don't return early)
+                }
+                else {
+                    // All fallbacks exhausted — return the primary error
+                    const durationMs = Date.now() - startTime;
+                    const nsErrMsg = extractProviderErrorMessage(responseData, result.status);
+                    logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, `${routingMode}+cascade`, undefined, taskType, complexity, undefined, undefined, nsErrMsg, result.status);
+                    if (recordTelemetry) {
+                        sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
+                        meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, nsErrMsg);
+                    }
+                    res.writeHead(result.status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(responseData));
+                    return;
+                }
             }
-            res.writeHead(result.status, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(responseData));
-            return;
+            else {
+                // No cascade — return error as-is
+                const durationMs = Date.now() - startTime;
+                const nsErrMsg = extractProviderErrorMessage(responseData, result.status);
+                logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, nsErrMsg, result.status);
+                if (recordTelemetry) {
+                    sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
+                    meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, nsErrMsg);
+                }
+                res.writeHead(result.status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(responseData));
+                return;
+            }
+            // ── End cross-provider cascade ──
         }
     }
     catch (err) {