@cjhyy/code-shell-core 0.8.12 → 0.8.20

package/dist/tool-system/builtin/configure-model-connection.js

@@ -0,0 +1,396 @@
+/**
+ * ConfigureModelConnection — safely materialize one catalog model into the
+ * unified settings.modelConnections store without exposing or copying API
+ * keys. The write is schema-validated, lock-protected, atomic, and updates the
+ * selected tag default in the same transaction when requested.
+ */
+import { SettingsManager } from "../../settings/manager.js";
+import { getMergedCatalog } from "../../model-catalog/index.js";
+import { modelEntriesFromConnections } from "../../engine/model-connections-pool.js";
+import { ModelPool } from "../../llm/model-pool.js";
+import { createLLMClient } from "../../llm/client-factory.js";
+import { isCredentialCompatible, } from "../../model-catalog/resolve.js";
+import { notifySettingsChanged } from "./settings-changed.js";
+function redactCredentialSecrets(message, credentials) {
+    let redacted = message;
+    for (const credential of credentials) {
+        if (credential.apiKey)
+            redacted = redacted.replaceAll(credential.apiKey, "[REDACTED]");
+    }
+    return redacted;
+}
+export async function probeTextModelConnection(connection, credentials, catalog, options = {}) {
+    const entry = modelEntriesFromConnections([connection], credentials, catalog)[0];
+    if (!entry)
+        return { ok: false, error: "the saved connection could not be resolved" };
+    const pool = new ModelPool([entry]);
+    const config = pool.toLLMConfig(entry);
+    try {
+        const client = await (options.createClient ?? createLLMClient)(config, {
+            temperature: 0,
+            timeout: 30_000,
+            retryMaxAttempts: 1,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+        const response = await client.createMessage({
+            systemPrompt: "You are a connection health check. Follow the user's reply instruction.",
+            messages: [{ role: "user", content: "Reply with READY only." }],
+            tools: [],
+            maxTokens: 32,
+            stream: false,
+            signal: AbortSignal.timeout(30_000),
+            requestVisible: false,
+        });
+        return {
+            ok: true,
+            response: response.text.slice(0, 200),
+            stopReason: response.stopReason,
+            ...(response.usage
+                ? {
+                    usage: {
+                        promptTokens: response.usage.promptTokens,
+                        completionTokens: response.usage.completionTokens,
+                        totalTokens: response.usage.totalTokens,
+                    },
+                }
+                : {}),
+        };
+    }
+    catch (error) {
+        const raw = error instanceof Error ? error.message : String(error);
+        const safeError = redactCredentialSecrets(raw, credentials);
+        return { ok: false, error: safeError.slice(0, 1000) };
+    }
+}
+const DEFAULT_DEPS = {
+    makeSettingsManager: (cwd, scope) => new SettingsManager(cwd, scope),
+    getCatalog: getMergedCatalog,
+    notifySettingsChanged,
+    testTextConnection: probeTextModelConnection,
+};
+export const configureModelConnectionToolDef = {
+    name: "ConfigureModelConnection",
+    description: "Create or update a configured model connection from an existing catalog model. " +
+        "Use this after EditModelCatalog when the user wants the model ready to use, not merely " +
+        "listed as a template. It validates the catalog model, reuses a compatible existing " +
+        "credential by id (never returns or copies its API key), seeds catalog parameter defaults, " +
+        "and atomically updates modelConnections plus defaults. User scope requires a full/trusted " +
+        "host context. If more than one compatible credential exists, pass credentialId explicitly. " +
+        "Set testConnection=true to make one small real request and report whether routing worked.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            catalogId: {
+                type: "string",
+                description: "Existing merged catalog provider id, e.g. 'openrouter'.",
+            },
+            model: {
+                type: "string",
+                description: "Exact model preset value in that provider, e.g. 'openai/gpt-5.6-luna'.",
+            },
+            connectionId: {
+                type: "string",
+                description: "Optional stable instance id. Omit to update an existing connection for the same " +
+                    "catalog model or generate a collision-free id.",
+            },
+            credentialId: {
+                type: "string",
+                description: "Existing compatible credential id. Omit to reuse the current connection credential " +
+                    "or auto-select when exactly one compatible credential exists.",
+            },
+            paramValues: {
+                type: "object",
+                description: "Optional model parameter overrides keyed by catalog ParamSpec name. Catalog defaults " +
+                    "are seeded first; unknown names or invalid enum/type/range values are rejected.",
+            },
+            setDefault: {
+                type: "boolean",
+                description: "Set this connection as the default for its catalog tag. The first configured " +
+                    "connection for a tag becomes default automatically.",
+            },
+            testConnection: {
+                type: "boolean",
+                description: "After saving a text connection, send one small real request through it. This may " +
+                    "incur a tiny provider charge. A failed test is reported without rolling back the " +
+                    "validated connection.",
+            },
+            scope: {
+                type: "string",
+                enum: ["user", "project"],
+                description: "Settings layer to update. Defaults to user in a full desktop host, otherwise project.",
+            },
+        },
+        required: ["catalogId", "model"],
+    },
+};
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function connectionIdIsSafe(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value);
+}
+function slugPart(value) {
+    return (value
+        .toLowerCase()
+        .split("/")
+        .filter(Boolean)
+        .pop()
+        ?.replace(/[^a-z0-9._-]+/gu, "-")
+        .replace(/^-+|-+$/gu, "") || "model");
+}
+function uniqueConnectionId(entry, model, taken) {
+    const base = !taken.has(entry.id) ? entry.id : `${entry.id}-${slugPart(model)}`;
+    if (!taken.has(base))
+        return base;
+    let suffix = 2;
+    while (taken.has(`${base}-${suffix}`))
+        suffix += 1;
+    return `${base}-${suffix}`;
+}
+function paramDefaults(preset) {
+    const values = {};
+    for (const spec of preset.params ?? []) {
+        if (spec.default !== undefined)
+            values[spec.name] = spec.default;
+    }
+    return values;
+}
+function validateParamValue(spec, value) {
+    if (spec.control === "enum") {
+        if (typeof value !== "string")
+            return "must be a string enum value";
+        if (spec.options?.length && !spec.options.includes(value)) {
+            return `must be one of [${spec.options.join(", ")}]`;
+        }
+        return undefined;
+    }
+    if (spec.control === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            return "must be a finite number";
+        if (spec.min !== undefined && value < spec.min)
+            return `must be >= ${spec.min}`;
+        if (spec.max !== undefined && value > spec.max)
+            return `must be <= ${spec.max}`;
+        return undefined;
+    }
+    if (spec.control === "toggle") {
+        return typeof value === "boolean" ? undefined : "must be a boolean";
+    }
+    return typeof value === "string" ? undefined : "must be a string";
+}
+function validateParamValues(values, specs) {
+    if (Object.keys(values).length > 64)
+        return "paramValues exceeds 64 entries";
+    const byName = new Map(specs.map((spec) => [spec.name, spec]));
+    for (const [name, value] of Object.entries(values)) {
+        const spec = byName.get(name);
+        if (!spec)
+            return `unknown parameter "${name}" for this model`;
+        const issue = validateParamValue(spec, value);
+        if (issue)
+            return `parameter "${name}" ${issue}`;
+    }
+    return undefined;
+}
+function connectionsFrom(settings) {
+    return Array.isArray(settings.modelConnections)
+        ? settings.modelConnections
+        : [];
+}
+function credentialsFrom(settings) {
+    return Array.isArray(settings.credentials) ? settings.credentials : [];
+}
+function findTargetConnection(connections, entry, model, explicitId) {
+    if (explicitId)
+        return connections.find((connection) => connection.id === explicitId);
+    return connections.find((connection) => connection.catalogId === entry.id &&
+        connection.tag === entry.tag &&
+        connection.model === model);
+}
+function selectCredential(entry, catalog, credentials, requestedId, existingId) {
+    const compatible = credentials.filter((credential) => isCredentialCompatible(entry, credential, catalog) &&
+        (entry.needsKey === false || Boolean(credential.apiKey?.trim())));
+    const selectedId = requestedId ?? existingId;
+    if (selectedId) {
+        const selected = credentials.find((credential) => credential.id === selectedId);
+        if (!selected)
+            return { error: `credential "${selectedId}" does not exist in this scope` };
+        if (!isCredentialCompatible(entry, selected, catalog)) {
+            return { error: `credential "${selectedId}" is not compatible with catalog "${entry.id}"` };
+        }
+        if (entry.needsKey !== false && !selected.apiKey?.trim()) {
+            return { error: `credential "${selectedId}" has no usable API key` };
+        }
+        return { credentialId: selected.id };
+    }
+    if (entry.needsKey === false)
+        return {};
+    if (compatible.length === 1)
+        return { credentialId: compatible[0].id };
+    if (compatible.length === 0) {
+        return { error: `no compatible credential is configured for catalog "${entry.id}"` };
+    }
+    return {
+        error: `multiple compatible credentials exist for catalog "${entry.id}": ` +
+            `${compatible.map((credential) => credential.id).join(", ")}. Pass credentialId explicitly.`,
+    };
+}
+export async function configureModelConnectionTool(args, ctx, deps = DEFAULT_DEPS) {
+    if (!ctx)
+        return "Error: ConfigureModelConnection requires a scoped tool context.";
+    if (ctx.settingsScope === "isolated") {
+        return "Error: isolated sessions cannot persist model connections.";
+    }
+    const requestedScope = args.scope;
+    const scope = requestedScope === "user" || requestedScope === "project"
+        ? requestedScope
+        : ctx.settingsScope === "full"
+            ? "user"
+            : "project";
+    if (scope === "user" && ctx.settingsScope !== "full") {
+        return "Error: user-scope model connections require settingsScope=full.";
+    }
+    const catalogId = typeof args.catalogId === "string" ? args.catalogId.trim() : "";
+    const model = typeof args.model === "string" ? args.model.trim() : "";
+    const connectionId = typeof args.connectionId === "string" ? args.connectionId.trim() : undefined;
+    const credentialId = typeof args.credentialId === "string" ? args.credentialId.trim() : undefined;
+    if (!catalogId)
+        return "Error: catalogId is required.";
+    if (!model)
+        return "Error: model is required.";
+    if (connectionId && !connectionIdIsSafe(connectionId)) {
+        return "Error: connectionId must be 1-128 safe id characters (letters, numbers, . _ : -).";
+    }
+    if (args.paramValues !== undefined && !isRecord(args.paramValues)) {
+        return "Error: paramValues must be an object.";
+    }
+    if (args.setDefault !== undefined && typeof args.setDefault !== "boolean") {
+        return "Error: setDefault must be a boolean.";
+    }
+    if (args.testConnection !== undefined && typeof args.testConnection !== "boolean") {
+        return "Error: testConnection must be a boolean.";
+    }
+    const catalog = deps.getCatalog();
+    const entry = catalog.find((candidate) => candidate.id === catalogId);
+    if (!entry)
+        return `Error: catalog "${catalogId}" does not exist.`;
+    const preset = entry.modelPresets?.find((candidate) => candidate.value === model);
+    if (!preset) {
+        return `Error: model "${model}" is not declared in catalog "${catalogId}".`;
+    }
+    if (args.testConnection === true && entry.tag !== "text") {
+        return "Error: testConnection currently supports text catalog entries only.";
+    }
+    const manager = deps.makeSettingsManager(ctx.cwd, ctx.settingsScope === "full" ? "full" : "project");
+    let effectiveSettings;
+    let targetSettings;
+    try {
+        effectiveSettings = manager.get();
+        targetSettings = manager.getForScope(scope, ctx.cwd);
+    }
+    catch (error) {
+        return `Error: settings validation failed: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    const targetConnections = connectionsFrom(targetSettings);
+    const preflightExisting = findTargetConnection(targetConnections, entry, model, connectionId);
+    if (connectionId &&
+        preflightExisting &&
+        (preflightExisting.catalogId !== entry.id || preflightExisting.tag !== entry.tag)) {
+        return `Error: connectionId "${connectionId}" already belongs to another catalog or tag.`;
+    }
+    const effectiveCredentials = scope === "user" ? credentialsFrom(targetSettings) : credentialsFrom(effectiveSettings);
+    const selected = selectCredential(entry, catalog, effectiveCredentials, credentialId, preflightExisting?.credentialId);
+    if (selected.error)
+        return `Error: ${selected.error}`;
+    const providedParams = args.paramValues;
+    let outcome;
+    try {
+        manager.mutateSettingsForScope(scope, ctx.cwd, (current) => {
+            const connections = connectionsFrom(current);
+            const existing = findTargetConnection(connections, entry, model, connectionId);
+            if (connectionId &&
+                existing &&
+                (existing.catalogId !== entry.id || existing.tag !== entry.tag)) {
+                throw new Error(`connectionId "${connectionId}" was concurrently claimed`);
+            }
+            // Revalidate user-scope credential references inside the same locked
+            // file transaction so a concurrent credential deletion cannot leave a
+            // newly written dangling reference. Project connections may intentionally
+            // inherit a user credential from the effective settings layer.
+            if (scope === "user" && selected.credentialId) {
+                const lockedSelection = selectCredential(entry, catalog, credentialsFrom(current), selected.credentialId, undefined);
+                if (lockedSelection.error)
+                    throw new Error(lockedSelection.error);
+            }
+            const id = existing?.id ??
+                connectionId ??
+                uniqueConnectionId(entry, model, new Set(connections.map((connection) => connection.id)));
+            const defaults = paramDefaults(preset);
+            const keepExistingParams = existing?.model === model && providedParams === undefined;
+            const paramValues = keepExistingParams
+                ? (existing?.paramValues ?? defaults)
+                : { ...defaults, ...(providedParams ?? {}) };
+            const paramIssue = validateParamValues(paramValues, preset.params ?? []);
+            if (paramIssue)
+                throw new Error(paramIssue);
+            const connection = {
+                ...(existing ?? {}),
+                id,
+                catalogId: entry.id,
+                tag: entry.tag,
+                model,
+                ...(selected.credentialId ? { credentialId: selected.credentialId } : {}),
+                ...(Object.keys(paramValues).length > 0 ? { paramValues } : {}),
+            };
+            if (!selected.credentialId)
+                delete connection.credentialId;
+            if (Object.keys(paramValues).length === 0)
+                delete connection.paramValues;
+            const nextConnections = existing
+                ? connections.map((candidate) => (candidate.id === existing.id ? connection : candidate))
+                : [...connections, connection];
+            current.modelConnections = nextConnections;
+            const rawDefaults = isRecord(current.defaults) ? current.defaults : {};
+            const becameDefault = args.setDefault === true || typeof rawDefaults[entry.tag] !== "string";
+            if (becameDefault)
+                current.defaults = { ...rawDefaults, [entry.tag]: id };
+            outcome = {
+                action: existing ? "updated" : "added",
+                connection,
+                becameDefault,
+            };
+        });
+    }
+    catch (error) {
+        return `Error: could not configure model connection: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (!outcome)
+        return "Error: model connection write produced no result.";
+    deps.notifySettingsChanged();
+    let verification;
+    if (args.testConnection === true) {
+        try {
+            // Reload credential metadata after the settings transaction. This avoids
+            // probing with a stale key if another settings writer rotated it between
+            // preflight and persistence.
+            const refreshed = scope === "user" ? manager.getForScope("user", ctx.cwd) : manager.get();
+            verification = await deps.testTextConnection(outcome.connection, credentialsFrom(refreshed), catalog);
+        }
+        catch (error) {
+            const raw = error instanceof Error ? error.message : String(error);
+            verification = {
+                ok: false,
+                error: `could not start connection test: ${redactCredentialSecrets(raw, effectiveCredentials)}`.slice(0, 1000),
+            };
+        }
+    }
+    return JSON.stringify({
+        ok: true,
+        action: outcome.action,
+        scope,
+        connection: outcome.connection,
+        defaultForTag: outcome.becameDefault ? entry.tag : undefined,
+        hotReloadRequested: true,
+        ...(verification ? { verification } : {}),
+    }, null, 2);
+}

package/dist/tool-system/builtin/edit-model-catalog.d.ts

@@ -1,9 +1,7 @@
 import type { ToolDefinition } from "../../types.js";
-/** Notifies process hosts after the user catalog has been persisted. Desktop
- * uses this to refresh mounted settings/connection views without waiting for
- * a parent turn_complete event (which may be absent for child/yielded runs). */
-type ModelCatalogChangedSink = () => void;
-export declare function setModelCatalogChangedSink(sink: ModelCatalogChangedSink | null): void;
+import { type SettingsChangedSink } from "./settings-changed.js";
+/** Backwards-compatible catalog-specific name for the shared settings/resource
+ * invalidation sink. */
+export declare function setModelCatalogChangedSink(sink: SettingsChangedSink | null): void;
 export declare const editModelCatalogToolDef: ToolDefinition;
 export declare function editModelCatalogTool(args: Record<string, unknown>): Promise<string>;
-export {};

package/dist/tool-system/builtin/edit-model-catalog.js

@@ -13,6 +13,7 @@ import { saveCatalogEntry } from "../../model-catalog/save-entry.js";
 import { catalogEntrySchema, modelPresetSchema, } from "../../model-catalog/types.js";
 import { upsertModelPreset } from "../../model-catalog/upsert.js";
 import { PROVIDER_KINDS } from "../../llm/provider-kinds.js";
+import { notifySettingsChanged, setSettingsChangedSink, } from "./settings-changed.js";
 const CATALOG_ADAPTER_KINDS = [...Object.keys(PROVIDER_KINDS), "fal"].join("|");
 /**
  * Recognise first-party provider hosts so the catalog tool can reject the
@@ -52,17 +53,13 @@ function providerIdentityError(entry) {
         `protocol="${protocolHint}". adapterKind identifies the provider/gateway account; ` +
         `protocol only identifies the HTTP wire format.`);
 }
-let modelCatalogChangedSink = null;
+/** Backwards-compatible catalog-specific name for the shared settings/resource
+ * invalidation sink. */
 export function setModelCatalogChangedSink(sink) {
-    modelCatalogChangedSink = sink;
+    setSettingsChangedSink(sink);
 }
 function fireModelCatalogChanged() {
-    try {
-        modelCatalogChangedSink?.();
-    }
-    catch {
-        // Host notification is best-effort; the catalog write itself succeeded.
-    }
+    notifySettingsChanged();
 }
 export const editModelCatalogToolDef = {
     name: "EditModelCatalog",

package/dist/tool-system/builtin/index.js

@@ -5,6 +5,7 @@ import { readToolDef, readTool } from "./read.js";
 import { writeToolDef, writeTool } from "./write.js";
 import { generateImageToolDef, generateImageTool, isGenerateImageAvailable, } from "./generate-image.js";
 import { editModelCatalogToolDef, editModelCatalogTool } from "./edit-model-catalog.js";
+import { configureModelConnectionToolDef, configureModelConnectionTool, } from "./configure-model-connection.js";
 import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable, } from "./generate-video.js";
 import { viewImageToolDef, viewImageTool } from "./view-image.js";
 import { editToolDef, editTool } from "./edit.js";
@@ -123,6 +124,19 @@ const BUILTIN_CONTRIBUTIONS = [
         execute: editModelCatalogTool,
         exposure: expose(GENERAL_TAGS),
     },
+    {
+        definition: {
+            ...configureModelConnectionToolDef,
+            source: "builtin",
+            permissionDefault: "ask",
+            isReadOnly: false,
+            // One lock-protected settings transaction; concurrent model connection
+            // mutations must serialize to preserve unique ids and defaults.
+            isConcurrencySafe: false,
+        },
+        execute: configureModelConnectionTool,
+        exposure: expose(GENERAL_TAGS),
+    },
     {
         definition: {
             ...generateImageToolDef,

package/dist/tool-system/builtin/install-capability.js

@@ -28,6 +28,7 @@ import { resolveExecutable } from "../../utils/exec.js";
 const SAFE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const SAFE_PLUGIN_SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const SAFE_SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SAFE_OVERRIDE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 const HEADER_NAME_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
 const MCP_TOOL_NAME_RE = /^[^\s\u0000-\u001F\u007F]{1,256}$/;
@@ -338,10 +339,13 @@ function isSafeRemoteUrl(raw) {
         return false;
     return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname.toLowerCase());
 }
-async function installMarketplacePlugin(args, deps) {
+async function installMarketplacePlugin(args, ctx, deps) {
     if (args.scope !== undefined && args.scope !== "user") {
         return "Error: marketplace plugins currently install at user scope; omit scope or use scope='user'.";
     }
+    if (ctx?.settingsScope !== "full") {
+        return "Error: this host isolates user settings; marketplace plugins cannot be installed.";
+    }
     const plugin = safePluginSegment(args.plugin);
     const marketplace = safePluginSegment(args.marketplace);
     if (!plugin)
@@ -440,6 +444,9 @@ async function mutateMarketplacePlugin(args, ctx, deps) {
     if (!deps.listInstalled().some((candidate) => candidate.key === installKey)) {
         return `Error: plugin ${installKey} is not installed.`;
     }
+    if ((action === "update" || action === "uninstall") && ctx?.settingsScope !== "full") {
+        return "Error: this host isolates user settings; marketplace plugins cannot be changed.";
+    }
     if (action === "update") {
         const refreshed = await deps.refreshMarketplace(marketplace);
         if (!refreshed.ok) {
@@ -474,12 +481,15 @@ async function mutateMarketplacePlugin(args, ctx, deps) {
     if (args.scope !== undefined && args.scope !== "project" && args.scope !== "user") {
         return "Error: plugin enable/disable scope must be `project` or `user`.";
     }
-    if (scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; use project scope.";
     }
     const manager = deps.makeSettingsManager(cwd, scope === "user" ? "full" : "project");
     const enabled = action === "enable";
     if (scope === "project") {
+        if (!SAFE_OVERRIDE_NAME_RE.test(plugin)) {
+            return "Error: project-scoped plugin overrides do not support dots in plugin names; use user scope.";
+        }
         manager.saveProjectSetting(`capabilityOverrides.plugins.${plugin}`, enabled ? "on" : "off", cwd);
     }
     else {
@@ -670,12 +680,16 @@ async function mutateProjectSkills(args, ctx, deps) {
     if (args.scope !== undefined && args.scope !== "project" && args.scope !== "user") {
         return "Error: Skill enable/disable scope must be `project` or `user`.";
     }
-    if (scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; use project scope.";
     }
     const manager = deps.makeSettingsManager(cwd, scope === "user" ? "full" : "project");
     const enabled = action === "enable";
     if (scope === "project") {
+        const unsafe = skills.filter((skill) => !SAFE_OVERRIDE_NAME_RE.test(skill));
+        if (unsafe.length > 0) {
+            return `Error: project-scoped Skill overrides do not support dots in names: ${unsafe.join(", ")}.`;
+        }
         for (const skill of skills) {
             manager.saveProjectSetting(`capabilityOverrides.skills.${skill}`, enabled ? "on" : "off", cwd);
         }
@@ -806,7 +820,7 @@ async function installMcpServer(args, ctx, deps) {
     if (!resolved.ok)
         return `Error: ${resolved.error}`;
     const scope = resolved.scope;
-    if (scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; install the MCP server at local or project scope.";
     }
     const built = buildMcpConfig(args);
@@ -927,7 +941,7 @@ function mcpDetailLines(name, scope, config) {
 }
 function listMcpServers(ctx, deps) {
     const cwd = ctx?.cwd ?? process.cwd();
-    const full = !ctx?.settingsScope || ctx.settingsScope === "full";
+    const full = ctx?.settingsScope === "full";
     const manager = deps.makeSettingsManager(cwd, full ? "full" : "project");
     const scopes = full
         ? ["local", "project", "user"]
@@ -953,7 +967,7 @@ function inspectMcpServer(args, ctx, deps) {
     const resolved = mcpScope(args);
     if (!resolved.ok)
         return `Error: ${resolved.error}`;
-    if (resolved.scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (resolved.scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; user MCP configuration is unavailable.";
     }
     const manager = deps.makeSettingsManager(cwd, resolved.scope === "user" ? "full" : "project");
@@ -980,7 +994,7 @@ async function mutateMcpServer(args, ctx, deps) {
     const resolved = mcpScope(args);
     if (!resolved.ok)
         return `Error: ${resolved.error}`;
-    if (resolved.scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (resolved.scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; use local or project scope.";
     }
     const manager = deps.makeSettingsManager(cwd, resolved.scope === "user" ? "full" : "project");
@@ -1044,7 +1058,7 @@ export async function installCapabilityWithDeps(args, ctx, deps) {
     }
     if (action === "install") {
         if (args.kind === "plugin")
-            return installMarketplacePlugin(args, deps);
+            return installMarketplacePlugin(args, ctx, deps);
         if (args.kind === "skill")
             return installGithubSkills(args, ctx, deps);
         return installMcpServer(args, ctx, deps);

package/dist/tool-system/builtin/settings-changed.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Process-host invalidation bridge for built-ins that persist settings-like
+ * resources outside the renderer. Desktop wires one sink that forwards the
+ * existing agent/settingsChanged notification; headless hosts may leave it
+ * unset and pick the change up on their next settings load.
+ */
+export type SettingsChangedSink = () => void;
+export declare function setSettingsChangedSink(sink: SettingsChangedSink | null): void;
+export declare function notifySettingsChanged(): void;

package/dist/tool-system/builtin/settings-changed.js

@@ -0,0 +1,18 @@
+/**
+ * Process-host invalidation bridge for built-ins that persist settings-like
+ * resources outside the renderer. Desktop wires one sink that forwards the
+ * existing agent/settingsChanged notification; headless hosts may leave it
+ * unset and pick the change up on their next settings load.
+ */
+let settingsChangedSink = null;
+export function setSettingsChangedSink(sink) {
+    settingsChangedSink = sink;
+}
+export function notifySettingsChanged() {
+    try {
+        settingsChangedSink?.();
+    }
+    catch {
+        // Persistence already succeeded. Host invalidation is best-effort.
+    }
+}

package/dist/tool-system/context.d.ts

@@ -227,10 +227,16 @@ export interface ToolContext {
     cwd: string;
     /**
      * True when this call belongs to an external Agent Runtime rather than the
-     * native Engine loop. Async handoff tools use this to keep their result on
-     * the current turn instead of queueing a wake-up only the Engine can consume.
+     * native Engine loop.
      */
     externalRuntime?: boolean;
+    /**
+     * The external-runtime host can route notificationQueue completions back into
+     * this business Session as an injected continuation turn. Async tools must
+     * require this capability before detaching work: `externalRuntime` alone says
+     * who owns the turn, not whether anybody can deliver a later result.
+     */
+    externalRuntimeBackgroundDelivery?: boolean;
     /**
      * Active digital-human profile's portable memory root. Present only when
      * the resolved WorkspaceProfile enables portableMemory for this run.

package/dist/types.d.ts

@@ -747,6 +747,11 @@ export interface ClientDefaults {
     timeout?: number;
     /** Max retry attempts for transient errors. Default 3. */
     retryMaxAttempts?: number;
+    /**
+     * Optional HTTP transport override. Primarily used by embedders and tests
+     * that need an isolated transport without mutating process-global fetch.
+     */
+    fetch?: typeof globalThis.fetch;
     /**
      * Provider-agnostic image clarity level. Drives the renderer-side
      * downscale (long-edge cap: low→~1024 / standard→~1568 / high→~2576)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.8.12",
+  "version": "0.8.20",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",