dominds 1.18.2 → 1.19.3

package/dist/llm/kernel-driver/types.d.ts

@@ -1,23 +1,39 @@
 import type { DialogDisplayState, DialogInterruptionReason } from '@longrun-ai/kernel/types/display-state';
-import type { DialogDiligencePrompt, DialogPrompt, DialogRunControlSpec, DialogRuntimeGuidePrompt, DialogRuntimePrompt, DialogRuntimeReplyPrompt, DialogRuntimeSubdialogPrompt, DialogUserPrompt } from '@longrun-ai/kernel/types/drive-intent';
+import type { DialogDiligencePrompt, DialogPrompt, DialogRunControlSpec, DialogRuntimeGuidePrompt, DialogRuntimePrompt, DialogRuntimeReplyPrompt, DialogRuntimeSideDialogPrompt, DialogUserPrompt } from '@longrun-ai/kernel/types/drive-intent';
 import type { Dialog, DialogID } from '../../dialog';
 export type KernelDriverRunControl = DialogRunControlSpec;
-export type KernelDriverDriveSource = 'unspecified' | 'ws_user_message' | 'ws_user_answer' | 'ws_diligence_push' | 'ws_resume_dialog' | 'ws_resume_all' | 'kernel_driver_backend_loop' | 'kernel_driver_follow_up' | 'kernel_driver_subdialog_init' | 'kernel_driver_subdialog_resume' | 'kernel_driver_fbr_subdialog_round' | 'kernel_driver_type_a_supdialog_call' | 'kernel_driver_supply_response_parent_revive';
+export type KernelDriverDriveSource = 'unspecified' | 'ws_user_message' | 'ws_user_answer' | 'ws_diligence_push' | 'ws_resume_dialog' | 'ws_resume_all' | 'kernel_driver_backend_loop' | 'kernel_driver_follow_up' | 'kernel_driver_sideDialog_init' | 'kernel_driver_sideDialog_resume' | 'kernel_driver_fbr_sideDialog_round' | 'kernel_driver_type_a_askerDialog_call' | 'kernel_driver_supply_response_parent_revive';
 export type KernelDriverDriveOptions = Readonly<{
     suppressDiligencePush?: boolean;
     allowResumeFromInterrupted?: boolean;
-    noPromptSubdialogResumeEntitlement?: Readonly<{
+    noPromptSideDialogResumeEntitlement?: Readonly<{
         ownerDialogId: string;
-        reason: 'resolved_pending_subdialog_reply' | 'reply_tellask_back_delivered';
-        subdialogId?: string;
+        reason: 'reply_tellask_back_delivered';
+        sideDialogId?: string;
         callType?: 'A' | 'B' | 'C';
         callId?: string;
+    }> | Readonly<{
+        ownerDialogId: string;
+        reason: 'replaced_pending_sideDialog_reply';
+        sideDialogId?: string;
+        callType?: 'A' | 'B' | 'C';
+        callId?: string;
+    }> | Readonly<{
+        ownerDialogId: string;
+        reason: 'resolved_pending_sideDialog_reply';
+        sideDialogId?: string;
+        callType?: 'A' | 'B' | 'C';
+        callId?: string;
+        callSiteCourse: number;
+        callSiteGenseq: number;
+        resolvedCallIds?: readonly string[];
+        triggerCallId?: string;
     }>;
     runControl?: KernelDriverRunControl;
     source: KernelDriverDriveSource;
     reason: string;
 }>;
-export type KernelDriverSubdialogReplyTarget = {
+export type KernelDriverSideDialogReplyTarget = {
     ownerDialogId: string;
     callType: 'A' | 'B' | 'C';
     callId: string;
@@ -29,7 +45,7 @@ export type KernelDriverUserPrompt = KernelDriverPromptWithRunControl<DialogUser
 export type KernelDriverDiligencePrompt = KernelDriverPromptWithRunControl<DialogDiligencePrompt>;
 export type KernelDriverRuntimeGuidePrompt = KernelDriverPromptWithRunControl<DialogRuntimeGuidePrompt>;
 export type KernelDriverRuntimeReplyPrompt = KernelDriverPromptWithRunControl<DialogRuntimeReplyPrompt>;
-export type KernelDriverRuntimeSubdialogPrompt = KernelDriverPromptWithRunControl<DialogRuntimeSubdialogPrompt>;
+export type KernelDriverRuntimeSideDialogPrompt = KernelDriverPromptWithRunControl<DialogRuntimeSideDialogPrompt>;
 export type KernelDriverRuntimePrompt = KernelDriverPromptWithRunControl<DialogRuntimePrompt>;
 export type KernelDriverPrompt = KernelDriverPromptWithRunControl<DialogPrompt>;
 export type KernelDriverDriveCallOptions = Readonly<{
@@ -63,7 +79,7 @@ export type KernelDriverEmitSayingArgs = [dlg: Dialog, content: string];
 export type KernelDriverEmitSayingResult = Promise<void>;
 export type KernelDriverSupplyResponseArgs = [
     parentDialog: Dialog,
-    subdialogId: DialogID,
+    sideDialogId: DialogID,
     responseText: string,
     callType: 'A' | 'B' | 'C',
     callId?: string,
@@ -86,7 +102,7 @@ export type KernelDriverCoreResult = {
     lastAssistantSayingContent: string | null;
     lastAssistantSayingGenseq: number | null;
     lastFunctionCallGenseq: number | null;
-    lastAssistantReplyTarget?: KernelDriverSubdialogReplyTarget;
+    lastAssistantReplyTarget?: KernelDriverSideDialogReplyTarget;
     fbrConclusion?: {
         responseText: string;
         responseGenseq: number;

package/dist/mcp/config.d.ts

@@ -12,6 +12,7 @@ export type McpHeaderValue = {
 } | {
     kind: 'from_env';
     env: string;
+    prefix: string;
 };
 export type McpTransport = 'stdio' | 'streamable_http';
 type McpServerConfigBase = {
@@ -61,6 +62,7 @@ export type McpConfigLoadResult = {
     }>;
     serverIdsInYamlOrder: ReadonlyArray<string>;
     validServerIdsInYamlOrder: ReadonlyArray<string>;
+    disabledServerIdsInYamlOrder: ReadonlyArray<string>;
     rawText: string;
 } | {
     ok: false;

package/dist/mcp/config.js

@@ -26,6 +26,7 @@ function parseMcpYaml(rawText) {
             invalidServers: res.invalidServers,
             serverIdsInYamlOrder: res.serverIdsInYamlOrder,
             validServerIdsInYamlOrder: res.validServerIdsInYamlOrder,
+            disabledServerIdsInYamlOrder: res.disabledServerIdsInYamlOrder,
             rawText,
         };
     }
@@ -45,9 +46,14 @@ function parseWorkspaceConfig(value) {
     const invalidServers = [];
     const serverIdsInYamlOrder = [];
     const validServerIdsInYamlOrder = [];
+    const disabledServerIdsInYamlOrder = [];
     for (const [serverId, serverRaw] of Object.entries(serversRecord)) {
         serverIdsInYamlOrder.push(serverId);
         try {
+            if (isDisabledServerConfig(serverId, serverRaw)) {
+                disabledServerIdsInYamlOrder.push(serverId);
+                continue;
+            }
             servers[serverId] = parseServerConfig(serverId, serverRaw);
             validServerIdsInYamlOrder.push(serverId);
         }
@@ -63,8 +69,18 @@ function parseWorkspaceConfig(value) {
         invalidServers,
         serverIdsInYamlOrder,
         validServerIdsInYamlOrder,
+        disabledServerIdsInYamlOrder,
     };
 }
+function isDisabledServerConfig(serverId, value) {
+    const obj = asRecord(value, `servers.${serverId}`);
+    const enabled = obj.enabled;
+    if (enabled === undefined || enabled === true)
+        return false;
+    if (enabled === false)
+        return true;
+    throw new Error(`Invalid mcp.yaml: servers.${serverId}.enabled must be a boolean`);
+}
 function parseServerConfig(serverId, value) {
     const obj = asRecord(value, `servers.${serverId}`);
     const truelyStatelessVal = obj['truely-stateless'];
@@ -168,9 +184,14 @@ function parseServerConfig(serverId, value) {
         const mapped = asRecord(v, `servers.${serverId}.headers.${k}`);
         const fromEnv = mapped.env;
         if (typeof fromEnv !== 'string' || !fromEnv.trim()) {
-            throw new Error(`Invalid mcp.yaml: servers.${serverId}.headers.${k} must be a string or { env: 'NAME' }`);
+            throw new Error(`Invalid mcp.yaml: servers.${serverId}.headers.${k} must be a string, { env: 'NAME' }, or { prefix: 'Bearer ', env: 'NAME' }`);
+        }
+        const prefixVal = mapped.prefix;
+        if (prefixVal !== undefined && typeof prefixVal !== 'string') {
+            throw new Error(`Invalid mcp.yaml: servers.${serverId}.headers.${k}.prefix must be a string`);
         }
-        headers[k] = { kind: 'from_env', env: fromEnv };
+        const prefix = prefixVal ?? '';
+        headers[k] = { kind: 'from_env', env: fromEnv, prefix };
     }
     const sessionIdVal = obj.sessionId;
     const sessionId = sessionIdVal === undefined

package/dist/mcp/supervisor.d.ts

@@ -1,7 +1,8 @@
+import type { McpStreamableHttpServerConfig } from './config';
 export type McpDeclaredServerRuntimeStatus = Readonly<{
     serverId: string;
     transport: 'stdio' | 'streamable_http' | 'invalid' | 'unknown';
-    status: 'loaded' | 'temporarily_unavailable' | 'config_invalid';
+    status: 'loaded' | 'temporarily_unavailable' | 'config_invalid' | 'disabled';
     errorText?: string;
 }>;
 export declare function isMcpToolsetLeasedToDialog(serverId: string, dialogKey: string): boolean;
@@ -25,9 +26,16 @@ export declare function requestMcpServerRestart(serverId: string): Promise<{
     ok: false;
     errorText: string;
 }>;
+export declare function requestMcpServerDisable(serverId: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    errorText: string;
+}>;
 export declare function requestMcpConfigReload(reason?: string): Promise<{
     ok: true;
 } | {
     ok: false;
     errorText: string;
 }>;
+export declare function buildHttpHeaders(cfg: McpStreamableHttpServerConfig, serverId: string): Record<string, string>;

package/dist/mcp/supervisor.js

@@ -40,11 +40,14 @@ exports.getMcpDeclaredServerRuntimeStatuses = getMcpDeclaredServerRuntimeStatuse
 exports.startMcpSupervisor = startMcpSupervisor;
 exports.stopMcpSupervisor = stopMcpSupervisor;
 exports.requestMcpServerRestart = requestMcpServerRestart;
+exports.requestMcpServerDisable = requestMcpServerDisable;
 exports.requestMcpConfigReload = requestMcpConfigReload;
+exports.buildHttpHeaders = buildHttpHeaders;
 const time_1 = require("@longrun-ai/kernel/utils/time");
 const fs = __importStar(require("fs"));
 const node_crypto_1 = require("node:crypto");
 const path = __importStar(require("path"));
+const yaml_1 = __importStar(require("yaml"));
 const log_1 = require("../log");
 const persistence_1 = require("../persistence");
 const problems_1 = require("../problems");
@@ -150,6 +153,7 @@ class McpServerDispatch {
         for (const rt of this.leasesByDialogKey.values()) {
             rt.requestStop({ forceKillAfterMs: 3000 });
         }
+        this.leasesByDialogKey.clear();
         for (const [dialogKey, init] of this.leaseInitByDialogKey.entries()) {
             this.canceledLeaseDialogs.add(dialogKey);
             void init
@@ -158,6 +162,7 @@ class McpServerDispatch {
                 // ignore
             });
         }
+        this.leaseInitByDialogKey.clear();
     }
     async callToolForDialog(dlg, mcpToolName, args) {
         const serverId = this.serverId;
@@ -322,6 +327,13 @@ function getMcpDeclaredServerRuntimeStatuses() {
                 errorText: catalogEntry.configErrorText,
             };
         }
+        if (catalogEntry?.disabled) {
+            return {
+                serverId,
+                transport: catalogEntry.transport,
+                status: 'disabled',
+            };
+        }
         if (serverStateById.has(serverId)) {
             return {
                 serverId,
@@ -434,6 +446,27 @@ function requestMcpServerRestart(serverId) {
         });
     });
 }
+function requestMcpServerDisable(serverId) {
+    return new Promise((resolve) => {
+        reloadChain = reloadChain
+            .then(async () => {
+            try {
+                const res = await disableServerNow(serverId);
+                resolve(res);
+            }
+            catch (err) {
+                const errorText = err instanceof Error ? err.message : String(err);
+                log.warn(`MCP server disable failed`, err, { serverId });
+                resolve({ ok: false, errorText });
+            }
+        })
+            .catch((err) => {
+            const errorText = err instanceof Error ? err.message : String(err);
+            log.warn(`MCP server disable enqueue failed`, err, { serverId });
+            resolve({ ok: false, errorText });
+        });
+    });
+}
 function requestMcpConfigReload(reason = 'manual') {
     const normalizedReason = reason.trim() === '' ? 'manual' : reason.trim();
     return new Promise((resolve) => {
@@ -553,7 +586,7 @@ async function reloadNow(reason) {
         const code = isRecord(err) && 'code' in err ? err.code : undefined;
         if (code === 'ENOENT') {
             // Deletion is treated as empty config.
-            await applyWorkspaceConfig({ version: 1, servers: {} }, [], [], [], `missing file (${reason})`);
+            await applyWorkspaceConfig({ version: 1, servers: {} }, [], [], [], [], null, `missing file (${reason})`);
             clearWorkspaceConfigProblem();
             await reconcileMcpManualProblemsForRuntime([], null);
             return;
@@ -571,10 +604,19 @@ async function reloadNow(reason) {
         return;
     }
     clearWorkspaceConfigProblem();
-    await applyWorkspaceConfig(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder, parsed.validServerIdsInYamlOrder, reason);
+    await applyWorkspaceConfig(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder, parsed.validServerIdsInYamlOrder, parsed.disabledServerIdsInYamlOrder, rawText, reason);
     await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, rawText);
 }
 async function restartServerNow(serverId) {
+    let removedPlaceholder = false;
+    const notifyPlaceholderRemovalOnFailure = (trigger) => {
+        if (!removedPlaceholder)
+            return;
+        (0, tool_availability_updates_1.notifyToolAvailabilityRegistryMaybeChanged)({
+            reason: 'registry_changed',
+            trigger,
+        });
+    };
     let rawText;
     try {
         rawText = await fs.promises.readFile(MCP_YAML_PATH, 'utf8');
@@ -591,23 +633,51 @@ async function restartServerNow(serverId) {
         upsertWorkspaceConfigProblem(`Failed to read ${MCP_YAML_PATH}: ${String(err)}`);
         return { ok: false, errorText: `Failed to read ${MCP_YAML_PATH}: ${String(err)}` };
     }
-    const parsed = (0, config_1.parseMcpYaml)(rawText);
+    let activeRawText = rawText;
+    let parsed = (0, config_1.parseMcpYaml)(activeRawText);
     if (!parsed.ok) {
         await reconcileMcpManualProblemsForRuntime([], null);
         upsertWorkspaceConfigProblem(parsed.errorText);
         return { ok: false, errorText: parsed.errorText };
     }
     clearWorkspaceConfigProblem();
+    const disabledServer = parsed.serverIdsInYamlOrder.includes(serverId) &&
+        parsed.invalidServers.every((s) => s.serverId !== serverId) &&
+        parsed.config.servers[serverId] === undefined;
+    if (disabledServer) {
+        const enableRes = setServerEnabledInMcpYaml(rawText, serverId, true);
+        if (!enableRes.ok) {
+            await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, rawText);
+            return { ok: false, errorText: enableRes.errorText };
+        }
+        if (enableRes.changed) {
+            await fs.promises.writeFile(MCP_YAML_PATH, enableRes.rawText, 'utf8');
+            lastSeenMcpYamlSig = await readMcpYamlSig();
+            removedPlaceholder = unregisterMcpToolsetPlaceholder(serverId) || removedPlaceholder;
+        }
+        activeRawText = enableRes.rawText;
+        parsed = (0, config_1.parseMcpYaml)(activeRawText);
+        if (!parsed.ok) {
+            clearDeclaredServerRuntimeCatalog();
+            await reconcileMcpManualProblemsForRuntime([], null);
+            upsertWorkspaceConfigProblem(parsed.errorText);
+            notifyPlaceholderRemovalOnFailure(`mcp:restart:${serverId}:parse-failed`);
+            return { ok: false, errorText: parsed.errorText };
+        }
+        clearWorkspaceConfigProblem();
+    }
     const invalid = parsed.invalidServers.find((s) => s.serverId === serverId);
     if (invalid) {
-        replaceDeclaredServerRuntimeCatalog(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder);
-        await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, rawText);
+        replaceDeclaredServerRuntimeCatalog(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder, parsed.disabledServerIdsInYamlOrder);
+        await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, activeRawText);
         upsertMcpServerConfigInvalidProblem(serverId, invalid.errorText);
+        notifyPlaceholderRemovalOnFailure(`mcp:restart:${serverId}:config-invalid`);
         return { ok: false, errorText: invalid.errorText };
     }
     const serverCfg = parsed.config.servers[serverId];
     if (!serverCfg) {
-        await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, rawText);
+        await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, activeRawText);
+        notifyPlaceholderRemovalOnFailure(`mcp:restart:${serverId}:not-configured`);
         return {
             ok: false,
             errorText: `MCP server '${serverId}' is not configured in ${MCP_YAML_PATH}`,
@@ -617,25 +687,28 @@ async function restartServerNow(serverId) {
     const fingerprint = fingerprintServerConfig(serverCfg);
     const existing = serverStateById.get(serverId);
     const runtimeLeaseChanged = existing !== undefined;
-    replaceDeclaredServerRuntimeCatalog(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder);
+    replaceDeclaredServerRuntimeCatalog(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder, parsed.disabledServerIdsInYamlOrder);
+    if (!existing) {
+        removedPlaceholder = unregisterMcpToolsetPlaceholder(serverId) || removedPlaceholder;
+    }
     const res = await tryBuildServerState(serverCfg, desiredToolsetName, fingerprint);
     if (!res.ok) {
-        await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, rawText);
+        await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, activeRawText);
         upsertDeclaredServerRuntimeError(serverId, res.errorText);
         upsertMcpServerRuntimeUnavailableProblem(serverId, res.errorText, res.detailTextI18n);
+        notifyPlaceholderRemovalOnFailure(`mcp:restart:${serverId}:runtime-unavailable`);
         return { ok: false, errorText: res.errorText };
     }
     clearDeclaredServerRuntimeError(serverId);
     (0, problems_1.removeProblemsByPrefix)(`${problemPrefixForServer(serverId)}server_error`);
     if (existing) {
-        unregisterServer(existing);
-        existing.dispatch.requestStop();
+        stopLoadedServer(serverId);
     }
     registerServer(res.state);
     serverStateById.set(serverId, res.state);
     (0, problems_1.reconcileProblemsByPrefix)(problemPrefixForServer(serverId), res.state.problems);
     reorderMcpToolsetsInRegistry(parsed.serverIdsInYamlOrder);
-    await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, rawText);
+    await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, activeRawText);
     (0, tool_availability_updates_1.notifyToolAvailabilityRegistryMaybeChanged)({
         reason: 'registry_changed',
         trigger: `mcp:restart:${serverId}`,
@@ -645,6 +718,119 @@ async function restartServerNow(serverId) {
     }
     return { ok: true };
 }
+async function disableServerNow(serverId) {
+    const stoppedExisting = stopLoadedServer(serverId);
+    let rawText;
+    try {
+        rawText = await fs.promises.readFile(MCP_YAML_PATH, 'utf8');
+    }
+    catch (err) {
+        const code = isRecord(err) && 'code' in err ? err.code : undefined;
+        if (stoppedExisting) {
+            (0, tool_availability_updates_1.notifyToolAvailabilityRegistryMaybeChanged)({
+                reason: 'registry_changed',
+                trigger: `mcp:disable:${serverId}:read-failed`,
+            });
+            (0, tool_availability_updates_1.notifyToolAvailabilityRuntimeLeaseChanged)(`mcp:disable:${serverId}:read-failed`);
+        }
+        if (code === 'ENOENT') {
+            return { ok: false, errorText: `Cannot disable '${serverId}': ${MCP_YAML_PATH} is missing` };
+        }
+        return { ok: false, errorText: `Failed to read ${MCP_YAML_PATH}: ${String(err)}` };
+    }
+    const disableRes = setServerEnabledInMcpYaml(rawText, serverId, false);
+    if (!disableRes.ok) {
+        if (stoppedExisting) {
+            (0, tool_availability_updates_1.notifyToolAvailabilityRegistryMaybeChanged)({
+                reason: 'registry_changed',
+                trigger: `mcp:disable:${serverId}:disable-failed`,
+            });
+            (0, tool_availability_updates_1.notifyToolAvailabilityRuntimeLeaseChanged)(`mcp:disable:${serverId}:disable-failed`);
+        }
+        return { ok: false, errorText: disableRes.errorText };
+    }
+    if (disableRes.changed) {
+        await fs.promises.writeFile(MCP_YAML_PATH, disableRes.rawText, 'utf8');
+        lastSeenMcpYamlSig = await readMcpYamlSig();
+    }
+    const parsed = (0, config_1.parseMcpYaml)(disableRes.rawText);
+    if (!parsed.ok) {
+        clearDeclaredServerRuntimeCatalog();
+        await reconcileMcpManualProblemsForRuntime([], null);
+        upsertWorkspaceConfigProblem(parsed.errorText);
+        if (stoppedExisting) {
+            (0, tool_availability_updates_1.notifyToolAvailabilityRegistryMaybeChanged)({
+                reason: 'registry_changed',
+                trigger: `mcp:disable:${serverId}:parse-failed`,
+            });
+            (0, tool_availability_updates_1.notifyToolAvailabilityRuntimeLeaseChanged)(`mcp:disable:${serverId}:parse-failed`);
+        }
+        return { ok: false, errorText: parsed.errorText };
+    }
+    clearWorkspaceConfigProblem();
+    await applyWorkspaceConfig(parsed.config, parsed.invalidServers, parsed.serverIdsInYamlOrder, parsed.validServerIdsInYamlOrder, parsed.disabledServerIdsInYamlOrder, disableRes.rawText, `mcp_disable:${serverId}`);
+    await reconcileMcpManualProblemsForRuntime(parsed.serverIdsInYamlOrder, disableRes.rawText);
+    if (stoppedExisting) {
+        (0, tool_availability_updates_1.notifyToolAvailabilityRuntimeLeaseChanged)(`mcp:disable:${serverId}`);
+    }
+    return { ok: true };
+}
+function setServerEnabledInMcpYaml(rawText, serverId, enabled) {
+    const doc = yaml_1.default.parseDocument(rawText, { prettyErrors: true });
+    if (doc.errors.length > 0) {
+        return { ok: false, errorText: doc.errors.map((e) => String(e)).join('\n') };
+    }
+    const parsed = doc.toJS();
+    if (!isRecord(parsed)) {
+        return { ok: false, errorText: `Invalid mcp.yaml: expected object at mcp.yaml root` };
+    }
+    if (parsed.version !== 1) {
+        return { ok: false, errorText: `Invalid mcp.yaml: expected version: 1` };
+    }
+    const servers = parsed.servers;
+    const server = isRecord(servers) ? servers[serverId] : undefined;
+    if (!isRecord(server)) {
+        return {
+            ok: false,
+            errorText: `MCP server '${serverId}' is not configured in ${MCP_YAML_PATH}`,
+        };
+    }
+    const currentEnabled = server.enabled;
+    if (currentEnabled !== undefined && typeof currentEnabled !== 'boolean') {
+        return {
+            ok: false,
+            errorText: `Invalid mcp.yaml: servers.${serverId}.enabled must be a boolean`,
+        };
+    }
+    if (currentEnabled === enabled) {
+        return { ok: true, rawText, changed: false };
+    }
+    const serverNode = doc.getIn(['servers', serverId], true);
+    if (!(0, yaml_1.isMap)(serverNode)) {
+        return {
+            ok: false,
+            errorText: `Invalid mcp.yaml: servers.${serverId} must be an object`,
+        };
+    }
+    const existingEnabledPair = serverNode.items.find((pair) => (0, yaml_1.isScalar)(pair.key) && pair.key.value === 'enabled');
+    if (existingEnabledPair) {
+        existingEnabledPair.value = doc.createNode(enabled);
+    }
+    else {
+        serverNode.items.unshift(doc.createPair('enabled', enabled));
+    }
+    return { ok: true, rawText: String(doc), changed: true };
+}
+function stopLoadedServer(serverId) {
+    const existing = serverStateById.get(serverId);
+    if (!existing)
+        return false;
+    unregisterServer(existing);
+    existing.dispatch.requestStop();
+    serverStateById.delete(serverId);
+    (0, problems_1.reconcileProblemsByPrefix)(problemPrefixForServer(serverId), []);
+    return true;
+}
 async function reconcileMcpManualProblemsForRuntime(serverIdsInYamlOrder, rawText) {
     const manualInfo = rawText === null ? (0, manual_problems_1.emptyMcpToolsetManualByServer)() : (0, manual_problems_1.parseMcpManualByServer)(rawText);
     await (0, manual_problems_1.reconcileMcpToolsetManualProblems)({
@@ -710,13 +896,15 @@ function upsertMcpToolCallProblem(args) {
     const hintLines = workLanguage === 'zh'
         ? [
             '建议排查：',
-            `- 先释放租约：mcp_release({"serverId":"${args.serverId}"})`,
+            `- 如果需要全局重建该 MCP server，直接调用 mcp_restart({"serverId":"${args.serverId}"})；它成功后会清理旧 runtime 的全部 lease`,
+            `- 如果只想丢弃当前对话的连接，再调用 mcp_release({"serverId":"${args.serverId}"})`,
             `- 重新打开/关闭浏览器窗口，避免 Playwright persistent context 残留`,
             `- 查看 ${MCP_YAML_PATH} 是否已加载且配置正确（Problems 面板 / 后端日志）`,
         ]
         : [
             'Suggested checks:',
-            `- Release the lease first: mcp_release({"serverId":"${args.serverId}"})`,
+            `- To rebuild this MCP server globally, call mcp_restart({"serverId":"${args.serverId}"}) directly; a successful restart clears all leases on the old runtime`,
+            `- To discard only this dialog's connection, call mcp_release({"serverId":"${args.serverId}"})`,
             `- Close/reopen browser windows to avoid leftover Playwright persistent contexts`,
             `- Verify ${MCP_YAML_PATH} is loaded and valid (Problems panel / backend logs)`,
         ];
@@ -745,12 +933,13 @@ function upsertMcpToolCallProblem(args) {
 function clearMcpToolCallProblem(serverId) {
     (0, problems_1.removeProblemsByPrefix)(`${MCP_TOOL_CALL_PROBLEM_PREFIX}${sanitizePathSegment(serverId)}`);
 }
-async function applyWorkspaceConfig(config, invalidServers, serverIdsInYamlOrder, validServerIdsInYamlOrder, reason) {
+async function applyWorkspaceConfig(config, invalidServers, serverIdsInYamlOrder, validServerIdsInYamlOrder, disabledServerIdsInYamlOrder, rawText, reason) {
     log.info(`Applying MCP rtws config (${reason})`);
-    replaceDeclaredServerRuntimeCatalog(config, invalidServers, serverIdsInYamlOrder);
+    replaceDeclaredServerRuntimeCatalog(config, invalidServers, serverIdsInYamlOrder, disabledServerIdsInYamlOrder);
     let runtimeLeaseChanged = false;
     const invalidIds = new Set(invalidServers.map((s) => s.serverId));
     const desiredIds = new Set([...Object.keys(config.servers), ...invalidIds]);
+    const declaredIds = new Set(serverIdsInYamlOrder);
     // Remove deleted servers first.
     for (const [serverId, state] of serverStateById.entries()) {
         if (desiredIds.has(serverId))
@@ -761,8 +950,18 @@ async function applyWorkspaceConfig(config, invalidServers, serverIdsInYamlOrder
         serverStateById.delete(serverId);
         (0, problems_1.reconcileProblemsByPrefix)(problemPrefixForServer(serverId), []);
     }
+    // Remove disabled/deleted MCP placeholders that are no longer declared.
+    for (const [toolsetName, owner] of Array.from(toolsetOwnerByName.entries())) {
+        if (owner.kind !== 'mcp')
+            continue;
+        if (declaredIds.has(owner.serverId))
+            continue;
+        (0, registry_1.unregisterToolset)(toolsetName);
+        toolsetOwnerByName.delete(toolsetName);
+    }
     // Surface invalid server config errors (while keeping last-known-good runtimes registered).
     for (const s of invalidServers) {
+        unregisterMcpToolsetPlaceholder(s.serverId);
         upsertMcpServerConfigInvalidProblem(s.serverId, s.errorText);
     }
     // Apply desired servers independently (deterministic order).
@@ -774,6 +973,9 @@ async function applyWorkspaceConfig(config, invalidServers, serverIdsInYamlOrder
         const fingerprint = fingerprintServerConfig(serverCfg);
         const existing = serverStateById.get(serverId);
         if (!existing || existing.configFingerprint !== fingerprint) {
+            if (!existing) {
+                unregisterMcpToolsetPlaceholder(serverId);
+            }
             const res = await tryBuildServerState(serverCfg, desiredToolsetName, fingerprint);
             if (!res.ok) {
                 upsertDeclaredServerRuntimeError(serverId, res.errorText);
@@ -826,6 +1028,11 @@ async function applyWorkspaceConfig(config, invalidServers, serverIdsInYamlOrder
         if (!changed)
             break;
     }
+    const manualInfo = rawText === null ? (0, manual_problems_1.emptyMcpToolsetManualByServer)() : (0, manual_problems_1.parseMcpManualByServer)(rawText);
+    for (const serverId of disabledServerIdsInYamlOrder) {
+        (0, problems_1.reconcileProblemsByPrefix)(problemPrefixForServer(serverId), []);
+        registerDisabledServerToolset(serverId, manualInfo);
+    }
     reorderMcpToolsetsInRegistry(serverIdsInYamlOrder);
     (0, tool_availability_updates_1.notifyToolAvailabilityRegistryMaybeChanged)({
         reason: 'registry_changed',
@@ -848,7 +1055,7 @@ function clearDeclaredServerRuntimeCatalog() {
     declaredServerIdsInYamlOrder = [];
     declaredServerRuntimeCatalogById.clear();
 }
-function replaceDeclaredServerRuntimeCatalog(config, invalidServers, serverIdsInYamlOrder) {
+function replaceDeclaredServerRuntimeCatalog(config, invalidServers, serverIdsInYamlOrder, disabledServerIdsInYamlOrder) {
     const previousRuntimeErrors = new Map();
     for (const [serverId, entry] of declaredServerRuntimeCatalogById.entries()) {
         if (typeof entry.runtimeErrorText === 'string' && entry.runtimeErrorText.trim() !== '') {
@@ -857,7 +1064,15 @@ function replaceDeclaredServerRuntimeCatalog(config, invalidServers, serverIdsIn
     }
     declaredServerIdsInYamlOrder = [...serverIdsInYamlOrder];
     declaredServerRuntimeCatalogById.clear();
+    const disabledIds = new Set(disabledServerIdsInYamlOrder);
     for (const serverId of serverIdsInYamlOrder) {
+        if (disabledIds.has(serverId)) {
+            declaredServerRuntimeCatalogById.set(serverId, {
+                transport: 'unknown',
+                disabled: true,
+            });
+            continue;
+        }
         const cfg = config.servers[serverId];
         if (!cfg)
             continue;
@@ -944,6 +1159,74 @@ function registerServer(state) {
     });
     toolsetOwnerByName.set(state.toolsetName, { kind: 'mcp', serverId: state.serverId });
 }
+function registerDisabledServerToolset(serverId, manualInfo) {
+    const existingToolset = registry_1.toolsetsRegistry.get(serverId);
+    const existingOwner = toolsetOwnerByName.get(serverId);
+    if (existingToolset && (!existingOwner || existingOwner.serverId !== serverId)) {
+        upsertMcpServerConfigInvalidProblem(serverId, `Toolset name collision: ${serverId}`);
+        return;
+    }
+    (0, registry_1.registerToolset)(serverId, []);
+    const manual = manualInfo.manualByServerId.get(serverId);
+    const manualSpec = manual?.contentFile
+        ? (0, spec_1.buildMcpManualSpec)(manual.contentFile)
+        : {
+            topics: ['index'],
+            warnOnMissing: false,
+            includeSchemaToolsSection: false,
+        };
+    const inlineManual = manual ? renderInlineMcpToolsetManual(manual) : '';
+    const disabledNoticeEn = [
+        `This MCP server is configured but disabled in \`.minds/mcp.yaml\` (\`enabled: false\`).`,
+        `It intentionally exposes zero tools until an MCP administrator enables it with \`mcp_restart({"serverId":"${serverId}"})\`.`,
+        inlineManual,
+    ]
+        .filter((part) => part.trim() !== '')
+        .join('\n\n');
+    const disabledNoticeZh = [
+        `该 MCP server 已在 \`.minds/mcp.yaml\` 中配置，但当前为禁用状态（\`enabled: false\`）。`,
+        `它会刻意暴露为 0 工具的 toolset；需要 MCP 排障/管理员用 \`mcp_restart({"serverId":"${serverId}"})\` 启用后才会加载工具。`,
+        inlineManual,
+    ]
+        .filter((part) => part.trim() !== '')
+        .join('\n\n');
+    (0, registry_1.setToolsetMeta)(serverId, {
+        source: 'mcp',
+        descriptionI18n: {
+            en: `MCP server: ${serverId} (disabled)`,
+            zh: `MCP 服务器：${serverId}（已禁用）`,
+        },
+        manualNoticeI18n: {
+            en: disabledNoticeEn,
+            zh: disabledNoticeZh,
+        },
+        ...(manualSpec !== undefined ? { manualSpec } : {}),
+    });
+    toolsetOwnerByName.set(serverId, { kind: 'mcp', serverId });
+}
+function renderInlineMcpToolsetManual(manual) {
+    const parts = [];
+    if (manual.content) {
+        parts.push(manual.content);
+    }
+    for (const section of manual.sections) {
+        parts.push(`#### ${section.title}\n\n${section.content}`);
+    }
+    return parts.join('\n\n');
+}
+function unregisterMcpToolsetPlaceholder(serverId) {
+    if (serverStateById.has(serverId))
+        return false;
+    const owner = toolsetOwnerByName.get(serverId);
+    if (owner?.kind !== 'mcp' || owner.serverId !== serverId)
+        return false;
+    const tools = registry_1.toolsetsRegistry.get(serverId);
+    if (tools && tools.length > 0)
+        return false;
+    (0, registry_1.unregisterToolset)(serverId);
+    toolsetOwnerByName.delete(serverId);
+    return true;
+}
 function unregisterServer(state) {
     // Unregister toolset first so Team.Member.listTools doesn't resolve stale tools.
     if (toolsetOwnerByName.get(state.toolsetName)?.serverId === state.serverId) {
@@ -1417,7 +1700,7 @@ function buildHttpHeaders(cfg, serverId) {
                 if (val === undefined) {
                     throw new Error(`MCP server '${serverId}' missing required host env var '${v.env}' (for headers.${k})`);
                 }
-                headers[k] = val;
+                headers[k] = `${v.prefix}${val}`;
                 break;
             }
             default: {