dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/runtime/mcp-client/host-contract.js

@@ -0,0 +1,10 @@
+/**
+ * Structural mirrors of the harness tool-registration surface the bridge
+ * registers against: the runtime accepts the same object shape the upstream
+ * `@deepseek-ai/dsh-tools` bridge registers, so the model-facing behavior is
+ * identical. Mirrored rather than imported so the market never loads a second
+ * copy of the host runtime.
+ *
+ * @module runtime/mcp-client/host-contract
+ */
+export {};

package/lib/runtime/mcp-client/oauth.js

@@ -22,18 +22,16 @@
  * then last exactly as long as the process.
  *
  * Ported from the harness `dsh-mcp-client` OAuth implementation (upstream
- * commits archived at `docs/upstream-proposal/patches/`); the record format is
+ * commits archived at `docs/developer/upstream-proposal/patches/`); the record format is
  * byte-compatible, so grants written by either implementation are interchangeable.
  *
  * @module runtime/mcp-client/oauth
  */
 import { createServer } from 'node:http';
 import { credentialKey, scrubbedParentEnv } from './host-seams.js';
+import { PLUGIN_NAME, PLUGIN_VERSION } from './plugin-identity.js';
 /** OAuth client identity presented during dynamic registration. */
-const CLIENT_NAME = 'DeepSeek Harness (dsh-agent-plugins-market)';
-/** Software id/version advertised in RFC 7591 registration metadata. */
-const CLIENT_SOFTWARE_ID = 'dsh-agent-plugins-market';
-const CLIENT_SOFTWARE_VERSION = '0.1.0';
+const CLIENT_NAME = `DeepSeek Harness (${PLUGIN_NAME})`;
 /** Credential-record scope for MCP OAuth state; per-server ids follow it. */
 export const MCP_AUTH_RECORD_SCOPE = 'mcp-auth';
 /** Loopback callback budget: the browser must land within five minutes. */
