@ran-sh/dsh-crew 1.5.1 → 1.6.1

package/src/multimodal.mjs

@@ -1,686 +0,0 @@
-// Multimodal bridge: gives the (text-only) DeepSeek model eyes and a brush by
-// borrowing the vision / image-generation abilities of locally installed
-// subscription CLIs (claude -p, codex exec, agy). Tools are plain
-// ToolDefinition-shaped objects (see @deepseek-ai/dsh-tools defineTool output)
-// so the hub keeps its zero-@deepseek-imports realm discipline.
-
-import { spawn, execFileSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from 'node:fs';
-import { join, isAbsolute, dirname } from 'node:path';
-import { homedir } from 'node:os';
-import { tr, setLang } from './i18n.mjs';
-import { withGeneratedImageOutput, downloadImageBytes } from './image-output.mjs';
-
-const CONFIG_DIR = join(homedir(), '.config', 'dsh-crew');
-const CACHE_FILE = join(CONFIG_DIR, 'vision-cache.json');
-const CACHE_CAP = 200;
-
-// A subscription CLI is often installed but not on PATH — Codex Desktop keeps
-// its binary under a versioned directory, and a GUI-launched Hub does not
-// inherit the shell's PATH. Spawning the bare name then fails with a bare
-// `spawn <name> ENOENT` even though the CLI is installed and working. Resolve
-// once per name, the same way the workspace code resolves git: ask the platform
-// locator first, then fall back to the known install locations.
-//
-// Callers that spawn a bare name pass it through `resolveCli` first. A name that
-// resolves to nothing is returned unchanged so the spawn still reports its own
-// ENOENT, and the error below says what to do about it.
-const CLI_FALLBACKS = [
-  (name, env) => env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'OpenAI', 'Codex', 'bin'),
-];
-const resolvedCli = new Map();
-
-function expandVersionedDirs(dir, name, exists) {
-  // <dir>/<hash>/<name>.exe — the layout Codex Desktop uses.
-  let entries = [];
-  try { entries = readdirSync(dir); } catch { return null; }
-  for (const entry of entries.sort().reverse()) {
-    for (const file of [`${name}.exe`, name]) {
-      const candidate = join(dir, entry, file);
-      if (exists(candidate)) return candidate;
-    }
-  }
-  return null;
-}
-
-export function resolveCli(name, { env = process.env, exists = existsSync, locate = null } = {}) {
-  if (resolvedCli.has(name)) return resolvedCli.get(name);
-  let found = null;
-  // 1) The platform's own locator, which is what a PATH lookup would use.
-  try {
-    const locator = locate ?? (process.platform === 'win32' ? 'where.exe' : 'which');
-    // where.exe prints a localised "not found" notice on stderr; capture it so a
-    // miss stays quiet and only the fallback path speaks. It can also list
-    // several hits for one name — npm installs an extensionless shell shim next
-    // to a .cmd — so prefer one this platform can actually execute.
-    const out = execFileSync(locator, [name], { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
-    const candidates = String(out).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-    found = pickExecutable(candidates);
-  } catch { /* not on PATH; try the known locations */ }
-  // 2) Known install locations.
-  if (!found && process.platform === 'win32') {
-    for (const dir of CLI_FALLBACKS.map((f) => f(name, env)).filter(Boolean)) {
-      found = expandVersionedDirs(dir, name, exists) ?? (exists(join(dir, `${name}.exe`)) ? join(dir, `${name}.exe`) : null);
-      if (found) break;
-    }
-  }
-  const value = found ?? name;
-  resolvedCli.set(name, value);
-  return value;
-}
-
-// Rank locator hits by what spawn() can launch on this platform. On Windows an
-// extensionless npm shim is a shell script, and since Node 18.20/20.12 spawning a
-// .bat/.cmd is also refused without a shell — so a plain .exe is the only
-// unambiguous choice, and a batch file is launched through cmd.exe in run().
-function pickExecutable(candidates) {
-  if (process.platform !== 'win32') return candidates[0] ?? null;
-  const rank = (p) => (/\.exe$/i.test(p) ? 0 : /\.(cmd|bat)$/i.test(p) ? 1 : 2);
-  return [...candidates].sort((a, b) => rank(a) - rank(b))[0] ?? null;
-}
-
-function run(cmd, args, { timeoutMs, cwd } = {}) {
-  // spawn with stdin ignored: several agent CLIs (codex in particular) behave
-  // differently when handed an open interactive stdin pipe.
-  return new Promise((resolve, reject) => {
-    const resolved = resolveCli(cmd);
-    // A Windows batch shim cannot be spawned directly; go through cmd.exe with
-    // argv (never a command string) so no argument is re-parsed by a shell.
-    const viaCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
-    const executable = viaCmd ? (process.env.ComSpec || 'cmd.exe') : resolved;
-    const argv = viaCmd ? ['/d', '/s', '/c', resolved, ...args] : args;
-    const child = spawn(executable, argv, { cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
-    let out = '', err = '';
-    const timer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs ?? 180_000);
-    child.stdout.on('data', (c) => { out += c; });
-    child.stderr.on('data', (c) => { err += c; });
-    child.on('error', (e) => {
-      clearTimeout(timer);
-      // Say which CLI and what to do, rather than a bare ENOENT.
-      const hint = e?.code === 'ENOENT'
-        ? `\nThe "${cmd}" CLI was not found (checked PATH and the known install locations). Install it, put it on PATH, or pick a different provider in Settings → DSH Crew → Vision.`
-        : '';
-      reject(new Error(`${cmd} spawn failed: ${e.message}${hint}`));
-    });
-    child.on('close', (code, signal) => {
-      clearTimeout(timer);
-      if (signal) reject(new Error(`${cmd} killed by ${signal} (timeout ${timeoutMs ?? 180_000}ms)\n${err.slice(-400)}`));
-      else if (code !== 0) reject(new Error(`${cmd} exited ${code}\n${(err || out).slice(-400)}`));
-      else resolve(out + (out === '' ? err : ''));
-    });
-  });
-}
-
-function cacheKey(parts) { return createHash('sha256').update(parts.join('\0')).digest('hex'); }
-function readCache() { try { return JSON.parse(readFileSync(CACHE_FILE, 'utf8')); } catch { return {}; } }
-function writeCache(cache) {
-  try {
-    const keys = Object.keys(cache);
-    if (keys.length > CACHE_CAP) for (const k of keys.slice(0, keys.length - CACHE_CAP)) delete cache[k];
-    mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(CACHE_FILE, JSON.stringify(cache));
-  } catch {}
-}
-
-const RESULT_SCHEMA = {
-  type: 'object',
-  properties: { ok: { type: 'boolean' }, tool: { type: 'string' }, text: { type: 'string' } },
-  required: ['ok', 'tool', 'text'],
-  additionalProperties: false,
-};
-
-async function describeViaClaude(model, imagePath, question) {
-  const prompt = `Use your Read tool to view the image file at ${imagePath}, then answer concisely: ${question}. Reply with the answer only — no preamble.`;
-  const { dirname } = await import('node:path');
-  // NOTE: --allowedTools is variadic and would swallow a trailing prompt, so
-  // the prompt rides directly on -p.
-  return (await run('claude', ['-p', prompt, '--model', model, '--allowedTools', 'Read'], {
-    timeoutMs: 180_000, cwd: dirname(imagePath),
-  })).trim();
-}
-
-async function describeViaCodex(imagePath, question, model) {
-  const prompt = `Look at the attached image and answer concisely: ${question}. Reply with the answer only.`;
-  const modelArgs = model && model !== 'default' ? ['-c', `model="${model}"`] : [];
-  // `-i/--image` is variadic: `-i file.png "prompt"` makes the CLI read the
-  // prompt as a second image and then fail with "no prompt provided". The
-  // prompt goes first and the image is bound with `=` so it takes one value.
-  const out = await run('codex', ['exec', '--skip-git-repo-check', ...modelArgs, prompt, `--image=${imagePath}`], { timeoutMs: 180_000 });
-  const lines = out.trim().split('\n').filter((l) => l.trim() !== '' && !l.startsWith('[20') && !/^(tokens used|codex$|user$|mcp:)/.test(l.trim()));
-  return lines.slice(-12).join('\n').trim();
-}
-
-async function describeViaGrok(imagePath, question, model) {
-  const { dirname, basename } = await import('node:path');
-  const prompt = `View the image file at ./${basename(imagePath)} and answer concisely: ${question}. Reply with the answer only — no preamble.`;
-  const modelArgs = model && model !== 'default' ? ['-m', model] : [];
-  const out = await run('grok', [...modelArgs, '-p', prompt], { timeoutMs: 240_000, cwd: dirname(imagePath) });
-  return out.trim();
-}
-
-async function describeViaAgy(imagePath, question, model) {
-  const prompt = `View the image file at ${imagePath} and answer concisely: ${question}. Reply with the answer only — no preamble.`;
-  const modelArgs = model && model !== 'default' ? ['--model', model] : [];
-  try {
-    return (await run('agy', [...modelArgs, '-p', prompt], { timeoutMs: 240_000 })).trim();
-  } catch (err) {
-    const msg = String(err?.message ?? err);
-    if (/permission/i.test(msg)) {
-      throw new Error(tr(
-        'agy 需要 read_file 权限：在 Antigravity 的 settings.json 的 permissions.allow 里加入 read_file 规则，或改用其他视觉 provider。原始错误: ',
-        'agy needs read_file permission: add a read_file rule to permissions.allow in Antigravity\'s settings.json, or pick another vision provider. Original error: ',
-      ) + msg.slice(0, 160));
-    }
-    throw err;
-  }
-}
-
-/** Shell-quote a value for interpolation into a custom command template. */
-function shq(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
-
-const BUILTIN_VISION = ['claude-code', 'codex', 'grok', 'agy'];
-const BUILTIN_IMAGEGEN = ['codex', 'agy', 'grok'];
-
-/** Look up a user-defined provider entry by id. */
-export function findCustomProvider(config, id) {
-  return (config?.custom_providers ?? []).find((p) => p && p.id === id);
-}
-
-/** 'api' (OpenAI-compatible endpoint) or 'cli' (command template). Entries
- * created before the type field existed carry commands → cli. */
-function entryType(entry) {
-  return entry.type ?? ((entry.vision_command || entry.imagegen_command) ? 'cli' : 'api');
-}
-
-function extMime(p) {
-  const e = p.toLowerCase().split('.').pop();
-  return e === 'jpg' || e === 'jpeg' ? 'image/jpeg' : e === 'webp' ? 'image/webp' : e === 'gif' ? 'image/gif' : 'image/png';
-}
-
-async function fetchJson(url, { apiKey, body, timeoutMs }) {
-  const ctl = new AbortController();
-  const t = setTimeout(() => ctl.abort(), timeoutMs);
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json', ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}) },
-      body: JSON.stringify(body),
-      signal: ctl.signal,
-    });
-    const text = await res.text();
-    if (!res.ok) throw new Error(`${url} → HTTP ${res.status}: ${text.slice(0, 300)}`);
-    return JSON.parse(text);
-  } catch (err) {
-    if (err?.name === 'AbortError') throw new Error(tr(`${url} 请求超时 (${timeoutMs}ms)`, `${url} timed out (${timeoutMs}ms)`));
-    throw err;
-  } finally { clearTimeout(t); }
-}
-
-function apiBase(entry) {
-  const base = String(entry.base_url ?? '').trim().replace(/\/+$/, '');
-  if (!base) throw new Error(tr(`自定义 provider "${entry.name ?? entry.id}" 未配置 Base URL`, `Custom provider "${entry.name ?? entry.id}" has no Base URL`));
-  return base;
-}
-
-async function describeViaApi(entry, imagePath, question, model) {
-  const base = apiBase(entry);
-  const m = model && model !== 'default' ? model : entry.models?.[0];
-  if (!m) throw new Error(tr(`自定义 provider "${entry.name ?? entry.id}" 未配置模型列表，无法确定视觉模型`, `Custom provider "${entry.name ?? entry.id}" has no models configured`));
-  const b64 = readFileSync(imagePath).toString('base64');
-  const data = await fetchJson(`${base}/chat/completions`, {
-    apiKey: entry.api_key,
-    timeoutMs: 240_000,
-    body: {
-      model: m,
-      messages: [{
-        role: 'user',
-        content: [
-          { type: 'text', text: `${question}\nReply with the answer only — no preamble.` },
-          { type: 'image_url', image_url: { url: `data:${extMime(imagePath)};base64,${b64}` } },
-        ],
-      }],
-    },
-  });
-  const text = data?.choices?.[0]?.message?.content;
-  if (typeof text !== 'string' || text.trim() === '') throw new Error(tr(`${entry.name ?? entry.id} API 返回为空`, `${entry.name ?? entry.id} API returned an empty answer`));
-  return text.trim();
-}
-
-async function generateViaApi(entry, prompt, outputPath, size) {
-  const base = apiBase(entry);
-  // No fallback to the vision model list: a VL model would accept the call and
-  // fail late (or bill for nothing). Image generation is opt-in per provider.
-  const m = String(entry.imagegen_model ?? '').trim();
-  if (!m) throw new Error(tr(
-    `自定义 provider "${entry.name ?? entry.id}" 未配置生图模型（在设置 → DSH Crew → 自定义 Provider 的"生图模型"里填写）`,
-    `Custom provider "${entry.name ?? entry.id}" has no image-gen model (fill in "Image-gen model" under Settings → DSH Crew → Custom providers)`));
-  const body = { model: m, prompt, n: 1 };
-  if (size && /^\d+x\d+$/.test(size)) body.size = size;
-  const data = await fetchJson(`${base}/images/generations`, { apiKey: entry.api_key, timeoutMs: 480_000, body });
-  const item = data?.data?.[0];
-  let buf;
-  if (item?.b64_json) buf = Buffer.from(item.b64_json, 'base64');
-  else if (item?.url) {
-    buf = await downloadImageBytes(item.url);
-  } else {
-    throw new Error(tr(
-      `${entry.name ?? entry.id} API 未返回图像数据: ${JSON.stringify(data).slice(0, 200)}`,
-      `${entry.name ?? entry.id} API returned no image data: ${JSON.stringify(data).slice(0, 200)}`));
-  }
-  writeFileSync(outputPath, buf);
-  return outputPath;
-}
-
-
-// The custom CLI templates are POSIX shell snippets: shq() quotes POSIX-style
-// and the readiness probe uses `command -v`. Windows has no /bin/bash, and
-// cmd.exe would silently misquote the POSIX-style substitutions, so custom CLI
-// providers fail closed there with a precise, actionable error instead of a
-// cryptic ENOENT. No arbitrary shell search.
-export const CUSTOM_CLI_UNSUPPORTED = 'CUSTOM_CLI_UNSUPPORTED';
-export function customCliInvocation(cmd, { platform = process.platform } = {}) {
-  if (platform === 'win32') {
-    const err = new Error(tr(
-      '\u81EA\u5B9A\u4E49 CLI provider \u9700\u8981 POSIX shell\uFF08/bin/bash\uFF09\uFF0C\u5F53\u524D Windows \u73AF\u5883\u4E0D\u53EF\u7528\uFF1B\u8BF7\u5728 WSL \u5185\u8FD0\u884C Harness\uFF0C\u6216\u6539\u7528\u5185\u7F6E provider\uFF08\u5982 codex\uFF09\u3002',
-      'Custom CLI providers require a POSIX shell (/bin/bash), which is unavailable on this Windows environment. Run the Harness inside WSL, or use a built-in provider (e.g. codex).'));
-    err.code = CUSTOM_CLI_UNSUPPORTED;
-    return { ok: false, error: err };
-  }
-  return { ok: true, file: '/bin/bash', args: ['-lc', cmd] };
-}
-
-async function describeViaCustom(entry, imagePath, question, model) {
-  const template = entry.vision_command;
-  if (!template || !template.includes('{image}')) {
-    throw new Error(tr(
-      `自定义 provider "${entry.name ?? entry.id}" 的视觉命令未配置或缺少 {image} 占位符（可用 {image} {question} {model}，stdout 即答案）`,
-      `Custom provider "${entry.name ?? entry.id}" has no vision command, or it lacks the {image} placeholder (available: {image} {question} {model}; stdout is the answer)`));
-  }
-  const cmd = template
-    .replaceAll('{image}', shq(imagePath))
-    .replaceAll('{question}', shq(question))
-    .replaceAll('{model}', shq(model ?? 'default'));
-    const inv = customCliInvocation(cmd);
-    if (!inv.ok) throw inv.error;
-    return (await run(inv.file, inv.args, { timeoutMs: 240_000, cwd: dirname(imagePath) })).trim();
-}
-
-async function generateViaCustom(entry, prompt, outputPath, size) {
-  const template = entry.imagegen_command;
-  if (!template || !template.includes('{prompt}') || !template.includes('{output}')) {
-    throw new Error(tr(
-      `自定义 provider "${entry.name ?? entry.id}" 的生图命令未配置或缺少 {prompt}/{output} 占位符（可用 {prompt} {output} {size}，命令须把图片写到 {output}）`,
-      `Custom provider "${entry.name ?? entry.id}" has no image-gen command, or it lacks the {prompt}/{output} placeholders (available: {prompt} {output} {size}; the command must write the image to {output})`));
-  }
-  const cmd = template
-    .replaceAll('{prompt}', shq(prompt))
-    .replaceAll('{output}', shq(outputPath))
-    .replaceAll('{size}', shq(size ?? ''));
-    const inv = customCliInvocation(cmd);
-    if (!inv.ok) throw inv.error;
-    const out = await run(inv.file, inv.args, { timeoutMs: 480_000, cwd: dirname(outputPath) });
-  if (!existsSync(outputPath)) {
-    throw new Error(`custom command finished but ${outputPath} was not created. Tail:\n${out.trim().slice(-300)}`);
-  }
-  return outputPath;
-}
-
-async function generateViaCodex(prompt, outputPath, size) {
-  // Run codex with cwd = the output directory and a relative save path, so the
-  // write lands inside its sandbox's writable root regardless of policy.
-  const { dirname, basename } = await import('node:path');
-  const task = `$imagegen ${prompt}. Save exactly one image to ./${basename(outputPath)} in the current directory.${size ? ` Target size ${size}.` : ''}`;
-  const out = await run('codex', ['exec', '--skip-git-repo-check', task], { timeoutMs: 480_000, cwd: dirname(outputPath) });
-  if (!existsSync(outputPath)) {
-    throw new Error(`codex finished but ${outputPath} was not created. Tail of output:\n${out.trim().slice(-400)}`);
-  }
-  return outputPath;
-}
-
-async function generateViaGrok(prompt, outputPath) {
-  // Grok Build CLI: native generate_image tool, saves straight into cwd.
-  const { dirname, basename } = await import('node:path');
-  const p = `Use your generate_image tool to create: ${prompt}. Save it to ./${basename(outputPath)} in the current directory (convert to the requested format if needed). Reply with the saved path.`;
-  const out = await run('grok', ['-p', p], { timeoutMs: 480_000, cwd: dirname(outputPath) });
-  if (!existsSync(outputPath)) {
-    throw new Error(`grok finished but ${outputPath} was not created. Tail:\n${out.trim().slice(-300)}`);
-  }
-  return outputPath;
-}
-
-export function findGeneratedImage(root, nonce, now = Date.now()) {
-  if (typeof nonce !== 'string' || !nonce.trim()) return null;
-  const matches = [];
-  for (const file of readdirSync(root, { recursive: true })) {
-    const name = String(file);
-    if (!name.includes(nonce) || !/\.(png|jpe?g|webp)$/i.test(name)) continue;
-    const path = join(root, name);
-    const info = statSync(path);
-    if (info.isFile() && info.size > 0 && info.mtimeMs <= now + 1000 && now - info.mtimeMs <= 8 * 60_000) matches.push(path);
-  }
-  // Multiple matching files are ambiguous; never guess which task output won.
-  return matches.length === 1 ? matches[0] : null;
-}
-
-async function generateViaAgy(prompt, outputPath) {
-  // Antigravity CLI: native generate_image (Nano Banana) needs no permission
-  // bypass, but saves into ~/.gemini/antigravity-cli/{brain,scratch}/... with a
-  // sanitized name. A nonce in the requested filename lets us find the output.
-  const { randomBytes } = await import('node:crypto');
-  const { copyFileSync } = await import('node:fs');
-  const nonce = randomBytes(4).toString('hex');
-  const p = `Use ONLY your native generate_image tool — do not run shell commands or any other tools. Generate: ${prompt}. Save the file with a name containing ${nonce}. Reply with the saved path.`;
-  await run('agy', ['-p', p], { timeoutMs: 480_000 });
-  const root = join(homedir(), '.gemini', 'antigravity-cli');
-  const found = findGeneratedImage(root, nonce);
-  if (!found) throw new Error('agy reported success but no unique image matched this request under ~/.gemini/antigravity-cli');
-  copyFileSync(found, outputPath);
-  return outputPath;
-}
-
-// --- connectivity test ------------------------------------------------------
-
-const CRC_TABLE = (() => {
-  const t = new Int32Array(256);
-  for (let n = 0; n < 256; n++) {
-    let c = n;
-    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-    t[n] = c;
-  }
-  return t;
-})();
-function crc32(buf) {
-  let c = -1;
-  for (const b of buf) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
-  return (c ^ -1) >>> 0;
-}
-function pngChunk(type, data) {
-  const len = Buffer.alloc(4);
-  len.writeUInt32BE(data.length);
-  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(body));
-  return Buffer.concat([len, body, crc]);
-}
-/** A small solid-colour PNG, built in memory so the test needs no fixture file. */
-async function testPng(size = 64, rgb = [220, 40, 40]) {
-  const { deflateSync } = await import('node:zlib');
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(size, 0);
-  ihdr.writeUInt32BE(size, 4);
-  ihdr[8] = 8; ihdr[9] = 2; // 8-bit RGB
-  const row = Buffer.concat([Buffer.from([0]), Buffer.concat(Array.from({ length: size }, () => Buffer.from(rgb)))]);
-  const raw = Buffer.concat(Array.from({ length: size }, () => row));
-  return Buffer.concat([
-    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    pngChunk('IHDR', ihdr),
-    pngChunk('IDAT', deflateSync(raw)),
-    pngChunk('IEND', Buffer.alloc(0)),
-  ]);
-}
-
-const TEST_QUESTION = 'What single colour fills this image? Answer with one word.';
-
-
-/**
- * Probe a custom provider entry (as edited in the panel, saved or not) and
- * report per-step results. Image generation is never actually run — it would
- * cost money and minutes; only reachability and configuration are checked.
- * @returns {Promise<{ok: boolean, steps: Array<{name: string, ok: boolean, detail: string}>}>}
- */
-export async function testProvider(entry, lang) {
-  if (lang) setLang(lang);
-  const steps = [];
-  const push = (name, ok, detail) => { steps.push({ name, ok, detail: String(detail).slice(0, 400) }); return ok; };
-  const type = entryType(entry ?? {});
-  const tmp = join(CONFIG_DIR, 'test-image.png');
-
-  if (type === 'api') {
-    let base;
-    try { base = apiBase(entry); } catch (err) { push(tr('配置', 'Configuration'), false, err.message); return { ok: false, steps }; }
-    push(tr('配置', 'Configuration'), true, `${base}${entry.api_key ? tr(' · 带 API Key', ' · with API key') : tr(' · 无 Key（不发送 Authorization）', ' · no key (no Authorization header)')}`);
-
-    // 1. Reachability + auth, via the optional /models endpoint.
-    try {
-      const ctl = new AbortController();
-      const t = setTimeout(() => ctl.abort(), 20_000);
-      const res = await fetch(`${base}/models`, {
-        headers: entry.api_key ? { authorization: `Bearer ${entry.api_key}` } : {},
-        signal: ctl.signal,
-      }).finally(() => clearTimeout(t));
-      const text = await res.text();
-      if (res.ok) {
-        let ids = [];
-        try { ids = (JSON.parse(text).data ?? []).map((m) => m.id).filter(Boolean); } catch {}
-        const missing = (entry.models ?? []).filter((m) => ids.length > 0 && !ids.includes(m));
-        push(tr('连接 /models', 'Reach /models'), true, ids.length
-          ? tr(`可达，返回 ${ids.length} 个模型${missing.length ? `；未列出: ${missing.join(', ')}` : ''}`,
-            `reachable, ${ids.length} models returned${missing.length ? `; not listed: ${missing.join(', ')}` : ''}`)
-          : tr('可达', 'reachable'));
-      } else if (res.status === 401 || res.status === 403) {
-        push(tr('连接 /models', 'Reach /models'), false, tr(`HTTP ${res.status}：鉴权失败，检查 API Key`, `HTTP ${res.status}: authentication failed, check the API key`));
-        return { ok: false, steps };
-      } else {
-        push(tr('连接 /models', 'Reach /models'), true, tr(`HTTP ${res.status}（该端点可能未实现，继续实测视觉调用）`, `HTTP ${res.status} (endpoint may be unimplemented; continuing with a real vision call)`));
-      }
-    } catch (err) {
-      push(tr('连接 /models', 'Reach /models'), false, err?.name === 'AbortError' ? tr('请求超时 (20s)', 'request timed out (20s)') : String(err.message ?? err));
-      return { ok: false, steps };
-    }
-
-    // 2. Real vision round-trip on a tiny generated image.
-    const model = entry.models?.[0];
-    if (!model) { push(tr('视觉调用', 'Vision call'), false, tr('未配置模型列表', 'no models configured')); return { ok: false, steps }; }
-    try {
-      mkdirSync(CONFIG_DIR, { recursive: true });
-      writeFileSync(tmp, await testPng());
-      const answer = await describeViaApi(entry, tmp, TEST_QUESTION, model);
-      push(tr('视觉调用', 'Vision call'), true, `${model} → “${answer.slice(0, 60)}”`);
-    } catch (err) {
-      push(tr('视觉调用', 'Vision call'), false, String(err.message ?? err));
-      return { ok: false, steps };
-    }
-
-    if (String(entry.imagegen_model ?? '').trim()) {
-      push(tr('生图配置', 'Image-gen setup'), true, tr(
-        `模型 ${entry.imagegen_model.trim()}（未实际出图，避免产生费用与等待）`,
-        `model ${entry.imagegen_model.trim()} (not actually run — that would cost money and time)`));
-    } else {
-      push(tr('生图配置', 'Image-gen setup'), true, tr(
-        '未配置生图模型 → 该 provider 只提供视觉能力',
-        'no image-gen model → this provider offers vision only'));
-    }
-    return { ok: true, steps };
-  }
-
-  // CLI: check the executables exist, then actually run the vision command.
-  const bin = (cmd) => String(cmd).trim().split(/\s+/)[0];
-  const cliShell = customCliInvocation('');
-  if (!cliShell.ok) {
-    push(tr('CLI shell', 'CLI shell'), false, cliShell.error.message);
-    return { ok: false, steps };
-  }
-  if (entry.vision_command) {
-    try {
-      const which = (await run('/bin/bash', ['-lc', `command -v ${shq(bin(entry.vision_command))}`], { timeoutMs: 15_000 })).trim();
-      push(tr('视觉命令可执行', 'Vision command found'), true, which);
-    } catch {
-      push(tr('视觉命令可执行', 'Vision command found'), false, tr(`找不到可执行文件: ${bin(entry.vision_command)}`, `executable not found: ${bin(entry.vision_command)}`));
-      return { ok: false, steps };
-    }
-    try {
-      mkdirSync(CONFIG_DIR, { recursive: true });
-      writeFileSync(tmp, await testPng());
-      const answer = await describeViaCustom(entry, tmp, TEST_QUESTION, entry.models?.[0] ?? 'default');
-      if (answer === '') { push(tr('视觉调用', 'Vision call'), false, tr('命令成功但没有输出', 'the command succeeded but printed nothing')); return { ok: false, steps }; }
-      push(tr('视觉调用', 'Vision call'), true, `“${answer.slice(0, 60)}”`);
-    } catch (err) {
-      push(tr('视觉调用', 'Vision call'), false, String(err.message ?? err));
-      return { ok: false, steps };
-    }
-  }
-  if (entry.imagegen_command) {
-    try {
-      const which = (await run('/bin/bash', ['-lc', `command -v ${shq(bin(entry.imagegen_command))}`], { timeoutMs: 15_000 })).trim();
-      push(tr('生图命令可执行', 'Image-gen command found'), true, tr(`${which}（未实际出图，避免长时间等待）`, `${which} (not actually run — that would take minutes)`));
-    } catch {
-      push(tr('生图命令可执行', 'Image-gen command found'), false, tr(`找不到可执行文件: ${bin(entry.imagegen_command)}`, `executable not found: ${bin(entry.imagegen_command)}`));
-      return { ok: false, steps };
-    }
-  }
-  if (steps.length === 0) push(tr('配置', 'Configuration'), false, tr('未填写任何命令', 'no command configured'));
-  return { ok: steps.every((s) => s.ok), steps };
-}
-
-const modelListCache = new Map(); // provider -> { at, models }
-
-/** List selectable models for CLIs that expose a `models` subcommand. */
-export async function listVisionModels(provider, force = false, getConfig = null, lang = null) {
-  if (lang) setLang(lang);
-  if (!BUILTIN_VISION.includes(provider)) {
-    const entry = getConfig ? findCustomProvider(getConfig(), provider) : null;
-    const models = (entry?.models ?? []).map((m) => ({ value: String(m) }));
-    // API providers must name a real model; only command-based ones have a
-    // meaningful "let the CLI decide" option.
-    return entryType(entry ?? {}) === 'api' ? models : [{ value: 'default', label: tr('default（CLI 默认）', 'default (CLI default)') }, ...models];
-  }
-  const cached = modelListCache.get(provider);
-  if (!force && cached && Date.now() - cached.at < 60 * 60 * 1000) return cached.models;
-  let models = [];
-  if (provider === 'agy') {
-    const out = await run('agy', ['models'], { timeoutMs: 60_000 });
-    models = out.split('\n')
-      .map((l) => l.split('\t'))
-      .filter((parts) => parts.length >= 2 && /^[a-z0-9.-]+$/i.test(parts[0].trim()))
-      .map((parts) => ({ value: parts[0].trim(), label: parts[1].trim() }));
-  } else if (provider === 'grok') {
-    const out = await run('grok', ['models'], { timeoutMs: 60_000 });
-    models = out.split('\n')
-      .map((l) => l.match(/^\s*[*-]\s+([a-z0-9.-]+)(\s+\(default\))?/i))
-      .filter(Boolean)
-      .map((m) => ({ value: m[1], label: m[1] + (m[2] ? tr('（默认）', ' (default)') : '') }));
-  }
-  const result = [{ value: 'default', label: tr('default（CLI 默认）', 'default (CLI default)') }, ...models];
-  modelListCache.set(provider, { at: Date.now(), models: result });
-  return result;
-}
-
-function envelope(tool, text) { return { ok: true, tool, text }; }
-
-/** Core vision call shared by the describe_image tool and the pre-step transcriber. */
-export async function describeFile(getConfig, imagePath, question) {
-  const config = getConfig();
-  const provider = config.vision_provider ?? 'claude-code';
-  if (provider === 'off') throw new Error('vision bridge is disabled');
-  const model = config.vision_model ?? 'haiku';
-  const custom = BUILTIN_VISION.includes(provider) ? null : findCustomProvider(config, provider);
-  if (!BUILTIN_VISION.includes(provider) && !custom) {
-    throw new Error(tr(
-      `未知视觉 provider: ${provider}（内置: ${BUILTIN_VISION.join(' / ')}，或在设置 → DSH Crew → 自定义 Provider 里添加）`,
-      `Unknown vision provider: ${provider} (built-in: ${BUILTIN_VISION.join(' / ')}, or add one under Settings → DSH Crew → Custom providers)`));
-  }
-  const stat = statSync(imagePath);
-  const keyParts = ['v2', provider, model, imagePath, String(stat.size), String(stat.mtimeMs), question];
-  if (custom) keyParts.push(entryType(custom), custom.vision_command ?? '', custom.base_url ?? '');
-  const key = cacheKey(keyParts);
-  const cache = readCache();
-  if (cache[key]) return cache[key];
-  const text = custom
-    ? (entryType(custom) === 'cli'
-      ? await describeViaCustom(custom, imagePath, question, model)
-      : await describeViaApi(custom, imagePath, question, model))
-    : provider === 'codex'
-      ? await describeViaCodex(imagePath, question, model)
-      : provider === 'grok'
-        ? await describeViaGrok(imagePath, question, model)
-        : provider === 'agy'
-          ? await describeViaAgy(imagePath, question, model)
-          : await describeViaClaude(model, imagePath, question);
-  if (text === '') throw new Error(`${provider} returned an empty answer`);
-  cache[key] = text;
-  writeCache(cache);
-  return text;
-}
-
-/**
- * @param getConfig () => global config (vision_provider, vision_model, imagegen_provider)
- */
-export function createMultimodalTools(getConfig) {
-  const describeImage = {
-    name: 'describe_image',
-    description: 'See an image through a vision-capable model (Claude / GPT / Grok / Gemini / custom CLI) and get an answer about it. Use whenever you need to understand an image file: screenshots, design renders, photos, diagrams. Ask a specific question for the most useful answer. Results are cached per image+question.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image_path: { type: 'string', description: 'Absolute path to the image file (png/jpg/webp/gif)' },
-        question: { type: 'string', description: 'What you want to know about the image. Default: a detailed description.' },
-      },
-      required: ['image_path'],
-      additionalProperties: false,
-    },
-    output: {
-      schema: RESULT_SCHEMA,
-      render: (_args, value) => [{ type: 'text', text: value.text }],
-    },
-    async execute(args) {
-      const config = getConfig();
-      const provider = config.vision_provider ?? 'claude-code';
-      if (provider === 'off') throw new Error(tr('视觉桥已关闭（设置 → DSH Crew → 视觉 provider）', 'the vision bridge is disabled (Settings → DSH Crew → Vision provider)'));
-      const imagePath = String(args.image_path ?? '');
-      if (!isAbsolute(imagePath) || !existsSync(imagePath)) throw new Error(`image_path must be an existing absolute path, got: ${imagePath}`);
-      const question = typeof args.question === 'string' && args.question !== ''
-        ? args.question
-        : 'Describe this image in detail: layout, text content, notable elements.';
-      return envelope('describe_image', await describeFile(getConfig, imagePath, question));
-    },
-  };
-
-  const generateImage = {
-    name: 'generate_image',
-    description: 'Generate a raster image from a text prompt via a subscription image model (codex → gpt-image-2, agy → Nano Banana, grok → Grok Imagine, custom → user-configured CLI). Provide a full visual description and an absolute output path. Note: output is a flat raster (no layers); for layered, editable design output use the OpenPencil pipeline instead.',
-    parameters: {
-      type: 'object',
-      properties: {
-        prompt: { type: 'string', description: 'Full visual description: subject, style, colors, composition, constraints' },
-        output_path: { type: 'string', description: 'Absolute path to save the image (e.g. /path/to/hero.png)' },
-        size: { type: 'string', description: 'Optional size hint, e.g. "1024x1024", "16:9"' },
-        provider: { type: 'string', description: 'Override the configured image provider: codex | agy | grok | a custom provider id' },
-      },
-      required: ['prompt', 'output_path'],
-      additionalProperties: false,
-    },
-    output: {
-      schema: RESULT_SCHEMA,
-      render: (_args, value) => [{ type: 'text', text: value.text }],
-    },
-    async execute(args) {
-      const config = getConfig();
-      const provider = args.provider ?? config.imagegen_provider ?? 'codex';
-      if (provider === 'off') throw new Error(tr('生图已关闭（设置 → DSH Crew → 生图 provider）', 'image generation is disabled (Settings → DSH Crew → Image-gen provider)'));
-      const outputPath = String(args.output_path ?? '');
-      if (!isAbsolute(outputPath)) throw new Error(`output_path must be absolute, got: ${outputPath}`);
-      const prompt = String(args.prompt ?? '').trim();
-      if (prompt === '') throw new Error('prompt is required');
-      const custom = BUILTIN_IMAGEGEN.includes(provider) ? null : findCustomProvider(config, provider);
-      if (!BUILTIN_IMAGEGEN.includes(provider) && !custom) {
-        throw new Error(tr(
-          `未知生图 provider: ${provider}（内置: ${BUILTIN_IMAGEGEN.join(' / ')}，或在设置 → DSH Crew → 自定义 Provider 里添加）`,
-          `Unknown image-gen provider: ${provider} (built-in: ${BUILTIN_IMAGEGEN.join(' / ')}, or add one under Settings → DSH Crew → Custom providers)`));
-      }
-      const saved = await withGeneratedImageOutput(outputPath, async (stagedPath) => custom
-        ? (entryType(custom) === 'cli'
-          ? await generateViaCustom(custom, prompt, stagedPath, args.size)
-          : await generateViaApi(custom, prompt, stagedPath, args.size))
-        : provider === 'agy'
-          ? await generateViaAgy(prompt, stagedPath)
-          : provider === 'grok'
-            ? await generateViaGrok(prompt, stagedPath)
-            : await generateViaCodex(prompt, stagedPath, args.size));
-      const bytes = statSync(saved).size;
-      return envelope('generate_image', `image saved: ${saved} (${Math.round(bytes / 1024)} KB, provider: ${provider})`);
-    },
-  };
-
-  return [describeImage, generateImage];
-}