@hzxwonder/dsh-mcp 0.3.0 → 0.5.0

package/config/routing.md

@@ -1,9 +1,12 @@
 ## DeepSeek task delegation
 
-Preserve the current GPT model, provider, and account. Delegate only bounded, low-risk tasks. Review actual changes before acceptance.
-
-Every delegate_to_deepseek call requires an absolute project_root from Codex context or explicit user authorization.
-Never infer this path from the server or installation. Use read-only unless the task requires edits. Follow project and user restrictions first.
+Keep the current GPT model, provider, and account.
+Every delegate_to_deepseek call needs the current authorized absolute project_root and an explicit thinking_effort from the selected model's current tool schema.
+Include both on resume. Never infer the root from the server or installation. Never default effort.
+Use read-only unless the task needs edits. Read the session answer, reason, and diagnostics before review. Follow user and project restrictions.
+The full Harness runs locally with the protocol, API service, and model selected in setup.
+The configured API service receives task data and charges its own API fees.
+Never silently replace the selected model with DeepSeek Flash or a direct API call.
 
 - Use the installed `deepseek-worker` skill for eligible tasks.
 - Delegate worthwhile, bounded, low-risk tasks by default when the MCP tool is available.
@@ -13,6 +16,15 @@ Never infer this path from the server or installation. Use read-only unless the
 - Use the active project root unless the user explicitly authorizes a different project directory.
 - Do not infer the root from the server directory, home directory, installation, or previous calls.
 - Do not delegate when the current project root is unknown.
+- Select `thinking_effort` consciously for every call, including continuation.
+- The tool schema exposes a model-dependent subset of `off`, `low`, `high`, and `max`.
+- Unknown model metadata exposes only `off`. This limit is not proof that the model cannot reason.
+- Use `low` for mechanical tasks and `high` for bounded reasoning only when the schema permits them.
+- Use `off` deliberately, including when the schema permits only `off`.
+- Use `max` only when the schema permits it and the task justifies its additional cost.
+- Never silently supply missing effort or use aliases such as `medium` or `xhigh`.
+- Never coerce an unsupported effort to another value.
+- This parameter sets DSH `agent-default-model.config.reasoningEffort`, not prompt text.
 - Each `project_root` grants directory access for that call only.
 - The server does not independently check this grant against a Codex workspace ACL.
 - This grant is not a read isolation boundary.
@@ -27,8 +39,51 @@ Never infer this path from the server or installation. Use read-only unless the
 - Require the worker to stop and report unresolved questions in its final answer.
 - Do not promise live dialogue or automatic approval responses during a call.
 - Resolve questions before a new call with the returned `session_id`, the same `project_root`, and the same `cwd`.
+- Select `thinking_effort` again when you resume. Do not depend on the old session setting.
+- After the worker stops, MCP reads the persisted session and checks its ID and saved physical working directory.
+- Read `answer`, `output_source: "session"`, `session_id`, `session_file`, `assistant_seq`, and `turn`.
+- Read `reason`, `terminal_reason`, `session_output_error`, and `diagnostics` before reviewing actual changes.
+- The answer is the last committed assistant text in the latest durable turn.
+- Hidden reasoning, tool calls, and tool results are not final answers.
+- An empty latest turn returns empty text and a null assistant sequence, never an earlier successful answer.
+- Session read failures are explicit. Do not substitute stdout or old answers.
+- The persisted turn must match this invocation's turn_start event. Never return a previous turn after a failed resume.
+- Do not promise a separate arbitrary-session reader.
 - Review actual changes and check evidence before acceptance.
 - Treat `completed` as Harness turn completion, not task acceptance.
 - Report unverified results and partial changes explicitly.
 
 These instructions guide delegation decisions but cannot guarantee automatic tool invocation.
+
+Example arguments:
+
+This example assumes that the current model's schema permits `low`.
+
+```json
+{
+  "project_root": "/absolute/authorized/project",
+  "thinking_effort": "low",
+  "task": "Correct the specified documentation typo. Preserve user changes. Do not commit or delegate. Report the changed file and any checks.",
+  "cwd": ".",
+  "permission_mode": "workspace-write"
+}
+```
+
+Global setup needs no project configuration.
+The installer can upgrade an owned, unchanged previous skill template.
+It preserves customized skills and skills without a previous-template reference.
+Back up those files and resolve conflicts manually before replacement.
+
+Setup runs in the terminal and configures protocol, Base URL, hidden API key, and a user-selected remote model.
+Rerun the same `dsh-mcp setup` command to edit saved settings or rotate the key from the masked summary.
+An unavailable model list permits an explicit manual model ID, not a fake discovery result.
+The real tiny inference test can incur an API charge.
+Only a successful inference test produces `✅ Connection successful!`.
+That message does not prove MCP registration or Codex App availability.
+Use `dsh-mcp doctor` to inspect effective configuration, stdio initialization, and the tool catalog without a paid inference request.
+A healthy independent handshake does not prove that the current App session exposes the tool.
+Use the same host, user, and `CODEX_HOME` as Codex.
+If necessary, ask the user to save work and fully restart Codex before starting a new session.
+Do not stop the user's client or inspect private login files.
+Unsupported OAuth for stdio is not a provider API key failure.
+Never include credentials in project configuration, task text, commands, logs, or screenshots.