@@ -146,8 +144,8 @@ export class LoopbackOAuthClientProvider {
             // Public client: PKCE carries the proof; no client secret exists.
             token_endpoint_auth_method: 'none',
             ...(this.scope === undefined ? {} : { scope: this.scope }),
-            software_id: CLIENT_SOFTWARE_ID,
-            software_version: CLIENT_SOFTWARE_VERSION
+            software_id: PLUGIN_NAME,
+            software_version: PLUGIN_VERSION
         };
     }
     async clientInformation() {

package/lib/runtime/mcp-client/plugin-identity.js

@@ -0,0 +1,28 @@
+/**
+ * This plugin's own identity as advertised to the servers it talks to: the MCP
+ * client implementation name and version, and the RFC 7591 `software_id` /
+ * `software_version` carried in OAuth dynamic-registration metadata.
+ *
+ * The version is read from the installed manifest through Node's package
+ * self-reference, so a release bumps exactly one number — `package.json`. A
+ * copy that can no longer resolve its own manifest (a bundle that inlined this
+ * module) reports {@link UNKNOWN_VERSION} rather than failing the connection.
+ *
+ * @module runtime/mcp-client/plugin-identity
+ */
+import { createRequire } from 'node:module';
+/** Name npm and the harness know this plugin by. */
+export const PLUGIN_NAME = 'dsh-agent-plugins-market';
+/** Reported when the plugin cannot read its own manifest; never a released version. */
+const UNKNOWN_VERSION = '0.0.0';
+function readVersion() {
+    try {
+        const manifest = createRequire(import.meta.url)('dsh-agent-plugins-market/package.json');
+        return typeof manifest.version === 'string' && manifest.version !== '' ? manifest.version : UNKNOWN_VERSION;
+    }
+    catch {
+        return UNKNOWN_VERSION;
+    }
+}
+/** This plugin's release version. */
+export const PLUGIN_VERSION = readVersion();

package/lib/runtime/mcp-client/projection.js

@@ -0,0 +1,202 @@
+/**
+ * MCP result projection: turn the content blocks an MCP server returns into
+ * the host content vocabulary the model sees.
+ *
+ * Text-like blocks collapse into newline-joined text runs; declared images are
+ * decoded, admitted against the live model route, and saved to the durable
+ * attachment store. Every refusal — an unsupported media type, a model that
+ * does not declare image input, a storage fault — projects the block as text
+ * explaining why, and the canonical raw value stays available to programmatic
+ * callers in the tool result.
+ *
+ * Everything here reads an untrusted network payload: the MCP server is an
+ * external process and the SDK's declared-required fields may be absent at
+ * runtime, so each block is narrowed field by field.
+ *
+ * @module runtime/mcp-client/projection
+ */
+import { isImageAdmissionError } from './host-seams.js';
+/** Raster formats supported by the durable attachment vocabulary. */
+const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
+/** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Whether an untrusted MCP content array contains a declared image block. */
+export function containsImage(content) {
+    return content.some(value => isRecord(value) && value.type === 'image');
+}
+/** Narrow one JSON value to a string-keyed object. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Narrow a declared MIME string to the durable image vocabulary. */
+function isImageMediaType(value) {
+    return IMAGE_MEDIA_TYPES.includes(value);
+}
+/** Decode one untrusted MCP image block without accepting base64 aliases. */
+function decodeImage(block) {
+    if (block.mimeType === undefined || !isImageMediaType(block.mimeType)) {
+        throw new Error('the declared media type is not PNG, JPEG, WebP, or GIF');
+    }
+    if (block.data === undefined || !CANONICAL_BASE64.test(block.data)) {
+        throw new Error('the image data is not canonical base64');
+    }
+    const data = Buffer.from(block.data, 'base64');
+    if (data.toString('base64') !== block.data) {
+        throw new Error('the image data is not canonical base64');
+    }
+    return { data, mediaType: block.mimeType };
+}
+/**
+ * Resolve the active model route and durable store for an image-bearing result.
+ * @param host - bridge host with optional services.
+ * @param exec - exact tool execution whose agent supplies the latest route.
+ * @returns the attachment store after exact positive image-capability proof.
+ */
+async function resolveImageAdmission(host, exec) {
+    const attachments = host.getService?.('attachments');
+    if (attachments === undefined || typeof attachments.saveImages !== 'function') {
+        throw new Error('no attachment store is mounted');
+    }
+    const routed = exec.agent?.session?.requestHeader?.()?.config;
+    const provider = routed?.provider ?? exec.agent?.options?.provider;
+    const model = routed?.model ?? exec.agent?.options?.model;
+    const llm = host.getService?.('llm');
+    if (provider === undefined || model === undefined || llm === undefined) {
+        throw new Error('the current model route could not be resolved');
+    }
+    let info;
+    try {
+        info = await llm.resolveModelInfo(provider, model, exec.signal);
+    }
+    catch {
+        throw new Error('the current model route could not be verified');
+    }
+    if (info?.inputModalities === undefined || !info.inputModalities.includes('image')) {
+        throw new Error(`model "${model}" does not declare image input`);
+    }
+    if (exec.signal.aborted)
+        throw new Error('the tool call was canceled before image storage');
+    return attachments;
+}
+/** Stable diagnostic text for an image block that was not admitted. */
+function imageDiagnostic(block, reason) {
+    return `[image unavailable: ${block.mimeType ?? 'unknown media type'}; ${reason}; raw image data remains available to programmatic callers]`;
+}
+/**
+ * Decode, preflight, and durably save one MCP result's ordered image batch.
+ * Any refusal projects every image as text while retaining the canonical raw
+ * value for programmatic callers.
+ */
+export async function prepareImageProjection(host, exec, content, toolName) {
+    const decoded = [];
+    const validationErrors = new Map();
+    const imageIndexes = [];
+    for (const [index, value] of content.entries()) {
+        if (!isRecord(value) || value.type !== 'image')
+            continue;
+        imageIndexes.push(index);
+        try {
+            decoded.push(decodeImage(value));
+        }
+        catch (error) {
+            // decodeImage owns every throw above and always produces Error.
+            validationErrors.set(index, error.message);
+        }
+    }
+    if (validationErrors.size > 0) {
+        return projectContent(content, toolName, (block, index) => ({
+            type: 'text',
+            text: imageDiagnostic(block, validationErrors.get(index) ?? 'another image in the same result was invalid')
+        }));
+    }
+    let attachments;
+    try {
+        attachments = await resolveImageAdmission(host, exec);
+    }
+    catch (error) {
+        // resolveImageAdmission contains provider failures and throws Error only.
+        const reason = error.message;
+        return projectContent(content, toolName, block => ({ type: 'text', text: imageDiagnostic(block, reason) }));
+    }
+    try {
+        const refs = await attachments.saveImages(decoded);
+        const byIndex = new Map(imageIndexes.map((index, offset) => [index, refs[offset]]));
+        return projectContent(content, toolName, (_block, index) => ({
+            type: 'image',
+            attachment: byIndex.get(index)
+        }));
+    }
+    catch (error) {
+        const reason = isImageAdmissionError(error) ? `image admission rejected the result: ${error.message}` : 'durable image storage rejected the result';
+        return projectContent(content, toolName, block => ({
+            type: 'text',
+            text: imageDiagnostic(block, reason)
+        }));
+    }
+}
+/**
+ * Extract text from an MCP content array into a single string.
+ * - text blocks: join with '\n'
+ * - image/audio/resource blocks: replaced with a placeholder
+ *
+ * Defensive: fields that the MCP spec declares required (mimeType, text) are
+ * guarded with fallbacks because this is a network trust boundary.
+ */
+export function extractText(mcpContent, toolName) {
+    const content = projectContent(mcpContent, toolName);
+    // The default image projector below also returns text, so this local call
+    // cannot produce a core image block.
+    return content.map(block => block.text).join('\n');
+}
+/**
+ * Project ordered MCP blocks into the core content vocabulary.
+ * Text-like runs are newline-coalesced; admitted images split those runs at
+ * their original position.
+ */
+function projectContent(mcpContent, toolName, image = block => ({
+    type: 'text',
+    text: imageDiagnostic(block, 'this result was not admitted to durable model context')
+})) {
+    const projected = [];
+    const text = [];
+    const flushText = () => {
+        if (text.length === 0)
+            return;
+        projected.push({ type: 'text', text: text.splice(0).join('\n') });
+    };
+    for (const [index, value] of mcpContent.entries()) {
+        if (!isRecord(value)) {
+            text.push('[unsupported MCP content block: expected an object]');
+            continue;
+        }
+        const block = value;
+        switch (block.type) {
+            case 'text':
+                if (block.text !== undefined)
+                    text.push(block.text);
+                break;
+            case 'image':
+                flushText();
+                projected.push(image(block, index));
+                break;
+            case 'resource_link':
+                if (block.name === undefined || block.uri === undefined) {
+                    text.push('[resource link unavailable: the MCP block is missing its name or URI]');
+                }
+                else {
+                    text.push(`Resource link: ${block.name} (${block.uri})`);
+                }
+                break;
+            case 'audio':
+                text.push(`[audio result unsupported: ${block.mimeType ?? 'unknown media type'}; raw audio data remains available to programmatic callers]`);
+                break;
+            case 'resource':
+                text.push('[embedded resource unsupported; raw resource data remains available to programmatic callers]');
+                break;
+            default:
+                text.push(`[unsupported MCP content type: ${block.type}]`);
+        }
+    }
+    flushText();
+    return projected.length > 0 ? projected : [{ type: 'text', text: `(${toolName} returned no model-visible content)` }];
+}

package/lib/runtime/mcp-client/tools.js

@@ -9,10 +9,9 @@
  * to the DeepSeek function-name constraints. The raw name is only ever sent on
  * the wire (`tools/call`); the public name is never parsed to recover it.
  *
- * The host contract below (`ToolDefinition`, `ToolExecution`,
- * `ToolExecutionResult`) is a structural mirror of `@deepseek-ai/dsh-tools`
- * rc.2's registration surface — the runtime accepts the same object shape the
- * upstream bridge registers, so the model-facing behavior is identical.
+ * The registration surface this module targets is mirrored by
+ * `./host-contract.js`; MCP results are mapped into host content blocks by
+ * `./projection.js`.
  *
  * @module runtime/mcp-client/tools
  */
@@ -21,7 +20,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { assertSupportedJsonSchema } from './json-schema-subset.js';
-import { isImageAdmissionError } from './host-seams.js';
+import { containsImage, extractText, prepareImageProjection } from './projection.js';
 /**
  * DeepSeek function-name contract: at most 64 characters. Wire-protocol
  * constant, not configuration.
@@ -31,10 +30,6 @@ const MAX_PUBLIC_NAME_LENGTH = 64;
 const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g;
 /** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
 const HASH_LENGTH = 12;
-/** Raster formats supported by the durable attachment vocabulary. */
-const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
-/** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
-const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 /** Raw result record: the bridge owns JSON-value validation after transport. */
 const RawCallToolResultSchema = z.record(z.string(), z.unknown());
 /** List without mutating the SDK's per-page output-validator cache. */
@@ -253,183 +248,3 @@ function createExecutor(client, host, rawName, taskRequired, opts, projections)
         return value;
     };
 }
