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

package/dist/settings/schema.js

@@ -2,7 +2,6 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
-import { ReasoningSettingSchema } from "../llm/reasoning-setting.js";
 /**
  * Tri-state project capability overlay. Lives in PROJECT settings only and
  * layers over the global baseline (disabledSkills / disabledPlugins /
@@ -21,6 +20,14 @@ export const CapabilityOverridesSchema = z
     agents: z.record(CapabilityOverrideSchema).optional(),
     mcp: z.record(CapabilityOverrideSchema).optional(),
     builtin: z.record(CapabilityOverrideSchema).optional(),
+    /**
+     * Per-hook overlay for PLUGIN-provided hooks, keyed by
+     * `pluginHookKey()` (`<plugin>:<RawEvent>:<command>`). Finer-grained
+     * than `plugins` (which kills a whole plugin): "off" suppresses one
+     * hook for this project only. Only "off" is meaningful today — plugin
+     * hooks have no global disable list to force back "on" from.
+     */
+    pluginHooks: z.record(CapabilityOverrideSchema).optional(),
 })
     .optional();
 export const SettingsSchema = z
@@ -43,23 +50,6 @@ export const SettingsSchema = z
             .optional(),
     })
         .default({}),
-    /**
-     * Primary source of truth for the active model is settings.activeKey
-     * (points at models[].key). settings.model is a derived mirror of that
-     * entry kept in sync for legacy boot paths (cli/main.ts, repl.ts, etc.)
-     * which read provider/name/apiKey/baseUrl directly. Writers must update
-     * both — appendOnboardingResult does this in one shot.
-     */
-    activeKey: z.string().optional(),
-    /**
-     * Auxiliary-task model — points at a models[].key. Background, non-user-
-     * facing LLM calls (memory extraction, the auto-dream loop) use this model
-     * instead of the active one, so per-turn book-keeping doesn't burn the
-     * expensive primary model. Pick something fast/cheap (e.g. a Haiku or
-     * DeepSeek key). When unset, those calls fall back to the active model
-     * (legacy behavior). An invalid/missing key also falls back to active.
-     */
-    auxModelKey: z.string().optional(),
     /**
      * Toggle background auto-update. When true (default), code-shell checks
      * npm for newer versions and — if the npm global prefix is writable —
@@ -68,84 +58,115 @@ export const SettingsSchema = z
      * Can also be disabled via env var `DISABLE_AUTOUPDATER=1`.
      */
     autoUpdates: z.boolean().default(true),
-    model: z
+    /**
+     * Image generation is a general capability, decoupled from LLM providers
+     * (TODO 7.1): a vendor may use different keys/endpoints/models for chat vs
+     * image, and image vendors (Gemini, and later 国内 模型) don't fit the LLM
+     * `providers[].kind` enum. `imageGen.providers[]` is the canonical config;
+     * each entry has a user-chosen `id` (selected via GenerateImage's
+     * `provider` arg) and a `kind` that picks the adapter. When `imageGen` is
+     * absent, resolution falls back to scanning LLM `providers[]` for an
+     * image-capable kind — so existing configs keep working with no migration.
+     */
+    imageGen: z
         .object({
-        provider: z.string().default("openai"),
-        name: z.string().default("anthropic/claude-opus-4-6"),
-        apiKey: z.string().optional(),
-        baseUrl: z.string().default("https://openrouter.ai/api/v1"),
-        temperature: z.number().min(0).max(2).default(0.3),
-        maxTokens: z.number().default(8192),
+        defaultProvider: z.string().optional(),
+        providers: z
+            .array(z.object({
+            /** User-chosen instance name; GenerateImage(provider) selects by this. */
+            id: z.string(),
+            /** Adapter selector — e.g. "openai", "google". */
+            kind: z.string(),
+            baseUrl: z.string(),
+            apiKey: z.string().optional(),
+            /** Default model for this instance when the call omits `model`. */
+            defaultModel: z.string().optional(),
+            /** Catalog template this instance was created from (for paramsDoc / displayName回显). */
+            catalogId: z.string().optional(),
+            /** Reuse another instance's key: id of the instance whose apiKey to use (when apiKey is empty). */
+            apiKeyRef: z.string().optional(),
+        }))
+            .default([]),
     })
