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

package/dist/llm/provider-auth.js

@@ -0,0 +1,76 @@
+/**
+ * Provider auth/header resolution for custom model providers (TODO 7.2).
+ *
+ * - `authCommand`: a shell command whose stdout is an auth token. Used for
+ *   short-lived tokens vended by an external tool (gcloud, aws, vault…). The
+ *   result is cached briefly so we don't re-run the command on every request.
+ * - `httpHeaders`: extra headers; a `$ENV_VAR` value is resolved from the
+ *   environment at build time so secrets stay out of settings.json.
+ *
+ * The token-running side is isolated behind a `runCommand` injection so the
+ * env-var + caching logic is unit-testable without spawning a shell.
+ */
+import { createRequire } from "node:module";
+/** Resolve `$ENV` / `${ENV}` placeholders in a header value against `env`. */
+export function resolveHeaderValue(value, env = process.env) {
+    const m = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(value.trim());
+    if (m)
+        return env[m[1]] ?? "";
+    return value;
+}
+/** Resolve every header value's env placeholders, dropping empties. */
+export function resolveHeaders(headers, env = process.env) {
+    const out = {};
+    if (!headers)
+        return out;
+    for (const [k, v] of Object.entries(headers)) {
+        const resolved = resolveHeaderValue(v, env);
+        if (resolved)
+            out[k] = resolved;
+    }
+    return out;
+}
+const tokenCache = new Map();
+/** Token cache TTL — short, since external tokens are usually short-lived. */
+const TOKEN_TTL_MS = 60_000;
+/**
+ * Run an auth command and return its trimmed first line as the token. Caches
+ * by command string for {@link TOKEN_TTL_MS}. `now`/`runCommand` are injectable
+ * for tests. Returns "" if the command yields no output.
+ */
+export function resolveAuthCommand(command, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const cached = tokenCache.get(command);
+    if (cached && cached.expiresAt > now)
+        return cached.token;
+    const run = opts.runCommand ??
+        ((cmd) => {
+            // Lazy require (via createRequire so it works in ESM bundles too) so the
+            // pure helpers above don't pull in child_process at module load.
+            const { execSync } = createRequire(import.meta.url)("node:child_process");
+            return execSync(cmd, { encoding: "utf8", timeout: 30_000 });
+        });
+    const out = run(command) ?? "";
+    const token = out.split("\n")[0]?.trim() ?? "";
+    tokenCache.set(command, { token, expiresAt: now + TOKEN_TTL_MS });
+    return token;
+}
+/** Test seam: clear the token cache. */
+export function __clearAuthTokenCache() {
+    tokenCache.clear();
+}
+/**
+ * Resolve the effective API key for a client: an explicit `apiKey` wins;
+ * otherwise run `authCommand` if present; otherwise fall back to `envKey`
+ * (e.g. process.env.OPENAI_API_KEY). Returns undefined when nothing resolves.
+ */
+export function resolveApiKey(config, envKey, opts = {}) {
+    if (config.apiKey)
+        return config.apiKey;
+    if (config.authCommand) {
+        const token = resolveAuthCommand(config.authCommand, opts);
+        if (token)
+            return token;
+    }
+    return envKey;
+}

package/dist/llm/provider-catalog.d.ts

@@ -11,6 +11,10 @@ export interface ProviderConfig {
     kind: ProviderKindName;
     baseUrl: string;
     apiKey?: string;
+    /** Shell command yielding an auth token (TODO 7.2). See LLMConfig.authCommand. */
+    authCommand?: string;
+    /** Extra HTTP headers for this provider (TODO 7.2). See LLMConfig.httpHeaders. */
+    httpHeaders?: Record<string, string>;
     protocol?: "openai-compat" | "anthropic-style";
     modelsPath?: string;
     /** Default reasoning/thinking setting for this provider. See LLMConfig. */

package/dist/llm/providers/anthropic.js

@@ -7,6 +7,7 @@ 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 { 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
@@ -30,9 +31,12 @@ export class AnthropicClient extends LLMClientBase {
     }
     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,
             });
         }
@@ -101,7 +105,7 @@ export class AnthropicClient extends LLMClientBase {
         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
@@ -118,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,
@@ -133,9 +137,9 @@ 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.
@@ -158,7 +162,7 @@ export class AnthropicClient extends LLMClientBase {
                 ...(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,
@@ -174,7 +178,7 @@ 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;
@@ -195,7 +199,7 @@ export class AnthropicClient extends LLMClientBase {
                 ...(options.temperature !== undefined
                     ? { temperature: options.temperature }
                     : { temperature: this.temperature }),
-            }, { signal: options.signal });
+            }, { signal: requestSignal ?? options.signal });
             let currentText = "";
             let currentToolName = "";
             let currentToolId = "";
@@ -212,12 +216,15 @@ export class AnthropicClient extends LLMClientBase {
                     return;
                 options.onChunk?.(chunk);
             };
-            if (options.signal) {
-                const sig = options.signal;
-                if (sig.aborted)
+            // 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
-                    sig.addEventListener("abort", () => stream.abort(), { once: true });
+                    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.
@@ -373,14 +380,57 @@ 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.

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

@@ -27,6 +27,13 @@ interface RunStreamOpts {
      * 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.
@@ -56,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.
@@ -67,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;
 }