-/** Whether an untrusted MCP content array contains a declared image block. */
-function containsImage(content) {
-    return content.some(value => isRecord(value) && value.type === 'image');
-}
-/** Narrow one JSON value to a string-keyed object. */
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/** Narrow a declared MIME string to the durable image vocabulary. */
-function isImageMediaType(value) {
-    return IMAGE_MEDIA_TYPES.includes(value);
-}
-/** Decode one untrusted MCP image block without accepting base64 aliases. */
-function decodeImage(block) {
-    if (block.mimeType === undefined || !isImageMediaType(block.mimeType)) {
-        throw new Error('the declared media type is not PNG, JPEG, WebP, or GIF');
-    }
-    if (block.data === undefined || !CANONICAL_BASE64.test(block.data)) {
-        throw new Error('the image data is not canonical base64');
-    }
-    const data = Buffer.from(block.data, 'base64');
-    if (data.toString('base64') !== block.data) {
-        throw new Error('the image data is not canonical base64');
-    }
-    return { data, mediaType: block.mimeType };
-}
-/**
- * Resolve the active model route and durable store for an image-bearing result.
- * @param host - bridge host with optional services.
- * @param exec - exact tool execution whose agent supplies the latest route.
- * @returns the attachment store after exact positive image-capability proof.
- */
-async function resolveImageAdmission(host, exec) {
-    const attachments = host.getService?.('attachments');
-    if (attachments === undefined || typeof attachments.saveImages !== 'function') {
-        throw new Error('no attachment store is mounted');
-    }
-    const routed = exec.agent?.session?.requestHeader?.()?.config;
-    const provider = routed?.provider ?? exec.agent?.options?.provider;
-    const model = routed?.model ?? exec.agent?.options?.model;
-    const llm = host.getService?.('llm');
-    if (provider === undefined || model === undefined || llm === undefined) {
-        throw new Error('the current model route could not be resolved');
-    }
-    let info;
-    try {
-        info = await llm.resolveModelInfo(provider, model, exec.signal);
-    }
-    catch {
-        throw new Error('the current model route could not be verified');
-    }
-    if (info?.inputModalities === undefined || !info.inputModalities.includes('image')) {
-        throw new Error(`model "${model}" does not declare image input`);
-    }
-    if (exec.signal.aborted)
-        throw new Error('the tool call was canceled before image storage');
-    return attachments;
-}
-/** Stable diagnostic text for an image block that was not admitted. */
-function imageDiagnostic(block, reason) {
-    return `[image unavailable: ${block.mimeType ?? 'unknown media type'}; ${reason}; raw image data remains available to programmatic callers]`;
-}
-/**
- * Decode, preflight, and durably save one MCP result's ordered image batch.
- * Any refusal projects every image as text while retaining the canonical raw
- * value for programmatic callers.
- */
-async function prepareImageProjection(host, exec, content, toolName) {
-    const decoded = [];
-    const validationErrors = new Map();
-    const imageIndexes = [];
-    for (const [index, value] of content.entries()) {
-        if (!isRecord(value) || value.type !== 'image')
-            continue;
-        imageIndexes.push(index);
-        try {
-            decoded.push(decodeImage(value));
-        }
-        catch (error) {
-            // decodeImage owns every throw above and always produces Error.
-            validationErrors.set(index, error.message);
-        }
-    }
-    if (validationErrors.size > 0) {
-        return projectContent(content, toolName, (block, index) => ({
-            type: 'text',
-            text: imageDiagnostic(block, validationErrors.get(index) ?? 'another image in the same result was invalid')
-        }));
-    }
-    let attachments;
-    try {
-        attachments = await resolveImageAdmission(host, exec);
-    }
-    catch (error) {
-        // resolveImageAdmission contains provider failures and throws Error only.
-        const reason = error.message;
-        return projectContent(content, toolName, block => ({ type: 'text', text: imageDiagnostic(block, reason) }));
-    }
-    try {
-        const refs = await attachments.saveImages(decoded);
-        const byIndex = new Map(imageIndexes.map((index, offset) => [index, refs[offset]]));
-        return projectContent(content, toolName, (_block, index) => ({
-            type: 'image',
-            attachment: byIndex.get(index)
-        }));
-    }
-    catch (error) {
-        const reason = isImageAdmissionError(error) ? `image admission rejected the result: ${error.message}` : 'durable image storage rejected the result';
-        return projectContent(content, toolName, block => ({
-            type: 'text',
-            text: imageDiagnostic(block, reason)
-        }));
-    }
-}
-/**
- * Extract text from an MCP content array into a single string.
- * - text blocks: join with '\n'
- * - image/audio/resource blocks: replaced with a placeholder
- *
- * Defensive: fields that the MCP spec declares required (mimeType, text) are
- * guarded with fallbacks because this is a network trust boundary.
- */
-function extractText(mcpContent, toolName) {
-    const content = projectContent(mcpContent, toolName);
-    // The default image projector below also returns text, so this local call
-    // cannot produce a core image block.
-    return content.map(block => block.text).join('\n');
-}
-/**
- * Project ordered MCP blocks into the core content vocabulary.
- * Text-like runs are newline-coalesced; admitted images split those runs at
- * their original position.
- */
-function projectContent(mcpContent, toolName, image = block => ({
-    type: 'text',
-    text: imageDiagnostic(block, 'this result was not admitted to durable model context')
-})) {
-    const projected = [];
-    const text = [];
-    const flushText = () => {
-        if (text.length === 0)
-            return;
-        projected.push({ type: 'text', text: text.splice(0).join('\n') });
-    };
-    for (const [index, value] of mcpContent.entries()) {
-        if (!isRecord(value)) {
-            text.push('[unsupported MCP content block: expected an object]');
-            continue;
-        }
-        const block = value;
-        switch (block.type) {
-            case 'text':
-                if (block.text !== undefined)
-                    text.push(block.text);
-                break;
-            case 'image':
-                flushText();
-                projected.push(image(block, index));
-                break;
-            case 'resource_link':
-                if (block.name === undefined || block.uri === undefined) {
-                    text.push('[resource link unavailable: the MCP block is missing its name or URI]');
-                }
-                else {
-                    text.push(`Resource link: ${block.name} (${block.uri})`);
-                }
-                break;
-            case 'audio':
-                text.push(`[audio result unsupported: ${block.mimeType ?? 'unknown media type'}; raw audio data remains available to programmatic callers]`);
-                break;
-            case 'resource':
-                text.push('[embedded resource unsupported; raw resource data remains available to programmatic callers]');
-                break;
-            default:
-                text.push(`[unsupported MCP content type: ${block.type}]`);
-        }
-    }
-    flushText();
-    return projected.length > 0 ? projected : [{ type: 'text', text: `(${toolName} returned no model-visible content)` }];
-}

