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

package/dist/index.js

@@ -3,11 +3,13 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.5.0-rc.0";
+export const VERSION = "0.5.0-rc.2";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Engine (primary API) ────────────────────────────────────────
 export { Engine, loadAgentDefinitionsForCwd } from "./engine/engine.js";
+export { resolveLLMConfigForTag } from "./engine/resolve-llm-config.js";
+export { resolveAuxKey } from "./engine/aux-key.js";
 export { parseAgentDefinition, serializeAgentDefinition, } from "./agent/agent-definition.js";
 export { AgentDefinitionRegistry, } from "./agent/agent-definition-registry.js";
 export { EngineRuntime } from "./engine/runtime.js";
@@ -18,13 +20,14 @@ export { createLLMClient, registerProvider } from "./llm/client-factory.js";
 export { AnthropicClient } from "./llm/providers/anthropic.js";
 export { OpenAIClient } from "./llm/providers/openai.js";
 export { ModelPool } from "./llm/model-pool.js";
+export { modelEntriesFromConnections } from "./engine/model-connections-pool.js";
 // ─── Tools ───────────────────────────────────────────────────────
 export { ToolRegistry } from "./tool-system/registry.js";
 export { ToolExecutor } from "./tool-system/executor.js";
 export { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend } from "./tool-system/permission.js";
 export { BUILTIN_TOOLS } from "./tool-system/builtin/index.js";
 export { makeUpdateAutomationMemoryTool } from "./tool-system/builtin/update-automation-memory.js";
-export { MCPManager } from "./tool-system/mcp-manager.js";
+export { MCPManager, buildHttpHeaders, buildStdioEnv } from "./tool-system/mcp-manager.js";
 // ─── Hooks ───────────────────────────────────────────────────────
 export { HookRegistry } from "./hooks/registry.js";
 export { wrapHookMessages } from "./hooks/inject.js";
@@ -41,6 +44,8 @@ export { Methods, ErrorCodes, } from "./protocol/types.js";
 export { Transcript } from "./session/transcript.js";
 export { SessionManager } from "./session/session-manager.js";
 export { FileHistory } from "./session/file-history.js";
+export { latestUndoTarget, earliestSnapshotsPerFile, latestTurnUndoTargets, latestRedoTargets, } from "./session/undo-target.js";
+export { diffLines, renderDiffPreview } from "./session/simple-diff.js";
 export { MemoryManager } from "./session/memory.js";
 export { runDreamConsolidation, } from "./services/dream-consolidation.js";
 // ─── Prompt ──────────────────────────────────────────────────────
@@ -59,18 +64,23 @@ export { scanSkills, invalidateSkillCache } from "./skills/index.js";
 // ─── Capability control (扩展能力 backend) ───────────────────────
 export { CapabilityService, CapabilityNotFoundError, projectBuiltin, projectMcp, projectSkills, projectPlugins, } from "./capability-control/index.js";
 export { readInstalledPlugins } from "./plugins/installedPlugins.js";
+export { computeEffectiveDisabledLists, } from "./capability-control/disabled-lists.js";
 // ─── Plugin installer (CC + Codex) ───────────────────────────────
 export { installPluginFromPath } from "./plugins/installer/install.js";
 export { installPluginFromSource } from "./plugins/installer/installFromSource.js";
+export { installLocalPlugin, installPluginFromArchive, } from "./plugins/installer/installFromArchive.js";
 export { parseSource } from "./plugins/installer/parseSource.js";
 export { detectPluginFormat } from "./plugins/installer/detectFormat.js";
 export { CodexPluginManifest, CSMeta, PluginInstallError, } from "./plugins/installer/types.js";
 export { mergePluginMcpServers } from "./plugins/installer/loadPluginMcp.js";
+export { listPluginHooks, pluginHookKey } from "./plugins/loadPluginHooks.js";
+export { describePluginContent } from "./plugins/pluginContent.js";
 export { pluginAgentDirs } from "./plugins/installer/loadPluginAgents.js";
 export { appendInstallEntry, pluginInstallKey, removeInstallEntries, } from "./plugins/installedPlugins.js";
 export { uninstallPluginByName } from "./plugins/installer/uninstall.js";
 export { listInstalledPlugins } from "./plugins/installer/list.js";
 export { updatePluginByName } from "./plugins/installer/update.js";
