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

package/dist/index.js

@@ -3,11 +3,15 @@
  *
  * 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 } from "./engine/engine.js";
+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";
 export { ChatSessionManager } from "./protocol/chat-session-manager.js";
 // ─── LLM ─────────────────────────────────────────────────────────
@@ -16,12 +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 { MCPManager } from "./tool-system/mcp-manager.js";
+export { makeUpdateAutomationMemoryTool } from "./tool-system/builtin/update-automation-memory.js";
+export { MCPManager, buildHttpHeaders, buildStdioEnv } from "./tool-system/mcp-manager.js";
 // ─── Hooks ───────────────────────────────────────────────────────
 export { HookRegistry } from "./hooks/registry.js";
 export { wrapHookMessages } from "./hooks/inject.js";
@@ -29,6 +35,7 @@ export { wrapHookMessages } from "./hooks/inject.js";
 export { AgentServer } from "./protocol/server.js";
 export { AgentClient } from "./protocol/client.js";
 export { createInProcessTransport, StdioTransport, } from "./protocol/transport.js";
+export { SocketTransport, listenTcp, } from "./protocol/tcp-transport.js";
 // Recommended public factories — see protocol/factories.ts for the
 // stable construction contract referenced by standard §7.
 export { createServer, createClient, } from "./protocol/factories.js";
@@ -37,7 +44,10 @@ 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 ──────────────────────────────────────────────────────
 export { PromptComposer } from "./prompt/composer.js";
 export { SectionCache } from "./prompt/section-cache.js";
@@ -51,6 +61,26 @@ export { estimateTokens, microcompact, windowCompact, truncateToolResult, buildS
 export { applyToolResultPersistence, createContentReplacementState, reconstructContentReplacementState, resolveToolResultsDir, isPersistedReplacement, DEFAULT_PERSIST_THRESHOLD, PER_MESSAGE_AGGREGATE_CAP, PREVIEW_SIZE, } from "./context/tool-result-storage.js";
 // ─── Skills ──────────────────────────────────────────────────────
 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";
@@ -75,7 +105,7 @@ RunManager, FileRunStore,
 // Queue
 RunQueue, 
 // Runner
-EngineRunner, 
+EngineRunner, AUTOMATION_PROMPT_NOTE, AUTOMATION_RUN_SOURCE, 
 // Approval / Input adapters
 RunApprovalBackend, createRunAskUserFn, 
 // Checkpoint & Artifacts
@@ -92,23 +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 ────────────────────────────────────────────────
@@ -120,26 +164,65 @@ 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";
+// Automation — zero-env-dependency scheduling module (startAutomation facade
+// + 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, } 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";
 export { PROVIDER_KINDS, } from "./llm/provider-kinds.js";
 export { capabilitiesFor, } from "./llm/capabilities/index.js";
+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/reasoning-control.d.ts

@@ -0,0 +1,24 @@
+/**
+ * reasoningControlFor — projects a model's ReasoningShape into "what control
+ * the UI should render". The UI never branches on provider; it switches on
+ * ReasoningControl.kind. Mirrors the capability-control descriptor pattern.
+ */
+import type { ProviderKindName } from "../provider-kinds.js";
+import type { ReasoningEffort } from "./types.js";
+export type ReasoningControl = {
+    kind: "none";
+} | {
+    kind: "toggle";
+    default: boolean;
+} | {
+    kind: "effort";
+    options: ReasoningEffort[];
+    default: ReasoningEffort;
+} | {
+    kind: "budget";
+    min: number;
+    default: number;
+} | {
+    kind: "adaptive";
+};
+export declare function reasoningControlFor(kind: ProviderKindName, model: string): ReasoningControl;

package/dist/llm/capabilities/reasoning-control.js

@@ -0,0 +1,38 @@
+import { capabilitiesFor } from "./index.js";
+const FULL_EFFORTS = ["minimal", "low", "medium", "high"];
+export function reasoningControlFor(kind, model) {
+    const cap = capabilitiesFor(kind, model);
+    const r = cap.reasoning;
+    switch (r.kind) {
+        case "none":
+            return { kind: "none" };
+        case "deepseek-thinking":
+            return { kind: "toggle", default: true };
+        case "anthropic-adaptive":
+            return { kind: "adaptive" };
+        case "anthropic-budget":
+            return {
+                kind: "budget",
+                min: r.minBudgetTokens,
+                default: Math.max(r.minBudgetTokens, 4096),
+            };
+        case "openrouter-reasoning":
+            // OpenRouter normalizes to minimal..high (no xhigh passthrough).
+            return { kind: "effort", options: FULL_EFFORTS, default: "medium" };
+        case "openai-effort": {
+            // Prefer the capability's first-class supportedEfforts list (gpt-5.5 →
+            // low..xhigh, magistral → [high]). Fall back to the default four levels
+            // when a rule didn't specify one. We no longer infer the level set from
+            // disabledEffort — that's a wire-detail two vendors can coincidentally
+            // share (gpt-5.5 and magistral both use "none"), so inferring misrendered
+            // magistral as a gpt-5.5-style control.
+            const options = r.supportedEfforts && r.supportedEfforts.length > 0
+                ? r.supportedEfforts
+                : FULL_EFFORTS;
+            // Default to "medium" if available, else the first offered level
+            // (magistral has only "high", so its default is "high").
+            const def = options.includes("medium") ? "medium" : options[0];
+            return { kind: "effort", options, default: def };
+        }
+    }
+}

package/dist/llm/capabilities/rules.js

@@ -39,10 +39,22 @@ export const RULES = [
                 "temperature", "top_p", "presence_penalty",
                 "frequency_penalty", "logit_bias", "logprobs", "top_logprobs",
             ]),