package/lib/runtime/mcp-config.js

@@ -20,6 +20,22 @@ import { PLUGIN_ROOT_VARIABLES, PLUGIN_DATA_VARIABLES } from '../model/layouts.j
 const SERVER_NAME_MAX = 32;
 const PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
 const BUILTIN_PLACEHOLDERS = new Set([...PLUGIN_ROOT_VARIABLES, ...PLUGIN_DATA_VARIABLES]);
+/**
+ * The effective view of one suite's `mcp.json` servers: the user's per-server
+ * overrides applied, every row flagged with whether it is used at all, and each
+ * row's credential references read off the effective shape. Mounting, status
+ * and detail rendering read this one projection, so a server cannot be listed
+ * as enabled while mounting something else.
+ */
+export function effectiveMcpServers(suite, overrides = {}) {
+    const rows = [];
+    for (const [serverKey, source] of Object.entries(suite.mcp?.servers ?? {})) {
+        const override = overrides[serverKey];
+        const server = applyOverride(source, override);
+        rows.push({ serverKey, server, override, enabled: override?.enabled !== false, credentialRefs: credentialRefsInServer(server) });
+    }
+    return rows;
+}
 /**
  * Build one mount request per supported mcp.json server, resolving every
  * `${NAME}` through the credential resolver before a child process or HTTP
@@ -29,31 +45,34 @@ const BUILTIN_PLACEHOLDERS = new Set([...PLUGIN_ROOT_VARIABLES, ...PLUGIN_DATA_V
  * @param overrides user-owned per-server overrides (url/headers/env/args
  *   replacement plus enable/disable); applied before mount. Disabled servers
  *   are omitted entirely.
- * @returns mount requests plus per-server failures. serverName collisions are
- *   reported by the mount registry, not here.
+ * @returns mount requests, per-server failures, and the credential references
+ *   the effective servers need. serverName collisions are reported by the
+ *   mount registry, not here.
  */
 export async function toMcpMounts(suite, pluginDataRoot, overrides = {}, resolver = { resolve: async () => undefined }) {
     if (suite.mcp === undefined)
-        return { mounts: [], failures: [] };
+        return { mounts: [], failures: [], credentialRefs: [] };
     const mounts = [];
     const failures = [];
-    for (const [serverKey, source] of Object.entries(suite.mcp.servers)) {
-        const override = overrides[serverKey];
-        if (override?.enabled === false)
+    const credentialRefs = new Set();
+    for (const row of effectiveMcpServers(suite, overrides)) {
+        if (!row.enabled)
             continue;
-        const server = applyOverride(source, override);
+        for (const ref of row.credentialRefs)
+            credentialRefs.add(ref);
         try {
-            const result = await toResolvedMount(suite.mcp.root === undefined ? suite : { ...suite, root: suite.mcp.root }, serverKey, server, pluginDataRoot, resolver);
+            const target = suite.mcp.root === undefined ? suite : { ...suite, root: suite.mcp.root };
+            const result = await toResolvedMount(target, row.serverKey, row.server, pluginDataRoot, resolver);
             if (result.failure !== undefined)
                 failures.push(result.failure);
             if (result.request !== undefined)
                 mounts.push(result.request);
         }
         catch {
-            failures.push({ serverKey, code: 'credential-error', credentialRefs: credentialRefsInServer(server), reason: 'credential lookup failed' });
+            failures.push({ serverKey: row.serverKey, code: 'credential-error', credentialRefs: row.credentialRefs, reason: 'credential lookup failed' });
         }
     }
-    return { mounts, failures };
+    return { mounts, failures, credentialRefs: [...credentialRefs] };
 }
 /** Find external credential references used by one MCP server definition. */
 export function credentialRefsInServer(server) {

package/lib/runtime/mcp-direct-config.js

@@ -1,56 +1,73 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { MCP_SCHEMA_ID, validateAgainstSchema, 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';
-/** User-created services reuse the owned bridge lifecycle without changing host configuration. */
-export async function loadUserMcpSuite(dataRoot) {
-    const path = join(dataRoot, 'mcp-servers.json');
+/**
+ * User-created services reuse the owned bridge lifecycle without changing host configuration.
+ *
+ * The declarations live in the shared Agent layout root
+ * (`~/.agents/mcp.json`), so a service the user adds by hand is ordinary
+ * `mcpServers` JSON in the same place other Agent tools look.
+ *
+ * The suite always carries an `mcp` document — an absent or malformed
+ * `mcp.json` leaves an empty one — so callers read `.mcp.servers` directly
+ * instead of re-checking the optional field.
+ */
+export async function loadUserMcpSuite(agentsRoot) {
+    const path = userMcpPath(agentsRoot);
     let mcp = { schema: MCP_SCHEMA_ID, servers: {} };
     const errors = [];
     try {
-        mcp = await validateUserMcp(dataRoot, JSON.parse(await readFile(path, 'utf8')));
+        mcp = await validateUserMcp(agentsRoot, JSON.parse(await readFile(path, 'utf8')));
     }
     catch (error) {
         if (error.code !== 'ENOENT')
-            errors.push(`mcp-servers.json: ${error instanceof Error ? error.message : String(error)}`);
+            errors.push(`mcp.json: ${error instanceof Error ? error.message : String(error)}`);
     }
     return {
         sourceId: USER_MCP_SOURCE,
         id: USER_MCP_SUITE,
-        root: dataRoot,
+        root: agentsRoot,
         manifest: { layout: 'agent-plugin-v1', path, id: USER_MCP_SUITE, name: USER_MCP_SUITE },
         skills: [],
         mcp,
         surfaces: { skills: 0, mcp: Object.keys(mcp.servers).length, commands: 0, agents: 0, hooks: 0, lsp: 0 },
         dimension: 'user',
         enabled: true,
+        // A user-created suite has no install entry and no overrides, so every
+        // surface keeps its enabled default.
+        activeSurfaces: effectiveSurfaces(undefined),
         installedAt: 'user',
         errors
     };
 }
-async function validateUserMcp(dataRoot, raw) {
+async function validateUserMcp(agentsRoot, raw) {
     const errors = await validateAgainstSchema(MCP_SCHEMA_ID, raw);
     if (errors.length > 0)
         throw new Error(`invalid MCP configuration: ${errors.join('; ')}`);
-    const result = await validateMcpJson(dataRoot, raw);
+    const result = await validateMcpJson(agentsRoot, raw);
     if (result.config === undefined || result.errors.length > 0)
         throw new Error(result.errors.join('; '));
     return result.config;
 }
 /** Add one service atomically; reject collisions and malformed config before writing. */
-export async function addUserMcpServer(dataRoot, name, server) {
+export async function addUserMcpServer(agentsRoot, name, server) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name))
         throw new Error('invalid MCP server name');
-    const suite = await loadUserMcpSuite(dataRoot);
+    const suite = await loadUserMcpSuite(agentsRoot);
     if (suite.errors.length > 0)
         throw new Error(suite.errors.join('; '));
     if (Object.hasOwn(suite.mcp.servers, name))
         throw new Error(`MCP server "${name}" already exists`);
     const document = { $schema: MCP_SCHEMA_ID, mcpServers: { ...suite.mcp.servers, [name]: server } };
-    await validateUserMcp(dataRoot, document);
-    await mkdir(dataRoot, { recursive: true });
-    const path = join(dataRoot, 'mcp-servers.json');
-    await writeFile(`${path}.tmp`, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
-    await rename(`${path}.tmp`, path);
+    await validateUserMcp(agentsRoot, document);
+    const path = userMcpPath(agentsRoot);
+    await writeFileAtomic(path, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+}
+/** The user's hand-written MCP declaration file: `<agentsRoot>/mcp.json`. */
+export function userMcpPath(agentsRoot) {
+    return join(agentsRoot, 'mcp.json');
 }