@hzxwonder/dsh-mcp 0.4.0 → 0.5.0

package/src/doctor.js

@@ -0,0 +1,230 @@
+import { constants } from 'node:fs';
+import { access, readFile, stat } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { isDeepStrictEqual, parseArgs, promisify } from 'node:util';
+import { parse } from 'smol-toml';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const execFileAsync = promisify(execFile);
+const requiredTool = 'delegate_to_deepseek';
+const reloadHint = 'This checks a new MCP connection, not the running Codex Desktop connection. If dsh is absent there, fully quit and reopen Codex, then start a new chat and inspect its MCP status. No client was restarted.';
+const authHint = 'Auth unsupported is normal for a local stdio MCP server; it does not report the worker API key status. No model/API request was made.';
+const rootHint = 'Each delegation still needs an absolute project_root and explicit thinking_effort; registration does not choose a workspace.';
+
+
+async function executablePath(command, env, cwd = process.cwd()) {
+  const candidates = isAbsolute(command) || command.includes('/') || command.includes('\\')
+    ? [resolve(cwd, command)]
+    : (env.PATH || '').split(delimiter).filter(Boolean).map((directory) => resolve(cwd, directory, command));
+  for (const candidate of candidates) {
+    try {
+      await access(candidate, constants.X_OK);
+      if ((await stat(candidate)).isFile()) return candidate;
+    } catch { /* Try the next PATH entry. */ }
+  }
+  return null;
+}
+
+function pathHint(path) {
+  return /(?:^|[/\\])(?:_npx|node_modules)(?:[/\\]|$)/.test(path)
+    ? 'The registered package/cache path is stale or incomplete. Rerun dsh-mcp setup from the current installed version to replace the old cached path.'
+    : 'Rerun dsh-mcp setup from an existing installation to refresh the absolute executable and server script paths.';
+}
+
+// Report only diagnostic categories, never arbitrary child output, config values, or prompts.
+function startupDetail(error, stderr = '') {
+  const text = `${error?.code || ''} ${error?.message || ''}\n${stderr}`;
+  const codes = [...new Set(text.match(/\b(?:ERR_MODULE_NOT_FOUND|ERR_REQUIRE_ESM|ERR_PACKAGE_PATH_NOT_EXPORTED|ERR_DLOPEN_FAILED|ERR_UNKNOWN_FILE_EXTENSION|ERR_INVALID_ARG_TYPE|ERR_ACCESS_DENIED|ERR_INVALID_PACKAGE_CONFIG|MODULE_NOT_FOUND|ENOENT|EACCES|ENOTDIR|SyntaxError|ReferenceError|TypeError)\b/g) || [])];
+  if (codes.length) return codes.slice(0, 5).join(', ');
+  if (/timed?\s*out|timeout|abort/i.test(text)) return 'startup/discovery timed out';
+  if (/connection closed|EPIPE/i.test(text)) return 'connection closed during startup/discovery';
+  if (/JSON|Unexpected token/i.test(text)) return 'invalid MCP JSON output';
+  return 'server startup or MCP protocol error';
+}
+
+async function inspectCodexCli(entry, configPath, timeoutMs) {
+  const command = await executablePath('codex', getDefaultEnvironment());
+  if (!command) return { available: false, ok: null, enabled: null, error: null };
+  try {
+    const { stdout } = await execFileAsync(command, ['mcp', 'get', 'dsh', '--json'], {
+      env: { ...process.env, CODEX_HOME: dirname(configPath) },
+      timeout: timeoutMs, maxBuffer: 1024 * 1024, windowsHide: true,
+    });
+    const effective = JSON.parse(stdout);
+    const transport = effective.transport;
+    const matches = effective.enabled !== false && transport?.type === 'stdio'
+      && transport.command === entry.command
+      && JSON.stringify(transport.args || []) === JSON.stringify(entry.args || [])
+      && (transport.cwd || null) === (entry.cwd || null)
+      && isDeepStrictEqual(transport.env || {}, entry.env || {})
+      && isDeepStrictEqual(transport.env_vars || [], entry.env_vars || [])
+      && !effective.disabled_tools?.includes(requiredTool)
+      && (!effective.enabled_tools || effective.enabled_tools.includes(requiredTool));
+    return {
+      available: true, ok: matches, enabled: effective.enabled !== false,
+      error: matches ? null : 'The Codex CLI effective dsh entry is disabled or differs from this stdio registration.',
+    };
+  } catch (error) {
+    return { available: true, ok: false, enabled: null, error: `Codex CLI could not read the effective dsh registration (${startupDetail(error)}).` };
+  }
+}
+
+export async function inspectRegistration({
+  configPath = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'config.toml'),
+  timeoutMs = 12000,
+  checkCodexCli = true,
+} = {}) {
+  const result = {
+    ok: false, configPath: resolve(configPath), serverVersion: null, tools: [],
+    codexCli: null, error: null, hints: [authHint, rootHint],
+  };
+  let client;
+  let transport;
+  let stderr = '';
+  try {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error('Provide a positive timeoutMs.');
+    let config;
+    try {
+      config = parse(await readFile(result.configPath, 'utf8'));
+    } catch (error) {
+      throw new Error(error.code === 'ENOENT'
+        ? 'Codex config.toml does not exist. Run dsh-mcp setup for this CODEX_HOME.'
+        : 'Codex config.toml cannot be read or parsed. Check its permissions and TOML syntax.');
+    }
+    const entry = config.mcp_servers?.dsh;
+    if (!entry || typeof entry !== 'object') throw new Error('No mcp_servers.dsh entry exists. Run dsh-mcp setup for this CODEX_HOME.');
+    if (entry.enabled === false) throw new Error('The dsh MCP entry is disabled. Enable mcp_servers.dsh in the selected Codex config.');
+    if ((entry.disabled_tools !== undefined && (!Array.isArray(entry.disabled_tools) || entry.disabled_tools.some((name) => typeof name !== 'string')))
+      || (entry.enabled_tools !== undefined && (!Array.isArray(entry.enabled_tools) || entry.enabled_tools.some((name) => typeof name !== 'string')))) {
+      throw new Error('The dsh MCP enabled_tools and disabled_tools must be arrays of tool names.');
+    }
+    if (entry.disabled_tools?.includes(requiredTool) || (entry.enabled_tools && !entry.enabled_tools.includes(requiredTool))) {
+      throw new Error('Codex tool filters hide delegate_to_deepseek. Remove it from disabled_tools and include it in enabled_tools, if configured.');
+    }
+    if (typeof entry.command !== 'string' || !entry.command.trim() || entry.url) {
+      throw new Error('The dsh MCP entry must use a local stdio command. Rerun dsh-mcp setup.');
+    }
+    if (entry.args !== undefined && (!Array.isArray(entry.args) || entry.args.some((arg) => typeof arg !== 'string'))) {
+      throw new Error('The dsh MCP command args must be an array of strings. Rerun dsh-mcp setup.');
+    }
+    if (entry.env !== undefined && (!entry.env || typeof entry.env !== 'object' || Array.isArray(entry.env)
+      || Object.values(entry.env).some((value) => typeof value !== 'string'))) {
+      throw new Error('The dsh MCP env entries must be strings. Check the Codex config.');
+    }
+    if (entry.env_vars !== undefined && (!Array.isArray(entry.env_vars) || entry.env_vars.some((name) => typeof name !== 'string'))) {
+      throw new Error('The dsh MCP env_vars must be an array of variable names. Check the Codex config.');
+    }
+    if (entry.cwd !== undefined && (typeof entry.cwd !== 'string' || !isAbsolute(entry.cwd))) {
+      throw new Error('The dsh MCP cwd must be an absolute directory path. Rerun dsh-mcp setup.');
+    }
+    const cwd = entry.cwd || process.cwd();
+    try {
+      if (!(await stat(cwd)).isDirectory()) throw new Error();
+    } catch {
+      throw new Error('The dsh MCP working directory is missing or inaccessible. Fix cwd or rerun setup.');
+    }
+    const env = { ...getDefaultEnvironment() };
+    for (const name of entry.env_vars || []) {
+      if (process.env[name] !== undefined) env[name] = process.env[name];
+    }
+    Object.assign(env, entry.env || {});
+    const command = await executablePath(entry.command, env, cwd);
+    if (!command) {
+      result.hints.push(pathHint(entry.command));
+      throw new Error('The registered dsh executable is missing or not executable. Check its absolute path and the client PATH.');
+    }
+    if (/^node(?:js)?(?:\.exe)?$/.test(basename(command))) {
+      const args = entry.args || [];
+      if (!args.some((arg) => ['-e', '--eval', '-p', '--print'].includes(arg))) {
+        const script = args.find((arg) => !arg.startsWith('-') && /\.[cm]?js$/.test(arg));
+        if (script) {
+          try {
+            const path = resolve(cwd, script);
+            await access(path, constants.R_OK);
+            if (!(await stat(path)).isFile()) throw new Error();
+          } catch {
+            result.hints.push(pathHint(script));
+            throw new Error('The registered dsh server script is missing or unreadable. Its source checkout or package cache may have moved.');
+          }
+        }
+      }
+    }
+    if (checkCodexCli) result.codexCli = await inspectCodexCli(entry, result.configPath, timeoutMs);
+    client = new Client({ name: 'dsh-mcp-doctor', version: '1' });
+    transport = new StdioClientTransport({ command, args: entry.args || [], cwd, env, stderr: 'pipe' });
+    transport.stderr.on('data', (chunk) => {
+      if (stderr.length < 8192) stderr += chunk.toString().slice(0, 8192 - stderr.length);
+    });
+    const signal = AbortSignal.timeout(timeoutMs);
+    await client.connect(transport, { signal, timeout: timeoutMs });
+    const version = client.getServerVersion()?.version;
+    result.serverVersion = typeof version === 'string' && /^[\w.+-]{1,100}$/.test(version) ? version : null;
+    const names = new Set();
+    const cursors = new Set();
+    let cursor;
+    do {
+      const page = await client.listTools(cursor ? { cursor } : undefined, { signal, timeout: timeoutMs });
+      for (const tool of page.tools) {
+        if (/^[\w.-]{1,128}$/.test(tool.name)) names.add(tool.name);
+      }
+      cursor = page.nextCursor;
+      if (cursor && cursors.has(cursor)) throw new Error('MCP tools/list repeated a pagination cursor.');
+      if (cursor) cursors.add(cursor);
+    } while (cursor);
+    result.tools = [...names].sort();
+    if (!names.has(requiredTool)) throw new Error('The MCP server initialized but did not expose delegate_to_deepseek. Rerun setup using the current dsh-mcp package.');
+    if (result.codexCli?.ok === false) throw new Error(result.codexCli.error);
+    result.ok = true;
+    result.hints.push(reloadHint);
+    if (result.codexCli?.available === false) result.hints.push('The global codex CLI is not installed or not on PATH. This does not prevent a healthy SDK/Desktop stdio installation.');
+  } catch (error) {
+    result.error = client
+      ? `MCP initialize/tools discovery failed (${startupDetail(error, stderr)}).`
+      : error.message;
+    if (client && /did not expose|pagination cursor|Codex CLI/.test(error.message)) result.error = error.message;
+    result.hints.push('After correcting registration/startup errors, rerun dsh-mcp doctor. A saved config file alone does not prove Codex loaded the server.');
+    if (client) result.hints.push('Check the registered package dependencies and runtime version; if its npm cache was removed, rerun dsh-mcp setup from the current package.');
+  } finally {
+    if (transport) await transport.close().catch(() => {});
+    if (client) await client.close().catch(() => {});
+  }
+  return result;
+}
+
+export async function runDoctor() {
+  const { values } = parseArgs({
+    options: {
+      home: { type: 'string' }, 'codex-home': { type: 'string' },
+      json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    },
+  });
+  if (values.help) {
+    console.log('Usage: dsh-mcp doctor [--codex-home PATH] [--home PATH] [--json]\n\nCheck the registered stdio command with MCP initialize and tools/list, without an inference request.\nDefaults to $CODEX_HOME/config.toml or ~/.codex/config.toml. --home checks the registered --dsh-home.\nThis does not inspect or restart the running Codex Desktop connection.');
+    return;
+  }
+  const configPath = join(resolve(values['codex-home'] || process.env.CODEX_HOME || join(homedir(), '.codex')), 'config.toml');
+  const result = await inspectRegistration({ configPath });
+  if (values.home && result.ok) {
+    const entry = parse(await readFile(configPath, 'utf8')).mcp_servers.dsh;
+    const index = (entry.args || []).indexOf('--dsh-home');
+    if (index < 0 || !entry.args[index + 1] || resolve(entry.cwd || process.cwd(), entry.args[index + 1]) !== resolve(values.home)) {
+      result.ok = false;
+      result.error = 'The registered --dsh-home differs from --home. Rerun setup with the intended --home and --codex-home.';
+    }
+  }
+  if (values.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`Codex config: ${result.configPath}`);
+    console.log(`MCP registration: ${result.ok ? 'healthy (initialize + tools/list succeeded)' : 'unhealthy'}`);
+    if (result.serverVersion) console.log(`Server version: ${result.serverVersion}`);
+    console.log(`Tools: ${result.tools.join(', ') || '(none discovered)'}`);
+    if (result.codexCli) console.log(`Codex CLI effective config: ${!result.codexCli.available ? 'not installed (optional)' : result.codexCli.ok ? 'matches' : 'failed'}`);
+    if (result.error) console.log(`Error: ${result.error}`);
+    for (const hint of result.hints) console.log(`- ${hint}`);
+  }
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}

