@kolbo/mcp 1.72.2 → 1.72.4

package/package.json

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

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@94bfcae, the single source of truth.
+This tree is mirrored from kolbo-code@6d0fcfe, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/references/workflows/production-log.md

@@ -16,9 +16,50 @@ Read `.kolbo/production.md` **before** acting on any of these signals:
 
 If the file is missing and the user is referencing prior media, ask the user — do not guess from chat.
 
+## ⚠️ Approval gates — the user is usually still iterating (READ THIS FIRST)
+
+Most media work is an **approval loop**, not a single shot. The user generates, looks, asks for another take, and keeps going until satisfied. This is the normal case for **images, image sets, Visual DNAs, moodboards, and videos** alike.
+
+The log records **what the user approved** — not everything you produced. Getting this wrong is expensive in both directions: log too eagerly and take 3 of 7 is enshrined as "the character"; log too late and the approved URL is gone after compaction.
+
+**The loop:**
+
+1. **Generate** candidates.
+2. **Present them so the user can actually judge.** Never ask "approve?" over bare URLs or ids — the user cannot see those. Use the widget-carrying tools:
+   - Visual DNAs → `list_visual_dnas` (renders a thumbnail media grid; `create_visual_dna` returns text only, so follow it with this)
+   - Moodboards → `list_moodboards`
+   - Images / videos / audio → show the returned URLs as markdown images/links
+   Say plainly which ones are in play, e.g. "created `@maya` and `@maya_alt` — here they are".
+3. **Ask for a decision** and name the options ("keep the first, redo the second, or both?").
+4. **Repeat** until the user is satisfied. Log nothing as approved during this stage.
+5. **On approval → update `.kolbo/production.md` immediately**, in the same turn, before your next tool call or final reply.
+
+**Never write an artifact into the log as approved without the user's approval.**
+
+**If the user genuinely doesn't care** — "whatever you think", "you pick", "don't care", or they hand you the whole job — then **you decide**. Choose, say in one line which you picked and why, and log it as usual with `(agent-selected)`. Do not stall a production waiting for an approval the user has already delegated to you.
+
+**Don't lose candidate URLs while iterating.** Recording a candidate is not the same as claiming approval, and compaction will eat unlogged URLs. Park in-flight takes under a `#### Candidates (pending approval)` bullet, and on approval promote the winner to a normal entry and mark the rest `(rejected)`:
+
+```md
+2. **Rainy street walk** — neon reflections, slow dolly
+   #### Candidates (pending approval)
+   - take 1: https://...02-rain-a.png  (flux-2-pro, 2026-08-17)
+   - take 2: https://...02-rain-b.png  (flux-2-pro, 2026-08-17)
+```
+
+after the user picks take 2:
+
+```md
+2. **Rainy street walk** — neon reflections, slow dolly
+   - still: https://...02-rain-b.png  (flux-2-pro · 1K, approved 2026-08-17)
+   - take 1: https://...02-rain-a.png  (rejected 2026-08-17)
+```
+
+**Re-confirm state after a long loop.** When a session has churned through many takes, restate the approved set before moving on — "so we're locked on: @maya, moodboard #noir, scenes 1-3" — and make the log match. An approval loop that ends without a written-down approved state is how the wrong asset ships.
+
 ## When to WRITE to it
 
-**Immediately after every successful generation tool call**, before your next tool call or your final reply. The runtime will inject a reminder after generation tool results — treat that as a hard rule, not a suggestion.
+**Immediately once an artifact is approved** (see the approval gates above), before your next tool call or your final reply. The runtime will inject a reminder after generation tool results — treat that as a hard rule, not a suggestion. Where there is no approval loop — the user asked for one thing and got it, or delegated the choice to you — approval is implicit and you log right away.
 
 Tools that REQUIRE logging:
 - `generate_image`, `generate_image_edit`, `edit_image`
@@ -52,6 +93,8 @@ Stub for first creation:
 
 **Brief:** <paraphrase of user's overall goal in 1-3 sentences>
 **Now working on:** <the immediate next step>
+**Approved:** <locked assets — DNAs, moodboards, scenes; "nothing yet" if still iterating>
+**Awaiting approval:** <what you've presented and are waiting on; omit when nothing is pending>
 **Last updated:** <ISO date>
 
 ---
