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

package/dist/llm/client-base.js

@@ -3,15 +3,26 @@
  */
 import { LLMError, ContextLimitError, LLMRateLimitError } from "../exceptions.js";
 import { logger } from "../logging/logger.js";
+function emptyUsageTracker() {
+    return {
+        records: [],
+        totalPromptTokens: 0,
+        totalCompletionTokens: 0,
+        totalTokens: 0,
+        totalCacheReadTokens: 0,
+        totalCacheCreationTokens: 0,
+        requestCount: 0,
+    };
+}
 export class LLMClientBase {
     config;
     provider;
     model;
-    temperature;
     maxTokens;
+    temperature;
     timeout;
     retryMaxAttempts;
-    enableStreaming;
+    imageDetail;
     /**
      * Process-wide hook fired on every LLM response. The CLI installs this in
      * main.ts to feed the cost tracker; lives on the base class so every code
@@ -19,22 +30,27 @@ export class LLMClientBase {
      * each call site needing to remember.
      */
     static onUsage;
-    usage = {
-        records: [],
-        totalPromptTokens: 0,
-        totalCompletionTokens: 0,
-        totalTokens: 0,
-        requestCount: 0,
-    };
-    constructor(config) {
+    usage = emptyUsageTracker();
+    /**
+     * `config` carries model identity (provider/model/apiKey/baseUrl/maxTokens/
+     * thinking/providerKind). `defaults` carries cross-model runtime knobs
+     * (temperature/timeout/retryMaxAttempts/imageDetail) — those are owned by
+     * the Engine and stay stable across hot model switches.
+     */
+    constructor(config, defaults) {
         this.config = config;
         this.provider = config.provider;
         this.model = config.model;
-        this.temperature = config.temperature ?? 0.3;
-        this.maxTokens = config.maxTokens ?? 8192;
-        this.timeout = config.timeout ?? 120_000;
-        this.retryMaxAttempts = config.retryMaxAttempts ?? 3;
-        this.enableStreaming = config.enableStreaming ?? true;
+        // No `?? 8192` fallback: when the model's output ceiling is unknown we keep
+        // `undefined` so each provider decides (OpenAI omits the field and lets the
+        // endpoint use its own max; Anthropic, where max_tokens is required, supplies
+        // a conservative default at request time). Forcing 8192 here truncated long
+        // outputs — a streamed tool-arg JSON cut off mid-token → "Missing file_path".
+        this.maxTokens = config.maxTokens;
+        this.temperature = defaults?.temperature ?? 0.3;
+        this.timeout = defaults?.timeout ?? 120_000;
+        this.retryMaxAttempts = defaults?.retryMaxAttempts ?? 3;
+        this.imageDetail = defaults?.imageDetail;
         this.initClient();
     }
     recordUsage(usage, options) {
@@ -44,23 +60,112 @@ export class LLMClientBase {
         this.usage.totalPromptTokens += usage.promptTokens;
         this.usage.totalCompletionTokens += usage.completionTokens;
         this.usage.totalTokens += usage.totalTokens;
+        this.usage.totalCacheReadTokens += usage.cacheReadTokens ?? 0;
+        this.usage.totalCacheCreationTokens += usage.cacheCreationTokens ?? 0;
         this.usage.requestCount++;
         LLMClientBase.onUsage?.(this.model, usage);
     }
     getUsage() {
         return { ...this.usage };
     }
-    async withRetry(fn, maxAttempts) {
-        const attempts = maxAttempts ?? this.retryMaxAttempts;
+    /** Zero all accumulated usage. Used when starting a fresh accounting window
+     *  (e.g. after a model switch, where the prior model's cache stats no longer
+     *  apply). */
+    resetUsage() {
+        this.usage = emptyUsageTracker();
+    }
+    /**
+     * Compose the caller's AbortSignal with a hard per-request deadline.
+     *
+     * The provider SDKs accept a `timeout`, but in practice it does NOT fire for
+     * a *half-dead socket* (TCP connected, keep-alives flowing, but no response
+     * bytes) — we have observed real requests hang 15–33 minutes before the SDK
+     * finally surfaced "Socket timeout". The streaming idle-watchdog only covers
+     * the gap BETWEEN chunks, not connection setup / first byte, and non-stream
+     * calls don't go through it at all. An explicit AbortSignal.timeout is the
+     * one mechanism that reliably tears such a request down.
+     *
+     * Returns a signal to hand the SDK (`{ signal }`) plus a `cleanup()` to clear
+     * the timer once the request settles. The deadline is generous (default 2×
+     * the SDK timeout, min 120s) — long enough for slow-but-alive generations,
+     * short enough that a wedged socket can't burn half an hour.
+     */
+    withRequestDeadline(callerSignal) {
+        const deadlineMs = Math.max(this.timeout * 2, 120_000);
+        const deadline = AbortSignal.timeout(deadlineMs);
+        // AbortSignal.any is available in Node ≥20 / Bun; combine so EITHER the
+        // user's cancel OR the deadline aborts the request.
+        const signal = callerSignal
+            ? AbortSignal.any([callerSignal, deadline])
+            : deadline;
+        // AbortSignal.timeout's timer is unref'd by the runtime; no manual clear is
+        // strictly required, but expose cleanup for symmetry / future tightening.
+        return { signal, cleanup: () => { } };
+    }
+    async withRetry(fn, opts) {
+        const attempts = opts?.maxAttempts ?? this.retryMaxAttempts;
+        const signal = opts?.signal;
         let lastError;
         for (let attempt = 1; attempt <= attempts; attempt++) {
+            // Bail BEFORE issuing (or re-issuing) the request if the run was
+            // cancelled. Without this, a cancel that lands during a backoff sleep —
+            // or while a flaky connection hangs — still re-fires the same doomed
+            // request, so the user's Stop "does nothing" until all attempts +
+            // backoffs drain (~50 s for a 3× Connection-error loop). Checking here
+            // makes Cancel take effect at the next retry boundary.
+            if (signal?.aborted) {
+                throw new DOMException("Request cancelled", "AbortError");
+            }
+            // Per-attempt hard deadline composed with the caller's cancel signal.
+            // A half-dead socket that ignores the SDK timeout is torn down here.
+            const { signal: requestSignal, cleanup } = this.withRequestDeadline(signal);
             try {
-                return await fn();
+                return await fn(requestSignal);
             }
             catch (err) {
                 lastError = err;
                 if (err instanceof ContextLimitError)
                     throw err;
+                // Distinguish a deadline tear-down from a user cancel. When the caller
+                // did NOT abort but the request signal did, the per-request deadline
+                // fired (wedged socket). That is RETRYABLE — fall through to the normal
+                // retry/backoff path rather than the abort-no-retry guard below, since
+                // the upstream may have just recovered.
+                const deadlineFired = !signal?.aborted && requestSignal.aborted;
+                if (deadlineFired) {
+                    logger.warn("llm.request_deadline", {
+                        cat: "llm",
+                        provider: this.provider,
+                        model: this.model,
+                        attempt,
+                        of: attempts,
+                    });
+                    if (attempt < attempts) {
+                        const backoff = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
+                        if (await abortableSleep(backoff, signal)) {
+                            throw new DOMException("Request cancelled during retry backoff", "AbortError");
+                        }
+                        continue;
+                    }
+                    throw new LLMError(`request exceeded deadline (${Math.max(this.timeout * 2, 120_000)}ms) — connection wedged`, this.provider);
+                }
+                // User pressed ESC / Stop, or the run's AbortSignal fired. The SDK
+                // throws APIUserAbortError (no HTTP status, so isClientError below
+                // can't catch it). Retrying re-issues the same aborted request 3×
+                // with growing backoff — ~40 s of dead time ending in llm.exhausted,
+                // for work the user explicitly cancelled. Surface immediately.
+                // Also catch the case where the run aborted but the underlying error
+                // surfaced as a generic Connection error (not an SDK abort): the
+                // signal is the authoritative "user cancelled" source.
+                if (isAbortError(err) || signal?.aborted) {
+                    logger.warn("llm.abort_no_retry", {
+                        cat: "llm",
+                        provider: this.provider,
+                        model: this.model,
+                        error: err.message,
+                    });
+                    throw err;
+                }
                 if (err instanceof LLMRateLimitError) {
                     const waitMs = (err.retryAfter ?? attempt * 2) * 1000;
                     logger.warn("llm.retry", {
@@ -72,7 +177,9 @@ export class LLMClientBase {
                         reason: "rate_limit",
                         waitMs,
                     });
-                    await new Promise((r) => setTimeout(r, waitMs));
+                    if (await abortableSleep(waitMs, signal)) {
+                        throw new DOMException("Request cancelled during retry backoff", "AbortError");
+                    }
                     continue;
                 }
                 // 4xx (except 429, handled above as LLMRateLimitError) is a
@@ -111,27 +218,80 @@ export class LLMClientBase {
                     error: err.message,
                     backoffMs: backoff,
                 });
-                await new Promise((r) => setTimeout(r, backoff));
+                if (await abortableSleep(backoff, signal)) {
+                    throw new DOMException("Request cancelled during retry backoff", "AbortError");
+                }
             }
         }
         throw lastError ?? new LLMError("Unknown LLM error");
     }
 }
+/**
+ * Sleep `ms`, but wake immediately if `signal` aborts. Returns true when it
+ * woke due to an abort (caller should bail), false on a normal timeout.
+ * Without this an abort during a retry backoff is invisible until the timer
+ * fires — the root cause of "Stop does nothing" during a flaky-connection
+ * retry loop.
+ */
+function abortableSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(false);
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /**
  * Detect HTTP 4xx errors from provider SDKs so withRetry can bail
- * without burning backoff time. OpenAI/Anthropic SDKs both attach a
- * numeric `status` to their error objects; we treat 400-499 as
- * non-retryable (429 is handled separately above as a rate-limit).
+ * without burning backoff time. OpenAI/Anthropic SDKs attach a numeric
+ * `status` to their error objects; we treat 400-499 as non-retryable
+ * (429 is handled separately above as a rate-limit).
+ *
+ * The provider clients also wrap SDK errors into `new LLMError(msg,
+ * provider, { status })`, where the status lands in
+ * `FrameworkError.details.status` rather than a top-level `.status`.
+ * We read both so a wrapped 400/401/404 isn't retried 3× (~9 s wasted)
+ * before finally surfacing.
  *
  * Network errors and 5xx fall through and remain retryable.
+ *
+ * Exported for unit testing.
  */
-function isClientError(err) {
+export function isClientError(err) {
     if (typeof err !== "object" || err === null)
         return false;
-    const status = err.status;
+    const top = err.status;
+    const buried = err.details?.status;
+    const status = typeof top === "number" ? top : typeof buried === "number" ? buried : undefined;
     if (typeof status !== "number")
         return false;
     if (status === 429)
         return false;
     return status >= 400 && status < 500;
 }
+/**
+ * Detect a user/run cancellation. The OpenAI and Anthropic SDKs throw
+ * `APIUserAbortError` when a request's AbortSignal fires mid-flight; the
+ * providers rethrow it unchanged (see handleApiError). It carries no HTTP
+ * `status`, so `isClientError` can't recognise it — without an explicit
+ * check it falls through to `withRetry`'s generic branch and gets retried.
+ *
+ * We match by error name rather than `instanceof` to avoid importing the
+ * provider SDKs into the base class: `APIUserAbortError` from the SDKs, and
+ * the WHATWG `AbortError` from `fetch`/AbortController, both surface here.
+ *
+ * Exported for unit testing.
+ */
+export function isAbortError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const name = err.name;
+    return name === "APIUserAbortError" || name === "AbortError";
+}

package/dist/llm/client-factory.d.ts

@@ -1,10 +1,10 @@
 /**
  * LLM provider factory with registry pattern.
  */
-import type { LLMConfig } from "../types.js";
+import type { ClientDefaults, LLMConfig } from "../types.js";
 import type { LLMClientBase } from "./client-base.js";
-type ProviderConstructor = new (config: LLMConfig) => LLMClientBase;
+type ProviderConstructor = new (config: LLMConfig, defaults?: ClientDefaults) => LLMClientBase;
 declare const PROVIDER_REGISTRY: Map<string, ProviderConstructor>;
 export declare function registerProvider(name: string, cls: ProviderConstructor): void;
-export declare function createLLMClient(config: LLMConfig): Promise<LLMClientBase>;
+export declare function createLLMClient(config: LLMConfig, defaults?: ClientDefaults): Promise<LLMClientBase>;
 export { PROVIDER_REGISTRY };

package/dist/llm/client-factory.js

@@ -6,7 +6,7 @@ const PROVIDER_REGISTRY = new Map();
 export function registerProvider(name, cls) {
     PROVIDER_REGISTRY.set(name, cls);
 }
-export async function createLLMClient(config) {
+export async function createLLMClient(config, defaults) {
     let Cls = PROVIDER_REGISTRY.get(config.provider);
     if (!Cls) {
         // Auto-register built-in providers on first use
@@ -24,6 +24,6 @@ export async function createLLMClient(config) {
     if (!Cls) {
         throw new LLMError(`Unknown LLM provider: ${config.provider}. Available: ${[...PROVIDER_REGISTRY.keys()].join(", ")}`);
     }
-    return new Cls(config);
+    return new Cls(config, defaults);
 }
 export { PROVIDER_REGISTRY };

package/dist/llm/model-cache.js

@@ -6,8 +6,8 @@
  * reads, isStale just checks. Malformed/missing files yield undefined.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHome } from "../settings/manager.js";
 const TTL_MS = 7 * 24 * 3600 * 1000;
 export function readCache(cacheDir, providerKey) {
     const path = join(cacheDir, `${providerKey}.json`);
@@ -42,5 +42,7 @@ export function isStale(file, now = Date.now()) {
     return now - ts > TTL_MS;
 }
 export function defaultCacheDir() {
-    return join(homedir(), ".code-shell", "cache", "models");
+    // userHome() (not raw homedir(), which bun caches at process start) so a
+    // relocated/test HOME redirects the cache dir instead of writing real ~/.code-shell.
+    return join(userHome(), ".code-shell", "cache", "models");
 }

package/dist/llm/model-pool.d.ts

@@ -23,19 +23,32 @@ export interface ModelEntry {
     model: string;
     baseUrl?: string;
     apiKey?: string;
+    /** Whether the catalog template requires a key (default true; false = local/
+     *  no-auth provider). Used by resolveLLMConfigForTag to reject a key-needing
+     *  connection that has no resolved key with a clear error rather than a 401. */
+    needsKey?: boolean;
     maxOutputTokens?: number;
     /** Per-model context window size. Falls back to config.maxContextTokens → 200_000. */
     maxContextTokens?: number;
     /** Optional reference into ProviderCatalog. When set, baseUrl/apiKey
      *  come from the catalog unless the entry overrides them. */
     providerKey?: string;
+    /** Per-model external token command; overrides provider-level (TODO 7.2). */
+    authCommand?: string;
+    /** Per-model extra HTTP headers; merged over provider-level (TODO 7.2). */
+    httpHeaders?: Record<string, string>;
+    /** OpenAI `service_tier` request param (TODO 7.2). */
+    serviceTier?: string;
+    /** OpenAI reasoning `summary` control (TODO 7.2). */
+    reasoningSummary?: string;
     /**
-     * Per-model thinking override. Wins over the provider-level setting
-     * (ProviderCatalog entry's `thinking`). Useful when models in the same
-     * provider need different defaults — e.g. DeepSeek V4 Pro off but
-     * V4 Flash on.
+     * Per-model reasoning override. Wins over the provider-level setting
+     * (ProviderCatalog entry's `reasoning`). Useful when models in the same
+     * provider need different defaults — e.g. one model off but another on.
      */
-    thinking?: "enabled" | "disabled";
+    reasoning?: import("./reasoning-setting.js").ReasoningSetting;
+    /** Catalog-driven extra request-body fields (wire-mapped paramValues). */
+    extraBody?: Record<string, unknown>;
 }
 export declare class ModelPool {
     private models;
@@ -83,13 +96,18 @@ export declare class ModelPool {
     /** Check if a key exists. */
     has(key: string): boolean;
     /**
-     * Build an LLMConfig for a given model entry, merging with a base config
-     * (inherits apiKey, baseUrl, etc. from the base if not set on the entry).
+     * Build an LLMConfig (pure model identity) for the given entry. Cross-model
+     * runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail) are NOT
+     * part of LLMConfig — they live on the Engine as ClientDefaults and are
+     * threaded into the LLMClient independently. That separation lets hot-
+     * switching the model replace this object wholesale without touching the
+     * user's runtime preferences (and without leaking the old model's settings
+     * onto a model that doesn't share them — e.g. 384k-output deepseek bleeding
+     * into 128k-cap gpt-5.5).
      */
-    toLLMConfig(entry: ModelEntry, base?: Partial<LLMConfig>): LLMConfig;
+    toLLMConfig(entry: ModelEntry): LLMConfig;
     /**
-     * Build an LLMConfig for the active model (or a specific key),
-     * merging with a base config.
+     * Build an LLMConfig for the active model (or a specific key).
      */
-    resolveLLMConfig(key?: string, base?: Partial<LLMConfig>): LLMConfig | undefined;
+    resolveLLMConfig(key?: string): LLMConfig | undefined;
 }

package/dist/llm/model-pool.js

@@ -193,10 +193,16 @@ export class ModelPool {
         return this.models.has(key);
     }
     /**
-     * Build an LLMConfig for a given model entry, merging with a base config
-     * (inherits apiKey, baseUrl, etc. from the base if not set on the entry).
+     * Build an LLMConfig (pure model identity) for the given entry. Cross-model
+     * runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail) are NOT
+     * part of LLMConfig — they live on the Engine as ClientDefaults and are
+     * threaded into the LLMClient independently. That separation lets hot-
+     * switching the model replace this object wholesale without touching the
+     * user's runtime preferences (and without leaking the old model's settings
+     * onto a model that doesn't share them — e.g. 384k-output deepseek bleeding
+     * into 128k-cap gpt-5.5).
      */
-    toLLMConfig(entry, base) {
+    toLLMConfig(entry) {
         const fromCat = entry.providerKey && this.providerCatalog
             ? this.providerCatalog.get(entry.providerKey)
             : undefined;
@@ -215,32 +221,42 @@ export class ModelPool {
                 kindToClientProvider(fromCat?.kind) ||
                 "openai",
             model: entry.model,
-            apiKey: entry.apiKey ?? fromCat?.apiKey ?? base?.apiKey,
-            baseUrl: entry.baseUrl ?? fromCat?.baseUrl ?? base?.baseUrl,
-            temperature: base?.temperature ?? 0.3,
-            maxTokens: entry.maxOutputTokens ?? base?.maxTokens ?? 8192,
-            enableStreaming: base?.enableStreaming ?? true,
-            // thinking precedence: model entry > provider catalog > base.
-            // Model-level wins so users can hold one default for "deepseek"
-            // and still override a single model (e.g. v4-pro off).
-            ...(entry.thinking || fromCat?.thinking || base?.thinking
-                ? { thinking: entry.thinking ?? fromCat?.thinking ?? base?.thinking }
+            apiKey: entry.apiKey ?? fromCat?.apiKey,
+            baseUrl: entry.baseUrl ?? fromCat?.baseUrl,
+            // No invented default: undefined lets each client apply its own fallback
+            // (OpenAI omits the token field entirely; Anthropic uses its own constant)
+            // instead of fabricating 8192, which silently truncates long outputs and
+            // masks the real per-model cap.
+            maxTokens: entry.maxOutputTokens,
+            // reasoning: entry overrides catalog. No base fallback — see class doc.
+            ...(entry.reasoning ?? fromCat?.reasoning
+                ? { reasoning: entry.reasoning ?? fromCat?.reasoning }
                 : {}),
+            // Auth command: entry overrides catalog. (TODO 7.2)
+            ...(entry.authCommand ?? fromCat?.authCommand
+                ? { authCommand: entry.authCommand ?? fromCat?.authCommand }
+                : {}),
+            // HTTP headers: merge catalog (base) then entry (override). (TODO 7.2)
+            ...(fromCat?.httpHeaders || entry.httpHeaders
+                ? { httpHeaders: { ...fromCat?.httpHeaders, ...entry.httpHeaders } }
+                : {}),
+            ...(entry.serviceTier ? { serviceTier: entry.serviceTier } : {}),
+            ...(entry.reasoningSummary ? { reasoningSummary: entry.reasoningSummary } : {}),
             // Carry the catalog kind through so the capability layer can pick
-            // per-(kind, model) request-shape rules. Defaults below cover the
-            // unusual case where an entry has a provider but no providerKey
-            // (legacy / arena-injected models).
+            // per-(kind, model) request-shape rules.
             ...(fromCat?.kind ? { providerKind: fromCat.kind } : {}),
+            ...(entry.extraBody && Object.keys(entry.extraBody).length > 0
+                ? { extraBody: entry.extraBody }
+                : {}),
         };
     }
     /**
-     * Build an LLMConfig for the active model (or a specific key),
-     * merging with a base config.
+     * Build an LLMConfig for the active model (or a specific key).
      */
-    resolveLLMConfig(key, base) {
+    resolveLLMConfig(key) {
         const entry = this.get(key);
         if (!entry)
             return undefined;
-        return this.toLLMConfig(entry, base);
+        return this.toLLMConfig(entry);
     }
 }

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

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+/** Resolve `$ENV` / `${ENV}` placeholders in a header value against `env`. */
+export declare function resolveHeaderValue(value: string, env?: NodeJS.ProcessEnv): string;
+/** Resolve every header value's env placeholders, dropping empties. */
+export declare function resolveHeaders(headers: Record<string, string> | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
+type RunCommand = (cmd: string) => string;
+/**
+ * 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 declare function resolveAuthCommand(command: string, opts?: {
+    runCommand?: RunCommand;
+    now?: number;
+}): string;
+/** Test seam: clear the token cache. */
+export declare function __clearAuthTokenCache(): void;
+/**
+ * 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 declare function resolveApiKey(config: {
+    apiKey?: string;
+    authCommand?: string;
+}, envKey?: string, opts?: {
+    runCommand?: RunCommand;
+    now?: number;
+}): string | undefined;
+export {};

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,10 +11,14 @@ 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 DeepSeek V4 thinking-mode for this provider. See LLMConfig. */
-    thinking?: "enabled" | "disabled";
+    /** Default reasoning/thinking setting for this provider. See LLMConfig. */
+    reasoning?: import("./reasoning-setting.js").ReasoningSetting;
 }
 export declare class ProviderCatalog {
     private byKey;