@kolbo/mcp 1.72.4 → 1.73.0

package/package.json

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

package/skill/SKILL.md

@@ -139,6 +139,19 @@ Passing `visual_dna_ids` is **not enough**. For every DNA in that array you MUST
 
 Resolve names with `list_visual_dnas` first. Full binding rules: `references/workflows/visual-dna.md`.
 
+## ⚠️ `enhance_prompt` — leave it OFF (HARD RULE)
+
+**Never pass `enhance_prompt: true` unless the user asked for it in words.** It is
+not a quality knob you turn on to be helpful — it sends the prompt to a rewriter
+first, so the model renders *different words than the ones the user wrote*.
+
+- The user says "make it more cinematic" → that is a request to change **your**
+  prompt. Write the better prompt yourself. It is NOT permission to enhance.
+- Only "enhance the prompt" / "improve my prompt" / "expand this prompt" is.
+- Passing it silently is the worst case: the card shows an `enhanced` chip the
+  user never asked for, and their own wording never reached the model.
+- The default is `false` in every generation tool. Leave the argument out.
+
 ## ⚠️ Seedance / Elements prompt contract (HARD RULE)
 
 `generate_elements`, Seedance 2, and Seedance 2.5 share **one** compile shape — the Locked Intro in `references/models/seedance.md`:

package/skill/references/workflows/visual-dna.md

@@ -112,6 +112,7 @@ The match is **literal and case-insensitive**, so:
 - The `@name` must equal the stored `name` field (e.g. if `name: "esther_model"` → write `@esther_model`, not `@Esther`, not `@אסתר`, not `@the model`).
 - Any-language characters are supported — if the DNA was created with `name: "אסתר"` you write `@אסתר`. Use the EXACT stored string.
 - Mentions terminate at punctuation (`.,!?`), double-spaces, another `@`, or end of string. So `@maya, wearing...` matches `maya`.
+- **Never glue a possessive onto the tag.** Write `the face of @maya stays stable`, not `@maya's face stays stable` — the tag must end at the stored name. kolbo-api does strip a trailing `'s` / `’s` before the lookup, so a possessive no longer loses the DNA, but the apostrophe is left sitting in the prompt text the model sees.
 
 This composes with `@image1` / `@image2` positional tags for plain reference/source images — see "Reference Tagging" below.
 

package/src/apps/bridge.js

@@ -103,12 +103,46 @@ const BRIDGE_JS = `
     var card = document.querySelector('.k-card');
     var rect = card ? card.getBoundingClientRect() : null;
     var height = rect ? Math.ceil(rect.bottom + 8) : document.documentElement.scrollHeight;
-    // Never ask the host for more than a viewport of inline height — a card
-    // taller than the screen overlaps Claude's prompt area.
-    height = Math.min(height, Math.max(window.innerHeight || 900, 500));
+    // Ceiling comes from the SCREEN, never window.innerHeight. Inside an iframe
+    // innerHeight IS the height the host already granted, so clamping to it made
+    // the request a feedback loop: once the host capped us, we could never ask
+    // for more than the cap, and any content past it became an inner scrollbar
+    // that no amount of growing could clear. The host clamps too, so this is
+    // only a sanity ceiling.
+    var ceiling = (window.screen && window.screen.availHeight) || 1200;
+    height = Math.min(height, Math.max(ceiling, 500));
     notify('ui/notifications/size-changed', {
       width: document.documentElement.scrollWidth, height: height
     });
+    markDraggable();
+  }
+
+  // Every image/video in a widget can be dragged straight into the host's
+  // composer. <img> is natively draggable but <video> is not, and neither sets
+  // a clean URL, so both get an explicit dragstart carrying text/uri-list —
+  // exactly the format the composer's drop handler already reads.
+  // Hooked off notifySize because that is the one thing every render path
+  // already calls, so new render sites are covered without touching them.
+  function markDraggable() {
+    var nodes = document.querySelectorAll('img[src], video[src]');
+    for (var i = 0; i < nodes.length; i++) {
+      var node = nodes[i];
+      if (node.getAttribute('data-kolbo-drag')) continue;
+      node.setAttribute('data-kolbo-drag', '1');
+      node.setAttribute('draggable', 'true');
+      node.addEventListener('dragstart', onMediaDragStart);
+    }
+  }
+
+  function onMediaDragStart(e) {
+    var node = e.currentTarget;
+    // Strip the #t=0.05 poster fragment videos carry, or the host would attach
+    // a URL the CDN answers differently.
+    var url = String(node.currentSrc || node.getAttribute('src') || '').split('#')[0];
+    if (!/^https?:/i.test(url) || !e.dataTransfer) return;
+    e.dataTransfer.setData('text/uri-list', url);
+    e.dataTransfer.setData('text/plain', url);
+    e.dataTransfer.effectAllowed = 'copy';
   }
 
   var sizeTimer = null;
@@ -149,6 +183,11 @@ const BRIDGE_JS = `
       return request('ui/message', { role: 'user', content: [{ type: 'text', text: text }] });
     },
     openLink: function (url) { return request('ui/open-link', { url: url }); },
