ldrouter 1.5.1

package/dist/server/gateway/runner.js

@@ -0,0 +1,745 @@
+// Gateway execution pipeline: auth -> resolve -> ACL -> limits -> route -> attempt -> persist.
+import { getDb, schema } from '../db/index.js';
+import { eq } from 'drizzle-orm';
+import { GatewayError } from '../errors.js';
+import { resolveRequestedModel, unwrapAlias } from '../routing/resolver.js';
+import { deriveRequiredCapabilities, modelMeets } from '../routing/capabilities.js';
+import { loadCombo, selectCandidates, orderCandidates, shouldFallback } from '../routing/combo.js';
+import { getEffectiveState, isOpen, recordSuccess, recordFailure, halfOpenProbeAllowed } from '../routing/circuit.js';
+import { checkRpm, checkTpm, acquireConcurrent, releaseConcurrent } from '../routing/ratelimit.js';
+import { checkDailyMonthly, consumeUsage } from '../routing/quota.js';
+import { keyAllowedFor } from '../auth/api-key.js';
+import { providerToUpstreamConfig, callUpstreamNonStreaming, callUpstreamStreaming, upstreamUrl } from '../upstream/client.js';
+import { canonicalToOpenAIRequest, openAIResponseToCanonical } from '../protocols/canonical.js';
+import { canonicalToAnthropicRequest, anthropicResponseToCanonical } from '../protocols/anthropic.js';
+import { uuid } from '../auth/ids.js';
+import { redactString, redactValue } from '../security/redact.js';
+import { getSettings } from '../db/repositories/settings.js';
+import { buildCacheKey, lookupCache, storeCache, cacheAllowed } from '../caching/store.js';
+import { metrics } from '../metrics/registry.js';
+export class GatewayRunner {
+    async execute(req, ctx) {
+        const start = Date.now();
+        metrics.activeRequests.inc();
+        let concurrencyAcquired = false;
+        const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
+        const attempts = [];
+        // --- Resolve model ---
+        const target = resolveRequestedModel(req.canonical.model);
+        const resolved = unwrapAlias(target);
+        let comboPlan = null;
+        if (resolved.kind === 'combo')
+            comboPlan = loadCombo(resolved.comboId);
+        // --- ACL check ---
+        if (ctx.key) {
+            if (resolved.kind === 'model') {
+                if (!keyAllowedFor(ctx.key, 'model', resolved.modelId))
+                    throw new GatewayError('permission_error', 'Model not permitted for this API key', { status: 403 });
+            }
+            else if (resolved.kind === 'combo') {
+                if (!keyAllowedFor(ctx.key, 'combo', resolved.comboId))
+                    throw new GatewayError('permission_error', 'Combo not permitted for this API key', { status: 403 });
+            }
+        }
+        // --- Limits: RPM / TPM / concurrency / quota ---
+        if (ctx.key) {
+            const rpm = checkRpm(ctx.key.id, ctx.key.rpmLimit);
+            if (!rpm.allowed) {
+                metrics.rateLimited.inc({ reason: 'rpm' });
+                const err = new GatewayError('rate_limit_error', 'Rate limit exceeded (RPM)', { status: 429, code: 'rpm_limit' });
+                err.retryAfter = rpm.retryAfterSeconds;
+                throw err;
+            }
+            // Estimate input tokens for TPM: conservative approximation (4 chars/token)
+            const estimatedInput = estimateTokens(JSON.stringify(req.canonical.messages));
+            const tpm = checkTpm(ctx.key.id, ctx.key.tpmLimit, estimatedInput + (req.canonical.maxOutputTokens ?? 1024));
+            if (!tpm.allowed) {
+                metrics.rateLimited.inc({ reason: 'tpm' });
+                const err = new GatewayError('rate_limit_error', 'Rate limit exceeded (TPM)', { status: 429, code: 'tpm_limit' });
+                err.retryAfter = tpm.retryAfterSeconds;
+                throw err;
+            }
+            const quota = checkDailyMonthly(ctx.key.id, ctx.key.dailyTokenLimit, ctx.key.monthlyTokenLimit, estimatedInput + (req.canonical.maxOutputTokens ?? 1024));
+            if (!quota.allowed) {
+                metrics.rateLimited.inc({ reason: quota.reason ?? 'quota' });
+                throw new GatewayError('rate_limit_error', `Quota exceeded (${quota.reason})`, { status: 429, code: 'quota_limit' });
+            }
+            if (!acquireConcurrent(ctx.key.id, ctx.key.maxConcurrent)) {
+                metrics.rateLimited.inc({ reason: 'concurrency' });
+                throw new GatewayError('rate_limit_error', 'Too many concurrent requests', { status: 429, code: 'concurrency_limit' });
+            }
+            concurrencyAcquired = true;
+        }
+        try {
+            // --- Capability requirements ---
+            const required = deriveRequiredCapabilities(req.canonical);
+            // --- Determine candidates ---
+            let candidates = [];
+            let selectionReasons = [];
+            if (resolved.kind === 'model') {
+                candidates = await this.loadModelCandidate(resolved.modelId, required);
+                selectionReasons.push('direct_model');
+            }
+            else if (comboPlan) {
+                const all = await this.loadAllModels();
+                const filtered = selectCandidates(comboPlan, all, required);
+                if (filtered.length === 0) {
+                    throw new GatewayError('capability_not_supported', 'No combo member satisfies the request capabilities or availability', { status: 400 });
+                }
+                candidates = orderCandidates(comboPlan, filtered);
+                selectionReasons.push('combo');
+            }
+            if (candidates.length === 0) {
+                throw new GatewayError('upstream_unavailable', 'No available model candidates', { status: 502 });
+            }
+            // --- Gateway response cache check ---
+            const settings = getSettings();
+            const keyCacheOverride = ctx.key?.cacheOverrideEnabled ?? null;
+            const targetCacheOverride = this.getTargetCacheOverride(resolved);
+            const allowed = cacheAllowed({
+                globalEnabled: settings.gatewayCacheEnabled,
+                keyAllowed: keyCacheOverride,
+                targetAllowed: targetCacheOverride,
+                streaming: req.canonical.stream,
+            });
+            if (allowed && !req.canonical.stream && !hasTools(req.canonical)) {
+                const configVersion = this.getTargetConfigVersion(resolved);
+                const cacheKey = buildCacheKey({
+                    protocol: req.protocol,
+                    resolvedTargetKind: resolved.kind,
+                    resolvedTargetId: this.resolvedId(resolved),
+                    configVersion,
+                    canonicalRequest: req.canonical,
+                });
+                const cached = lookupCache(cacheKey);
+                if (cached.hit && cached.payload) {
+                    metrics.cacheHits.inc();
+                    const g = this.cachedToOutcome(cached.payload, cached.usage, ctx, resolved, start);
+                    await this.persistRequest(req, ctx, resolved, g, usageFromCache(cached.usage), attempts, true);
+                    metrics.activeRequests.dec();
+                    return g;
+                }
+                // remember cacheKey for storing after success
+                req._cacheKey = cacheKey;
+                req._cacheConfigVersion = configVersion;
+            }
+            // --- Attempt loop with fallback ---
+            const maxAttempts = comboPlan?.maxTotalAttempts ?? (candidates.length > 1 ? 2 : 1);
+            let lastError = null;
+            let sentToClient = false; // semantically committed output sent
+            let resultText = '';
+            let resultToolCalls = [];
+            let resultFinishReason = null;
+            let finalModelId = null;
+            for (let i = 0; i < maxAttempts && i < candidates.length; i++) {
+                const candidate = candidates[i];
+                finalModelId = candidate.modelId;
+                const provider = getDb().select().from(schema.providers).where(eq(schema.providers.id, candidate.providerId)).get();
+                if (!provider || !provider.enabled) {
+                    attempts.push(this.failedAttempt(i + 1, candidate, provider?.name ?? '', 'skipped_disabled_provider', null, null, 0, null, null));
+                    continue;
+                }
+                const eff = getEffectiveState(provider.id, provider.cbCooldownSeconds);
+                if (eff === 'open' && !halfOpenProbeAllowed(provider.id)) {
+                    attempts.push(this.failedAttempt(i + 1, candidate, provider.name, 'circuit_open', null, null, 0, null, null));
+                    if (comboPlan && shouldFallback(comboPlan, { type: 'connection_error' })) {
+                        metrics.fallbackCount.inc();
+                        continue;
+                    }
+                    lastError = new GatewayError('upstream_unavailable', 'Provider circuit is open', { status: 502 });
+                    break;
+                }
+                const cfg = providerToUpstreamConfig(provider);
+                const attemptStart = Date.now();
+                const attempt = {
+                    attemptNumber: i + 1,
+                    providerId: provider.id,
+                    modelId: candidate.modelId,
+                    providerName: provider.name,
+                    startedAt: new Date(attemptStart).toISOString(),
+                    completedAt: '',
+                    statusCode: null,
+                    success: false,
+                    latencyMs: 0,
+                    ttftMs: null,
+                    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 },
+                    streamStarted: false,
+                    partialResponse: false,
+                    selectionReason: selectionReasons[0] ?? 'direct',
+                    failureReason: null,
+                    sanitizedError: null,
+                    upstreamRequestId: null,
+                };
+                try {
+                    const out = await this.runOneAttempt(req, ctx, candidate, provider.name, cfg, required, (isStreamStarted) => {
+                        attempt.streamStarted = isStreamStarted;
+                        attempt.ttftMs = Date.now() - attemptStart;
+                    });
+                    attempt.statusCode = out.statusCode ?? null;
+                    attempt.success = true;
+                    attempt.latencyMs = Date.now() - attemptStart;
+                    attempt.ttftMs = out.ttftMs;
+                    attempt.usage = out.usage;
+                    attempt.upstreamRequestId = out.upstreamRequestId;
+                    attempt.completedAt = new Date().toISOString();
+                    attempt.result = out.result;
+                    usage.input += out.usage.input;
+                    usage.output += out.usage.output;
+                    usage.cacheRead += out.usage.cacheRead;
+                    usage.cacheWrite += out.usage.cacheWrite;
+                    usage.reasoning += out.usage.reasoning;
+                    usage.total += out.usage.total;
+                    resultText = out.result.text;
+                    resultToolCalls = out.result.toolCalls;
+                    resultFinishReason = out.result.finishReason;
+                    recordSuccess(provider.id);
+                    getDb().update(schema.providers).set({ healthState: 'healthy', updatedAt: new Date().toISOString() }).where(eq(schema.providers.id, provider.id)).run();
+                    attempts.push(attempt);
+                    sentToClient = out.streamStarted ?? false;
+                    break;
+                }
+                catch (e) {
+                    const err = e instanceof GatewayError ? e : new GatewayError('upstream_error', e.message, { cause: e });
+                    const shouldRetry = comboPlan ? shouldFallback(comboPlan, { type: classifyFailure(err), status: err.status }) : false;
+                    attempt.statusCode = err.status;
+                    attempt.success = false;
+                    attempt.latencyMs = Date.now() - attemptStart;
+                    attempt.completedAt = new Date().toISOString();
+                    attempt.failureReason = classifyFailure(err);
+                    attempt.sanitizedError = redactString(err.message);
+                    // If stream already started sending content, do NOT fallback
+                    if (attempt.streamStarted) {
+                        attempt.partialResponse = true;
+                        attempts.push(attempt);
+                        sentToClient = true;
+                        void sentToClient;
+                        lastError = err;
+                        break;
+                    }
+                    attempts.push(attempt);
+                    lastError = err;
+                    recordFailure(provider.id, provider.cbFailureThreshold, provider.cbCooldownSeconds);
+                    getDb().update(schema.providers).set({ healthState: 'down', updatedAt: new Date().toISOString() }).where(eq(schema.providers.id, provider.id)).run();
+                    if (shouldRetry && i + 1 < maxAttempts) {
+                        metrics.fallbackCount.inc();
+                        continue;
+                    }
+                    break;
+                }
+            }
+            // Build outcome
+            const latencyMs = Date.now() - start;
+            const outcome = {
+                success: !lastError,
+                httpStatus: lastError ? lastError.status : 200,
+                errorType: lastError?.type ?? null,
+                errorMessage: lastError ? redactString(lastError.message) : null,
+                text: lastError ? null : resultText,
+                toolCalls: lastError ? null : resultToolCalls,
+                finishReason: lastError ? null : resultFinishReason,
+                usage,
+                ttftMs: attempts.find((a) => a.ttftMs != null)?.ttftMs ?? null,
+                latencyMs,
+                attempts,
+                finalModelId,
+                resolvedTargetKind: resolved.kind,
+                resolvedTargetId: resolved.kind === 'model' ? resolved.modelId : resolved.kind === 'combo' ? resolved.comboId : null,
+                gatewayCacheHit: false,
+                streamEvents: null,
+            };
+            // Store in gateway cache if eligible
+            const cacheMeta = req;
+            if (outcome.success && cacheMeta._cacheKey && !req.canonical.stream && !hasTools(req.canonical)) {
+                const payload = this.buildCachedPayload(req, ctx, outcome);
+                storeCache({
+                    cacheKey: cacheMeta._cacheKey,
+                    targetKind: resolved.kind,
+                    targetId: outcome.resolvedTargetId ?? '',
+                    configVersion: cacheMeta._cacheConfigVersion ?? 1,
+                    protocol: req.protocol,
+                    payload,
+                    usage: usage,
+                    ttlSeconds: settings.gatewayCacheDefaultTtlSeconds,
+                });
+            }
+            await this.persistRequest(req, ctx, resolved, outcome, usage, attempts, false);
+            metrics.requestsTotal.inc({ protocol: req.protocol, status: String(outcome.httpStatus) });
+            metrics.requestDuration.observe(outcome.latencyMs, { protocol: req.protocol });
+            if (outcome.ttftMs != null)
+                metrics.requestTtft.observe(outcome.ttftMs, { protocol: req.protocol });
+            metrics.tokensInput.inc({ protocol: req.protocol }, usage.input);
+            metrics.tokensOutput.inc({ protocol: req.protocol }, usage.output);
+            metrics.tokensCacheRead.inc({ protocol: req.protocol }, usage.cacheRead);
+            metrics.tokensCacheWrite.inc({ protocol: req.protocol }, usage.cacheWrite);
+            metrics.tokensReasoning.inc({ protocol: req.protocol }, usage.reasoning);
+            if (ctx.key)
+                consumeUsage(ctx.key.id, usage.input, usage.output);
+            return outcome;
+        }
+        finally {
+            if (concurrencyAcquired && ctx.key)
+                releaseConcurrent(ctx.key.id);
+            metrics.activeRequests.dec();
+        }
+    }
+    async loadModelCandidate(modelId, required) {
+        const db = getDb();
+        const m = db.select().from(schema.models).where(eq(schema.models.id, modelId)).get();
+        if (!m)
+            return [];
+        const p = db.select().from(schema.providers).where(eq(schema.providers.id, m.providerId)).get();
+        if (!p || !p.enabled)
+            return [];
+        const caps = safeJson(m.capabilitiesJson);
+        const candidate = {
+            modelId: m.id,
+            publicModelId: m.publicModelId,
+            providerId: m.providerId,
+            enabled: m.enabled,
+            upstreamAvailable: m.upstreamAvailable,
+            circuitOpen: isOpen(m.providerId),
+            capabilities: caps,
+        };
+        if (!m.enabled || !m.upstreamAvailable)
+            return [];
+        if (candidate.circuitOpen)
+            return [];
+        if (!modelMeets(caps, required))
+            return [];
+        return [candidate];
+    }
+    async loadAllModels() {
+        const db = getDb();
+        const models = db.select().from(schema.models).all();
+        const providers = db.select().from(schema.providers).all();
+        const providerEnabled = new Map(providers.map((p) => [p.id, p.enabled]));
+        return models.map((m) => ({
+            modelId: m.id,
+            publicModelId: m.publicModelId,
+            providerId: m.providerId,
+            enabled: m.enabled,
+            upstreamAvailable: m.upstreamAvailable,
+            circuitOpen: isOpen(m.providerId),
+            capabilities: safeJson(m.capabilitiesJson),
+        })).filter((m) => m.enabled && m.upstreamAvailable && providerEnabled.get(m.providerId));
+    }
+    async runOneAttempt(req, ctx, candidate, providerName, cfg, required, onStreamStart) {
+        if (req.canonical.stream) {
+            return this.runStreamingAttempt(req, ctx, candidate, cfg, onStreamStart);
+        }
+        return this.runNonStreamingAttempt(req, candidate, cfg);
+    }
+    async runNonStreamingAttempt(req, candidate, cfg) {
+        const upstreamModel = candidate.publicModelId.split('/').slice(1).join('/');
+        let call;
+        if (cfg.type === 'openai') {
+            const payload = canonicalToOpenAIRequest(req.canonical, upstreamModel);
+            call = await callUpstreamNonStreaming(cfg, upstreamUrl(cfg, '/v1/chat/completions'), payload);
+        }
+        else {
+            const payload = canonicalToAnthropicRequest(req.canonical, upstreamModel);
+            call = await callUpstreamNonStreaming(cfg, upstreamUrl(cfg, '/v1/messages'), payload);
+        }
+        if (!call.ok) {
+            if (call.status === 429)
+                throw new GatewayError('upstream_rate_limit', `Upstream rate limited (HTTP ${call.status})`, { status: 429, code: 'upstream_http_429' });
+            if (call.status === 401 || call.status === 403)
+                throw new GatewayError('upstream_auth_error', 'Upstream authentication failed', { status: 502 });
+            if (call.status >= 500)
+                throw new GatewayError('upstream_error', `Upstream HTTP ${call.status}`, { status: 502, code: `upstream_http_${call.status}` });
+            throw new GatewayError('upstream_error', `Upstream HTTP ${call.status}: ${redactString(call.text.slice(0, 300))}`, { status: 502 });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(call.text);
+        }
+        catch {
+            throw new GatewayError('upstream_error', 'Upstream returned invalid JSON', { status: 502 });
+        }
+        let result;
+        let usage;
+        if (cfg.type === 'openai') {
+            const conv = openAIResponseToCanonical(parsed, req.canonical.model);
+            result = { text: conv.text, toolCalls: conv.toolCalls, finishReason: conv.finishReason };
+            usage = conv.usage;
+        }
+        else {
+            const conv = anthropicResponseToCanonical(parsed, req.canonical.model);
+            result = { text: conv.text, toolCalls: conv.toolCalls, finishReason: conv.finishReason };
+            usage = conv.usage;
+        }
+        return { statusCode: call.status, ttftMs: call.ttftMs, upstreamRequestId: call.upstreamRequestId, usage, result };
+    }
+    async runStreamingAttempt(req, ctx, candidate, cfg, onStreamStart) {
+        const upstreamModel = candidate.publicModelId.split('/').slice(1).join('/');
+        const encoder = req.protocol === 'openai' ? openaiStreamEncoder : anthropicStreamEncoder;
+        // Hard streaming invariant: the client SSE head is NOT written until the
+        // upstream confirms by delivering its first chunk (or completes). Before
+        // that first chunk, a pre-stream failure may fall back to the next model.
+        // Once content hits the client, fallback is forbidden (see docs/04).
+        const pipe = ctx.reply.raw;
+        let headWritten = false;
+        const writeHead = () => {
+            if (headWritten)
+                return;
+            headWritten = true;
+            pipe.writeHead(200, {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-cache',
+                connection: 'keep-alive',
+                'x-request-id': ctx.requestId,
+            });
+        };
+        let streamStarted = false;
+        let textBuf = '';
+        const toolBuf = [];
+        let finishReason = null;
+        const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
+        const chunkHandler = (chunk, isFirst) => {
+            // Track usage/finish (protocol-agnostic; runs even on the first chunk).
+            try {
+                const obj = JSON.parse(chunk.data);
+                if (cfg.type === 'openai') {
+                    const choice = obj.choices?.[0];
+                    if (choice?.delta?.content)
+                        textBuf += choice.delta.content;
+                    if (choice?.delta?.tool_calls) {
+                        for (const tc of choice.delta.tool_calls) {
+                            if (tc.function?.name)
+                                toolBuf.push({ id: tc.id ?? '', name: tc.function.name, input: {} });
+                        }
+                    }
+                    if (choice?.finish_reason)
+                        finishReason = choice.finish_reason;
+                    if (obj.usage) {
+                        usage.input = obj.usage.prompt_tokens ?? usage.input;
+                        usage.output = obj.usage.completion_tokens ?? usage.output;
+                        usage.cacheRead = obj.usage.prompt_tokens_details?.cached_tokens ?? usage.cacheRead;
+                        usage.reasoning = obj.usage.completion_tokens_details?.reasoning_tokens ?? usage.reasoning;
+                        usage.total = obj.usage.total_tokens ?? usage.total;
+                    }
+                }
+                else {
+                    // anthropic stream events
+                    if (obj.type === 'content_block_delta' && obj.delta?.text)
+                        textBuf += obj.delta.text;
+                    if (obj.type === 'content_block_start' && obj.content_block?.type === 'tool_use')
+                        toolBuf.push({ id: obj.content_block.id, name: obj.content_block.name, input: obj.content_block.input ?? {} });
+                    if (obj.type === 'message_delta' && obj.delta?.stop_reason)
+                        finishReason = obj.delta.stop_reason;
+                    if (obj.type === 'message_start' && obj.message?.usage) {
+                        usage.input = obj.message.usage.input_tokens ?? 0;
+                        usage.cacheRead = obj.message.usage.cache_read_input_tokens ?? 0;
+                        usage.cacheWrite = obj.message.usage.cache_creation_input_tokens ?? 0;
+                    }
+                    if (obj.type === 'message_delta' && obj.usage) {
+                        usage.output = obj.usage.output_tokens ?? usage.output;
+                    }
+                }
+            }
+            catch {
+                // ignore parse errors in stream
+            }
+            // First chunk: commit the downstream SSE response and flush any buffered.
+            if (isFirst) {
+                streamStarted = true;
+                onStreamStart(true);
+            }
+            const encoded = encoder(chunk.data, chunk.event);
+            if (!headWritten)
+                writeHead();
+            if (encoded)
+                pipe.write(encoded);
+            return;
+        };
+        try {
+            const url = cfg.type === 'openai' ? upstreamUrl(cfg, '/v1/chat/completions') : upstreamUrl(cfg, '/v1/messages');
+            const payload = cfg.type === 'openai' ? canonicalToOpenAIRequest(req.canonical, upstreamModel) : canonicalToAnthropicRequest(req.canonical, upstreamModel);
+            const meta = await callUpstreamStreaming(cfg, url, payload, chunkHandler);
+            // Upstream completed cleanly: ensure head + terminator are written.
+            if (!headWritten)
+                writeHead();
+            pipe.write('data: [DONE]\n\n');
+            pipe.end();
+            if (!usage.total)
+                usage.total = usage.input + usage.output;
+            return {
+                statusCode: 200,
+                ttftMs: meta.ttftMs,
+                upstreamRequestId: meta.upstreamRequestId,
+                usage,
+                result: { text: textBuf, toolCalls: toolBuf, finishReason },
+            };
+        }
+        catch (e) {
+            // Stream ended with failure. If we already sent content, mark partial and terminate.
+            if (streamStarted) {
+                // Ensure the (already-committed) response is closed.
+                if (!headWritten)
+                    writeHead();
+                pipe.end();
+                const err = e instanceof GatewayError ? e : new GatewayError('upstream_error', e.message);
+                throw err;
+            }
+            throw e;
+        }
+    }
+    failedAttempt(n, candidate, providerName, failureReason, statusCode, sanitizedError, latencyMs, ttftMs, upstreamRequestId) {
+        const now = new Date().toISOString();
+        return {
+            attemptNumber: n,
+            providerId: candidate.providerId,
+            modelId: candidate.modelId,
+            providerName,
+            startedAt: now,
+            completedAt: now,
+            statusCode,
+            success: false,
+            latencyMs,
+            ttftMs,
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 },
+            streamStarted: false,
+            partialResponse: false,
+            selectionReason: 'candidate',
+            failureReason,
+            sanitizedError,
+            upstreamRequestId,
+        };
+    }
+    getTargetCacheOverride(resolved) {
+        const db = getDb();
+        if (resolved.kind === 'model' && 'modelId' in resolved && resolved.modelId) {
+            const m = db.select().from(schema.models).where(eq(schema.models.id, resolved.modelId)).get();
+            return m?.cacheOverrideEnabled ?? null;
+        }
+        if (resolved.kind === 'combo' && 'comboId' in resolved && resolved.comboId) {
+            const c = db.select().from(schema.combos).where(eq(schema.combos.id, resolved.comboId)).get();
+            return c?.cacheOverrideEnabled ?? null;
+        }
+        return null;
+    }
+    getTargetConfigVersion(resolved) {
+        if (resolved.kind === 'combo' && 'comboId' in resolved && resolved.comboId) {
+            const db = getDb();
+            const c = db.select().from(schema.combos).where(eq(schema.combos.id, resolved.comboId)).get();
+            return c?.configVersion ?? 1;
+        }
+        return 1;
+    }
+    resolvedId(resolved) {
+        if (resolved.kind === 'model' && resolved.modelId)
+            return resolved.modelId;
+        if (resolved.kind === 'combo' && resolved.comboId)
+            return resolved.comboId;
+        return '';
+    }
+    buildCachedPayload(req, ctx, outcome) {
+        // Encode canonical outcome into the originating protocol's JSON response shape.
+        if (req.protocol === 'openai') {
+            return {
+                id: `chatcmpl-${ctx.requestId}`,
+                object: 'chat.completion',
+                created: Math.floor(Date.now() / 1000),
+                model: req.canonical.model,
+                choices: [
+                    {
+                        index: 0,
+                        message: {
+                            role: 'assistant',
+                            content: outcome.text,
+                            ...(outcome.toolCalls && outcome.toolCalls.length ? { tool_calls: outcome.toolCalls.map((tc) => ({ id: tc.id, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.input) } })) } : {}),
+                        },
+                        finish_reason: outcome.finishReason,
+                    },
+                ],
+                usage: {
+                    prompt_tokens: outcome.usage.input,
+                    completion_tokens: outcome.usage.output,
+                    total_tokens: outcome.usage.total,
+                },
+            };
+        }
+        return {
+            id: `msg_${ctx.requestId}`,
+            type: 'message',
+            role: 'assistant',
+            model: req.canonical.model,
+            content: [
+                ...(outcome.text ? [{ type: 'text', text: outcome.text }] : []),
+                ...(outcome.toolCalls ?? []).map((tc) => ({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.input })),
+            ],
+            stop_reason: outcome.finishReason,
+            usage: {
+                input_tokens: outcome.usage.input,
+                output_tokens: outcome.usage.output,
+                cache_read_input_tokens: outcome.usage.cacheRead,
+                cache_creation_input_tokens: outcome.usage.cacheWrite,
+            },
+        };
+    }
+    cachedToOutcome(payload, usage, ctx, resolved, start) {
+        const p = payload;
+        let text = '';
+        let toolCalls = [];
+        let finishReason = null;
+        if (p.choices) {
+            const c = p.choices[0];
+            text = c?.message?.content ?? '';
+            toolCalls = (c?.message?.tool_calls ?? []).map((tc) => ({ id: tc.id, name: tc.function.name, input: safeJsonParse(tc.function.arguments) }));
+            finishReason = c?.finish_reason ?? null;
+        }
+        else if (p.content) {
+            text = p.content.filter((b) => b.type === 'text').map((b) => b.text ?? '').join('');
+            toolCalls = p.content.filter((b) => b.type === 'tool_use').map((b) => ({ id: b.id ?? '', name: b.name ?? '', input: b.input ?? {} }));
+            finishReason = p.stop_reason ?? null;
+        }
+        const u = usage ? { ...usage, total: usage.total ?? usage.input + usage.output } : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
+        return {
+            success: true,
+            httpStatus: 200,
+            errorType: null,
+            errorMessage: null,
+            text,
+            toolCalls,
+            finishReason,
+            usage: u,
+            ttftMs: 0,
+            latencyMs: Date.now() - start,
+            attempts: [],
+            finalModelId: resolved.kind === 'model' && 'modelId' in resolved ? resolved.modelId ?? null : null,
+            resolvedTargetKind: resolved.kind,
+            resolvedTargetId: null,
+            gatewayCacheHit: true,
+            streamEvents: null,
+        };
+    }
+    async persistRequest(req, ctx, resolved, outcome, usage, attempts, cacheHit) {
+        const db = getDb();
+        const settings = getSettings();
+        const requestId = ctx.requestId;
+        const now = new Date().toISOString();
+        let requestPayload = null;
+        let responsePayload = null;
+        if (settings.contentLogMode === 'prompt' || settings.contentLogMode === 'prompt_and_response') {
+            requestPayload = JSON.stringify(redactValue(req.canonical));
+        }
+        if (settings.contentLogMode === 'prompt_and_response') {
+            responsePayload = JSON.stringify(redactValue({ text: outcome.text, toolCalls: outcome.toolCalls, finishReason: outcome.finishReason }));
+        }
+        db.insert(schema.requests).values({
+            id: requestId,
+            createdAt: now,
+            completedAt: now,
+            apiKeyId: ctx.key?.id ?? null,
+            keyPrefixSnapshot: ctx.key?.keyPrefix ?? null,
+            clientIp: ctx.clientIp,
+            protocol: ctx.protocol,
+            endpoint: req.endpoint,
+            requestedModel: req.canonical.model,
+            resolvedTargetKind: outcome.resolvedTargetKind,
+            resolvedTargetId: outcome.resolvedTargetId,
+            finalModelId: outcome.finalModelId,
+            streaming: req.canonical.stream,
+            httpStatus: outcome.httpStatus,
+            success: outcome.success ? 1 : 0,
+            totalLatencyMs: outcome.latencyMs,
+            ttftMs: outcome.ttftMs,
+            inputTokens: usage.input,
+            outputTokens: usage.output,
+            cacheReadTokens: usage.cacheRead,
+            cacheWriteTokens: usage.cacheWrite,
+            reasoningTokens: usage.reasoning,
+            totalTokens: usage.total,
+            attemptsCount: attempts.length,
+            errorType: outcome.errorType,
+            errorMessage: outcome.errorMessage ? redactString(outcome.errorMessage) : null,
+            requestPayloadJson: requestPayload,
+            responsePayloadJson: responsePayload,
+            gatewayCacheHit: cacheHit ? true : false,
+        }).run();
+        for (const a of attempts) {
+            db.insert(schema.requestAttempts).values({
+                id: uuid(),
+                requestId,
+                attemptNumber: a.attemptNumber,
+                providerId: a.providerId,
+                modelId: a.modelId,
+                startedAt: a.startedAt,
+                completedAt: a.completedAt,
+                statusCode: a.statusCode,
+                success: a.success,
+                latencyMs: a.latencyMs,
+                ttftMs: a.ttftMs,
+                inputTokens: a.usage.input,
+                outputTokens: a.usage.output,
+                cacheReadTokens: a.usage.cacheRead,
+                cacheWriteTokens: a.usage.cacheWrite,
+                reasoningTokens: a.usage.reasoning,
+                streamStarted: a.streamStarted ? 1 : 0,
+                partialResponse: a.partialResponse ? 1 : 0,
+                selectionReason: a.selectionReason,
+                failureReason: a.failureReason,
+                errorMessage: a.sanitizedError ? redactString(a.sanitizedError) : null,
+                upstreamRequestId: a.upstreamRequestId,
+            }).run();
+        }
+    }
+}
+function classifyFailure(err) {
+    switch (err.type) {
+        case 'timeout_error':
+            return err.message.includes('first token') ? 'first_token_timeout' : 'connect_timeout';
+        case 'upstream_unavailable':
+            return 'connection_error';
+        case 'upstream_rate_limit':
+            return 'http_status';
+        case 'upstream_error':
+            return err.status >= 500 ? 'http_status' : 'connection_error';
+        default:
+            return 'unknown';
+    }
+}
+function hasTools(req) {
+    if (req.tools && req.tools.length > 0)
+        return true;
+    for (const m of req.messages) {
+        for (const b of m.content) {
+            if (b.type === 'tool_use' || b.type === 'tool_result')
+                return true;
+        }
+    }
+    return false;
+}
+function estimateTokens(s) {
+    return Math.ceil(s.length / 4);
+}
+function safeJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return {};
+    }
+}
+function safeJsonParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+function usageFromCache(u) {
+    return u ? { ...u, total: u.input + u.output } : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
+}
+// SSE encoders: canonical stream chunk -> client protocol event
+function openaiStreamEncoder(data, _event) {
+    if (data === '[DONE]')
+        return 'data: [DONE]\n\n';
+    return `data: ${data}\n\n`;
+}
+function anthropicStreamEncoder(data, _event) {
+    if (data === '[DONE]')
+        return 'data: [DONE]\n\n';
+    return `data: ${data}\n\n`;
+}