@hzxwonder/dsh-mcp 0.3.0 → 0.5.0

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,19 +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(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.'),

package/src/session-output.js

@@ -0,0 +1,72 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { Context } from '@deepseek-ai/cordis';
+import { Session } from '@deepseek-ai/dsh-session';
+import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl';
+import { currentSessionMessageProjections } from '@deepseek-ai/dsh-session-format-catalog/message-projections';
+
+export async function readSessionOutput({ home, sessionId, cwd }) {
+  if (typeof sessionId !== 'string' || !sessionId) throw new Error('A persisted DSH session ID is required');
+  if (typeof cwd !== 'string' || !isAbsolute(cwd)) throw new Error('The session cwd must be an absolute path');
+  const physicalCwd = await realpath(cwd);
+  const ctx = new Context();
+  try {
+    await ctx.plugin(JsonlSessionPersistence, { root: join(home, 'sessions') }).await();
+    const persistence = ctx.sessionPersistence;
+    const snapshot = await persistence.stat(sessionId);
+    if (!snapshot?.location?.path) throw new Error('Persisted session log not found');
+    const handle = await persistence.open(sessionId, 'read');
+    let read;
+    try {
+      if (handle.header.id !== sessionId || snapshot.header.id !== sessionId) {
+        throw new Error('Persisted session header ID does not match the requested session');
+      }
+      if (!handle.header.cwd || await realpath(handle.header.cwd) !== physicalCwd
+        || snapshot.header.cwd !== handle.header.cwd) {
+        throw new Error('Persisted session cwd does not match the requested physical cwd');
+      }
+      read = await handle.read();
+    } finally {
+      await handle.close();
+    }
+
+    // Restore only in memory: the storage backend owns decoding and migrations.
+    const session = Session.fromRestore(sessionId, read.events, handle.header,
+      handle.inheritedEventCount, read.eventState, currentSessionMessageProjections);
+    const events = read.events;
+    let start = events.length - 1;
+    while (start >= 0 && events[start].type !== 'turn/start') start--;
+    if (start < 0) throw new Error('Persisted session has no durable turn');
+    const turn = events[start].data.turn;
+    const current = new Set(session.surface.nodes);
+    let text = '';
+    let assistantSeq = null;
+    let terminalReason = null;
+    for (let index = events.length - 1; index > start; index--) {
+      const event = events[index];
+      if (event.type === 'turn/end' && event.data.turn === turn && terminalReason === null) {
+        terminalReason = event.data.reason;
+      }
+      if (event.type !== 'assistant/message' || event.data.turn !== turn
+        || assistantSeq !== null || !current.has(event.seq)) continue;
+      const message = session.deriveEventMessage(event);
+      const visibleText = message?.content.filter((block) => block.type === 'text').map((block) => block.text).join('') ?? '';
+      if (visibleText) {
+        text = visibleText;
+        assistantSeq = event.seq;
+      }
+    }
+    return {
+      session_id: sessionId,
+      text,
+      session_file: snapshot.location.path,
+      assistant_seq: assistantSeq,
+      turn,
+      terminal_reason: terminalReason,
+    };
+  } catch (error) {
+    throw new Error(`Cannot read persisted DSH session "${sessionId}": ${error.message}`, { cause: error });
+  } finally {
+    await ctx.fiber.dispose();
+  }
+}

package/src/setup-terminal.js

@@ -0,0 +1,183 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { PROTOCOLS, DEFAULT_PROTOCOL, normalizeBaseUrl, resolveProviderSettings, discoverModels, testConnection } from './provider.js';
+
+const clean = (value) => String(value).replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '?');
+
+export function maskApiKey(value) {
+  if (!value) return '未设置';
+  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value)) return '[REDACTED]';
+  const masked = value.length >= 12 ? `********${value.slice(-4)}` : '********';
+  return masked === value ? '[REDACTED]' : masked;
+}
+
+function question(prompt, hidden = false) {
+  if (!process.stdin.isTTY) throw new Error('配置向导需要交互式终端。请在终端运行 dsh-mcp setup。');
+  const output = hidden ? new Writable({ write(_chunk, _encoding, done) { done(); } }) : process.stdout;
+  const input = createInterface({ input: process.stdin, output, terminal: true, historySize: 0 });
+  if (hidden) process.stdout.write(prompt);
+  return new Promise((accept, reject) => {
+    input.once('SIGINT', () => { input.close(); reject(new Error('配置已取消，尚未保存。')); });
+    input.once('close', () => reject(new Error('输入已关闭，尚未保存。')));
+    input.question(hidden ? '' : prompt, (answer) => {
+      accept(answer);
+      input.close();
+      if (hidden) process.stdout.write('\n');
+    });
+  });
+}
+
+async function progress(label, operation) {
+  const frames = ['|', '/', '-', '\\'];
+  let frame = 0;
+  process.stdout.write(`${label} ${frames[frame]}`);
+  const timer = setInterval(() => process.stdout.write(`\r\u001b[2K${label} ${frames[++frame % frames.length]}`), 120);
+  try { return await operation(AbortSignal.timeout(45000)); }
+  finally { clearInterval(timer); process.stdout.write('\r\u001b[2K'); }
+}
+
+export async function runTerminalSetup({ settings, apiKey = '', existing = false, io = {} }) {
+  const ask = io.ask ?? question;
+  const log = io.log ?? console.log;
+  const run = io.progress ?? progress;
+  const draft = { ...settings };
+  let key = apiKey;
+  const errorText = (error) => {
+    const message = String(error?.message ?? error);
+    return clean(key ? message.split(key).join('[REDACTED]') : message);
+  };
+  const protocol = () => PROTOCOLS.find((item) => item.id === draft.protocol);
+  const summary = () => {
+    log('\n配置汇总（密钥不会明文显示）');
+    log(`  1. 接口类型: ${protocol()?.label ?? clean(draft.protocol)}`);
+    log(`  2. Base URL: ${clean(draft.baseUrl)}`);
+    log(`  3. API Key: ${maskApiKey(key)}`);
+    log(`  4. 模型: ${draft.model ? clean(draft.model) : '待选择'}`);
+  };
+  const chooseProtocol = async () => {
+    log('\n第一层：选择接口协议');
+    PROTOCOLS.forEach((item, index) => log(`  ${index + 1}. ${item.label}`));
+    const current = Math.max(0, PROTOCOLS.findIndex((item) => item.id === (draft.protocol || DEFAULT_PROTOCOL)));
+    for (;;) {
+      const answer = (await ask(`接口 [${current + 1}]: `)).trim();
+      const index = answer ? Number(answer) - 1 : current;
+      if (Number.isInteger(index) && PROTOCOLS[index]) {
+        const selected = PROTOCOLS[index];
+        if (draft.protocol !== selected.id) {
+          draft.protocol = selected.id;
+          draft.baseUrl = selected.defaultBaseUrl;
+          draft.model = '';
+        }
+        return;
+      }
+      log('请输入列表中的编号。');
+    }
+  };
+  const chooseUrl = async () => {
+    log('\n第二层：输入 API 根地址，不是具体的推理端点。');
+    for (;;) {
+      const value = (await ask(`Base URL [${draft.baseUrl || protocol().defaultBaseUrl}]: `)).trim() || draft.baseUrl || protocol().defaultBaseUrl;
+      try {
+        const normalized = normalizeBaseUrl(value, protocol().defaultBaseUrl);
+        if (draft.baseUrl !== normalized) draft.model = '';
+        draft.baseUrl = normalized;
+        return;
+      } catch (error) { log(errorText(error)); }
+    }
+  };
+  const chooseKey = async () => {
+    log(`\n第三层：输入 API Key。目标服务: ${clean(draft.baseUrl)}`);
+    if (key) log('回车表示保留已保存的密钥，并授权将它用于上方服务；也可以输入新密钥。');
+    for (;;) {
+      const value = (await ask(`API Key${key ? ` [${maskApiKey(key)}，回车保留]` : ''}: `, true)).trim();
+      if (value && /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value)) { log('API Key 必须是单行文本。'); continue; }
+      if (value) key = value;
+      if (key) return;
+      log('API Key 不能为空。');
+    }
+  };
+  const manualModel = async () => {
+    for (;;) {
+      const id = (await ask(`模型 ID${draft.model ? ` [${clean(draft.model)}]` : ''}: `)).trim() || draft.model;
+      if (!id || /[\u0000-\u001f\u007f]/.test(id)) { log('请输入有效的模型 ID。'); continue; }
+      draft.model = id;
+      return true;
+    }
+  };
+  const chooseModel = async () => {
+    let models;
+    try {
+      models = await run('正在获取当前凭据可见的模型', (signal) => discoverModels({ ...draft, apiKey: key, signal }));
+      if (!models.length) throw new Error('服务没有返回可选择的模型。');
+    } catch (error) {
+      log(`模型探测失败: ${errorText(error)}`);
+      log('请检查协议、地址和 Key。部分网关不提供模型列表，可手工填写 ID 后进行真实测试。');
+      const action = (await ask('输入 m 手工填写模型，或回车返回配置汇总: ')).trim().toLowerCase();
+      return action === 'm' ? manualModel() : false;
+    }
+    let page = 0;
+    const pageSize = 15;
+    for (;;) {
+      const pages = Math.ceil(models.length / pageSize);
+      log(`\n选择模型：共 ${models.length} 个，第 ${page + 1}/${pages} 页`);
+      models.slice(page * pageSize, (page + 1) * pageSize).forEach((model, index) => {
+        log(`  ${page * pageSize + index + 1}. ${clean(model.id)}${model.id === draft.model ? ' [当前]' : ''}`);
+      });
+      log('  n 下一页 / p 上一页 / m 手工输入 / q 返回汇总');
+      const answer = (await ask(`模型编号${draft.model && models.some((model) => model.id === draft.model) ? ' [回车保留当前]' : ''}: `)).trim();
+      if (!answer && draft.model && models.some((model) => model.id === draft.model)) return true;
+      if (answer === 'q') return false;
+      if (answer === 'm') return manualModel();
+      if (answer === 'n') { page = Math.min(pages - 1, page + 1); continue; }
+      if (answer === 'p') { page = Math.max(0, page - 1); continue; }
+      const index = Number(answer) - 1;
+      if (Number.isInteger(index) && models[index]) { draft.model = models[index].id; return true; }
+      log('请输入有效编号，或使用 n/p 切换页面。');
+    }
+  };
+  const verify = async () => {
+    if (!key) { log('请先设置 API Key。'); return null; }
+    if (!draft.model && !await chooseModel()) return null;
+    summary();
+    log('将向上方服务发送一次最小模型请求，可能产生少量 API 费用。');
+    try {
+      const canonical = resolveProviderSettings(draft);
+      await run('正在测试模型连接', (signal) => testConnection({ ...canonical, apiKey: key, signal }));
+      log('✅ Connection successful!');
+      return { settings: canonical, apiKey: key };
+    } catch (error) {
+      log(`连接失败: ${errorText(error)}`);
+      log('尚未保存。请在配置汇总中选择要修改的项目。');
+      return null;
+    }
+  };
+
+  log('DeepSeek Harness MCP 终端配置');
+  if (!existing) {
+    await chooseProtocol();
+    await chooseUrl();
+    await chooseKey();
+    draft.model = '';
+    if (await chooseModel()) {
+      const result = await verify();
+      if (result) return result;
+    }
+  }
+  for (;;) {
+    summary();
+    log('  5. 重新探测模型并选择');
+    log('  6. 测试并保存');
+    log('  q. 退出，不保存');
+    const action = (await ask('选择操作 [6]: ')).trim().toLowerCase() || '6';
+    if (action === 'q') throw new Error('配置已取消，尚未保存。');
+    if (action === '1') await chooseProtocol();
+    else if (action === '2') await chooseUrl();
+    else if (action === '3') await chooseKey();
+    else if (action === '4') await manualModel();
+    else if (action === '5') await chooseModel();
+    else if (action === '6') {
+      const result = await verify();
+      if (result) return result;
+    } else log('请输入 1–6 或 q。');
+  }
+}