+    // Hand a piece of this widget's media to the host's composer. Dragging it
+    // out cannot work: a widget is a sandboxed cross-origin iframe, so a native
+    // HTML5 drag started in here never delivers its dataTransfer to the host
+    // document. Hosts that ignore this method simply do nothing.
+    attachMedia: function (url) { return request('ui/attach-media', { url: url }); },
     updateModelContext: function (text) {
       return request('ui/update-model-context', { content: [{ type: 'text', text: text }] });
     },

package/src/apps/theme.js

@@ -122,6 +122,12 @@ body {
 }
 .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); }
+/* Visual DNA chips: the character's face, so you can see WHICH DNA is locked in. */
+.k-dna-face { width: 18px; height: 18px; border-radius: 999px; object-fit: cover; margin-left: -3px; background: var(--border-strong); }
+.k-dna-stack .k-dna-stack-item { display: inline-flex; }
+.k-dna-stack .k-dna-stack-item + .k-dna-stack-item .k-dna-face { margin-left: -9px; }
+.k-dna-stack .k-dna-face { box-shadow: 0 0 0 1.5px var(--card-solid); }
+.k-dna-stack { cursor: default; }
 
 /* ---- Generating state ---- */
 .k-gen-grid { display: grid; gap: 8px; }
@@ -192,6 +198,8 @@ body {
 }
 .k-media:hover .k-dl, .k-viewer:hover .k-dl, .k-skel:hover .k-dl { opacity: 1; }
 .k-dl:hover { background: var(--brand); border-color: var(--brand); }
