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

package/dist/llm/providers/openai.js

@@ -14,8 +14,33 @@ 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
@@ -28,7 +53,12 @@ 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.
@@ -137,9 +167,15 @@ export class OpenAIClient extends LLMClientBase {
     }
     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,
             });
         }
@@ -160,8 +196,27 @@ 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 () => {
+        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;
@@ -177,8 +232,8 @@ export class OpenAIClient extends LLMClientBase {
             });
             try {
                 const response = options.stream && options.onChunk
-                    ? await this.streamMessage(options, messages, tools, reasoning)
-                    : await this.nonStreamMessage(options, messages, tools, reasoning);
+                    ? 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,
@@ -192,7 +247,7 @@ export class OpenAIClient extends LLMClientBase {
                 span.fail(err);
                 throw err;
             }
-        });
+        }, { signal: options.signal });
     }
     /**
      * Build the request body honoring the model's capability descriptor.
@@ -216,11 +271,23 @@ export class OpenAIClient extends LLMClientBase {
             : useCompletion
                 ? { max_completion_tokens: maxTokens }
                 : { max_tokens: maxTokens };
-        // Sampling params — only include if the model accepts them.
-        const sampling = {};
+        // 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 — translate the user's ReasoningSetting to the wire
         // shape. Different vendors, different fields, never combine. We read the
@@ -228,6 +295,15 @@ export class OpenAIClient extends LLMClientBase {
         // 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":
@@ -240,10 +316,11 @@ export class OpenAIClient extends LLMClientBase {
                     // Mistral magistral, Groq reasoning models — `reasoning_effort`.
                     // 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) {
+                    // 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";
                     }
@@ -269,8 +346,9 @@ export class OpenAIClient extends LLMClientBase {
                     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) {
+                    // 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;
@@ -281,19 +359,58 @@ export class OpenAIClient extends LLMClientBase {
                     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,
-            ...reasoningBody,
+            ...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, reasoning) {
+    async nonStreamMessage(options, messages, tools, reasoning, requestSignal) {
         try {
-            const response = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, reasoning, 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");
@@ -301,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);
@@ -310,9 +430,10 @@ export class OpenAIClient extends LLMClientBase {
             throw err;
         }
     }
-    async streamMessage(options, messages, tools, reasoning) {
+    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, reasoning, 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();
@@ -368,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)
@@ -405,26 +533,42 @@ 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: options.signal,
+                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 {
@@ -449,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,
@@ -674,20 +822,56 @@ 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) {
-        // 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: {
@@ -773,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.
  *
@@ -785,14 +990,15 @@ function extractReasoningContent(msg) {
     return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
 }
 /**
- * Map our internal image-detail enum to the OpenAI wire enum.
+ * 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).
  *
- * 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.
+ * 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

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

@@ -27,13 +27,13 @@ export declare const ReasoningSettingSchema: z.ZodDiscriminatedUnion<"mode", [z.
     mode: "on";
 }>, z.ZodObject<{
     mode: z.ZodLiteral<"effort">;
-    effort: z.ZodEnum<["minimal", "low", "medium", "high", "xhigh"]>;
+    effort: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     mode: "effort";
-    effort: "minimal" | "low" | "medium" | "high" | "xhigh";
+    effort: string;
 }, {
     mode: "effort";
-    effort: "minimal" | "low" | "medium" | "high" | "xhigh";
+    effort: string;
 }>, z.ZodObject<{
     mode: z.ZodLiteral<"budget">;
     budgetTokens: z.ZodNumber;

package/dist/llm/reasoning-setting.js

@@ -11,11 +11,19 @@
  * lingering caller/config still works (mapped to on/off).
  */
 import { z } from "zod";
+// Recommended effort levels — used to render UI dropdowns and as capability
+// hints. NOT a hard schema constraint: effort is a free-form, catalog-driven
+// param (a model's real ladder is declared by its catalog ParamSpec, and models
+// gain/rename levels over time — e.g. gpt-5.5 added "xhigh", some models accept
+// "max"). The settings schema validates the *shape* (mode/field names), not the
+// *value*; pinning effort to a closed enum here made one unknown level
+// (a connection's paramValues.reasoning flowing through the legacy models[]
+// bridge) throw in validateSettings and take the whole app down on boot.
 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("effort"), effort: z.string().min(1) }),
     z.object({ mode: z.literal("budget"), budgetTokens: z.number().int().positive() }),
 ]);
 /** Coerce legacy "enabled"/"disabled" or an object into a ReasoningSetting. */

package/dist/llm/stream-watchdog.js