-        .default({}),
-    providers: z
+        .optional(),
+    /**
+     * Video generation config (TODO 7.1) — same shape as imageGen, decoupled
+     * from LLM providers. `videoGen.providers[]` each carry an `id` (selected
+     * via GenerateVideo's `provider` arg) + a `kind` picking the adapter. With
+     * no real adapters wired yet, this is config-ready: a future getVideoProvider
+     * case lights it up. Falls back to scanning LLM providers[] when absent.
+     */
+    videoGen: z
+        .object({
+        defaultProvider: z.string().optional(),
+        providers: z
+            .array(z.object({
+            id: z.string(),
+            kind: z.string(),
+            baseUrl: z.string(),
+            apiKey: z.string().optional(),
+            defaultModel: z.string().optional(),
+            /** Catalog template this instance was created from (for paramsDoc / displayName回显). */
+            catalogId: z.string().optional(),
+            /** Reuse another instance's key: id of the instance whose apiKey to use (when apiKey is empty). */
+            apiKeyRef: z.string().optional(),
+        }))
+            .default([]),
+    })
+        .optional(),
+    /**
+     * Credentials — independent key entities (统一模型接入方案 §3.3). A key
+     * lives here, not inlined on a connection, so deleting a connection never
+     * loses a key and many connections share one key by referencing the same
+     * credential id (LiteLLM credential_list model).
+     */
+    credentials: z
         .array(z.object({
-        key: z.string(),
-        label: z.string().optional(),
-        kind: z.enum([
-            "openai",
-            "anthropic",
-            "deepseek",
-            "zai",
-            "xai",
-            "mistral",
-            "groq",
-            "google",
-            "openrouter",
-            "ollama",
-            "custom",
-        ]),
-        baseUrl: z.string(),
+        /** User-chosen unique credential name. */
+        id: z.string(),
+        /** Catalog template this credential is for (a key belongs to one provider). */
+        catalogId: z.string(),
         apiKey: z.string().optional(),
-        protocol: z.enum(["openai-compat", "anthropic-style"]).optional(),
-        modelsPath: z.string().optional(),
-        /**
-         * Default reasoning/thinking setting for this provider's models.
-         * Rich shape: {mode:"off"|"on"} | {mode:"effort",effort} |
-         * {mode:"budget",budgetTokens}. Per-model `reasoning` wins.
-         */
-        reasoning: ReasoningSettingSchema.optional(),
+        baseUrl: z.string().optional(),
     }))
         .default([]),