+/* Attach-to-prompt sits immediately left of Download (30px button + 8px gap). */
+.k-attach { right: 46px; }
 .k-viewer { position: relative; }
 
 /* Keep the whole completed card under the host's iframe height cap (~800px):
@@ -199,7 +207,9 @@ body {
    or claude.ai adds an inner scrollbar. Click the image to expand in-Claude. */
 .k-viewer { margin-bottom: 10px; }
 .k-viewer img, .k-viewer video { display: block; width: 100%;
-  max-height: min(340px, 55vh); object-fit: contain;
+  /* Fixed px, no vh: vh inside an iframe is the height the host granted, so a
+     vh-based cap grew as the iframe grew and the card chased its own tail. */
+  max-height: 320px; object-fit: contain;
   border-radius: 12px; background: #000; border: 1px solid var(--border); cursor: zoom-in; }
 .k-viewer video { cursor: default; }
 

package/src/apps/widgets/generation.js

@@ -148,7 +148,19 @@ function voiceLabel(sc) { return sc.voice_name || sc.voice || (sc.settings || {}
 // real reference assets — rendering them as flat prose hid the single most
 // consequential part of the prompt. Escape FIRST, then wrap: the pattern only
 // matches after a boundary, so an email or a #fff hex never lights up.
-var MENTION_RE = /(^|[\s([{"'>])([@#][A-Za-z][\w-]*)/g;
+// DOUBLE backslashes: this whole file is a JS template literal, so a single
+// backslash-s / backslash-w is eaten before the browser ever sees it. This was
+// emitting /(^|[s([{"'>])([@#][A-Za-z][w-]*)/g — character classes of the
+// LITERAL letters s and w — so "@zohar_apocalypse" highlighted as just "@z",
+// and a mention after a space (rather than at the very start of the prompt)
+// did not highlight at all.
+// The boundary is a NEGATIVE set, not a whitelist of openers. The old
+// whitelist ([\s([{"'>]) meant any other character glued to a mention killed
+// the chip — "×@tel_aviv_invasion" rendered as flat text. Excluding word chars
+// keeps the thing that whitelist was really protecting: an email's "a@b.com"
+// has a word char before the @, so it still never lights up. (. and - are in
+// the set for the same reason: "file.name@host", "co-op@x".)
+var MENTION_RE = /(^|[^\\w@.-])([@#][A-Za-z][\\w-]*)/g;
 // #ff8800 / #fff are hex colors, and prompts are full of them. A moodboard tag
 // that happens to be 3 or 6 hex letters loses this coin flip; a grading note
 // mistaken for a moodboard is the worse read.
@@ -174,9 +186,7 @@ function renderChips(sc) {
   // Ids where we have them (title = the id, so it can be copied / reused),
   // falling back to the old count/boolean shape for payloads generated before
   // the ids were carried.
-  var dnaIds = s.visual_dna_ids || [];
-  if (dnaIds.length) h += chipT(dnaIds.length + ' Visual DNA', dnaIds.join('\\n'));
-  else if (s.visual_dna) h += chip(s.visual_dna + ' Visual DNA');
+  h += dnaChipsHTML(sc, s);
   var mbIds = s.moodboard_ids || (s.moodboard_id ? [s.moodboard_id] : []);
   if (mbIds.length) h += chipT(mbIds.length > 1 ? mbIds.length + ' moodboards' : 'moodboard', mbIds.join('\\n'));
   else if (s.moodboard) h += chip('moodboard');
@@ -193,12 +203,94 @@ function renderChips(sc) {
   }
   if (s.mode) h += chip(esc(s.mode));
   if (sc.count > 1) h += chip('×' + sc.count);
-  var refs = Array.isArray(sc.reference_images) && sc.reference_images.length
-    ? sc.reference_images : (sc.reference_image ? [sc.reference_image] : []);
+  h += referenceHTML(sc);
+  el('chips').innerHTML = h;
+}
+
+var REF_VIDEO_RE = /\\.(mp4|mov|webm|mkv|avi|m4v)(\\?|#|$)/i;
+var REF_AUDIO_RE = /\\.(mp3|wav|m4a|aac|ogg|flac)(\\?|#|$)/i;
+
+// Every reference the generation was actually given — images, videos AND audio.
+// Kind is taken from the URL rather than from which field it arrived in: callers
+// legitimately pack a video into reference_images (Elements files, v2v
+// elements), and an <img> pointed at an .mp4 renders nothing, so those
+// references were silently invisible. Extension wins, field is the fallback.
+function refKind(url, fallback) {
+  if (REF_VIDEO_RE.test(url)) return 'video';
+  if (REF_AUDIO_RE.test(url)) return 'audio';
+  return fallback;
+}
+function collectRefs(sc) {
+  var out = [];
+  var push = function (list, fallback) {
+    (Array.isArray(list) ? list : []).forEach(function (url) {
+      if (typeof url !== 'string' || !url) return;
+      if (out.some(function (r) { return r.url === url; })) return;
+      out.push({ url: url, kind: refKind(url, fallback) });
+    });
+  };
+  push(sc.reference_images && sc.reference_images.length ? sc.reference_images
+    : (sc.reference_image ? [sc.reference_image] : []), 'image');
+  push(sc.reference_videos, 'video');
+  push(sc.reference_audio, 'audio');
+  return out;
+}
+function referenceHTML(sc) {
+  var refs = collectRefs(sc);
+  var h = '';
   for (var i = 0; i < refs.length; i++) {
-    h += '<img class="k-ref-thumb" src="' + esc(refs[i]) + '" alt="" loading="lazy" title="Reference image ' + (i + 1) + ' of ' + refs.length + '" onerror="this.style.display=\\'none\\'">';
+    var url = esc(refs[i].url);
+    var title = 'Reference ' + refs[i].kind + ' ' + (i + 1) + ' of ' + refs.length;
+    if (refs[i].kind === 'video') {
+      // #t=0.1 so the poster is a real frame, not a black canvas.
+      h += '<video class="k-ref-thumb" src="' + url + '#t=0.1" muted playsinline preload="metadata" title="'
+        + title + '" onerror="this.style.display=\\'none\\'"></video>';
+    } else if (refs[i].kind === 'audio') {
+      h += '<span class="k-chip" title="' + title + '">' + ICONS.sound + ' audio ref</span>';
+    } else {
+      h += '<img class="k-ref-thumb" src="' + url + '" alt="" loading="lazy" title="' + title
+        + '" onerror="this.style.display=\\'none\\'">';
+    }
   }
-  el('chips').innerHTML = h;
+  return h;
+}
+// Which characters/looks are locked into this generation — by face and name,
+// resolved from visual_dna_ids server-side. "1 Visual DNA" told the user nothing
+// about WHICH DNA. Up to DNA_CHIP_MAX get their own named chip; beyond that they
+// collapse into one stack of overlapping faces whose tooltip lists every name,
+// so a 12-DNA scene can't push the model and aspect chips off the card.
+var DNA_CHIP_MAX = 3;
+function dnaFaceHTML(dna, cls) {
+  if (dna.thumbnail) {
+    return '<img class="' + cls + '" src="' + esc(dna.thumbnail) + '" alt="" loading="lazy" onerror="this.style.display=\\'none\\'">';
+  }
+  return '';
+}
+function dnaChipsHTML(sc, s) {
+  var dnas = Array.isArray(sc.visual_dnas) ? sc.visual_dnas : [];
+  if (!dnas.length) {
+    // Payloads from before the ids were resolved (or an offline resolve).
+    var ids = s.visual_dna_ids || [];
+    if (ids.length) return chipT(ids.length + ' Visual DNA', ids.join('\\n'));
+    if (s.visual_dna) return chip(s.visual_dna + ' Visual DNA');
+    return '';
+  }
+  var h = '';
+  if (dnas.length <= DNA_CHIP_MAX) {
+    for (var i = 0; i < dnas.length; i++) {
+      h += '<span class="k-chip" title="' + esc(dnas[i].id) + '">'
+        + dnaFaceHTML(dnas[i], 'k-dna-face') + esc(dnas[i].name) + '</span>';
+    }
+    return h;
+  }
+  var names = [];
+  var stack = '';
+  for (var j = 0; j < dnas.length; j++) {
+    names.push(dnas[j].name);
+    if (j < 4) stack += '<span class="k-dna-stack-item">' + dnaFaceHTML(dnas[j], 'k-dna-face') + '</span>';
+  }
+  return '<span class="k-chip k-dna-stack" title="' + esc(names.join('\\n')) + '">'
+    + stack + dnas.length + ' Visual DNA</span>';
 }
 function chip(inner) { return '<span class="k-chip">' + inner + '</span>'; }
 // Same chip with a hover title — used to surface the asset id behind a
@@ -618,7 +710,12 @@ function renderLinks(urls) {
 // Small hover download button attached to a media cell (per-item downloads —
 // batch grids and CD scenes have no single "current" url for the action row).
 function dlBtnHTML(u) {
-  return '<button class="k-dl" data-dl="' + esc(u) + '" title="Download" aria-label="Download">' + ICONS.download + '</button>';
+  // Attach sits beside Download on the same hover overlay. It is the reliable
+  // route into the composer — see window.kolbo.attachMedia for why dragging the
+  // media out of the iframe cannot be made to work.
+  return '<button class="k-dl k-attach" data-attach="' + esc(u) + '" title="Attach to prompt" aria-label="Attach to prompt">'
+    + ICONS.upload + '</button>'
+    + '<button class="k-dl" data-dl="' + esc(u) + '" title="Download" aria-label="Download">' + ICONS.download + '</button>';
 }
 function wireDlButtons(root) {
   Array.prototype.forEach.call((root || document).querySelectorAll('.k-dl[data-dl]'), function (b) {
@@ -627,6 +724,12 @@ function wireDlButtons(root) {
       window.kolbo.openLink(downloadUrl(b.getAttribute('data-dl')));
     };
   });
+  Array.prototype.forEach.call((root || document).querySelectorAll('.k-attach[data-attach]'), function (b) {
+    b.onclick = function (e) {
+      e.stopPropagation();
+      window.kolbo.attachMedia(b.getAttribute('data-attach'));
+    };
+  });
 }
 
 // CD scenes render as the SAME viewer+thumbnail carousel as image batches —

package/src/apps/widgets/mediaGrid.js

@@ -63,10 +63,15 @@ function boot(sc) {
 function cellHTML(item, i) {
   var idx = state.items.indexOf(item);
   var isVideo = item.media_type === 'video' && item.url;
-  var media = item.thumbnail
-    ? '<img src="' + esc(item.thumbnail) + '" loading="lazy" alt="">'
-    : '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text-faint);font-size:22px">' +
+  // onerror matters: a thumbnail that 404s / expires / can't be fetched by the
+  // host webview left a BLACK tile with no glyph and no label hint — visually
+  // identical to "corrupted media". Fall back to the same kind icon a
+  // thumbnail-less item gets, so a dead URL degrades instead of looking broken.
+  var fallbackCell = '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text-faint);font-size:22px">' +
       kindIcon(item.media_type) + '</div>';
+  var media = item.thumbnail
+    ? '<img src="' + esc(item.thumbnail) + '" loading="lazy" alt="" onerror="this.parentNode.innerHTML=this.getAttribute(\\'data-fb\\')" data-fb="' + esc(fallbackCell) + '">'
+    : fallbackCell;
   return '<div class="k-cell" data-i="' + idx + '">' +
     '<div class="k-cell-media">' + media +
     (isVideo ? '<button class="k-play k-cell-play" data-video-play="' + esc(item.url) + '">' + ICONS.play + '</button>' : '') +

package/src/tools/_shared.js

@@ -512,6 +512,48 @@ async function modelChipFields(client, model) {
   };
 }
 
+/**
+ * Resolve `visual_dna_ids` to {id, name, thumbnail} so the card can show WHICH
+ * characters are locked in, not just how many. An id tells the user nothing;
+ * the face does.
+ *
+ * One list fetch per process, cached — the DNA catalog barely moves within a
+ * session, and a generation card must never add a round-trip per chip. A miss
+ * (id not in the caller's own DNAs) degrades to the bare id, which is exactly
+ * what the card showed before.
+ */
+const _dnaChipCache = new Map();
+let _dnaChipLoaded = 0;
+const DNA_CHIP_TTL = 5 * 60 * 1000;
+
+async function resolveVisualDnas(client, ids) {
+  const list = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id) : [];
+  if (!list.length) return [];
+
+  const stale = Date.now() - _dnaChipLoaded > DNA_CHIP_TTL;
+  if (stale || list.some((id) => !_dnaChipCache.has(id))) {
+    try {
+      const res = await client.get('/v1/visual-dna?scope=mine');
+      const rows = res?.visual_dnas || res?.data || [];
+      for (const row of rows) {
+        const id = row?.id || row?._id;
+        if (!id) continue;
+        _dnaChipCache.set(String(id), {
+          id: String(id),
+          name: row.name || String(id),
+          // Same hero-image rule as the app: reference sheet, then thumbnail.
+          thumbnail: row.sheet_url || row.thumbnail_url || (Array.isArray(row.images) ? row.images[0] : null) || null,
+        });
+      }
+      _dnaChipLoaded = Date.now();
+    } catch {
+      // Offline / rate-limited — fall through to bare ids.
+    }
+  }
+
+  return list.map((id) => _dnaChipCache.get(id) || { id, name: id, thumbnail: null });
+}
+
 /**
  * Build the "submitted — widget is live" tool result for a UI host.
  * @param {object} p
@@ -543,6 +585,7 @@ async function uiGenerating(p) {
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},
+    visual_dnas: await resolveVisualDnas(p.client, (p.settings || {}).visual_dna_ids),
     // `reference_image` is retained for older widget builds. New widgets render
     // every browser-loadable image supplied to the generation.
     reference_images: Array.isArray(p.reference_images)
@@ -573,10 +616,20 @@ async function uiGenerating(p) {
 }
 
 /**
- * Wrap an already-completed generation result with the widget (used by tools
- * that stay blocking even on UI hosts, e.g. creative director).
+ * Wrap an already-completed generation result with the widget.
+ *
+ * Used by tools that stay blocking even on UI hosts (creative director), AND —
+ * since structuredContent costs a text host nothing — by every generation tool
+ * on its normal blocking return. That second case is why model names, model
+ * avatars and Visual DNA chips were missing in Kolbo Code: it does not advertise
+ * MCP Apps, so `ui()` is false, `uiGenerating` never runs, and the host had to
+ * rebuild the card from raw text that carries only a model IDENTIFIER. Shipping
+ * the resolved payload here fixes every non-Apps host at once, exactly the way
+ * the list tools already do it (see listResult).
+ *
+ * The TEXT is unchanged, so text-only hosts see precisely what they saw before.
  */
-async function uiCompleted(p, textPayload) {
+async function uiCompleted(p, textPayload, extraContent) {
   const chip = await modelChipFields(p.client, p.model);
   const structured = {
     phase: 'completed',
@@ -587,6 +640,7 @@ async function uiCompleted(p, textPayload) {
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},
+    visual_dnas: await resolveVisualDnas(p.client, (p.settings || {}).visual_dna_ids),
     reference_images: Array.isArray(p.reference_images)
       ? p.reference_images.filter(Boolean)
       : (p.reference_image ? [p.reference_image] : []),
@@ -599,7 +653,11 @@ async function uiCompleted(p, textPayload) {
     credits_used: p.credits_used,
     open_url: buildOpenUrl(p.tool, p.gen),
   };
-  return uiResult(UI.generation, textPayload, structured);
+  const out = uiResult(UI.generation, textPayload, structured);
+  if (Array.isArray(extraContent) && extraContent.length) {
+    out.content = [...out.content, ...extraContent];
+  }
+  return out;
 }
 
 // ─── Text-payload budget ─────────────────────────────────────────────────────

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, appsEnabled } = require('./_shared');
+const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, sessionIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
@@ -224,19 +224,20 @@ function registerGenerateTools(server, client, options = {}) {
       const result = poll.result;
 
       const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            model: result.result.model,
-            prompt_used: result.result.prompt_used,
-            _followup_hint: 'If the user asks to edit/change/modify this image next (scene, lighting, objects, style, color — any content edit), pass urls[0] to generate_image_edit. Use edit_image ONLY for mechanical ops (upscale/reframe/removebg/enhance_skin). Do NOT call generate_image again.'
-          }, null, 2)
-        }, ...images]
-      };
+      return uiCompleted({
+        tool: 'generate_image', kind: 'image', gen, client, model, prompt,
+        count: num_images, settings: imageSettings(shared),
+        reference_images,
+        urls: result.result.urls,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        model: result.result.model,
+        prompt_used: result.result.prompt_used,
+        _followup_hint: 'If the user asks to edit/change/modify this image next (scene, lighting, objects, style, color — any content edit), pass urls[0] to generate_image_edit. Use edit_image ONLY for mechanical ops (upscale/reframe/removebg/enhance_skin). Do NOT call generate_image again.'
+      }, null, 2), images);
     }
   );
 
@@ -311,19 +312,20 @@ function registerGenerateTools(server, client, options = {}) {
       const result = poll.result;
 
       const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            model: result.result.model,
-            prompt_used: result.result.prompt_used,
-            _followup_hint: 'If the user asks for another edit on this output, pass urls[0] back into generate_image_edit as source_images. For targeted ops (upscale/reframe/removebg/enhance_skin) use edit_image instead. Do NOT call generate_image from scratch.'
-          }, null, 2)
-        }, ...images]
-      };
+      return uiCompleted({
+        tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
+        count: num_images, settings: imageSettings(shared),
+        reference_images: source_images,
+        urls: result.result.urls,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        model: result.result.model,
+        prompt_used: result.result.prompt_used,
+        _followup_hint: 'If the user asks for another edit on this output, pass urls[0] back into generate_image_edit as source_images. For targeted ops (upscale/reframe/removebg/enhance_skin) use edit_image instead. Do NOT call generate_image from scratch.'
+      }, null, 2), images);
     }
   );
 