+export { checkPluginUpdate } from "./plugins/installer/checkUpdate.js";
 // ─── Arena ───────────────────────────────────────────────────────
 export { Arena } from "./arena/arena.js";
 export { MODEL_PRESETS, getMaxOutputTokens } from "./arena/model-presets.js";
@@ -112,24 +122,37 @@ export { defineProduct, } from "./product/index.js";
 export { logger } from "./logging/logger.js";
 // ─── Settings ────────────────────────────────────────────────────
 export { SettingsManager } from "./settings/manager.js";
+export { migrateConfig, configVersionOf, CURRENT_CONFIG_VERSION, } from "./settings/migrate-config.js";
 export { SettingsSchema, validateSettings } from "./settings/schema.js";
+export { settingsJsonSchema, writeSettingsSchemaFile } from "./settings/schema-export.js";
 export { personalizationFrom } from "./settings/personalization.js";
+export { CredentialStore, formatNetscapeCookies, parseCookieJar, useCredentialToolDef, useCredentialToolDefFor, sweepStaleCredentialCookies, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./credentials/index.js";
 // ─── State (runtime singletons shared with TUI) ──────────────────
+/** @internal Shared with the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { getSessionId, switchSession, getOriginalCwd, setOriginalCwd, getProjectRoot, setProjectRoot, getCwdState, getIsInteractive, updateLastInteractionTime, flushInteractionTime, markScrollActivity, } from "./state.js";
 // ─── Utils (shared primitives used by TUI) ───────────────────────
+/** @internal Shared primitives for the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, getRelativeTimeFormat, getTimeZone, getSystemLocaleLanguage, } from "./utils/intl.js";
 export { env } from "./utils/env.js";
 export { default as sliceAnsi } from "./utils/sliceAnsi.js";
 export { execFileNoThrow } from "./utils/execFileNoThrow.js";
+export { findExecutable, resolveExecutable, setGitPathOverride, resolveGit, isGitAvailable, } from "./utils/exec.js";
 export { gte } from "./utils/semver.js";
+// Cross-process file lock (proper-lockfile via createRequire, ESM-safe). Used by
+// RunLock / CronStore internally; exported so other writers of shared files
+// (e.g. desktop settings-service writing the same settings.json as the worker)
+// can take the same advisory lock.
+export { lock, lockSync, unlock, check } from "./utils/lockfile.js";
 export { logForDebugging } from "./utils/debug.js";
-export { isEnvTruthy, isEnvDefinedFalsy, getClaudeConfigHomeDir, isBareMode, parseEnvVars, shouldMaintainProjectWorkingDir, isRunningOnHomespace, getAWSRegion, getDefaultVertexRegion, getVertexRegionForModel, isInProtectedNamespace, } from "./utils/envUtils.js";
+export { isEnvTruthy, isEnvDefinedFalsy, getClaudeConfigHomeDir, isBareMode, parseEnvVars, shouldMaintainProjectWorkingDir, getAWSRegion, getDefaultVertexRegion, getVertexRegionForModel, } from "./utils/envUtils.js";
 export { startCapturingEarlyInput, stopCapturingEarlyInput, consumeEarlyInput, hasEarlyInput, seedEarlyInput, isCapturingEarlyInput, } from "./utils/earlyInput.js";
 export { formatBytes, formatToolArgs, singleLine, MAX_LINE_WIDTH, TOOL_DOT_COLORS, } from "./utils/toolDisplay.js";
+export { classifyBashLines, } from "./tool-system/builtin/bash-output-style.js";
 export { formatDuration, formatTokens } from "./utils/format.js";
 export { getTheme, } from "./utils/theme.js";
 export { resolveThemeSetting } from "./utils/systemTheme.js";
 // ─── Logging (extended) ──────────────────────────────────────────
+/** @internal Host-lifecycle logging hooks for the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { rotateLogs } from "./logging/logger.js";
 export { recordUIEvent } from "./logging/session-recorder.js";
 // ─── Cost Tracker ────────────────────────────────────────────────
@@ -141,7 +164,15 @@ export { hasApiKey, resolveApiKey, appendOnboardingResult, detectEnvKeys, saveAr
 export { getCurrentVersion, checkForUpdate, scheduleAutoInstallOnExit, getUpdateAvailable, getAutoUpdateDisabledReason, } from "./updater.js";
 // ─── Git Utilities ───────────────────────────────────────────────
 export { isGitRepo, getCurrentBranch, getGitStatus, getGitDiff, getGitDiffStat, getGitLog, gitAdd, gitCommit, gitListBranches, gitCheckout, ghAvailable, ghPrComments, } from "./git/utils.js";
+// ─── Code review (TODO 7.3) ─────────────────────────────────────
+export { buildReviewPrompt, parseDimensions, ALL_DIMENSIONS, } from "./review/review-prompt.js";
 // ─── Tool-system (extended for TUI) ─────────────────────────────
+/**
+ * @internal Exports below are consumed by the in-repo TUI/desktop hosts, not
+ * part of the stable `@cjhyy/code-shell-core` SDK surface. They may change or
+ * move to a `/tui` subpath without a major bump. External SDK users: prefer the
+ * primary Engine/Protocol API above.
+ */
 export { getInteractiveApprovalBackend } from "./tool-system/permission.js";
 export { defaultSandboxConfig, } from "./tool-system/sandbox/index.js";
 export { buildNotificationMessage, buildNotificationSummary, notificationQueue, agentNotificationBus, notificationItemToStreamEvent, } from "./tool-system/builtin/agent-notifications.js";
@@ -149,18 +180,32 @@ export { buildNotificationMessage, buildNotificationSummary, notificationQueue,
 // + scheduler/store/runner). Hosts (Electron main, future CLI server) load
 // this and inject store + runner. See docs/automation-plan-2026-05-31.md.
 export { startAutomation, CronScheduler, cronScheduler, CronStore, defaultCronStorePath, bindCronToEngine, bindCronToRunManager, isCronExpression, parseCronExpression, nextCronTime, resolveWritePolicy, wrapUntrustedInput, runWriteJobInWorktree, } from "./automation/index.js";
+// CC orchestrator (external claude-cli rooms + CC-aware scheduling).
+export * from "./cc-orchestrator/index.js";
+// Quota — remaining CC/Codex subscription usage (self-contained, plugin-liftable).
+export { checkQuota, formatQuota } from "./quota/index.js";
+export { resolveQuotaCredentials } from "./quota/credentials.js";
 export { asyncAgentRegistry, } from "./tool-system/builtin/agent-registry.js";
+export { backgroundShellManager, BackgroundShellManager, } from "./runtime/background-shell.js";
+export { getImageProvider, DEFAULT_IMAGE_MODEL, } from "./tool-system/builtin/image-providers.js";
+// ─── Speech-to-text (voice input / 听写) ────────────────────────
+export { transcribe, } from "./stt/transcribe.js";
+export { resolveTranscribeProvider, isTranscribeAvailable, describeTranscribe, } from "./stt/resolve-transcribe.js";
+export { BUILTIN_CATALOG, getMergedCatalog, loadUserCatalog, userCatalogPath, findCatalogEntry, saveCatalogEntry, deleteUserCatalogEntry, catalogEntryOrigins, } from "./model-catalog/index.js";
 // ─── Protocol (extended for TUI) ────────────────────────────────
+/** @internal Extended protocol surface for the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { createInProcessClient } from "./protocol/helpers.js";
 // ─── Arena (extended for TUI) ───────────────────────────────────
+/** @internal Extended Arena surface for the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { formatArenaResult, printArenaResult, renderProgress, createProgressRenderer, } from "./arena/render/terminal.js";
 export { formatArenaResultForSession } from "./arena/render/session.js";
 // ─── Plugins ─────────────────────────────────────────────────────
 export { installPlugin, uninstallPlugin, listInstalled, } from "./plugins/pluginInstaller.js";
-export { addMarketplace, removeMarketplace, listMarketplaces, loadMarketplace, } from "./plugins/marketplaceManager.js";
+export { addMarketplace, refreshMarketplace, removeMarketplace, listMarketplaces, loadMarketplace, } from "./plugins/marketplaceManager.js";
 export { parseMarketplaceInput, deriveMarketplaceName, } from "./plugins/parseMarketplaceInput.js";
 export { scanPluginCommands, } from "./plugins/pluginCommandsLoader.js";
 // ─── LLM (extended for TUI) ─────────────────────────────────────
+/** @internal Extended LLM surface for the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { defaultCacheDir, } from "./llm/model-cache.js";
 export { fetchModelList, } from "./llm/model-fetcher.js";
 export { sanitizeApiKey, hasNonAsciiPrintable, } from "./llm/api-key-sanitize.js";
@@ -170,3 +215,14 @@ export { reasoningControlFor, } from "./llm/capabilities/reasoning-control.js";
 export { REASONING_EFFORTS, } from "./llm/reasoning-setting.js";
 // ─── Data ────────────────────────────────────────────────────────
 export { syncOpenRouterCatalog, getOpenRouterSnapshot, } from "./data/openrouter-sync.js";
+// ─── External agent config (Mobile Web Remote Rooms) ─────────────
+// Resolves the externalAgents settings block (notably claudeCode.trustedWorkspaces),
+// the source of truth for a Room's permission mode. The former /cc & /codex
+// managed-job path was removed — the phone now talks to resident Rooms only.
+export { resolveExternalAgentConfig } from "./external-agents/config.js";
+// ─── Browser automation bridge ───────────────────────────────────
+// Driver-agnostic contract + the pure a11y-tree flattener. The desktop host's
+// browser-driver module implements BrowserBridge on top of webContents.debugger
+// (CDP), reusing flattenAxTree. See the MVP spec
+// docs/superpowers/specs/2026-06-16-browser-automation-mvp.md.
+export { flattenAxTree, renderElementList, cleanPageText, CONTENT_CHAR_CAP, buildExtractLinksScript, EXTRACT_LINK_CAP, } from "./tool-system/browser-bridge.js";

package/dist/llm/capabilities/param-specs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * paramSpecsFromCapability — bridge the capability layer (rules.ts, the vetted
+ * single source of truth) into the unified catalog's ParamSpec[]. The catalog
+ * reuses this knowledge instead of re-hand-writing reasoning/vision per model.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §4.
+ */
+import type { ProviderKindName } from "../provider-kinds.js";
+import type { ParamSpec } from "../../model-catalog/types.js";
+/**
+ * Project a (kind, model)'s capabilities into catalog ParamSpec[]. Currently
+ * covers reasoning (the param that diverges most across models); image
+ * size/quality live in their own catalog entries. Adaptive / none → no spec.
+ */
+export declare function paramSpecsFromCapability(kind: ProviderKindName, model: string): ParamSpec[];

package/dist/llm/capabilities/param-specs.js

@@ -0,0 +1,62 @@
+import { reasoningControlFor } from "./reasoning-control.js";
+/** Where each provider kind's reasoning knob lands on the request body. */
+function reasoningWireField(kind) {
+    switch (kind) {
+        case "anthropic":
+            return "thinking.budget_tokens";
+        case "deepseek":
+        case "zai":
+            return "thinking.type";
+        default:
+            // OpenAI-compat (openai/google/openrouter/xai/mistral/groq) use reasoning_effort.
+            return "reasoning_effort";
+    }
+}
+/**
+ * Project a (kind, model)'s capabilities into catalog ParamSpec[]. Currently
+ * covers reasoning (the param that diverges most across models); image
+ * size/quality live in their own catalog entries. Adaptive / none → no spec.
+ */
+export function paramSpecsFromCapability(kind, model) {
+    const specs = [];
+    const control = reasoningControlFor(kind, model);
+    const wire = { field: reasoningWireField(kind) };
+    switch (control.kind) {
+        case "effort":
+            specs.push({
+                name: "reasoning",
+                label: "思考强度",
+                control: "enum",
+                options: control.options,
+                default: control.default,
+                doc: "Reasoning effort — how hard the model thinks before answering.",
+                wire,
+            });
+            break;
+        case "budget":
+            specs.push({
+                name: "reasoning",
+                label: "思考预算",
+                control: "number",
+                min: control.min,
+                default: control.default,
+                doc: "Thinking token budget — higher = more deliberate reasoning.",
+                wire,
+            });
+            break;
+        case "toggle":
+            specs.push({
+                name: "reasoning",
+                label: "思考",
+                control: "toggle",
+                default: control.default,
+                doc: "Toggle the model's thinking mode on/off.",
+                wire,
+            });
+            break;
+        case "adaptive":
+        case "none":
+            break; // nothing to set
+    }
+    return specs;
+}

package/dist/llm/capabilities/rules.js

@@ -43,6 +43,10 @@ export const RULES = [
                 kind: "openai-effort",
                 disabledEffort: "none",
                 supportedEfforts: ["low", "medium", "high", "xhigh"], // no "minimal"; adds "xhigh"
+                // gpt-5.5 400s when `reasoning_effort` rides alongside `tools` on
+                // /v1/chat/completions — drop the field up-front on tool turns instead
+                // of eating the 400 + 1s-backoff retry on every tool-using turn.
+                noEffortWithTools: true,
             },
             echoReasoning: "optional",
             // 400s on `max_tokens is too large: ... at most 128000`. Clamp here so a

package/dist/llm/capabilities/types.d.ts

@@ -47,6 +47,16 @@ export type ReasoningShape = {
     kind: "openai-effort";
     disabledEffort?: ReasoningEffort | "none";
     supportedEfforts?: ReasoningEffort[];
+    /**
+     * gpt-5.5+ rejects `reasoning_effort` whenever `tools` are also present on
+     * `/v1/chat/completions` ("Function tools with reasoning_effort are not
+     * supported … Please use /v1/responses instead"), 400-ing the request.
+     * When set, the OpenAI client OMITS `reasoning_effort` on any tool-bearing
+     * request up-front — so we never eat the 400 + retry on every tool turn.
+     * The reactive `_dropReasoningEffort` sticky still covers any variant we
+     * haven't tagged here.
+     */
+    noEffortWithTools?: boolean;
 }
 /** Anthropic Claude 4.x ≤ 4.5 — `{thinking: {type: "enabled", budget_tokens: N}}`. */
  | {

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

@@ -31,7 +31,34 @@ export declare abstract class LLMClientBase {
     abstract createMessage(options: CreateMessageOptions): Promise<LLMResponse>;
     protected recordUsage(usage: TokenUsage, options?: CreateMessageOptions): void;
     getUsage(): LLMUsageTracker;
-    protected withRetry<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
+    /** 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(): void;
+    /**
+     * 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.
+     */
+    protected withRequestDeadline(callerSignal?: AbortSignal): {
+        signal: AbortSignal;
+        cleanup: () => void;
+    };
+    protected withRetry<T>(fn: (requestSignal?: AbortSignal) => Promise<T>, opts?: {
+        maxAttempts?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
 }
 /**
  * Detect HTTP 4xx errors from provider SDKs so withRetry can bail

package/dist/llm/client-base.js

@@ -3,6 +3,17 @@
  */
 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;
@@ -19,13 +30,7 @@ export class LLMClientBase {
      * each call site needing to remember.
      */
     static onUsage;
-    usage = {
-        records: [],
-        totalPromptTokens: 0,
-        totalCompletionTokens: 0,
-        totalTokens: 0,
-        requestCount: 0,
-    };
+    usage = emptyUsageTracker();
     /**
      * `config` carries model identity (provider/model/apiKey/baseUrl/maxTokens/
      * thinking/providerKind). `defaults` carries cross-model runtime knobs
@@ -55,29 +60,104 @@ 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.
-                if (isAbortError(err)) {
+                // 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,
@@ -97,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
@@ -136,12 +218,36 @@ 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 attach a numeric

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,18 +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 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.
      */
     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;

package/dist/llm/model-pool.js

@@ -232,9 +232,22 @@ export class ModelPool {
             ...(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.
             ...(fromCat?.kind ? { providerKind: fromCat.kind } : {}),
+            ...(entry.extraBody && Object.keys(entry.extraBody).length > 0
+                ? { extraBody: entry.extraBody }
+                : {}),
         };
     }
     /**

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 {};