infinicode 2.3.5 → 2.4.0

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

@@ -36,8 +36,28 @@ export class FetchExecutor {
         return fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal });
     }
 }
-const MAX_ATTEMPTS = 4;
+// 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;
@@ -57,25 +77,38 @@ export class KernelGateway {
     get url() {
         return `http://${this.opts.host ?? '127.0.0.1'}:${this.boundPort}/v1`;
     }
-    /** Start listening. Scans ports [port .. port+10] to avoid collisions. */
+    /**
+     * 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 + 10; candidate++) {
+        for (let candidate = first; candidate <= first + 20; candidate++) {
             try {
                 await this.listen(host, candidate);
-                this.boundPort = candidate;
-                this.opts.logger.info(`[gateway] OpenAI-compatible endpoint on ${host}:${candidate} (${this.table.size} providers)`);
+                this.opts.logger.info(`[gateway] OpenAI-compatible endpoint on ${host}:${this.boundPort} (${this.table.size} providers)`);
                 return;
             }
             catch (err) {
                 lastErr = err;
-                if (err.code !== 'EADDRINUSE')
-                    throw err;
+                const code = err.code;
+                if (code !== 'EADDRINUSE' && code !== 'EACCES')
+                    break; // unexpected — stop scanning, try ephemeral
             }
         }
-        throw lastErr ?? new Error('gateway: no free port');
+        // 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) => {
@@ -84,6 +117,8 @@ export class KernelGateway {
             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();
             });
         });
@@ -131,12 +166,13 @@ export class KernelGateway {
         }
         return { object: 'list', data };
     }
-    // ── Chat: route → execute → escalate-on-error → relay ────────────────────────
+    // ── 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) {
@@ -147,27 +183,51 @@ export class KernelGateway {
         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 = { ...body, model: target.model, stream };
-            try {
-                const resp = await this.executor.execute(target, upstream, controller.signal);
-                if (resp.ok) {
-                    this.opts.kernel.providerManager.recordSuccess(target.providerId);
-                    await this.relay(resp, res, stream);
+            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;
-                }
-                lastStatus = resp.status;
-                lastErr = await resp.text().catch(() => `${resp.status}`);
-                this.recordError(target.providerId, resp.status, lastErr);
+                } // pool spent — close cleanly, don't hang
+                currentBody = this.buildContinuation(body, carried);
+                this.emitSwitch(target, next, 'continue after truncation');
+                target = next;
+                continue;
             }
-            catch (err) {
-                lastStatus = 502;
-                lastErr = err instanceof Error ? err.message : String(err);
-                if (controller.signal.aborted)
-                    return; // client hung up
-                this.recordError(target.providerId, 0, lastErr);
+            // 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;
@@ -179,28 +239,318 @@ export class KernelGateway {
                 error: { message: `all routes failed: ${lastErr}`, type: 'gateway_error' },
             });
         }
+        else {
+            this.endStream(res); // exhausted attempts mid-stream — close so the TUI doesn't hang
+        }
     }
-    /** Stream bytes through untouched, or relay the JSON body for non-streaming. */
-    async relay(resp, res, stream) {
-        if (stream && resp.body) {
-            res.writeHead(200, {
-                'content-type': resp.headers.get('content-type') ?? 'text/event-stream',
-                'cache-control': 'no-cache',
-                connection: 'keep-alive',
-            });
-            const reader = resp.body.getReader();
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                res.write(Buffer.from(value));
+    /**
+     * 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);
             }
-            res.end();
-            return;
         }
-        const text = await resp.text();
-        res.writeHead(resp.status, { 'content-type': resp.headers.get('content-type') ?? 'application/json' });
-        res.end(text);
+    }
+    /**
+     * 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. */
@@ -250,18 +600,41 @@ export class KernelGateway {
         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}`));
-        if (kind === '429' || kind === 'provider-down') {
+        // 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);
-            return usable[0] ? this.toTarget(this.table.get(usable[0].providerId), usable[0].modelId) : null;
+            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);
         }
-        return usable[0] ? this.toTarget(this.table.get(usable[0].providerId), usable[0].modelId) : null;
+        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 };
@@ -288,18 +661,24 @@ export class KernelGateway {
             availableProviders: kernel.providerManager.listInfos(),
             availableModels: this.modelsCache.models,
             estimatedRequestTokens: estTokens,
+            minBenchmark: this.opts.minBenchmark,
         };
     }
     // ── Telemetry / health ───────────────────────────────────────────────────────
     recordError(providerId, status, error) {
-        if (status === 429)
+        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, error: error.slice(0, 300) },
+            data: { source: 'gateway', providerId, status, kind, error: error.slice(0, 300) },
         });
     }
     emitSwitch(from, to, reason) {

package/dist/kernel/index.d.ts

@@ -22,7 +22,7 @@ export { VerificationEngine } from './verification-engine.js';
 export type { VerificationEngineDeps } from './verification-engine.js';
 export { RecoveryManager } from './recovery-manager.js';
 export type { RecoveryManagerDeps, RecoveryContext } from './recovery-manager.js';
-export { ConsoleLogger, SilentLogger } from './logger.js';
+export { ConsoleLogger, SilentLogger, FileLogger } from './logger.js';
 export { OllamaProvider } from './providers/ollama-provider.js';
 export type { OllamaProviderOptions } from './providers/ollama-provider.js';
 export { OpenAICompatibleProvider } from './providers/openai-compatible-provider.js';
@@ -37,6 +37,7 @@ export type { MissionPlannerDeps, PlanOptions } from './planner.js';
 export { normalizeCapabilities, CANONICAL_CAPABILITIES } from './capability-map.js';
 export { phaseBenchmarkFloor, phaseLabel } from './scheduler.js';
 export * from './federation/index.js';
+export * from './agents/index.js';
 export * from './gateway/index.js';
 export { createMcpServer, serveMcpStdio } from './mcp/index.js';
 export type { McpServerDeps } from './mcp/index.js';

package/dist/kernel/index.js

@@ -18,7 +18,7 @@ export { PluginManager } from './plugin-manager.js';
 export { PolicyEngine, PolicyPresets, POLICY_FACTORIES } from './policies.js';
 export { VerificationEngine } from './verification-engine.js';
 export { RecoveryManager } from './recovery-manager.js';
-export { ConsoleLogger, SilentLogger } from './logger.js';
+export { ConsoleLogger, SilentLogger, FileLogger } from './logger.js';
 export { OllamaProvider } from './providers/ollama-provider.js';
 export { OpenAICompatibleProvider } from './providers/openai-compatible-provider.js';
 export { GeminiProvider } from './providers/gemini-provider.js';
@@ -29,6 +29,8 @@ export { normalizeCapabilities, CANONICAL_CAPABILITIES } from './capability-map.
 export { phaseBenchmarkFloor, phaseLabel } from './scheduler.js';
 // Federation — neutral device mesh (peers, telemetry, config sync, MOLTFED interop)
 export * from './federation/index.js';
+// Agents — pluggable executors (native kernel + third-party coding CLIs)
+export * from './agents/index.js';
 // Gateway — local OpenAI-compatible endpoint backed by kernel routing/recovery
 export * from './gateway/index.js';
 // MCP — north-facing control surface (spawn/dispatch/role/voice/map over the mesh)

package/dist/kernel/logger.d.ts

@@ -1,6 +1,3 @@
-/**
- * OpenKernel — Logger
- */
 import type { Logger } from './types.js';
 export declare class ConsoleLogger implements Logger {
     private prefix;
@@ -16,3 +13,19 @@ export declare class SilentLogger implements Logger {
     warn(): void;
     error(): void;
 }
+/**
+ * Appends structured lines to a log file (best-effort — never throws into the
+ * caller). Used to give the kernel gateway a durable trace of routing/swap/
+ * truncation decisions during a TUI session, since its console is owned by the
+ * TUI. Read the file to see exactly why a turn died mid-task.
+ */
+export declare class FileLogger implements Logger {
+    private file;
+    private prefix;
+    constructor(file: string, prefix?: string);
+    private write;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}