@link-assistant/hive-mind 2.18.0 → 2.19.0

package/src/model-catalogue-fetch.lib.mjs

@@ -0,0 +1,333 @@
+/**
+ * The token-free readers behind the live model catalogue (issue #2202, R2/R7/R8).
+ *
+ * One function per source in `MODEL_CATALOGUE_SOURCES`, each returning the same
+ * envelope so the orchestrator in ./model-catalogue.lib.mjs never has to know
+ * which one it called:
+ *
+ *   { status, models: [{ id, label, … }], meta: {}, error: string|null }
+ *
+ * `status` is `ok`, `skipped` (the source does not apply here — no credential,
+ * no router, no binary) or `error` (it applied and failed). The distinction
+ * matters to the caller: `skipped` is normal, `error` is worth showing.
+ *
+ * Every network call goes through `assertTokenFreeUrl`, so a URL that would run
+ * a model throws before a socket is opened rather than after a bill is incurred.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { assertTokenFreeUrl } from './model-catalogue-sources.lib.mjs';
+import { ROUTER_SIDECAR_CONTAINER_NAME, ROUTER_SIDECAR_PORT } from './router-isolation.lib.mjs';
+import { buildRouterCatalogueEndpoints, ROUTER_TOOL_SERVICE } from './router-routes.lib.mjs';
+
+const execFileAsync = promisify(execFile);
+
+export const DEFAULT_CATALOGUE_TIMEOUT_MS = 20_000;
+
+const ok = (models, meta = {}) => ({ status: 'ok', models, meta, error: null });
+const skipped = reason => ({ status: 'skipped', models: [], meta: {}, error: reason });
+const failed = error => ({ status: 'error', models: [], meta: {}, error: String(error?.message ?? error) });
+
+/**
+ * Reduce a provider's listing response to `{ id, label, … }` records.
+ *
+ * The shapes differ enough that sniffing them at the merge would be guesswork,
+ * so the shape is declared by the caller — for the router it comes from the
+ * route table, which already records one per catalogue endpoint.
+ */
+export const normalizeCataloguePayload = ({ shape, payload } = {}) => {
+  if (!payload || typeof payload !== 'object') return [];
+  if (shape === 'gemini') {
+    const entries = Array.isArray(payload.models) ? payload.models : [];
+    return entries
+      .map(entry => ({
+        id: String(entry?.name ?? '').replace(/^models\//, ''),
+        label: entry?.displayName ?? null,
+        contextWindow: entry?.inputTokenLimit ?? null,
+        maxOutput: entry?.outputTokenLimit ?? null,
+      }))
+      .filter(entry => entry.id);
+  }
+  if (shape === 'codex-cli') {
+    const entries = Array.isArray(payload.models) ? payload.models : [];
+    return entries
+      .map(entry => ({
+        id: String(entry?.slug ?? ''),
+        label: entry?.display_name ?? null,
+        visibility: entry?.visibility ?? null,
+        supportedInApi: entry?.supported_in_api ?? null,
+      }))
+      .filter(entry => entry.id);
+  }
+  // `anthropic` and `openai` both answer `{ data: [ { id, … } ] }`; they differ
+  // only in the optional fields, which are carried through as-is.
+  const entries = Array.isArray(payload.data) ? payload.data : [];
+  return entries
+    .map(entry => ({
+      id: String(entry?.id ?? ''),
+      label: entry?.display_name ?? null,
+      createdAt: entry?.created_at ?? (typeof entry?.created === 'number' ? new Date(entry.created * 1000).toISOString() : null),
+      ownedBy: entry?.owned_by ?? null,
+    }))
+    .filter(entry => entry.id);
+};
+
+/**
+ * The router's own health signal, carried alongside the models.
+ *
+ * The router's listing response is a superset of OpenAI's: it adds
+ * `using_fallback`, `degraded_providers`, `degraded_reasons` and
+ * `healthy_providers`. That is exactly what R5 asks `/models` to surface — "we
+ * should see which models are loaded live" — so it is preserved rather than
+ * normalised away.
+ */
+export const extractRouterCatalogueMeta = payload => ({
+  usingFallback: payload?.using_fallback ?? null,
+  degradedProviders: Array.isArray(payload?.degraded_providers) ? payload.degraded_providers : [],
+  degradedReasons: payload?.degraded_reasons ?? null,
+  healthyProviders: Array.isArray(payload?.healthy_providers) ? payload.healthy_providers : [],
+});
+
+/**
+ * Fetch a JSON document with the billable-URL guard in front of it.
+ *
+ * `fetchImpl` is injected rather than closed over so tests can drive every
+ * branch without a network, following the pattern the rest of the repository
+ * already uses.
+ */
+export const fetchJsonCatalogue = async (url, { sourceId = 'unknown', headers = {}, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS } = {}) => {
+  assertTokenFreeUrl(url, sourceId);
+  if (typeof fetchImpl !== 'function') throw new Error('No fetch implementation available');
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  try {
+    const response = await fetchImpl(url, { headers, signal: controller?.signal });
+    if (!response?.ok) throw new Error(`HTTP ${response?.status ?? '?'} from ${url}`);
+    return await response.json();
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+};
+
+/**
+ * Read the router's live catalogue.
+ *
+ * Two paths, because the sidecar Hive Mind starts publishes no port (see the
+ * `No -p` note in src/router-sidecar.lib.mjs): an operator-run router is fetched
+ * over the network, while the local sidecar is read from *inside* the container
+ * with `bun`, the same client `checkRouterSidecarHealth` uses for the same
+ * reason — the router's image ships no curl.
+ *
+ * A token is required either way. For the sidecar the caller supplies one it
+ * already leased, so `/models` mints nothing on its own.
+ */
+export const fetchRouterCatalogue = async ({ baseUrl, dialect, token = null, tool = null, containerName = ROUTER_SIDECAR_CONTAINER_NAME, transport = 'exec', fetchImpl = globalThis.fetch, run = execFileAsync, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS } = {}) => {
+  if (!baseUrl || !dialect) return skipped('router is not configured');
+  const endpoints = buildRouterCatalogueEndpoints({ baseUrl, dialect });
+  if (endpoints.length === 0) return skipped('this router dialect exposes no catalogue route');
+  if (!token) return skipped('no router token available');
+
+  // On the canonical dialect there is one catalogue per service, so asking about
+  // one tool should not fan out across all five. On the legacy dialect the single
+  // `/v1/models` already answers for every adopted provider, and the filter falls
+  // through to it because no entry matches the tool's service name.
+  const service = tool ? ROUTER_TOOL_SERVICE[String(tool).toLowerCase()] : null;
+  const wanted = service ? endpoints.filter(endpoint => endpoint.service === service) : [];
+  const selected = wanted.length > 0 ? wanted : endpoints;
+
+  const models = [];
+  const meta = { endpoints: [], usingFallback: null, degradedProviders: [], healthyProviders: [] };
+  const errors = [];
+  for (const endpoint of selected) {
+    assertTokenFreeUrl(endpoint.url, 'router');
+    try {
+      const payload = transport === 'http' ? await fetchJsonCatalogue(endpoint.url, { sourceId: 'router', headers: { Authorization: `Bearer ${token}` }, fetchImpl, timeoutMs }) : await fetchRouterCatalogueViaExec({ url: endpoint.url, token, containerName, run, timeoutMs });
+      const entries = normalizeCataloguePayload({ shape: endpoint.shape, payload });
+      for (const entry of entries) models.push({ ...entry, service: endpoint.service });
+      const endpointMeta = extractRouterCatalogueMeta(payload);
+      meta.endpoints.push({ service: endpoint.service, url: endpoint.url, count: entries.length, ...endpointMeta });
+      if (endpointMeta.usingFallback) meta.usingFallback = true;
+      meta.degradedProviders.push(...endpointMeta.degradedProviders);
+      meta.healthyProviders.push(...endpointMeta.healthyProviders);
+    } catch (error) {
+      errors.push(`${endpoint.service}: ${error?.message ?? error}`);
+    }
+  }
+
+  if (models.length === 0 && errors.length > 0) return failed(errors.join('; '));
+  meta.degradedProviders = [...new Set(meta.degradedProviders)];
+  meta.healthyProviders = [...new Set(meta.healthyProviders)];
+  if (errors.length > 0) meta.partialErrors = errors;
+  return ok(models, meta);
+};
+
+/**
+ * Read one catalogue endpoint from inside the sidecar.
+ *
+ * TLS verification is disabled for this call for the same reason the health
+ * probe disables it: the certificate names the network alias, the request is a
+ * loopback socket inside the container, and there is no network for anyone to
+ * sit in the middle of. The alternative — shipping the CA back into an image
+ * Hive Mind does not own — buys nothing here.
+ */
+export const fetchRouterCatalogueViaExec = async ({ url, token, containerName = ROUTER_SIDECAR_CONTAINER_NAME, run = execFileAsync, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS } = {}) => {
+  assertTokenFreeUrl(url, 'router');
+  // The container reaches itself on loopback; the authority in `url` is the
+  // alias, which does not resolve from inside.
+  const loopback = String(url).replace(/^https?:\/\/[^/]+/, `https://127.0.0.1:${ROUTER_SIDECAR_PORT}`);
+  assertTokenFreeUrl(loopback, 'router');
+  const script = `fetch(${JSON.stringify(loopback)},{headers:{Authorization:"Bearer "+process.env.ROUTER_CATALOGUE_TOKEN}}).then(r=>r.ok?r.text():Promise.reject(new Error("HTTP "+r.status))).then(t=>{process.stdout.write(t)}).catch(e=>{process.stderr.write(String(e&&e.message||e));process.exit(1)})`;
+  try {
+    const { stdout } = await run('docker', ['exec', '--env', 'NODE_TLS_REJECT_UNAUTHORIZED=0', '--env', `ROUTER_CATALOGUE_TOKEN=${token}`, containerName, 'bun', '-e', script], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 });
+    return JSON.parse(stdout);
+  } catch (error) {
+    // Node builds a failed `execFile`'s message as "Command failed: <argv…>",
+    // and this argv carries the leased router token. That message would travel
+    // straight into the source footer `/models` prints and into
+    // `hive-models --json`. So the failure is re-raised from the parts that are
+    // safe to show, and anything left is scrubbed of the token as well — docker
+    // itself sometimes echoes the environment back in its own error text.
+    //
+    // The cause is the caught error, but scrubbed first and in place: its
+    // message *and* its stack (which repeats the message) hold the argv, and a
+    // cause is printed in full by Node's default handler and by util.inspect.
+    scrubRouterToken(error, token);
+    throw new Error(redactRouterToken(describeExecFailure(error, containerName), token), { cause: error });
+  }
+};
+
+/** A failed `docker exec` described without repeating the command line. */
+const describeExecFailure = (error, containerName) => {
+  const detail = String(error?.stderr || '')
+    .trim()
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .join(' ');
+  if (detail) return `docker exec into ${containerName} failed: ${detail}`;
+  if (error?.code === 'ENOENT') return 'docker is not installed';
+  return `docker exec into ${containerName} failed (${error?.code ?? error?.signal ?? 'unknown error'})`;
+};
+
+/**
+ * Scrub a leased token out of a caught error, in place.
+ *
+ * Node puts the whole argv in `message`, repeats it in `stack`, and `exec`-style
+ * failures also carry it in `cmd`. Every string the error owns is rewritten, so
+ * attaching it as a `cause` cannot resurrect the secret somewhere downstream.
+ */
+const scrubRouterToken = (error, token) => {
+  if (!error || typeof error !== 'object') return error;
+  for (const key of ['message', 'stack', 'cmd', 'stdout', 'stderr']) {
+    const value = error[key];
+    if (typeof value !== 'string') continue;
+    const redacted = redactRouterToken(value, token);
+    if (redacted !== value) {
+      try {
+        error[key] = redacted;
+      } catch {
+        // A frozen error cannot be scrubbed; the caller still only surfaces the
+        // description built above, which never quotes the command line.
+      }
+    }
+  }
+  return error;
+};
+
+/** Replace a leased token wherever it survived into text meant for a human. */
+const redactRouterToken = (text, token) => {
+  const secret = String(token || '');
+  if (secret.length < 8) return text;
+  return String(text).split(secret).join('***');
+};
+
+/**
+ * Read the installed Codex CLI's compiled catalogue.
+ *
+ * No network, no account, no cost — the binary answers from what it was built
+ * with, which is also precisely the set it will accept as `--model`.
+ */
+export const fetchCodexCliCatalogue = async ({ run = execFileAsync, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS, binary = 'codex' } = {}) => {
+  try {
+    const { stdout } = await run(binary, ['debug', 'models'], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 });
+    const payload = JSON.parse(stdout);
+    return ok(normalizeCataloguePayload({ shape: 'codex-cli', payload }), { binary });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return skipped('codex CLI is not installed');
+    return failed(error);
+  }
+};
+
+/** Anthropic's listing endpoint, paginated with `after_id` and never metered. */
+export const fetchAnthropicCatalogue = async ({ env = process.env, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS, baseUrl = 'https://api.anthropic.com', maxPages = 5 } = {}) => {
+  const apiKey = String(env?.ANTHROPIC_API_KEY || '').trim();
+  if (!apiKey) return skipped('ANTHROPIC_API_KEY is not set');
+  const headers = { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' };
+  const models = [];
+  let afterId = null;
+  try {
+    for (let page = 0; page < maxPages; page += 1) {
+      const url = `${baseUrl.replace(/\/$/, '')}/v1/models?limit=100${afterId ? `&after_id=${encodeURIComponent(afterId)}` : ''}`;
+      const payload = await fetchJsonCatalogue(url, { sourceId: 'anthropic-api', headers, fetchImpl, timeoutMs });
+      models.push(...normalizeCataloguePayload({ shape: 'anthropic', payload }));
+      if (!payload?.has_more || !payload?.last_id) break;
+      afterId = payload.last_id;
+    }
+    return ok(models, { baseUrl });
+  } catch (error) {
+    return failed(error);
+  }
+};
+
+/** OpenAI's listing endpoint. Same reasoning as Anthropic's, single page. */
+export const fetchOpenAiCatalogue = async ({ env = process.env, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS, baseUrl = 'https://api.openai.com' } = {}) => {
+  const apiKey = String(env?.OPENAI_API_KEY || '').trim();
+  if (!apiKey) return skipped('OPENAI_API_KEY is not set');
+  try {
+    const payload = await fetchJsonCatalogue(`${baseUrl.replace(/\/$/, '')}/v1/models`, { sourceId: 'openai-api', headers: { Authorization: `Bearer ${apiKey}` }, fetchImpl, timeoutMs });
+    return ok(normalizeCataloguePayload({ shape: 'openai', payload }), { baseUrl });
+  } catch (error) {
+    return failed(error);
+  }
+};
+
+/**
+ * models.dev, the R8 fallback — metadata only.
+ *
+ * Returned as a flat map from bare model id to specification, so the merge can
+ * annotate a model without models.dev ever being able to claim one is available:
+ * it aggregates published specifications and knows nothing about this account.
+ */
+export const fetchModelsDevMetadata = async ({ fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_CATALOGUE_TIMEOUT_MS, url = 'https://models.dev/api.json' } = {}) => {
+  try {
+    const payload = await fetchJsonCatalogue(url, { sourceId: 'models-dev', fetchImpl, timeoutMs });
+    const metadata = {};
+    for (const provider of Object.values(payload ?? {})) {
+      for (const [modelId, model] of Object.entries(provider?.models ?? {})) {
+        // First provider wins: the same id under two providers describes the
+        // same model, and the extra copies only differ in pricing presentation.
+        if (!metadata[modelId]) metadata[modelId] = { ...model, provider: provider?.name ?? provider?.id ?? null };
+      }
+    }
+    return ok([], { metadata, providerCount: Object.keys(payload ?? {}).length });
+  } catch (error) {
+    return failed(error);
+  }
+};
+
+export default {
+  DEFAULT_CATALOGUE_TIMEOUT_MS,
+  extractRouterCatalogueMeta,
+  fetchAnthropicCatalogue,
+  fetchCodexCliCatalogue,
+  fetchJsonCatalogue,
+  fetchModelsDevMetadata,
+  fetchOpenAiCatalogue,
+  fetchRouterCatalogue,
+  fetchRouterCatalogueViaExec,
+  normalizeCataloguePayload,
+};

package/src/model-catalogue-render.lib.mjs

@@ -0,0 +1,191 @@
+/**
+ * Rendering for the merged model catalogue (issue #2202, R5).
+ *
+ * R5 asks that `/models` show "list of merged models (from fully supported, to
+ * hot loaded)… which models are loaded live, and available for use with all our
+ * tools, and which models are included with Hive Mind installation". Those are
+ * the three groups `mergeModelCatalogue` produces, and this module is the only
+ * place that decides how they look — so the CLI and the Telegram command cannot
+ * drift apart, and both can be tested without a network.
+ *
+ * Pure formatting: no I/O, no imports beyond the source table it labels with.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ */
+
+import { getModelCatalogueSource } from './model-catalogue-sources.lib.mjs';
+
+/** Telegram refuses a message over 4096 characters; leave room for the footer. */
+export const TELEGRAM_MESSAGE_BUDGET = 3600;
+
+export const GROUP_TITLES = Object.freeze({
+  bundledAndLive: { title: 'Bundled and live', note: 'shipped with this installation and confirmed reachable now' },
+  liveOnly: { title: 'Hot loaded', note: 'a live source has them, this installation does not — use with --model at your own risk' },
+  bundledOnly: { title: 'Bundled only', note: 'shipped, but no live source confirmed them' },
+});
+
+/**
+ * With hot load off there is nothing to compare against, so "no live source
+ * confirmed them" would be an accusation rather than a fact.
+ */
+export const groupHeading = (key, { hotLoad = true } = {}) => (!hotLoad && key === 'bundledOnly' ? { title: 'Bundled', note: 'shipped with this installation; live sources were not consulted' } : GROUP_TITLES[key]);
+
+/** "2 minutes", "1 hour" — a duration a person reads rather than parses. */
+export const formatAge = ms => {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+};
+
+/** 200000 → "200K", 1000000 → "1M". Context windows are quoted, not computed. */
+export const formatTokenCount = value => {
+  const tokens = Number(value);
+  if (!Number.isFinite(tokens) || tokens <= 0) return null;
+  if (tokens >= 1_000_000) return `${Math.round((tokens / 1_000_000) * 10) / 10}M`;
+  if (tokens >= 1000) return `${Math.round(tokens / 1000)}K`;
+  return String(tokens);
+};
+
+/**
+ * The R8 technical detail line for one model.
+ *
+ * Whatever the sources actually carried, in a fixed order, and nothing when
+ * they carried nothing — an invented number is worse than a blank.
+ */
+export const formatModelSpec = (model = {}) => {
+  const spec = model.spec ?? {};
+  const parts = [];
+  const context = formatTokenCount(model.contextWindow ?? spec?.limit?.context);
+  if (context) parts.push(`${context} ctx`);
+  const output = formatTokenCount(model.maxOutput ?? spec?.limit?.output);
+  if (output) parts.push(`${output} out`);
+  const input = spec?.cost?.input;
+  const outputCost = spec?.cost?.output;
+  if (Number.isFinite(Number(input)) && Number.isFinite(Number(outputCost))) parts.push(`$${input}/$${outputCost} per Mtok`);
+  if (spec?.reasoning === true) parts.push('reasoning');
+  if (Array.isArray(spec?.modalities?.input) && spec.modalities.input.length > 1) parts.push(spec.modalities.input.join('+'));
+  if (spec?.release_date) parts.push(String(spec.release_date));
+  return parts.join(' · ');
+};
+
+/** Source ids as a reader-facing list: `router, anthropic-api` → their labels. */
+export const formatModelSources = (model = {}) =>
+  (model.sources ?? [])
+    .map(id => getModelCatalogueSource(id)?.label ?? id)
+    .filter(Boolean)
+    .join(', ');
+
+/** One line per source: what it said, and how old the answer is. */
+export const describeCatalogueSources = (catalogue = {}) =>
+  (catalogue.sources ?? []).map(source => {
+    // A metadata source contributes specifications, not names, so counting its
+    // models would always print "0" and read like a failure.
+    const okDetail = source.kind === 'metadata' ? `specifications for ${Object.keys(source.meta?.metadata ?? {}).length} model(s)` : `${source.models?.length ?? 0} model(s)`;
+    const detail = source.status === 'ok' ? okDetail : source.error || source.status;
+    const age = source.cached ? ` · cached ${formatAge(source.ageMs)}` : '';
+    const stale = source.stale ? ' · stale' : '';
+    return { id: source.id, label: source.label ?? source.id, status: source.status, text: `${source.label ?? source.id}: ${source.status} — ${detail}${age}${stale}` };
+  });
+
+const modelLine = (model, { details = false } = {}) => {
+  const columns = [model.id];
+  if (model.aliases?.length > 0) columns.push(`(${model.aliases.join(', ')})`);
+  if (model.label && model.label !== model.id) columns.push(`— ${model.label}`);
+  const spec = details ? formatModelSpec(model) : '';
+  if (spec) columns.push(`[${spec}]`);
+  const sources = details ? formatModelSources(model) : '';
+  if (sources) columns.push(`via ${sources}`);
+  return columns.join(' ');
+};
+
+/**
+ * The plain-text rendering used by `hive-models`.
+ *
+ * @param {object} merged result of `mergeModelCatalogue`, with `.catalogue`
+ * @param {object} options `details` adds the R8 specification columns
+ */
+export const formatModelCatalogueText = (merged = {}, { details = false, defaultModel = null } = {}) => {
+  const catalogue = merged.catalogue ?? {};
+  const lines = [];
+  lines.push(`Models for ${merged.tool}${merged.default ? ` (default: ${merged.default})` : ''}`);
+  lines.push(`${merged.counts?.bundledAndLive ?? 0} bundled and live · ${merged.counts?.liveOnly ?? 0} hot loaded · ${merged.counts?.bundledOnly ?? 0} bundled only`);
+
+  for (const key of ['bundledAndLive', 'liveOnly', 'bundledOnly']) {
+    const group = merged[key] ?? [];
+    if (group.length === 0) continue;
+    lines.push('');
+    const heading = groupHeading(key, { hotLoad: catalogue.hotLoad !== false });
+    lines.push(`${heading.title} (${group.length}) — ${heading.note}`);
+    for (const model of group) {
+      const marker = defaultModel && (model.id === defaultModel || model.aliases?.includes(defaultModel)) ? '*' : ' ';
+      lines.push(`  ${marker} ${modelLine(model, { details })}`);
+    }
+  }
+
+  const sources = describeCatalogueSources(catalogue);
+  if (sources.length > 0) {
+    lines.push('');
+    lines.push('Sources, in the order they are trusted:');
+    for (const source of sources) lines.push(`  - ${source.text}`);
+  }
+  // Only when the router never became a source line of its own; otherwise this
+  // repeats what the list above already said.
+  const routerReported = (catalogue.sources ?? []).some(source => source.id === 'router');
+  if (!routerReported && catalogue.router && !catalogue.router.available && catalogue.router.reason) lines.push(`  - router: not read — ${catalogue.router.reason}`);
+  lines.push('');
+  lines.push(`Live answers are cached for ${formatAge(catalogue.ttlMs ?? 0)}; pass --refresh to ignore the cache.`);
+  if (catalogue.hotLoad === false) lines.push('Hot load is disabled (HIVE_MIND_MODELS_HOT_LOAD), so only the bundled catalogue was consulted.');
+  return lines.join('\n');
+};
+
+/**
+ * The Telegram rendering.
+ *
+ * Same content, but budgeted: a full catalogue is far longer than one message,
+ * so each group is truncated with an explicit "and N more" rather than being
+ * silently cut by the API.
+ */
+export const formatModelCatalogueTelegram = (merged = {}, { details = false, budget = TELEGRAM_MESSAGE_BUDGET, perGroupLimit = 40 } = {}) => {
+  const catalogue = merged.catalogue ?? {};
+  const lines = [];
+  lines.push(`🧠 *Models for ${merged.tool}*${merged.default ? ` — default \`${merged.default}\`` : ''}`);
+  lines.push(`${merged.counts?.bundledAndLive ?? 0} bundled and live · ${merged.counts?.liveOnly ?? 0} hot loaded · ${merged.counts?.bundledOnly ?? 0} bundled only`);
+
+  for (const key of ['bundledAndLive', 'liveOnly', 'bundledOnly']) {
+    const group = merged[key] ?? [];
+    if (group.length === 0) continue;
+    lines.push('');
+    const heading = groupHeading(key, { hotLoad: catalogue.hotLoad !== false });
+    lines.push(`*${heading.title}* (${group.length}) — _${heading.note}_`);
+    for (const model of group.slice(0, perGroupLimit)) lines.push(`• \`${model.id}\`${details && formatModelSpec(model) ? ` — ${formatModelSpec(model)}` : ''}`);
+    if (group.length > perGroupLimit) lines.push(`… and ${group.length - perGroupLimit} more`);
+  }
+
+  lines.push('');
+  const sources = describeCatalogueSources(catalogue);
+  lines.push(`Sources: ${sources.map(source => `${source.label} (${source.status})`).join(' · ') || 'none'}`);
+  lines.push(`Cached for ${formatAge(catalogue.ttlMs ?? 0)}; \`/models --refresh\` re-reads them.`);
+
+  const text = lines.join('\n');
+  if (text.length <= budget) return text;
+  // Trim whole lines from the model listings rather than cutting mid-token, and
+  // keep the footer, which is the part that explains what was left out.
+  const footer = lines.slice(-3).join('\n');
+  const head = [];
+  let used = footer.length + 24;
+  for (const line of lines.slice(0, -3)) {
+    if (used + line.length + 1 > budget) {
+      head.push('… list truncated; run `hive-models` for the full catalogue');
+      break;
+    }
+    head.push(line);
+    used += line.length + 1;
+  }
+  return `${head.join('\n')}\n\n${footer}`;
+};
+
+export default { GROUP_TITLES, groupHeading, TELEGRAM_MESSAGE_BUDGET, describeCatalogueSources, formatAge, formatModelCatalogueTelegram, formatModelCatalogueText, formatModelSources, formatModelSpec, formatTokenCount };