dsh-agent-plugins-market 0.7.0 → 0.7.2

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

@@ -1,88 +1,8 @@
-/**
- * Local ports of the tiny host seams the self-built MCP client needs.
- *
- * The market plugin must stay self-contained at runtime: it cannot import
- * host-internal packages that are not published at compatible versions, and
- * every one of these seams is a small pure function or constant. Each port
- * below is copied verbatim (semantics, not prose) from the harness source at
- * `0.1.1-rc.2` and carries the upstream reference it came from, so a future
- * host change can be re-diffed against `~/workspace/deepseek-harness`.
- *
- * Anything larger than a handful of lines (the JSON Schema subset validator)
- * lives in its own module.
- *
- * @module runtime/mcp-client/host-seams
- */
-// ---- dsh-timeout: MAX_TIMER_DELAY_MS (packages/util/timeout/src/index.ts) ----
-/**
- * The largest delay `setTimeout` accepts without overflowing to a 1ms clamp
- * (2^31 - 1). Shared guard for reconnect and callback timers.
- */
-export const MAX_TIMER_DELAY_MS = 2_147_483_647;
-// ---- dsh-subprocess: scrubbedParentEnv (packages/subprocess/subprocess/src/index.ts) ----
-/** `DSH_*` environment namespace owned by the harness. */
-export const DSH_ENV_PREFIX = 'DSH_';
-/**
- * Credential-shaped environment names are NOT forwarded to MCP server child
- * processes (the harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a
- * spawned server implicitly). Deliberately supplied env entries survive
- * because the config's explicit env merges after the scrub.
- */
-export const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i;
-/**
- * The ambient parent environment minus credential-shaped names and minus all
- * `DSH_*` names — the canonical base every harness child starts from. `PATH`,
- * `HOME`, locale, and proxy variables survive, so child CLIs run normally;
- * harness identity never leaks implicitly. Both scrubs match case-insensitively:
- * Windows environment names are case-insensitive, so a parent `dsh_*` entry
- * would otherwise survive and read back as `$env:DSH_*` in the child.
- * @returns a fresh environment object safe to hand to a child spawn.
- */
-export function scrubbedParentEnv() {
-    const env = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value !== undefined && !SENSITIVE_ENV_PATTERN.test(key) && !key.toUpperCase().startsWith(DSH_ENV_PREFIX))
-            env[key] = value;
-    }
-    return env;
-}
-/** Key segments are lowercase hyphenated identifiers. */
-const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
-/**
- * Brand a scope and an id as a {@link CredentialKey}.
- * @param scope - the owning plugin's registered name (here: the `mcp-auth` record scope).
- * @param id - the plugin's own addressing unit (here: the folded serverName).
- * @returns the branded key.
- * @throws TypeError when either segment is not a lowercase hyphenated identifier.
- */
-export function credentialKey(scope, id) {
-    for (const segment of [scope, id]) {
-        if (!KEY_SEGMENT_PATTERN.test(segment)) {
-            throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
-        }
-    }
-    return `${scope}/${id}`;
-}
-// ---- dsh-attachment: image admission error routing (packages/attachment/attachment/src/error.ts) ----
-/** Caller-correctable attachment failure codes raised while admitting image input. */
-const IMAGE_ADMISSION_ERROR_CODES = [
-    'TOO_MANY_IMAGES',
-    'IMAGES_TOO_LARGE',
-    'UNSUPPORTED_IMAGE_TYPE',
-    'INVALID_IMAGE_BASE64',
-    'INVALID_IMAGE',
-    'IMAGE_TYPE_MISMATCH',
-    'IMAGE_TOO_LARGE',
-    'IMAGE_TOO_MANY_PIXELS',
-    'IMAGE_DIMENSION_TOO_LARGE'
-];
-/** Runtime membership for structurally compatible errors crossing package boundaries. */
-const IMAGE_ADMISSION_ERROR_CODE_SET = new Set(IMAGE_ADMISSION_ERROR_CODES);
-/**
- * Distinguish caller-correctable image admission failures from storage faults,
- * so an admission refusal projects text diagnostics while a storage fault is
- * reported as such.
- */
-export function isImageAdmissionError(error) {
-    return error instanceof Error && 'code' in error && typeof error.code === 'string' && IMAGE_ADMISSION_ERROR_CODE_SET.has(error.code);
-}
+// ---- dsh-timeout: timer bounds ----
+export { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
+// ---- dsh-subprocess: the canonical child environment ----
+export { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess';
+// ---- dsh-credentials: key grammar ----
+export { credentialKey } from '@deepseek-ai/dsh-credentials';
+// ---- dsh-attachment: durable image vocabulary ----
+export { isImageAdmissionError } from '@deepseek-ai/dsh-attachment';

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

@@ -28,7 +28,10 @@
  * @module runtime/mcp-client/oauth
  */
 import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
 import { credentialKey, scrubbedParentEnv } from './host-seams.js';
+import { redactErrorMessage, redactUrl } from '../mcp-redaction.js';
 import { PLUGIN_NAME, PLUGIN_VERSION } from './plugin-identity.js';
 /** OAuth client identity presented during dynamic registration. */
 const CLIENT_NAME = `DeepSeek Harness (${PLUGIN_NAME})`;
@@ -65,6 +68,18 @@ function asMcpAuthRecord(record) {
         ...(payload.tokens === undefined ? {} : { tokens: payload.tokens })
     };
 }
+/**
+ * Merge one locally changed durable field without overwriting a concurrent
+ * process's update. If the value read before the mutation no longer matches
+ * the store's locked current value, the current value wins conservatively.
+ */
+function mergeDurableField(base, desired, current) {
+    if (isDeepStrictEqual(base, desired))
+        return current;
+    if (isDeepStrictEqual(base, current))
+        return desired;
+    return current;
+}
 /**
  * Error thrown when the human leg fails or is abandoned: the browser never
  * returned, the callback carried an OAuth error, or no browser could open.
@@ -89,7 +104,7 @@ export const platformBrowserOpener = async (authorizationUrl, serverName, log) =
         detached: platform !== 'win32'
     });
     child.once('error', error => {
-        log(`${serverName}: could not open a browser automatically (${String(error)}); open this URL manually: ${authorizationUrl.toString()}`);
+        log(`${serverName}: could not open a browser automatically (${redactErrorMessage(String(error))}); open this URL manually: ${redactUrl(authorizationUrl.toString())}`);
     });
     child.once('spawn', () => {
         child.unref();
@@ -113,6 +128,8 @@ export class LoopbackOAuthClientProvider {
     providerState = {};
     /** The transport generation whose `finishAuth` completes the browser leg. */
     activeTransport;
+    /** One process-local OAuth state value for the current browser leg. */
+    expectedState;
     /** Resolves `true` when the leg saved tokens, `false` when it failed; undefined while no leg is open. */
     browserLegSettled;
     callbackServer;
@@ -148,6 +165,12 @@ export class LoopbackOAuthClientProvider {
             software_version: PLUGIN_VERSION
         };
     }
