dsh-agent-plugins-market 0.6.2 → 0.7.1

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

@@ -8,9 +8,16 @@
  *
  * @module runtime/mcp-client/config
  */
-export { RECONNECT_DEFAULTS } from './connection.js';
 /** Default timeout for individual MCP tool calls (ms). */
 export const DEFAULT_TOOL_CALL_TIMEOUT_MS = 60_000;
+/**
+ * How long one connection attempt may spend initializing (ms). A server that
+ * never answers would otherwise hold its process, transport and browser leg
+ * until the SDK's own 60-second request default expired; a working server
+ * handshakes well under a second, and a genuinely slow one can declare its own
+ * `startupTimeoutMs`.
+ */
+export const DEFAULT_STARTUP_TIMEOUT_MS = 10_000;
 /** Valid `serverName`, kept below the public tool-name budget. */
 export const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
 /**

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

@@ -23,8 +23,10 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
 import { MAX_TIMER_DELAY_MS } from './host-seams.js';
+import { PLUGIN_NAME, PLUGIN_VERSION } from './plugin-identity.js';
 import { createTransport } from './transport.js';
 import { syncTools } from './tools.js';
+import { DEFAULT_STARTUP_TIMEOUT_MS } from './config.js';
 /** Defaults shared by the config and {@link resolveReconnectPolicy}. */
 export const RECONNECT_DEFAULTS = Object.freeze({
     enabled: true,
@@ -88,9 +90,11 @@ export function startConnection(host, config, policy, credentials) {
         registrationFailure: 'contain',
         serverName: config.serverName,
         toolCallTimeoutMs: config.toolCallTimeoutMs,
+        // Every attempt is bounded: an unreachable server must not hold its
+        // process, transport and browser leg while nothing can arrive.
+        startupTimeoutMs: config.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS,
         ...(config.enabledTools === undefined ? {} : { enabledTools: config.enabledTools }),
-        ...(config.disabledTools === undefined ? {} : { disabledTools: config.disabledTools }),
-        ...(config.startupTimeoutMs === undefined ? {} : { startupTimeoutMs: config.startupTimeoutMs })
+        ...(config.disabledTools === undefined ? {} : { disabledTools: config.disabledTools })
     };
     // The initial sync uses 'throw' when failOnStartupError is configured, so
     // a registration conflict propagates to the startup-await path. Re-syncs
@@ -197,7 +201,7 @@ export function startConnection(host, config, policy, credentials) {
      * @param startup - Whether this is the bridge's activation attempt.
      */
     async function connectGeneration(startup) {
-        const generation = new Client({ name: 'dsh-agent-plugins-market', version: '0.1.0' }, { capabilities: {} });
+        const generation = new Client({ name: PLUGIN_NAME, version: PLUGIN_VERSION }, { capabilities: {} });
         const closed = Promise.withResolvers();
         let attemptSettled = false;
         let closeObserved = false;
@@ -228,14 +232,36 @@ export function startConnection(host, config, policy, credentials) {
                     host.logger.error(`${label}: tool re-sync failed: ${String(error)}`);
             }
         });
+        /**
+         * Retire a generation whose attempt failed: close it, wait for the
+         * transport's own close signal, then hand it to the disconnect path. A
+         * generation that will not close stops reconnection outright — respawning
+         * would overlap the server process still running behind it.
+         */
+        async function teardownFailedAttempt() {
+            try {
+                await generation.close();
+            }
+            catch {
+                /* transport already gone */
+            }
+            const quiesced = hasClosed() || (await waitForClose(closed.promise));
+            attemptSettled = true;
+            if (!isCurrent(generation))
+                return;
+            if (quiesced) {
+                generationDown(generation);
+                return;
+            }
+            client = undefined;
+            clientClosed = undefined;
+            host.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
+        }
         const { transport, oauthProvider } = createTransport(config, credentials, (message) => {
             host.logger.info(message);
         });
         try {
-            if (config.startupTimeoutMs === undefined)
-                await generation.connect(transport);
-            else
-                await generation.connect(transport, { timeout: config.startupTimeoutMs });
+            await generation.connect(transport, { timeout: opts.startupTimeoutMs });
             if (hasClosed()) {
                 attemptSettled = true;
                 generationDown(generation);
@@ -261,11 +287,9 @@ export function startConnection(host, config, policy, credentials) {
                 attemptSettled = true;
                 if (!isCurrent(generation))
                     return;
-                if (hasClosed()) {
-                    generationDown(generation);
-                    return;
-                }
-                if (!legSettled) {
+                // The leg failed, or the transport closed while it ran: no generation
+                // is left to finish establishing.
+                if (hasClosed() || !legSettled) {
                     generationDown(generation);
                     return;
                 }
@@ -277,20 +301,7 @@ export function startConnection(host, config, policy, credentials) {
                 catch (syncError) {
                     if (isCurrent(generation))
                         host.logger.warn(`${label}: tool sync after authorization failed: ${String(syncError)}`);
-                    try {
-                        await generation.close();
-                    }
-                    catch {
-                        /* transport already gone */
-                    }
-                    const quiescedSync = hasClosed() || (await waitForClose(closed.promise));
-                    if (!quiescedSync) {
-                        client = undefined;
-                        clientClosed = undefined;
-                        host.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes`);
-                        return;
-                    }
-                    generationDown(generation);
+                    await teardownFailedAttempt();
                     return;
                 }
                 if (hasClosed()) {
@@ -304,23 +315,7 @@ export function startConnection(host, config, policy, credentials) {
                     host.logger.info(`${label}: authorized and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
                 return;
             }
-            try {
-                await generation.close();
-            }
-            catch {
-                /* transport already gone */
-            }
-            const quiesced = hasClosed() || (await waitForClose(closed.promise));
-            attemptSettled = true;
-            if (!isCurrent(generation))
-                return;
-            if (!quiesced) {
-                client = undefined;
-                clientClosed = undefined;
-                host.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
-                return;
-            }
-            generationDown(generation);
+            await teardownFailedAttempt();
             return;
         }
         attemptSettled = true;

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/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

@@ -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)` }];
+}