teapot-coding-agent 0.37.59 → 0.37.61

package/dist/agent/llm.js

@@ -1,118 +1,40 @@
-/**
- * LLM access via the official `openai` npm client (OpenAI-compatible APIs:
- * OpenAI, OpenRouter, local vLLM/Ollama, ...).
- *
- * Retries, timeouts and response-shape handling are delegated to the SDK rather
- * than hand-rolled.
- */
 import OpenAI from "openai";
 import { providerHeaders } from "./provider-headers.js";
 export { providerHeaders };
 import { isRateLimitStatus, nextKey } from "./key-pool.js";
 const clients = new WeakMap();
-/**
- * Rotate to another key after a KEY-level failure (#170), returning a config that
- * uses it — or null when there is nothing to rotate to.
- *
- * Only the `apiKey` differs; the pool (and therefore the shared cooldown state) is
- * the same object, so the key we just failed stays parked for every other agent too.
- *
- * Returns null when the pool has one key, has no pool at all, or the only other
- * candidates are the failed one: retrying with the SAME credential cannot help, and
- * the caller's own staircase is the right response then.
- */
 export function rotateKey(cfg) {
     const pool = cfg.keyPool;
     if (!pool)
         return null;
     const next = nextKey(pool);
     if (!next)
-        return null; // every key has had its turn
-    // a new apiKey means a new OpenAI client below, which is correct: the credential is
-    // baked into the client at construction
+        return null;
     return { ...cfg, apiKey: next };
 }
-/**
- * Reasoning effort for a request body (#47, #150).
- *
- * MEASURED against the live endpoints (one probe each, `max_tokens: 3` with
- * `reasoning_effort: "low"`):
- *
- *   commandcode-goat   200 OK, reply carried `reasoning_content`   -> accepts
- *   google             400 "Thinking level is not supported for this model."
- *   openrouter         documented, catalogue advertises the field
- *
- * and — the fact that decides the design — what each endpoint PUBLISHES in
- * `/models`:
- *
- *   openrouter         `supported_parameters: [… "reasoning_effort" …]` per model
- *   commandcode-goat   only `id`, `name`, `context_length`, `supported_endpoints`
- *   google             no capability list either
- *
- * So for a gateway that publishes nothing there is NO per-model signal to gate on,
- * and the only honest way to find out whether it accepts the field is to TRY it.
- * A wrong guess is cheap to recover from: the endpoint answers 400 with a
- * recognisable message, and `isEffortUnsupported()` + the retry in `chat()` drop
- * the field for that request. That is better than a config flag the operator has to
- * know about, and better than hiding the control behind a capability list most
- * endpoints do not publish.
- *
- * Consequences, in order:
- *   1. a catalogue that explicitly EXCLUDES `reasoning_effort` is respected (no
- *      point provoking a 400 for a model that tells us up front it will refuse);
- *   2. a catalogue that INCLUDES it, or publishes no capability list at all, gets
- *      the field — and self-corrects on refusal;
- *   3. an invalid or absent level is never sent, whatever the endpoint says.
- */
 export function effortForRequest(cfg, supported = cfg.supportedParameters) {
     const e = cfg.reasoningEffort;
     if (!e || !REASONING_EFFORTS.includes(e))
         return {};
-    // a catalogue that names the parameter it supports and does NOT list this one is
-    // a definite "no" — only the ones that omit the question are worth a probe
     if (supported && !supported.includes("reasoning_effort"))
         return {};
-    // Clamp into the model's own levels when it publishes them (#150). The USER's input
-    // is validated against the four levels we offer, but the CLAMPED result may be a
-    // provider-specific one (`xhigh`, `max`) — deepseek advertises `["max","high","low"]`,
-    // so refusing to send `max` because it is not in our own four would throw away the
-    // model's real top tier.
     const clamped = clampEffort(e, cfg.supportedEfforts);
     if (!EFFORT_LADDER.includes(clamped))
         return {};
     return { reasoning_effort: clamped };
 }
