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

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

@@ -1,14 +1,44 @@
 /**
  * Anthropic Claude provider using @anthropic-ai/sdk.
  */
-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";
 export declare class AnthropicClient extends LLMClientBase {
     private _client;
-    constructor(config: LLMConfig);
+    constructor(config: LLMConfig, defaults?: ClientDefaults);
     protected initClient(): void;
     private get client();
+    /**
+     * Resolve the capability descriptor for the current model. `providerKind`
+     * defaults to "anthropic" (this client only serves the Anthropic API).
+     * Memoized — the model doesn't change mid-client.
+     */
+    private _capability;
+    private get capability();
+    /**
+     * Translate the resolved ReasoningSetting into Anthropic's `thinking` field,
+     * honoring the model's reasoning shape (rules.ts):
+     *
+     *  - `anthropic-budget` (Claude 4.0–4.5): supports explicit
+     *    `thinking:{type:"enabled", budget_tokens≥minBudgetTokens}`.
+     *      · mode "budget" → use budgetTokens (clamped up to minBudgetTokens)
+     *      · mode "on"     → default budget (clamped up to minBudgetTokens)
+     *      · mode "effort" → this family is budget-typed, not effort-typed, so
+     *                        treat any effort selection as "on" with the default.
+     *      · mode "off" / unset → return undefined (omit the field).
+     *  - `anthropic-adaptive` (Claude 4.6+): thinking is automatic and NOT
+     *    controllable; sending `type:"enabled"` 400s. Always omit → undefined.
+     *  - anything else (Claude 3.x catch-all → kind "none"): omit → undefined.
+     *
+     * `maxTokens` is the request's max_tokens. Anthropic requires
+     * max_tokens > budget_tokens when thinking is enabled, so we cap the budget
+     * just below it (leaving headroom for the visible answer). The minBudgetTokens
+     * floor still wins — if even the floor doesn't fit under max_tokens the model
+     * itself rejects it, which surfaces as a clear API error rather than us
+     * silently sending a degenerate budget.
+     */
+    private buildThinking;
     createMessage(options: CreateMessageOptions): Promise<LLMResponse>;
     private nonStreamMessage;
     private streamMessage;

package/dist/llm/providers/anthropic.js

@@ -6,26 +6,106 @@ import { LLMClientBase } from "../client-base.js";
 import { ContextLimitError, LLMError, LLMRateLimitError } from "../../exceptions.js";
 import { logger } from "../../logging/logger.js";
 import { countTokens } from "../token-counter.js";
+import { capabilitiesFor } from "../capabilities/index.js";
+import { resolveApiKey, resolveHeaders } from "../provider-auth.js";
+import { stripVisionFromHistory } from "../strip-vision.js";
+/**
+ * Anthropic's `max_tokens` is required, so unlike OpenAI we can't omit it when
+ * the model's ceiling is unknown. Use a conservative floor in that rare case
+ * (every catalog Anthropic model resolves a real value via resolveMaxOutput, so
+ * this only fires for an unconfigured/unknown model).
+ */
+const ANTHROPIC_FALLBACK_MAX_TOKENS = 4096;
+/**
+ * Default thinking budget when a budget-capable model wants "thinking on" but
+ * no explicit token budget was given. Clamped up to the model's minimum.
+ */
+const ANTHROPIC_DEFAULT_THINKING_BUDGET = 4096;
 export class AnthropicClient extends LLMClientBase {
     _client = null;
-    constructor(config) {
-        super(config);
+    constructor(config, defaults) {
+        super(config, defaults);
     }
     initClient() {
         // Lazy init
     }
     get client() {
         if (!this._client) {
+            const headers = resolveHeaders(this.config.httpHeaders);
             this._client = new Anthropic({
-                apiKey: this.config.apiKey ?? process.env.ANTHROPIC_API_KEY,
+                // explicit apiKey > authCommand stdout > ANTHROPIC_API_KEY (TODO 7.2).
+                apiKey: resolveApiKey(this.config, process.env.ANTHROPIC_API_KEY),
                 ...(this.config.baseUrl ? { baseURL: this.config.baseUrl } : {}),
+                ...(Object.keys(headers).length > 0 ? { defaultHeaders: headers } : {}),
                 timeout: this.timeout,
             });
         }
         return this._client;
     }
+    /**
+     * Resolve the capability descriptor for the current model. `providerKind`
+     * defaults to "anthropic" (this client only serves the Anthropic API).
+     * Memoized — the model doesn't change mid-client.
+     */
+    _capability = null;
+    get capability() {
+        if (!this._capability) {
+            const kind = (this.config.providerKind ?? "anthropic");
+            this._capability = capabilitiesFor(kind, this.model);
+        }
+        return this._capability;
+    }
+    /**
+     * Translate the resolved ReasoningSetting into Anthropic's `thinking` field,
+     * honoring the model's reasoning shape (rules.ts):
+     *
+     *  - `anthropic-budget` (Claude 4.0–4.5): supports explicit
+     *    `thinking:{type:"enabled", budget_tokens≥minBudgetTokens}`.
+     *      · mode "budget" → use budgetTokens (clamped up to minBudgetTokens)
+     *      · mode "on"     → default budget (clamped up to minBudgetTokens)
+     *      · mode "effort" → this family is budget-typed, not effort-typed, so
+     *                        treat any effort selection as "on" with the default.
+     *      · mode "off" / unset → return undefined (omit the field).
+     *  - `anthropic-adaptive` (Claude 4.6+): thinking is automatic and NOT
+     *    controllable; sending `type:"enabled"` 400s. Always omit → undefined.
+     *  - anything else (Claude 3.x catch-all → kind "none"): omit → undefined.
+     *
+     * `maxTokens` is the request's max_tokens. Anthropic requires
+     * max_tokens > budget_tokens when thinking is enabled, so we cap the budget
+     * just below it (leaving headroom for the visible answer). The minBudgetTokens
+     * floor still wins — if even the floor doesn't fit under max_tokens the model
+     * itself rejects it, which surfaces as a clear API error rather than us
+     * silently sending a degenerate budget.
+     */
+    buildThinking(reasoning, maxTokens) {
+        const cap = this.capability;
+        if (cap.reasoning.kind !== "anthropic-budget") {
+            // anthropic-adaptive and none: never send a thinking field.
+            return undefined;
+        }
+        if (!reasoning || reasoning.mode === "off") {
+            return undefined;
+        }
+        const min = cap.reasoning.minBudgetTokens;
+        // Anthropic constraint: max_tokens must STRICTLY exceed budget_tokens, and
+        // budget_tokens must be ≥ the model's minimum. If max_tokens can't fit a
+        // min-sized thinking block plus at least `min` tokens of answer, there is
+        // no valid budget — omit thinking entirely rather than emit budget_tokens
+        // ≥ max_tokens (which the API rejects with a 400). This is reachable for
+        // small-maxTokens auxiliary calls (judge/planner) on budget models.
+        const ceiling = maxTokens - min;
+        if (ceiling < min) {
+            return undefined;
+        }
+        let budget = reasoning.mode === "budget"
+            ? reasoning.budgetTokens
+            : ANTHROPIC_DEFAULT_THINKING_BUDGET; // "on" or "effort" → default budget
+        // Clamp into [min, ceiling] — both bounds are now guaranteed ≥ min.
+        budget = Math.min(Math.max(budget, min), ceiling);
+        return { type: "enabled", budget_tokens: budget };
+    }
     async createMessage(options) {
-        return this.withRetry(async () => {
+        return this.withRetry(async (requestSignal) => {
             const messages = this.buildMessages(options.messages);
             const tools = options.tools ? this.convertTools(options.tools) : undefined;
             // One span per outbound LLM request. Begin emits debug-level so the
@@ -42,8 +122,8 @@ export class AnthropicClient extends LLMClientBase {
             });
             try {
                 const response = options.stream && options.onChunk
-                    ? await this.streamMessage(options, messages, tools)
-                    : await this.nonStreamMessage(options, messages, tools);
+                    ? await this.streamMessage(options, messages, tools, requestSignal)
+                    : await this.nonStreamMessage(options, messages, tools, requestSignal);
                 span.end({
                     stopReason: response.stopReason,
                     promptTokens: response.usage?.promptTokens,
@@ -57,13 +137,18 @@ export class AnthropicClient extends LLMClientBase {
                 span.fail(err);
                 throw err;
             }
-        });
+        }, { signal: options.signal });
     }
-    async nonStreamMessage(options, messages, tools) {
+    async nonStreamMessage(options, messages, tools, requestSignal) {
         try {
+            // Per-call reasoning wins; otherwise fall back to the provider/model
+            // default (settings → LLMConfig.reasoning). Mirrors openai.ts.
+            const reasoning = options.reasoning ?? this.config.reasoning;
+            const maxTokens = options.maxTokens ?? this.maxTokens ?? ANTHROPIC_FALLBACK_MAX_TOKENS;
+            const thinking = this.buildThinking(reasoning, maxTokens);
             const response = await this.client.messages.create({
                 model: this.model,
-                max_tokens: options.maxTokens ?? this.maxTokens,
+                max_tokens: maxTokens,
                 system: [
                     {
                         type: "text",
@@ -73,10 +158,11 @@ export class AnthropicClient extends LLMClientBase {
                 ],
                 messages,
                 ...(tools?.length ? { tools } : {}),
+                ...(thinking ? { thinking } : {}),
                 ...(options.temperature !== undefined
                     ? { temperature: options.temperature }
                     : { temperature: this.temperature }),
-            }, { signal: options.signal });
+            }, { signal: requestSignal ?? options.signal });
             const usage = {
                 promptTokens: response.usage.input_tokens,
                 completionTokens: response.usage.output_tokens,
@@ -92,11 +178,14 @@ export class AnthropicClient extends LLMClientBase {
             throw err;
         }
     }
-    async streamMessage(options, messages, tools) {
+    async streamMessage(options, messages, tools, requestSignal) {
         try {
+            const reasoning = options.reasoning ?? this.config.reasoning;
+            const maxTokens = options.maxTokens ?? this.maxTokens ?? ANTHROPIC_FALLBACK_MAX_TOKENS;
+            const thinking = this.buildThinking(reasoning, maxTokens);
             const stream = this.client.messages.stream({
                 model: this.model,
-                max_tokens: options.maxTokens ?? this.maxTokens,
+                max_tokens: maxTokens,
                 system: [
                     {
                         type: "text",
@@ -106,14 +195,37 @@ export class AnthropicClient extends LLMClientBase {
                 ],
                 messages,
                 ...(tools?.length ? { tools } : {}),
+                ...(thinking ? { thinking } : {}),
                 ...(options.temperature !== undefined
                     ? { temperature: options.temperature }
                     : { temperature: this.temperature }),
-            }, { signal: options.signal });
+            }, { signal: requestSignal ?? options.signal });
             let currentText = "";
             let currentToolName = "";
             let currentToolId = "";
             let currentToolInput = "";
+            // Abort-guarded emit: once the turn is cancelled, stop forwarding chunks
+            // to the UI. The SDK's event emitter can keep firing buffered text/
+            // contentBlock/inputJson events after abort() until its HTTP stream tears
+            // down; without this guard those leak to the UI after the user hit Stop
+            // ("content comes back after interrupt"). We also eagerly abort the SDK
+            // stream below so teardown starts immediately rather than waiting on the
+            // passed-in request signal alone.
+            const emit = (chunk) => {
+                if (options.signal?.aborted)
+                    return;
+                options.onChunk?.(chunk);
+            };
+            // Tear the SDK stream down on EITHER the user's cancel OR the per-request
+            // deadline (requestSignal composes both) — a wedged stream then aborts
+            // instead of hanging on the SDK's unreliable timeout.
+            const teardownSig = requestSignal ?? options.signal;
+            if (teardownSig) {
+                if (teardownSig.aborted)
+                    stream.abort();
+                else
+                    teardownSig.addEventListener("abort", () => stream.abort(), { once: true });
+            }
             // Time-to-first-byte: log exactly once per stream so streaming-latency
             // questions ("model felt slow tonight") get a clean number per request.
             const streamStartedAt = Date.now();
@@ -129,14 +241,14 @@ export class AnthropicClient extends LLMClientBase {
                     });
                 }
                 currentText += text;
-                options.onChunk?.({ type: "text", text, tokens: countTokens(text) });
+                emit({ type: "text", text, tokens: countTokens(text) });
             });
             stream.on("contentBlock", (block) => {
                 if (block.type === "tool_use") {
                     currentToolName = block.name;
                     currentToolId = block.id;
                     currentToolInput = "";
-                    options.onChunk?.({
+                    emit({
                         type: "tool_use_start",
                         toolCall: { id: block.id, toolName: block.name, args: {} },
                     });
@@ -145,7 +257,7 @@ export class AnthropicClient extends LLMClientBase {
             stream.on("inputJson", (_delta, snapshot) => {
                 currentToolInput = JSON.stringify(snapshot);
                 if (currentToolId) {
-                    options.onChunk?.({
+                    emit({
                         type: "tool_use_delta",
                         toolCall: {
                             id: currentToolId,
@@ -195,6 +307,7 @@ export class AnthropicClient extends LLMClientBase {
         };
     }
     buildMessages(messages) {
+        messages = stripVisionFromHistory(messages, this.capability.supportsVision);
         const result = [];
         for (const msg of messages) {
             if (msg.role === "system")
@@ -218,10 +331,37 @@ export class AnthropicClient extends LLMClientBase {
                         });
                     }
                     else if (block.type === "tool_result" && block.tool_use_id) {
+                        let content;
+                        if (typeof block.content === "string") {
+                            content = block.content;
+                        }
+                        else if (Array.isArray(block.content)) {
+                            const parts = [];
+                            for (const part of block.content) {
+                                if (part.type === "text" && part.text) {
+                                    parts.push({ type: "text", text: part.text });
+                                }
+                                else if (part.type === "image" && part.source) {
+                                    parts.push({
+                                        type: "image",
+                                        source: {
+                                            type: "base64",
+                                            media_type: part.source.media_type,
+                                            data: part.source.data,
+                                        },
+                                    });
+                                }
+                            }
+                            content = parts;
+                        }
+                        else {
+                            content = "";
+                        }
                         blocks.push({
                             type: "tool_result",
                             tool_use_id: block.tool_use_id,
-                            content: typeof block.content === "string" ? block.content : "",
+                            content,
+                            ...(block.is_error ? { is_error: true } : {}),
                         });
                     }
                     else if (block.type === "image" && block.source) {
@@ -240,16 +380,65 @@ export class AnthropicClient extends LLMClientBase {
                 }
             }
         }
+        // Prompt-cache breakpoint on the history: mark the LAST content block of
+        // the LAST message. The API caches everything up to the marker, so the
+        // stable prefix (all prior turns) is reused; only the growing tail is
+        // re-billed. CC does exactly this (one marker at messages.length - 1) and
+        // warns a second history marker causes KV page eviction. We only ANNOTATE
+        // the tail block — never reorder — so the tool_use/tool_result adjacency
+        // invariant is untouched. A string-content message is lifted to a single
+        // text block so it can carry cache_control. See
+        // docs/todo/prompt-cache-optimization.md.
+        const lastMsg = result[result.length - 1];
+        if (lastMsg) {
+            if (typeof lastMsg.content === "string") {
+                lastMsg.content = [
+                    {
+                        type: "text",
+                        text: lastMsg.content,
+                        cache_control: { type: "ephemeral" },
+                    },
+                ];
+            }
+            else {
+                const lastBlock = lastMsg.content[lastMsg.content.length - 1];
+                // Skip thinking/redacted_thinking blocks: they reject cache_control and
+                // marking them would 400. buildMessages never emits them today (thinking
+                // is a top-level request field, not history content), but guard anyway
+                // so a future block type can't silently break the request.
+                if (lastBlock &&
+                    lastBlock.type !== "thinking" &&
+                    lastBlock.type !== "redacted_thinking") {
+                    lastBlock.cache_control = { type: "ephemeral" };
+                }
+            }
+        }
         return result;
     }
     convertTools(tools) {
-        return tools.map((t) => ({
+        const converted = tools.map((t) => ({
             name: t.name,
             description: t.description,
             input_schema: t.inputSchema,
         }));
+        // Prompt-cache breakpoint: mark ONLY the last tool. The API caches every
+        // block up to and including a cache_control marker, so one marker on the
+        // tail makes the whole (stable) tools array a cached prefix — vs 73
+        // definitions re-billed as input every turn. CC does the same (one marker,
+        // not per-tool); a second marker here would waste a scarce cache_control
+        // slot (max 4) and risk KV eviction. See docs/todo/prompt-cache-optimization.md.
+        const last = converted[converted.length - 1];
+        if (last)
+            last.cache_control = { type: "ephemeral" };
+        return converted;
     }
     handleApiError(err) {
+        // ESC / Stop path — see openai.ts handleApiError for the same logic.
+        // Rethrow the SDK's abort error unchanged so server.ts recognises
+        // cancellation; don't repackage it as a generic "Anthropic API error".
+        if (err instanceof Anthropic.APIUserAbortError) {
+            throw err;
+        }
         if (err instanceof Anthropic.APIError) {
             if (err.status === 429) {
                 throw new LLMRateLimitError("anthropic");

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,21 @@ 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;
+    /**
+     * Per-call override of the watchdog. Leave undefined to follow the env
+     * default (STREAM_WATCHDOG_CONFIG.enabled). Set false to force the fast
+     * path even when the watchdog is enabled globally; passing idleTimeoutMs
+     * still re-activates it (an explicit timeout means the caller wants it).
+     */
+    disableWatchdog?: boolean;
 }
 /**
  * Consume an async iterable of stream chunks with an idle watchdog.
@@ -35,7 +50,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();
     /**
@@ -47,6 +63,20 @@ export declare class OpenAIClient extends LLMClientBase {
      */
     private _capability;
     private get 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/".
+     */
+    private get isOpenRouterAnthropic();
     createMessage(options: CreateMessageOptions): Promise<LLMResponse>;
     /**
      * Build the request body honoring the model's capability descriptor.
@@ -58,6 +88,21 @@ export declare class OpenAIClient extends LLMClientBase {
     private streamMessage;
     private processChoice;
     private buildMessages;
+    /**
+     * 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.
+     */
+    private applyAnthropicCacheBreakpoints;
     private convertTools;
     private handleApiError;
 }