@@ -538,21 +540,24 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            model: result.result.model,
-            duration: result.result.duration,
-            thumbnail_url: result.result.thumbnail_url,
-            prompt_used: result.result.prompt_used,
-            _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video (upscale/reframe/face_swap/extend/generate_audio/lipsync/magic_edit) or generate_video_from_video (restyle). Do NOT call generate_video from scratch.'
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_video', kind: 'video', gen, client, model, prompt,
+        settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, preset_id }),
+        reference_images,
+        urls: result.result.urls,
+        thumbnail_url: result.result.thumbnail_url,
+        duration: result.result.duration,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        model: result.result.model,
+        duration: result.result.duration,
+        thumbnail_url: result.result.thumbnail_url,
+        prompt_used: result.result.prompt_used,
+        _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video (upscale/reframe/face_swap/extend/generate_audio/lipsync/magic_edit) or generate_video_from_video (restyle). Do NOT call generate_video from scratch.'
+      }, null, 2));
     }
   );
 
@@ -621,20 +626,23 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            model: result.result.model,
-            duration: result.result.duration,
-            thumbnail_url: result.result.thumbnail_url,
-            _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video or generate_video_from_video. Do NOT re-run generate_video_from_image unless they want a fresh animation from a different source image. Animating more shots of THIS same sequence? Pass the session_id above back on each of those calls so they all land in one session.'
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_video_from_image', kind: 'video', gen, client, model, prompt,
+        settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, visual_dna_ids }),
+        reference_images: [image_url],
+        urls: result.result.urls,
+        thumbnail_url: result.result.thumbnail_url,
+        duration: result.result.duration,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        model: result.result.model,
+        duration: result.result.duration,
+        thumbnail_url: result.result.thumbnail_url,
+        _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video or generate_video_from_video. Do NOT re-run generate_video_from_image unless they want a fresh animation from a different source image. Animating more shots of THIS same sequence? Pass the session_id above back on each of those calls so they all land in one session.'
+      }, null, 2));
     }
   );
 