-/**
- * Did the endpoint refuse `reasoning_effort` as an unsupported PARAMETER? (#150)
- *
- * Google's wording is "Thinking level is not supported for this model."; other
- * gateways phrase it as an unknown/unsupported parameter or field. Matched
- * narrowly: a retry that drops the field is only correct when THIS is the
- * complaint, and misreading an unrelated 400 as one would silently discard the
- * operator's choice instead of surfacing the real error.
- */
 export function isEffortUnsupported(err) {
     const msg = String(err?.message ?? err ?? "");
     if (!/reasoning_effort|thinking level|effort/i.test(msg))
         return false;
     return /not supported|unsupported|unknown (parameter|field)|invalid/i.test(msg);
 }
-/**
- * Is this model OFFERED a reasoning-effort control? (#150)
- *
- * The right panel shows the row when it can do something. A model whose catalogue
- * says it does not take the parameter hides it; one whose catalogue is silent
- * still shows it, because the endpoints that publish nothing (measured: commandcode,
- * google) accept the field for some models and refuse it for others, and a silent
- * 400 with an automatic retry is a better experience than a control that is missing
- * where it would have worked.
- */
 export function effortChoosable(supported) {
     if (!supported)
-        return true; // no capability list published: worth a try
+        return true;
     return supported.includes("reasoning_effort");
 }