-    models: z
-        .array(z
-        .object({
-        key: z.string(),
-        label: z.string().optional(),
-        providerKey: z.string().optional(),
+    /**
+     * Unified instance layer (统一模型接入方案, see
+     * docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §3.3).
+     * One store for text/image/video connections, each pointing at a catalog
+     * entry (catalogId), a credential (credentialId), its chosen model, and the
+     * param values the user picked. Replaces the legacy split of
+     * providers[]/models[]/imageGen/videoGen.
+     */
+    modelConnections: z
+        .array(z.object({
+        /** User-chosen unique instance name. */
+        id: z.string(),
+        /** Catalog template this instance was created from. */
+        catalogId: z.string(),
+        tag: z.enum(["text", "image", "video", "audio"]),
+        /** Selected modelId (from the entry's modelPresets). */
         model: z.string(),
-        maxOutputTokens: z.number().optional(),
-        maxContextTokens: z.number().optional(),
-        /**
-         * Which LLM client to use ("openai" or "anthropic"). New name —
-         * the legacy field is `provider`, which we still accept and
-         * fold into `protocol` below so old configs keep working.
-         * NOT the brand/vendor — that's providerKey above.
-         */
-        protocol: z.string().optional(),
-        provider: z.string().optional(),
+        /** Per-connection baseUrl override (else the credential's / catalog's). */
         baseUrl: z.string().optional(),
-        apiKey: z.string().optional(),
-        /**
-         * Per-model reasoning override. Wins over the provider-level
-         * `reasoning` setting (settings.providers[].reasoning). Use this
-         * when different models under the same provider need different
-         * defaults — e.g. one model off (faster) and another on.
-         */
-        reasoning: ReasoningSettingSchema.optional(),
-    })
-        .transform((m) => {
-        // Normalize: prefer `protocol`; fall back to legacy `provider`.
-        // We keep `provider` populated as a mirror because engine code
-        // and a few downstream readers still query it directly.
-        const effective = m.protocol ?? m.provider;
-        return {
-            ...m,
-            protocol: effective,
-            provider: effective,
-        };
+        /** Which credential supplies this connection's key. */
+        credentialId: z.string().optional(),
+        /** Values the user picked for the model's params, e.g. { reasoning: "high" }. */
+        paramValues: z.record(z.string(), z.unknown()).optional(),
     }))
         .default([]),
+    /** Default instance id per tag (replaces activeKey / defaultProvider). */
+    defaults: z
+        .object({
+        text: z.string().optional(),
+        image: z.string().optional(),
+        video: z.string().optional(),
+        /** Default speech-to-text (voice input) connection. */
+        audio: z.string().optional(),
+        /** Background-task model (replaces auxModelKey). */
+        auxText: z.string().optional(),
+    })
+        .default({}),
     permissions: z
         .object({
         defaultMode: z
@@ -164,8 +185,27 @@ export const SettingsSchema = z
     context: z
         .object({
         maxTokens: z.number().default(200_000),
-        compactAtRatio: z.number().default(0.6),
-        summarizeAtRatio: z.number().default(0.8),
+        // 压缩阈值（占上下文窗口的比例）。窗口越大可调越高：1M 窗口的模型
+        // 把 compactAtRatio 调到 0.95 能少浪费几十万 token。三档须满足
+        // floor < compact < summarize，否则运行时会 clamp 回安全顺序。
+        compactAtRatio: z
+            .number()
+            .min(0.1)
+            .max(0.98)
+            .default(0.85)
+            .describe("达到该比例开始压缩历史（先试摘要，再退化为窗口裁剪）。默认 0.85。"),
+        summarizeAtRatio: z
+            .number()
+            .min(0.1)
+            .max(0.99)
+            .default(0.92)
+            .describe("紧急阈值：到此比例做最激进的窗口压缩。须 ≥ compactAtRatio。默认 0.92。"),
+        microcompactFloorRatio: z
+            .number()
+            .min(0.1)
+            .max(0.95)
+            .default(0.7)
+            .describe("低于该比例不做 microcompact，保留早期工具输出、保住 prompt cache 前缀。默认 0.7。"),
     })
         .default({}),
     session: z
@@ -174,8 +214,31 @@ export const SettingsSchema = z
         maxHistory: z.number().default(100),
     })
         .default({}),
+    // The record key IS the server name at runtime (MCPManager.connectAll
+    // uses Object.entries keys; desktop's persist strips the `name` field and
+    // keys by it via stripNameFromServer). So `name` here is optional and
+    // backfilled from the key — a config keyed `{"23": {…}}` with no `name`
+    // field is valid, not a crash. The preprocess also tolerates a legacy
+    // array form (`[{name, …}]`) by re-keying it into a name → config record.
     mcpServers: z
-        .record(z.object({
+        .preprocess((value) => {
+        const entries = Array.isArray(value)
+            ? value
+                .filter((v) => !!v && typeof v === "object")
+                .map((v, i) => [String(v.name ?? i), v])
+            : value && typeof value === "object"
+                ? Object.entries(value)
+                : [];
+        return Object.fromEntries(entries.map(([key, raw]) => [
+            key,
+            raw && typeof raw === "object"
+                ? { ...raw, name: raw.name ?? key }
+                : raw,
+        ]));
+    }, z.record(z.object({
+        // Always present here: the preprocess above backfills it from the
+        // record key, so a stored entry that omits `name` (the common
+        // desktop case, which strips it) still validates.
         name: z.string(),
         command: z.string().optional(),
         args: z.array(z.string()).optional(),
@@ -183,10 +246,34 @@ export const SettingsSchema = z
         url: z.string().optional(),
         transport: z.enum(["stdio", "sse", "streamable-http", "inprocess"]).optional(),
         headers: z.record(z.string()).optional(),
+        // Codex-style env-secret handling: store env-var NAMES, read the
+        // secret from process.env at connect time (never plaintext here).
+        envVars: z.array(z.string()).optional(), // (stdio) forward these env vars
+        bearerTokenEnvVar: z.string().optional(), // (HTTP) → Authorization: Bearer <env value>
+        envHeaders: z.record(z.string()).optional(), // (HTTP) header-name → env-var-name
+        credentialRef: z.string().optional(), // (HTTP) id of a stored credential → Bearer, resolved at connect time
         // Codex-style on/off switch. Absent or true → connected; only
         // literal false disables. Filtered in MCPManager.connectAll.
         enabled: z.boolean().optional(),
-    }))
+    })))
+        .default({}),
+    /**
+     * User supplements for PLUGIN-provided MCP servers, keyed by the server's
+     * `<plugin>:<server>` name. Layered onto the plugin config at merge time
+     * (mergePluginMcpServers). Only env/credential fields are accepted —
+     * command/args/url/transport are intentionally absent and `.strict()`
+     * rejects them, so a plugin update is never shadowed by a stale copy.
+     */
+    mcpServerOverrides: z
+        .record(z
+        .object({
+        env: z.record(z.string()).optional(),
+        envVars: z.array(z.string()).optional(),
+        credentialRef: z.string().optional(),
+        bearerTokenEnvVar: z.string().optional(),
+        envHeaders: z.record(z.string()).optional(),
+    })
+        .strict())
         .default({}),
     /**
      * Skill names hidden from the LLM. Names include the full
@@ -216,6 +303,32 @@ export const SettingsSchema = z
      * capability-assembly time. Optional — absence === everything inherits.
      */
     capabilityOverrides: CapabilityOverridesSchema,
+    /**
+     * Feature flags overlay: a map of flag name → boolean that overrides the
+     * compiled-in defaults (see settings/feature-flags.ts FEATURE_FLAGS).
+     * Project settings override user settings via the normal merge, so a flag
+     * can be flipped per-workspace. Unknown flag names are tolerated (kept as
+     * data) for forward-compat; consumers only read known flags via
+     * isFeatureEnabled(). Passthrough record — values coerced to boolean.
+     */
+    featureFlags: z.record(z.string(), z.boolean()).default({}),
+    /**
+     * Cross-session memory knobs. Optional — absence keeps the built-in
+     * defaults (see services/extract-memories.ts). `maxCount` caps memories
+     * accepted per extraction pass; `maxAge`/`extractionModel` are reserved
+     * for the consolidation/extraction pipeline.
+     */
+    memories: z
+        .object({
+        maxCount: z.number().int().positive().optional(),
+        maxAge: z.number().int().positive().optional(),
+        extractionModel: z.string().optional(),
+        /** Master switch for end-of-session automatic memory extraction.
+         *  Absent/true = extract (current behavior); false = skip extraction
+         *  while keeping session summaries and Dream untouched. */
+        autoExtract: z.boolean().optional(),
+    })
+        .optional(),
     instructions: z
         .object({
         fileName: z.string().default("CODESHELL.md"),
@@ -278,19 +391,22 @@ export const SettingsSchema = z
         .default({}),
     /**
      * Image attachment handling. Sub-fields:
-     *   - detail: OpenAI-style fidelity hint applied to every user-
-     *     attached image. "low" = 85 tokens/image fixed (cheap
-     *     thumbnail), "high" = ~768 px tiles (default), "original" =
-     *     keep client-side dimensions (most expensive). Anthropic
-     *     ignores this field today; that's fine — it just gets
-     *     dropped on the Claude path.
+     *   - detail: provider-agnostic image clarity. Drives the
+     *     renderer-side downscale (low→~1024 / standard→~1568 /
+     *     high→~2576 px long edge) so BOTH providers save tokens
+     *     before send. Legacy "original" is migrated to "high".
      *   - mcpImageTokenBudget: per-turn cap on token cost of images
      *     returned by MCP tools. Codex doesn't enforce this; CC uses
      *     25 000. Set to 0 to disable.
      */
     images: z
         .object({
-        detail: z.enum(["low", "high", "original"]).optional(),
+        detail: z
+            .preprocess(
+        // Legacy migration: old settings stored "original"; map it to
+        // "high" so existing user.json doesn't fail validation on boot.
+        (v) => (v === "original" ? "high" : v), z.enum(["low", "standard", "high"]))
+            .optional(),
         mcpImageTokenBudget: z.number().int().nonnegative().optional(),
     })
         .optional(),
@@ -308,6 +424,21 @@ export const SettingsSchema = z
         network: z.enum(["allow", "deny"]).optional(),
     })
         .optional(),
+    /**
+     * Top-level environment variables injected into tool subprocesses (the
+     * Bash tool, background shells). Mirrors Claude Code's `env` field: a
+     * KEY=VALUE map that can be set globally (~/.code-shell/settings.json) and
+     * overridden per-project (.code-shell/settings.json). The canonical home
+     * for API keys (e.g. OPENAI_API_KEY) that a skill's script reads — configure
+     * once globally and every project's skills can use it.
+     *
+     * Precedence when merged into the spawn env (lowest → highest):
+     *   project localEnvironment.env  →  global env  →  project env
+     * None of these is filtered through the deny regex (see mergeShellEnv):
+     * they are values the user typed deliberately, a different trust class from
+     * the host process.env passthrough the deny machinery guards against.
+     */
+    env: z.record(z.string()).optional(),
     /**
      * Project-local environment profile. Mirrors Codex's local-environment
      * shape at the settings layer: setup/cleanup scripts can be customized per
@@ -353,8 +484,48 @@ export const SettingsSchema = z
         matcher: z.string().optional(),
         timeout_ms: z.number().int().positive().optional(),
         cwd: z.string().optional(),
+        /** Soft off-switch: the entry stays in the file (and the UI) but
+         *  registerSettingsHooks skips it. Absent = enabled. */
+        disabled: z.boolean().optional(),
     }))
         .optional(),
