dsh-agent-plugins-market 0.8.0 → 0.8.2

package/lib/application/agent-roles.js

@@ -0,0 +1,53 @@
+/**
+ * Agent-role card parsing: the frontmatter grammar and the policy it yields.
+ * Pure text processing shared by the project-role projection and the runtime
+ * delegation router; the executing half stays in runtime.
+ * @module application/agent-roles
+ */
+import { parse as parseYaml } from 'yaml';
+function optionalText(value, key) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new Error(`agent metadata ${key} must be a non-empty string`);
+    return value.trim();
+}
+/** Strict YAML parsing prevents malformed routing metadata from silently inheriting wider privileges. */
+export function parseAgentRole(text) {
+    const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+    if (match === null) {
+        if (/^(?:\uFEFF)?---(?:\r?\n|$)/.test(text))
+            throw new Error('agent frontmatter is not closed');
+        return { content: text, disabled: false };
+    }
+    // A matched block always carries its body; the check keeps the type honest.
+    const frontmatter = match[1];
+    if (frontmatter === undefined)
+        throw new Error('agent frontmatter is not closed');
+    const parsed = parseYaml(frontmatter);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('agent frontmatter must be a YAML object');
+    const metadata = parsed;
+    if (metadata.disabled !== undefined && typeof metadata.disabled !== 'boolean')
+        throw new Error('agent metadata disabled must be a boolean');
+    const model = optionalText(metadata.model, 'model');
+    const provider = optionalText(metadata.provider, 'provider');
+    const effort = optionalText(metadata.reasoning_effort, 'reasoning_effort');
+    const camelEffort = optionalText(metadata.reasoningEffort, 'reasoningEffort');
+    if (effort !== undefined && camelEffort !== undefined && effort !== camelEffort)
+        throw new Error('agent metadata reasoning_effort and reasoningEffort conflict');
+    const reasoningEffort = effort ?? camelEffort;
+    const title = optionalText(metadata.name, 'name');
+    const description = optionalText(metadata.description, 'description');
+    if (model === 'inherit' && provider !== undefined)
+        throw new Error('agent model inherit cannot specify a provider');
+    return {
+        content: text.slice(match[0].length),
+        disabled: metadata.disabled === true,
+        ...(model === undefined || model === 'inherit' ? {} : { model }),
+        ...(provider === undefined ? {} : { provider }),
+        ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+        ...(title === undefined ? {} : { title }),
+        ...(description === undefined ? {} : { description })
+    };
+}

package/lib/application/catalog-context.js

@@ -10,8 +10,8 @@
 import { join } from 'node:path';
 import { MARKET_SETTINGS_DEFAULTS } from '../contracts/settings.js';
 import { STATE_FILE_NAME } from '../catalog/paths.js';
-import { settlesWithin } from '../runtime/deadline.js';
-import { EMPTY_STATE, loadState, saveState } from '../runtime/state-store.js';
+import { settlesWithin } from './deadline.js';
+import { EMPTY_STATE, loadState, saveState } from './state/state-store.js';
 import { effectiveSurfaces } from '../model/types.js';
 import { SCAN_CACHE_TTL_MS, SnapshotCache } from './snapshot-cache.js';
 /** Key of one install entry in the persisted `installed` record. */

package/lib/application/catalog.js

@@ -10,10 +10,10 @@
  * know which collaborator owns a given invariant.
  */
 import { qualifiedSuiteId } from '../catalog/paths.js';
-import { loadUserMcpSuite } from '../runtime/mcp-direct-config.js';
-import { loadSuiteOverrides } from '../runtime/mcp-overrides.js';
-import { loadUserHooksSuite } from '../runtime/user-hooks.js';
-import { applyLspOverrides } from '../runtime/server-config.js';
+import { loadUserMcpSuite } from './mcp/mcp-direct-config.js';
+import { loadSuiteOverrides } from './mcp/mcp-overrides.js';
+import { loadUserHooksSuite } from './panels/user-hooks.js';
+import { applyLspOverrides } from './server-config.js';
 import { buildSuiteDetail, readSkillContent } from './details.js';
 import { CatalogContext } from './catalog-context.js';
 import { InstallStore } from './install-store.js';
