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

package/dist/llm/providers/openai.d.ts

@@ -7,7 +7,7 @@
  * field name, rejected sampling params, thinking knob, reasoning echo —
  * is resolved through `capabilitiesFor()`, not hardcoded.
  */
-import type { LLMConfig, LLMResponse } from "../../types.js";
+import type { ClientDefaults, LLMConfig, LLMResponse } from "../../types.js";
 import type { CreateMessageOptions } from "../types.js";
 import { LLMClientBase } from "../client-base.js";
 interface RunStreamOpts {
@@ -19,6 +19,14 @@ interface RunStreamOpts {
      * the watchdog-side text accumulator used in tests.
      */
     onChunk?: (chunk: any) => string;
+    /**
+     * Abort signal. Checked BEFORE handing each chunk to onChunk so a cancelled
+     * turn stops emitting text_delta immediately — the SDK keeps yielding
+     * already-buffered chunks after abort() until its HTTP teardown completes, and
+     * without this guard those buffered deltas leak to the UI after the user hit
+     * Stop ("content comes back after interrupt").
+     */
+    signal?: AbortSignal;
 }
 /**
  * Consume an async iterable of stream chunks with an idle watchdog.
@@ -35,7 +43,8 @@ export declare function runStreamWithWatchdog<T = any>(stream: AsyncIterable<T>,
 export declare class OpenAIClient extends LLMClientBase {
     private _client;
     private _forceMaxCompletionTokens;
-    constructor(config: LLMConfig);
+    private _dropReasoningEffort;
+    constructor(config: LLMConfig, defaults?: ClientDefaults);
     protected initClient(): void;
     private get client();
     /**

package/dist/llm/providers/openai.js

@@ -13,6 +13,8 @@ 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 { stripVisionFromHistory } from "../strip-vision.js";
 import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError, } from "../stream-watchdog.js";
 /**
  * Consume an async iterable of stream chunks with an idle watchdog.
@@ -32,6 +34,13 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
     // 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 +55,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 +68,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,8 +122,15 @@ 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
@@ -121,10 +162,10 @@ export class OpenAIClient extends LLMClientBase {
     }
     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);
+            // 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 +177,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)
+                    : await this.nonStreamMessage(options, messages, tools, reasoning);
                 span.end({
                     stopReason: response.stopReason,
                     promptTokens: response.usage?.promptTokens,
@@ -158,49 +199,59 @@ export class OpenAIClient extends LLMClientBase {
      * 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 };
+        const tokenLimit = maxTokens === undefined
+            ? {}
+            : useCompletion
+                ? { max_completion_tokens: maxTokens }
+                : { max_tokens: maxTokens };
         // Sampling params — only include if the model accepts them.
         const sampling = {};
         if (!cap.rejectedParams.has("temperature")) {
             sampling.temperature =
                 options.temperature !== undefined ? options.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 = {};
+        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 entirely once the endpoint has told us `reasoning_effort` is
+                    // incompatible with `tools` here (see _dropReasoningEffort) — sending
+                    // it again would just re-trigger the same 400.
+                    if (!this._dropReasoningEffort) {
+                        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 +261,39 @@ 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.
+                    if (!this._dropReasoningEffort) {
+                        reasoningBody.reasoning_effort = cap.reasoning.disabledEffort ?? "minimal";
+                    }
+                    break;
+                case "openrouter-reasoning":
+                    reasoningBody.reasoning = { effort: "minimal", exclude: true };
+                    break;
+                default:
+                    break;
+            }
+        }
         return {
             model: this.model,
             messages,
             ...tokenLimit,
             ...sampling,
-            ...reasoning,
+            ...reasoningBody,
             ...(tools ? { tools } : {}),
             ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
         };
     }
-    async nonStreamMessage(options, messages, tools, thinking) {
+    async nonStreamMessage(options, messages, tools, reasoning) {
         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: options.signal });
             const choice = response.choices[0];
             if (!choice)
                 throw new LLMError("No response from OpenAI", "openai");
@@ -239,13 +310,18 @@ export class OpenAIClient extends LLMClientBase {
             throw err;
         }
     }
-    async streamMessage(options, messages, tools, thinking) {
+    async streamMessage(options, messages, tools, reasoning) {
         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: options.signal });
             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 +333,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 "";
@@ -329,6 +410,7 @@ export class OpenAIClient extends LLMClientBase {
                     : undefined,
                 requestId,
                 onChunk: handleChunk,
+                signal: options.signal,
             });
             const toolCalls = [];
             for (const [, tc] of toolCallsMap) {
@@ -349,7 +431,7 @@ export class OpenAIClient extends LLMClientBase {
                 text,
                 toolCalls,
                 usage,
-                stopReason: "stop",
+                stopReason: finishReason ?? "stop",
                 ...(reasoningContent ? { reasoningContent } : {}),
             };
         }
@@ -384,8 +466,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 +486,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 +580,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 +625,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 } : {}),
                                 },
                             });
                         }
@@ -543,6 +677,17 @@ export class OpenAIClient extends LLMClientBase {
         return result;
     }
     convertTools(tools) {
+        // DEBUG: OpenAI rejects tool names that don't match ^[a-zA-Z0-9_-]+$.
+        // Dump the full list with index + source so we can pin which tool
+        // (e.g. tools[33]) carries the illegal name. Remove once diagnosed.
+        const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+        logger.info("openai.convertTools.names", {
+            count: tools.length,
+            names: tools.map((t, i) => `[${i}] ${t.name}${NAME_RE.test(t.name) ? "" : "  <-- ILLEGAL"} (src=${t.source ?? "?"})`),
+            illegal: tools
+                .map((t, i) => ({ i, name: t.name, source: t.source }))
+                .filter((x) => !NAME_RE.test(x.name)),
+        });
         return tools.map((t) => ({
             type: "function",
             function: {
@@ -553,22 +698,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") ||
@@ -604,3 +784,24 @@ function extractReasoningContent(msg) {
     const candidate = msg.reasoning_content ?? msg.reasoning;
     return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
 }
+/**
+ * Map our internal image-detail enum to the OpenAI wire enum.
+ *
+ * OpenAI accepts only `low` / `high` / `auto`. We carry an extra
+ * `original` value through settings/config to match the Codex
+ * concept (preserve client-side dimensions, most expensive), but on
+ * the wire it has to collapse to `high` — OpenAI's server scales
+ * 2048+ images down regardless, so this is the closest faithful
+ * mapping.
+ *
+ * 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";
+}

package/dist/llm/reasoning-setting.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ReasoningSetting — the rich, normalized reasoning/thinking config that
+ * replaces the old binary `thinking: "enabled"|"disabled"`.
+ *
+ *  - off    : no thinking (openai-effort → disabledEffort; deepseek → type:disabled; openrouter → exclude)
+ *  - on     : binary "thinking on" for deepseek-thinking / zai (no effort levels)
+ *  - effort : openai-effort / openrouter — pick a level
+ *  - budget : anthropic-budget — explicit thinking token budget
+ *
+ * `normalizeReasoning` accepts the legacy "enabled"/"disabled" strings so any
+ * lingering caller/config still works (mapped to on/off).
+ */
+import { z } from "zod";
+import type { ReasoningEffort } from "./capabilities/types.js";
+export declare const REASONING_EFFORTS: readonly ["minimal", "low", "medium", "high", "xhigh"];
+export declare const ReasoningSettingSchema: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
+    mode: z.ZodLiteral<"off">;
+}, "strip", z.ZodTypeAny, {
+    mode: "off";
+}, {
+    mode: "off";
+}>, z.ZodObject<{
+    mode: z.ZodLiteral<"on">;
+}, "strip", z.ZodTypeAny, {
+    mode: "on";
+}, {
+    mode: "on";
+}>, z.ZodObject<{
+    mode: z.ZodLiteral<"effort">;
+    effort: z.ZodEnum<["minimal", "low", "medium", "high", "xhigh"]>;
+}, "strip", z.ZodTypeAny, {
+    mode: "effort";
+    effort: "minimal" | "low" | "medium" | "high" | "xhigh";
+}, {
+    mode: "effort";
+    effort: "minimal" | "low" | "medium" | "high" | "xhigh";
+}>, z.ZodObject<{
+    mode: z.ZodLiteral<"budget">;
+    budgetTokens: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    mode: "budget";
+    budgetTokens: number;
+}, {
+    mode: "budget";
+    budgetTokens: number;
+}>]>;
+export type ReasoningSetting = z.infer<typeof ReasoningSettingSchema>;
+/** Coerce legacy "enabled"/"disabled" or an object into a ReasoningSetting. */
+export declare function normalizeReasoning(raw: ReasoningSetting | "enabled" | "disabled" | undefined): ReasoningSetting | undefined;
+/** Effort to send when a model wants "thinking on" but the user picked no level. */
+export declare const DEFAULT_EFFORT: ReasoningEffort;