@@ -686,19 +694,21 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            title: result.result.title,
-            duration: result.result.duration,
-            lyrics: result.result.lyrics
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_music', kind: 'audio', gen, client, model: model || 'Suno', prompt,
+        settings: { mode: instrumental ? 'instrumental' : (style || undefined) },
+        urls: result.result.urls,
+        title: result.result.title,
+        duration: result.result.duration,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        title: result.result.title,
+        duration: result.result.duration,
+        lyrics: result.result.lyrics
+      }, null, 2));
     }
   );
 
@@ -788,19 +798,26 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            voice: result.result.voice,
-            duration: result.result.duration,
-            ...(unknownVoice ? { _warning: unknownVoice } : {})
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_speech', kind: 'audio', gen, client, model, prompt: text,
+        voice: voiceRecord,
+        settings: {
+          voice: voice || 'Rachel',
+          style: selected_style || emotion || style_instructions_preset_id || style_instructions,
+          speaking_speed,
+          language,
+        },
+        urls: result.result.urls,
+        duration: result.result.duration,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        voice: result.result.voice,
+        duration: result.result.duration,
+        ...(unknownVoice ? { _warning: unknownVoice } : {})
+      }, null, 2));
     }
   );
 
@@ -851,17 +868,19 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result.urls,
-            duration: result.result.duration
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_sound', kind: 'audio', gen, client, model, prompt,
+        settings: { duration },
+        reference_images: seed_reference_image_url ? [seed_reference_image_url] : [],
+        urls: result.result.urls,
+        duration: result.result.duration,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        duration: result.result.duration
+      }, null, 2));
     }
   );
 
