@kolbo/mcp 1.58.0 → 1.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.58.0",
+  "version": "1.60.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -10,7 +10,8 @@
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "check-model-catalog": "node scripts/check-model-catalog.js",
     "check-widget-fields": "node scripts/check-widget-fields.js",
     "check-widget-render": "node scripts/check-widget-render.js",
     "check-skill-tools": "node scripts/check-skill-tools.js",

package/src/apps/index.js

@@ -203,7 +203,10 @@ async function modelInfoMap(client) {
       // Real p75 wall-clock estimate mined from production creditUsages —
       // the same source the in-app countdowns use. No estimate → no ETA shown.
       const eta = Number(m.estimatedDurationSeconds || m.estimated_duration_seconds) || null;
-      const info = { icon, eta, id: m.identifier || null };
+      // `name` is the CLEAN display name ("Google TTS"); it is what widgets show.
+      // Without it the model chip fell back to whatever raw string the caller or
+      // the status endpoint supplied ("google_tts", "fal-ai/bytedance/omnihuman/v1.5").
+      const info = { icon, eta, id: m.identifier || null, name: m.name || null };
       // Display names collide across variants ("Nano Banana 2" names both the
       // t2i model and its editing sibling) — on collision keep the model with
       // the SHORTEST identifier (the base model), deterministically.
@@ -224,11 +227,51 @@ async function modelInfoMap(client) {
   return byKey;
 }
 
-/** Resolve one model's { icon, eta }; missing → { icon: null, eta: null }. */
+/** Resolve one model's { icon, eta, name }; missing → all null. */
 async function modelInfo(client, modelName) {
-  if (!modelName) return { icon: null, eta: null };
+  if (!modelName) return { icon: null, eta: null, name: null };
   const map = await modelInfoMap(client);
-  return map.get(String(modelName).toLowerCase()) || { icon: null, eta: null };
+  return map.get(String(modelName).toLowerCase()) || { icon: null, eta: null, name: null };
+}
+
+/* ------------------------------------------------------------------ */
+/* Voice lookup (voice_id / display name → { id, name, thumbnail })    */
+/* ------------------------------------------------------------------ */
+
+// Same shape and TTL as the model catalog above: the voice catalog is stable,
+// and a per-generation /v1/voices round trip would be paid on every speech card.
+const voiceCache = new Map(); // apiBase → { at, byKey }
+
+async function voiceInfoMap(client) {
+  const cacheKey = client.apiBase || 'default';
+  const hit = voiceCache.get(cacheKey);
+  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit.byKey;
+  const byKey = new Map();
+  try {
+    const res = await client.request('GET', '/v1/voices');
+    for (const v of res?.voices || []) {
+      if (!v || !v.voice_id) continue;
+      // thumbnail/preview come from the catalog record — NEVER templated from
+      // the id, so a change to the CDN path scheme cannot silently 404 the card.
+      const info = { id: v.voice_id, name: v.name || v.voice_id, thumbnail: v.thumbnail || null };
+      byKey.set(String(v.voice_id).toLowerCase(), info);
+      // Display names are not unique across locales (the same Gemini voice is
+      // catalogued per language). First one wins; the id lookup above is exact.
+      const nameKey = String(info.name).toLowerCase();
+      if (v.name && !byKey.has(nameKey)) byKey.set(nameKey, info);
+    }
+  } catch (_) {
+    /* fail open — cards fall back to the raw voice string */
+  }
+  if (byKey.size > 0) voiceCache.set(cacheKey, { at: Date.now(), byKey });
+  return byKey;
+}
+
+/** Resolve a voice id OR display name to { id, name, thumbnail }; null if unknown. */
+async function voiceInfo(client, voice) {
+  if (!voice) return null;
+  const map = await voiceInfoMap(client);
+  return map.get(String(voice).toLowerCase().trim()) || null;
 }
 
 /** Back-compat shim (used by uiCompleted and older call sites). */
@@ -236,29 +279,79 @@ async function modelIcon(client, modelName) {
   return (await modelInfo(client, modelName)).icon;
 }
 
+// Separator-insensitive key. Catalog keys carry their own punctuation — the
+// NAME is keyed "minimax h3", the IDENTIFIER "flux-2/flash" — so both sides
+// must be flattened before comparing. Normalising only the input (the old
+// `key.replace(/\s+/g, '-')`) is why "flux-2-flash" never found "flux-2/flash".
+const normId = (s) => String(s || '').toLowerCase().replace(/[\s._/-]+/g, '');
+
+// The API maps these to Smart Select itself. They are never typos, so they must
+// never be "corrected" or reported as unknown.
+const AUTO_ALIASES = new Set([
+  'auto', 'autoselect', 'smartselect', 'kolbosmartselectrouter', 'default', 'none',
+]);
+
 /**
  * Lenient model-identifier resolution for LLM-supplied model args.
  * Users say "z-image"; the real identifier is "z-image/turbo" — the backend
  * has no fuzzy matching on generation routes and fails deep in credit
  * reservation. Resolve here: exact name/identifier hit → its identifier;
- * else a UNIQUE identifier prefix match ("z-image" → "z-image/turbo");
- * ambiguous or unknown → pass through unchanged (API stays source of truth).
+ * else a separator-insensitive hit ("flux-2-flash" → "flux-2/flash"); else a
+ * UNIQUE prefix match ("z-image" → "z-image/turbo").
+ *
+ * Still unresolved: throw with the near misses named. The API answers a bad
+ * identifier with a bare INVALID_*_MODEL and no hint, which on 2026-08-09 sent
+ * an agent guessing "minimax-hailuo-3" (real id: "minimax-h3") and then
+ * substituting a far more expensive model. Only throws when the catalog is
+ * healthy AND actually offers candidates — otherwise it passes through
+ * unchanged, so identifiers the catalog does not publish (hidden models) still
+ * reach the API and it stays the source of truth.
  */
 async function canonicalModelId(client, input) {
   if (!input || typeof input !== 'string') return input;
+  const key = input.toLowerCase().trim();
+  const want = normId(key);
+  if (!want || AUTO_ALIASES.has(want)) return input;
+
+  let map;
   try {
-    const map = await modelInfoMap(client);
-    const key = input.toLowerCase().trim();
-    const hit = map.get(key) || map.get(key.replace(/\s+/g, '-'));
-    if (hit && hit.id) return hit.id;
-    const ids = new Set();
-    for (const info of map.values()) {
-      const id = (info.id || '').toLowerCase();
-      if (id && (id.startsWith(key + '/') || id.startsWith(key + '-'))) ids.add(info.id);
+    map = await modelInfoMap(client);
+  } catch (_) {
+    return input; // fail open — never block a generation on a catalog hiccup
+  }
+  if (!map || map.size === 0) return input;
+
+  // 1. exact name / identifier hit
+  const hit = map.get(key) || map.get(key.replace(/\s+/g, '-'));
+  if (hit && hit.id) return hit.id;
+
+  // 2 + 3. separator-insensitive exact, then unique prefix
+  const byNorm = new Map();
+  for (const info of map.values()) {
+    if (!info.id) continue;
+    for (const k of [info.id, info.name]) {
+      const n = normId(k);
+      if (n && !byNorm.has(n)) byNorm.set(n, info.id);
     }
-    if (ids.size === 1) return [...ids][0];
-  } catch (_) { /* fail open */ }
-  return input;
+  }
+  if (byNorm.has(want)) return byNorm.get(want);
+  const prefixed = new Set();
+  for (const [n, id] of byNorm) if (n.startsWith(want)) prefixed.add(id);
+  if (prefixed.size === 1) return [...prefixed][0];
+
+  // 4. unknown — name the near misses instead of dead-ending at the API.
+  const stem = normId(key.split(/[\s._/-]+/).filter(Boolean)[0] || key);
+  const near = [...new Set(
+    [...map.values()]
+      .filter((i) => i.id && stem && (normId(i.id).startsWith(stem) || normId(i.name).startsWith(stem)))
+      .map((i) => (i.name ? `${i.id} (${i.name})` : i.id))
+  )].sort().slice(0, 12);
+  if (!near.length) return input;
+  throw new Error(
+    `Unknown model identifier "${input}". Did you mean: ${near.join(', ')}? `
+    + 'Never guess an identifier — call list_models with the matching `type` and `format: "json"` '
+    + 'to get the exact identifiers and caps.'
+  );
 }
 
 /* ------------------------------------------------------------------ */
@@ -341,6 +434,7 @@ module.exports = {
   modelIcon,
   modelInfo,
   modelInfoMap,
+  voiceInfo,
   canonicalModelId,
   resolveAvatarUrl,
   widgetHtml, // exported for smoke tests

package/src/apps/theme.js

@@ -111,6 +111,7 @@ body {
   color: #fff; font-size: 9px; font-weight: 700; display: inline-flex;
   align-items: center; justify-content: center; font-family: 'Inter', sans-serif;
 }
+.k-chip img.k-voice-thumb { width: 18px; height: 18px; border-radius: 999px; margin-left: -3px; }
 .k-ref-thumb { width: 26px; height: 26px; border-radius: 6px; object-fit: cover; border: 1px solid var(--border-strong); }
 
 /* ---- Generating state ---- */

package/src/apps/widgets/generation.js

@@ -105,8 +105,14 @@ function boot(sc) {
   window.kolbo.notifySize();
 }
 
+// model_name / voice_name are the CLEAN catalog names, resolved server-side
+// (src/tools/_shared.js on submit, get_generation_status on completion). The raw
+// ids stay in sc.model / sc.voice for Recreate + model context — never for display.
+function modelLabel(sc) { return sc.model_name || sc.model; }
+function voiceLabel(sc) { return sc.voice_name || sc.voice || (sc.settings || {}).voice; }
+
 function renderChips(sc) {
-  var h = modelChipHTML(sc.model, sc.model_icon);
+  var h = modelChipHTML(modelLabel(sc), sc.model_icon);
   var s = sc.settings || {};
   if (sc.kind) h += chip(iconFor(sc.kind) + ' ' + sc.kind);
   if (s.duration) h += chip(ICONS.clock + ' ' + fmtDur(s.duration));
@@ -120,7 +126,13 @@ function renderChips(sc) {
   if (s.preset) h += chip('preset');
   if (s.cinematic) h += chip('cinematic');
   if (s.audio) h += chip(ICONS.sound + ' audio');
-  if (s.voice) h += chip(ICONS.mic + ' ' + esc(s.voice));
+  var voice = voiceLabel(sc);
+  if (voice) {
+    var face = sc.voice_thumbnail
+      ? '<img class="k-voice-thumb" src="' + esc(sc.voice_thumbnail) + '" alt="" loading="lazy" onerror="this.style.display=\\'none\\'">'
+      : ICONS.mic;
+    h += chip(face + ' ' + esc(voice));
+  }
   if (s.mode) h += chip(esc(s.mode));
   if (sc.count > 1) h += chip('×' + sc.count);
   if (sc.reference_image) h += '<img class="k-ref-thumb" src="' + esc(sc.reference_image) + '" alt="" loading="lazy" title="Reference image" onerror="this.style.display=\\'none\\'">';
@@ -414,6 +426,10 @@ function fillBatchCell(sc, i, g) {
 function renderResult(sc) {
   clearTimeout(pollTimer);
 
+  // Repaint the chips: the generating phase only knew what the CALLER asked for
+  // (often nothing → "Smart Select"). The completed status carries the model and
+  // voice that actually ran, so the finished card must not keep the guess.
+  renderChips(sc);
   setPhaseChip('', false);
   if (sc.batch && sc.scenes && sc.scenes.length) return renderBatchGrid(sc);
   if (sc.kind === 'scenes' && sc.scenes && sc.scenes.length) return renderScenes(sc);
@@ -482,7 +498,9 @@ function renderAudio(sc, urls) {
       (artwork ? '<img class="k-audio-art" src="' + esc(artwork) + '" alt="" loading="lazy">' :
         '<div class="k-audio-art k-audio-placeholder">' + ICONS.audio + '</div>') +
       '<div class="k-audio-meta"><div class="k-audio-title">' + esc(title) + '</div>' +
-      '<div class="k-audio-sub">' + esc(track.model || sc.model || '') +
+      // Resolved name first: a per-track model field is the raw id, and every
+      // track in one generation came from the same model anyway.
+      '<div class="k-audio-sub">' + esc(modelLabel(sc) || track.model || '') +
       (duration ? ' · ' + fmtDur(duration) : '') + '</div></div>' +
       '<button class="k-btn k-audio-download" data-audio-download="' + esc(u) +
       '" aria-label="Download ' + esc(title) + '">' + ICONS.download + ' Download</button>' +

package/src/tools/_shared.js

@@ -484,7 +484,22 @@ function buildProjectUrl(projectId, opts = {}) {
 // ui://kolbo/generation.html widget takes over: live progress, inline result,
 // action buttons. Text-only hosts never enter this path — their blocking
 // behavior and response bytes are UNCHANGED.
-const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
+const { UI, uiResult, appsEnabled, modelInfo } = require('../apps');
+
+/**
+ * Chip identity for a model: the CLEAN display name + its icon, resolved from
+ * the same /v1/models catalog `list_models` renders. Callers pass whatever the
+ * user/LLM supplied (an identifier like `google_tts`, `fal-ai/…/omnihuman/v1.5`,
+ * or a display name) — the card must never show the raw id.
+ */
+async function modelChipFields(client, model) {
+  const info = await modelInfo(client, model).catch(() => null);
+  return {
+    model: model || 'Smart Select',
+    model_name: (info && info.name) || model || 'Smart Select',
+    model_icon: (info && info.icon) || null,
+  };
+}
 
 /**
  * Build the "submitted — widget is live" tool result for a UI host.
@@ -494,12 +509,13 @@ const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
  *   gen            the submit response ({ generation_id, poll_interval_hint })
  *   client         KolboClient (for model icon lookup)
  *   model, prompt, count, settings, reference_image, estimated_seconds
+ *   voice          resolved voice record { name, thumbnail } (speech only)
  *   poll_tool      widget-side status tool (default 'get_generation_status')
  *   status_args    args for poll_tool (default { generation_id, wait: true })
  */
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
-  const icon = await modelIcon(p.client, p.model).catch(() => null);
+  const chip = await modelChipFields(p.client, p.model);
   const structured = {
     phase: 'generating',
     widget: 'generation',
@@ -511,8 +527,8 @@ async function uiGenerating(p) {
     // wait=true, every open card calls tools/call every few seconds, flooding
     // the host's global progress/context stream and API rate limits.
     status_args: p.status_args || { generation_id: p.gen.generation_id, wait: true },
-    model: p.model || 'Smart Select',
-    model_icon: icon,
+    ...chip,
+    ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},
@@ -531,6 +547,7 @@ async function uiGenerating(p) {
       ? { batch: true, generation_ids: p.generation_ids } : {}),
     ...(p.failed_submissions && p.failed_submissions.length
       ? { failed_submissions: p.failed_submissions } : {}),
+    ...(p.warning ? { _warning: p.warning } : {}),
     _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you need the output URLs (e.g. for a follow-up edit or a report), call get_generation_status ONCE with wait=true — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
   }, null, 2);
   return uiResult(UI.generation, text, structured);
@@ -541,14 +558,13 @@ async function uiGenerating(p) {
  * that stay blocking even on UI hosts, e.g. creative director).
  */
 async function uiCompleted(p, textPayload) {
-  const icon = await modelIcon(p.client, p.model).catch(() => null);
+  const chip = await modelChipFields(p.client, p.model);
   const structured = {
     phase: 'completed',
     widget: 'generation',
     kind: p.kind,
     tool: p.tool,
-    model: p.model || 'Smart Select',
-    model_icon: icon,
+    ...chip,
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},

package/src/tools/generate.js

@@ -7,7 +7,7 @@ const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
 const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
-const { UI, uiResult, canonicalModelId } = require('../apps');
+const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
 // Kolbo's "Cinema mode": eight independent photographic dimensions, each an OPTIONAL
@@ -42,9 +42,20 @@ const CINEMATIC_SCHEMA = z.object({
 // The manual-control twin of generate_creative_director: no orchestration pass,
 // the user's exact prompts verbatim. Submit failures never sink the batch —
 // successful ids proceed, failed prompts are reported alongside.
+// Over the cap is a hard rejection, never a truncation: this used to
+// `.slice(0, MAX_BATCH_PROMPTS)`, so a 9-prompt call silently generated 8 and
+// the caller had no way to know which prompt vanished. `promptsField` also caps
+// the array in the schema (so hosts see `maxItems` before calling); the guard
+// below is the choke point EVERY batch tool routes through, and names the count.
 const MAX_BATCH_PROMPTS = 8;
 async function submitBatch(rawPrompts, submitOne) {
-  const prompts = rawPrompts.slice(0, MAX_BATCH_PROMPTS).map((s) => String(s).trim()).filter(Boolean);
+  if (rawPrompts.length > MAX_BATCH_PROMPTS) {
+    throw new Error(
+      `Too many prompts: ${rawPrompts.length} received, max ${MAX_BATCH_PROMPTS} per call. ` +
+      `Split them across ${Math.ceil(rawPrompts.length / MAX_BATCH_PROMPTS)} calls of at most ${MAX_BATCH_PROMPTS}.`
+    );
+  }
+  const prompts = rawPrompts.map((s) => String(s).trim()).filter(Boolean);
   const settled = await Promise.allSettled(prompts.map((p) => submitOne(p)));
   const ok = [], failed = [];
   settled.forEach((s, i) => {
@@ -91,8 +102,8 @@ const imageSettings = (a = {}) => ({
   cinematic: a.cinematic ? true : undefined,
 });
 
-const promptsField = (what) => z.array(z.string()).optional().describe(
-  `BATCH MODE — several DIFFERENT prompts (2–${MAX_BATCH_PROMPTS}) generated concurrently in ONE call and rendered together in ONE combined widget. Whenever the user wants multiple distinct ${what} with their own prompts, ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All prompts share the same model/settings. When set, \`prompt\` is ignored. For N variations of a SINGLE prompt use num_images (image tools); for an AI-planned coherent scene set use generate_creative_director.`
+const promptsField = (what) => z.array(z.string()).max(MAX_BATCH_PROMPTS).optional().describe(
+  `BATCH MODE — several DIFFERENT prompts (2–${MAX_BATCH_PROMPTS}) generated concurrently in ONE call and rendered together in ONE combined widget. **Hard cap: ${MAX_BATCH_PROMPTS} prompts per call — more than that is REJECTED with an error (never silently truncated), so split a longer list across several calls of at most ${MAX_BATCH_PROMPTS}.** Whenever the user wants multiple distinct ${what} with their own prompts, ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All prompts share the same model/settings. When set, \`prompt\` is ignored. For N variations of a SINGLE prompt use num_images (image tools); for an AI-planned coherent scene set use generate_creative_director.`
 );
 
 function registerGenerateTools(server, client, options = {}) {
@@ -588,7 +599,7 @@ function registerGenerateTools(server, client, options = {}) {
     'Convert text to speech using Kolbo AI. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Every voice belongs to a provider (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos) and each provider exposes its own expressive/style controls below — the engine ignores any control that does not apply to the chosen voice\'s provider, so it is safe to pass only what you need. Returns the final audio URL when complete.',
     {
       text: z.string().describe('The text to convert to speech'),
-      voice: z.string().optional().describe('Voice ID (from list_voices) or voice display name (e.g., "Rachel", "Adam"). Default: "Rachel"'),
+      voice: z.string().optional().describe('Voice ID or display name — MUST come from a `list_voices` result, never constructed. Google/Gemini ids in particular are not validated provider-side: an id that is not in the catalog is silently mapped to another voice (or a default one) and the audio comes back in a voice nobody asked for. Do not pattern-match a locale onto an id you saw for another language. Default: "Rachel"'),
       model: z.string().optional().describe('Model identifier. Use list_models type="text_to_speech" to see options. Default: eleven_v3'),
       language: z.string().optional().describe('Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"'),
       // ── Expressive style / emotion (provider-specific) ──
@@ -620,6 +631,16 @@ function registerGenerateTools(server, client, options = {}) {
     },
     async ({ text, voice, model, language, style_instructions, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      // Resolve the requested voice against the REAL catalog (cached) so the card
+      // can show its display name + portrait instead of a raw id, and so an id
+      // that does not exist is reported instead of rendering silently: Google
+      // voice ids collapse to their last segment provider-side, so a made-up
+      // "en-US-Chirp3-HD-<Name>" either speaks as some other catalog entry's
+      // voice or falls back to a default one — with the card naming neither.
+      const voiceRecord = await voiceInfo(client, voice).catch(() => null);
+      const unknownVoice = voice && !voiceRecord && !/^custom_/i.test(voice)
+        ? `Voice "${voice}" is not in the Kolbo voice catalog. Call list_voices and pass a voice_id it returns — an unrecognised id is NOT rejected, it is silently mapped to a different voice, so the audio will not be the voice you named.`
+        : null;
       const gen = await client.post('/v1/generate/speech', {
         text, voice, model, language,
         style_instructions, selected_style, emotion, speaking_speed,
@@ -631,7 +652,9 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_speech', kind: 'audio', gen, client, model, prompt: text,
-        settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions }
+        voice: voiceRecord,
+        settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions },
+        warning: unknownVoice
       });
 
       const poll = await pollOrTimedOut(client, gen.generation_id, {
@@ -648,7 +671,8 @@ function registerGenerateTools(server, client, options = {}) {
             ...creditFields(result),
             urls: result.result.urls,
             voice: result.result.voice,
-            duration: result.result.duration
+            duration: result.result.duration,
+            ...(unknownVoice ? { _warning: unknownVoice } : {})
           }, null, 2)
         }]
       };
@@ -713,6 +737,32 @@ function registerGenerateTools(server, client, options = {}) {
     }
   );
 
+  // The status endpoint reports RAW ids — `model: "google_tts"`, `voice:
+  // "he-IL-Chirp3-HD-Kore"`. That is the model/voice that ACTUALLY ran (for
+  // Smart Select it is the only place the choice surfaces), so the card must
+  // show it — but with the clean name + icon everything else uses. Resolved
+  // here, off the same cached catalogs `list_models` / `list_voices` serve, so
+  // the widget adds no round trip per generation. Written INTO `result` because
+  // that is the object the widget merges over its generating-phase state.
+  async function addDisplayNames(status) {
+    const r = status && status.result;
+    if (!r || typeof r !== 'object') return;
+    // Always WRITE both keys, even on a catalog miss: the widget merges this
+    // over its generating-phase state, so a missing key silently keeps the
+    // pre-submit guess ("Smart Select") for a model that is not what ran. An
+    // unresolvable id is at least honest.
+    if (r.model) {
+      const info = await modelInfo(client, r.model).catch(() => null);
+      r.model_name = (info && info.name) || r.model;
+      r.model_icon = (info && info.icon) || null;
+    }
+    if (r.voice) {
+      const v = await voiceInfo(client, r.voice).catch(() => null);
+      r.voice_name = (v && v.name) || r.voice;
+      r.voice_thumbnail = (v && v.thumbnail) || null;
+    }
+  }
+
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
@@ -753,6 +803,7 @@ function registerGenerateTools(server, client, options = {}) {
       };
 
       const results = await Promise.all(ids.map(checkOne));
+      await Promise.all(results.map(addDisplayNames));
 
       const pending = results.filter(r => r.state !== 'completed' && r.state !== 'failed' && r.state !== 'cancelled');
       const doneHint = 'ALL generations are in a final state — do NOT poll again. Report the results to the user.';

package/src/tools/models.js

@@ -83,15 +83,26 @@ function buildCatalogStructured(models, type, compact) {
   };
 }
 
+// One row per model — every identifier, nothing else. ~90 bytes/model, so the
+// whole 400+ model catalog fits in a payload an agent can actually read.
+const identifierRow = (m) => ({
+  identifier: m.identifier,
+  name: m.name,
+  types: m.types,
+  credit: m.credit,
+  ...(m.recommended ? { recommended: true } : {}),
+  ...(m.new_model ? { new_model: true } : {}),
+});
+
 function registerModelTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
   // ─── list_models ───────────────────────────────────────────
   server.tool(
     'list_models',
-    'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to get the raw model documents (every constraint field, useful for programmatic comparison / cap validation before submitting a generation). Default `format: "text"` returns the human-readable summary.',
+    'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to enumerate the catalog with exact identifiers — `format: "json"` + `type` returns the full raw model documents (every constraint field, for programmatic comparison / cap validation before submitting a generation); `format: "json"` alone returns a compact index of EVERY model and its identifier. Default `format: "text"` returns the human-readable summary. NEVER guess a model identifier: call this tool.',
     {
       type: z.string().optional().describe('Filter by DB type name: "text_to_img", "image_editing", "text_to_video", "img_to_video", "draw_to_video", "video_to_video", "elements", "firstlastgenerations", "lipsync-image", "lipsync-video", "music_gen", "text_to_speech", "text_to_sound", "stt", "text". Legacy aliases also accepted: "image", "image_edit", "video", "video_from_image", "video_from_video", "music", "speech", "sound", "chat", "lipsync" (both lipsync types), "three_d" (all 3D types), "first_last_frame", "transcription". Omit for all models.'),
-      format: z.enum(['text', 'json']).optional().describe('Output format. "text" (default) returns a human-readable summary with the most-used caps. "json" returns the raw model documents from the API — use this when you need to programmatically verify caps (max_reference_images, max_visual_dna, max_video_duration, supported_aspect_ratios, etc.) before passing an array/value that might exceed a model-specific limit. The JSON form is the source of truth; the text form is a convenience preview.'),
+      format: z.enum(['text', 'json']).optional().describe('Output format. "text" (default) returns a human-readable summary with the most-used caps. "json" is the source of truth for identifiers and caps: with `type` it returns the raw model documents from the API (identifier, credit, supported_durations, supported_resolutions, supported_aspect_ratios, max_reference_images, max_visual_dna, max_video_duration, …) for EVERY model of that type; without `type` it returns a compact index of every model in the catalog and its exact identifier. Use it whenever you need an identifier you have not seen listed, or must verify a cap before passing a value that might exceed a model-specific limit.'),
       display_catalog: z.boolean().optional().describe('Set true when the USER explicitly asked to see/browse the available models — the visual catalog opens expanded. Leave unset for internal lookups (verifying a model name, checking caps before a generation): the catalog stays collapsed to a single row the user can tap to browse.')
     },
     async ({ type, format, display_catalog }) => {
@@ -106,14 +117,41 @@ function registerModelTools(server, client, options = {}) {
       const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
       const result = await client.get(path);
 
-      // JSON mode — return the raw API documents unchanged. This is the
-      // authoritative shape; every constraint the agent might need to validate
-      // a request lives here (durations, reference caps, audio/video min/max,
-      // resolution multipliers, supports_* flags, prompt-length limits, etc.).
+      // ⚠️ Hosts that mount this widget (claude.ai, Claude Code desktop) hand the
+      // MODEL `structuredContent` and DROP `content[].text`. So every payload the
+      // agent needs has to ride in structuredContent — shipping it as text only
+      // makes it invisible. That is exactly how `format: "json"` came to return
+      // the curated 6-per-group picker instead of the raw documents: v1.53.1
+      // (406a51e) flipped `if (ui() && showCatalog)` → `if (ui())` on all three
+      // return paths, so the widget payload started shadowing the real answer and
+      // the other 43 text_to_video identifiers became undiscoverable by any MCP
+      // call. On 2026-08-09 that cost a wrong-model generation (minimax-h3).
+      // `extra` (json mode) carries the data as structured fields; without it the
+      // full text payload is attached verbatim. The widget ignores both.
+      const respond = (text, extra) => (ui()
+        ? uiResult(UI.catalog, text, {
+            ...buildCatalogStructured(result.models, type, !showCatalog),
+            ...(extra || { text }),
+          })
+        : { content: [{ type: 'text', text }] });
+
+      // JSON mode — the authoritative shape; every constraint the agent might
+      // need to validate a request lives here (durations, reference caps,
+      // audio/video min/max, resolution multipliers, supports_* flags,
+      // prompt-length limits, etc.).
       if (format === 'json') {
-        const text = JSON.stringify({ count: result.count, models: result.models }, null, 2);
-        if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
-        return { content: [{ type: 'text', text }] };
+        // Raw documents once `type` narrows the set (~49 docs for a video type).
+        // Unfiltered that is 400+ documents / hundreds of KB, so return the
+        // complete IDENTIFIER INDEX instead: every model stays enumerable and
+        // the full caps are one `type` away.
+        const payload = type
+          ? { count: result.count, models: result.models }
+          : {
+              count: result.count,
+              models: result.models.map(identifierRow),
+              note: 'Compact index — every model in the catalog and its exact identifier. Re-call with `type` for the full documents (all caps, credit costs, supported_* fields).',
+            };
+        return respond(JSON.stringify(payload, null, 2), payload);
       }
 
       // Split into auto-selectable (has summary) and named-only (no summary)
@@ -306,9 +344,9 @@ function registerModelTools(server, client, options = {}) {
           + '  first_last_frame · elements · lipsync · music_gen · text_to_speech ·\n'
           + '  text_to_sound · stt · three_d · text\n\n'
           + 'Use the "identifier" value as the "model" parameter in generate tools. '
-          + 'For raw documents (programmatic cap validation), re-call with format: "json".';
-        if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
-        return { content: [{ type: 'text', text }] };
+          + 'For EVERY model + its exact identifier, re-call with format: "json" (compact index of the '
+          + 'whole catalog). Add `type` to that call for the full raw documents with all caps.';
+        return respond(text);
       }
 
       if (withSummary.length > 0) {
@@ -318,9 +356,8 @@ function registerModelTools(server, client, options = {}) {
         sections.push(`Named-only models (${withoutSummary.length}) — only use if the user explicitly requests by name:\n${withoutSummary.map(formatModel).join('\n')}`);
       }
 
-      const text = `Available ${type} models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`;
-      if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
-      return { content: [{ type: 'text', text }] };
+      const text = `Available ${type} models (${result.count}):\n\n${sections.join('\n\n')}\n\nEvery ${type} model in the catalog is listed above — both sections together are the complete set. Use the "identifier" value as the "model" parameter in generate tools. For the raw documents (programmatic cap validation), re-call with format: "json".`;
+      return respond(text);
     }
   );
 

package/src/tools/voices.js

@@ -19,14 +19,29 @@ function registerVoiceTools(server, client, options = {}) {
     },
     async ({ language, gender, provider }) => {
       const params = new URLSearchParams();
-      if (language) params.set('language', language);
       if (gender) params.set('gender', gender);
       if (provider) params.set('provider', provider);
+      const withoutLanguage = `/v1/voices${params.toString() ? '?' + params.toString() : ''}`;
 
-      const path = `/v1/voices${params.toString() ? '?' + params.toString() : ''}`;
-      const result = await client.get(path);
+      const qs = new URLSearchParams(params);
+      if (language) qs.set('language', language);
+      const result = await client.get(`/v1/voices${qs.toString() ? '?' + qs.toString() : ''}`);
 
-      const voices = result.voices || [];
+      let voices = result.voices || [];
+      // The API matches `language` EXACTLY against the voice's language name or
+      // its locale code — "hebrew" and "he-IL" both hit, but "he" / "heb" /
+      // "Hebrew (Israel)" return nothing. This arg is documented as a partial
+      // match, and an empty list reads to the model as "Kolbo has no Google
+      // Hebrew voices at all", which is how a whole provider goes missing.
+      // Retry ONCE, unfiltered, and match locally — only on the empty path, so
+      // the normal call still costs one request.
+      if (voices.length === 0 && language) {
+        const l = language.toLowerCase();
+        const all = await client.get(withoutLanguage);
+        voices = (all.voices || []).filter(v =>
+          [v.language, v.language_code, v.languageCode]
+            .some(x => String(x || '').toLowerCase().includes(l)));
+      }
       if (voices.length === 0) {
         return {
           content: [{ type: 'text', text: 'No voices found matching those filters.' }]