package/src/provider.js

@@ -1,11 +1,31 @@
-export const DEFAULT_BASE_URL = 'https://api.deepseek.com/anthropic';
+import { stripVTControlCharacters } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { createModels, createProvider } from '@earendil-works/pi-ai/models';
+import { getBuiltinModels, getBuiltinProviders } from '@earendil-works/pi-ai/providers/all';
+import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy';
+import { openAIResponsesApi } from '@earendil-works/pi-ai/api/openai-responses.lazy';
+import { anthropicMessagesApi } from '@earendil-works/pi-ai/api/anthropic-messages.lazy';
 
-export function normalizeBaseUrl(value = DEFAULT_BASE_URL) {
-  if (typeof value !== 'string' || /[\r\n\0]/.test(value)) {
-    throw new Error('Base URL must be one HTTP or HTTPS URL without line breaks.');
+export const PROTOCOLS = Object.freeze([
+  { id: 'chat-completions', label: 'OpenAI Chat Completions — POST /chat/completions', defaultBaseUrl: 'https://api.deepseek.com/v1', api: 'openai-completions' },
+  { id: 'responses', label: 'OpenAI Responses (Codex) — POST /responses', defaultBaseUrl: 'https://api.openai.com/v1', api: 'openai-responses' },
+  { id: 'anthropic', label: 'Anthropic Messages — POST /v1/messages', defaultBaseUrl: 'https://api.anthropic.com', api: 'anthropic-messages' },
+]);
+export const DEFAULT_PROTOCOL = 'chat-completions';
+export const DEFAULT_BASE_URL = PROTOCOLS[0].defaultBaseUrl;
+const LEGACY_BASE_URL = 'https://api.deepseek.com/anthropic';
+const EFFORTS = ['off', 'low', 'high', 'max'];
+const CONTROLS = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+const preferredProviders = ['deepseek', 'openai', 'anthropic'];
+const catalog = [...preferredProviders, ...getBuiltinProviders().filter((provider) => !preferredProviders.includes(provider))]
+  .flatMap((provider) => getBuiltinModels(provider));
+
+export function normalizeBaseUrl(value = DEFAULT_BASE_URL, fallback = DEFAULT_BASE_URL) {
+  if (typeof value !== 'string' || CONTROLS.test(value)) {
+    throw new Error('Base URL must be one HTTP or HTTPS URL without control characters.');
   }
   let url;
-  try { url = new URL(value.trim() || DEFAULT_BASE_URL); }
+  try { url = new URL(value.trim() || fallback); }
   catch { throw new Error('Base URL must be an absolute HTTP or HTTPS URL.'); }
   if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
     throw new Error('Base URL must use HTTP or HTTPS without credentials, a query, or a fragment.');
@@ -23,3 +43,279 @@ export function parseProviderSettings(text) {
   }
   return settings;
 }
+
+function modelId(value) {
+  if (typeof value !== 'string' || !value.trim() || value !== value.trim() || value.length > 512 || CONTROLS.test(value)) {
+    throw new Error('Model ID must be nonempty, at most 512 characters, and contain no control characters or surrounding whitespace.');
+  }
+  return value;
+}
+
+export function resolveProviderSettings(input = {}, { legacy = false } = {}) {
+  const protocol = input.protocol ?? (legacy ? 'anthropic' : DEFAULT_PROTOCOL);
+  const definition = PROTOCOLS.find((item) => item.id === protocol);
+  if (!definition) throw new Error('Protocol must be chat-completions, responses, or anthropic.');
+  const fallback = legacy && input.protocol == null ? LEGACY_BASE_URL : definition.defaultBaseUrl;
+  return {
+    protocol,
+    baseUrl: normalizeBaseUrl(input.baseUrl ?? fallback, fallback),
+    model: modelId(input.model ?? 'deepseek-flash'),
+  };
+}
+
+function requireApiKey(apiKey) {
+  if (typeof apiKey !== 'string' || !apiKey.trim() || CONTROLS.test(apiKey)) {
+    throw new Error('A nonempty API key without control characters is required.');
+  }
+}
+
+function boundedSignal(signal, milliseconds) {
+  const timeout = AbortSignal.timeout(milliseconds);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+async function readModelPage(response) {
+  if (response.status >= 300 && response.status < 400) {
+    await response.body?.cancel();
+    throw new Error('Model discovery refused a redirect; use the provider’s final Base URL.');
+  }
+  if (!response.ok) {
+    await response.body?.cancel();
+    const detail = [401, 403].includes(response.status) ? ' Credentials were rejected or lack model-list permission.' : '';
+    throw new Error(`Model discovery failed (HTTP ${response.status}).${detail}`);
+  }
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of response.body ?? []) {
+    bytes += chunk.length;
+    if (bytes > 2 * 1024 * 1024) throw new Error('Model discovery returned an oversized response.');
+    chunks.push(chunk);
+  }
+  let page;
+  try { page = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw new Error('Model discovery did not return a valid JSON model list.'); }
+  if (!page || !Array.isArray(page.data)) throw new Error('Model discovery did not return a data array.');
+  return page;
+}
+
+export async function discoverModels({ protocol, baseUrl, apiKey, signal }) {
+  const settings = resolveProviderSettings({ protocol, baseUrl });
+  requireApiKey(apiKey);
+  const url = new URL(settings.baseUrl);
+  const anthropic = settings.protocol === 'anthropic';
+  // The official DSH Messages adapter lists DeepSeek models at /models on this same origin.
+  const deepseek = anthropic && url.origin === 'https://api.deepseek.com';
+  url.pathname = deepseek ? '/models' : `${url.pathname.replace(/\/+$/, '')}${anthropic && !url.pathname.endsWith('/v1') ? '/v1' : ''}/models`;
+  const headers = anthropic ? { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' } : { Authorization: `Bearer ${apiKey}` };
+  const requestSignal = boundedSignal(signal, 15000);
+  const models = new Map();
+  const cursors = new Set();
+  try {
+    for (let count = 0; count < 100; count++) {
+      const page = await readModelPage(await fetch(url, { headers, signal: requestSignal, redirect: 'manual' }));
+      if (anthropic && !deepseek && page.has_more !== undefined && typeof page.has_more !== 'boolean') {
+        throw new Error('Model discovery returned invalid pagination.');
+      }
+      for (const entry of page.data) {
+        if (!entry || typeof entry !== 'object') throw new Error('Model discovery returned an invalid model entry.');
+        const id = modelId(entry.id);
+        const name = typeof (entry.display_name ?? entry.name) === 'string'
+          ? stripVTControlCharacters(entry.display_name ?? entry.name).replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '').slice(0, 256).trim() : '';
+        models.set(id, name ? { id, name } : { id });
+      }
+      if (!anthropic || deepseek || page.has_more !== true) return [...models.values()];
+      const cursor = modelId(page.last_id);
+      if (!page.data.length || cursors.has(cursor)) throw new Error('Model discovery returned invalid pagination.');
+      cursors.add(cursor);
+      url.searchParams.set('after_id', cursor);
+    }
+    throw new Error('Model discovery exceeded its pagination limit.');
+  } catch (error) {
+    if (requestSignal.aborted) throw new Error(signal?.aborted ? 'Model discovery cancelled.' : 'Model discovery timed out.');
+    // Never relay provider bodies, fetch causes, URLs, or credential-bearing headers.
+    if (/^(Model discovery|Model ID)/.test(error.message)) throw error;
+    throw new Error('Model discovery could not reach the selected endpoint. Check the Base URL and network.');
+  }
+}
+
+function describeRuntime(settings) {
+  const definition = PROTOCOLS.find((item) => item.id === settings.protocol);
+  const deepseekModel = catalog.find((item) => item.provider === 'deepseek' && item.id === settings.model);
+  const direct = settings.protocol === 'anthropic' && deepseekModel !== undefined;
+  const known = direct ? deepseekModel : catalog.find((item) => item.id === settings.model && item.api === definition.api);
+  const thinkingEfforts = known?.reasoning ? EFFORTS.filter((effort) => {
+    const wire = known.thinkingLevelMap?.[effort];
+    return wire !== null && (effort !== 'max' || wire !== undefined);
+  }) : ['off'];
+  if (!thinkingEfforts.length) throw new Error('The selected model has no supported off, low, high, or max effort in the installed metadata.');
+  const route = direct ? 'deepseek-official' : known?.provider ?? 'dsh-mcp';
+  const reasoningEfforts = known?.reasoning ? Object.fromEntries(thinkingEfforts.map((effort) => [effort, known.thinkingLevelMap?.[effort] ?? (effort === 'off' ? null : effort)])) : false;
+  const model = {
+    id: settings.model,
+    ...(known ? { name: known.name, contextWindow: known.contextWindow, input: known.input } : {}),
+    reasoningEfforts,
+  };
+  const compat = !known && settings.protocol === 'chat-completions'
+    ? { supportsStore: false, supportsDeveloperRole: false, maxTokensField: 'max_tokens', supportsStrictMode: false } : undefined;
+  const profile = {
+    apiKeyEnv: 'DEEPSEEK_API_KEY', api: definition.api,
+    baseURL: settings.protocol === 'anthropic' ? settings.baseUrl.replace(/\/v1$/, '') : settings.baseUrl,
+    models: [model], defaultContextWindow: 32768, defaultMaxTokens: 4096,
+    ...(compat ? { compat } : {}),
+  };
+  const directProfile = direct ? {
+    apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: settings.baseUrl,
+    models: [{ id: settings.model, name: known.name, contextWindow: known.contextWindow, inputModalities: known.input }],
+  } : {};
+  return { route, known, profile, directProfile, thinkingEfforts };
+}
+
+export function buildProviderRuntime(input, apiKey) {
+  const settings = resolveProviderSettings(input);
+  if (apiKey !== undefined) requireApiKey(apiKey);
+  const { route, known, profile, directProfile, thinkingEfforts } = describeRuntime(settings);
+  const contextWindow = known?.contextWindow ?? profile.defaultContextWindow;
+  const headroomTokens = Math.max(1, Math.floor(contextWindow / 8));
+  const compaction = contextWindow < 131072 ? { headroomTokens, maxTokens: Math.min(4096, headroomTokens) } : {};
+  return {
+    protocol: settings.protocol, model: settings.model, route, thinkingEfforts,
+    env: {
+      ...(apiKey === undefined ? {} : { DEEPSEEK_API_KEY: apiKey }),
+      DEEPSEEK_BASE_URL: settings.baseUrl,
+      DSH_MCP_PROTOCOL: settings.protocol, DSH_MCP_MODEL: settings.model, DSH_MCP_PROVIDER: route,
+      DSH_MCP_PI_PLUGIN: !known?.reasoning && route !== 'deepseek-official' ? fileURLToPath(import.meta.url) : '@deepseek-ai/dsh-llm-pi-ai',
+      DSH_MCP_PI_PROVIDERS: JSON.stringify(route === 'deepseek-official' ? {} : { [route]: profile }),
+      DSH_MCP_DEEPSEEK_PROFILE: JSON.stringify(directProfile),
+      DSH_MCP_COMPACTION_PROFILE: JSON.stringify(compaction),
+    },
+  };
+}
+
+function nativeModel(settings, route, known, profile) {
+  return {
+    ...known, id: settings.model, name: known?.name ?? settings.model, api: profile.api,
+    provider: route, baseUrl: profile.baseURL, reasoning: known?.reasoning ?? false,
+    input: known?.input ?? ['text'], contextWindow: known?.contextWindow ?? profile.defaultContextWindow,
+    maxTokens: known?.maxTokens ?? profile.defaultMaxTokens,
+    cost: known?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    compat: known?.compat ?? profile.compat,
+  };
+}
+
+function nativeApi(protocol) {
+  return { 'chat-completions': openAICompletionsApi, responses: openAIResponsesApi, anthropic: anthropicMessagesApi }[protocol]();
+}
+
+// Pinned DSH hides the native adapter's valid off level for non-reasoning models.
+// Advertise only that level; the unchanged native stream still receives explicit off.
+export const name = 'dsh-mcp-off-only';
+export const inject = ['llm'];
+export async function apply(ctx) {
+  const [{ PiAiAdapter }, { InMemoryCredentialStore, defaultProviderAuthContext }, { resolveRetryPolicy, resolveImageAttachmentAccess }] = await Promise.all([
+    import('@deepseek-ai/dsh-llm-pi-ai'),
+    import('@earendil-works/pi-ai'),
+    import('@deepseek-ai/dsh-llm'),
+  ]);
+  const settings = resolveProviderSettings({
+    protocol: process.env.DSH_MCP_PROTOCOL, baseUrl: process.env.DEEPSEEK_BASE_URL, model: process.env.DSH_MCP_MODEL,
+  });
+  const { route, known, profile, thinkingEfforts } = describeRuntime(settings);
+  if (thinkingEfforts.length !== 1 || thinkingEfforts[0] !== 'off' || known?.reasoning) {
+    throw new Error('The off-only adapter requires a model without selectable reasoning metadata.');
+  }
+  const descriptor = nativeModel(settings, route, known, profile);
+  const resolveApiKey = async () => {
+    const credentials = ctx.get('credentials');
+    const apiKey = credentials ? (await credentials.resolve(profile.apiKeyEnv))?.value : process.env[profile.apiKeyEnv];
+    requireApiKey(apiKey);
+    return apiKey;
+  };
+  const piProvider = createProvider({
+    id: route, baseUrl: profile.baseURL, models: [descriptor], api: nativeApi(settings.protocol),
+    auth: { apiKey: { name: 'Configured API key', resolve: async () => ({ auth: { apiKey: await resolveApiKey() } }) } },
+  });
+  const resolved = {
+    ...profile, provider: route, displayName: route, piProvider,
+    streamIdleTimeoutMs: 300000, maxRequestImageBytes: 20 * 1024 * 1024, maxRequestImages: 50,
+    imageOffloadCountQuantum: 10, requestImagePixelBudget: 4194304, requestImageMaxBytes: 4 * 1024 * 1024,
+    retryPolicy: resolveRetryPolicy(undefined, 'dsh-mcp'),
+    modelErrors: new Map(), configuredMaxTokens: new Map(),
+  };
+  const profiles = new Map([[route, resolved]]);
+  const withOff = (model) => ({
+    ...model, reasoning: { efforts: [{ id: 'off', name: 'Off', description: 'No explicit reasoning request; unknown providers retain their own defaults.' }] },
+  });
+  class OffOnlyAdapter extends PiAiAdapter {
+    async resolveModel(...args) { return withOff(await super.resolveModel(...args)); }
+    async prepareCall(...args) {
+      const prepared = await super.prepareCall(...args);
+      return { ...prepared, model: withOff(prepared.model) };
+    }
+  }
+  ctx.llm.registerAdapter([route], new OffOnlyAdapter({
+    profiles: () => profiles, resolveApiKey,
+    auth: { credentials: new InMemoryCredentialStore(), authContext: defaultProviderAuthContext() },
+    prepareHeaders: (request, headers) => ctx.waterfall('llm-pi-ai/request-headers', request, headers, () => headers),
+    resolveAttachments: () => ctx.get('attachments'),
+    resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(attachments, (path) => ctx.get('fs')?.processPathFromHostPath(path), ref),
+  }));
+}
+
+async function probeDirect(settings, apiKey, signal, directProfile) {
+  const { DeepSeekAdapter, resolveAdapterOptions } = await import('@deepseek-ai/dsh-llm-deepseek');
+  const { apiKeyEnv, ...configuration } = directProfile;
+  const connection = resolveAdapterOptions({ ...configuration, reasoningEffort: 'off', maxTokens: 32, streamIdleTimeoutMs: 20000, retryPolicy: { mode: 'normal', maxRetries: 0 } });
+  const adapter = new DeepSeekAdapter({
+    options: () => connection,
+    resolveAuth: async () => ({ headers: { 'x-api-key': apiKey } }),
+    resolveUserId: () => 'dsh-mcp-connection-check',
+    prepareExtensions: async () => ({ fields: {}, accept: async () => {} }),
+  });
+  let content = false;
+  let finished = false;
+  for await (const event of adapter.stream({
+    provider: 'deepseek-official', model: settings.model, reasoningEffort: 'off', maxTokens: 32, signal,
+    messages: [{ role: 'user', content: [{ type: 'text', text: 'Reply with OK.' }] }],
+  })) {
+    if (event.type === 'text-delta' && event.text?.trim()) content = true;
+    if (event.type === 'finish') finished = ['stop', 'max-tokens'].includes(event.reason.kind);
+  }
+  if (!content || !finished) throw new Error('Connection test did not receive a completed model response.');
+}
+
+export async function testConnection({ protocol, baseUrl, model, apiKey, signal }) {
+  const settings = resolveProviderSettings({ protocol, baseUrl, model });
+  requireApiKey(apiKey);
+  const requestSignal = boundedSignal(signal, 20000);
+  const { route, known, profile, directProfile, thinkingEfforts } = describeRuntime(settings);
+  try {
+    if (route === 'deepseek-official') {
+      await probeDirect(settings, apiKey, requestSignal, directProfile);
+    } else {
+      const descriptor = nativeModel(settings, route, known, profile);
+      const api = nativeApi(settings.protocol);
+      const models = createModels();
+      models.setProvider(createProvider({
+        id: route, baseUrl: profile.baseURL, models: [descriptor], api,
+        auth: { apiKey: { name: 'Explicit setup key', resolve: async () => ({ auth: { apiKey } }) } },
+      }));
+      const response = await models.completeSimple(descriptor, {
+        messages: [{ role: 'user', content: 'Reply with OK.', timestamp: Date.now() }],
+      }, {
+        apiKey, signal: requestSignal, reasoning: thinkingEfforts.includes('off') ? undefined : thinkingEfforts[0],
+        maxTokens: 32, maxRetries: 0, timeoutMs: 20000, transport: 'sse',
+        fetch: (url, options) => fetch(url, { ...options, redirect: 'error' }),
+      });
+      const hasOutput = response.content.some((part) =>
+        part.type === 'text' && part.text?.trim() || part.type === 'thinking' && part.thinking?.trim())
+        || response.usage?.output > 0;
+      if (!['stop', 'length'].includes(response.stopReason) || !hasOutput) {
+        throw new Error('Connection test did not receive a completed model response.');
+      }
+    }
+    return settings;
+  } catch {
+    if (requestSignal.aborted) throw new Error(signal?.aborted ? 'Connection test cancelled.' : 'Connection test timed out.');
+    throw new Error('Connection test failed: no valid inference response. Check protocol, Base URL, API key, model access, and billing.');
+  }
+}

package/src/server.js

@@ -7,7 +7,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { createWorker } from './worker.js';
 import metadata from '../package.json' with { type: 'json' };
-import { normalizeBaseUrl, parseProviderSettings } from './provider.js';
+import { buildProviderRuntime, resolveProviderSettings, parseProviderSettings } from './provider.js';
 
 const { values } = parseArgs({ options: {
   'dsh-home': { type: 'string', default: join(homedir(), '.dsh-mcp') },
@@ -25,20 +25,25 @@ catch (error) { if (error.code !== 'ENOENT') throw error; }
 let provider = {};
 try { provider = parseProviderSettings(await readFile(join(home, 'settings.json'), 'utf8')); }
 catch (error) { if (error.code !== 'ENOENT') throw error; }
-const apiKey = process.env.DEEPSEEK_API_KEY ?? stored.DEEPSEEK_API_KEY;
-if (apiKey !== undefined) process.env.DEEPSEEK_API_KEY = apiKey;
-process.env.DEEPSEEK_BASE_URL = normalizeBaseUrl(process.env.DEEPSEEK_BASE_URL ?? provider.baseUrl);
+const apiKey = process.env.DEEPSEEK_API_KEY?.trim() || stored.DEEPSEEK_API_KEY?.trim() || undefined;
+const savedProvider = resolveProviderSettings(provider, { legacy: !!provider.baseUrl && !provider.protocol });
+const protocol = process.env.DSH_MCP_PROTOCOL || savedProvider.protocol;
+const providerRuntime = buildProviderRuntime({
+  protocol,
+  baseUrl: process.env.DEEPSEEK_BASE_URL ?? (protocol === savedProvider.protocol ? savedProvider.baseUrl : undefined),
+  model: process.env.DSH_MCP_MODEL || savedProvider.model,
+}, apiKey);
 
-const worker = createWorker({ home });
+const worker = createWorker({ home, providerRuntime });
 const instructions = await readFile(new URL('../config/routing.md', import.meta.url), 'utf8');
 const server = new McpServer({ name: 'dsh-mcp', version: metadata.version }, { instructions });
 server.registerTool('delegate_to_deepseek', {
   title: 'Delegate a bounded task to DeepSeek Harness',
-  description: 'Run one bounded task with DeepSeek Flash. Supply the absolute project_root from active Codex context or explicit user authorization. Use read-only for analysis. Select workspace-write explicitly for edits. Supply complete context and acceptance criteria. Pause other writers. Review the actual files and check the result. A completed status does not mean task acceptance.',
+  description: 'Run one bounded task with the configured model through local DeepSeek Harness. Supply the absolute project_root from active Codex context or explicit user authorization. Use read-only for analysis. Select workspace-write explicitly for edits. Supply complete context and acceptance criteria. Pause other writers. Review the actual files and check the result. A completed status does not mean task acceptance.',
   inputSchema: {
     project_root: z.string().min(1).describe('Required absolute project directory from Codex context or explicit user authorization. This is the caller directory grant, not an independently verified workspace ACL.'),
     task: z.string().trim().min(1).max(65536).describe('Self-contained task, allowed files, constraints, acceptance criteria and requested verification.'),
-    thinking_effort: z.enum(['off', 'low', 'high', 'max']).describe('Required DSH reasoning effort. Choose explicitly for every call and resume. Use low for mechanical tasks and high for bounded reasoning.'),
+    thinking_effort: z.enum(providerRuntime.thinkingEfforts).describe('Required model-supported DSH reasoning effort. Choose explicitly for every call and resume; unsupported levels are rejected, never silently clamped.'),
     cwd: z.string().min(1).default('.').describe('Directory relative to project_root, or an absolute directory within project_root.'),
     permission_mode: z.enum(['read-only', 'workspace-write']).default('read-only'),
     session_id: z.string().min(1).max(256).optional().describe('Previously returned DSH session ID for scoped revision in the same cwd.'),