infinicode 2.3.4 → 2.3.6

package/dist/kernel/gateway/openai-gateway.js

@@ -0,0 +1,723 @@
+/**
+ * OpenKernel — OpenAI-compatible Gateway
+ *
+ * A local HTTP endpoint (`/v1/chat/completions`, `/v1/models`) that sits between
+ * the opencode TUI (the Harness) and the real LLM providers. Every chat turn the
+ * TUI makes flows THROUGH the kernel, so the interactive path gains full 1:1
+ * parity with the headless mission path:
+ *
+ *   • routing        — CapabilityRouter.rank() picks the best model per request
+ *                      (model "auto"), honoring the active policy + benchmarks.
+ *   • escalation     — on a provider error (e.g. Groq 400 "tool_use_failed"),
+ *                      RecoveryManager.classify() + router.escalate() swap to a
+ *                      stronger model (or rotate provider) and retry, transparently.
+ *   • health/quota   — recordSuccess/recordFailure/record429 feed the pool.
+ *   • telemetry      — MODEL_CHANGED / PROVIDER_CHANGED / RECOVERY events fire on
+ *                      the kernel bus, so /activity + the mesh see TUI traffic.
+ *
+ * Because the TUI *and* every upstream speak the OpenAI wire format, the gateway
+ * is a TRANSPARENT RELAY: it forwards messages/tools/tool_choice verbatim and
+ * streams the response back byte-for-byte, only choosing WHICH provider+model to
+ * hit. The kernel is purely the routing/recovery brain — no lossy re-encoding.
+ *
+ * The provider CALL is isolated behind the ProviderExecutor interface. The default
+ * FetchExecutor calls the upstream directly; a BifrostExecutor (or any other
+ * execution plane) can be dropped in later without touching the routing logic.
+ */
+import { createServer } from 'node:http';
+/** Default executor: call the upstream OpenAI-compatible endpoint directly. */
+export class FetchExecutor {
+    async execute(target, body, signal) {
+        const headers = { 'content-type': 'application/json' };
+        if (target.apiKey)
+            headers['authorization'] = `Bearer ${target.apiKey}`;
+        Object.assign(headers, target.headers ?? {}); // custom headers win (e.g. non-Authorization key header)
+        const url = `${target.baseURL.replace(/\/+$/, '')}/chat/completions`;
+        return fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal });
+    }
+}
+// Keep swapping models until one succeeds (or the pool is exhausted). A weak
+// model hallucinating a tool call must never stop the flow — it just triggers
+// the next escalation. Bounded only to cap worst-case latency on huge pools;
+// the loop also exits early the moment nextTarget() runs out of untried models.
+const MAX_ATTEMPTS = 8;
+const MODELS_TTL_MS = 30_000;
+// Stall guards — a provider that accepts the request then goes silent must not
+// hang the TUI forever. Time out and swap instead.
+const HEADERS_TIMEOUT_MS = 60_000; //     to receive response headers
+const FIRST_CHUNK_TIMEOUT_MS = 120_000; // to first streamed byte (reasoning models are slow to start)
+const IDLE_TIMEOUT_MS = 60_000; //        max silence BETWEEN chunks before we call it stalled
+// Never buffer more than this many SSE frames while looking for a commit point —
+// past it, start streaming regardless so the user always sees output flowing
+// (prevents a whole long generation from being withheld until the very end).
+const FLUSH_AFTER_FRAMES = 6;
+/** Extract the concatenated `data:` payload from one SSE frame (or null). */
+function sseData(frame) {
+    const lines = frame.split('\n').filter(l => l.startsWith('data:'));
+    if (lines.length === 0)
+        return null;
+    return lines.map(l => l.slice(5).trimStart()).join('');
+}
+export class KernelGateway {
+    opts;
+    server;
+    table = new Map();
+    executor;
+    boundPort = 0;
+    modelsCache;
+    constructor(opts) {
+        this.opts = opts;
+        for (const p of opts.providers)
+            this.table.set(p.id, p);
+        this.executor = opts.executor ?? new FetchExecutor();
+    }
+    get port() {
+        return this.boundPort;
+    }
+    get url() {
+        return `http://${this.opts.host ?? '127.0.0.1'}:${this.boundPort}/v1`;
+    }
+    /**
+     * Start listening. Scans ports [port .. port+20] then falls back to an OS-chosen
+     * ephemeral port. Retries past BOTH EADDRINUSE (a lingering session holds it) and
+     * EACCES (a Windows excluded/reserved range) — never dies on a single bad port,
+     * since the whole point is that the gateway must come up so the TUI gets routing.
+     */
+    async start() {
+        const host = this.opts.host ?? '127.0.0.1';
+        const first = this.opts.port ?? 47915;
+        let lastErr;
+        for (let candidate = first; candidate <= first + 20; candidate++) {
+            try {
+                await this.listen(host, candidate);
+                this.opts.logger.info(`[gateway] OpenAI-compatible endpoint on ${host}:${this.boundPort} (${this.table.size} providers)`);
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                const code = err.code;
+                if (code !== 'EADDRINUSE' && code !== 'EACCES')
+                    break; // unexpected — stop scanning, try ephemeral
+            }
+        }
+        // Last resort: let the OS pick any free port (bulletproof against reserved ranges).
+        try {
+            await this.listen(host, 0);
+            this.opts.logger.info(`[gateway] OpenAI-compatible endpoint on ${host}:${this.boundPort} (ephemeral, ${this.table.size} providers)`);
+            return;
+        }
+        catch (err) {
+            throw lastErr ?? err;
+        }
+    }
+    listen(host, port) {
+        return new Promise((resolve, reject) => {
+            const server = createServer((req, res) => void this.handle(req, res));
+            server.once('error', reject);
+            server.listen(port, host, () => {
+                server.off('error', reject);
+                this.server = server;
+                const addr = server.address();
+                this.boundPort = typeof addr === 'object' && addr ? addr.port : port;
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        if (this.server) {
+            await new Promise(resolve => this.server.close(() => resolve()));
+            this.server = undefined;
+        }
+    }
+    // ── HTTP ────────────────────────────────────────────────────────────────────
+    async handle(req, res) {
+        const url = req.url ?? '/';
+        try {
+            if (req.method === 'GET' && (url.startsWith('/v1/models') || url === '/v1' || url === '/')) {
+                this.sendJson(res, 200, this.listModels());
+                return;
+            }
+            if (req.method === 'POST' && url.startsWith('/v1/chat/completions')) {
+                const body = JSON.parse(await this.readBody(req));
+                await this.handleChat(body, res);
+                return;
+            }
+            this.sendJson(res, 404, { error: { message: 'not found', type: 'invalid_request_error' } });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.opts.logger.warn(`[gateway] ${message}`);
+            if (!res.headersSent)
+                this.sendJson(res, 500, { error: { message, type: 'gateway_error' } });
+            else
+                try {
+                    res.end();
+                }
+                catch { /* ignore */ }
+        }
+    }
+    listModels() {
+        const data = [
+            { id: 'auto', object: 'model', created: 0, owned_by: 'infinicode' },
+        ];
+        for (const p of this.table.values()) {
+            for (const m of p.models)
+                data.push({ id: `${p.id}/${m.id}`, object: 'model', created: 0, owned_by: p.id });
+        }
+        return { object: 'list', data };
+    }
+    // ── Chat: route → execute → validate → swap-on-failure → relay ──────────────
+    async handleChat(body, res) {
+        const stream = body['stream'] === true;
+        const messages = Array.isArray(body['messages']) ? body['messages'] : [];
+        const estTokens = Math.ceil(JSON.stringify(messages).length / 4);
+        const requested = typeof body['model'] === 'string' ? body['model'] : '';
+        const toolNames = this.allowedTools(body);
+        const tried = new Set();
+        let target = await this.resolveTarget(requested, estTokens, tried);
+        if (!target) {
+            this.sendJson(res, 503, { error: { message: 'no providers available', type: 'gateway_error' } });
+            return;
+        }
+        const controller = new AbortController();
+        res.on('close', () => controller.abort());
+        let lastStatus = 502;
+        let lastErr = 'no attempt made';
+        // `currentBody` may become a continuation request (original messages + the
+        // partial answer as an assistant prefix). `carried` is the whole answer
+        // streamed so far, accumulated across however many providers died mid-task.
+        let currentBody = body;
+        let carried = '';
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS && target; attempt++) {
+            tried.add(`${target.providerId}/${target.model}`);
+            const upstream = { ...currentBody, model: target.model, stream };
+            const outcome = await this.attempt(target, upstream, res, stream, toolNames, controller);
+            // Clean completion (streamed finish, or any non-stream response).
+            if (outcome.forwarded && outcome.complete !== false) {
+                this.opts.kernel.providerManager.recordSuccess(target.providerId);
+                return;
+            }
+            if (outcome.aborted)
+                return; // client hung up — nothing to do
+            // Mid-stream truncation: the provider streamed part of the answer then died
+            // (finish_reason:length, dropped connection, or went idle). We can't swap
+            // cleanly — the client already has the partial — so CONTINUE from it with a
+            // fresh model. This is the "long task never just stops" guarantee.
+            if (outcome.truncated && outcome.committed) {
+                carried += outcome.assembled ?? '';
+                this.opts.logger.warn(`[gateway] truncated on ${target.providerId}/${target.model} (${outcome.finishReason ?? '?'}) — continuing from ${carried.length} chars`);
+                this.opts.kernel.providerManager.penalize?.(target.providerId, 'provider-down');
+                const next = await this.nextTarget(target, `truncated ${outcome.finishReason ?? ''}`, estTokens, tried);
+                if (!next) {
+                    this.endStream(res);
+                    return;
+                } // pool spent — close cleanly, don't hang
+                currentBody = this.buildContinuation(body, carried);
+                this.emitSwitch(target, next, 'continue after truncation');
+                target = next;
+                continue;
+            }
+            // Committed but failed in a way we can't continue from — end the open stream
+            // gracefully instead of trying to send an error over it.
+            if (outcome.committed) {
+                this.opts.logger.warn(`[gateway] committed stream failed on ${target.providerId}/${target.model}: ${outcome.error}`);
+                this.endStream(res);
+                return;
+            }
+            // Pre-commit failure — nothing sent yet, swap cleanly to the next model.
+            lastStatus = outcome.status;
+            lastErr = outcome.error;
+            this.recordError(target.providerId, outcome.status, outcome.error);
+            const next = await this.nextTarget(target, `${lastStatus} ${lastErr}`, estTokens, tried);
+            if (!next)
+                break;
+            this.emitSwitch(target, next, `${lastStatus} ${lastErr}`);
+            target = next;
+        }
+        if (!res.headersSent) {
+            this.sendJson(res, lastStatus >= 400 ? lastStatus : 502, {
+                error: { message: `all routes failed: ${lastErr}`, type: 'gateway_error' },
+            });
+        }
+        else {
+            this.endStream(res); // exhausted attempts mid-stream — close so the TUI doesn't hang
+        }
+    }
+    /**
+     * Build a continuation request: the original messages plus the partial answer as
+     * an assistant prefix so a fresh model resumes it instead of restarting. `prefix:
+     * true` is the continue-this-message convention (DeepSeek/Mistral/Zhipu/Qwen);
+     * providers that ignore it at worst restart — still better than a dead task.
+     */
+    buildContinuation(body, assembled) {
+        const base = Array.isArray(body['messages']) ? body['messages'] : [];
+        const messages = assembled.length > 0
+            ? [...base, { role: 'assistant', content: assembled, prefix: true }]
+            : [...base];
+        return { ...body, messages };
+    }
+    /** Close an already-open SSE stream with a synthetic clean finish so the client
+     *  gets a proper end-of-turn instead of hanging on a half-open connection. */
+    endStream(res) {
+        try {
+            if (!res.headersSent) {
+                res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+            }
+            if (!res.writableEnded) {
+                res.write('data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\n');
+                res.write('data: [DONE]\n\n');
+                res.end();
+            }
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Run one model. Returns forwarded:true only after the response is validated
+     * and sent to the client; otherwise nothing is written to `res` and the caller
+     * swaps to the next model. Catches BOTH transport failures (non-2xx) AND bad
+     * tool calls the model streams back on a 200 (a weak model naming a tool that
+     * isn't in request.tools — e.g. `glob={...}` — which downstream would reject).
+     */
+    async attempt(target, upstream, res, stream, toolNames, controller) {
+        // Per-attempt controller: aborts on client close OR our stall timeouts, so a
+        // silent provider can't hang the request. Linked to the parent controller.
+        const ctrl = new AbortController();
+        const onParentAbort = () => ctrl.abort();
+        if (controller.signal.aborted)
+            ctrl.abort();
+        else
+            controller.signal.addEventListener('abort', onParentAbort, { once: true });
+        const cleanup = () => controller.signal.removeEventListener('abort', onParentAbort);
+        let resp;
+        const headersTimer = setTimeout(() => ctrl.abort(), this.opts.headersTimeoutMs ?? HEADERS_TIMEOUT_MS);
+        try {
+            resp = await this.executor.execute(target, upstream, ctrl.signal);
+        }
+        catch (err) {
+            clearTimeout(headersTimer);
+            cleanup();
+            if (controller.signal.aborted)
+                return { forwarded: false, status: 0, error: 'aborted', aborted: true };
+            return { forwarded: false, status: 504, error: `connect/headers timeout: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        clearTimeout(headersTimer);
+        if (!resp.ok) {
+            cleanup();
+            const text = await resp.text().catch(() => `${resp.status}`);
+            return { forwarded: false, status: resp.status, error: text };
+        }
+        const ctype = resp.headers.get('content-type') ?? '';
+        if (stream && ctype.includes('text/event-stream') && resp.body) {
+            const out = await this.streamValidated(resp, res, toolNames, controller, ctrl);
+            cleanup();
+            return out;
+        }
+        // Non-streaming (or a provider that returned plain JSON despite stream=true).
+        try {
+            const text = await resp.text();
+            let parsed = null;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch { /* leave null */ }
+            const bad = this.validateResponse(parsed, toolNames);
+            if (bad)
+                return { forwarded: false, status: 200, error: bad };
+            res.writeHead(resp.status, { 'content-type': ctype || 'application/json' });
+            res.end(text);
+            return { forwarded: true, status: resp.status, error: '' };
+        }
+        finally {
+            cleanup();
+        }
+    }
+    /**
+     * Relay an SSE stream, but with a small look-ahead: buffer frames until the
+     * first tool-call name or content delta. If that first tool call names a tool
+     * not in request.tools (or an error frame arrives), fail WITHOUT writing to the
+     * client so the caller can swap models. Once a valid start is seen, commit and
+     * stream the rest live (so large generations still stream token-by-token).
+     */
+    async streamValidated(resp, res, toolNames, parentCtrl, ctrl) {
+        const reader = resp.body.getReader();
+        const decoder = new TextDecoder();
+        let raw = '';
+        let committed = res.headersSent; // a prior (continuation) attempt already opened the stream
+        let started = false;
+        // Terminal frames (a finish_reason marker or `[DONE]`) are HELD, not written
+        // live: if the stream turns out truncated we must NOT send a finish/[DONE] to
+        // the client (that would end the turn) — we swap and continue instead. On a
+        // clean finish we flush them so the client sees a proper end.
+        const held = [];
+        let assembled = ''; // visible answer text so far (for continuation prefix)
+        let finishReason = null;
+        let sawDone = false;
+        let sawToolCall = false;
+        const pending = [];
+        const commit = () => {
+            if (!res.headersSent) {
+                res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+            }
+            for (const p of pending)
+                res.write(p);
+            pending.length = 0;
+            committed = true;
+        };
+        // What did this stream actually do? Distinguishes "done for real" from
+        // "cut off mid-answer", which is the whole point of continuation.
+        const classify = (endReason) => {
+            const clean = sawToolCall
+                || finishReason === 'stop'
+                || finishReason === 'tool_calls'
+                || (sawDone && finishReason !== 'length');
+            if (clean) {
+                // Real completion — flush the held terminal frames + trailing partial.
+                if (!committed)
+                    commit();
+                for (const h of held)
+                    res.write(h);
+                if (raw)
+                    res.write(raw);
+                if (!res.writableEnded)
+                    res.end();
+                return { forwarded: true, status: 200, error: '', committed: true, complete: true, assembled };
+            }
+            // Never committed anything and the stream is already over → clean swap
+            // (nothing was sent to the client, so the caller can retry from scratch).
+            if (!committed && assembled.length === 0) {
+                return { forwarded: false, status: endReason === 'done' ? 502 : 504, error: `truncated before any output (${endReason}${finishReason ? ' ' + finishReason : ''})` };
+            }
+            // Committed + truncated (finish_reason:length, dropped connection, or idle
+            // stall). We've already streamed part of the answer, so we CANNOT swap
+            // cleanly — signal the caller to CONTINUE from `assembled` with a fresh model.
+            if (!committed)
+                commit(); // flush what we buffered so the client sees it
+            return {
+                forwarded: false, status: 0, error: `stream truncated (${endReason}${finishReason ? ' ' + finishReason : ''})`,
+                committed: true, complete: false, assembled, truncated: true, finishReason: finishReason ?? endReason,
+            };
+        };
+        for (;;) {
+            // Race each read against a stall timeout (longer for the first token). On a
+            // stall we abort the upstream and — if nothing has been sent yet — swap.
+            const limit = started
+                ? (this.opts.idleTimeoutMs ?? IDLE_TIMEOUT_MS)
+                : (this.opts.firstChunkTimeoutMs ?? FIRST_CHUNK_TIMEOUT_MS);
+            let timer;
+            const readP = reader.read().then(r => ({ r })).catch(e => ({ err: e }));
+            const outcome = await Promise.race([
+                readP,
+                new Promise(resolve => { timer = setTimeout(() => resolve({ idle: true }), limit); }),
+            ]);
+            clearTimeout(timer);
+            if ('idle' in outcome) {
+                ctrl.abort();
+                try {
+                    await reader.cancel();
+                }
+                catch { /* ignore */ }
+                if (!committed) {
+                    return { forwarded: false, status: 504, error: `upstream stalled (${started ? 'idle' : 'no first token'} >${limit / 1000}s)` };
+                }
+                return classify('idle'); // streaming already started — continue from partial
+            }
+            if ('err' in outcome) {
+                if (parentCtrl.signal.aborted)
+                    return { forwarded: false, status: 0, error: 'aborted', aborted: true };
+                if (!committed)
+                    return { forwarded: false, status: 502, error: outcome.err instanceof Error ? outcome.err.message : String(outcome.err) };
+                return classify('err');
+            }
+            const { done, value } = outcome.r;
+            if (done)
+                return classify('done');
+            started = true;
+            raw += decoder.decode(value, { stream: true });
+            const parts = raw.split('\n\n');
+            raw = parts.pop() ?? '';
+            for (const frame of parts) {
+                const payload = frame + '\n\n';
+                const verdict = this.inspectFrame(frame, toolNames);
+                // Track completion signals + accumulate the visible answer for continuation.
+                if (verdict.done)
+                    sawDone = true;
+                if (verdict.toolCall)
+                    sawToolCall = true;
+                if (verdict.finishReason)
+                    finishReason = verdict.finishReason;
+                if (verdict.content)
+                    assembled += verdict.content;
+                if (!committed) {
+                    if (verdict.error) {
+                        try {
+                            await reader.cancel();
+                        }
+                        catch { /* ignore */ }
+                        return { forwarded: false, status: 200, error: verdict.error };
+                    }
+                    if (verdict.commit || pending.length >= FLUSH_AFTER_FRAMES)
+                        commit();
+                }
+                // Hold terminal frames (finish/`[DONE]`) so a truncation can suppress them;
+                // stream everything else live.
+                if (verdict.terminal) {
+                    held.push(payload);
+                    continue;
+                }
+                if (committed)
+                    res.write(payload);
+                else
+                    pending.push(payload);
+            }
+        }
+    }
+    /**
+     * Classify one SSE frame: does it error, is it a safe commit point, is it a
+     * TERMINAL frame (finish_reason / `[DONE]` — held back so a truncation can be
+     * continued), and what visible content does it carry (accumulated so a fresh
+     * model can continue the answer from where a dead provider left off)?
+     */
+    inspectFrame(frame, toolNames) {
+        const data = sseData(frame);
+        if (!data)
+            return { commit: false };
+        if (data === '[DONE]')
+            return { commit: true, terminal: true, done: true }; // end of stream
+        let obj = null;
+        try {
+            obj = JSON.parse(data);
+        }
+        catch {
+            return { commit: false };
+        }
+        if (obj && obj['error']) {
+            const e = obj['error'];
+            return { commit: false, error: typeof e === 'string' ? e : JSON.stringify(e) };
+        }
+        const choice = obj?.choices?.[0];
+        const delta = choice?.delta;
+        const finish = choice?.finish_reason;
+        const finishReason = typeof finish === 'string' && finish.length > 0 ? finish : undefined;
+        const tcName = delta?.tool_calls?.[0]?.function?.name;
+        if (typeof tcName === 'string' && tcName.length > 0) {
+            if (toolNames.size > 0 && !toolNames.has(tcName)) {
+                return { commit: false, error: `tool call validation failed: '${tcName}' was not in request.tools` };
+            }
+            return { commit: true, toolCall: true, finishReason };
+        }
+        // Only real answer text (delta.content) feeds the continuation prefix; reasoning
+        // tokens are internal and must not be replayed as the assistant's answer.
+        const visible = typeof delta?.content === 'string' ? delta.content : '';
+        const anyText = visible || (typeof delta?.reasoning_content === 'string' ? delta.reasoning_content : '')
+            || (typeof delta?.reasoning === 'string' ? delta.reasoning : '');
+        if (finishReason)
+            return { commit: true, terminal: true, finishReason, content: visible || undefined };
+        if (anyText.length > 0)
+            return { commit: true, content: visible || undefined };
+        return { commit: false };
+    }
+    /** Validate a non-streamed response body for unknown tool calls / errors. */
+    validateResponse(parsed, toolNames) {
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const obj = parsed;
+        if (obj['error']) {
+            const e = obj['error'];
+            return typeof e === 'string' ? e : JSON.stringify(e);
+        }
+        if (toolNames.size === 0)
+            return null;
+        const calls = obj
+            ?.choices?.[0]?.message?.tool_calls;
+        if (Array.isArray(calls)) {
+            for (const c of calls) {
+                const n = c?.function?.name;
+                if (typeof n === 'string' && !toolNames.has(n)) {
+                    return `tool call validation failed: '${n}' was not in request.tools`;
+                }
+            }
+        }
+        return null;
+    }
+    /** The set of tool names the request declared (OpenAI tools[].function.name). */
+    allowedTools(body) {
+        const set = new Set();
+        const tools = body['tools'];
+        if (Array.isArray(tools)) {
+            for (const t of tools) {
+                const n = t?.function?.name ?? t?.name;
+                if (typeof n === 'string')
+                    set.add(n);
+            }
+        }
+        return set;
+    }
+    // ── Routing helpers ──────────────────────────────────────────────────────────
+    /** Resolve the initial target: honor an explicit provider/model, else route. */
+    async resolveTarget(requested, estTokens, tried) {
+        const raw = requested.trim();
+        const isAuto = raw === '' || raw === 'auto' || raw === 'infinicode/auto' || raw.endsWith('/auto');
+        if (!isAuto) {
+            const slash = raw.indexOf('/');
+            if (slash > 0) {
+                const providerId = raw.slice(0, slash);
+                const modelId = raw.slice(slash + 1);
+                const gp = this.table.get(providerId);
+                if (gp)
+                    return this.toTarget(gp, modelId);
+            }
+            // bare model id — find its owner
+            for (const gp of this.table.values()) {
+                if (gp.models.some(m => m.id === raw))
+                    return this.toTarget(gp, raw);
+            }
+        }
+        return this.routerPick(estTokens, tried);
+    }
+    /** Ask the kernel router for the best untried, executable model. */
+    async routerPick(estTokens, tried) {
+        const ranked = await this.rank(estTokens);
+        for (const d of ranked) {
+            const gp = this.table.get(d.providerId);
+            if (gp && !tried.has(`${d.providerId}/${d.modelId}`))
+                return this.toTarget(gp, d.modelId);
+        }
+        // last resort: first configured model not yet tried
+        for (const gp of this.table.values()) {
+            for (const m of gp.models) {
+                if (!tried.has(`${gp.id}/${m.id}`))
+                    return this.toTarget(gp, m.id);
+            }
+        }
+        return null;
+    }
+    /**
+     * Choose the next target after a failure. 429 / provider-down → rotate to a
+     * different provider; everything else (incl. Groq's tool_use_failed) →
+     * escalate to a stronger model via the kernel ladder, then fall back to rank.
+     */
+    async nextTarget(current, errText, estTokens, tried) {
+        const kind = this.opts.kernel.recovery.classify(errText);
+        const ranked = await this.rank(estTokens);
+        const usable = ranked.filter(d => this.table.has(d.providerId) && !tried.has(`${d.providerId}/${d.modelId}`));
+        // Provider-level failures (rate limit, credits, bad key, outage, filter) →
+        // move to a DIFFERENT provider; escalating to a bigger model on the same dead
+        // provider would just fail again.
+        const rotateKinds = new Set(['429', 'provider-down', 'quota-exhausted', 'auth-failure', 'content-filter']);
+        if (rotateKinds.has(kind)) {
+            const diffProvider = usable.find(d => d.providerId !== current.providerId);
+            if (diffProvider)
+                return this.toTarget(this.table.get(diffProvider.providerId), diffProvider.modelId);
+            if (usable[0])
+                return this.toTarget(this.table.get(usable[0].providerId), usable[0].modelId);
+            // Ranking gave nothing usable — still rotate to ANY untried provider/model.
+            return this.firstUntried(tried, current.providerId) ?? this.firstUntried(tried);
+        }
+        // escalate: strictly stronger model than the current one
+        const esc = this.opts.kernel.router.escalate(await this.routingRequest(estTokens), current.providerId, current.model);
+        if (esc && this.table.has(esc.providerId) && !tried.has(`${esc.providerId}/${esc.modelId}`)) {
+            return this.toTarget(this.table.get(esc.providerId), esc.modelId);
+        }
+        if (usable[0])
+            return this.toTarget(this.table.get(usable[0].providerId), usable[0].modelId);
+        // Last resort: ANY configured model not yet tried, so a swap/continuation never
+        // dead-ends just because the router couldn't rank (e.g. providers not yet
+        // health-verified at session start). Prefer a different provider.
+        return this.firstUntried(tried, current.providerId) ?? this.firstUntried(tried);
+    }
+    /** First configured provider/model not in `tried` (optionally skipping a provider). */
+    firstUntried(tried, exceptProvider) {
+        for (const gp of this.table.values()) {
+            if (exceptProvider && gp.id === exceptProvider)
+                continue;
+            for (const m of gp.models)
+                if (!tried.has(`${gp.id}/${m.id}`))
+                    return this.toTarget(gp, m.id);
+        }
+        return null;
+    }
+    toTarget(gp, model) {
+        return { providerId: gp.id, baseURL: gp.baseURL, apiKey: gp.apiKey, headers: gp.headers, model };
+    }
+    async rank(estTokens) {
+        try {
+            return this.opts.kernel.router.rank(await this.routingRequest(estTokens));
+        }
+        catch {
+            return [];
+        }
+    }
+    async routingRequest(estTokens) {
+        const kernel = this.opts.kernel;
+        const now = Date.now();
+        if (!this.modelsCache || now - this.modelsCache.at > MODELS_TTL_MS) {
+            this.modelsCache = { at: now, models: await kernel.providerManager.getAvailableModels() };
+        }
+        const policy = kernel.policies.get(this.opts.policyName);
+        return {
+            capabilities: this.opts.capabilities ?? ['coding', 'reasoning'],
+            preferences: { reasoning: 88, speed: 70, cost: 'medium', contextLength: Math.max(16_000, estTokens * 2) },
+            policy,
+            availableProviders: kernel.providerManager.listInfos(),
+            availableModels: this.modelsCache.models,
+            estimatedRequestTokens: estTokens,
+            minBenchmark: this.opts.minBenchmark,
+        };
+    }
+    // ── Telemetry / health ───────────────────────────────────────────────────────
+    recordError(providerId, status, error) {
+        const kind = this.opts.kernel.recovery.classify(`${status} ${error}`);
+        if (status === 429 || kind === '429')
+            this.opts.kernel.providerManager.record429(providerId);
+        else
+            this.opts.kernel.providerManager.recordFailure(providerId);
+        // Cooldown credits/auth/outage providers so the NEXT turns skip them too
+        // (not just this request's retry loop). tool/context failures cool down 0ms.
+        this.opts.kernel.providerManager.penalize(providerId, kind, `${kind}: ${error.slice(0, 120)}`);
+        this.modelsCache = undefined; // reflect the cooldown in the next routing pass
+        this.opts.kernel.eventBus.emit({
+            type: 'RECOVERY',
+            timestamp: Date.now(),
+            data: { source: 'gateway', providerId, status, kind, error: error.slice(0, 300) },
+        });
+    }
+    emitSwitch(from, to, reason) {
+        const bus = this.opts.kernel.eventBus;
+        if (from.providerId !== to.providerId) {
+            bus.emit({
+                type: 'PROVIDER_CHANGED',
+                timestamp: Date.now(),
+                data: { source: 'gateway', previousProviderId: from.providerId, providerId: to.providerId, reason: reason.slice(0, 200) },
+            });
+        }
+        bus.emit({
+            type: 'MODEL_CHANGED',
+            timestamp: Date.now(),
+            data: {
+                source: 'gateway',
+                previousModelId: `${from.providerId}/${from.model}`,
+                modelId: `${to.providerId}/${to.model}`,
+                providerId: to.providerId,
+                reason: reason.slice(0, 200),
+            },
+        });
+        this.opts.logger.info(`[gateway] ${from.providerId}/${from.model} → ${to.providerId}/${to.model}`);
+    }
+    // ── IO ────────────────────────────────────────────────────────────────────────
+    sendJson(res, status, body) {
+        res.writeHead(status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(body));
+    }
+    readBody(req) {
+        return new Promise((resolve, reject) => {
+            let data = '';
+            req.on('data', chunk => {
+                data += chunk;
+                if (data.length > 32_000_000)
+                    reject(new Error('body too large'));
+            });
+            req.on('end', () => resolve(data));
+            req.on('error', reject);
+        });
+    }
+}