@sanqianx/claude-ai-workbench 0.11.0

package/packages/server/lib/http-handler.js

@@ -0,0 +1,254 @@
+'use strict';
+
+const { DEFAULT_API_PREFIX, cleanId } = require('../../contracts');
+const { pickFolder: defaultPickFolder } = require('./folder-picker');
+
+function createHttpHandler(service, options = {}) {
+  const prefix = String(options.apiPrefix || DEFAULT_API_PREFIX).replace(/\/$/, '');
+  // Stateless host capability — the picker module is required directly.
+  const pickFolder = options.pickFolder || defaultPickFolder;
+  return async function handle(req, res) {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) return false;
+    const path = url.pathname.slice(prefix.length) || '/';
+    // System endpoints trigger host-native side effects (a modal folder
+    // dialog) and answer with a local filesystem path. The API-wide CORS `*`
+    // would let any website stack dialogs and read the choice, so they are
+    // restricted to loopback origins — same-origin GETs and non-browser
+    // clients send no Origin header at all and always pass.
+    if (path.startsWith('/system/')) {
+      const origin = req.headers.origin;
+      if (origin && !isLoopbackOrigin(origin) && origin !== options.corsOrigin) {
+        return json(res, 403, { ok: false, error: 'cross-origin access to system endpoints is not allowed' });
+      }
+      if (origin) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+      }
+      if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return true; }
+    } else {
+      setCors(req, res, options.corsOrigin);
+      if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return true; }
+    }
+    try {
+      if (req.method === 'GET' && path === '/health') return json(res, 200, service.health());
+      // {path} on success, {path:null} when the user cancelled, 501 when the
+      // host has no folder picker, 500 on real failures. `win=x,y,w,h` (the
+      // calling browser window's screen rect) anchors the dialog so it opens
+      // over the UI instead of the screen's top-left corner.
+      if (req.method === 'GET' && path === '/system/pick-folder') {
+        const parts = (url.searchParams.get('win') || '').split(',').map(Number);
+        const windowRect = parts.length === 4 && parts.every(Number.isFinite)
+          ? { x: parts[0], y: parts[1], width: parts[2], height: parts[3] }
+          : undefined;
+        return json(res, 200, await pickFolder({ windowRect, title: '选择项目文件夹' }));
+      }
+      // Environment diagnostics: resolved executables, live version probes,
+      // login-state files (no secrets). Answers "discovery showed the agent
+      // but turns failed" on fresh machines.
+      if (req.method === 'GET' && path === '/system/doctor') {
+        return json(res, 200, (options.doctor && options.doctor()) || {
+          schema: 'agent-terminal-doctor/v1',
+          error: 'doctor not wired',
+        });
+      }
+      if (req.method === 'GET' && path === '/runtime') return json(res, 200, service.runtime());
+      if (req.method === 'GET' && path === '/agents') return json(res, 200, service.listAgents());
+      if (req.method === 'GET' && path === '/profiles') return json(res, 200, service.listProfiles());
+      if (req.method === 'POST' && path === '/profiles') return json(res, 201, service.saveProfile(await body(req)));
+      if (req.method === 'POST' && path === '/profiles/test') return json(res, 200, await service.testProfileDraft(await body(req)));
+      if (req.method === 'POST' && path === '/profiles/detect-models') return json(res, 200, await service.detectProfileModels(await body(req)));
+      if (req.method === 'GET' && path === '/capture-settings') return json(res, 200, service.getCaptureSettings());
+      if (req.method === 'PUT' && path === '/capture-settings') return json(res, 200, service.saveCaptureSettings(await body(req)));
+      if (req.method === 'GET' && path === '/ui-preferences') return json(res, 200, service.getUiPreferences());
+      if (req.method === 'PUT' && path === '/ui-preferences') return json(res, 200, service.saveUiPreferences(await body(req)));
+
+      if (path === '/projects' && req.method === 'GET') return json(res, 200, service.listProjects());
+      if (path === '/projects' && req.method === 'POST') return json(res, 201, service.createProject(await body(req)));
+      const projectMatch = path.match(/^\/projects\/([^/]+)$/);
+      if (projectMatch) {
+        const id = decode(projectMatch[1]);
+        if (req.method === 'GET') return json(res, 200, service.getProject(id));
+        if (req.method === 'PATCH') return json(res, 200, service.renameProject(id, await body(req)));
+        if (req.method === 'DELETE') {
+          service.removeProject(id, { keepSessions: url.searchParams.get('keepSessions') === '1' });
+          res.writeHead(204); res.end(); return true;
+        }
+      }
+
+      let match = path.match(/^\/profiles\/([^/]+)$/);
+      if (match) {
+        const id = decode(match[1]);
+        if (req.method === 'GET') {
+          const profile = service.getProfile(id);
+          if (!profile) throw Object.assign(new Error('profile not found'), { status: 404 });
+          return json(res, 200, profile);
+        }
+        if (req.method === 'PUT') return json(res, 200, service.saveProfile(await body(req), id));
+        if (req.method === 'DELETE') {
+          if (!service.deleteProfile(id)) throw Object.assign(new Error('profile not found'), { status: 404 });
+          res.writeHead(204); res.end(); return true;
+        }
+      }
+
+      match = path.match(/^\/profiles\/([^/]+)\/credential$/);
+      if (match && req.method === 'PUT') {
+        service.setCredential(decode(match[1]), await body(req));
+        res.writeHead(204); res.end(); return true;
+      }
+      match = path.match(/^\/profiles\/([^/]+)\/test$/);
+      if (match && req.method === 'POST') return json(res, 200, await service.testProfile(decode(match[1])));
+
+      if (path === '/sessions' && req.method === 'GET') {
+        const sessions = service.listSessions(url.searchParams.get('contextId'), {
+          includeArchived: ['1', 'true'].includes(url.searchParams.get('archived')),
+        });
+        return json(res, 200, { sessions });
+      }
+      if (path === '/sessions' && req.method === 'POST') {
+        const input = await body(req);
+        const session = service.startSession(input.context, input.aiProfileId, input);
+        return json(res, 201, { session });
+      }
+
+      match = path.match(/^\/sessions\/([^/]+)\/archive$/);
+      if (match && req.method === 'PUT') return json(res, 200, service.archiveSession(decode(match[1])));
+      if (match && req.method === 'DELETE') {
+        service.restoreSession(decode(match[1]));
+        res.writeHead(204); res.end(); return true;
+      }
+
+      match = path.match(/^\/sessions\/([^/]+)\/context-usage$/);
+      if (match && req.method === 'GET') return json(res, 200, service.contextUsage(decode(match[1])));
+
+      match = path.match(/^\/sessions\/([^/]+)$/);
+      if (match && req.method === 'GET') return json(res, 200, service.loadSession(decode(match[1])));
+
+      match = path.match(/^\/sessions\/([^/]+)\/events$/);
+      if (match && req.method === 'GET') {
+        const sessionId = decode(match[1]);
+        const after = sequenceFromRequest(req, url);
+        service.loadSession(sessionId);
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store, no-transform',
+          Connection: 'keep-alive', 'X-Accel-Buffering': 'no',
+          'Access-Control-Allow-Origin': options.corsOrigin || '*',
+        });
+        res.write(': claude-workbench stream\n\n');
+        const unsubscribe = service.subscribe(sessionId, after, event => writeSse(res, event));
+        const heartbeat = setInterval(() => { try { res.write(`: keepalive ${Date.now()}\n\n`); } catch {} }, 15000);
+        heartbeat.unref && heartbeat.unref();
+        let closed = false;
+        const close = () => { if (closed) return; closed = true; clearInterval(heartbeat); try { unsubscribe(); } catch {} };
+        req.on('close', close); req.on('error', close); res.on('close', close);
+        return true;
+      }
+
+      match = path.match(/^\/sessions\/([^/]+)\/input$/);
+      if (match && req.method === 'POST') {
+        const input = await body(req, 32 * 1024 * 1024);
+        return json(res, 202, await service.send(decode(match[1]), input.text, input.options, input.attachments));
+      }
+      match = path.match(/^\/sessions\/([^/]+)\/commands$/);
+      if (match && req.method === 'GET') return json(res, 200, await service.listCommands(decode(match[1])));
+
+      match = path.match(/^\/sessions\/([^/]+)\/attachments\/([^/]+)$/);
+      if (match && req.method === 'GET') {
+        const attachment = service.readAttachment(decode(match[1]), decode(match[2]));
+        const headers = {
+          'Content-Type': attachment.metadata.mediaType,
+          'Content-Length': attachment.data.length,
+          'Cache-Control': 'private, max-age=3600',
+          'X-Content-Type-Options': 'nosniff',
+        };
+        // Images stay inline for the chat UI; anything textual is forced to
+        // download so a crafted .html/.svg attachment can never render in the
+        // page origin.
+        if (!String(attachment.metadata.mediaType || '').startsWith('image/')) {
+          const safeName = String(attachment.metadata.name || 'attachment').replace(/[^\w.\-]+/g, '_').slice(0, 100) || 'attachment';
+          headers['Content-Disposition'] = `attachment; filename="${safeName}"`;
+        }
+        res.writeHead(200, headers);
+        res.end(attachment.data);
+        return true;
+      }
+      match = path.match(/^\/sessions\/([^/]+)\/permissions\/([^/]+)\/resolve$/);
+      if (match && req.method === 'POST') {
+        return json(res, 200, service.resolvePermission(decode(match[1]), decode(match[2]), await body(req)));
+      }
+      match = path.match(/^\/sessions\/([^/]+)\/abort$/);
+      if (match && req.method === 'POST') return json(res, 202, service.abort(decode(match[1])));
+
+      match = path.match(/^\/sessions\/([^/]+)\/permission-mode$/);
+      if (match && req.method === 'PUT') {
+        const input = await body(req);
+        return json(res, 200, service.setPermissionMode(decode(match[1]), input.mode));
+      }
+      match = path.match(/^\/sessions\/([^/]+)\/selection$/);
+      if (match && req.method === 'PUT') {
+        const input = await body(req);
+        return json(res, 200, service.updateSessionSelection(decode(match[1]), input.aiProfileId, input.model));
+      }
+      throw Object.assign(new Error('route not found'), { status: 404 });
+    } catch (error) {
+      if (res.headersSent) {
+        if (!res.writableEnded) try { res.end(); } catch {}
+        return true;
+      }
+      const status = Number(error.status) || (error.message === 'request body too large' ? 413 : 400);
+      return json(res, status, { ok: false, error: safeError(error) });
+    }
+  };
+}
+
+function body(req, limit = 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let size = 0; let settled = false;
+    req.on('data', chunk => {
+      if (settled) return;
+      size += chunk.length;
+      if (size > limit) { settled = true; reject(new Error('request body too large')); return; }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (settled) return;
+      try { resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {}); }
+      catch { reject(Object.assign(new Error('invalid JSON body'), { status: 400 })); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function json(res, status, value) {
+  const payload = status === 204 ? undefined : JSON.stringify(value);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+  res.end(payload);
+  return true;
+}
+function writeSse(res, event) {
+  res.write(`id: ${event.sequence}\n`);
+  res.write(`event: ${event.type}\n`);
+  res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+function sequenceFromRequest(req, url) {
+  const value = req.headers['last-event-id'] || url.searchParams.get('after') || 0;
+  const parsed = Number(value); return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+function setCors(req, res, origin) {
+  res.setHeader('Access-Control-Allow-Origin', origin || '*');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Last-Event-ID');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+}
+// `Origin` values a system endpoint may serve: the local machine itself
+// (the app is same-origin already; a dev server on another loopback port is
+// fine). `Origin: null` (sandboxed/data frames) and foreign hosts are not.
+function isLoopbackOrigin(origin) {
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  return ['localhost', '127.0.0.1', '[::1]', '::1'].includes(parsed.hostname);
+}
+function decode(value) { try { return cleanId(decodeURIComponent(value)); } catch (error) { error.status = 400; throw error; } }
+function safeError(error) { return String(error && error.message || 'request failed').replace(/[\r\n]+/g, ' ').slice(0, 500); }
+
+module.exports = { createHttpHandler, body, writeSse, sequenceFromRequest };

package/packages/server/lib/json-file.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readJson(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { return fallback; }
+}
+
+function writeJson(file, value, mode = 0o600) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode });
+  fs.renameSync(temp, file);
+  try { fs.chmodSync(file, mode); } catch {}
+}
+
+module.exports = { readJson, writeJson };

package/packages/server/lib/model-detection.js

@@ -0,0 +1,295 @@
+'use strict';
+
+// Auto-detection of a provider's usable models, modeled after all-api-hub:
+//   1. The provider's own models endpoint yields the ids the key can use —
+//      Anthropic-style (x-api-key, /v1/models with cursor pagination and a
+//      Bearer retry on 401) and OpenAI-style (Bearer, /v1/models with a
+//      /models fallback only for missing-route 404/405).
+//   2. Capability metadata (context window, input modalities, reasoning,
+//      tool calls) comes from the models.dev catalog, cached in memory for
+//      24h and degrading to "unavailable" when it cannot be fetched.
+// The two sides are joined with a forgiving id match chain so relay-station
+// ids like claude-3-5-sonnet-20241022-latest still find their metadata.
+
+const MODELS_DEV_URL = 'https://models.dev/models.json';
+const METADATA_TTL_MS = 24 * 60 * 60 * 1000;
+const ANTHROPIC_VERSION = '2023-06-01';
+const PAGE_LIMIT = 1000;
+const MAX_PAGES = 5;
+const MAX_MODELS = 2000;
+const REQUEST_TIMEOUT_MS = 15000;
+const DATE_SUFFIX = /-(?:latest|preview|stable|\d{4}-?\d{2}-?\d{2}|\d{8,10})(?:-\d+)?$/i;
+
+function createModelDetection(options = {}) {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') throw new Error('fetch is required for model detection');
+  const contextLookup = typeof options.contextLookup === 'function' ? options.contextLookup : () => null;
+  const modelsDevUrl = options.modelsDevUrl || MODELS_DEV_URL;
+  let cache = null; // { entries, exact, tokenKeys, fetchedAt }
+  let inFlight = null;
+
+  async function fetchJson(url, headers) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const response = await fetchImpl(url, { headers, signal: controller.signal });
+      const text = await response.text();
+      let data = null;
+      try { data = text ? JSON.parse(text) : null; } catch { /* non-JSON error bodies stay raw */ }
+      return { response, data, text };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function endpointError(label, url, response, text) {
+    const snippet = String(text || '').replace(/\s+/g, ' ').slice(0, 200);
+    return Object.assign(
+      new Error(`${label} request failed: HTTP ${response.status}${snippet ? ` — ${snippet}` : ''}`),
+      { status: 400, upstreamStatus: response.status, url },
+    );
+  }
+
+  // "https://x.test/v1" and "https://x.test/v1/" both normalize to
+  // "https://x.test" so /v1/models is never doubled.
+  function stripVersionSuffix(baseUrl) {
+    return String(baseUrl || '').trim().replace(/\/+$/, '').replace(/\/v1(?:beta)?$/i, '');
+  }
+
+  function collectIds(data) {
+    const rows = data && Array.isArray(data.data) ? data.data : Array.isArray(data) ? data : null;
+    if (!rows) return null;
+    const ids = [];
+    for (const row of rows) {
+      const id = row && typeof row === 'object' ? String(row.id || '').trim() : '';
+      if (id) ids.push(id);
+    }
+    return ids;
+  }
+
+  async function fetchAnthropicModels(baseUrl, apiKey) {
+    const root = stripVersionSuffix(baseUrl);
+    const seen = new Set();
+    const ids = [];
+    let afterId = '';
+    for (let page = 0; page < MAX_PAGES && ids.length < MAX_MODELS; page++) {
+      const query = `limit=${PAGE_LIMIT}${afterId ? `&after_id=${encodeURIComponent(afterId)}` : ''}`;
+      const url = `${root}/v1/models?${query}`;
+      let result = await fetchJson(url, { 'x-api-key': apiKey, 'anthropic-version': ANTHROPIC_VERSION });
+      if (result.response.status === 401) {
+        // Some relays only accept Bearer auth; retry once before failing.
+        result = await fetchJson(url, { Authorization: `Bearer ${apiKey}`, 'anthropic-version': ANTHROPIC_VERSION });
+      }
+      if (!result.response.ok) throw endpointError('Anthropic models', url, result.response, result.text);
+      const pageIds = collectIds(result.data);
+      if (!pageIds) throw Object.assign(new Error(`Anthropic models response has no model list: ${url}`), { status: 400 });
+      for (const id of pageIds) { if (!seen.has(id)) { seen.add(id); ids.push(id); } }
+      const last = pageIds.length ? pageIds[pageIds.length - 1] : '';
+      if (result.data.has_more !== true || !last || last === afterId) break;
+      afterId = last;
+    }
+    return ids.slice(0, MAX_MODELS);
+  }
+
+  async function fetchOpenAiModels(baseUrl, apiKey) {
+    const root = stripVersionSuffix(baseUrl);
+    const auth = { Authorization: `Bearer ${apiKey}` };
+    let result = await fetchJson(`${root}/v1/models`, auth);
+    // Volcengine-style hosts expose /models on an already-prefixed base URL;
+    // only a missing route falls through — auth and server errors fail fast.
+    if (result.response.status === 404 || result.response.status === 405) {
+      result = await fetchJson(`${String(baseUrl).trim().replace(/\/+$/, '')}/models`, auth);
+    }
+    if (!result.response.ok) throw endpointError('OpenAI models', root, result.response, result.text);
+    const ids = collectIds(result.data);
+    if (!ids) throw Object.assign(new Error(`OpenAI models response has no model list: ${root}/v1/models`), { status: 400 });
+    return ids.slice(0, MAX_MODELS);
+  }
+
+  // ---- models.dev capability catalog ----
+
+  function normalizeCatalog(payload) {
+    const entries = [];
+    const source = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {};
+    for (const [key, raw] of Object.entries(source)) {
+      if (!raw || typeof raw !== 'object') continue;
+      // The map key "provider/model-id" is authoritative; entry.id may be bare.
+      const bareId = String(key.includes('/') ? key.slice(key.lastIndexOf('/') + 1) : raw.id || key).trim();
+      if (!bareId) continue;
+      const modalities = raw.modalities && typeof raw.modalities === 'object' ? raw.modalities : {};
+      const limit = raw.limit && typeof raw.limit === 'object' ? raw.limit : {};
+      const context = Number(limit.context);
+      const maxOutput = Number(limit.output);
+      entries.push({
+        id: bareId,
+        name: String(raw.name || bareId).trim(),
+        provider: String(key.includes('/') ? key.slice(0, key.indexOf('/')) : raw.provider_id || '').trim(),
+        reasoning: raw.reasoning === true,
+        toolCall: raw.tool_call === true,
+        attachment: raw.attachment === true,
+        input: Array.isArray(modalities.input) ? modalities.input.map(String) : [],
+        output: Array.isArray(modalities.output) ? modalities.output.map(String) : [],
+        context: Number.isFinite(context) && context > 0 ? Math.floor(context) : null,
+        maxOutput: Number.isFinite(maxOutput) && maxOutput > 0 ? Math.floor(maxOutput) : null,
+      });
+    }
+    const exact = new Map();
+    for (const entry of entries) {
+      const key = entry.id.toLowerCase();
+      if (exact.has(key)) exact.set(key, null); // ambiguous: never match silently
+      else exact.set(key, entry);
+    }
+    const tokenKeys = new Map();
+    for (const entry of entries) {
+      const key = tokenKey(entry.id);
+      if (tokenKeys.has(key)) tokenKeys.set(key, null);
+      else tokenKeys.set(key, entry);
+    }
+    return { entries, exact, tokenKeys, fetchedAt: Date.now() };
+  }
+
+  function tokenKey(id) {
+    const base = String(id || '').toLowerCase().replace(/[._]/g, '-');
+    const tokens = base.split('-').filter(token => token && !DATE_SUFFIX.test(`-${token}`) && token !== 'latest' && token !== 'preview');
+    if (!tokens.length) return base;
+    const [first, ...rest] = tokens;
+    return `${first}:${[...rest].sort().join('-')}`;
+  }
+
+  function matchModel(catalog, modelId) {
+    if (!catalog || !modelId) return null;
+    const bare = String(modelId).toLowerCase();
+    const direct = catalog.exact.get(bare);
+    if (direct) return direct;
+    // Fetched ids sometimes carry a provider prefix (openai/gpt-4o).
+    const suffix = bare.includes('/') ? bare.slice(bare.lastIndexOf('/') + 1) : bare;
+    if (suffix !== bare) {
+      const prefixed = catalog.exact.get(suffix);
+      if (prefixed) return prefixed;
+    }
+    let stripped = suffix;
+    while (true) {
+      const next = stripped.replace(DATE_SUFFIX, '');
+      if (next === stripped) break;
+      stripped = next;
+      const hit = catalog.exact.get(stripped);
+      if (hit) return hit;
+    }
+    const fuzzy = catalog.tokenKeys.get(tokenKey(suffix));
+    return fuzzy || null;
+  }
+
+  async function loadCatalog() {
+    if (cache && Date.now() - cache.fetchedAt < METADATA_TTL_MS) return cache;
+    if (!inFlight) {
+      inFlight = (async () => {
+        try {
+          const result = await fetchJson(modelsDevUrl, {});
+          if (!result.response.ok) return null;
+          const next = normalizeCatalog(result.data);
+          cache = next;
+          return next;
+        } catch {
+          return null; // offline/blocked: detection continues without capabilities
+        } finally {
+          inFlight = null;
+        }
+      })();
+    }
+    return inFlight;
+  }
+
+  function capabilityTags(entry) {
+    if (!entry) return [];
+    const tags = [];
+    if (entry.reasoning) tags.push('思考');
+    if (entry.input.includes('image')) tags.push('图片');
+    if (entry.input.includes('audio')) tags.push('音频');
+    if (entry.input.includes('pdf')) tags.push('PDF');
+    if (entry.toolCall) tags.push('工具');
+    return tags.slice(0, 8);
+  }
+
+  // Dual-protocol relays usually expose both routes on one origin: the OpenAI
+  // api at /v1 and the Anthropic api at /anthropic.
+  function sameOriginPath(baseUrl, segment) {
+    try { return `${new URL(baseUrl).origin}${segment}`; } catch { return ''; }
+  }
+
+  async function detectModels({ profile } = {}) {
+    if (!profile || typeof profile !== 'object') {
+      throw Object.assign(new Error('profile is required'), { status: 400 });
+    }
+    const apiKey = String(profile.apiKey || '');
+    // Explicit slots first; an empty slot falls back to probing the same
+    // origin of the filled one, and a verified hit is reported so the caller
+    // can pin it.
+    const anthropicBase = String(profile.baseUrl || '').trim()
+      || sameOriginPath(String(profile.openaiBaseUrl || '').trim(), '/anthropic');
+    const openaiBase = String(profile.openaiBaseUrl || '').trim()
+      || sameOriginPath(String(profile.baseUrl || '').trim(), '/v1');
+    if (!anthropicBase && !openaiBase) {
+      throw Object.assign(new Error('a base URL is required to detect models'), { status: 400 });
+    }
+    if (!apiKey) {
+      throw Object.assign(new Error('an API key is required to detect models'), { status: 400 });
+    }
+
+    const attempts = [];
+    if (anthropicBase) {
+      attempts.push({ label: 'anthropic', base: anthropicBase, run: () => fetchAnthropicModels(anthropicBase, apiKey) });
+    }
+    if (openaiBase) {
+      attempts.push({ label: 'openai', base: openaiBase, run: () => fetchOpenAiModels(openaiBase, apiKey) });
+    }
+
+    const sources = {};
+    const failures = [];
+    const ordered = []; // canonical first-seen order: anthropic side wins
+    const seen = new Set();
+    for (const attempt of attempts) {
+      try {
+        const ids = await attempt.run();
+        sources[attempt.label] = { ok: true, baseUrl: attempt.base, count: ids.length };
+        for (const id of ids) {
+          const bare = id.includes('/') ? id.slice(id.lastIndexOf('/') + 1) : id;
+          if (!seen.has(bare)) { seen.add(bare); ordered.push(bare); }
+        }
+      } catch (error) {
+        sources[attempt.label] = { ok: false, baseUrl: attempt.base, error: error.message };
+        failures.push(error.message);
+      }
+    }
+    if (!ordered.length) {
+      throw Object.assign(new Error(failures.join(' ; ') || 'no models detected'), { status: 400 });
+    }
+
+    const catalog = await loadCatalog();
+    const models = ordered.slice(0, MAX_MODELS).map(id => {
+      const meta = matchModel(catalog, id);
+      const contextWindow = meta && meta.context || contextLookup(id) || null;
+      return {
+        id,
+        openaiId: id.replace(/\[1m\]$/i, ''),
+        label: meta && meta.name || id,
+        contextWindow,
+        tags: capabilityTags(meta),
+        reasoning: meta ? meta.reasoning : null,
+        toolCall: meta ? meta.toolCall : null,
+        input: meta ? meta.input : null,
+        output: meta ? meta.output : null,
+        maxOutput: meta ? meta.maxOutput : null,
+      };
+    });
+    return {
+      ok: true,
+      models,
+      sources,
+      metadataSource: catalog ? 'models.dev' : 'unavailable',
+    };
+  }
+
+  return { detectModels, matchModel, normalizeCatalog, stripVersionSuffix, tokenKey };
+}
+
+module.exports = { createModelDetection, MODELS_DEV_URL, METADATA_TTL_MS };