@@ -1109,7 +1128,12 @@ function registerGenerateTools(server, client, options = {}) {
           ...(reference_images || []),
           ...(keyframes || []).map((keyframe) => keyframe.image_url),
           ...(files || []).filter((source) => /^https?:\/\//i.test(source))
-        ]
+        ],
+        // Elements is the one tool that takes all three modalities. The widget
+        // sorts kind by extension, so a video that arrived via `files` is still
+        // rendered as a video — these two just make sure nothing is dropped.
+        reference_videos: reference_videos || [],
+        reference_audio: [...(reference_audio_urls || []), ...(audio_url ? [audio_url] : [])]
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1119,19 +1143,33 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: startResponse.session_id,
-            urls: result.result?.urls || [],
-            thumbnail_url: result.result?.thumbnail_url || null,
-            duration: result.result?.duration || null,
-            model: result.result?.model || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_elements', kind: 'video', gen: startResponse, client, model, prompt,
+        settings: videoSettings({
+          duration,
+          reported_duration: result.result?.duration,
+          shots: multi_shot_count ?? (Array.isArray(multi_shots) ? multi_shots.length : undefined),
+          resolution, aspect_ratio, enhance_prompt, visual_dna_ids, preset_id,
+        }),
+        reference_images: [
+          ...(reference_images || []),
+          ...(keyframes || []).map((keyframe) => keyframe.image_url),
+          ...(files || []).filter((source) => /^https?:\/\//i.test(source))
+        ],
+        reference_videos: reference_videos || [],
+        reference_audio: [...(reference_audio_urls || []), ...(audio_url ? [audio_url] : [])],
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: startResponse.session_id,
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        model: result.result?.model || null
+      }, null, 2));
     }
   );
 