package/config/worker.patch.yml

@@ -1,7 +1,18 @@
 - id: agent-default-model
   config:
-    provider: deepseek-official
-    model: deepseek-flash
+    provider: !!js process.env.DSH_MCP_PROVIDER
+    model: !!js process.env.DSH_MCP_MODEL
+    reasoningEffort: !!js process.env.DSH_MCP_THINKING_EFFORT
+- id: llm-pi-ai
+  config:
+    providers: !!js JSON.parse(process.env.DSH_MCP_PI_PROVIDERS)
+- id: llm-deepseek
+  disabled: !!js process.env.DSH_MCP_PROVIDER !== 'deepseek-official'
+  config: !!js JSON.parse(process.env.DSH_MCP_DEEPSEEK_PROFILE)
+- id: llm-deepseek-account
+  disabled: true
+- id: compaction-basic
+  config: !!js JSON.parse(process.env.DSH_MCP_COMPACTION_PROFILE)
 - id: settings
   disabled: true
 - id: config-editor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzxwonder/dsh-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "mcpName": "io.github.hzxwonder/dsh-mcp",
   "type": "module",
   "description": "Delegate bounded Codex tasks to DeepSeek Harness over MCP stdio.",
@@ -35,7 +35,15 @@
     "dsh": "dsh"
   },
   "dependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
     "@deepseek-ai/dsh": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-format-catalog": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.2-rc.1",
+    "@earendil-works/pi-ai": "1.5.0",
     "@modelcontextprotocol/sdk": "1.32.2",
     "smol-toml": "1.9.1",
     "zod": "^4.0.0"

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.hzxwonder/dsh-mcp",
   "title": "DeepSeek Harness for Codex",
-  "description": "Delegate bounded tasks to local DeepSeek Harness with an explicit project_root in every tool call.",
-  "version": "0.3.0",
+  "description": "Run local Harness tasks through Chat Completions, Responses, or Anthropic Messages.",
+  "version": "0.5.0",
   "repository": {
     "url": "https://github.com/hzxwonder/dsh-mcp",
     "source": "github"
@@ -14,26 +14,41 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@hzxwonder/dsh-mcp",
-      "version": "0.3.0",
+      "version": "0.5.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
+        {
+          "name": "DSH_MCP_PROTOCOL",
+          "description": "Wire protocol. The terminal setup command discovers models and validates the selected protocol.",
+          "format": "string",
+          "choices": ["chat-completions", "responses", "anthropic"],
+          "default": "chat-completions",
+          "isRequired": false,
+          "isSecret": false
+        },
         {
           "name": "DEEPSEEK_API_KEY",
-          "description": "API Key for a compatible Messages API provider. Pass this secret through the environment, not command arguments.",
+          "description": "API Key for the selected provider. Pass this secret through the environment, never command arguments.",
           "format": "string",
           "isRequired": true,
           "isSecret": true
         },
         {
           "name": "DEEPSEEK_BASE_URL",
-          "description": "Messages API root. Requests use /v1/messages. An OpenAI chat-completions-only endpoint is not compatible.",
+          "description": "API root. Leave empty for the selected protocol's default. Use terminal setup for model discovery.",
           "format": "string",
-          "default": "https://api.deepseek.com/anthropic",
           "isRequired": false,
           "isSecret": false
+        },
+        {
+          "name": "DSH_MCP_MODEL",
+          "description": "Model ID available to this API key. Terminal setup can discover the model list.",
+          "format": "string",
+          "isRequired": true,
+          "isSecret": false
         }
       ]
     }

package/src/cli.js

@@ -5,6 +5,10 @@ try {
     process.argv.splice(2, 1);
     const { runSetup } = await import('./setup.js');
     await runSetup();
+  } else if (process.argv[2] === 'doctor') {
+    process.argv.splice(2, 1);
+    const { runDoctor } = await import('./doctor.js');
+    await runDoctor();
   } else {
     await import('./server.js');
   }

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;
+}