package/dist/llm/reasoning-setting.js

@@ -0,0 +1,32 @@
+/**
+ * ReasoningSetting — the rich, normalized reasoning/thinking config that
+ * replaces the old binary `thinking: "enabled"|"disabled"`.
+ *
+ *  - off    : no thinking (openai-effort → disabledEffort; deepseek → type:disabled; openrouter → exclude)
+ *  - on     : binary "thinking on" for deepseek-thinking / zai (no effort levels)
+ *  - effort : openai-effort / openrouter — pick a level
+ *  - budget : anthropic-budget — explicit thinking token budget
+ *
+ * `normalizeReasoning` accepts the legacy "enabled"/"disabled" strings so any
+ * lingering caller/config still works (mapped to on/off).
+ */
+import { z } from "zod";
+export const REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh"];
+export const ReasoningSettingSchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("off") }),
+    z.object({ mode: z.literal("on") }),
+    z.object({ mode: z.literal("effort"), effort: z.enum(REASONING_EFFORTS) }),
+    z.object({ mode: z.literal("budget"), budgetTokens: z.number().int().positive() }),
+]);
+/** Coerce legacy "enabled"/"disabled" or an object into a ReasoningSetting. */
+export function normalizeReasoning(raw) {
+    if (raw == null)
+        return undefined;
+    if (raw === "enabled")
+        return { mode: "on" };
+    if (raw === "disabled")
+        return { mode: "off" };
+    return raw;
+}
+/** Effort to send when a model wants "thinking on" but the user picked no level. */
+export const DEFAULT_EFFORT = "medium";

