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

package/dist/settings/schema.js

@@ -2,6 +2,34 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
+/**
+ * Tri-state project capability overlay. Lives in PROJECT settings only and
+ * layers over the global baseline (disabledSkills / disabledPlugins /
+ * mcpServers.<name>.enabled / disabledAgents). NOT a second denylist:
+ *   - "on"      → force enabled (even if globally disabled)
+ *   - "off"     → force disabled (even if globally enabled)
+ *   - "inherit" → take the global baseline. We don't persist "inherit"; an
+ *                 absent key means inherit. See the project-scoped
+ *                 capabilities design (spec §4).
+ */
+export const CapabilityOverrideSchema = z.enum(["inherit", "on", "off"]);
+export const CapabilityOverridesSchema = z
+    .object({
+    skills: z.record(CapabilityOverrideSchema).optional(),
+    plugins: z.record(CapabilityOverrideSchema).optional(),
+    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
     .object({
     agent: z
@@ -12,16 +40,16 @@ export const SettingsSchema = z
         disabledBuiltinTools: z.array(z.string()).default([]),
         customSystemPrompt: z.string().optional(),
         appendSystemPrompt: z.string().optional(),
+        responseLanguage: z.string().optional(),
+        userProfile: z.string().optional(),
+        instructions: z
+            .object({
+            compatClaude: z.boolean().default(true),
+            compatCodex: z.boolean().default(true),
+        })
+            .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(),
     /**
      * Toggle background auto-update. When true (default), code-shell checks
      * npm for newer versions and — if the npm global prefix is writable —
@@ -30,85 +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(),
-        /**
-         * DeepSeek V4 thinking-mode default for this provider. "enabled"
-         * matches endpoint default; "disabled" makes V4 calls run in
-         * non-thinking mode (faster, cheaper). Ignored by every provider
-         * other than DeepSeek V4. Per-call overrides still win.
-         */
-        thinking: z.enum(["enabled", "disabled"]).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 thinking override. Wins over the provider-level
-         * setting (settings.providers[].thinking). Use this when
-         * different models under the same provider need different
-         * defaults — e.g. DeepSeek V4 Pro off (faster) but V4 Flash on.
-         */
-        thinking: z.enum(["enabled", "disabled"]).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
@@ -127,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
@@ -137,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(),
@@ -146,7 +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
@@ -162,6 +289,46 @@ export const SettingsSchema = z
      * names (no colon suffix). See scanSkills(opts.disabledPlugins).
      */
     disabledPlugins: z.array(z.string()).default([]),
+    /**
+     * Sub-agent role names (the `name` in .code-shell/agents/*.md) to
+     * hide from the registry. A disabled role is filtered out at load
+     * so it never appears in registry.list()/get() — the Agent tool's
+     * agent_type list won't show it and the LLM can't pick it. Mirrors
+     * disabledSkills / disabledPlugins.
+     */
+    disabledAgents: z.array(z.string()).default([]),
+    /**
+     * Project-scoped tri-state capability overlay. Only meaningful in
+     * ${cwd}/.code-shell/settings.json; layered over the global baseline at
+     * 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"),
@@ -204,6 +371,15 @@ export const SettingsSchema = z
             .record(z.enum(["serper", "tavily", "searxng"]), z.object({
             apiKey: z.string().optional(),
             baseUrl: z.string().optional(),
+            lastProbe: z
+                .object({
+                status: z.enum(["ok", "error", "unconfigured"]),
+                sampleTitles: z.array(z.string()).optional(),
+                errorMessage: z.string().optional(),
+                errorDetail: z.string().optional(),
+                lastProbedAt: z.string(),
+            })
+                .optional(),
         }))
             .optional(),
     })
@@ -213,6 +389,27 @@ export const SettingsSchema = z
         format: z.enum(["text", "json", "jsonl", "stream-json"]).default("text"),
     })
         .default({}),
+    /**
+     * Image attachment handling. Sub-fields:
+     *   - 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
+            .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(),
     /**
      * OS-level sandbox for shell-tool execution. "auto" picks per platform:
      * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
@@ -227,6 +424,49 @@ 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
+     * platform, and env values are stored as KEY=VALUE pairs. Runtime wiring is
+     * intentionally separate from the MCP server env model above.
+     */
+    localEnvironment: z
+        .object({
+        name: z.string().optional(),
+        setupScripts: z
+            .object({
+            default: z.string().optional(),
+            macos: z.string().optional(),
+            linux: z.string().optional(),
+            windows: z.string().optional(),
+        })
+            .optional(),
+        cleanupScripts: z
+            .object({
+            default: z.string().optional(),
+            macos: z.string().optional(),
+            linux: z.string().optional(),
+            windows: z.string().optional(),
+        })
+            .optional(),
+        env: z.record(z.string()).optional(),
+    })
+        .optional(),
     /**
      * Shell-hook configuration. Each entry binds a HookEventName to a
      * shell command; the command receives ctx JSON on stdin and returns
@@ -244,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;