@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/llm/providers/openai.js

@@ -13,7 +13,34 @@ import { ContextLimitError, LLMError, LLMRateLimitError } from "../../exceptions
 import { logger } from "../../logging/logger.js";
 import { countTokens } from "../token-counter.js";
 import { capabilitiesFor } from "../capabilities/index.js";
+import { clampMaxTokens } from "../clamp-max-tokens.js";
+import { resolveApiKey, resolveHeaders } from "../provider-auth.js";
+import { stripVisionFromHistory } from "../strip-vision.js";
 import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError, } from "../stream-watchdog.js";
+/**
+ * Extract prompt-cache counts from an OpenAI-compatible usage object.
+ *
+ * - Cache HITS live under `usage.prompt_tokens_details.cached_tokens` (NOT a
+ *   top-level field). Both OpenAI and OpenRouter report this.
+ * - Cache WRITES (first-time prefix ingestion) are reported by OpenRouter as
+ *   `prompt_tokens_details.cache_write_tokens` (verified live 2026-07-02).
+ *   OpenAI's automatic caching has no separate write charge and omits it. We
+ *   map it to `cacheCreationTokens` so the UI can show "writing cache" on the
+ *   first turn, not just hits on later turns.
+ *
+ * Returns a spreadable partial so callers omit each key entirely when the API
+ * reports no value — keeping the field `undefined` rather than a misleading 0.
+ * See docs/todo/prompt-cache-optimization.md.
+ */
+function cachedTokensOf(usage) {
+    const details = usage?.prompt_tokens_details;
+    const out = {};
+    if (typeof details?.cached_tokens === "number")
+        out.cacheReadTokens = details.cached_tokens;
+    if (typeof details?.cache_write_tokens === "number")
+        out.cacheCreationTokens = details.cache_write_tokens;
+    return out;
+}
 /**
  * Consume an async iterable of stream chunks with an idle watchdog.
  * Returns the accumulated text — either from onChunk return values, or
@@ -26,12 +53,24 @@ import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError, } from "../stream-watch
  * the function rejects with StreamIdleTimeoutError.
  */
 export async function runStreamWithWatchdog(stream, opts = {}) {
-    const watchdogActive = STREAM_WATCHDOG_CONFIG.enabled || opts.idleTimeoutMs !== undefined;
+    // An explicit idleTimeoutMs always activates the watchdog. Otherwise follow
+    // disableWatchdog (per-call override) if set, else the env default.
+    const watchdogActive = opts.idleTimeoutMs !== undefined ||
+        (opts.disableWatchdog === undefined
+            ? STREAM_WATCHDOG_CONFIG.enabled
+            : !opts.disableWatchdog);
     const idleTimeoutMs = opts.idleTimeoutMs ?? STREAM_WATCHDOG_CONFIG.idleTimeoutMs;
     let text = "";
     // Fast path: watchdog disabled AND caller did not override → no overhead.
     if (!watchdogActive) {
         for await (const chunk of stream) {
+            // Stop consuming the moment the turn is aborted — do NOT forward more
+            // chunks to onChunk (which emits text_delta to the UI). The SDK may still
+            // be draining buffered chunks after abort(); this prevents them leaking
+            // post-Stop. `break` from a for-await calls the iterator's return() for us,
+            // letting the SDK tear the stream down.
+            if (opts.signal?.aborted)
+                break;
             if (opts.onChunk) {
                 text += opts.onChunk(chunk) ?? "";
             }
@@ -46,6 +85,11 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
     const iterator = stream[Symbol.asyncIterator]();
     try {
         while (true) {
+            // Abort short-circuit: stop before awaiting/forwarding the next chunk so
+            // buffered post-abort deltas never reach onChunk. The finally below calls
+            // iterator.return() to tear the SDK stream down.
+            if (opts.signal?.aborted)
+                break;
             const nextPromise = iterator.next();
             // Build a timeout promise that rejects if no chunk arrives in time.
             let timeoutHandle = null;
@@ -54,14 +98,34 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
                     reject(new StreamIdleTimeoutError(idleTimeoutMs, opts.requestId));
                 }, idleTimeoutMs);
             });
+            // Abort promise: resolve as soon as the signal fires so a cancel mid-chunk
+            // (while awaiting the next delta) breaks out immediately instead of
+            // waiting for the next chunk or the idle deadline.
+            const abortCleanups = [];
+            const abortPromise = new Promise((resolve) => {
+                const sig = opts.signal;
+                if (!sig)
+                    return; // never resolves → no effect on the race
+                if (sig.aborted) {
+                    resolve({ aborted: true });
+                    return;
+                }
+                const onAbort = () => resolve({ aborted: true });
+                sig.addEventListener("abort", onAbort, { once: true });
+                abortCleanups.push(() => sig.removeEventListener("abort", onAbort));
+            });
             let result;
             try {
-                result = await Promise.race([nextPromise, timeoutPromise]);
+                result = await Promise.race([nextPromise, timeoutPromise, abortPromise]);
             }
             finally {
                 if (timeoutHandle !== null)
                     clearTimeout(timeoutHandle);
+                for (const c of abortCleanups)
+                    c();
             }
+            if ("aborted" in result)
+                break;
             if (result.done)
                 break;
             const chunk = result.value;
@@ -88,17 +152,30 @@ export class OpenAIClient extends LLMClientBase {
     // client. Cheaper and more reliable than re-deriving from the model id when
     // a new variant ships before our regex knows about it.
     _forceMaxCompletionTokens = false;
-    constructor(config) {
-        super(config);
+    // Sticky override: some gpt-5.x variants reject `reasoning_effort` when it's
+    // combined with `tools` on /v1/chat/completions ("Please use /v1/responses
+    // instead"). Once we see that 400, drop `reasoning_effort` for the lifetime
+    // of the client so tool-calling turns (e.g. the dream consolidation loop)
+    // succeed. Omitting the field just means "model default reasoning", which is
+    // fine for our background/aux calls.
+    _dropReasoningEffort = false;
+    constructor(config, defaults) {
+        super(config, defaults);
     }
     initClient() {
         // Lazy init — client created on first use
     }
     get client() {
         if (!this._client) {
+            const headers = resolveHeaders(this.config.httpHeaders);
             this._client = new OpenAI({
-                apiKey: this.config.apiKey ?? process.env.OPENAI_API_KEY,
+                // apiKey: explicit > authCommand stdout > OPENAI_API_KEY (TODO 7.2).
+                // OpenAI's SDK requires a non-empty string; fall back to a placeholder
+                // when a custom provider authenticates purely via httpHeaders.
+                apiKey: resolveApiKey(this.config, process.env.OPENAI_API_KEY) ??
+                    (Object.keys(headers).length > 0 ? "x-headers-auth" : undefined),
                 ...(this.config.baseUrl ? { baseURL: this.config.baseUrl } : {}),
+                ...(Object.keys(headers).length > 0 ? { defaultHeaders: headers } : {}),
                 timeout: this.timeout,
             });
         }
@@ -119,12 +196,31 @@ export class OpenAIClient extends LLMClientBase {
         }
         return this._capability;
     }
+    /**
+     * True when this client routes an Anthropic-family model through OpenRouter's
+     * OpenAI-compatible endpoint. Anthropic caching is EXPLICIT — nothing is
+     * cached unless the request carries `cache_control` breakpoints (verified live
+     * 2026-07-02: plain requests to anthropic/claude-opus-4.7-fast via OpenRouter
+     * report cached_tokens 0 on every repeat; a single system-block breakpoint
+     * turns the whole stable prefix — tools + system — into a cache hit, ~89%
+     * cheaper on the follow-up). OpenAI and other OpenRouter models cache
+     * automatically, so they must NOT get breakpoints. The slug arrives resolved
+     * (e.g. "anthropic/claude-opus-4.7-fast") or as the router alias
+     * ("~anthropic/claude-opus-latest") — both start with an optional "~" then
+     * "anthropic/".
+     */
+    get isOpenRouterAnthropic() {
+        return this.config.providerKind === "openrouter" && /^~?anthropic\//.test(this.model);
+    }
     async createMessage(options) {
-        return this.withRetry(async () => {
-            // Per-call thinking wins; otherwise fall back to provider default
-            // (settings.providers[].thinking, threaded through LLMConfig).
-            const thinking = options.thinking ?? this.config.thinking;
-            const messages = this.buildMessages(options.systemPrompt, options.messages, thinking);
+        return this.withRetry(async (requestSignal) => {
+            // requestSignal = caller's cancel signal composed with a per-request
+            // hard deadline (withRetry). Hand it to the SDK so a wedged socket is
+            // torn down instead of hanging for tens of minutes.
+            // Per-call reasoning wins; otherwise fall back to provider default
+            // (settings.providers[].reasoning, threaded through LLMConfig).
+            const reasoning = options.reasoning ?? this.config.reasoning;
+            const messages = this.buildMessages(options.systemPrompt, options.messages, reasoning);
             const tools = options.tools?.length ? this.convertTools(options.tools) : undefined;
             const span = logger.span("llm.request", {
                 cat: "llm",
@@ -136,8 +232,8 @@ export class OpenAIClient extends LLMClientBase {
             });
             try {
                 const response = options.stream && options.onChunk
-                    ? await this.streamMessage(options, messages, tools, thinking)
-                    : await this.nonStreamMessage(options, messages, tools, thinking);
+                    ? await this.streamMessage(options, messages, tools, reasoning, requestSignal)
+                    : await this.nonStreamMessage(options, messages, tools, reasoning, requestSignal);
                 span.end({
                     stopReason: response.stopReason,
                     promptTokens: response.usage?.promptTokens,
@@ -151,56 +247,88 @@ export class OpenAIClient extends LLMClientBase {
                 span.fail(err);
                 throw err;
             }
-        });
+        }, { signal: options.signal });
     }
     /**
      * Build the request body honoring the model's capability descriptor.
      * Centralized so both streaming and non-streaming paths agree on the
      * exact shape.
      */
-    buildRequestBody(options, messages, tools, thinking, stream) {
+    buildRequestBody(options, messages, tools, reasoning, stream) {
         const cap = this.capability;
-        const maxTokens = options.maxTokens ?? this.maxTokens;
+        // Clamp to the model's known output ceiling so a stale catalog value
+        // (e.g. 384000 inherited after a hot model switch) can't 400 a
+        // smaller-cap model. No known cap → send the value as-is.
+        const maxTokens = clampMaxTokens(options.maxTokens ?? this.maxTokens, cap.maxOutputTokens);
         // Token-limit field — capability picks `max_tokens` vs `max_completion_tokens`.
         // Sticky fallback (set by handleApiError on a 400) overrides the rule for
-        // ids the regex hasn't learned about yet.
+        // ids the regex hasn't learned about yet. When neither a requested value nor
+        // a known cap exists, omit the field entirely and let the endpoint apply its
+        // own ceiling (rather than inventing 8192 and truncating long outputs).
         const useCompletion = this._forceMaxCompletionTokens || cap.tokenLimitField === "max_completion_tokens";
-        const tokenLimit = useCompletion
-            ? { max_completion_tokens: maxTokens }
-            : { max_tokens: maxTokens };
-        // Sampling params — only include if the model accepts them.
-        const sampling = {};
+        const tokenLimit = maxTokens === undefined
+            ? {}
+            : useCompletion
+                ? { max_completion_tokens: maxTokens }
+                : { max_tokens: maxTokens };
+        // Sampling params — only include if the model accepts them. Split by
+        // precedence so the request body composes correctly against catalog
+        // extraBody (see the merge below):
+        //   - samplingDefault: the connection's DEFAULT temperature (this.temperature).
+        //     It's the BASE — a user's catalog `temperature` in extraBody should
+        //     override the bare default.
+        //   - samplingOverride: a PER-REQUEST temperature (options.temperature). It
+        //     wins over both the default and the catalog value.
+        const samplingDefault = {};
+        const samplingOverride = {};
         if (!cap.rejectedParams.has("temperature")) {
-            sampling.temperature =
-                options.temperature !== undefined ? options.temperature : this.temperature;
+            if (options.temperature !== undefined) {
+                samplingOverride.temperature = options.temperature;
+            }
+            else {
+                samplingDefault.temperature = this.temperature;
+            }
         }
-        // Reasoning shape — different vendors, different fields, never combine.
-        // We treat `options.thinking` as the user's intent ("enabled"/"disabled")
-        // and translate to whichever wire shape the model expects.
-        const reasoning = {};
-        if (thinking) {
+        // Reasoning shape — translate the user's ReasoningSetting to the wire
+        // shape. Different vendors, different fields, never combine. We read the
+        // real picked level (no "medium" hardcode) — only fall back to "medium"
+        // when the setting says "thinking on" but carries no explicit effort
+        // ({mode:"on"}).
+        const reasoningBody = {};
+        // gpt-5.5+ 400s when `reasoning_effort` rides alongside `tools` on
+        // /v1/chat/completions. If the capability flags that combo AND this request
+        // carries tools, suppress the field up-front (same effect as the reactive
+        // _dropReasoningEffort sticky, but BEFORE the first failed request — so we
+        // never burn a 400 + 1s-backoff retry on every tool-using turn).
+        const suppressEffort = this._dropReasoningEffort ||
+            (cap.reasoning.kind === "openai-effort" &&
+                cap.reasoning.noEffortWithTools === true &&
+                !!tools?.length);
+        if (reasoning && reasoning.mode !== "off") {
             switch (cap.reasoning.kind) {
                 case "deepseek-thinking":
                     // DeepSeek V4, Z.AI GLM-4.5+ — top-level {thinking: {type}}.
-                    reasoning.thinking = { type: thinking };
+                    // Binary: any non-off means thinking on (effort irrelevant).
+                    reasoningBody.thinking = { type: "enabled" };
                     break;
                 case "openai-effort":
                     // OpenAI o-series, gpt-5+, Gemini OpenAI-compat, xAI grok-4.3,
                     // Mistral magistral, Groq reasoning models — `reasoning_effort`.
-                    // "enabled" → "medium" (safe middle). "disabled" → the capability's
-                    // `disabledEffort` value; defaults to "minimal" (OpenAI), but xAI
-                    // uses "low" (no minimal) and Mistral uses "none" (only high|none).
-                    reasoning.reasoning_effort =
-                        thinking === "disabled"
-                            ? (cap.reasoning.disabledEffort ?? "minimal")
-                            : "medium";
+                    // Send the user's real level; {mode:"on"} (no level) → "medium".
+                    //
+                    // Skip when the endpoint has told us (reactive _dropReasoningEffort)
+                    // OR the capability tells us up-front (noEffortWithTools) that
+                    // `reasoning_effort` is incompatible with `tools` here — sending it
+                    // would just trigger the "use /v1/responses" 400.
+                    if (!suppressEffort) {
+                        reasoningBody.reasoning_effort =
+                            reasoning.mode === "effort" ? reasoning.effort : "medium";
+                    }
                     break;
                 case "openrouter-reasoning":
-                    // OpenRouter normalized shape — {reasoning: {effort, exclude}}.
-                    reasoning.reasoning =
-                        thinking === "disabled"
-                            ? { effort: "minimal", exclude: true }
-                            : { effort: "medium" };
+                    // OpenRouter normalized shape — {reasoning: {effort}}.
+                    reasoningBody.reasoning =
+                        reasoning.mode === "effort" ? { effort: reasoning.effort } : { effort: "medium" };
                     break;
                 case "anthropic-budget":
                 case "anthropic-adaptive":
@@ -210,19 +338,79 @@ export class OpenAIClient extends LLMClientBase {
                     break;
             }
         }
+        else if (reasoning && reasoning.mode === "off") {
+            // Explicit OFF — each shape's "don't think" wire form.
+            switch (cap.reasoning.kind) {
+                case "deepseek-thinking":
+                    reasoningBody.thinking = { type: "disabled" };
+                    break;
+                case "openai-effort":
+                    // The capability's `disabledEffort` (defaults "minimal"; xAI "low",
+                    // Mistral "none"). Skip if the endpoint already rejected the field
+                    // OR the capability says it's incompatible with tools here.
+                    if (!suppressEffort) {
+                        reasoningBody.reasoning_effort = cap.reasoning.disabledEffort ?? "minimal";
+                    }
+                    break;
+                case "openrouter-reasoning":
+                    reasoningBody.reasoning = { effort: "minimal", exclude: true };
+                    break;
+                default:
+                    break;
+            }
+        }
+        // reasoning_summary (TODO 7.2): when the model uses the object-form
+        // reasoning shape (OpenRouter normalized / Responses-style), attach the
+        // requested summary level to that object. For the bare `reasoning_effort`
+        // shape there's no summary field on chat-completions, so we skip it rather
+        // than send an unknown top-level param.
+        if (this.config.reasoningSummary && reasoningBody.reasoning &&
+            typeof reasoningBody.reasoning === "object") {
+            reasoningBody.reasoning.summary =
+                this.config.reasoningSummary;
+        }
+        // Catalog-driven passthrough params (temperature/top_p/thinking etc, already
+        // wire-mapped from the connection's paramValues by applyParams). Filter each
+        // key by rejectedParams so we never send a field the model rejects (same
+        // contract as `sampling` above — e.g. temperature to gpt-5).
+        const extra = {};
+        const rejected = cap.rejectedParams;
+        for (const [k, v] of Object.entries(this.config.extraBody ?? {})) {
+            if (rejected.has(k))
+                continue;
+            extra[k] = v;
+        }
+        // Compose the param fragments with explicit precedence + deep merge:
+        //   connection default sampling (base)
+        //     ← static catalog extraBody
+        //     ← per-request sampling override
+        //     ← reasoning translation (wins)
+        // - A catalog `temperature` in extraBody overrides the bare connection
+        //   default, but a PER-REQUEST temperature (options.temperature) overrides
+        //   both — a plain `...sampling, ...extra` got this backwards. (review #4)
+        // - extra and reasoningBody can both carry nested objects under the SAME
+        //   top-level key (a catalog param wired to `thinking.type`/`reasoning.effort`
+        //   vs the reasoning translation's `thinking`/`reasoning`). A shallow spread
+        //   would wholesale-replace one nested object; deepMergeInto merges them. (review #5)
+        const paramBody = {};
+        deepMergeInto(paramBody, samplingDefault);
+        deepMergeInto(paramBody, extra);
+        deepMergeInto(paramBody, samplingOverride);
+        deepMergeInto(paramBody, reasoningBody);
         return {
             model: this.model,
             messages,
             ...tokenLimit,
-            ...sampling,
-            ...reasoning,
+            ...paramBody,
+            // service_tier (TODO 7.2): passed through verbatim when configured.
+            ...(this.config.serviceTier ? { service_tier: this.config.serviceTier } : {}),
             ...(tools ? { tools } : {}),
             ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
         };
     }
-    async nonStreamMessage(options, messages, tools, thinking) {
+    async nonStreamMessage(options, messages, tools, reasoning, requestSignal) {
         try {
-            const response = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, thinking, false), { signal: options.signal });
+            const response = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, reasoning, false), { signal: requestSignal ?? options.signal });
             const choice = response.choices[0];
             if (!choice)
                 throw new LLMError("No response from OpenAI", "openai");
@@ -230,6 +418,9 @@ export class OpenAIClient extends LLMClientBase {
                 promptTokens: response.usage?.prompt_tokens ?? 0,
                 completionTokens: response.usage?.completion_tokens ?? 0,
                 totalTokens: response.usage?.total_tokens ?? 0,
+                // OpenAI caching is automatic; hits land here, NOT in a top-level
+                // cacheReadTokens field. Reading the wrong field made hit-rate invisible.
+                ...cachedTokensOf(response.usage),
             };
             this.recordUsage(usage, options);
             return this.processChoice(choice, usage);
@@ -239,13 +430,19 @@ export class OpenAIClient extends LLMClientBase {
             throw err;
         }
     }
-    async streamMessage(options, messages, tools, thinking) {
+    async streamMessage(options, messages, tools, reasoning, requestSignal) {
+        const sdkSignal = requestSignal ?? options.signal;
         try {
-            const stream = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, thinking, true), { signal: options.signal });
+            const stream = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, reasoning, true), { signal: sdkSignal });
             let text = "";
             let reasoningContent = "";
             const toolCallsMap = new Map();
             let streamUsage;
+            // Last finish_reason seen on the stream. Without this we returned a
+            // hardcoded "stop", so an output-cap cutoff (finish_reason "length")
+            // was indistinguishable from a clean finish and the turn loop never
+            // ran its max-output continuation. Capture it and return it verbatim.
+            let finishReason;
             // TTFT — first chunk that actually carried text. Tool-call-only chunks
             // earlier in the stream don't count: the user-visible "text starts now"
             // moment is what we want to compare across providers.
@@ -257,6 +454,11 @@ export class OpenAIClient extends LLMClientBase {
                 if (chunk.usage) {
                     streamUsage = chunk.usage;
                 }
+                // Capture finish_reason BEFORE the no-delta early return below: the
+                // final chunk frequently carries finish_reason with an empty delta.
+                const chunkFinish = chunk.choices?.[0]?.finish_reason;
+                if (chunkFinish)
+                    finishReason = chunkFinish;
                 const delta = chunk.choices[0]?.delta;
                 if (!delta)
                     return "";
@@ -287,11 +489,18 @@ export class OpenAIClient extends LLMClientBase {
                     for (const tc of delta.tool_calls) {
                         const idx = tc.index;
                         if (!toolCallsMap.has(idx)) {
-                            toolCallsMap.set(idx, { id: tc.id ?? "", name: tc.function?.name ?? "", args: "" });
-                            options.onChunk?.({
-                                type: "tool_use_start",
-                                toolCall: { id: tc.id, toolName: tc.function?.name },
-                            });
+                            const id = tc.id ?? "";
+                            const name = tc.function?.name ?? "";
+                            toolCallsMap.set(idx, { id, name, args: "" });
+                            // Only announce once we actually have an id+name; some providers
+                            // stream them across deltas. Emitting undefined here violates the
+                            // ToolCall contract and breaks downstream consumers.
+                            if (id && name) {
+                                options.onChunk?.({
+                                    type: "tool_use_start",
+                                    toolCall: { id, toolName: name },
+                                });
+                            }
                         }
                         const existing = toolCallsMap.get(idx);
                         if (tc.id)
@@ -324,32 +533,49 @@ export class OpenAIClient extends LLMClientBase {
                 return delta.content ?? "";
             };
             await runStreamWithWatchdog(stream, {
-                idleTimeoutMs: STREAM_WATCHDOG_CONFIG.enabled
-                    ? STREAM_WATCHDOG_CONFIG.idleTimeoutMs
-                    : undefined,
+                // Idle watchdog is now ON by default (see STREAM_WATCHDOG_CONFIG) — it
+                // catches a stream that connects then stalls mid-generation; the
+                // per-request deadline (sdkSignal) catches connect/first-byte hangs.
+                idleTimeoutMs: STREAM_WATCHDOG_CONFIG.idleTimeoutMs,
                 requestId,
                 onChunk: handleChunk,
+                signal: sdkSignal,
             });
             const toolCalls = [];
             for (const [, tc] of toolCallsMap) {
+                // Drop incomplete tool calls: an empty id or name (the fallbacks set
+                // when a delta never delivered them) would become a malformed call
+                // that breaks transcript keying and tool dispatch downstream.
+                if (!tc.id || !tc.name) {
+                    logger.warn("openai.incomplete_tool_call_dropped", {
+                        id: tc.id || "(empty)",
+                        name: tc.name || "(empty)",
+                    });
+                    continue;
+                }
                 let args = {};
                 try {
                     args = JSON.parse(tc.args || "{}");
                 }
-                catch { }
+                catch {
+                    /* intentional: model emitted malformed tool-call JSON — fall back to
+                       empty args rather than crashing the stream; the tool layer reports
+                       the resulting validation error back to the model. */
+                }
                 toolCalls.push({ id: tc.id, toolName: tc.name, args });
             }
             const usage = {
                 promptTokens: streamUsage?.prompt_tokens ?? 0,
                 completionTokens: streamUsage?.completion_tokens ?? 0,
                 totalTokens: streamUsage?.total_tokens ?? 0,
+                ...cachedTokensOf(streamUsage),
             };
             this.recordUsage(usage, options);
             return {
                 text,
                 toolCalls,
                 usage,
-                stopReason: "stop",
+                stopReason: finishReason ?? "stop",
                 ...(reasoningContent ? { reasoningContent } : {}),
             };
         }
@@ -367,7 +593,11 @@ export class OpenAIClient extends LLMClientBase {
                 try {
                     args = JSON.parse(tc.function.arguments || "{}");
                 }
-                catch { }
+                catch {
+                    /* intentional: model emitted malformed tool-call JSON — fall back to
+                       empty args rather than crashing; the tool layer reports the
+                       resulting validation error back to the model. */
+                }
                 toolCalls.push({
                     id: tc.id,
                     toolName: tc.function.name,
@@ -384,8 +614,14 @@ export class OpenAIClient extends LLMClientBase {
             ...(reasoningContent ? { reasoningContent } : {}),
         };
     }
-    buildMessages(systemPrompt, messages, thinking) {
+    buildMessages(systemPrompt, messages, reasoning) {
         const result = [{ role: "system", content: systemPrompt }];
+        // Drop historical image blocks when the active model can't accept vision.
+        // Engine.run only gates *new* attachments; an image left in history from
+        // when a vision model was active otherwise re-serializes into `image_url`
+        // below and 400s ("unknown variant `image_url`") after a model switch.
+        // Identity-preserving on the common path (vision models / no images).
+        messages = stripVisionFromHistory(messages, this.capability.supportsVision);
         // Reasoning-content echo-back contract — driven by capability:
         //   "when-tools"  : backfill an empty placeholder if the prior assistant
         //                   turn doesn't carry one (DeepSeek V4 + tools 400s
@@ -398,7 +634,7 @@ export class OpenAIClient extends LLMClientBase {
         const cap = this.capability;
         const hasTools = messages.some((m) => Array.isArray(m.content) &&
             m.content.some((b) => b.type === "tool_use" || b.type === "tool_result"));
-        const needsReasoningBackfill = thinking !== "disabled" &&
+        const needsReasoningBackfill = reasoning?.mode !== "off" &&
             cap.echoReasoning === "when-tools" &&
             hasTools;
         const stripReasoning = cap.echoReasoning === "never";
@@ -492,10 +728,44 @@ export class OpenAIClient extends LLMClientBase {
                     const toolResults = [];
                     for (const block of msg.content) {
                         if (block.type === "tool_result" && block.tool_use_id) {
-                            toolResults.push({
-                                tool_use_id: block.tool_use_id,
-                                content: typeof block.content === "string" ? block.content : "",
-                            });
+                            if (typeof block.content === "string") {
+                                toolResults.push({
+                                    tool_use_id: block.tool_use_id,
+                                    content: block.content,
+                                });
+                            }
+                            else if (Array.isArray(block.content)) {
+                                // view_image returns an image inside tool_result.content. OpenAI's
+                                // role:"tool" message can't carry an image, so split it: text stays
+                                // in the tool message, image blocks are hoisted into imageParts and
+                                // get emitted as their own user image_url message below.
+                                const texts = [];
+                                for (const inner of block.content) {
+                                    if (inner.type === "text" && inner.text) {
+                                        texts.push(inner.text);
+                                    }
+                                    else if (inner.type === "image" && inner.source) {
+                                        const wireDetail = mapImageDetailToOpenAI(this.imageDetail);
+                                        imageParts.push({
+                                            type: "image_url",
+                                            image_url: {
+                                                url: `data:${inner.source.media_type};base64,${inner.source.data}`,
+                                                ...(wireDetail ? { detail: wireDetail } : {}),
+                                            },
+                                        });
+                                    }
+                                }
+                                toolResults.push({
+                                    tool_use_id: block.tool_use_id,
+                                    content: texts.length > 0 ? texts.join("\n") : "[image returned to user message]",
+                                });
+                            }
+                            else {
+                                toolResults.push({
+                                    tool_use_id: block.tool_use_id,
+                                    content: "",
+                                });
+                            }
                         }
                         else if (block.type === "text" && block.text) {
                             textParts.push(block.text);
@@ -503,13 +773,25 @@ export class OpenAIClient extends LLMClientBase {
                         else if (block.type === "image" && block.source) {
                             // OpenAI-compat image_url: every supported provider (OpenAI,
                             // OpenRouter, OpenAI-compatible proxies for Gemini/xAI/etc)
-                            // accepts a base64 data URL as the URL. Per-(provider, model)
-                            // vision-capability gating happens earlier in Engine.run —
-                            // by the time we reach here, the model supports vision.
+                            // accepts a base64 data URL as the URL. Non-vision models never
+                            // reach here — stripVisionFromHistory() (top of buildMessages)
+                            // has already swapped their image blocks for text placeholders,
+                            // and Engine.run rejects *new* attachments to non-vision models.
+                            //
+                            // The `detail` hint is honored by OpenAI; OpenAI-compat
+                            // proxies (OpenRouter for non-OpenAI models, etc.) tolerate
+                            // the field even when their backend ignores it, so it's
+                            // safe to always set when settings.images.detail is on.
+                            // OpenAI's wire only accepts "low" / "high" / "auto"; map
+                            // our internal "original" (a Codex-style high-fidelity
+                            // marker) to "high" since OpenAI server-side scales 2048+
+                            // images anyway.
+                            const wireDetail = mapImageDetailToOpenAI(this.imageDetail);
                             imageParts.push({
                                 type: "image_url",
                                 image_url: {
                                     url: `data:${block.source.media_type};base64,${block.source.data}`,
+                                    ...(wireDetail ? { detail: wireDetail } : {}),
                                 },
                             });
                         }
@@ -540,8 +822,55 @@ export class OpenAIClient extends LLMClientBase {
                 }
             }
         }
+        if (this.isOpenRouterAnthropic) {
+            this.applyAnthropicCacheBreakpoints(result);
+        }
         return result;
     }
+    /**
+     * In-place: add prompt-cache breakpoints for Anthropic-over-OpenRouter.
+     * Mirrors the native anthropic provider (≤4 breakpoints):
+     *   1. System block  — the stable prefix. Anthropic sees tools BEFORE the
+     *      system prompt, so one marker on the system block caches tools too
+     *      (verified live: system-only marker cached 3511/3952 prompt tokens
+     *      including tool defs).
+     *   2. Last message  — one rolling breakpoint so the growing conversation
+     *      history becomes a cached prefix. Not scrolled: as history grows the
+     *      "last message" naturally advances and its tail is the next write.
+     * A string `content` is lifted to a single-element `[{type:"text",...}]`
+     * array so it can carry `cache_control`; OpenRouter accepts this OpenAI
+     * multimodal wire form for text.
+     */
+    applyAnthropicCacheBreakpoints(messages) {
+        const mark = (m) => {
+            if (!m)
+                return;
+            // Lift a plain-string content to a text-block array so it can carry the
+            // marker. Non-text content (tool messages, image arrays) already uses an
+            // array of parts — mark the last part instead.
+            if (typeof m.content === "string") {
+                m.content = [
+                    { type: "text", text: m.content, cache_control: { type: "ephemeral" } },
+                ];
+                return;
+            }
+            if (Array.isArray(m.content) && m.content.length > 0) {
+                // cache_control is an Anthropic-via-OpenRouter extension field, not in
+                // the OpenAI content-part union — attach through `unknown`.
+                const last = m.content[m.content.length - 1];
+                last.cache_control = { type: "ephemeral" };
+            }
+        };
+        // 1. System block (always index 0 — buildMessages seeds it first).
+        const sys = messages[0];
+        if (sys && sys.role === "system")
+            mark(sys);
+        // 2. Rolling history breakpoint on the very last message. Skip if it IS the
+        //    system message (no conversation yet) — one breakpoint already covers it.
+        const last = messages[messages.length - 1];
+        if (last && last !== sys)
+            mark(last);
+    }
     convertTools(tools) {
         return tools.map((t) => ({
             type: "function",
@@ -553,22 +882,57 @@ export class OpenAIClient extends LLMClientBase {
         }));
     }
     handleApiError(err) {
+        // User pressed ESC / Stop — the SDK throws APIUserAbortError when
+        // the request's AbortSignal fires mid-flight. Rethrow it unchanged
+        // so callers up the chain (turn-loop → server.ts) can recognise it
+        // as a cancellation rather than a real API failure. Wrapping it
+        // into "OpenAI API error: Request was aborted" was surfacing a
+        // scary toast for what is, from the user's perspective, "I clicked
+        // Stop and it worked."
+        if (err instanceof OpenAI.APIUserAbortError) {
+            throw err;
+        }
         if (err instanceof OpenAI.APIError) {
             if (err.status === 429) {
                 throw new LLMRateLimitError("openai");
             }
             const msg = (err.message ?? "").toLowerCase();
+            // Some 400s are deterministically self-correctable: we flip a sticky
+            // flag that changes the NEXT request body. For those we rethrow a
+            // STATUS-LESS LLMError so withRetry's isClientError() check doesn't bail
+            // (4xx is normally non-retryable) and the immediate retry goes out with
+            // the corrected body — fixing the call that triggered it, not just the
+            // next one.
+            let selfCorrected = false;
             // o-series / gpt-5+ reject `max_tokens` and demand
             // `max_completion_tokens`. The id-based regex catches the common
             // cases; this is the belt-and-suspenders path for ids that ship
             // before the regex knows about them (e.g. new `gpt-5.x` variants
-            // routed via OpenAI-compatible proxies). Flip a sticky flag so the
-            // next request — including `withRetry`'s next attempt — sends the
-            // right field, instead of looping on the same 400.
+            // routed via OpenAI-compatible proxies).
             if (err.status === 400 &&
                 msg.includes("max_tokens") &&
-                msg.includes("max_completion_tokens")) {
+                msg.includes("max_completion_tokens") &&
+                !this._forceMaxCompletionTokens) {
                 this._forceMaxCompletionTokens = true;
+                selfCorrected = true;
+            }
+            // gpt-5.x: "Function tools with reasoning_effort are not supported for
+            // <model> in /v1/chat/completions. Please use /v1/responses instead."
+            // Drop reasoning_effort for the lifetime of the client so the retry —
+            // and every later tool-calling turn — goes through. We can't switch to
+            // /v1/responses here, but tool calls work on /v1/chat/completions as long
+            // as reasoning_effort is absent.
+            if (err.status === 400 &&
+                msg.includes("reasoning_effort") &&
+                (msg.includes("tools") || msg.includes("/v1/responses")) &&
+                !this._dropReasoningEffort) {
+                this._dropReasoningEffort = true;
+                selfCorrected = true;
+            }
+            if (selfCorrected) {
+                // No status in details → withRetry treats it as retryable and reissues
+                // with the now-corrected request body.
+                throw new LLMError(`OpenAI API error (auto-correcting): ${err.message}`, "openai");
             }
             if (msg.includes("context_length_exceeded") ||
                 msg.includes("maximum context length") ||
@@ -593,6 +957,27 @@ export class OpenAIClient extends LLMClientBase {
         throw err;
     }
 }
+/**
+ * Merge `src` into `dst` in place, recursing into plain-object values so a
+ * nested field (e.g. `thinking.type`) from one source doesn't wholesale-replace
+ * the nested object from another. Arrays and non-objects overwrite. `src` wins
+ * on leaf collisions. Used to compose the request body's param fragments
+ * (static extraBody base ← per-request sampling ← reasoning translation) so
+ * shared nested keys like `thinking`/`reasoning` merge instead of clobber.
+ */
+function deepMergeInto(dst, src) {
+    for (const [k, v] of Object.entries(src)) {
+        const cur = dst[k];
+        if (v && typeof v === "object" && !Array.isArray(v) &&
+            cur && typeof cur === "object" && !Array.isArray(cur)) {
+            deepMergeInto(cur, v);
+        }
+        else {
+            dst[k] = v;
+        }
+    }
+    return dst;
+}
 /**
  * Pull a non-empty reasoning payload out of a provider message.
  *
@@ -604,3 +989,25 @@ function extractReasoningContent(msg) {
     const candidate = msg.reasoning_content ?? msg.reasoning;
     return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
 }
+/**
+ * Map our internal image-clarity enum to the OpenAI wire enum.
+ *
+ * OpenAI accepts only `low` / `high` / `auto`. Our provider-agnostic
+ * levels are low / standard / high — the real token saving happens in
+ * the renderer downscale (long-edge cap) before send, so on the wire
+ * we only need the coarse low/high distinction: low→low, while both
+ * standard and high collapse to high (OpenAI's full-tile rendering).
+ *
+ * Legacy "original" (from older settings) is treated as high.
+ *
+ * Returns undefined when the caller didn't set a detail at all, so
+ * the OpenAI client uses its own default ("auto", equivalent to
+ * "high" today).
+ */
+function mapImageDetailToOpenAI(detail) {
+    if (!detail)
+        return undefined;
+    if (detail === "low")
+        return "low";
+    return "high";
+}