@@ -64,7 +64,11 @@ export function createStreamWatchdog(opts) {
 }
 /** Environment-driven defaults. Read once at import time is fine — these never change inside a process. */
 export const STREAM_WATCHDOG_CONFIG = {
-    enabled: process.env.CODESHELL_ENABLE_STREAM_WATCHDOG === "1",
+    // ON by default — a streamed response that connects then stalls mid-flight
+    // would otherwise hang until the SDK's (unreliable-for-half-dead-sockets)
+    // timeout, which we observed take 15–33 min in practice. Opt OUT with
+    // CODESHELL_ENABLE_STREAM_WATCHDOG=0 (rollback knob).
+    enabled: process.env.CODESHELL_ENABLE_STREAM_WATCHDOG !== "0",
     idleTimeoutMs: parseInt(process.env.CODESHELL_STREAM_IDLE_TIMEOUT_MS || "", 10) || 90_000,
     retries: parseInt(process.env.CODESHELL_STREAM_WATCHDOG_RETRIES || "", 10) || 2,
 };

package/dist/llm/token-counter.js

@@ -18,9 +18,16 @@ async function getEncoder() {
 }
 let encoderSync = null;
 // Kick off the import so synchronous callers can use it on the next tick.
-// First call still falls back to a length estimate.
-void getEncoder().then((fn) => {
+// First call still falls back to a length estimate. The .catch keeps a failed
+// import (corrupt node_modules / packaging error) from becoming an unhandled
+// rejection — the chars/4 fallback below IS the intended degradation, so a
+// load failure should stay silent, not surface as a process-level warning/crash.
+void getEncoder()
+    .then((fn) => {
     encoderSync = fn;
+})
+    .catch(() => {
+    /* encoder unavailable — count() falls back to the length estimate */
 });
 /**
  * Count tokens in `text`. Synchronous. If the encoder isn't loaded yet,

package/dist/llm/types.d.ts

@@ -32,5 +32,9 @@ export interface LLMUsageTracker {
     totalPromptTokens: number;
     totalCompletionTokens: number;
     totalTokens: number;
+    /** Sum of cache-read tokens across responses (0 when no provider reported any). */
+    totalCacheReadTokens: number;
+    /** Sum of cache-creation tokens across responses. */
+    totalCacheCreationTokens: number;
     requestCount: number;
 }

package/dist/logging/sanitize-messages.js

@@ -139,6 +139,23 @@ export function sanitizeMessages(messages) {
 // These walkers redact secrets *in place on a deep clone* so the caller
 // can still log "useful shape, scrubbed values".
 const SECRET_KEY_RE = /(^|[._-])(api[_-]?key|authorization|x[_-]api[_-]key|bearer[_-]?token|access[_-]?token|refresh[_-]?token|session[_-]?token|token|secret|password|client[_-]?secret|cookie)($|[._-])/i;
+// Header containers whose VALUES are all header values — any of them can carry
+// a bespoke auth token under a non-secret-looking key name (e.g.
+// `x-custom-auth`), which SECRET_KEY_RE alone would miss. Treat the whole
+// container as sensitive: every non-empty value inside is redacted.
+const HEADERS_CONTAINER_RE = /^(httpHeaders|headers|defaultHeaders|envHeaders)$/;
+/** Redact all non-empty string/scalar values of a headers container object. */
+function redactHeaderValues(headers) {
+    const out = {};
+    for (const [hName, hVal] of Object.entries(headers)) {
+        // Preserve present-vs-absent for empty/null, redact everything else.
+        if (hVal === null || hVal === undefined || hVal === "")
+            out[hName] = hVal;
+        else
+            out[hName] = REDACTED;
+    }
+    return out;
+}
 const BEARER_RE = /\bBearer\s+[A-Za-z0-9._\-+/=~]{8,}/g;
 // URL query parameters that look like credentials. Conservative — only
 // trigger on a small named set so a normal `?id=…&q=…` URL passes through.
@@ -211,6 +228,11 @@ export function redactSecrets(value, depth = 0) {
                 else
                     out[k] = REDACTED;
             }
+            else if (HEADERS_CONTAINER_RE.test(k) && v && typeof v === "object" && !Array.isArray(v)) {
+                // Blanket-redact header values regardless of the inner header name, so a
+                // custom `x-custom-auth` doesn't leak in cleartext.
+                out[k] = redactHeaderValues(v);
+            }
             else {
                 out[k] = redactSecrets(v, depth + 1);
             }

package/dist/lsp/manager.d.ts

@@ -33,8 +33,8 @@ export declare class LSPServerManager {
      * Shutdown all servers.
      */
     shutdownAll(): Promise<void>;
-    private isCommandAvailable;
 }
+export declare function isCommandAvailable(command: string, env?: NodeJS.ProcessEnv): boolean;
 export declare function initializeLSPManager(cwd: string): LSPServerManager;
 export declare function getLSPManager(): LSPServerManager | undefined;
 export {};