+    /** Issue one unpredictable state value for the SDK's authorization request. */
+    state() {
+        const state = randomBytes(32).toString('base64url');
+        this.expectedState = state;
+        return state;
+    }
     async clientInformation() {
         return (await this.load()).clientInformation;
     }
@@ -177,6 +200,11 @@ export class LoopbackOAuthClientProvider {
         if (transport === undefined) {
             throw new AuthorizationAbortedError(`${this.serverName}: no active transport to complete authorization into`);
         }
+        // The SDK normally calls state() before this hook. Keep a defensive path
+        // for direct callers too, and overwrite any caller-supplied value with the
+        // state issued by this provider.
+        const state = this.expectedState ?? this.state();
+        authorizationUrl.searchParams.set('state', state);
         this.browserLegSettled = Promise.withResolvers();
         let succeeded = false;
         try {
@@ -222,6 +250,7 @@ export class LoopbackOAuthClientProvider {
         this.callbackServer?.close(() => undefined);
         this.callbackServer = undefined;
         this.boundPort = undefined;
+        this.expectedState = undefined;
     }
     saveCodeVerifier(codeVerifier) {
         // The verifier only needs to survive the browser leg; keeping it out of
@@ -287,17 +316,41 @@ export class LoopbackOAuthClientProvider {
     async mutate(mutator) {
         const run = this.writeChain.then(async () => {
             await this.load();
+            const base = {
+                clientInformation: this.providerState.clientInformation,
+                tokens: this.providerState.tokens
+            };
             mutator(this.providerState);
             if (this.store === undefined)
                 return;
-            const record = {
-                kind: 'grant',
-                payload: {
-                    ...(this.providerState.clientInformation === undefined ? {} : { clientInformation: this.providerState.clientInformation }),
-                    ...(this.providerState.tokens === undefined ? {} : { tokens: this.providerState.tokens })
-                }
+            const desired = {
+                clientInformation: this.providerState.clientInformation,
+                tokens: this.providerState.tokens
+            };
+            const saved = await this.store.modifyRecord(this.recordKey, async (current) => {
+                const currentPayload = asMcpAuthRecord(current);
+                // Never replace a record owned by another credential provider just
+                // because this process raced it; the next read will observe it as
+                // absent and the caller can decide what to do.
+                if (current !== undefined && currentPayload === undefined)
+                    return current;
+                const payload = currentPayload ?? {};
+                const clientInformation = mergeDurableField(base.clientInformation, desired.clientInformation, payload.clientInformation);
+                const tokens = mergeDurableField(base.tokens, desired.tokens, payload.tokens);
+                const merged = {
+                    kind: 'grant',
+                    payload: {
+                        ...(clientInformation === undefined ? {} : { clientInformation }),
+                        ...(tokens === undefined ? {} : { tokens })
+                    }
+                };
+                return merged;
+            });
+            const savedPayload = asMcpAuthRecord(saved);
+            this.providerState = {
+                ...(savedPayload ?? {}),
+                ...(this.providerState.codeVerifier === undefined ? {} : { codeVerifier: this.providerState.codeVerifier })
             };
-            await this.store.modifyRecord(this.recordKey, () => Promise.resolve(record));
         });
         // A failed write must not poison the chain; the caller's rejection is the
         // signal, and the next write re-reads whatever is durable now.
@@ -317,7 +370,7 @@ export class LoopbackOAuthClientProvider {
             });
             server.on('error', error => {
                 this.clearCallbackTimer();
-                reject(new AuthorizationAbortedError(`${this.serverName}: loopback callback server failed: ${String(error)}`));
+                reject(new AuthorizationAbortedError(`${this.serverName}: loopback callback server failed: ${redactErrorMessage(String(error))}`));
             });
             server.listen(this.storage.callbackPort ?? 0, '127.0.0.1', () => {
                 const address = server.address();
@@ -343,19 +396,34 @@ export class LoopbackOAuthClientProvider {
         const url = new URL(request.url ?? '/', 'http://127.0.0.1');
         const oauthError = url.searchParams.get('error');
         const code = url.searchParams.get('code');
-        const respond = (status, message) => {
+        const respond = (status, message, closeServer = true) => {
             // Drain the request, then answer with a plain page the user can close.
             request.resume();
             request.socket.end(`HTTP/1.1 ${status} ${status === 200 ? 'OK' : 'Bad Request'}\r\n` + 'content-type: text/plain; charset=utf-8\r\nconnection: close\r\n\r\n' + `${message}\n`);
-            request.on('close', () => {
-                server.close(() => undefined);
-            });
+            if (closeServer) {
+                request.on('close', () => {
+                    server.close(() => undefined);
+                });
+            }
         };
+        // Keep the listener alive for malformed or forged callbacks so the real
+        // browser redirect can still complete the same authorization leg.
+        if (url.pathname !== '/callback') {
+            respond(404, 'Not an OAuth callback endpoint.', false);
+            return;
+        }
+        const expectedState = this.expectedState;
+        const callbackState = url.searchParams.get('state');
+        if (expectedState === undefined || callbackState !== expectedState) {
+            respond(400, 'Authorization callback carried an invalid state.', false);
+            return;
+        }
         this.clearCallbackTimer();
         this.callbackServer = undefined;
         this.boundPort = undefined;
+        this.expectedState = undefined;
         if (oauthError !== null) {
-            const description = url.searchParams.get('error_description') ?? '';
+            const description = redactErrorMessage(url.searchParams.get('error_description') ?? '');
             respond(400, `Authorization failed: ${oauthError}${description === '' ? '' : ` — ${description}`}`);
             reject(new AuthorizationAbortedError(`${this.serverName}: the authorization server returned "${oauthError}"${description === '' ? '' : ` (${description})`}`));
             return;

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

@@ -21,6 +21,7 @@ import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { assertSupportedJsonSchema } from './json-schema-subset.js';
 import { containsImage, extractText, prepareImageProjection } from './projection.js';
+import { redactErrorMessage } from '../mcp-redaction.js';
 /**
  * DeepSeek function-name contract: at most 64 characters. Wire-protocol
  * constant, not configuration.
@@ -122,7 +123,7 @@ export async function syncTools(client, host, opts, previous) {
         // sees either the full generation or none of it — never a partial set.
         for (const dispose of disposers.values())
             dispose();
-        host.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`);
+        host.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${redactErrorMessage(String(error))}`);
         if (opts.registrationFailure === 'throw')
             throw error;
         return new Map();

package/lib/runtime/mcp-config.js

@@ -4,16 +4,25 @@
  * The portable format is translated, not executed directly: stdio commands
  * resolve against the suite root (spec §7.2.1), `${PLUGIN_ROOT}` /
  * `${PLUGIN_DATA}` expand against the suite root and its data directory, and
- * every `${NAME}` — including ones inside a streamable-http `url` — expands
- * through the optional DSH credentials seam at mount time. Legacy HTTP+SSE
- * servers are supported by the market's own bridge (the host client had no
- * such transport); unrecognized shapes are still skipped with a per-server
- * reason.
+ * the child environment carries both variables (§9.1) with the data directory
+ * created before launch. Legacy HTTP+SSE servers are supported by the
+ * market's own bridge (the host client had no such transport); unrecognized
+ * shapes are still skipped with a per-server reason.
+ *
+ * Placeholder discipline follows the package's origin. A suite mounted from
+ * the portable v1 format (`portable: true`) is package data: §9.2 forbids any
+ * expansion beyond the two built-in variables, and per-server client policy
+ * (OAuth, tool lists, timeouts) comes from the `com.deepseek.harness`
+ * namespace instead of the `mcp.json` body. Dialect-native files and
+ * user-owned config keep the credential seam: every `${NAME}` — including
+ * ones inside a streamable-http `url` — expands through the optional DSH
+ * credentials resolver at mount time, and missing references fail closed per
+ * server instead of becoming empty strings.
  */
 import { createHash } from 'node:crypto';
-import { DEFAULT_TOOL_CALL_TIMEOUT_MS } from './mcp-client/config.js';
+import { DEFAULT_STARTUP_TIMEOUT_MS, DEFAULT_TOOL_CALL_TIMEOUT_MS } from './mcp-client/config.js';
 import { resolveCwd } from '../catalog/validate.js';
-import { qualifiedSuiteId } from '../catalog/paths.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';
 /** The max length the bridge accepts for a serverName. */
@@ -21,26 +30,10 @@ 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
- * request is created. Missing references fail closed per server instead of
- * becoming empty strings.
+ * Build one mount request per supported mcp.json server, expanding built-in
+ * variables (and, for user-owned data, `${NAME}` credential references)
+ * before a child process or HTTP request is created. Missing references fail
+ * closed per server instead of becoming empty strings.
  *
  * @param overrides user-owned per-server overrides (url/headers/env/args
  *   replacement plus enable/disable); applied before mount. Disabled servers
@@ -74,6 +67,141 @@ export async function toMcpMounts(suite, pluginDataRoot, overrides = {}, resolve
     }
     return { mounts, failures, credentialRefs: [...credentialRefs] };
 }
+/**
+ * Whether a suite's MCP declarations are package data under the portable
+ * format. Installed v1 suites are; the user's own `~/.agents/mcp.json`,
+ * project-native config, and every dialect-native file are user-owned data
+ * where `${NAME}` credential references stay resolvable.
+ */
+export function isPortableMcp(suite) {
+    return suite.dimension !== 'user' && suite.manifest.layout === 'agent-plugin-v1';
+}
+/**
+ * The `com.deepseek.harness` policy declared for one portable server.
+ * Server keys in the namespace match the server's own name in `mcp.json`;
+ * `serverKey` is that name at discovery time.
+ */
+export function namespaceMcpPolicy(suite, serverKey) {
+    return suite.manifest.harness?.mcpServers?.[serverKey];
+}
+/**
+ * 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.
+ *
+ * Portable v1 suites (`isPortableMcp`) carry package data: their credential
+ * reference list is empty by definition (§9.2 leaves unrecognized
+ * placeholder-like text literal), and client policy comes from the
+ * `com.deepseek.harness` namespace instead. Overrides applied by the user are
+ * user-owned data, so a reference a user typed into an override still
+ * resolves.
+ */
+export function effectiveMcpServers(suite, overrides = {}) {
+    const rows = [];
+    const portable = isPortableMcp(suite);
+    for (const [serverKey, source] of Object.entries(suite.mcp?.servers ?? {})) {
+        const override = overrides[serverKey];
+        const declared = namespaceMcpPolicy(suite, serverKey);
+        const policy = resolveMcpPolicy(declaredMcpPolicy(source, declared), override);
+        const connection = applyNamespaceAuth(applyOverride(source, override), declared);
+        const effective = applyMcpPolicy(connection, policy);
+        const credentialRefs = portable ? credentialRefsInServer(overrideValues(override)) : credentialRefsInServer(effective);
+        rows.push({ serverKey, server: effective, override, enabled: override?.enabled !== false, credentialRefs, policy });
+    }
+    return rows;
+}
+/** Credential references a user typed into their own override values. */
+function overrideValues(override) {
+    if (override === undefined)
+        return { type: 'stdio', command: '' };
+    return {
+        type: 'stdio',
+        command: '',
+        ...(override.args !== undefined ? { args: override.args } : {}),
+        ...(override.env !== undefined ? { env: override.env } : {}),
+        ...(override.headers !== undefined ? { headers: override.headers } : {}),
+        ...(override.url !== undefined ? { url: override.url, type: 'streamable-http' } : {})
+    };
+}
+/**
+ * The suite's declared per-server policy. The `com.deepseek.harness`
+ * namespace seat carries the policy a portable `mcp.json` has no room for and
+ * wins over an inline declaration; dialect-native files declare it inline.
+ */
+export function declaredMcpPolicy(server, policy) {
+    const enabledTools = policy?.enabledTools ?? server.enabledTools;
+    const disabledTools = policy?.disabledTools ?? server.disabledTools;
+    const startupTimeoutMs = policy?.startupTimeoutMs ?? server.startupTimeoutMs;
+    const toolCallTimeoutMs = policy?.toolCallTimeoutMs ?? server.toolCallTimeoutMs;
+    return {
+        ...(enabledTools === undefined ? {} : { enabledTools }),
+        ...(disabledTools === undefined ? {} : { disabledTools }),
+        ...(startupTimeoutMs === undefined ? {} : { startupTimeoutMs }),
+        ...(toolCallTimeoutMs === undefined ? {} : { toolCallTimeoutMs })
+    };
+}
+/**
+ * Bring the suite's declaration and the user's override together.
+ *
+ * A timeout is a plain override: the user's value wins, a declaration fills in
+ * when the user set none, and the built-in default stands behind both. Tool
+ * filtering only tightens: the effective deny list is the suite's entries
+ * unioned with the user's, and the suite's allow-list stands as declared, so a
+ * user cannot open a tool the suite left out.
+ */
+export function resolveMcpPolicy(declared, override) {
+    const enabledTools = dedupe(declared.enabledTools);
+    const suiteDisabledTools = dedupe(declared.disabledTools);
+    const disabledTools = dedupe([...(declared.disabledTools ?? []), ...(override?.disabledTools ?? [])]);
+    return {
+        ...(enabledTools === undefined ? {} : { enabledTools }),
+        ...(suiteDisabledTools === undefined ? {} : { suiteDisabledTools }),
+        ...(disabledTools === undefined ? {} : { disabledTools }),
+        toolCallTimeout: timeoutResolution(override?.toolCallTimeoutMs, declared.toolCallTimeoutMs, DEFAULT_TOOL_CALL_TIMEOUT_MS),
+        startupTimeout: timeoutResolution(override?.startupTimeoutMs, declared.startupTimeoutMs, DEFAULT_STARTUP_TIMEOUT_MS)
+    };
+}
+function timeoutResolution(user, suite, fallback) {
+    const effective = user ?? suite ?? fallback;
+    return {
+        user: user ?? null,
+        suite: suite ?? null,
+        effective,
+        source: user !== undefined ? 'user' : suite !== undefined ? 'suite' : 'default'
+    };
+}
+/** Apply one resolved policy onto a server, in the shape the bridge reads. */
+function applyMcpPolicy(server, policy) {
+    return {
+        ...server,
+        toolCallTimeoutMs: policy.toolCallTimeout.effective,
+        // An undeclared startup timeout stays absent: the built-in bridge applies
+        // its own default at connect time, and host compatibility mode, which
+        // cannot enforce one, keeps accepting the server.
+        ...(policy.startupTimeout.source === 'default' ? {} : { startupTimeoutMs: policy.startupTimeout.effective }),
+        ...(policy.enabledTools === undefined ? {} : { enabledTools: policy.enabledTools }),
+        ...(policy.disabledTools === undefined ? {} : { disabledTools: policy.disabledTools })
+    };
+}
+/**
+ * Apply the namespace policy's OAuth seat onto one server. A remote server
+ * keeps its OAuth opt-out from the namespace; a policy on a portable server
+ * also supplies the credential seam the portable file may not declare.
+ */
+function applyNamespaceAuth(server, policy) {
+    if (policy?.auth === undefined || server.type === 'stdio')
+        return server;
+    return { ...server, auth: { enabled: policy.auth.enabled, ...(policy.auth.scope === undefined ? {} : { scope: policy.auth.scope }) } };
+}
+/** Deduplicate a tool-name list, preserving declaration order; an empty result is absent. */
+function dedupe(values) {
+    if (values === undefined)
+        return undefined;
+    const names = [...new Set(values.filter(name => name !== ''))];
+    return names.length > 0 ? names : undefined;
+}
 /** Find external credential references used by one MCP server definition. */
 export function credentialRefsInServer(server) {
     const values = [];
@@ -96,9 +224,11 @@ export function credentialRefsInServer(server) {
     return [...refs].sort();
 }
 async function toResolvedMount(suite, serverKey, server, pluginDataRoot, resolver) {
+    const portable = isPortableMcp(suite);
+    const dataDir = suiteDataDir(pluginDataRoot, suite.sourceId, suite.id);
     if (server.type === 'sse') {
         // The market bridge supports the legacy HTTP+SSE transport natively.
-        const expand = expander(suite, joinInside(pluginDataRoot, qualifiedSuiteId(suite.sourceId, suite.id)), resolver);
+        const expand = expander(suite, dataDir, resolver, portable);
         const url = await expand.one(server.url);
         const headers = await expand.map(server.headers ?? {});
         const missing = unique([...url.missing, ...headers.missing]);
@@ -115,7 +245,7 @@ async function toResolvedMount(suite, serverKey, server, pluginDataRoot, resolve
         };
         return { request: { suiteId: qualifiedSuiteId(suite.sourceId, suite.id), serverKey, config: sseConfig } };
     }
-    const expand = expander(suite, joinInside(pluginDataRoot, qualifiedSuiteId(suite.sourceId, suite.id)), resolver);
+    const expand = expander(suite, dataDir, resolver, portable);
     const serverName = deriveServerName(suite.id, serverKey);
     if (server.type === 'stdio') {
         const args = await expand.all(server.args ?? []);
@@ -133,8 +263,10 @@ async function toResolvedMount(suite, serverKey, server, pluginDataRoot, resolve
                     serverName,
                     command: server.command.startsWith('./') ? joinInside(suite.root, server.command.slice(2)) : server.command,
                     args: args.values,
-                    env: env.values,
-                    cwd: resolveCwd(cwd.value, suite.root, joinInside(pluginDataRoot, qualifiedSuiteId(suite.sourceId, suite.id))),
+                    // §9.1: configured env overlays the base, then the client sets
+                    // PLUGIN_ROOT and PLUGIN_DATA, replacing same-name entries.
+                    env: { ...env.values, PLUGIN_ROOT: suite.root, PLUGIN_DATA: dataDir },
+                    cwd: resolveCwd(cwd.value, suite.root, dataDir),
                     ...bridgePolicy(server),
                     failOnStartupError: true
                 }
@@ -177,13 +309,24 @@ function mapAuth(auth) {
 function bridgePolicy(server) {
     return {
         toolCallTimeoutMs: server.toolCallTimeoutMs ?? DEFAULT_TOOL_CALL_TIMEOUT_MS,
+        // Only a DECLARED startup timeout is a policy: host compatibility mode
+        // cannot enforce one, so an undeclared server stays enforceable there and
+        // the built-in bridge applies its own default at connect time.
         ...(server.startupTimeoutMs === undefined ? {} : { startupTimeoutMs: server.startupTimeoutMs }),
         ...(server.enabledTools === undefined ? {} : { enabledTools: server.enabledTools }),
         ...(server.disabledTools === undefined ? {} : { disabledTools: server.disabledTools })
     };
 }
-/** Per-mount expansion context; credential lookups are memoized per call. */
-function expander(suite, pluginData, resolver) {
+/**
+ * Per-mount expansion context.
+ *
+ * Portable package data (`portable: true`) honors §9.2: only the two built-in
+ * variables expand, single pass, and unrecognized placeholder-like text stays
+ * literal — the credential resolver is never consulted. User-owned data
+ * keeps the `${NAME}` seam, with `${NAME:-default}` fallbacks and missing
+ * references reported.
+ */
+function expander(suite, pluginData, resolver, portable) {
     // Promise-valued cache: concurrent expansions of the same reference share
     // one in-flight lookup, so a config using a token twice resolves it once.
     const inflight = new Map();
@@ -211,15 +354,19 @@ function expander(suite, pluginData, resolver) {
                 replacement = suite.root;
             else if (PLUGIN_DATA_VARIABLES.has(name))
                 replacement = pluginData;
-            else
+            else if (!portable)
                 replacement = (await lookup(name))?.value;
             if (replacement === undefined || replacement === '') {
                 if (fallback !== undefined && fallback !== '')
                     replacement = fallback;
-                else {
+                else if (!portable) {
                     missing.push(name);
                     replacement = '';
                 }
+                else {
+                    // §9.2: unrecognized placeholder-like text stays literal.
+                    replacement = match[0];
+                }
             }
             output += replacement;
             cursor = index + match[0].length;

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

@@ -1,7 +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, validateAgainstSchema, validateMcpJson } from '../catalog/validate.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';
@@ -44,13 +44,16 @@ export async function loadUserMcpSuite(agentsRoot) {
         errors
     };
 }
+/**
+ * The user's own declaration file is local data, not a distributable package:
+ * keys this client does not know ride along untouched rather than failing the
+ * whole file, and the closed-set rule the package schema applies to suites
+ * does not apply here.
+ */
 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(agentsRoot, raw);
+    const result = await validateMcpJson(agentsRoot, raw, { packageRules: false });
     if (result.config === undefined || result.errors.length > 0)
-        throw new Error(result.errors.join('; '));
+        throw new Error(`invalid MCP configuration: ${result.errors.join('; ')}`);
     return result.config;
 }
 /** Add one service atomically; reject collisions and malformed config before writing. */
@@ -71,3 +74,43 @@ export async function addUserMcpServer(agentsRoot, name, server) {
 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 };
+}