-            reasoning: { kind: "openai-effort", disabledEffort: "none" },
+            reasoning: {
+                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
+            // stale 384000 (copied from a DeepSeek/OpenRouter entry on a prior model)
+            // can't bleed in after a hot switch.
+            maxOutputTokens: 128_000,
         },
-        why: "OpenAI gpt-5.5+ accepts reasoning_effort none|low|medium|high|xhigh (no `minimal`).",
+        why: "OpenAI gpt-5.5+ accepts reasoning_effort none|low|medium|high|xhigh (no `minimal`); output cap 128k.",
     },
     // ─── OpenAI native — o-series + gpt-5 through gpt-5.4 ──────────
     {
@@ -63,6 +75,24 @@ export const RULES = [
         },
         why: "OpenAI o-series + gpt-5..5.4 reject classic sampling params; use max_completion_tokens + reasoning_effort.",
     },
+    // ─── OpenAI native — gpt-4o / gpt-4-turbo (multimodal, non-reasoning) ──
+    // The famous vision models. They are NOT reasoning models, so they keep
+    // classic sampling params + max_tokens — only `supportsVision` differs
+    // from DEFAULT_CAPABILITY. Listed AFTER the gpt-5+ rules (those anchor on
+    // gpt-[5-9]) so neither family masks the other. Without this rule gpt-4o
+    // falls through to DEFAULT_CAPABILITY (supportsVision:false) and a famous
+    // vision model gets its history images stripped / new attachments rejected.
+    {
+        kind: "openai",
+        // gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4-vision-preview, gpt-4.1*.
+        // gpt-4o has no separator before the "o"; the rest are `-`/`.`-separated.
+        // Stays clear of gpt-3.5-turbo (no vision) and gpt-5+ (handled above).
+        match: /^gpt-4o(?:[-.]|$)|^gpt-4(?:\.1|-turbo|-vision)(?:[-.]|$)/i,
+        capability: {
+            supportsVision: true,
+        },
+        why: "OpenAI gpt-4o / gpt-4o-mini / gpt-4-turbo / gpt-4.1 are multimodal but non-reasoning; only vision differs from default.",
+    },
     // ─── DeepSeek ──────────────────────────────────────────────────
     {
         kind: "deepseek",
@@ -196,7 +226,11 @@ export const RULES = [
         // Magistral series exposes reasoning_effort: high|none — no minimal/low/medium.
         match: /^magistral/i,
         capability: {
-            reasoning: { kind: "openai-effort", disabledEffort: "none" },
+            reasoning: {
+                kind: "openai-effort",
+                disabledEffort: "none",
+                supportedEfforts: ["high"], // magistral: only high|none — "none" is the off value
+            },
         },
         why: "Mistral magistral models accept only reasoning_effort `high` or `none`.",
     },

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

@@ -9,8 +9,11 @@
  * `rules.ts` — vendor docs, not folklore.
  */
 import type { ProviderKindName } from "../provider-kinds.js";
-/** OpenAI-style reasoning effort levels — shared by several vendors. */
-export type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+/**
+ * OpenAI-style reasoning effort levels — shared by several vendors.
+ * `xhigh` is gpt-5.5+ only (which also drops `minimal`); see rules.ts.
+ */
+export type ReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
 /** A binary thinking switch, like DeepSeek V4 and Z.AI GLM use. */
 export type ThinkingSwitch = "enabled" | "disabled";
 /**
@@ -31,10 +34,29 @@ export type ReasoningShape = {
  * "disabled" — defaults to `"minimal"` (OpenAI), but vendors with a
  * narrower vocabulary override it (e.g. xAI Grok 4.3 has no `"minimal"`;
  * Mistral Magistral only accepts `"high"` and `"none"`).
+ *
+ * `supportedEfforts` is the FIRST-CLASS list of levels a UI may offer for
+ * this model. Set it whenever the vocabulary differs from the default
+ * `["minimal","low","medium","high"]` — e.g. gpt-5.5 is
+ * `["low","medium","high","xhigh"]`, Mistral magistral is `["high"]`. The UI
+ * (reasoningControlFor) reads this directly instead of inferring the
+ * level set from `disabledEffort`, which is a wire-detail, not a
+ * capability marker (two unrelated vendors can share `disabledEffort:"none"`).
  */
  | {
     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}}`. */
  | {
@@ -95,6 +117,14 @@ export interface Capability {
     parallelToolCalls: ParallelToolCallsShape;
     /** Streaming usage reporting shape. */
     streamUsage: StreamUsageShape;
+    /**
+     * Known hard ceiling for max-output-tokens, when the vendor publishes one
+     * and exceeding it 400s. Used to clamp a requested/inherited max_tokens so
+     * a stale catalog value (e.g. 384000 copied from a DeepSeek/OpenRouter
+     * entry) can't bleed onto a smaller-cap model after a hot switch. Undefined
+     * = no known cap → send the request value unclamped.
+     */
+    maxOutputTokens?: number;
 }
 /**
  * Conservative default — used when no rule matches. Picks "send everything

package/dist/llm/clamp-max-tokens.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Clamp a requested max-output-tokens value to a model's known output cap.
+ *
+ * Background: model-pool copies a catalog `maxOutputTokens` straight into
+ * LLMConfig.maxTokens. For some OpenRouter/DeepSeek entries that value is huge
+ * (e.g. 384000) and bleeds onto a model with a much smaller cap after a hot
+ * switch, producing `max_tokens is too large` 400s. When the capability layer
+ * knows the model's real ceiling we clamp to it; when it doesn't we pass the
+ * value through (or omit it entirely when there is no request value).
+ */
+export declare function clampMaxTokens(requested: number | undefined, cap: number | undefined): number | undefined;

package/dist/llm/clamp-max-tokens.js

@@ -0,0 +1,17 @@
+/**
+ * Clamp a requested max-output-tokens value to a model's known output cap.
+ *
+ * Background: model-pool copies a catalog `maxOutputTokens` straight into
+ * LLMConfig.maxTokens. For some OpenRouter/DeepSeek entries that value is huge
+ * (e.g. 384000) and bleeds onto a model with a much smaller cap after a hot
+ * switch, producing `max_tokens is too large` 400s. When the capability layer
+ * knows the model's real ceiling we clamp to it; when it doesn't we pass the
+ * value through (or omit it entirely when there is no request value).
+ */
+export function clampMaxTokens(requested, cap) {
+    if (requested === undefined)
+        return undefined;
+    if (cap === undefined)
+        return requested;
+    return Math.min(requested, cap);
+}

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

@@ -1,17 +1,17 @@
 /**
  * Abstract base class for all LLM provider clients.
  */
-import type { LLMConfig, LLMResponse, TokenUsage } from "../types.js";
+import type { ClientDefaults, LLMConfig, LLMResponse, TokenUsage } from "../types.js";
 import type { CreateMessageOptions, LLMUsageTracker } from "./types.js";
 export declare abstract class LLMClientBase {
     protected readonly config: LLMConfig;
     readonly provider: string;
     readonly model: string;
+    readonly maxTokens: number | undefined;
     readonly temperature: number;
-    readonly maxTokens: number;
     readonly timeout: number;
     readonly retryMaxAttempts: number;
-    readonly enableStreaming: boolean;
+    readonly imageDetail?: ClientDefaults["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
@@ -20,10 +20,74 @@ export declare abstract class LLMClientBase {
      */
     static onUsage?: (model: string, usage: TokenUsage) => void;
     protected usage: LLMUsageTracker;
-    constructor(config: LLMConfig);
+    /**
+     * `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: LLMConfig, defaults?: ClientDefaults);
     protected abstract initClient(): void;
     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
+ * 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.
+ */
+export declare function isClientError(err: unknown): boolean;
+/**
+ * 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 declare function isAbortError(err: unknown): boolean;