package/dist/llm/stop-reason.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared stop-reason helpers.
+ *
+ * Providers report "the response was cut off at the output-token cap" with
+ * different finish/stop-reason strings:
+ *   - OpenAI / OpenAI-compat:  finish_reason "length"
+ *   - Anthropic:               stop_reason  "max_tokens"
+ *
+ * The turn loop uses this to decide whether to run a max-output
+ * continuation, so the check must accept both spellings.
+ */
+/** True when the stop reason indicates the model hit its output-token cap. */
+export declare function isTruncatedStop(stopReason: string | undefined): boolean;

package/dist/llm/stop-reason.js

@@ -0,0 +1,21 @@
+/**
+ * Shared stop-reason helpers.
+ *
+ * Providers report "the response was cut off at the output-token cap" with
+ * different finish/stop-reason strings:
+ *   - OpenAI / OpenAI-compat:  finish_reason "length"
+ *   - Anthropic:               stop_reason  "max_tokens"
+ *
+ * The turn loop uses this to decide whether to run a max-output
+ * continuation, so the check must accept both spellings.
+ */
+const TRUNCATED_STOP_REASONS = new Set([
+    "length", // OpenAI / OpenAI-compatible
+    "max_tokens", // Anthropic
+]);
+/** True when the stop reason indicates the model hit its output-token cap. */
+export function isTruncatedStop(stopReason) {
+    if (!stopReason)
+        return false;
+    return TRUNCATED_STOP_REASONS.has(stopReason);
+}