+    /**
+     * External coding-agent orchestration (Claude Code / Codex CLI).
+     * Used by the Mobile Web Remote to launch managed jobs. dangerousArgs
+     * is config-provided (not hardcoded) so it tracks CLI flag changes;
+     * project-default dangerous mode only applies inside trustedWorkspaces.
+     */
+    externalAgents: z
+        .object({
+        claudeCode: z
+            .object({
+            command: z.string().optional(),
+            defaultMode: z.enum(["safe", "dangerous"]).optional(),
+            dangerousArgs: z.array(z.string()).optional(),
+            trustedWorkspaces: z.array(z.string()).optional(),
+            autoStartInTrustedWorkspaces: z.boolean().optional(),
+        })
+            .optional(),
+        codex: z
+            .object({
+            command: z.string().optional(),
+            args: z.array(z.string()).optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+    /**
+     * Credential-use gate (凭证模块第二期). Controls whether the AI's
+     * `UseCredential` tool prompts before handing a stored credential to a
+     * command. `autoApprove: true` skips the prompt entirely (默认关 — every
+     * use asks, or is remembered for the session). See
+     * docs/superpowers/specs/2026-06-16-credential-use-gate-design.md §5.
+     */
+    credentialUse: z
+        .object({
+        autoApprove: z.boolean().optional(),
+    })
+        .optional(),
 })
     .passthrough();
 export function validateSettings(raw) {

package/dist/skills/scanner.d.ts

@@ -33,6 +33,15 @@ export interface SkillDefinition {
 export interface ScanSkillsOptions {
     disabledSkills?: string[];
     disabledPlugins?: string[];
+    /**
+     * Hard skill isolation for sub-agents. When set, ONLY skills whose name is
+     * in this list survive — every other skill is dropped from the result
+     * regardless of the disabled lists. Undefined → no allowlist filtering
+     * (parent inherits the full pool). An empty array → no skills at all.
+     * Applied after the disabled-list filters, so a skill must be both allowed
+     * AND not disabled to appear.
+     */
+    skillAllowlist?: string[];
 }
 export declare function scanSkills(cwd: string, opts?: ScanSkillsOptions): SkillDefinition[];
 export declare function invalidateSkillCache(): void;

package/dist/skills/scanner.js

@@ -157,18 +157,46 @@ function installedPluginsMtime() {
         return "0";
     }
 }
-const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}`);
+/**
+ * mtime of each local skills base dir (project + user). A directory's mtime
+ * changes when a child entry is added/removed, so installing a new skill into
+ * `<cwd>/.code-shell/skills` or `~/.code-shell/skills` busts the cache on the
+ * next scan — the just-installed skill becomes visible to the running session
+ * without a restart. (Editing an existing skill's *contents* does not bump the
+ * dir mtime; install paths additionally call invalidateSkillCache() to cover
+ * that, so this is the passive half of a two-part guard.)
+ */
+function skillsDirsMtime(cwd) {
+    return bases(cwd)
+        .map((b) => {
+        try {
+            return statSync(b.dir).mtimeMs.toString();
+        }
+        catch {
+            return "0";
+        }
+    })
+        .join("|");
+}
+const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}\0${skillsDirsMtime(cwd)}`);
 export function scanSkills(cwd, opts) {
     const all = memoized(cwd);
     const disabledSkills = opts?.disabledSkills;
     const disabledPlugins = opts?.disabledPlugins;
+    const skillAllowlist = opts?.skillAllowlist;
     const hasSkillFilter = disabledSkills && disabledSkills.length > 0;
     const hasPluginFilter = disabledPlugins && disabledPlugins.length > 0;
-    if (!hasSkillFilter && !hasPluginFilter)
+    // An allowlist of [] is meaningful (no skills at all), so check for
+    // presence with !== undefined, not truthiness/length.
+    const hasAllowlist = skillAllowlist !== undefined;
+    if (!hasSkillFilter && !hasPluginFilter && !hasAllowlist)
         return all;
     const skillSet = hasSkillFilter ? new Set(disabledSkills) : null;
     const pluginSet = hasPluginFilter ? new Set(disabledPlugins) : null;
+    const allowSet = hasAllowlist ? new Set(skillAllowlist) : null;
     return all.filter((s) => {
+        if (allowSet && !allowSet.has(s.name))
+            return false;
         if (skillSet && skillSet.has(s.name))
             return false;
         if (pluginSet) {

package/dist/stt/resolve-transcribe.d.ts

@@ -0,0 +1,31 @@
+import type { TranscribeCreds } from "./transcribe.js";
+export interface ResolvedTranscribeProvider {
+    creds: TranscribeCreds;
+    /** Model id to transcribe with (e.g. gpt-4o-transcribe). */
+    model: string;
+}
+export declare function resolveTranscribeProvider(cwd: string, prefer?: string): ResolvedTranscribeProvider | null;
+/** Tool/UI-visibility guard: is voice input usable (some transcribe provider
+ *  resolvable)? Lets the desktop disable/enable the mic button. */
+export declare function isTranscribeAvailable(cwd: string): boolean;
+/**
+ * A renderer-safe description of what voice input will ACTUALLY use right now —
+ * so the UI can show "currently using gpt-4o-transcribe, reusing your OpenAI key
+ * sk-…1234" instead of looking unconfigured when the fallback is silently in
+ * effect. The key is MASKED (never ship the full secret to the renderer for
+ * display). `source`:
+ *   - "connection": an explicit audio modelConnection is configured
+ *   - "fallback":   no audio connection; reusing an OpenAI-family credential
+ *   - "none":       nothing usable — voice input unavailable
+ */
+export interface TranscribeDescription {
+    source: "connection" | "fallback" | "none";
+    model?: string;
+    baseUrl?: string;
+    /** Masked key for display (e.g. "sk-123...cdef"). */
+    maskedKey?: string;
+    /** For "fallback": the credential id/catalog whose key is being reused. */
+    reusedCredentialId?: string;
+    reusedCredentialCatalogId?: string;
+}
+export declare function describeTranscribe(cwd: string): TranscribeDescription;

package/dist/stt/resolve-transcribe.js

@@ -0,0 +1,108 @@
+/**
+ * Resolve which transcription (speech-to-text) provider the desktop voice-input
+ * should use, from settings. Mirrors generate-image.ts's resolveImageProvider:
+ *
+ *   0. Unified store — modelConnections (tag=audio) + credentials, via
+ *      genInstancesFromConnections. Honors `defaults.audio` / an explicit
+ *      `prefer` id, else the first usable.
+ *   1. Fallback — no audio connection configured: reuse any OpenAI-family
+ *      credential's key (so a user who only set up OpenAI text/images can
+ *      dictate immediately with zero extra config). Targets the official
+ *      OpenAI endpoint + gpt-4o-transcribe.
+ *
+ * Returns null when nothing usable is configured (or an explicit `prefer` isn't
+ * usable — no silent fallback in that case, matching the image resolver).
+ */
+import { SettingsManager } from "../settings/manager.js";
+import { getMergedCatalog } from "../model-catalog/index.js";
+import { genInstancesFromConnections } from "../model-catalog/gen-connections.js";
+import { maskKey } from "../onboarding.js";
+/** Catalog ids whose credentials are OpenAI-compatible and carry an OpenAI key
+ *  reusable for /audio/transcriptions on the official endpoint. */
+const OPENAI_CRED_CATALOG_IDS = new Set(["openai", "openai-images", "openai-transcribe"]);
+const OPENAI_AUDIO_BASE_URL = "https://api.openai.com/v1";
+const OPENAI_DEFAULT_TRANSCRIBE_MODEL = "gpt-4o-transcribe";
+export function resolveTranscribeProvider(cwd, prefer) {
+    const settings = new SettingsManager(cwd, "full").get();
+    const conns = settings.modelConnections;
+    const creds = settings.credentials;
+    // 0. Unified store: audio connections.
+    if (Array.isArray(conns) && conns.some((c) => c.tag === "audio")) {
+        const list = genInstancesFromConnections(conns, (Array.isArray(creds) ? creds : []), getMergedCatalog(), "audio");
+        const usable = list.filter((p) => !!p.apiKey && !!p.baseUrl);
+        const def = settings.defaults?.audio;
+        if (prefer) {
+            const chosen = usable.find((p) => p.id === prefer);
+            // Explicit request not usable → don't silently fall back.
+            if (chosen) {
+                return {
+                    creds: { baseUrl: chosen.baseUrl, apiKey: chosen.apiKey },
+                    model: chosen.defaultModel || OPENAI_DEFAULT_TRANSCRIBE_MODEL,
+                };
+            }
+            return null;
+        }
+        const preferred = def ? usable.find((p) => p.id === def) : undefined;
+        const chosen = preferred ?? usable[0];
+        if (chosen) {
+            return {
+                creds: { baseUrl: chosen.baseUrl, apiKey: chosen.apiKey },
+                model: chosen.defaultModel || OPENAI_DEFAULT_TRANSCRIBE_MODEL,
+            };
+        }
+        // audio connections exist but none usable; if explicit prefer was handled
+        // above. Fall through to the credential fallback for the implicit case.
+    }
+    // 1. Fallback: reuse an OpenAI-family credential key (no audio connection set
+    // up yet). Only for the implicit path — an explicit `prefer` that didn't
+    // resolve above already returned null.
+    if (prefer)
+        return null;
+    if (Array.isArray(creds)) {
+        const openaiCred = creds.find((c) => typeof c.apiKey === "string" && c.apiKey && OPENAI_CRED_CATALOG_IDS.has(c.catalogId ?? ""));
+        if (openaiCred?.apiKey) {
+            return {
+                creds: { baseUrl: OPENAI_AUDIO_BASE_URL, apiKey: openaiCred.apiKey },
+                model: OPENAI_DEFAULT_TRANSCRIBE_MODEL,
+            };
+        }
+    }
+    return null;
+}
+/** Tool/UI-visibility guard: is voice input usable (some transcribe provider
+ *  resolvable)? Lets the desktop disable/enable the mic button. */
+export function isTranscribeAvailable(cwd) {
+    return resolveTranscribeProvider(cwd) !== null;
+}
+export function describeTranscribe(cwd) {
+    const settings = new SettingsManager(cwd, "full").get();
+    const conns = settings.modelConnections;
+    const creds = settings.credentials;
+    // A configured audio connection wins (mirror resolveTranscribeProvider's order).
+    if (Array.isArray(conns) && conns.some((c) => c.tag === "audio")) {
+        const resolved = resolveTranscribeProvider(cwd);
+        if (resolved) {
+            return {
+                source: "connection",
+                model: resolved.model,
+                baseUrl: resolved.creds.baseUrl,
+                maskedKey: maskKey(resolved.creds.apiKey),
+            };
+        }
+    }
+    // Fallback: reused OpenAI-family credential.
+    if (Array.isArray(creds)) {
+        const openaiCred = creds.find((c) => typeof c.apiKey === "string" && c.apiKey && OPENAI_CRED_CATALOG_IDS.has(c.catalogId ?? ""));
+        if (openaiCred?.apiKey) {
+            return {
+                source: "fallback",
+                model: OPENAI_DEFAULT_TRANSCRIBE_MODEL,
+                baseUrl: OPENAI_AUDIO_BASE_URL,
+                maskedKey: maskKey(openaiCred.apiKey),
+                reusedCredentialId: openaiCred.id,
+                reusedCredentialCatalogId: openaiCred.catalogId,
+            };
+        }
+    }
+    return { source: "none" };
+}