@@ -107,6 +150,8 @@ When a user request supersedes a previous artifact (e.g., "redo scene 2 with mor
 4. **Do not log failures.** Only successful generations.
 5. **Resolve user references via the log, not chat history.** If the user says "scene 3," use the URL the log says is scene 3, even if a later tool_result mentioned a different URL.
 6. **One file per workspace.** Multiple concurrent productions go under separate `## Production: <name>` headings inside the same file.
+7. **Approved state is user-granted, never assumed.** A generation succeeding is not approval. Only the user's "yes" — or their explicit delegation of the choice to you — promotes a candidate to an approved entry. Silence is not approval; neither is the user moving on to another topic.
+8. **The `## 🎯 Now` block names what is locked.** Keep an `**Approved:**` line there listing the currently-approved cast, DNAs, moodboards, and scenes, so the approved state survives compaction and is the first thing you read next session.
 
 ## Bulk Generation Entry Shape
 

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

@@ -207,7 +207,7 @@ Read `max_visual_dna` from `list_models` for the exact cap, AND `supports_visual
 
 **Step 1 — Generate both images in parallel (one `generate_image` call each, fire simultaneously):**
 
-1. **4-angle character sheet** — prompt: `"[character description], character reference sheet showing front view, back view, left side view, right side view, four panels arranged in a 2x2 grid, neutral solid background, full body, photorealistic"`, aspect ratio `16:9`
+1. **4-angle character sheet** — prompt: `"[character description], character reference sheet showing front view, back view, left side view, right side view, four panels arranged in a 2x2 grid, neutral solid background, full body, photorealistic"`, aspect ratio `16:9` (or `3:2` — always landscape, see the aspect-ratio rule below)
 2. **Close-up portrait** — prompt: `"[character description], close-up portrait, face and shoulders, neutral solid background, soft studio lighting, photorealistic"`, aspect ratio `1:1`
 
 **Step 2 — Call `create_visual_dna`** with:
@@ -250,3 +250,13 @@ Tools: `list_visual_dna_folders`, `create_visual_dna_folder` (`name`, optional h
 - When the user is about to create a **character** DNA, proactively OFFER it: "want me to generate a character sheet first? It makes the character far more consistent and costs a few credits." Run it only on a yes.
 - Flow: `generate_character_sheet {image_urls}` → show the sheet → `create_visual_dna {name, images, character_sheet_url: <url>}`.
 - For non-character DNAs (style/product/environment), skip it.
+
+### ⚠️ Aspect ratio — character sheets and bibles are LANDSCAPE
+
+Default every character sheet, turnaround, and character/production **bible** sheet to **`3:2` or `16:9`** unless the user asks for something else.
+
+These are multi-panel grids laid out side by side — front, back, left, right, plus detail callouts. A square or portrait frame forces the panels to stack, which shrinks each one and costs the engine the very facial and body detail the sheet exists to capture. Landscape gives each panel usable width.
+
+- Character sheet / turnaround / bible sheet → `3:2` or `16:9`
+- Close-up portrait reference → `1:1` (a single panel, so the grid logic doesn't apply)
+- Only deviate when the user explicitly names a different ratio.

package/src/apps/index.js

@@ -447,6 +447,10 @@ const TOOL_WIDGETS = {
   generate_speech: UI.generation,
   generate_sound: UI.generation,
   generate_3d: UI.generation,
+  // Declared explicitly so Apps hosts prepare the card from tools/list rather
+  // than inferring it from the `generate_*` name; result-level _meta alone is
+  // not enough for hosts that read the declaration (see the note below).
+  generate_character_sheet: UI.generation,
   edit_image: UI.generation,
   edit_video: UI.generation,
   // transcript viewer

package/src/apps/theme.js

@@ -85,6 +85,15 @@ body {
   display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
 .k-prompt.k-clamped, .k-caption.k-clamped { cursor: pointer; }
 .k-prompt.expanded { -webkit-line-clamp: unset; }
+/* @VisualDNA / #Moodboard mentions are load-bearing prompt syntax, not prose —
+   the server resolves them to the actual asset. Mark them so a glance at the
+   prompt shows which references it pulls in. */
+.k-mention {
+  display: inline; padding: 1px 5px; border-radius: 5px;
+  background: var(--brand-soft); color: var(--brand);
+  font-family: 'JetBrains Mono', ui-monospace, monospace;
+  font-size: 0.94em; font-weight: 500;
+}
 /* Single-line media caption (scene / batch prompt under the viewer) */
 .k-caption { font-size: 11px; color: var(--text-faint); margin: 2px 2px 0;
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }

package/src/apps/widgets/generation.js

@@ -127,7 +127,7 @@ function boot(sc) {
   if (isListPayload(sc, sc.tool)) return renderList(sc);
   state = sc;
   el('tool-title').textContent = TOOL_TITLES[sc.tool] || 'Generation';
-  el('prompt').textContent = sc.prompt || '';
+  el('prompt').innerHTML = promptHTML(sc.prompt);
   el('prompt').style.display = sc.prompt ? '' : 'none';
   makeExpandable(el('prompt'));
   renderChips(sc);
@@ -144,19 +144,44 @@ function boot(sc) {
 function modelLabel(sc) { return sc.model_name || sc.model; }
 function voiceLabel(sc) { return sc.voice_name || sc.voice || (sc.settings || {}).voice; }
 
+// @VisualDNA / #Moodboard mentions are the tag syntax the server resolves into
+// 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;
+// #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.
+var HEX_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function promptHTML(text) {
+  return esc(text || '').replace(MENTION_RE, function (m, pre, tag) {
+    if (HEX_RE.test(tag)) return m;
+    return pre + '<span class="k-mention">' + tag + '</span>';
+  });
+}
+
 function renderChips(sc) {
   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));
+  if (s.duration) h += chip(ICONS.clock + ' ' + fmtDur(s.duration) + (s.shots > 1 ? ' · ' + s.shots + ' shots' : ''));
+  else if (s.shots > 1) h += chip(s.shots + ' shots');
   if (s.resolution) h += chip(esc(s.resolution));
   if (s.aspect_ratio) h += chip(esc(s.aspect_ratio));
   if (s.quality) h += chip(esc(s.quality) + ' quality');
   if (s.enhance_prompt) h += chip(ICONS.sparkle + ' enhanced');
   if (s.web_search) h += chip('web search');
-  if (s.visual_dna) h += chip(s.visual_dna + ' Visual DNA');
-  if (s.moodboard) h += chip('moodboard');
-  if (s.preset) h += chip('preset');
+  // 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');
+  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');
+  if (s.preset_id) h += chipT('preset', s.preset_id);
+  else if (s.preset) h += chip('preset');
   if (s.cinematic) h += chip('cinematic');
   if (s.audio) h += chip(ICONS.sound + ' audio');
   var voice = voiceLabel(sc);
@@ -176,6 +201,11 @@ function renderChips(sc) {
   el('chips').innerHTML = h;
 }
 function chip(inner) { return '<span class="k-chip">' + inner + '</span>'; }
+// Same chip with a hover title — used to surface the asset id behind a
+// "2 Visual DNA" / "preset" label without spending chip width on it.
+function chipT(inner, title) {
+  return '<span class="k-chip" title="' + esc(title) + '">' + inner + '</span>';
+}
 function iconFor(kind) {
   switch (kind) {
     case 'image': return ICONS.image;
@@ -841,8 +871,8 @@ function bootPre(toolName, args) {
   }
   el('tool-title').textContent = TOOL_TITLES[toolName] || 'Generation';
   if (args && (args.prompt || args.text || (Array.isArray(args.prompts) && args.prompts.length))) {
-    el('prompt').textContent = args.prompt || args.text ||
-      (args.prompts.length + ' prompts — ' + args.prompts.join(' · '));
+    el('prompt').innerHTML = promptHTML(args.prompt || args.text ||
+      (args.prompts.length + ' prompts — ' + args.prompts.join(' · ')));
     el('prompt').style.display = '';
     makeExpandable(el('prompt'));
   }

package/src/tools/generate.js

@@ -101,16 +101,41 @@ async function pollBatch(client, batch, { interval, timeout }) {
 // only values that were really supplied ever surface. This used to be
 // `{ resolution, aspect_ratio }` only — `quality` (and every knob below it) was
 // silently dropped, so three calls at low/medium/high rendered identical cards.
+// `visual_dna`/`moodboard`/`preset` used to collapse to a count and two
+// booleans, which told nobody WHICH asset was applied — not the user reading
+// the card, and not the agent reading the tool result, so a follow-up call
+// could not reuse the same DNA or preset without re-listing. Carry the ids.
+const refSettings = (a = {}) => ({
+  enhance_prompt: a.enhance_prompt || undefined,
+  web_search: a.enable_web_search || undefined,
+  visual_dna_ids: (a.visual_dna_ids && a.visual_dna_ids.length) ? a.visual_dna_ids : undefined,
+  moodboard_id: a.moodboard_id || undefined,
+  moodboard_ids: (a.moodboard_ids && a.moodboard_ids.length) ? a.moodboard_ids : undefined,
+  preset_id: a.preset_id || undefined,
+  cinematic: a.cinematic ? true : undefined,
+});
+
 const imageSettings = (a = {}) => ({
   resolution: a.resolution,
   aspect_ratio: a.aspect_ratio,
   quality: a.quality,
-  enhance_prompt: a.enhance_prompt || undefined,
-  web_search: a.enable_web_search || undefined,
-  visual_dna: (a.visual_dna_ids && a.visual_dna_ids.length) || undefined,
-  moodboard: a.moodboard_id ? true : undefined,
-  preset: a.preset_id ? true : undefined,
-  cinematic: a.cinematic ? true : undefined,
+  ...refSettings(a),
+});
+
+// Same block for the video tools, which carried only { duration, resolution,
+// aspect_ratio } — a DNA-anchored video card showed no sign a DNA was in play.
+const videoSettings = (a = {}) => ({
+  // Multi-shot elements calls usually set shot COUNT and let the model take the
+  // default per-shot length, so `duration` came through undefined and the card
+  // showed model/resolution/ratio but never how long the video actually is —
+  // the one number the user picked and is paying for. Fall back to what the API
+  // echoed back on start, then to per-shot × shots.
+  duration: a.duration ?? a.reported_duration ?? (a.shot_duration && a.shots ? a.shot_duration * a.shots : undefined),
+  ...(a.shots > 1 ? { shots: a.shots } : {}),
+  resolution: a.resolution,
+  aspect_ratio: a.aspect_ratio,
+  ...(a.mode ? { mode: a.mode } : {}),
+  ...refSettings(a),
 });
 
 const promptsField = (what) => z.array(z.string()).max(MAX_BATCH_PROMPTS).optional().describe(
@@ -220,9 +245,11 @@ function registerGenerateTools(server, client, options = {}) {
     'generate_image_edit',
     'THE tool for ANY prompt-driven / content edit of an existing image — changing the scene ("make it night", "change the sky to sunset"), adding/removing/replacing objects, restyling, recoloring, compositing, or any "edit this image to…" request. This is the image-editing equivalent of generate_image and runs on strong dedicated editing models (nano-banana-2, gpt-image-2). Provide the source image URL(s) in `source_images` and the instruction in `prompt`. Supports Visual DNA profiles, moodboards, and Kolbo image-editing presets. PRESET CONTRACT: if the user requests a preset, call list_presets type="image_edit" and pass its exact id as `preset_id`; never silently omit it. Do NOT use `edit_image` for these — that tool is only for mechanical enhancements (upscale/reframe/remove-background/skin). For a brand-new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
-      prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
+      prompt: z.string().optional().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset"). Required unless `prompts` is provided.'),
+      prompts: promptsField('edits of the SAME source images'),
       model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Many text-to-image ids double as editors: the server auto-routes a base id to its editing variant when source_images is present (e.g. "gpt-image-2" → gpt-image-2/edit, "nano-banana-2" → nano-banana-2-image-editing) — passing the bare id is fine, no need to hunt for the "/edit" suffix yourself. BUT this only works for models that actually have a registered edit variant. For prompt-driven photoreal photo edits (object removal, keep-this-person/remove-the-rest, crowd cleanup, inpainting) the ONLY auto-pick defaults are "nano-banana-2" or "gpt-image-2" (use GPT Image 2 when the image needs readable text). Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style models; use them only if the user names Flux. If unsure, confirm the model appears in `list_models type="image_editing"` and choose by the strengths summary — Flux edit variants are named-only.'),
       source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image") or use @image1/@image2 tags. Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
+      reference_images: z.array(z.string()).optional().describe('STYLE/COMPOSITION inspiration, alongside `source_images` on the same call — does NOT embed reference pixels. Use when the edit should follow a look sampled from other images ("re-light this shot like these references"). The pixels that must survive the edit go in `source_images`; these only steer the look. **Cap: `source_images` + `reference_images` together must not exceed `max_reference_images` from list_models for the chosen model.**'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
       num_images: z.number().optional().describe('Number of output images. Default: 1'),
@@ -230,23 +257,45 @@ function registerGenerateTools(server, client, options = {}) {
       moodboard_id: z.string().optional().describe('Moodboard ID whose master_prompt and style_guide should be applied.'),
       enable_web_search: z.boolean().optional().describe('Enable web-search grounding. Default: false'),
       resolution: z.string().optional().describe('Image resolution tier: "1K" / "2K" / "3K" / "4K". Model-dependent — call list_models and read supported_resolutions. Default: "1K" for most edit models.'),
+      quality: z.string().optional().describe('Quality tier for edit models that support it (e.g. "low", "medium", "high", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
       preset_id: z.string().optional().describe('Exact preset ID from list_presets type="image_edit" to apply an image-editing preset. If the user requests a preset, resolve and pass it; do not silently omit it.'),
       cinematic: CINEMATIC_SCHEMA,
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one edit ungraded.'),
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, cinematic, skip_color_palette, project_id, session_id }) => {
+    async ({ prompt, prompts, model, source_images, reference_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id }) => {
+      if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
       model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
-      const gen = await client.post('/v1/generate/image-edit', {
-        prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
-        visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, cinematic, skip_color_palette, project_id, session_id
-      });
+      const shared = {
+        model, source_images, reference_images, aspect_ratio, enhance_prompt,
+        visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id
+      };
+      const settings = imageSettings(shared);
+
+      // Batch mode: N different edit instructions against the SAME source
+      // images, one widget owning every generation id. Same contract as
+      // generate_image — without it, "give me 4 variations of this edit" came
+      // back as four stacked cards.
+      if (prompts && prompts.length) {
+        const batch = await submitBatch(prompts, (p) => client.post('/v1/generate/image-edit', { ...shared, prompt: p }));
+        if (ui()) return uiGenerating({
+          tool: 'generate_image_edit', kind: 'image', gen: batch.ok[0].gen, client, model,
+          count: batch.ids.length, settings,
+          generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
+          failed_submissions: batch.failed,
+          status_args: { generation_ids: batch.ids, wait: true },
+          reference_images: source_images
+        });
+        return pollBatch(client, batch, { interval: (batch.ok[0].gen.poll_interval_hint || 3) * 1000, timeout: 240000 });
+      }
+
+      const gen = await client.post('/v1/generate/image-edit', { ...shared, prompt, num_images });
 
       if (ui()) return uiGenerating({
         tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
         count: num_images,
-        settings: imageSettings({ resolution, aspect_ratio, enhance_prompt, enable_web_search, visual_dna_ids, moodboard_id, preset_id, cinematic }),
+        settings,
         reference_images: source_images
       });
 
@@ -308,7 +357,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_creative_director', kind: 'scenes', gen, client, model, prompt,
         count: scene_count || 4,
-        settings: { duration, resolution, aspect_ratio, mode: workflow_type || 'image' },
+        settings: videoSettings({ duration, resolution, aspect_ratio, mode: workflow_type || 'image', enhance_prompt, visual_dna_ids, moodboard_id, moodboard_ids }),
         reference_images,
         poll_tool: 'get_creative_director_status',
         status_args: { generation_id: gen.generation_id, wait: true }
@@ -462,7 +511,7 @@ function registerGenerateTools(server, client, options = {}) {
         const batch = await submitBatch(prompts, (p) => client.post('/v1/generate/video', { ...shared, prompt: p }));
         if (ui()) return uiGenerating({
           tool: 'generate_video', kind: 'video', gen: batch.ok[0].gen, client, model,
-          count: batch.ids.length, settings: { duration, resolution, aspect_ratio },
+          count: batch.ids.length, settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, preset_id }),
           generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
           failed_submissions: batch.failed,
           status_args: { generation_ids: batch.ids, wait: true },
@@ -475,7 +524,7 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_video', kind: 'video', gen, client, model, prompt,
-        settings: { duration, resolution, aspect_ratio },
+        settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, preset_id }),
         reference_images
       });
 
@@ -546,7 +595,7 @@ function registerGenerateTools(server, client, options = {}) {
         const batch = await submitBatch(items, (it) => client.post('/v1/generate/video/from-image', { ...shared, image_url: it.image_url, prompt: it.prompt }));
         if (ui()) return uiGenerating({
           tool: 'generate_video_from_image', kind: 'video', gen: batch.ok[0].gen, client, model,
-          count: batch.ids.length, settings: { duration, resolution, aspect_ratio },
+          count: batch.ids.length, settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, visual_dna_ids }),
           generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
           failed_submissions: batch.failed,
           status_args: { generation_ids: batch.ids, wait: true },
@@ -559,7 +608,7 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_video_from_image', kind: 'video', gen, client, model, prompt,
-        settings: { duration, resolution, aspect_ratio },
+        settings: videoSettings({ duration, resolution, aspect_ratio, enhance_prompt, visual_dna_ids }),
         reference_images: [image_url]
       });
 
@@ -1050,7 +1099,12 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_elements', kind: 'video', gen: startResponse, client, model, prompt,
-        settings: { duration, resolution, aspect_ratio },
+        settings: videoSettings({
+          duration,
+          reported_duration: startResponse?.duration ?? startResponse?.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),
@@ -1138,7 +1192,7 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_first_last_frame', kind: 'video', gen: startResponse, client, model, prompt,
-        settings: { duration, resolution, aspect_ratio },
+        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 || ''))
       });
@@ -1359,7 +1413,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_video_from_video', kind: 'video', gen: startResponse, client, model,
         prompt: prompt || (preset ? `Subtitles preset: ${preset}` : undefined),
-        settings: { duration, resolution, aspect_ratio, mode: preset ? 'subtitles' : 'restyle' },
+        settings: videoSettings({ duration, resolution, aspect_ratio, mode: preset ? 'subtitles' : 'restyle', enhance_prompt, visual_dna_ids }),
         reference_images: [...(reference_images || []), ...(elements || [])]
       });
 

package/src/tools/media.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { resolveToBuffer, DEFAULT_MAX_FILE_MB, compactList } = require('./_shared');
-const { UI, uiResult, listResult, appsEnabled } = require('../apps');
+const { UI, uiResult, listResult } = require('../apps');
 
 // How many tiles the media grid renders. A rendering limit only — the text
 // payload always carries the full page, and `total` reports the real library
@@ -65,8 +65,6 @@ function uploadTicketPayload(ticket) {
 }
 
 function registerMediaTools(server, client, options = {}) {
-  const ui = () => appsEnabled(server, options);
-
   // `opts.apps` is set only by kolbo-api's per-request server (see createServer
   // in ../index.js), which makes it a TRANSPORT signal — deliberately not
   // `appsEnabled()`, which also returns true for stdio hosts that advertise UI.
@@ -101,24 +99,27 @@ function registerMediaTools(server, client, options = {}) {
         expires_in_seconds: ticket.expires_in,
       };
 
-      if (ui()) {
-        // upload_ui_url: top-level page for Claude iOS/Android — in-iframe
-        // <input type=file> selections are dropped by WebKit (see upload widget).
-        const uploadUiUrl = ticket.upload_ui_url
-          || String(ticket.upload_url || '').replace(/\/upload\/?$/, '/upload-ui');
-        return uiResult(UI.upload, JSON.stringify(info, null, 2), {
-          widget: 'upload',
-          title: purpose || 'Upload media',
-          upload_url: ticket.upload_url,
-          upload_ui_url: uploadUiUrl,
-          token: ticket.token,
-          expires_at: Date.now() + (ticket.expires_in || 900) * 1000,
-          kinds: media_types && media_types.length ? media_types : undefined,
-          max_files: Math.min(Math.max(Number(max_files) || 10, 1), 20),
-          max_mb: ticket.max_file_mb || DEFAULT_MAX_FILE_MB,
-          ...(project_id ? { project_id } : {}),
-        });
-      }
+      // Always ship structuredContent. Kolbo Code does NOT advertise MCP Apps, so
+      // gating the grid payload on appsEnabled() sent it text only; the host then
+      // rebuilt items from the compactList text, whose field names are
+      // `filename`/`url` — not the `title`/`thumbnail` the grid renders — so every
+      // tile came out black and unlabelled. Same reasoning as listResult().
+      // upload_ui_url: top-level page for Claude iOS/Android — in-iframe
+      // <input type=file> selections are dropped by WebKit (see upload widget).
+      const uploadUiUrl = ticket.upload_ui_url
+        || String(ticket.upload_url || '').replace(/\/upload\/?$/, '/upload-ui');
+      return uiResult(UI.upload, JSON.stringify(info, null, 2), {
+        widget: 'upload',
+        title: purpose || 'Upload media',
+        upload_url: ticket.upload_url,
+        upload_ui_url: uploadUiUrl,
+        token: ticket.token,
+        expires_at: Date.now() + (ticket.expires_in || 900) * 1000,
+        kinds: media_types && media_types.length ? media_types : undefined,
+        max_files: Math.min(Math.max(Number(max_files) || 10, 1), 20),
+        max_mb: ticket.max_file_mb || DEFAULT_MAX_FILE_MB,
+        ...(project_id ? { project_id } : {}),
+      });
 
       // Text-only host (Claude Code, Codex CLI, Cursor): no iframe to render —
       // but these are exactly the hosts that CAN reach a filesystem, so hand
@@ -263,30 +264,33 @@ function registerMediaTools(server, client, options = {}) {
         note: 'Narrow with `type`, `category`, `project_id`, `folder_id`, or `search`; get_media returns one item in full.',
       });
 
-      if (ui()) {
-        // The SDK envelope reports `total_items` (see sdk/controller.js listMedia);
-        // reading `total` always came back undefined, so the grid claimed the page
-        // size was the whole library. Accept either, then fall back.
-        const totalItems = pagination
-          ? (pagination.total_items != null ? pagination.total_items : pagination.total)
-          : null;
-        const items = media.slice(0, GRID_CAP).map((m) => ({
-          id: m.id,
-          title: m.filename,
-          subtitle: m.media_type + (m.size ? ' · ' + Math.round(m.size / 1024) + 'KB' : ''),
-          thumbnail: m.media_type === 'image' ? m.url : (m.thumbnail_url || null),
-          media_type: m.media_type,
-          url: m.url,
-          use_hint: 'Use this media library asset in my next step:\nURL: {URL}\n(id: {ID})'
-        }));
-        return uiResult(UI.mediaGrid, text, {
-          widget: 'media-grid',
-          title: 'Media Library',
-          items,
-          total: totalItems != null ? totalItems : media.length,
-          shown: Math.min(media.length, GRID_CAP)
-        });
-      }
+      // Always ship structuredContent. Kolbo Code does NOT advertise MCP Apps, so
+      // gating the grid payload on appsEnabled() sent it text only; the host then
+      // rebuilt items from the compactList text, whose field names are
+      // `filename`/`url` — not the `title`/`thumbnail` the grid renders — so every
+      // tile came out black and unlabelled. Same reasoning as listResult().
+      // The SDK envelope reports `total_items` (see sdk/controller.js listMedia);
+      // reading `total` always came back undefined, so the grid claimed the page
+      // size was the whole library. Accept either, then fall back.
+      const totalItems = pagination
+        ? (pagination.total_items != null ? pagination.total_items : pagination.total)
+        : null;
+      const items = media.slice(0, GRID_CAP).map((m) => ({
+        id: m.id,
+        title: m.filename,
+        subtitle: m.media_type + (m.size ? ' · ' + Math.round(m.size / 1024) + 'KB' : ''),
+        thumbnail: m.media_type === 'image' ? m.url : (m.thumbnail_url || null),
+        media_type: m.media_type,
+        url: m.url,
+        use_hint: 'Use this media library asset in my next step:\nURL: {URL}\n(id: {ID})'
+      }));
+      return uiResult(UI.mediaGrid, text, {
+        widget: 'media-grid',
+        title: 'Media Library',
+        items,
+        total: totalItems != null ? totalItems : media.length,
+        shown: Math.min(media.length, GRID_CAP)
+      });
 
       return {
         content: [{

package/src/tools/moodboards.js

@@ -4,11 +4,10 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
-const { UI, uiResult, appsEnabled } = require('../apps');
+const { UI, uiResult } = require('../apps');
 const { projectScopeReadField } = require('./_shared');
 
 function registerMoodboardTools(server, client, options = {}) {
-  const ui = () => appsEnabled(server, options);
   // ─── list_moodboards ───────────────────────────────────────
   server.tool(
     'list_moodboards',
@@ -29,25 +28,26 @@ function registerMoodboardTools(server, client, options = {}) {
         count: result.count || 0
       }, null, 2);
 
-      if (ui()) {
-        return uiResult(UI.mediaGrid, text, {
-          widget: 'media-grid',
-          title: 'Moodboards',
-          items: moodboards.slice(0, 24).map(mb => ({
-            id: mb.id,
-            title: mb.name,
-            // API returns thumbnail_url + images[] (sdk listMoodboards) — both
-            // previous keys were wrong, so the fallback never fired either.
-            thumbnail: mb.thumbnail_url || mb.thumbnail || (Array.isArray(mb.images) ? mb.images[0] : undefined),
-            media_type: 'image',
-            use_hint: 'Apply moodboard "{TITLE}" (moodboard_id: {ID}) to my next generation.'
-          })),
-          total: result.count || moodboards.length,
-          has_more: moodboards.length > 24
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      // Always ship structuredContent. Kolbo Code does NOT advertise MCP Apps, so
+      // gating the grid payload on appsEnabled() sent it text only; the host then
+      // rebuilt items from the compactList text, whose field names are
+      // `filename`/`url` — not the `title`/`thumbnail` the grid renders — so every
+      // tile came out black and unlabelled. Same reasoning as listResult().
+      return uiResult(UI.mediaGrid, text, {
+        widget: 'media-grid',
+        title: 'Moodboards',
+        items: moodboards.slice(0, 24).map(mb => ({
+          id: mb.id,
+          title: mb.name,
+          // API returns thumbnail_url + images[] (sdk listMoodboards) — both
+          // previous keys were wrong, so the fallback never fired either.
+          thumbnail: mb.thumbnail_url || mb.thumbnail || (Array.isArray(mb.images) ? mb.images[0] : undefined),
+          media_type: 'image',
+          use_hint: 'Apply moodboard "{TITLE}" (moodboard_id: {ID}) to my next generation.'
+        })),
+        total: result.count || moodboards.length,
+        has_more: moodboards.length > 24
+      });
     }
   );
 

package/src/tools/visual_dna.js

@@ -6,7 +6,11 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES, projectScopeReadField, compactList } = require('./_shared');
-const { UI, uiResult, listResult, appsEnabled } = require('../apps');
+const { UI, uiResult, listResult } = require('../apps');
+
+// Reference sheets are a blocking multi-panel render; the 120s client default
+// aborted them mid-flight while the server finished and charged anyway.
+const CHARACTER_SHEET_TIMEOUT_MS = Number(process.env.KOLBO_CHARACTER_SHEET_TIMEOUT_MS) || 600000;
 
 // Visual DNA caps reference media at 25MB per file (stricter than the
 // default _shared.resolveToBuffer cap — DNA profiles only need enough
@@ -16,7 +20,6 @@ function resolveToBuffer(source, kind) {
 }
 
 function registerVisualDnaTools(server, client, options = {}) {
-  const ui = () => appsEnabled(server, options);
   // ─── create_visual_dna ─────────────────────────────────────
   server.tool(
     'create_visual_dna',
@@ -129,24 +132,25 @@ function registerVisualDnaTools(server, client, options = {}) {
         note: 'Narrow with `search`, `tags`, or `collection`, or pass `page`/`limit` for the rest; get_visual_dna returns one in full.',
       });
 
-      if (ui()) {
-        return uiResult(UI.mediaGrid, text, {
-          widget: 'media-grid',
-          title: 'Visual DNA Profiles',
-          items: dnas.slice(0, 24).map(d => ({
-            id: d.id,
-            title: d.name,
-            subtitle: (d.dna_type || '') + (Array.isArray(d.tags) && d.tags.length ? ' · ' + d.tags.slice(0, 3).join(', ') : ''),
-            thumbnail: d.thumbnail_url || d.thumbnail,
-            media_type: 'image',
-            use_hint: 'Use Visual DNA "{TITLE}" (id: {ID}) in my next generation for character/style consistency.'
-          })),
-          total,
-          has_more: result.has_more || dnas.length > 24
-        });
-      }
-
-      return { content: [{ type: 'text', text }] };
+      // Always ship structuredContent. Kolbo Code does NOT advertise MCP Apps, so
+      // gating the grid payload on appsEnabled() sent it text only; the host then
+      // rebuilt items from the compactList text, whose field names are
+      // `filename`/`url` — not the `title`/`thumbnail` the grid renders — so every
+      // tile came out black and unlabelled. Same reasoning as listResult().
+      return uiResult(UI.mediaGrid, text, {
+        widget: 'media-grid',
+        title: 'Visual DNA Profiles',
+        items: dnas.slice(0, 24).map(d => ({
+          id: d.id,
+          title: d.name,
+          subtitle: (d.dna_type || '') + (Array.isArray(d.tags) && d.tags.length ? ' · ' + d.tags.slice(0, 3).join(', ') : ''),
+          thumbnail: d.thumbnail_url || d.thumbnail,
+          media_type: 'image',
+          use_hint: 'Use Visual DNA "{TITLE}" (id: {ID}) in my next generation for character/style consistency.'
+        })),
+        total,
+        has_more: result.has_more || dnas.length > 24
+      });
     }
   );
 
@@ -200,12 +204,33 @@ function registerVisualDnaTools(server, client, options = {}) {
       sheet_type: z.enum(['character', 'character_headless', 'character_bible', 'product', 'environment', 'style']).optional().describe('Sheet layout. character = front/back/face turnaround. character_headless = wardrobe/body refs with a headless front panel (use when clothing must change without fighting the face sheet). character_bible = denser production model-sheet (turnaround + faces + wardrobe + color swatches). product / environment / style = matching DNA types. Defaults to character.')
     },
     async ({ image_urls, sheet_type }) => {
-      const result = await client.post('/v1/visual-dna/character-sheet', { image_urls, ...(sheet_type ? { sheet_type } : {}) });
+      // The endpoint is blocking and a 2K multi-panel sheet routinely runs past the
+      // 120s default: the MCP aborted while kolbo-api kept going, finished, and
+      // billed — the user saw "Failed" for a sheet they had already paid for.
+      const result = await client.post(
+        '/v1/visual-dna/character-sheet',
+        { image_urls, ...(sheet_type ? { sheet_type } : {}) },
+        { timeoutMs: CHARACTER_SHEET_TIMEOUT_MS },
+      );
+      // `urls` is NOT redundant with character_sheet_url. Every generation-card
+      // reader keys on `urls` — the MCP's own widget (apps/widgets/generation.js),
+      // kolbo-code's kolbo-operation.ts mediaUrls(), and its operation.js urlsOf().
+      // Kolbo Code mounts a generation card for ANY tool named `generate_*`, so
+      // returning only character_sheet_url gave the card zero URLs and it rendered
+      // "No output received / Failed" on top of a sheet that generated fine and was
+      // already billed — and "Try Again" then double-charged. `widget`/`phase` mark
+      // the payload as a completed generation so the card stops falling back to the
+      // stale `phase: "review"` envelope built before the tool ran.
+      const urls = result.character_sheet_url ? [result.character_sheet_url] : [];
       return {
         content: [{
           type: 'text',
           text: JSON.stringify({
             character_sheet_url: result.character_sheet_url,
+            urls,
+            widget: 'generation',
+            phase: 'completed',
+            kind: 'image',
             credits_used: result.credits_used,
             _hint: 'Show the sheet to the user, then pass character_sheet_url to create_visual_dna as that DNA\'s reference.'
           }, null, 2)