@@ -233,10 +233,6 @@ export class Catalog {
     async addMcpServer(name, server) {
         await this.mcp.addServer(name, server);
     }
-    /** Import several pasted services in one write; each entry reports its own outcome. */
-    async importMcpServers(servers, overwrite) {
-        return this.mcp.importServers(servers, overwrite);
-    }
     /** Read effective service configuration without exposing credential literals. */
     async serverConfig(kind, id) {
         return this.mcp.serverConfig(kind, id);

package/lib/{runtime → application}/deadline.js

@@ -11,7 +11,7 @@
  * only notifies. This module adds the one thing that primitive does not answer
  * and these callers need: whether the work settled at all.
  *
- * @module runtime/deadline
+ * @module application/deadline
  */
 import { deadline } from '@deepseek-ai/dsh-timeout';
 /** Identifies this plugin's bounded waits inside a timeout reason. */

package/lib/application/details.js

@@ -3,9 +3,9 @@ import { readFile, stat } from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import { discoverLspEntries } from '../catalog/surfaces.js';
 import { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
-import { credentialRefsInServer } from '../runtime/mcp-config.js';
-import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
-import { applyOverride } from '../runtime/mcp-overrides.js';
+import { credentialRefsInServer } from './mcp/mcp-config.js';
+import { redactMcpConfig, redactMcpOverrides } from './mcp/mcp-redaction.js';
+import { applyOverride } from './mcp/mcp-overrides.js';
 import { effectiveSurfaces } from '../model/types.js';
 /** The checkout's last modification, or null when the path cannot be read. */
 async function rootModifiedAt(root) {

package/lib/application/json-file.js

@@ -0,0 +1,43 @@
+/**
+ * The one JSON persistence loop every plugin-owned document runs: read with
+ * ENOENT tolerance, validate through a caller hook, and write back through the
+ * harness atomic-write helper with the private-file modes. Files here are
+ * plugin state under `$DSH_HOME`, written by the host process only; a caller
+ * needing shared or user-authored content keeps its own rules.
+ *
+ * The read resolves `undefined` when the file does not exist or parses to
+ * nothing usable, and rethrows anything else — a permission problem must
+ * surface, not read as an empty document. What counts as usable is the
+ * caller's `parse`: it receives the parsed value and returns the typed
+ * document, so each store keeps its own tolerance policy (fail-closed to a
+ * default, or reject) instead of sharing one.
+ * @module application/json-file
+ */
+import { readFile } from 'node:fs/promises';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+/**
+ * Read one JSON document. Resolves `undefined` when the file is absent or its
+ * text is empty; a `parse` that wants an absent file to read as a default
+ * handles `undefined` itself.
+ */
+export async function readJsonFile(path) {
+    try {
+        const text = await readFile(path, 'utf8');
+        if (text.trim() === '')
+            return undefined;
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Write one JSON document atomically: two-space indent, trailing newline, and
+ * the private-file modes the plugin's state files carry (0o600 file, 0o700
+ * directory).
+ */
+export async function writeJsonDocument(path, document) {
+    await writeFileAtomic(path, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+}

package/lib/{runtime → application/lsp}/lsp-direct-config.js

@@ -8,10 +8,9 @@
  * `lsp-spec` rules as suite declarations; a broken file degrades to no direct
  * servers plus a diagnostic, never a thrown discovery.
  */
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-import { parseLspServers } from '../catalog/lsp-spec.js';
+import { readJsonFile, writeJsonDocument } from '../json-file.js';
+import { parseLspServers } from '../../catalog/lsp-spec.js';
 /** The direct LSP server configuration file path. */
 export function lspServersPath(agentsRoot) {
     return join(agentsRoot, 'lsp.json');
@@ -20,11 +19,15 @@ export function lspServersPath(agentsRoot) {
 export async function loadLspServers(agentsRoot) {
     let raw;
     try {
-        raw = JSON.parse(await readFile(lspServersPath(agentsRoot), 'utf8'));
+        raw = await readJsonFile(lspServersPath(agentsRoot));
     }
     catch (error) {
-        return { servers: {}, errors: error.code === 'ENOENT' ? [] : [`lsp.json: ${error instanceof Error ? error.message : String(error)}`] };
+        return { servers: {}, errors: [`lsp.json: ${error instanceof Error ? error.message : String(error)}`] };
     }
+    // An absent file is an empty table, not a broken one; only a present file
+    // with a wrong shape carries a diagnostic.
+    if (raw === undefined)
+        return { servers: {}, errors: [] };
     const errors = [];
     const table = raw?.['lspServers'];
     if (table === undefined || table === null || Array.isArray(table) || typeof table !== 'object')
@@ -40,8 +43,7 @@ export async function saveLspServers(agentsRoot, raw) {
     if (errors.length > 0) {
         throw new Error(`invalid lspServers: ${errors[0]}`);
     }
-    const path = lspServersPath(agentsRoot);
     const persisted = Object.fromEntries(Object.entries(servers).map(([name, { key: _key, ...config }]) => [name, config]));
-    await writeFileAtomic(path, `${JSON.stringify({ lspServers: persisted }, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+    await writeJsonDocument(lspServersPath(agentsRoot), { lspServers: persisted });
     return { servers };
 }

package/lib/application/lsp/lsp-server-state.js

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { readJsonFile, writeJsonDocument } from '../json-file.js';
+export function lspServerStatePath(dataRoot) {
+    return join(dataRoot, 'lsp-server-state.json');
+}
+export async function loadDisabledLspServers(dataRoot) {
+    try {
+        const value = (await readJsonFile(lspServerStatePath(dataRoot)));
+        return new Set(Array.isArray(value?.disabled) ? value.disabled.filter((id) => typeof id === 'string') : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+export async function saveDisabledLspServers(dataRoot, disabled) {
+    await writeJsonDocument(lspServerStatePath(dataRoot), { disabled: [...new Set(disabled)].sort() });
+}

package/lib/{runtime → application/lsp}/lsp-status.js

@@ -1,6 +1,16 @@
-import { qualifiedSuiteId } from '../catalog/paths.js';
+import { qualifiedSuiteId } from '../../catalog/paths.js';
 /** Sentinel suite id for user-configured (non-suite) LSP servers. */
 export const DIRECT_LSP_SUITE_ID = 'direct';
+/** The fields one diagnostic contributes to its status row. */
+function diagnosticReport(diagnostic) {
+    if (diagnostic === undefined)
+        return {};
+    return {
+        reason: diagnostic.reason,
+        ...(diagnostic.code === undefined ? {} : { code: diagnostic.code }),
+        ...(diagnostic.causes === undefined ? {} : { causes: diagnostic.causes })
+    };
+}
 /**
  * Derive one row's state from its suite's diagnostic and the live-mount flag.
  * Shared by suite rows and direct rows so both kinds report identically.
@@ -8,15 +18,16 @@ export const DIRECT_LSP_SUITE_ID = 'direct';
 function deriveState(disabled, diagnostic, anyLive) {
     if (disabled)
         return { state: 'disabled' };
+    const reported = diagnosticReport(diagnostic);
     if (diagnostic?.code === 'host-missing')
-        return { state: 'host-missing', reason: diagnostic.reason };
+        return { state: 'host-missing', ...reported };
     if (diagnostic?.code === 'seam-conflict')
-        return { state: 'conflict', reason: diagnostic.reason };
+        return { state: 'conflict', ...reported };
     if (diagnostic?.code === 'mount-failed' || diagnostic?.code === 'unmount-failed') {
-        return { state: 'failed', reason: diagnostic.reason, retryable: true };
+        return { state: 'failed', ...reported, retryable: true };
     }
     if (diagnostic !== undefined)
-        return { state: 'failed', reason: diagnostic.reason };
+        return { state: 'failed', ...reported };
     if (anyLive)
         return { state: 'mounted' };
     // A declaration with neither a diagnostic nor a live mount is mid-flight:
@@ -42,7 +53,7 @@ export function buildLspStatus(suites, registry, direct = { servers: {}, errors:
         const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
         const disabled = suite.activeSurfaces.lsp === false;
         const diagnostic = diagnostics.get(suiteKey);
-        const { state, reason, retryable } = deriveState(disabled, diagnostic, anyLive);
+        const { state, reason, code, causes, retryable } = deriveState(disabled, diagnostic, anyLive);
         if (state === 'mounted')
             mountedSuiteIds.add(suiteKey);
         for (const spec of Object.values(suite.lsp.servers)) {
@@ -58,6 +69,8 @@ export function buildLspStatus(suites, registry, direct = { servers: {}, errors:
                 extensions: spec.extensionToLanguage,
                 state: disabled || disabledServers.has(`${suiteKey}/${spec.key}`) ? 'disabled' : state,
                 ...(reason === undefined ? {} : { reason }),
+                ...(code === undefined ? {} : { code }),
+                ...(causes === undefined ? {} : { causes }),
                 ...(retryable === undefined ? {} : { retryable })
             });
         }
@@ -65,7 +78,7 @@ export function buildLspStatus(suites, registry, direct = { servers: {}, errors:
     // Direct user-configured rows: no install state or surface toggle of their
     // own — configured means on; the mount diagnostic decides the state.
     const directDiagnostic = diagnostics.get(DIRECT_LSP_SUITE_ID);
-    const { state: directState, reason: directReason, retryable: directRetryable } = deriveState(false, directDiagnostic, anyLive);
+    const { state: directState, reason: directReason, code: directCode, causes: directCauses, retryable: directRetryable } = deriveState(false, directDiagnostic, anyLive);
     if (directState === 'mounted')
         mountedSuiteIds.add(DIRECT_LSP_SUITE_ID);
     for (const spec of Object.values(direct.servers)) {
@@ -81,6 +94,8 @@ export function buildLspStatus(suites, registry, direct = { servers: {}, errors:
             extensions: spec.extensionToLanguage,
             state: disabledServers.has(`${DIRECT_LSP_SUITE_ID}/${spec.key}`) ? 'disabled' : directState,
             ...(directReason === undefined ? {} : { reason: directReason }),
+            ...(directCode === undefined ? {} : { code: directCode }),
+            ...(directCauses === undefined ? {} : { causes: directCauses }),
             ...(directRetryable === undefined ? {} : { retryable: directRetryable })
         });
     }

package/lib/{runtime → application/lsp}/profile-seam.js

@@ -28,7 +28,7 @@ import { readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isMap, isNode, isScalar, isSeq, parseDocument } from 'yaml';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-import { resolveDshHome } from '../catalog/paths.js';
+import { resolveDshHome } from '../../catalog/paths.js';
 /** Every package the plugin provisions for LSP, in declaration order. */
 export const LSP_PACKAGE_SPECIFIERS = ['@deepseek-ai/dsh-lsp', '@deepseek-ai/dsh-lsp-stdio', '@deepseek-ai/dsh-tool-lsp'];
 /**

package/lib/application/lsp-service.js

@@ -1,8 +1,8 @@
-import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
-import { loadDisabledLspServers, saveDisabledLspServers } from '../runtime/lsp-server-state.js';
-import { buildLspStatus } from '../runtime/lsp-status.js';
-import { describeLegacySeam, findLegacyLspSeams, migrateLegacyLspSeam } from '../runtime/profile-seam.js';
-import { applyLspOverrides, lspConfig, validateServerLsp } from '../runtime/server-config.js';
+import { loadLspServers, saveLspServers } from './lsp/lsp-direct-config.js';
+import { loadDisabledLspServers, saveDisabledLspServers } from './lsp/lsp-server-state.js';
+import { buildLspStatus } from './lsp/lsp-status.js';
+import { describeLegacySeam, findLegacyLspSeams, migrateLegacyLspSeam } from './lsp/profile-seam.js';
+import { applyLspOverrides, lspConfig, validateServerLsp } from './server-config.js';
 export class LspService {
     context;
     ports;

package/lib/{runtime → application/mcp}/mcp-backend.js

@@ -8,43 +8,28 @@
  * namespace (see `contracts/settings.ts`) registered by the plugin's node half:
  * the registration is what makes the host 插件配置 tab serve our card, the
  * client card binds it for state, and the node half watches it to remount
- * servers when the switch flips. `readMcpBackend` remains only as the
- * one-time migration from the earlier data-root `settings.json` choice.
+ * servers when the switch flips.
  *
- * @module runtime/mcp-backend
+ * @module application/mcp-backend
  */
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { MARKET_SETTINGS_DEFAULTS } from '../contracts/settings.js';
+import { MARKET_SETTINGS_DEFAULTS } from '../../contracts/settings.js';
 /**
  * Schema of the market settings namespace: the switches this plugin's config
  * card serves, with the defaults declared to the host. The values themselves
  * belong to {@link MARKET_SETTINGS_DEFAULTS}; this schema states them, it does
  * not own them.
  */
-export const MarketSettingsSchema = z.object({
+export const MarketSettingsFields = {
     mcpEnhanced: z.boolean().default(MARKET_SETTINGS_DEFAULTS.mcpEnhanced),
     scanProjectLayouts: z.boolean().default(MARKET_SETTINGS_DEFAULTS.scanProjectLayouts),
     downloadRegion: z.union([z.const('auto'), z.const('global'), z.const('china')]).default(MARKET_SETTINGS_DEFAULTS.downloadRegion),
     feedbackEnabled: z.boolean().default(MARKET_SETTINGS_DEFAULTS.feedbackEnabled),
     autoUpdateSources: z.boolean().default(MARKET_SETTINGS_DEFAULTS.autoUpdateSources)
-});
-/** Path of the legacy persisted settings file under the plugin data root. */
-export function marketSettingsPath(dataRoot) {
-    return join(dataRoot, 'settings.json');
-}
-/** Read the legacy persisted backend; absent or invalid values read as the default. */
-export async function readMcpBackend(dataRoot) {
-    try {
-        const parsed = JSON.parse(await readFile(marketSettingsPath(dataRoot), 'utf8'));
-        return parsed.mcpBackend === 'host' ? 'host' : 'builtin';
-    }
-    catch {
-        return 'builtin';
-    }
-}
+};
+export const MarketSettingsSchema = z.object(MarketSettingsFields);
 /**
  * Probe whether the host's `dsh-mcp-client` is resolvable from this plugin's
  * module context, and at which version. Best effort: any failure reads as

package/lib/{runtime → application/mcp}/mcp-config.js

@@ -20,11 +20,11 @@
  * server instead of becoming empty strings.
  */
 import { createHash } from 'node:crypto';
-import { DEFAULT_STARTUP_TIMEOUT_MS, DEFAULT_TOOL_CALL_TIMEOUT_MS } from './mcp-client/config.js';
-import { resolveCwd } from '../catalog/validate.js';
-import { qualifiedSuiteId, suiteDataDir } from '../catalog/paths.js';
+import { DEFAULT_STARTUP_TIMEOUT_MS, DEFAULT_TOOL_CALL_TIMEOUT_MS } from './mcp-bridge-config.js';
+import { resolveCwd } from '../../catalog/validate.js';
+import { qualifiedSuiteId, suiteDataDir } from '../../catalog/paths.js';
 import { applyOverride } from './mcp-overrides.js';
-import { PLUGIN_ROOT_VARIABLES, PLUGIN_DATA_VARIABLES } from '../model/layouts.js';
+import { PLUGIN_ROOT_VARIABLES, PLUGIN_DATA_VARIABLES } from '../../model/layouts.js';
 /** The max length the bridge accepts for a serverName. */
 const SERVER_NAME_MAX = 32;
 const PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;

package/lib/{runtime → application/mcp}/mcp-direct-config.js

@@ -1,8 +1,7 @@
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-import { MCP_SCHEMA_ID, validateMcpJson } from '../catalog/validate.js';
-import { effectiveSurfaces } from '../model/types.js';
+import { readJsonFile, writeJsonDocument } from '../json-file.js';
+import { MCP_SCHEMA_ID, validateMcpJson } from '../../catalog/validate.js';
+import { effectiveSurfaces } from '../../model/types.js';
 export const USER_MCP_SOURCE = '@user-mcp';
 export const USER_MCP_SUITE = 'user-mcp';
 /**
@@ -17,11 +16,12 @@ export async function loadUserMcpSuite(agentsRoot) {
     let mcp = { schema: MCP_SCHEMA_ID, servers: {} };
     const errors = [];
     try {
-        mcp = await validateUserMcp(agentsRoot, JSON.parse(await readFile(path, 'utf8')));
+        const raw = await readJsonFile(path);
+        if (raw !== undefined)
+            mcp = await validateUserMcp(agentsRoot, raw);
     }
     catch (error) {
-        if (error.code !== 'ENOENT')
-            errors.push(`mcp.json: ${error instanceof Error ? error.message : String(error)}`);
+        errors.push(`mcp.json: ${error instanceof Error ? error.message : String(error)}`);
     }
     return {
         sourceId: USER_MCP_SOURCE,
@@ -76,50 +76,9 @@ export async function addUserMcpServer(agentsRoot, name, server) {
         throw new Error(`MCP server "${name}" already exists`);
     const document = { $schema: MCP_SCHEMA_ID, mcpServers: { ...suite.mcp.servers, [name]: server } };
     await validateUserMcp(agentsRoot, document);
-    const path = userMcpPath(agentsRoot);
-    await writeFileAtomic(path, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+    await writeJsonDocument(userMcpPath(agentsRoot), document);
 }
 /** The user's hand-written MCP declaration file: `<agentsRoot>/mcp.json`. */
 export function userMcpPath(agentsRoot) {
     return join(agentsRoot, 'mcp.json');
 }
-const SERVER_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
-/**
- * Import several pasted servers in one write.
- *
- * Every entry is judged on its own so one bad definition cannot take the rest
- * of the paste with it, and an existing name is kept unless the caller asked to
- * overwrite. The file is written once, after every entry has been checked, so a
- * rejected entry never lands half-written beside the accepted ones.
- */
-export async function importUserMcpServers(agentsRoot, entries, overwrite = false) {
-    const suite = await loadUserMcpSuite(agentsRoot);
-    if (suite.errors.length > 0)
-        throw new Error(suite.errors.join('; '));
-    const servers = { ...suite.mcp.servers };
-    const imported = [];
-    const skipped = [];
-    for (const entry of entries) {
-        if (!SERVER_NAME_PATTERN.test(entry.name)) {
-            skipped.push({ name: entry.name, reason: 'invalid name' });
-            continue;
-        }
-        if (Object.hasOwn(servers, entry.name) && !overwrite) {
-            skipped.push({ name: entry.name, reason: 'already exists' });
-            continue;
-        }
-        try {
-            await validateUserMcp(agentsRoot, { $schema: MCP_SCHEMA_ID, mcpServers: { ...servers, [entry.name]: entry.server } });
-        }
-        catch (reason) {
-            skipped.push({ name: entry.name, reason: reason instanceof Error ? reason.message : String(reason) });
-            continue;
-        }
-        servers[entry.name] = entry.server;
-        imported.push(entry.name);
-    }
-    if (imported.length > 0) {
-        await writeFileAtomic(userMcpPath(agentsRoot), `${JSON.stringify({ $schema: MCP_SCHEMA_ID, mcpServers: servers }, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
-    }
-    return { imported, skipped };
-}

package/lib/{runtime → application/mcp}/mcp-overrides.js

@@ -11,9 +11,8 @@
  * resolved by the Host credentials service (or launch-environment fallback)
  * so keys never persist in plain text.
  */
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { readJsonFile, writeJsonDocument } from '../json-file.js';
 import { isSensitiveKey } from './mcp-redaction.js';
 /** The largest timeout a bridge config and the host timer can hold. */
 export const MAX_TIMEOUT_MS = 2_147_483_647;
@@ -28,7 +27,7 @@ export function suiteOverridePath(dataRoot, suiteId) {
 /** Load one suite's persisted overrides; unreadable files yield none. */
 export async function loadSuiteOverrides(dataRoot, suiteId) {
     try {
-        const raw = JSON.parse(await readFile(suiteOverridePath(dataRoot, suiteId), 'utf8'));
+        const raw = await readJsonFile(suiteOverridePath(dataRoot, suiteId));
         if (typeof raw !== 'object' || raw === null)
             return {};
         const parsed = sanitizeOverrides(raw);
@@ -40,8 +39,7 @@ export async function loadSuiteOverrides(dataRoot, suiteId) {
 }
 /** Persist one suite's overrides through the harness atomic write. */
 export async function saveSuiteOverrides(dataRoot, suiteId, overrides) {
-    const path = suiteOverridePath(dataRoot, suiteId);
-    await writeFileAtomic(path, `${JSON.stringify(overrides, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+    await writeJsonDocument(suiteOverridePath(dataRoot, suiteId), overrides);
 }
 /** Keep only recognized fields with correct shapes; drop everything else. */
 export function sanitizeOverrides(raw) {

package/lib/{runtime → application/mcp}/mcp-status.js

@@ -1,8 +1,6 @@
 import { credentialRefsInServer, effectiveMcpServers, deriveServerName } from './mcp-config.js';
-import { inspectToolRegistry } from './tool-registry-observer.js';
 import { redactMcpConfig, redactUrl } from './mcp-redaction.js';
-import { qualifiedSuiteId } from '../catalog/paths.js';
-export { inspectToolRegistry };
+import { qualifiedSuiteId } from '../../catalog/paths.js';
 /** Build status rows from discovered plugin MCP definitions and observed tool names. */
 export function buildMcpStatus(suites, diagnostics, observed, overrides = new Map()) {
     const entries = [];
@@ -55,9 +53,15 @@ export function buildMcpStatus(suites, diagnostics, observed, overrides = new Ma
                                 : tools.length > 0
                                     ? 'connected'
                                     : 'degraded';
-            const reason = orphaned
-                ? 'MCP tools remain after this plugin surface was disabled'
-                : (diagnostic?.reason ?? (override === undefined || (state !== 'disabled' && tools.length > 0) ? undefined : disabled ? 'disabled by override' : 'modified by override'));
+            // A diagnostic's reason keeps the code the mount pipeline gave it. The
+            // notes this builder adds describe the declaration's own state — an
+            // override switched it off, an override rewrote it, or its surface is
+            // gone while its tools remain — so each carries the matching state code
+            // for the panel to localize.
+            const orphanNote = orphaned ? 'MCP tools remain after this plugin surface was disabled' : undefined;
+            const overrideNote = override === undefined || (state !== 'disabled' && tools.length > 0) ? undefined : disabled ? 'disabled by override' : 'modified by override';
+            const reason = orphanNote ?? diagnostic?.reason ?? overrideNote;
+            const code = orphanNote !== undefined ? 'orphaned-tools' : (diagnostic?.code ?? (overrideNote === undefined ? undefined : disabled ? 'disabled-override' : 'modified-override'));
             entries.push({
                 id: `plugin:${suiteKey}/${serverKey}`,
                 name: serverName,
@@ -76,8 +80,9 @@ export function buildMcpStatus(suites, diagnostics, observed, overrides = new Ma
                 ...(policy.enabledTools === undefined ? {} : { suiteEnabledTools: policy.enabledTools }),
                 ...(policy.suiteDisabledTools === undefined ? {} : { suiteDisabledTools: policy.suiteDisabledTools }),
                 ...(override?.disabledTools === undefined ? {} : { userDisabledTools: override.disabledTools }),
-                ...(diagnostic?.code === undefined ? {} : { code: diagnostic.code }),
+                ...(code === undefined ? {} : { code }),
                 ...(reason === undefined ? {} : { reason }),
+                ...(diagnostic?.causes === undefined ? {} : { causes: diagnostic.causes }),
                 ...(credentialRefs.length === 0 ? {} : { credentialRefs })
             });
         }
@@ -102,6 +107,7 @@ export function buildMcpStatus(suites, diagnostics, observed, overrides = new Ma
                 config: redactMcpConfig(stale.server),
                 tools: observedTools(tools),
                 reason: 'MCP tools remain after this plugin was disabled or uninstalled',
+                code: 'orphaned-tools',
                 ...(staleRefs.length === 0 ? {} : { credentialRefs: staleRefs })
             });
             continue;

package/lib/application/mcp-service.js

@@ -9,16 +9,15 @@
 import { qualifiedSuiteId } from '../catalog/paths.js';
 import { isDirectory } from '../catalog/fs-probes.js';
 import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
-import { readLocalePreference } from '../runtime/host-locale.js';
-import { probeHostMcpClient } from '../runtime/mcp-backend.js';
-import { declaredMcpPolicy, namespaceMcpPolicy, resolveMcpPolicy } from '../runtime/mcp-config.js';
-import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
-import { addUserMcpServer, importUserMcpServers, loadUserMcpSuite, USER_MCP_SOURCE, USER_MCP_SUITE } from '../runtime/mcp-direct-config.js';
-import { applyOverride, loadSuiteOverrides, mergeOverridePatch, parseMcpPolicyPatch, saveSuiteOverrides, withoutPolicyFields } from '../runtime/mcp-overrides.js';
-import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
-import { buildMcpStatus } from '../runtime/mcp-status.js';
-import { resolveRegion } from '../runtime/regions.js';
-import { applyLspOverrides, lspConfig, restoreRedactedConfig, saveLspOverride, validateServerLsp, validateServerMcp } from '../runtime/server-config.js';
+import { probeHostMcpClient } from './mcp/mcp-backend.js';
+import { declaredMcpPolicy, namespaceMcpPolicy, resolveMcpPolicy } from './mcp/mcp-config.js';
+import { loadLspServers, saveLspServers } from './lsp/lsp-direct-config.js';
+import { addUserMcpServer, loadUserMcpSuite, USER_MCP_SOURCE, USER_MCP_SUITE } from './mcp/mcp-direct-config.js';
+import { applyOverride, loadSuiteOverrides, mergeOverridePatch, parseMcpPolicyPatch, saveSuiteOverrides, withoutPolicyFields } from './mcp/mcp-overrides.js';
+import { redactMcpConfig, redactMcpOverrides } from './mcp/mcp-redaction.js';
+import { buildMcpStatus } from './mcp/mcp-status.js';
+import { resolveRegion } from './regions.js';
+import { applyLspOverrides, lspConfig, restoreRedactedConfig, saveLspOverride, validateServerLsp, validateServerMcp } from './server-config.js';
 /** The host compatibility client mounts servers without a startup timeout or tool filters. */
 const HOST_STARTUP_TIMEOUT_UNSUPPORTED = 'the host MCP backend cannot enforce a startup timeout; switch the MCP backend to the built-in client to set one';
 const HOST_TOOL_FILTER_UNSUPPORTED = 'the host MCP backend cannot enforce tool filters; switch the MCP backend to the built-in client to choose tools';
@@ -64,29 +63,6 @@ export class McpService {
             await this.context.notifyChanged(true);
         });
     }
-    /**
-     * Import several pasted services in one write. Each entry is checked on its
-     * own and reports back with its own outcome, so a paste of many services
-     * never fails as a block.
-     */
-    async importServers(servers, overwrite) {
-        if (!Array.isArray(servers))
-            throw new Error('servers must be an array');
-        const entries = servers.map(entry => {
-            if (typeof entry !== 'object' || entry === null)
-                throw new Error('each server must be an object');
-            const { name, config } = entry;
-            if (typeof name !== 'string' || name === '')
-                throw new Error('each server needs a name');
-            return { name, server: config };
-        });
-        return this.context.enqueue(async () => {
-            const result = await importUserMcpServers(this.context.agentsRoot, entries, overwrite);
-            if (result.imported.length > 0)
-                await this.context.notifyChanged(true);
-            return result;
-        });
-    }
     /** Read effective service configuration without exposing credential literals. */
     async serverConfig(kind, id) {
         const config = await this.resolveServerConfig(kind, id);
@@ -272,8 +248,8 @@ export class McpService {
      * everything the plugin-config card renders.
      */
     async backendInfo() {
-        const [backend, hostClient, regionSetting, locale] = await Promise.all([this.ports.mcpBackend(), probeHostMcpClient(), this.ports.downloadRegion(), readLocalePreference()]);
-        return { backend, hostClient, downloadRegion: { setting: regionSetting, effective: resolveRegion(regionSetting, locale) } };
+        const [backend, hostClient, regionSetting] = await Promise.all([this.ports.mcpBackend(), probeHostMcpClient(), this.ports.downloadRegion()]);
+        return { backend, hostClient, downloadRegion: { setting: regionSetting, effective: resolveRegion(regionSetting, this.ports.localePreference()) } };
     }
     /**
      * Switch the MCP mount backend and remount every suite server through it.