-function isOpenRouterEndpoint(baseUrl) {
+export function isOpenRouterEndpoint(baseUrl) {
     try {
         return /(^|\.)openrouter\.ai$/i.test(new URL(String(baseUrl ?? "")).host);
     }
@@ -120,20 +42,6 @@ function isOpenRouterEndpoint(baseUrl) {
         return false;
     }
 }
-/**
- * Ask the endpoint NOT to retain a one-off request (Pi does the same with
- * `cacheRetention: "none"`; its docs say "summarization requests disable
- * prompt-cache writes because these one-off prompts are unlikely to be reused").
- *
- * Sent ONLY to OpenRouter, which is the one endpoint in use here that both
- * accepts the field and documents it. Every other OpenAI-compatible endpoint gets
- * nothing: an unrecognised body field is a 400 on strict providers, and "send
- * nothing" is exactly today's behaviour, so this can only ever add a saving.
- *
- * `24h` is the value that means "do not retain beyond this request's lifetime" for
- * an organisation with zero-data-retention off; with ZDR on the default is already
- * `in_memory` and this is a no-op.
- */
 export function cacheControlForRequest(cfg) {
     if (!cfg.oneOff)
         return {};
@@ -142,36 +50,7 @@ export function cacheControlForRequest(cfg) {
     return { prompt_cache_retention: "24h" };
 }
 const REASONING_EFFORTS = ["minimal", "low", "medium", "high"];
-/**
- * Canonical low→high ordering used for clamping, including the levels this harness
- * does not itself offer (`none`, `xhigh`, `max`) because a provider's own list is
- * spelled in those terms and the comparison needs the full ladder.
- *
- * Same ladder and the same rules as Hermes' `EFFORT_LADDER` / `clamp_effort`, which
- * is the clearest statement of the problem: a provider that does not have the
- * requested level should not receive a request it will refuse, and should not be
- * silently escalated either.
- */
 const EFFORT_LADDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
-/**
- * Map a requested level onto the levels a MODEL actually accepts (#150).
- *
- * Measured: OpenRouter publishes `reasoning.supported_efforts` per model (198 of 458
- * models), and the levels are not the four a naive UI would offer — deepseek-v4.1-flash
- * advertises `["max","high","low"]`, so `minimal` and `medium` do not exist for it and
- * `max` does. Sending an absent level is a refused turn; offering one is a control that
- * does nothing.
- *
- * Rules, matching Hermes:
- *   - unknown or empty support → the request passes through (we cannot judge it)
- *   - already supported → unchanged
- *   - a level that is not on the ladder at all → unchanged (custom providers use
- *     bespoke names, and rewriting one would be guesswork)
- *   - otherwise the nearest WEAKER level, so a clamp never escalates cost; if nothing
- *     weaker exists, the weakest supported level
- *   - never to `none`, which would silently switch thinking OFF for a caller who asked
- *     for it to be on
- */
 export function clampEffort(requested, supported) {
     if (!requested || !supported?.length)
         return requested;
@@ -180,7 +59,7 @@ export function clampEffort(requested, supported) {
         return requested;
     const reqIdx = EFFORT_LADDER.indexOf(requested);
     if (reqIdx < 0)
-        return requested; // not a ladder level: not ours to rewrite
+        return requested;
     const candidates = norm.filter((l) => l !== "none" && EFFORT_LADDER.includes(l));
     if (!candidates.length)
         return requested;
@@ -193,40 +72,22 @@ export function clampEffort(requested, supported) {
 function client(cfg) {
     let c = clients.get(cfg);
     if (!c) {
-        // #170: the SDK's retry ladder is deliberately KEPT for a pooled provider too.
-        // The operator's rule is "規定のリトライ回数を超えたら次の鍵にローテ", i.e. each key gets
-        // its own retries before the pool moves on — so `maxRetries` is the per-key budget
-        // and must not be zeroed.
         c = new OpenAI({
             baseURL: cfg.baseUrl,
             apiKey: cfg.apiKey,
             timeout: cfg.timeoutMs ?? 120_000,
-            maxRetries: cfg.maxRetries ?? 4, // per-key: rotation happens after these are spent
+            maxRetries: cfg.maxRetries ?? 4,
             defaultHeaders: providerHeaders(cfg.baseUrl, cfg.sessionId),
         });
         clients.set(cfg, c);
     }
     return c;
 }
-/**
- * Run a request, rotating to another key when the failure is KEY-level (#170).
- *
- * Bounded by the pool size: each rotation parks the key that just failed, so the walk
- * cannot revisit one and cannot loop forever. A non-key failure (a 500, a malformed
- * request, an abort) is rethrown untouched — rotating on those would burn every key
- * for a problem none of them caused.
- *
- * The LAST failure is the one propagated, so the operator sees the error from the
- * final key rather than whichever happened to fail first.
- */
 async function withKeyRotation(cfg, run) {
     let cur = cfg;
     let lastErr;
     for (let i = 0; i < Math.max(1, cfg.keyPool?.keys.length ?? 1); i++) {
         try {
-            // The client's own retry ladder runs inside `run`, so by the time this catch
-            // fires the FIRST key has already been retried its configured number of times.
-            // Only then do we move on — that is the operator's "規定のリトライ回数を超えたら".
             return { value: await run(cur), cfg: cur };
         }
         catch (err) {
@@ -235,7 +96,6 @@ async function withKeyRotation(cfg, run) {
             if (typeof status !== "number" || !isRateLimitStatus(status))
                 throw err;
             const rotated = rotateKey(cur);
-            // no key left: "全キーを回ってもまだレートリミットだったらエラーで停止"
             if (!rotated)
                 throw err;
             console.warn(`[teapot] rate limited (HTTP ${status}) on this key — moving to the next of ${cur.keyPool?.keys.length ?? 1} for this provider`);
@@ -244,17 +104,8 @@ async function withKeyRotation(cfg, run) {
     }
     throw lastErr;
 }
-/**
- * Providers occasionally glue MULTIPLE tool calls into one entry, or leak
- * their internal framing into the name field (seen live: a name of
- * `get_goal\uFFFD\uFFFDlist_dir` whose raw bytes were
- * `get_goal</tool_call><…><tool_call><…>`). Detect the tag boundaries and
- * split the blob back into individual calls so the round stays usable
- * instead of failing with "unknown tool".
- */
 function repairMangledToolName(raw) {
     const calls = [];
-    // Form 1 — framing tags survived: <name></tool_call>[<id>…]<tool_call><name>
     const tagRe = /([a-zA-Z_][\w.]*)<\/tool_call>|<tool_call>\s*<?([a-zA-Z_][\w.]*)?/g;
     let m;
     while ((m = tagRe.exec(raw))) {
@@ -264,54 +115,20 @@ function repairMangledToolName(raw) {
     }
     if (calls.length)
         return calls;
-    // Form 2 — tags were already destroyed into U+FFFD replacement chars:
-    // "get_goal\uFFFD\uFFFDlist_dir" → split on the replacement runs
     const parts = raw.split(/[\ufffd]+/).filter((p) => /^[a-zA-Z_][\w.]*$/.test(p));
     for (const p of parts)
         calls.push({ name: p, arguments: "{}" });
     return calls;
 }
-/** true when a tool name can't possibly be one of ours (framing leaked in) */
 function looksMangled(name) {
     return !name || /[\ufffd<>]/.test(name) || /<tool_call>|<\/tool/.test(name);
 }
-/**
- * Repair tool-call pairing so a provider will accept the request (#152).
- *
- * MEASURED against commandcode/deepseek: a request is rejected with
- *
- *     {"message":"invalid request error","type":"invalid_request_error"}
- *
- * — a message that names neither the call nor the message — in three cases, all the
- * same defect:
- *
- *   - an assistant `tool_calls` entry with NO matching `tool` result
- *   - a `tool` result whose `tool_calls` entry is absent (e.g. the prefix that issued
- *     it was compacted away)
- *   - a leading `tool` message, which cannot be answered by anything before it
- *
- * The consequences are worse than a bad status code: the failure is not recognisable
- * as a context overflow, so recovery never runs, and the generic message gives the
- * operator nothing to act on. It also costs the full retry staircase first (5s + 5s +
- * 30s) for a request that could never succeed.
- *
- * Dropping is the only safe repair for a result with no call: there is no id to
- * synthesise a call from, and keeping it re-creates the rejection. An unanswered CALL
- * gets a placeholder result instead, which preserves the exchange's meaning.
- *
- * Returns the input unchanged when it is already valid, so the common path allocates
- * nothing and the prompt stays byte-identical for prefix caching.
- */
 export function repairToolPairing(messages) {
-    // which call ids exist, in the order they are issued
     const callOrder = new Map();
     for (const m of messages)
         for (const t of m.tool_calls ?? [])
             if (t.id && !callOrder.has(t.id))
                 callOrder.set(t.id, callOrder.size);
-    // nothing to repair when every result follows its own call exactly once and every
-    // call is answered — checked first so the common path returns the SAME array and the
-    // prompt stays byte-identical for prefix caching
     const seen = new Set();
     let ok = true;
     for (const m of messages) {
@@ -323,21 +140,12 @@ export function repairToolPairing(messages) {
                 seen.add(id);
             continue;
         }
-        // a call must not be answered before it is issued
         for (const t of m.tool_calls ?? [])
             if (t.id && seen.has(t.id))
                 ok = false;
     }
     if (ok && seen.size === callOrder.size)
         return messages;
-    // Rebuild. Rules, in the order they are applied:
-    //   - a result with no call, or for a call not yet issued, is DROPPED (it cannot be
-    //     attributed; a result placed BEFORE its call is the same defect and the
-    //     provider refuses both with the same "invalid request error")
-    //   - a second result for one call is DROPPED (a call gets exactly one answer)
-    //   - an unanswered call gets a placeholder, so the exchange survives
-    // MEASURED: dropping only the unattributable ones left two shapes still failing, and
-    // reporting success on a request the provider refuses is the worst outcome for a guard.
     const out = [];
     const answered = new Set();
     for (const m of messages) {
@@ -347,13 +155,12 @@ export function repairToolPairing(messages) {
         }
         const id = m.tool_call_id;
         if (!id || !callOrder.has(id) || answered.has(id))
-            continue; // unattributable or duplicate
+            continue;
         if (!issuedBefore(messages, m))
-            continue; // out of order
+            continue;
         answered.add(id);
         out.push(m);
     }
-    // answer every call that no result covered, right after its call
     const filled = [];
     for (const m of out) {
         filled.push(m);
@@ -367,13 +174,11 @@ export function repairToolPairing(messages) {
             });
         }
     }
-    // a prefix drop can leave the kept tail starting on a result, which nothing justifies
     let first = 0;
     while (first < filled.length && filled[first].role === "tool")
         first++;
     return first ? filled.slice(first) : filled;
 }
-/** was this result's call issued earlier in the array? */
 function issuedBefore(messages, result) {
     for (const m of messages) {
         if (m === result)
@@ -384,18 +189,13 @@ function issuedBefore(messages, result) {
     return false;
 }
 function sanitize(messages) {
-    // #152: repair pairing BEFORE mapping — every request path goes through here, and a
-    // violated pairing is refused with an unhelpful "invalid request error"
     return repairToolPairing(messages).map((m) => {
-        // multimodal user message → OpenAI content-parts array (text + images);
-        // providers without vision reject it, but those models were never a fit
         if (m.content_parts?.length) {
             const parts = m.content_parts.map((p) => p.type === "image_url"
                 ? { type: "image_url", image_url: { url: p.image_url.url } }
                 : { type: "text", text: p.text ?? "" });
             return { role: m.role, content: parts };
         }
-        // empty text content makes many providers 400 — send a harmless placeholder
         if ((m.role === "user" || m.role === "assistant") && !m.content) {
             return { ...m, content: m.tool_calls?.length ? "(tool call)" : "(no content)" };
         }
@@ -405,26 +205,6 @@ function sanitize(messages) {
         return { ...m };
     });
 }
-/**
- * Why did the response carry no usable message? (#50)
- *
- * The leading text is kept stable at "LLM API returned no choices" so existing
- * matching (and the retry notes operators have learned to read) still works; the
- * diagnosis follows after a colon.
- */
-/**
- * The chain-of-thought text a provider attached, whichever field it used (#153).
- *
- * MEASURED against commandcode / deepseek-v4.1-flash: the reasoning arrives as
- * `reasoning_content` (115 chars non-streaming, 181 via the stream) and teapot read only
- * `reasoning`, so the thinking was received and DISCARDED — the reported "全然think
- * しない". DeepSeek Harness shows it because it reads the field this provider actually
- * sends.
- *
- * Both spellings are accepted because the endpoints in use disagree: OpenRouter uses
- * `reasoning`, DeepSeek/commandcode use `reasoning_content`. Neither is in the OpenAI SDK's
- * types, so both arrive as extra fields and must be read defensively.
- */
 function reasoningTextOf(m) {
     for (const key of ["reasoning", "reasoning_content"]) {
         const v = m?.[key];
@@ -435,17 +215,12 @@ function reasoningTextOf(m) {
 }
 function noChoicesDetail(res) {
     const base = "LLM API returned no choices";
-    // a gateway that answers 200 with an error object instead of failing: the
-    // actionable message is right there
     const err = res?.error;
     if (err && typeof err === "object") {
         const msg = typeof err.message === "string" ? err.message : JSON.stringify(err);
         const code = err.code ?? err.type;
         return `${base}: provider returned an error in a 200 response${code ? ` (${String(code)})` : ""} — ${String(msg).slice(0, 300)}`;
     }
-    // the SDK returned raw text — e.g. an SSE body served to a non-streaming
-    // request. JSON.parse succeeds for a real object, so a failure here means we
-    // were handed something that is not a completion at all.
     if (typeof res === "string") {
         const head = res.slice(0, 160).replace(/\s+/g, " ").trim();
         return `${base}: response was not a completion object (${res.length} bytes of ${res.trimStart().startsWith("data:") || res.trimStart().startsWith("event:") ? "SSE" : "text"})${head ? ` — ${head}` : ""}`;
@@ -465,7 +240,6 @@ function noChoicesDetail(res) {
     }
     return `${base}: the response had no choices array (${safeShape(res)})`;
 }
-/** a short type summary of an unexpected response, for the log line */
 function safeShape(res) {
     try {
         const o = res;
@@ -477,23 +251,9 @@ function safeShape(res) {
         return "unreadable response";
     }
 }
-/**
- * HTTP statuses that mean "this request shape is not supported here", so
- * re-issuing it without `stream: true` is a genuinely different request.
- *
- * Deliberately an allow-list rather than the whole 4xx range. 408/425/429 are
- * TRANSIENT: replaying them immediately against an already-saturated provider
- * just doubles the request count without changing anything. 401/403 mean the
- * credentials are wrong, which is not fixed by dropping `stream` either — they
- * are excluded on purpose, since a fallback there would replace one honest
- * auth error with the same one and a wasted round trip.
- */
 const STREAM_REJECTED_STATUS = new Set([400, 404, 405, 406, 415, 422, 501]);
 export async function chat(cfg, messages, tools, signal, onDelta) {
     try {
-        // #170: a KEY-level failure (429 especially) rotates to the provider's next key
-        // and retries immediately, rather than handing a rate limit straight to the
-        // caller's backoff ladder — with several keys this usually just works.
         const { value: res } = await withKeyRotation(cfg, (c) => client(c).chat.completions.create({
             model: c.model,
             messages: sanitize(messages),
@@ -501,16 +261,10 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
             ...effortForRequest(c),
             ...cacheControlForRequest(c),
         }, { signal }));
-        // #50: a gateway may answer with `null` (or any non-object) on some proxy
-        // error paths, so the guard is on `rm`, not on `res` being truthy —
-        // reading `res.choices` unguarded threw a bare TypeError that named neither
-        // the provider nor the shape.
         const raw = res?.choices?.[0];
         const rm = raw?.message;
         if (!rm)
             throw new Error(noChoicesDetail(res));
-        // normalize: providers attach extra fields (reasoning, refusal, ...) and
-        // nullable content — keep only what our protocol understands
         const message = {
             role: "assistant",
             content: typeof rm.content === "string" ? rm.content : "",
@@ -520,8 +274,6 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
         if (calls?.length) {
             message.tool_calls = calls.flatMap((c, i) => {
                 const name = c.function?.name ?? "";
-                // provider glued several calls together / leaked framing into the
-                // name — split the blob back into real calls so the round survives
                 if (looksMangled(name)) {
                     const repaired = repairMangledToolName(name);
                     if (repaired.length)
@@ -530,7 +282,7 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
                             type: "function",
                             function: { name: r.name, arguments: r.arguments },
                         }));
-                    return []; // unsalvageable — drop rather than feed "unknown tool"
+                    return [];
                 }
                 return [{
                         id: c.id ?? `call_${i}`,
@@ -539,9 +291,6 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
                     }];
             });
         }
-        // some gateways answer 200 with finish_reason "error"; those tool calls /
-        // text are often truncated garbage — discard the whole completion so the
-        // caller retries cleanly instead of poisoning history
         const finishReason = raw?.finish_reason;
         if (finishReason === "error") {
             throw new Error("LLM API error: provider returned an errored completion");
@@ -549,7 +298,6 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
         if (!message.content && !message.tool_calls) {
             throw new Error("LLM API error: empty completion");
         }
-        // non-streaming fallback still feeds the UI one final snapshot
         onDelta?.({ text: message.content ?? "", reasoning: reasoning ?? "" });
         return {
             message,
@@ -558,7 +306,6 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
                 ? {
                     inputTokens: res.usage.prompt_tokens,
                     outputTokens: res.usage.completion_tokens,
-                    // OpenAI-compatible providers attach cache details here (OpenRouter included)
                     cachedInputTokens: res.usage
                         .prompt_tokens_details?.cached_tokens ?? undefined,
                 }
@@ -566,40 +313,23 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
         };
     }
     catch (err) {
-        // #150: retry ONCE without the effort field when the endpoint says it does not
-        // take it, so a level that a particular model refuses never costs a turn
         if (!signal?.aborted && isEffortUnsupported(err) && effortForRequest(cfg).reasoning_effort) {
             return chat({ ...cfg, reasoningEffort: "" }, messages, tools, signal);
         }
         const e = err;
-        // #50: our own shape-diagnosis reads as a full sentence but carries no HTTP
-        // status (the request SUCCEEDED — that is the whole problem), so the generic
-        // wrapper below would relabel it "LLM API error ?: …".
         if (String(err.message ?? "").startsWith("LLM API returned no choices"))
             throw err;
         if (e.status === undefined && !String(err.message).includes("provider returned"))
-            throw err; // not an API error (abort, bug, ...)
+            throw err;
         const detail = e.error?.message ?? e.message ?? "unknown provider error";
         throw new Error(`LLM API error ${e.status ?? "?"}: ${String(detail).slice(0, 500)}`);
     }
 }
-/**
- * Streaming variant of chat(): same result shape, but calls onDelta with
- * cumulative {text, reasoning} snapshots as chunks arrive so the UI can show
- * the response live. Falls back to plain chat() once if the provider rejects
- * streaming before producing any chunk.
- */
 export async function chatStream(cfg, messages, tools, signal, onDelta) {
     let gotChunk = false;
-    // hoisted so the abort handler below can attach whatever streamed so far
     let text = "";
     let reasoning = "";
     try {
-        // #170: the KEY-level rotation covers this path the same way as chat(). It can
-        // only start a NEW stream — if a key fails MID-stream the text already sent to
-        // the UI stands, and `gotChunk` below stops us from silently restarting and
-        // duplicating it. A 429 on a stream is a REJECTION (no chunks yet), which is the
-        // case rotation is for.
         const { value: stream } = await withKeyRotation(cfg, (c) => client(c).chat.completions.create({
             model: c.model,
             messages: sanitize(messages),
@@ -607,8 +337,6 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
             ...effortForRequest(c),
             ...cacheControlForRequest(c),
             stream: true,
-            // ask providers to include the final usage chunk in streaming mode
-            // (OpenAI-compatible; harmless where unsupported)
             stream_options: { include_usage: true },
         }, { signal }));
         const calls = {};
@@ -621,9 +349,6 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
             const d = c?.delta;
             if (d?.content)
                 text += d.content;
-            // both spellings: OpenRouter streams `reasoning`, DeepSeek/commandcode stream
-            // `reasoning_content` (#153 — reading only the first discarded the thinking).
-            // The helper takes a loose record because neither field is in the SDK's types.
             reasoning += reasoningTextOf(d) ?? "";
             for (const tc of d?.tool_calls ?? []) {
                 const i = tc.index ?? 0;
@@ -672,9 +397,6 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
                     }];
             });
         if (!message.content && !message.tool_calls) {
-            // #50: a stream that opened, produced NOTHING, and closed cleanly. The
-            // marker lets the handler below tell this apart from a request the provider
-            // actively rejected — re-issuing THIS one without `stream` usually succeeds.
             const e = new Error("LLM API error: empty completion");
             e.emptyStream = true;
             throw e;
@@ -682,28 +404,7 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
         return { message, reasoning: reasoning || undefined, usage };
     }
     catch (err) {
-        // #50 — a provider that doesn't support streaming at all still gets ONE clean
-        // fallback, but ONLY when the failure could plausibly be the stream itself.
-        // The condition must NOT be `!gotChunk && !signal?.aborted`: that also matches
-        // a request that FAILED (a 200 carrying an SSE `error` frame, a context-length
-        // rejection), and the fallback then re-issues the same oversized request,
-        // replacing the real diagnosis — a restored 1500-message session reports "no
-        // choices" instead of "context length exceeded", so isContextOverflow() never
-        // runs compact-and-retry.
-        //
-        //  1. A status in STREAM_REJECTED_STATUS: only a request rejected outright is a
-        //     genuinely DIFFERENT request when re-issued without `stream`.
-        //  2. `emptyStream`: a 200 that streams zero chunks and closes cleanly is a
-        //     broken/flaky proxy — precisely the case the retry rescues. Requiring a
-        //     4xx here would delete that safety net, a regression this file's own
-        //     tests caught.
-        //
-        // Everything else — 5xx, an error frame, a mid-stream failure — is the ANSWER,
-        // rethrown untouched so overflow recovery can see it.
         const status = err?.status;
-        // #150: the endpoint refused `reasoning_effort` itself. Retry ONCE without it,
-        // so choosing a level never costs a turn — this is what makes the control safe
-        // to offer on an endpoint whose capabilities cannot be known in advance.
         if (!signal?.aborted && isEffortUnsupported(err) && effortForRequest(cfg).reasoning_effort) {
             return chatStream({ ...cfg, reasoningEffort: "" }, messages, tools, signal, onDelta);
         }
@@ -712,8 +413,6 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
         if (!gotChunk && !signal?.aborted && (rejectedByProvider || emptyStream)) {
             return chat(cfg, messages, tools, signal, onDelta);
         }
-        // user interrupt: hand back whatever streamed so far so the harness can
-        // keep the partial output visible instead of losing it
         if (signal?.aborted && (text || reasoning)) {
             err.partial = { text, reasoning };
         }