@@ -1204,19 +1242,23 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: startResponse.session_id,
-            urls: result.result?.urls || [],
-            thumbnail_url: result.result?.thumbnail_url || null,
-            duration: result.result?.duration || null,
-            model: result.result?.model || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_first_last_frame', kind: 'video', gen: startResponse, client, model, prompt,
+        settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, visual_dna_ids }),
+        reference_images: [first_frame_url || first_frame, last_frame_url || last_frame]
+          .filter((source) => /^https?:\/\//i.test(source || '')),
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: startResponse.session_id,
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        model: result.result?.model || null
+      }, null, 2));
     }
   );
 
@@ -1319,19 +1361,23 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: startResponse.session_id,
-            urls: result.result?.urls || [],
-            thumbnail_url: result.result?.thumbnail_url || null,
-            duration: result.result?.duration || null,
-            model: result.result?.model || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_lipsync', kind: 'video', gen: startResponse, client, model,
+        prompt: text_prompt, settings: { mode: 'lipsync' },
+        reference_images: sourceIsUrl && !/\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? [source] : [],
+        reference_videos: sourceIsUrl && /\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? [source] : [],
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: startResponse.session_id,
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        model: result.result?.model || null
+      }, null, 2));
     }
   );
 
@@ -1414,7 +1460,13 @@ function registerGenerateTools(server, client, options = {}) {
         tool: 'generate_video_from_video', kind: 'video', gen: startResponse, client, model,
         prompt: prompt || (preset ? `Subtitles preset: ${preset}` : undefined),
         settings: videoSettings({ duration, resolution, aspect_ratio, mode: preset ? 'subtitles' : 'restyle', enhance_prompt, visual_dna_ids }),
-        reference_images: [...(reference_images || []), ...(elements || [])]
+        reference_images: [...(reference_images || []), ...(elements || [])],
+        // The source clip IS the primary reference for a restyle — showing the
+        // extra references while hiding the video being transformed was backwards.
+        reference_videos: [
+          ...(isUrl ? [source_video] : []),
+          ...(reference_videos || [])
+        ]
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1424,19 +1476,27 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: startResponse.session_id,
-            urls: result.result?.urls || [],
-            thumbnail_url: result.result?.thumbnail_url || null,
-            duration: result.result?.duration || null,
-            model: result.result?.model || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_video_from_video', kind: 'video', gen: startResponse, client, model,
+        prompt: prompt || (preset ? `Subtitles preset: ${preset}` : undefined),
+        settings: videoSettings({ duration, resolution, aspect_ratio, mode: preset ? 'subtitles' : 'restyle', enhance_prompt, visual_dna_ids }),
+        reference_images: [...(reference_images || []), ...(elements || [])],
+        reference_videos: [
+          ...(isUrl ? [source_video] : []),
+          ...(reference_videos || [])
+        ],
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: startResponse.session_id,
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        duration: result.result?.duration || null,
+        model: result.result?.model || null
+      }, null, 2));
     }
   );
 
