@kolbo/mcp 1.81.4 → 1.81.6

package/README.md

@@ -58,12 +58,12 @@ Or add the config by hand — this block is identical for every MCP client and c
 
 Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
 
-### Browser-only (claude.ai / ChatGPT / Codex): connector + zip
+### Browser-only (claude.ai / ChatGPT / Codex): connector + skill
 
 1. Add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow.
-2. Download **[`kolbo.zip`](https://github.com/Zoharvan12/kolbo-skills/raw/main/kolbo.zip)** and upload it as a skill (Claude.ai: Settings → Features → Skills; ChatGPT/Codex: Settings → Skills). Codex CLI: unzip into `~/.codex/skills/`.
+2. [Download the Skill](https://kolbo.ai/skills/kolbo.zip) and upload it (Claude.ai: Settings → Features → Skills; ChatGPT/Codex: Settings → Skills). Codex CLI: unzip into `~/.codex/skills/`.
 
-The zip is the canonical routing skill. Without it the tools still work, but the model will not load Seedance / Visual DNA / filmmaking rules.
+The Skill is the canonical routing layer. Without it the tools still work, but the model will not load Seedance / Visual DNA / filmmaking rules.
 
 ### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.81.4",
+  "version": "1.81.6",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/apps/bridge.js

@@ -22,6 +22,7 @@
  *   .onThemeChange(fn)         — fn(hostContext) on host-context-changed
  *   .callTool(name, args)      — Promise<CallToolResult>
  *   .sendMessage(text)         — append a user chat message (returns Promise)
+ *   .insertText(text)          — paste into the host composer, do not send
  *   .openLink(url)             — open external URL
  *   .copyText(text)            — copy via the host clipboard (ui/copy-text)
  *   .notifySize()              — report content size to host
@@ -183,6 +184,9 @@ const BRIDGE_JS = `
     sendMessage: function (text) {
       return request('ui/message', { role: 'user', content: [{ type: 'text', text: text }] });
     },
+    insertText: function (text) {
+      return request('ui/insert-text', { text: text });
+    },
     openLink: function (url) { return request('ui/open-link', { url: url }); },
     copyText: function (text) { return request('ui/copy-text', { text: text }); },
     // Hand a piece of this widget's media to the host's composer. Dragging it

package/src/apps/html.js

@@ -136,7 +136,8 @@ function modelChipHTML(name, iconUrl) {
   return '<span class="k-chip brand">' + inner + esc(name) + '</span>';
 }
 function monogram(name) {
-  return '<span class="k-mono-icon">' + esc(String(name).trim().charAt(0).toUpperCase()) + '</span>';
+  var ch = String(name || '').replace(/^[@#]+/, '').trim().charAt(0) || '?';
+  return '<span class="k-mono-icon">' + esc(ch.toUpperCase()) + '</span>';
 }
 // In-widget preview overlay — every card (generation chips, media grid, list
 // rows) uses this so a DNA / reference / library thumb opens a popup in Kolbo

package/src/apps/index.js

@@ -630,6 +630,7 @@ const TOOL_WIDGETS = {
   list_docs: UI.list,
   list_media_folders: UI.list,
   list_visual_dna_folders: UI.list,
+  list_project_assets: UI.list,
 };
 
 function attachToolWidgetMeta(server) {

package/src/apps/theme.js

@@ -340,7 +340,8 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
   background: var(--brand-soft); }
 .k-audio-meta { flex: 1; min-width: 0; }
 .k-audio-title { font-size: 12.5px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.k-audio-sub { font-size: 11px; color: var(--text-faint); }
+.k-audio-sub { font-size: 11px; color: var(--text-faint);
+  display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
 .k-generated-audio {
   display: grid; grid-template-columns: 40px minmax(0, 1fr) auto;
   align-items: center; gap: 7px 10px;

package/src/apps/widgets/catalog.js

@@ -67,7 +67,7 @@ function boot(sc) {
   Array.prototype.forEach.call(document.querySelectorAll('[data-g]'), function (row) {
     row.onclick = function () {
       var m = state.groups[+row.getAttribute('data-g')].models[+row.getAttribute('data-m')];
-      window.kolbo.sendMessage(m.use_hint || ('Generate something with the "' + m.name + '" model — ask me what I want to make.'));
+      window.kolbo.insertText(m.identifier || m.name || '');
     };
   });
   window.kolbo.notifySize();

package/src/apps/widgets/generation.js

@@ -75,6 +75,34 @@ var TOOL_TITLES = {
   generate_creative_director: 'Creative Director', edit_image: 'Image Edit', edit_video: 'Video Edit',
   get_generation_status: 'Generations'
 };
+var OPEN_ROUTES = {
+  generate_image: { path: '/image-tools', tool: 'text-to-image' },
+  generate_image_edit: { path: '/image-tools', tool: 'image-editing' },
+  edit_image: { path: '/image-tools', tool: 'image-editing' },
+  generate_video: { path: '/video-tools', tool: 'text-to-video' },
+  generate_video_from_image: { path: '/video-tools', tool: 'image-to-video' },
+  generate_elements: { path: '/video-tools', tool: 'image-to-video', mode: 'elements' },
+  generate_first_last_frame: { path: '/video-tools', tool: 'image-to-video', mode: 'first-last' },
+  generate_video_from_video: { path: '/video-tools', tool: 'video-to-video' },
+  generate_lipsync: { path: '/video-tools', tool: 'lipsync' },
+  generate_music: { path: '/audio-tools', tool: 'music-generator' },
+  generate_speech: { path: '/audio-tools', tool: 'text-to-speech' },
+  generate_sound: { path: '/audio-tools', tool: 'text-to-sound' },
+  transcribe_audio: { path: '/audio-tools', tool: 'speech-to-text' },
+  generate_creative_director: { path: '/creative-director' }
+};
+function kolboUrl(sc) {
+  if (sc && typeof sc.open_url === 'string' && sc.open_url) return sc.open_url;
+  var sid = sc && (sc.session_id || sc.sessionId);
+  var route = OPEN_ROUTES[(sc && sc.tool) || originTool];
+  if (!route || !sid) return 'https://app.kolbo.ai';
+  var url = 'https://app.kolbo.ai' + route.path + '?session=' + encodeURIComponent(sid);
+  if (route.tool) url += '&tool=' + route.tool;
+  if (route.mode) url += '&mode=' + route.mode;
+  var pid = sc && (sc.project_id || sc.projectId);
+  if (pid) url += '&project=' + encodeURIComponent(pid);
+  return url;
+}
 
 // Long text is clamped by CSS (.k-prompt 2 lines / .k-caption 1 line). Expand
 // lives on a separate button so the text itself stays selectable.
@@ -488,20 +516,20 @@ function stopNow(sc, spec) {
         var refund = 0;
         sts.forEach(function (s) { if (s.credits_refunded) refund += s.credits_refunded; });
         return {
-          cancelled: sts.some(function (s) { return s.cancelled !== false; }),
+          cancelled: sts.some(function (s) { return s.cancelled === true; }),
           credits_refunded: refund || undefined
         };
       })
     : window.kolbo.callTool(spec.tool, spec.args).then(function (r) { return structured(r) || {}; });
-  call.then(function (st) {
-    if (st.cancelled === false) {
-      // Already terminal — let the normal poll path report the real outcome
-      // instead of claiming a cancel that did not happen.
-      cancelRequested = false;
-      renderStopButton(sc);
-      return schedulePoll(sc);
-    }
-    renderCancelled(st.credits_refunded);
+    call.then(function (st) {
+      if (!st || st.cancelled !== true) {
+        // Empty host ack used to land here as {} and the card painted
+        // cancelled while the job kept running. Only an explicit cancel counts.
+        cancelRequested = false;
+        renderStopButton(sc);
+        return schedulePoll(sc);
+      }
+      renderCancelled(st.credits_refunded);
   }).catch(function () {
     cancelRequested = false;
     renderStopButton(sc);
@@ -608,7 +636,12 @@ function poll(sc) {
       var done = Object.assign({}, sc, r, {
         phase: 'completed',
         urls: r.urls || st.urls || [],
-        credits_used: st.credits_used != null ? st.credits_used : sc.credits_used
+        credits_used: st.credits_used != null ? st.credits_used : sc.credits_used,
+        // Status structuredContent used to set open_url:undefined and wipe the
+        // session deep-link the generating card already had.
+        open_url: (sc && sc.open_url) || r.open_url,
+        session_id: (sc && (sc.session_id || sc.sessionId)) || r.session_id || st.session_id,
+        project_id: (sc && (sc.project_id || sc.projectId)) || r.project_id || st.project_id
       });
       state = done;
       el('credits').textContent = done.credits_used != null ? fmtCredits(done.credits_used) : '';
@@ -652,6 +685,11 @@ function handleBatchStatus(sc, st) {
   if (!st.all_done) return schedulePoll(sc);
 
   var scenes = [], failedCount = 0, credits = 0, haveCredits = false, allUrls = [];
+  // get_generation_status resolves model_name/model_icon into EACH result
+  // (addDisplayNames in generate.js) — sc is only the submit-time guess
+  // (usually "Smart Select"). Every id in one batch ran the same model, so the
+  // first resolved one is enough to replace the guess on the finished card.
+  var resolved = {};
   gens.forEach(function (g, i) {
     var r = g.result || g;
     var urls = (r && r.urls) || [];
@@ -659,6 +697,16 @@ function handleBatchStatus(sc, st) {
     allUrls = allUrls.concat(urls);
     var c = g.credits_used != null ? g.credits_used : (r.credits_used != null ? r.credits_used : null);
     if (c != null) { credits += c; haveCredits = true; }
+    if (!resolved.model_name && r.model_name) {
+      resolved.model = r.model;
+      resolved.model_name = r.model_name;
+      resolved.model_icon = r.model_icon;
+    }
+    // Same for the references actually used (reference_details from the
+    // server) — every id in the batch shares one reference set.
+    if (!resolved.reference_images && r.reference_images && r.reference_images.length) {
+      resolved.reference_images = r.reference_images;
+    }
     scenes.push({
       scene_number: i + 1,
       title: (sc.prompts && sc.prompts[i]) || '',
@@ -668,7 +716,7 @@ function handleBatchStatus(sc, st) {
   });
   if (!scenes.length) return renderError('All ' + gens.length + ' generations failed');
 
-  var done = Object.assign({}, sc, {
+  var done = Object.assign({}, sc, resolved, {
     phase: 'completed', kind: 'scenes', batch: true, scenes: scenes, urls: [],
     credits_used: haveCredits ? credits : sc.credits_used
   });
@@ -902,10 +950,14 @@ function renderBatchGrid(sc) {
         dlBtnHTML(it.url) + '</div>';
     }).join('') + '</div>';
   wireDlButtons(el('stage'));
+  // In-widget popup, not the host round-trip focusMedia() uses — a batch grid
+  // tile has no visible full-size image otherwise, so a host that never resolves
+  // requestDisplayMode() (or drops window.open after the async round trip eats
+  // the click's user-activation window) leaves the click doing nothing at all.
   Array.prototype.forEach.call(el('stage').querySelectorAll('[data-focus]'), function (cell) {
     var it = items[+cell.getAttribute('data-focus')];
     if (it.type !== 'image') return; // <video controls> owns its own clicks
-    cell.onclick = function () { focusMedia(it.url); };
+    cell.onclick = function () { openPeek(it.url, 'image', it.label); };
   });
   renderActions(sc);
   window.kolbo.notifySize();
@@ -949,7 +1001,7 @@ function renderStatusGrid(sc) {
   Array.prototype.forEach.call(el('stage').querySelectorAll('[data-focus]'), function (cell) {
     var it = items[+cell.getAttribute('data-focus')];
     if (it.kind !== 'image') return; // <video controls> owns its own clicks
-    cell.onclick = function () { focusMedia(it.url); };
+    cell.onclick = function () { openPeek(it.url, 'image', it.title); };
   });
   renderActions(sc);
   window.kolbo.notifySize();
@@ -1030,7 +1082,7 @@ function renderTrackingIssue(msg) {
       (state && state.generation_id ? '\\nGeneration ID: ' + state.generation_id : ''));
   };
   el('tracking-open').onclick = function () {
-    window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai');
+    window.kolbo.openLink(kolboUrl(state));
   };
   window.kolbo.notifySize();
 }
@@ -1100,7 +1152,7 @@ function renderActions(sc) {
   el('actions').innerHTML = a.join('');
 
   bind('btn-download', function () { window.kolbo.openLink(downloadUrl(currentUrl())); });
-  bind('btn-open', function () { window.kolbo.openLink(state.open_url || 'https://app.kolbo.ai'); });
+  bind('btn-open', function () { window.kolbo.openLink(kolboUrl(state)); });
   bind('btn-recreate', function () {
     window.kolbo.sendMessage('Recreate this with the same settings' +
       (state.model ? '\\nModel: ' + state.model : '') +
@@ -1195,7 +1247,10 @@ function completedFromPlain(sc) {
       aspect_ratio: originArgs.aspect_ratio,
       quality: originArgs.quality
     },
-    urls: sc.urls || []
+    urls: sc.urls || [],
+    session_id: sc.session_id || originArgs.session_id,
+    project_id: sc.project_id || originArgs.project_id,
+    open_url: sc.open_url
   });
 }
 

package/src/apps/widgets/list.js

@@ -20,7 +20,7 @@ const { widgetPage } = require('../html');
  *     badge,                      // small pill, e.g. role/status ("owner", "default", "shared")
  *     meta,                       // small trailing text, e.g. a date or count
  *     open_url,                   // optional — renders an "Open" button (openLink)
- *     use_hint                    // optional — row becomes clickable, sends this on click
+ *     use_hint                    // unused — a click pastes `id` into the composer
  *   }],
  *   total
  * }
@@ -72,7 +72,7 @@ function apply(result) {
 }
 
 function itemHTML(item, i) {
-  var clickable = !!item.use_hint;
+  var clickable = !!item.id;
   var avatar = item.thumbnail
     ? '<img class="k-audio-art k-peek-hit" src="' + esc(item.thumbnail) + '" alt="" loading="lazy"'
       + peekAttrs(item.thumbnail, 'image', item.title)
@@ -98,10 +98,10 @@ function wire() {
   });
   Array.prototype.forEach.call(document.querySelectorAll('.k-audio-row'), function (row) {
     var item = state.items[+row.getAttribute('data-i')];
-    if (!item || !item.use_hint) return;
-    row.onclick = function () {
-      var msg = item.use_hint.replace('{TITLE}', item.title || '').replace('{ID}', item.id || '');
-      window.kolbo.sendMessage(msg);
+    if (!item || !item.id) return;
+    row.onclick = function (e) {
+      if (e.target && e.target.closest && e.target.closest('[data-open],[data-peek]')) return;
+      window.kolbo.insertText(String(item.id));
     };
   });
 }

package/src/apps/widgets/mediaGrid.js

@@ -14,7 +14,7 @@ const { widgetPage } = require('../html');
  *     id, title, subtitle, thumbnail, media_type: 'image'|'video'|'audio'|'3d',
  *     url,                 // full asset / playback URL
  *     preview_audio,       // audio preview URL (voices, music)
- *     use_hint             // message template sent when "Use" clicked, {URL}/{ID}/{TITLE} substituted
+ *     use_hint             // unused — Use pastes `id` into the composer
  *   }],
  *   total, has_more,
  *   import_tool_hint       // e.g. 'import via import_stock_asset' — shown on Use
@@ -154,11 +154,8 @@ function wire() {
 
 function useItem(i) {
   var item = state.items[i];
-  if (!item) return;
-  var msg = item.use_hint
-    ? item.use_hint.replace('{URL}', item.url || '').replace('{ID}', item.id || '').replace('{TITLE}', item.title || '')
-    : 'Use this asset: "' + (item.title || item.id) + '"\\nURL: ' + (item.url || '') + (item.id ? '\\nID: ' + item.id : '');
-  window.kolbo.sendMessage(msg);
+  if (!item || !item.id) return;
+  window.kolbo.insertText(String(item.id));
 }
 
 window.kolbo.onToolResult(function (result) {

package/src/tools/_shared.js

@@ -458,8 +458,8 @@ const OPEN_URL_ROUTES = {
   edit_image:                 { path: '/image-tools', tool: 'image-editing' },
   generate_video:             { path: '/video-tools', tool: 'text-to-video' },
   generate_video_from_image:  { path: '/video-tools', tool: 'image-to-video' },
-  generate_elements:          { path: '/video-tools', tool: 'image-to-video' },
-  generate_first_last_frame:  { path: '/video-tools', tool: 'image-to-video' },
+  generate_elements:          { path: '/video-tools', tool: 'image-to-video', mode: 'elements' },
+  generate_first_last_frame:  { path: '/video-tools', tool: 'image-to-video', mode: 'first-last' },
   generate_video_from_video:  { path: '/video-tools', tool: 'video-to-video' },
   generate_lipsync:           { path: '/video-tools', tool: 'lipsync' },
   generate_music:             { path: '/audio-tools', tool: 'music-generator' },
@@ -468,6 +468,35 @@ const OPEN_URL_ROUTES = {
   transcribe_audio:           { path: '/audio-tools', tool: 'speech-to-text' },
   generate_creative_director: { path: '/creative-director' },
 };
+// SDK tracking `type` on get_generation_status — same session model as the
+// generate_* tool that created the job, so "Open in Kolbo" still deep-links
+// after a status poll overwrites the live card.
+const TYPE_TO_TOOL = {
+  image: 'generate_image',
+  image_edit: 'generate_image_edit',
+  global_image_edit: 'edit_image',
+  video: 'generate_video',
+  video_from_image: 'generate_video_from_image',
+  elements: 'generate_elements',
+  first_last_frame: 'generate_first_last_frame',
+  video_from_video: 'generate_video_from_video',
+  lipsync: 'generate_lipsync',
+  music: 'generate_music',
+  speech: 'generate_speech',
+  sound: 'generate_sound',
+  transcription: 'transcribe_audio',
+  creative_director: 'generate_creative_director',
+};
+
+function sessionOf(gen) {
+  if (!gen || typeof gen !== 'object') return undefined;
+  return gen.session_id || gen.sessionId || undefined;
+}
+
+function projectOf(gen) {
+  if (!gen || typeof gen !== 'object') return undefined;
+  return gen.project_id || gen.projectId || undefined;
+}
 
 /**
  * Build the "Open in Kolbo" deep link for a generation's actual session.
@@ -476,14 +505,30 @@ const OPEN_URL_ROUTES = {
  * kolbo-api, shorts render, 3D).
  */
 function buildOpenUrl(tool, gen) {
-  const route = OPEN_URL_ROUTES[tool];
-  if (!route || !gen || !gen.session_id) return undefined;
-  let url = `${APP_BASE_URL}${route.path}?session=${encodeURIComponent(gen.session_id)}`;
+  const sid = sessionOf(gen);
+  if (!sid) return undefined;
+  const key = OPEN_URL_ROUTES[tool] ? tool : (TYPE_TO_TOOL[gen && gen.type] || TYPE_TO_TOOL[tool]);
+  const route = OPEN_URL_ROUTES[key];
+  if (!route) return undefined;
+  let url = `${APP_BASE_URL}${route.path}?session=${encodeURIComponent(sid)}`;
   if (route.tool) url += `&tool=${route.tool}`;
-  if (gen.project_id) url += `&project=${encodeURIComponent(gen.project_id)}`;
+  if (route.mode) url += `&mode=${route.mode}`;
+  const pid = projectOf(gen);
+  if (pid) url += `&project=${encodeURIComponent(pid)}`;
   return url;
 }
 
+function linkFields(tool, gen) {
+  const sid = sessionOf(gen);
+  const pid = projectOf(gen);
+  const href = buildOpenUrl(tool, gen);
+  return {
+    ...(sid ? { session_id: String(sid) } : {}),
+    ...(pid ? { project_id: String(pid) } : {}),
+    ...(href ? { open_url: href } : {}),
+  };
+}
+
 /**
  * Build the "Open in Kolbo" deep link for a PROJECT. Lands on the Media hub
  * (all-assets view) pre-filtered to this project, where the user sees every
@@ -671,8 +716,11 @@ function mediaRefs(p) {
     ? p.reference_images.filter(Boolean)
     : (p.reference_image ? [p.reference_image] : []);
   return {
-    reference_images: images,
-    reference_image: p.reference_image || images[0],
+    // Omitted when empty: a live card MERGES status payloads over its own
+    // state, so a present-but-empty reference_images (the single-id status
+    // path has no input refs of its own) wiped the submit-time thumbnails
+    // off the finished card.
+    ...(images.length ? { reference_images: images, reference_image: p.reference_image || images[0] } : {}),
     ...(Array.isArray(p.reference_videos) && p.reference_videos.length
       ? { reference_videos: p.reference_videos.filter(Boolean) } : {}),
     ...(Array.isArray(p.reference_audio) && p.reference_audio.length
@@ -723,7 +771,7 @@ async function uiGenerating(p) {
     // `reference_image` is retained for older widget builds. New widgets render
     // every browser-loadable image supplied to the generation.
     ...mediaRefs(p),
-    open_url: buildOpenUrl(p.tool, p.gen),
+    ...linkFields(p.tool, p.gen),
   };
   // Batch mode (prompts[] fan-out): ONE widget tracks every id in the set.
   if (Array.isArray(p.generation_ids) && p.generation_ids.length > 1) {
@@ -741,7 +789,7 @@ async function uiGenerating(p) {
     ...(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.',
+    _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. CREDIT GUARD: END YOUR TURN now — do not keep Thinking, writing skills/files, or planning while the card spins (that burns coding credits). Do NOT poll in a loop. If you need the output URLs for a follow-up step, call get_generation_status ONCE with wait=true as the only next tool — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
     _paid_note: 'This generation is RUNNING and the user is paying for it. If you now realize the tool, model, or parameters were wrong, call cancel_generation with this generation_id FIRST, then start the replacement — never leave a wrong generation running alongside its retry (the user gets two cards and two charges).',
   }, null, 2);
   return uiResult(UI.generation, text, structured);
@@ -819,7 +867,7 @@ async function uiCompleted(p, textPayload, extraContent) {
     // resolved as completed-with-no-media and painted a red failure card.
     ...(p.state ? { state: p.state } : {}),
     credits_used: p.credits_used,
-    open_url: buildOpenUrl(p.tool, p.gen),
+    ...linkFields(p.tool, p.gen),
   };
   const out = uiResult(UI.generation, textPayload, structured);
   if (Array.isArray(extraContent) && extraContent.length) {
@@ -913,6 +961,7 @@ module.exports = {
   projectScopeReadField,
   inlineImageBlocks,
   buildOpenUrl,
+  linkFields,
   buildProjectUrl,
   uiGenerating,
   uiCompleted,

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone, waitWindowMs } = require('../polling');
-const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, sessionIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
+const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, sessionIdField, inlineImageBlocks, linkFields, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
 const { ownedUrl } = require('./owned-url');
 const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo, resolveCatalogAspectRatio } = require('../apps');
 
@@ -282,7 +282,10 @@ function registerGenerateTools(server, client, options = {}) {
       return uiCompleted({
         tool: 'generate_image', kind: 'image', gen, client, model, prompt,
         count: num_images, settings: imageSettings(shared),
-        reference_images,
+        // The status result reports what the server ACTUALLY conditioned on
+        // (reference_details: DNA stills, merged sources, auto-routing) — the
+        // input arg is only what the caller happened to name.
+        reference_images: result.result.reference_images || reference_images,
         urls: result.result.urls,
         credits_used: creditFields(result).credits_used,
       }, JSON.stringify({
@@ -371,7 +374,8 @@ function registerGenerateTools(server, client, options = {}) {
       return uiCompleted({
         tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
         count: num_images, settings: imageSettings(shared),
-        reference_images: [...(source_images || []), ...(reference_images || [])],
+        reference_images: result.result.reference_images
+          || [...(source_images || []), ...(reference_images || [])],
         urls: result.result.urls,
         credits_used: creditFields(result).credits_used,
       }, JSON.stringify({
@@ -1086,10 +1090,21 @@ function registerGenerateTools(server, client, options = {}) {
           // The model that ACTUALLY ran. A single-id check resolves one
           // generation, so 'Generations' here overwrote the real model name on
           // the finished card the moment the live widget merged this payload in.
-          model: res.model || 'Generations', gen: { generation_id: single.generation_id },
+          model: res.model || 'Generations',
+          gen: {
+            generation_id: single.generation_id,
+            session_id: single.session_id,
+            project_id: single.project_id,
+            type: single.type,
+          },
           state: single.state,
           urls: done ? urls : undefined,
           thumbnail_url: res.thumbnail_url,
+          // The refs the server actually conditioned on (reference_details) —
+          // the live card merges this payload over its submit-time state, so
+          // the finished card shows every reference, including server-side
+          // additions (DNA stills, merged sources) the tool call never named.
+          reference_images: res.reference_images,
           prompt: res.prompt_used || res.prompt || undefined,
           credits_used: creditFields(single).credits_used,
           items: [{
@@ -1130,10 +1145,27 @@ function registerGenerateTools(server, client, options = {}) {
       // moodboards.js / visual_dna.js / listResult(). uiResult always embeds
       // both text and structuredContent, so hosts without a UI-app renderer
       // are unaffected — only the fallback quality changes.
+      // A live batch card (prompts[] fan-out) merges this payload over its
+      // submit-time state, so a hardcoded 'Generations' model here painted
+      // over the real model chip on every finished batch. When all results
+      // ran the same model (the batch case), name it; only a genuinely mixed
+      // multi-id check falls back to the generic label. Same for the
+      // references actually used — one shared set per batch.
+      const modelsRan = [...new Set(results.map(r => r.result && r.result.model).filter(Boolean))];
+      const actualRefs = results
+        .map(r => r.result && r.result.reference_images)
+        .find(refs => Array.isArray(refs) && refs.length);
       return uiCompleted({
         tool: 'get_generation_status', kind: 'status', client,
-        model: 'Generations', gen: { generation_id: ids[0] },
+        model: modelsRan.length === 1 ? modelsRan[0] : 'Generations',
+        gen: {
+          generation_id: ids[0],
+          session_id: results[0] && results[0].session_id,
+          project_id: results[0] && results[0].project_id,
+          type: results[0] && results[0].type,
+        },
         settings: {},
+        reference_images: actualRefs,
         items: results.map(r => {
           const res = r.result || {};
           return {
@@ -1786,7 +1818,7 @@ function registerGenerateTools(server, client, options = {}) {
           poll_tool: 'get_generation_status',
           status_args: { generation_id: startResponse.generation_id, wait: true },
           audio_url: isUrl ? source : undefined,
-          open_url: buildOpenUrl('transcribe_audio', startResponse),
+          ...linkFields('transcribe_audio', startResponse),
         });
       }
 
@@ -2056,7 +2088,7 @@ function registerGenerateTools(server, client, options = {}) {
         'inpaint', 'retake'
       ]).describe([
         'Edit operation:',
-        '"upscale" — boost to 4K/2K resolution (use `scale` for factor, `resolution` for target, `target_fps` for frame rate).',
+        '"upscale" — boost to 4K/2K resolution (use `scale` for factor, `resolution` for target, `target_fps` for frame rate). On model "blackforestlabs/flux-video-upscale" (Flux Video Upscale): `scale` is 1.5-3x (no named `resolution` target — billed on the OUTPUT tier it lands in), `mode` is "precise" (source-faithful, default) or "creative" (reimagines detail — a pricier tier), and `prompt` optionally guides the creative-mode enhancement.',
         '"reframe" — change aspect ratio (requires `aspect_ratio`; use `grid_position_x`/`grid_position_y` to control where the original sits).',
         '"generate_audio" — add AI-generated audio from `prompt`. Optionally split into `sound_effect_prompt` and `background_music_prompt`. Set `original_sound=true` to keep original audio alongside.',
         '"remove_watermark" — AI-powered watermark removal.',
@@ -2074,9 +2106,9 @@ function registerGenerateTools(server, client, options = {}) {
 
       // ── upscale ────────────────────────────────────────────
       scale: z.number().optional()
-        .describe('Upscale factor (e.g. 2, 4). Used with operation="upscale".'),
+        .describe('Upscale factor (e.g. 2, 4). Used with operation="upscale". On "blackforestlabs/flux-video-upscale" the valid range is 1.5-3 (default 2).'),
       resolution: z.string().optional()
-        .describe('Target resolution (e.g. "4k", "2k", "1080p"). Used with "upscale" and "reframe".'),
+        .describe('Target resolution (e.g. "4k", "2k", "1080p"). Used with "upscale" and "reframe". Not used by "blackforestlabs/flux-video-upscale" — use `scale` instead.'),
       target_fps: z.number().optional()
         .describe('Target frame rate (e.g. 24, 30, 60). Used with operation="upscale".'),
       enhancement_model: z.string().optional()
@@ -2092,7 +2124,7 @@ function registerGenerateTools(server, client, options = {}) {
 
       // ── generate_audio ─────────────────────────────────────
       prompt: z.string().optional()
-        .describe('Text prompt. Required for "magic_edit". Used with "generate_audio", "extend", "inpaint", "retake", and optionally "lipsync" (for text-to-speech instead of audio_url).'),
+        .describe('Text prompt. Required for "magic_edit". Used with "generate_audio", "extend", "inpaint", "retake", optionally "lipsync" (for text-to-speech instead of audio_url), and optionally "upscale" on model "blackforestlabs/flux-video-upscale" (guides creative-mode detail enhancement).'),
       sound_effect_prompt: z.string().optional()
         .describe('Separate prompt for sound effects layer. Used with operation="generate_audio" when you want to specify SFX and music independently.'),
       background_music_prompt: z.string().optional()
@@ -2110,7 +2142,7 @@ function registerGenerateTools(server, client, options = {}) {
       duration: z.number().optional()
         .describe('Seconds of content to generate. Used with "extend" (required) and "retake" (optional). Typical range: 1–20.'),
       mode: z.string().optional()
-        .describe('Extension direction: "start" or "end". Used with "extend". For "retake": replacement mode (default: "replace_audio_and_video"). Default: "end".'),
+        .describe('Extension direction: "start" or "end". Used with "extend". For "retake": replacement mode (default: "replace_audio_and_video"). For "upscale" on model "blackforestlabs/flux-video-upscale": "precise" (source-faithful, default) or "creative" (reimagines detail — pricier). Default: "end".'),
       context: z.string().optional()
         .describe('Additional context to guide what gets generated in the extended segment. Used with "extend".'),
 

package/src/tools/projects.js

@@ -4,9 +4,15 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
-const { buildProjectUrl } = require('./_shared');
+const { buildProjectUrl, compactList } = require('./_shared');
 const { listResult } = require('../apps');
 
+function blurb(text) {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  if (s.length <= 96) return s;
+  return s.slice(0, 96).replace(/\s+\S*$/, '') + '…';
+}
+
 function registerProjectTools(server, client) {
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
@@ -465,11 +471,33 @@ function registerProjectTools(server, client) {
       const result = await client.get(`/v1/projects/${encodeURIComponent(project_id)}/assets`);
       const dnas = result.visual_dnas || [];
       const moodboards = result.moodboards || [];
-      const text = JSON.stringify({
-        visual_dnas: dnas,
-        moodboards,
-        _hint: 'Edit a DNA\'s identity description with update_project_asset (description) or update_visual_dna. The `note` is project-scoped purpose (update_project_asset note). Link missing assets with link_project_asset — do not delete+recreate.'
-      }, null, 2);
+      const text = compactList(
+        [
+          ...dnas.map((d) => ({
+            id: d.id,
+            name: d.name,
+            dna_type: d.dna_type,
+            thumbnail: d.thumbnail_url || d.thumbnail,
+            note: blurb(d.note),
+            description: blurb(d.description),
+          })),
+          ...moodboards.map((m) => ({
+            id: m.id,
+            name: m.name,
+            dna_type: 'moodboard',
+            thumbnail: m.thumbnail_url || m.thumbnail,
+            note: blurb(m.note),
+            description: blurb(m.summary),
+          })),
+        ],
+        {
+          fields: ['id', 'name', 'dna_type', 'thumbnail', 'note', 'description'],
+          cap: 80,
+          total: dnas.length + moodboards.length,
+          extra: { visual_dna_count: dnas.length, moodboard_count: moodboards.length },
+          note: 'Edit identity text with update_project_asset (description) or update_visual_dna. `note` is project-scoped purpose. Link missing assets with link_project_asset — do not delete+recreate.',
+        },
+      );
       return listResult(text, {
         widget: 'list',
         title: 'Project cast',
@@ -477,13 +505,17 @@ function registerProjectTools(server, client) {
           ...dnas.map((d) => ({
             id: d.id,
             title: '@' + (d.name || d.id),
-            subtitle: [d.dna_type, d.note || d.description].filter(Boolean).join(' · ')
+            subtitle: blurb(d.note || d.description),
+            thumbnail: d.thumbnail_url || d.thumbnail,
+            badge: d.dna_type,
           })),
           ...moodboards.map((m) => ({
             id: m.id,
             title: '#' + (m.name || m.id),
-            subtitle: ['moodboard', m.note || m.summary].filter(Boolean).join(' · ')
-          }))
+            subtitle: blurb(m.note || m.summary),
+            thumbnail: m.thumbnail_url || m.thumbnail,
+            badge: 'moodboard',
+          })),
         ],
         total: dnas.length + moodboards.length
       });