@@ -1567,18 +1627,20 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            urls: result.result?.urls || [],
-            thumbnail_url: result.result?.thumbnail_url || null,
-            mode: result.result?.mode || null,
-            prompt_used: result.result?.prompt_used || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'generate_3d', kind: '3d', gen: startResponse, client, model, prompt,
+        settings: { mode: mode || (reference_images?.length > 1 ? 'multi' : reference_images?.length === 1 ? 'single' : 'text') },
+        reference_images,
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        urls: result.result?.urls || [],
+        thumbnail_url: result.result?.thumbnail_url || null,
+        mode: result.result?.mode || null,
+        prompt_used: result.result?.prompt_used || null
+      }, null, 2));
     }
   );
   // ─── edit_image ────────────────────────────────────────────
@@ -1713,18 +1775,20 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result?.urls || [],
-            edit_type: result.result?.edit_type || null,
-            model: result.result?.model || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'edit_image', kind: 'image', gen, client, model,
+        prompt: prompt || operation,
+        settings: { mode: operation, aspect_ratio, scale, resolution },
+        reference_images: [image_url, mask_image_url, ...(additional_images || [])].filter(Boolean),
+        urls: result.result?.urls || [],
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result?.urls || [],
+        edit_type: result.result?.edit_type || null,
+        model: result.result?.model || null
+      }, null, 2));
     }
   );
 
@@ -1878,20 +1942,23 @@ function registerGenerateTools(server, client, options = {}) {
       if (poll.timedOut) return poll.timedOut;
       const result = poll.result;
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...creditFields(result),
-            session_id: gen.session_id,
-            urls: result.result?.urls || [],
-            download_url: result.result?.download_url || null,
-            edit_type: result.result?.edit_type || null,
-            duration: result.result?.duration || null,
-            model: result.result?.model || null
-          }, null, 2)
-        }]
-      };
+      return uiCompleted({
+        tool: 'edit_video', kind: 'video', gen, client, model,
+        prompt: prompt || operation,
+        settings: { mode: operation, duration, aspect_ratio, resolution },
+        reference_images: image_url ? [image_url] : [],
+        urls: result.result?.urls || [],
+        duration: result.result?.duration || null,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result?.urls || [],
+        download_url: result.result?.download_url || null,
+        edit_type: result.result?.edit_type || null,
+        duration: result.result?.duration || null,
+        model: result.result?.model || null
+      }, null, 2));
     }
   );
 

package/src/tools/media.js

@@ -291,13 +291,6 @@ function registerMediaTools(server, client, options = {}) {
         total: totalItems != null ? totalItems : media.length,
         shown: Math.min(media.length, GRID_CAP)
       });
-
-      return {
-        content: [{
-          type: 'text',
-          text
-        }]
-      };
     }
   );