@kolbo/mcp 1.108.0 → 1.110.1

package/package.json

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

package/src/apps/html.js

@@ -236,9 +236,13 @@ function showPeekItem(time) {
   var it = peekList[peekIndex];
   var img = el('peek-img');
   var vid = el('peek-video');
+  var oldNote = el('peek-stage') && el('peek-stage').querySelector('.k-vnote');
+  if (oldNote) oldNote.parentNode.removeChild(oldNote);
+  vid.removeAttribute('data-unplayable');
   if (it.kind === 'video') {
     img.removeAttribute('src');
     vid.setAttribute('src', it.url);
+    guardPlayback(vid);
     if (time) vid.addEventListener('loadedmetadata', function () { try { vid.currentTime = time; } catch (e) {} }, { once: true });
     var p = vid.play && vid.play();
     if (p && p.catch) p.catch(function () {});
@@ -363,6 +367,42 @@ function wireVideoExpand(root) {
     b.addEventListener('keydown', mark);
     v.addEventListener('dblclick', function (e) { e.preventDefault(); mark(); b.click(); });
     v.parentNode.insertBefore(b, v.nextSibling);
+    guardPlayback(v);
+  });
+}
+// Some outputs cannot be decoded by a browser: 10/12-bit HEVC (Bytedance
+// Upscaler Pro, Seedance 1080p masters) either errors or plays sound over a
+// black frame. Detect both and replace the dead player with a clear note and
+// a Download button instead of leaving the user staring at nothing.
+function guardPlayback(v) {
+  if (!v || v.getAttribute('data-guard')) return;
+  v.setAttribute('data-guard', '1');
+  function fail() {
+    if (v.getAttribute('data-unplayable') || !v.parentNode) return;
+    v.setAttribute('data-unplayable', '1');
+    try { v.pause(); } catch (e) {}
+    var url = v.currentSrc || v.getAttribute('src');
+    var note = document.createElement('div');
+    note.className = 'k-vnote';
+    note.innerHTML = '<div class="k-vnote-t"></div><div class="k-vnote-s"></div><button type="button" class="k-btn primary"></button>';
+    note.querySelector('.k-vnote-t').textContent = "This video can't play in the browser";
+    note.querySelector('.k-vnote-s').textContent = 'It uses a high-quality format (HEVC, 10/12-bit) most browsers do not decode. Download it and open it in a video player.';
+    var dl = note.querySelector('button');
+    dl.innerHTML = ICONS.download + ' Download video';
+    dl.onclick = function (e) { e.stopPropagation(); window.kolbo.openLink(downloadUrl(url)); };
+    v.parentNode.insertBefore(note, v.nextSibling);
+    if (window.kolbo && window.kolbo.notifySize) window.kolbo.notifySize();
+  }
+  v.addEventListener('error', function () {
+    var code = v.error && v.error.code;
+    // 3 = decode failure, 4 = format not supported. Network errors (2) are not a format problem.
+    if (code === 3 || code === 4) fail();
+  });
+  // Sound with no picture: time advances but no video frame was ever decoded.
+  v.addEventListener('timeupdate', function () {
+    if (v.currentTime < 1.2 || v.getAttribute('data-unplayable')) return;
+    var q = v.getVideoPlaybackQuality ? v.getVideoPlaybackQuality() : null;
+    if ((q && q.totalVideoFrames === 0) || (v.readyState >= 2 && v.videoWidth === 0)) fail();
   });
 }
 if (window.MutationObserver) {

package/src/apps/index.js

@@ -358,8 +358,20 @@ async function modelInfoMap(client) {
 }
 
 /** Resolve one model's { icon, eta, name }; missing → all null. */
+// Engines hidden from /v1/models that still reach a card, shown as the public
+// model the user actually knows. draft_enhance finalizes a Seedance 2.5 Draft;
+// its engine id is internal, so the card showed "Smart Select" / a raw id.
+const DISPLAY_ALIASES = {
+  'flux-3-draft-enhance': { base: 'seedance-2-5', name: 'Seedance 2.5 Draft Enhance' },
+  'video-draft-enhance': { base: 'seedance-2-5', name: 'Seedance 2.5 Draft Enhance' },
+};
+// Operations whose engine is picked server-side when no model is passed.
+const OPERATION_ENGINES = { draft_enhance: 'flux-3-draft-enhance' };
+
 async function modelInfo(client, modelName) {
   if (!modelName) return { icon: null, eta: null, name: null };
+  const alias = DISPLAY_ALIASES[String(modelName).toLowerCase()];
+  if (alias) return { ...(await modelInfo(client, alias.base)), name: alias.name };
   const catalog = await modelCatalog(client);
   const exact = catalog.byKey.get(String(modelName).toLowerCase());
   if (exact) return exact;
@@ -827,6 +839,7 @@ module.exports = {
   appsEnabled,
   modelIcon,
   modelInfo,
+  OPERATION_ENGINES,
   modelInfoMap,
   voiceInfo,
   canonicalModelId,

package/src/apps/theme.js

@@ -222,6 +222,17 @@ html.k-peek-fs .k-card { min-height: 0; backdrop-filter: none; -webkit-backdrop-
   display: inline-flex; align-items: center; justify-content: center;
 }
 .k-vexpand:hover { background: var(--brand); border-color: var(--brand); }
+/* Undecodable video (10/12-bit HEVC): the dead player is replaced by a note. */
+video[data-unplayable] { display: none !important; }
+video[data-unplayable] ~ .k-vexpand { display: none; }
+.k-vnote { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 6px;
+  width: 100%; min-height: 160px; padding: 18px 16px; border-radius: 10px; text-align: center;
+  background: rgba(255, 255, 255, 0.05); }
+.k-vnote-t { font-size: 13px; font-weight: 600; color: var(--text); }
+.k-vnote-s { font-size: 12px; color: var(--text-muted); max-width: 360px; margin-bottom: 4px; }
+.k-peek-stage .k-vnote { max-width: 440px; color: #fff; }
+.k-peek-stage .k-vnote-t { color: #fff; }
+.k-peek-stage .k-vnote-s { color: rgba(255, 255, 255, 0.7); }
 /* Recent Chromium still draws the native button despite controlslist. */
 video::-webkit-media-controls-fullscreen-button { display: none !important; }
 /* ---- Plans / upgrade card ---- */

package/src/apps/widgets/generation.js

@@ -340,7 +340,8 @@ function renderChips(sc) {
       : ICONS.mic;
     h += chip(face + ' ' + esc(voice));
   }
-  if (s.mode) h += chip(esc(s.mode));
+  if (s.mode) h += chip(esc(editLabel(s.mode)));
+  if (Array.isArray(s.details)) s.details.forEach(function (d) { if (d) h += chip(esc(String(d))); });
   if (many && !kind) h += chip(sc.count + ' items');
   h += referenceHTML(sc);
   el('chips').innerHTML = h;
@@ -460,6 +461,17 @@ function capLabel(inner) {
   return String(inner).replace(/(^|>)(\\s*)([a-z])/, function (m, gt, sp, ch) { return gt + sp + ch.toUpperCase(); });
 }
 function chip(inner) { return '<span class="k-chip">' + capLabel(inner) + '</span>'; }
+// edit_image / edit_video operation ids -> the words a user reads. Unknown ids
+// fall back to the id with spaces, never the raw snake_case.
+var EDIT_LABELS = {
+  upscale: 'Upscale', clarity_upscale: 'Clarity upscale', reframe: 'Reframe', zoom_out: 'Expand',
+  removebg: 'Remove background', remove_background: 'Remove background', background_replace: 'Replace background',
+  enhance_skin: 'Skin enhance', enhance: 'Photo enhance', inpaint: 'Inpaint', erase: 'Erase', face_swap: 'Face swap',
+  camera_angle: 'Camera angle', split: 'Split grid', split_upscale: 'Split + upscale', multi_shot: 'Multi-shot',
+  magic_edit: 'Magic edit', generate_audio: 'Add audio', remove_watermark: 'Remove watermark', extend: 'Extend',
+  lipsync: 'Lipsync', retake: 'Retake', draft_enhance: 'Finalize draft', draft_quote: 'Draft quote'
+};
+function editLabel(mode) { return EDIT_LABELS[mode] || String(mode).split('_').join(' '); }
 // 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) {
@@ -1246,6 +1258,7 @@ function renderActions(sc) {
   bind('btn-open', function () { window.kolbo.openLink(kolboUrl(state)); });
   bind('btn-recreate', function () {
     window.kolbo.sendMessage('Recreate this with the same settings' +
+      (state.settings && state.settings.mode ? '\\nOperation: ' + state.settings.mode : '') +
       (state.model ? '\\nModel: ' + state.model : '') +
       (state.prompt ? '\\nPrompt: ' + state.prompt : '') +
       '\\n(from the ' + (TOOL_TITLES[state.tool] || 'generation') + ' widget)');
@@ -1335,7 +1348,7 @@ function preRefSc(toolName, a) {
       resolution: a.draft === true ? '480p-draft' : a.draft === false ? String(a.resolution || '').replace(/-draft$/i, '') : a.resolution,
       aspect_ratio: a.aspect_ratio,
       quality: a.quality,
-      mode: a.mode,
+      mode: a.operation || a.mode,
       cinematic: a.cinematic,
       visual_dna_ids: a.visual_dna_ids,
       moodboard_ids: a.moodboard_ids,
@@ -1405,6 +1418,7 @@ function liveFromTimedOut(sc) {
       resolution: originArgs.draft === true ? '480p-draft' : originArgs.draft === false ? String(originArgs.resolution || '').replace(/-draft$/i, '') : originArgs.resolution,
       aspect_ratio: originArgs.aspect_ratio,
       quality: originArgs.quality,
+      mode: originArgs.operation,
       visual_dna_ids: originArgs.visual_dna_ids,
       moodboard_id: originArgs.moodboard_id
     },
@@ -1433,7 +1447,8 @@ function completedFromPlain(sc) {
       is_draft: originArgs.draft,
       resolution: originArgs.draft === true ? '480p-draft' : originArgs.draft === false ? String(originArgs.resolution || '').replace(/-draft$/i, '') : originArgs.resolution,
       aspect_ratio: originArgs.aspect_ratio,
-      quality: originArgs.quality
+      quality: originArgs.quality,
+      mode: originArgs.operation
     },
     urls: sc.urls || [],
     session_id: sc.session_id || originArgs.session_id,

package/src/index.js

@@ -141,7 +141,8 @@ function createServer(opts = {}) {
       '9. MODEL SELECTION — NAMED MODEL WINS, THEN STRENGTHS SUMMARY: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). If the user named a model this turn OR earlier in the conversation (including a compaction "Locked choices" / summary), that name is a FAMILY LOCK: pass it (or its display name) on every follow-up, including when the tool changes (text-to-video → image-to-video). Identifier resolution remaps a t2v id to the family\'s i2v sibling automatically. NEVER substitute a different brand because it is cheaper, faster, or "best balance" (Grok Imagine named → do not fire Seedance). If the named family has no variant for this modality, ASK — do not silently switch. Cheapest-summary routing applies ONLY when no model was named on this task: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost — then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
       '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
       '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.',
-      '12. DRAFT IS A TIER, NOT A RESOLUTION: when the user says "draft" (Hebrew "טיוטה") for a video — "480 draft", "draft mode", "480p draft" — pass `draft: true` on the generate_* call (or `resolution: "480p-draft"`) with the SAME model, e.g. `seedance-2-5`. Plain `resolution: "480p"` is a regular full-price render and is NEVER Draft. Draft exists only where list_models `supported_resolutions` includes "480p-draft"; if the chosen model lacks it, say so instead of silently rendering regular 480p.'
+      '12. DRAFT IS A TIER, NOT A RESOLUTION: when the user says "draft" (Hebrew "טיוטה") for a video — "480 draft", "draft mode", "480p draft" — pass `draft: true` on the generate_* call (or `resolution: "480p-draft"`) with the SAME model, e.g. `seedance-2-5`. Plain `resolution: "480p"` is a regular full-price render and is NEVER Draft. Draft exists only where list_models `supported_resolutions` includes "480p-draft"; if the chosen model lacks it, say so instead of silently rendering regular 480p.',
+      '13. VIDEO UPSCALE SETTINGS: when the user asks to upscale a video with specific quality controls (6K/8K, Pro/fast, 10/12-bit, film restoration, AI-footage tuning, custom scale), use `edit_video` operation="upscale" with model "bytedance-upscaler/upscale/video" and pass the matching fields (`resolution` 1080p-8k or `scale_ratio`, `target_fps`, `enhancement_tier`, `enhancement_preset`, `fidelity`, `bit_depth`). Pro costs 10x and caps the source at 30s; 6K/8K cap at 120s/60s; 10/12-bit needs Pro. State the credit cost before running Pro or 6K/8K.'
     ].join('\n')
   });
   const progress = require('./progress');

package/src/tools/_shared.js

@@ -698,7 +698,7 @@ function buildProjectUrl(projectId, opts = {}) {
 // ui://kolbo/generation.html widget takes over: live progress, inline result,
 // action buttons. Text-only hosts never enter this path — their blocking
 // behavior and response bytes are UNCHANGED.
-const { UI, uiResult, appsEnabled, modelInfo } = require('../apps');
+const { UI, uiResult, appsEnabled, modelInfo, OPERATION_ENGINES } = require('../apps');
 
 /**
  * Chip identity for a model: the CLEAN display name + its icon, resolved from
@@ -706,8 +706,13 @@ const { UI, uiResult, appsEnabled, modelInfo } = require('../apps');
  * user/LLM supplied (an identifier like `google_tts`, `fal-ai/…/omnihuman/v1.5`,
  * or a display name) — the card must never show the raw id.
  */
-async function modelChipFields(client, model) {
-  const info = await modelInfo(client, model).catch(() => null);
+// `operation`: an edit whose engine the server picks when no model is passed
+// (draft_enhance) still names that engine on the chip, not "Smart Select".
+// `model` itself stays unset so Recreate never pins a hidden engine id.
+async function modelChipFields(client, model, operation) {
+  const lookup = model || (operation && OPERATION_ENGINES[operation]);
+  const info = await modelInfo(client, lookup).catch(() => null);
+  if (!model && info && info.name) return { model: 'Smart Select', model_name: info.name, model_icon: info.icon || null };
   return {
     model: model || 'Smart Select',
     model_name: (info && info.name) || model || 'Smart Select',
@@ -898,7 +903,7 @@ function moodboardIds(settings) {
  */
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
-  const chip = await modelChipFields(p.client, p.model);
+  const chip = await modelChipFields(p.client, p.model, p.settings && p.settings.mode);
   const settings = await decorateSettings(p.client, p.settings || {});
   const structured = {
     phase: 'generating',
@@ -1009,7 +1014,7 @@ function preferOwnedUrls(urls) {
 }
 
 async function uiCompleted(p, textPayload, extraContent) {
-  const chip = await modelChipFields(p.client, p.model);
+  const chip = await modelChipFields(p.client, p.model, p.settings && p.settings.mode);
   const settings = p.settings ? await decorateSettings(p.client, p.settings) : undefined;
   const structured = {
     phase: 'completed',

package/src/tools/flow-contract.json

@@ -131,6 +131,11 @@
     "upscaleMode",
     "targetResolution",
     "targetFps",
+    "scaleRatio",
+    "enhancementTier",
+    "enhancementPreset",
+    "fidelity",
+    "bitDepth",
     "extendMode",
     "extendDuration",
     "presetId",

package/src/tools/flow-schema.js

@@ -20,7 +20,7 @@ const voice = z.union([z.string().max(256), z.object({
   name: z.string().max(500).optional(), type: z.string().max(128).optional(),
 }).strict()]);
 const booleanConfig = new Set('instrumental preservePitch resolved enhancePrompt soundEnabled sound_enabled showLyrics includeAudio loop reverse'.split(' '));
-const numberConfig = new Set('scale frameCount quantity startTime endTime speed timestamp speaking_speed promptInfluence creativity resemblance movement upscaleFactor targetFps extendDuration skinIntensity start end cropX cropY cropWidth cropHeight x y width height fps frameTime seed temperature maxTokens volume'.split(' '));
+const numberConfig = new Set('scale frameCount quantity startTime endTime speed timestamp speaking_speed promptInfluence creativity resemblance movement upscaleFactor targetFps scaleRatio bitDepth extendDuration skinIntensity start end cropX cropY cropWidth cropHeight x y width height fps frameTime seed temperature maxTokens volume'.split(' '));
 const modelConfig = new Set('model t2iModel i2iModel t2vModel i2vModel flModel modelId engineId'.split(' '));
 const configShape = Object.fromEntries(contract.config_fields.map(field => {
   let schema = text;

package/src/tools/generate.js

@@ -2325,6 +2325,50 @@ function registerGenerateTools(server, client, options = {}) {
       }, null, 2));
     }
   );
+  // Short human chips for the settings an edit actually ran with — the card
+  // shows these next to the operation label (raw ids never reach the card).
+  const editDetails = (op, a) => {
+    const d = [];
+    const has = (v) => v !== undefined && v !== null && v !== '';
+    if (op === 'upscale' || op === 'split_upscale') {
+      if (has(a.scale)) d.push(`${a.scale}×`);
+      if (a.face_enhancement === false) d.push('no face enhance');
+      else if (has(a.face_enhancement_strength)) d.push(`face ${a.face_enhancement_strength}`);
+    }
+    if (op === 'clarity_upscale') {
+      if (has(a.scale)) d.push(`${a.scale}×`);
+      if (has(a.creativity)) d.push(`creativity ${a.creativity}`);
+      if (has(a.resemblance)) d.push(`resemblance ${a.resemblance}`);
+    }
+    if (op === 'enhance_skin') {
+      d.push(a.skin_strength || 'realistic');
+      if (a.fix_lighting) d.push('fix lighting');
+      if (has(a.freckle_intensity) && a.skin_strength === 'freckle') d.push(`freckles ${a.freckle_intensity}`);
+    }
+    if (op === 'camera_angle') {
+      if (a.generate_all_angles) d.push('all angles');
+      else {
+        if (has(a.horizontal_angle)) d.push(`${a.horizontal_angle}° turn`);
+        if (has(a.vertical_angle)) d.push(`${a.vertical_angle}° tilt`);
+        if (has(a.camera_zoom)) d.push(`zoom ${a.camera_zoom}`);
+      }
+    }
+    if (op === 'zoom_out') {
+      if ([a.expand_left, a.expand_right, a.expand_top, a.expand_bottom].some(has)) d.push('custom expand');
+      else if (has(a.zoom_out_percentage)) d.push(`${a.zoom_out_percentage}%`);
+    }
+    if (op === 'split' && has(a.split_layout)) d.push(a.split_layout);
+    if (op === 'background_replace' && a.background_reference_image) d.push('reference bg');
+    if (has(a.enhancement_model)) d.push(a.enhancement_model);
+    if (has(a.scale_ratio)) d.push(`${a.scale_ratio}×`);
+    if (has(a.enhancement_tier) && a.enhancement_tier !== 'standard') d.push(a.enhancement_tier);
+    if (has(a.enhancement_preset) && a.enhancement_preset !== 'general') d.push(a.enhancement_preset);
+    if (has(a.bit_depth) && Number(a.bit_depth) > 8) d.push(`${a.bit_depth}-bit`);
+    if (has(a.target_fps)) d.push(`${a.target_fps} fps`);
+    if (op === 'extend' && has(a.mode)) d.push(`at ${a.mode}`);
+    return d.length ? d : undefined;
+  };
+
   // ─── edit_image ────────────────────────────────────────────
   server.tool(
     'edit_image',
@@ -2351,12 +2395,12 @@ function registerGenerateTools(server, client, options = {}) {
         '"reframe" — RE-GENERATES the entire picture at a new aspect ratio (Luma Photon). The subject is re-imagined, not preserved — expect a different-looking image. Use ONLY when the user explicitly wants the shot re-taken in another format. If they said "expand", "extend", "widen", "uncrop", "add space", "fill the sides", or "keep it the same but 16:9", they want "zoom_out" instead. Requires `aspect_ratio`.',
         '"removebg" — remove the image background, output is transparent PNG.',
         '"background_replace" — remove background and replace it with AI-generated content from `prompt`.',
-        '"enhance_skin" — portrait skin retouching (use `skin_strength`: "subtle" | "realistic" | "pimple" | "freckle").',
+        '"enhance_skin" — realistic skin texture on portraits (Enhancor). `skin_strength`: "subtle" (barely visible — avoid unless asked), "realistic" (default, visible pore/texture detail; add `fix_lighting=true` to also even out lighting), "pimple" (removes blemishes), "freckle" (adds freckles — set `freckle_intensity`). Works on visible faces: on a full-body shot or a multi-panel character sheet the face is small and the change is hard to see — run it on a face close-up or crop instead.',
         '"enhance" — Topaz photo correction at the SOURCE resolution (no resizing). Pick the tool with `model`: "topaz/adjust/image" (exposure, white balance, or colorizing a black-and-white photo), "topaz/sharpen/image" (lens / motion / portrait / wildlife blur, or Super Focus for severely blurred shots), "topaz/denoise/image" (high-ISO and night noise), "topaz/restore/image" (old or damaged photos, dust and scratches). Choose the specific engine with `enhancement_model` — call list_models type="graphics_enhance" to see each model\'s engines. To make an image BIGGER use "upscale" instead.',
         '"inpaint" — paint over a masked area using `mask_image_url` (B&W mask, white = fill area) and optional `prompt`. Add reference images via `additional_images`.',
         '"erase" — erase an object defined by `mask_image_url` (white = erase area).',
         '"face_swap" — swap the face in `image_url` with the face from `mask_image_url` (required).',
-        '"camera_angle" — generate the image from a different camera angle. Set `generate_all_angles=true` for a full set. Use `prompt` to guide the angle.',
+        '"camera_angle" — generate the image from a different camera angle. Set the view with `horizontal_angle` / `vertical_angle` / `camera_zoom` (preferred — exact), or describe it in `prompt` ("left side", "back", "low angle", "bird\'s eye", "close up", "wide"); with neither, the view barely changes. Set `generate_all_angles=true` for the 12-angle set.',
         '"split" — split the image into a 3×3 grid of tiles. "split_upscale" — split into a grid and upscale each tile.',
         '"multi_shot" — generate a 3×3 multi-shot grid of scenes (uses `additional_images` as reference shots). Use `resolution` for output quality.',
         '"magic_edit" (DEPRECATED) — prompt-driven content edit. Prefer `generate_image_edit` for better results.',
@@ -2400,7 +2444,45 @@ function registerGenerateTools(server, client, options = {}) {
 
       // ── enhance_skin ───────────────────────────────────────
       skin_strength: z.enum(['subtle', 'realistic', 'pimple', 'freckle']).optional()
-        .describe('Skin enhancement preset. Used with operation="enhance_skin". Default: "realistic".'),
+        .describe('Skin enhancement preset. Used with operation="enhance_skin". Default: "realistic". "subtle" changes very little.'),
+      freckle_intensity: z.union([z.literal(0), z.literal(50), z.literal(100)]).optional()
+        .describe('Freckle amount: 0, 50 or 100. Used with operation="enhance_skin" and skin_strength="freckle". Default: 50.'),
+      fix_lighting: z.boolean().optional()
+        .describe('Also correct uneven / flat lighting on the face. Used with operation="enhance_skin" and skin_strength="realistic". Default: false.'),
+
+      // ── camera_angle ───────────────────────────────────────
+      horizontal_angle: z.number().min(0).max(360).optional()
+        .describe('Camera rotation around the subject in degrees (0-360; 0 = unchanged, 90 = right side, 180 = behind). Used with operation="camera_angle" when generate_all_angles is not set.'),
+      vertical_angle: z.number().min(-30).max(90).optional()
+        .describe('Camera tilt in degrees (-30 = from below, 0 = eye level, 90 = straight down). Used with operation="camera_angle".'),
+      camera_zoom: z.number().min(0).max(10).optional()
+        .describe('Camera distance (0 = far, 5 = unchanged, 10 = close-up). Used with operation="camera_angle". Default: 5.'),
+
+      // ── upscale (Topaz) / clarity_upscale ──────────────────
+      face_enhancement: z.boolean().optional()
+        .describe('Topaz face recovery. Used with operation="upscale" on Topaz precision/generative engines. Default: true — set false to keep faces exactly as in the source.'),
+      face_enhancement_strength: z.number().min(0).max(1).optional()
+        .describe('How strongly faces are recovered (0-1). Used with operation="upscale" (Topaz). Default: 0.8.'),
+      face_enhancement_creativity: z.number().min(0).max(1).optional()
+        .describe('How much new facial detail Topaz may invent (0-1; 0 = faithful). Used with operation="upscale". Default: 0.'),
+      subject_detection: z.enum(['All', 'Foreground', 'Background']).optional()
+        .describe('Which part Topaz enhances. Used with operation="upscale". Default: "All".'),
+      crop_to_fill: z.boolean().optional()
+        .describe('Crop to fill the target size instead of keeping the source framing. Used with operation="upscale" (Topaz). Default: false.'),
+      creativity: z.number().optional()
+        .describe('How much new detail is invented. operation="clarity_upscale": 0-1 (default 0.35). operation="upscale" with the Bloom (creative) engine: 1-9.'),
+      resemblance: z.number().min(0).max(1).optional()
+        .describe('How closely the result must match the source (0-1). Used with operation="clarity_upscale". Default: 0.6.'),
+
+      // ── background_replace / split / erase ─────────────────
+      background_reference_image: z.string().optional()
+        .describe('URL or absolute local path of an image to use as the new background. Used with operation="background_replace" (prompt still required).'),
+      negative_prompt: z.string().optional()
+        .describe('What must NOT appear. Used with operation="background_replace" and "clarity_upscale".'),
+      split_layout: z.string().optional()
+        .describe('Grid to split into: "auto" (detect), "2x2", "3x3" or "4x4". Used with operation="split" / "split_upscale". Default: "auto".'),
+      mask_expansion: z.number().min(0).max(100).optional()
+        .describe('Pixels to grow the erase mask so edges blend. Used with operation="erase". Default: 15.'),
 
       // ── inpaint / erase / face_swap / background_replace / zoom_out / camera_angle / magic_edit ──
       prompt: z.string().optional()
@@ -2427,10 +2509,14 @@ function registerGenerateTools(server, client, options = {}) {
       session_id: sessionIdField
     },
     async ({
-      image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
+      image_url, operation, model, scale, aspect_ratio, skin_strength, freckle_intensity, fix_lighting, prompt,
       mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize = false,
       zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
       enhancement_model, output_format,
+      horizontal_angle, vertical_angle, camera_zoom,
+      face_enhancement, face_enhancement_strength, face_enhancement_creativity,
+      subject_detection, crop_to_fill, creativity, resemblance,
+      background_reference_image, negative_prompt, split_layout, mask_expansion,
       project_id, session_id
     }) => {
       const editModelType = modelTypeForEditOperation('image', operation);
@@ -2454,23 +2540,37 @@ function registerGenerateTools(server, client, options = {}) {
       }
 
       // Local paths → CDN URLs (image_url / mask_image_url / additional_images).
-      [image_url, mask_image_url, additional_images] = await Promise.all([
+      [image_url, mask_image_url, additional_images, background_reference_image] = await Promise.all([
         rehostLocal(image_url, 'image', project_id),
         rehostLocal(mask_image_url, 'image', project_id),
         additional_images ? Promise.all(additional_images.map((s) => rehostLocal(s, 'image', project_id))) : additional_images,
+        rehostLocal(background_reference_image, 'image', project_id),
       ]);
       const gen = await client.post('/v1/edit/image', {
-        image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
+        image_url, operation, model, scale, aspect_ratio, skin_strength, freckle_intensity, fix_lighting, prompt,
         mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize,
         zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
         enhancement_model, output_format,
+        horizontal_angle, vertical_angle, camera_zoom,
+        face_enhancement, face_enhancement_strength, face_enhancement_creativity,
+        subject_detection, crop_to_fill, creativity, resemblance,
+        background_reference_image, negative_prompt, split_layout, mask_expansion,
         project_id, session_id
       });
+      const cardSettings = {
+        mode: operation, aspect_ratio, resolution,
+        details: editDetails(operation, {
+          scale, skin_strength, freckle_intensity, fix_lighting, generate_all_angles,
+          horizontal_angle, vertical_angle, camera_zoom, face_enhancement, face_enhancement_strength,
+          creativity, resemblance, zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
+          split_layout, background_reference_image, enhancement_model,
+        }),
+      };
 
       if (returnsImmediately()) return submittedResult({
         tool: 'edit_image', kind: 'image', gen, client, model,
-        prompt: prompt || operation,
-        settings: { mode: operation, aspect_ratio, scale, resolution },
+        prompt: prompt || '',
+        settings: cardSettings,
         reference_images: [image_url, mask_image_url, ...(additional_images || [])].filter(Boolean)
       });
 
@@ -2483,8 +2583,8 @@ function registerGenerateTools(server, client, options = {}) {
 
       return uiCompleted({
         tool: 'edit_image', kind: 'image', gen, client, model,
-        prompt: prompt || operation,
-        settings: { mode: operation, aspect_ratio, scale, resolution },
+        prompt: prompt || '',
+        settings: cardSettings,
         reference_images: [image_url, mask_image_url, ...(additional_images || [])].filter(Boolean),
         urls: result.result?.urls || [],
         credits_used: creditFields(result).credits_used,
@@ -2515,7 +2615,7 @@ function registerGenerateTools(server, client, options = {}) {
         'Edit operation:',
         '"draft_enhance" — render an owned saved draft at full quality in its original project. Pass `resolution` from the draft model capabilities; the server selects its finalization engine. No prompt or provider task ID is needed.',
         '"draft_quote" — check a saved draft’s supported final resolutions, expiry and exact credit cost without starting a render. Use this before draft_enhance.',
-        '"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.',
+        '"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. On model "bytedance-upscaler/upscale/video" (Bytedance Upscaler): `resolution` is "1080p" | "2k" | "4k" | "6k" | "8k" (OR `scale_ratio` 1.1-10, output ≤4K), plus `target_fps` (24-120), `enhancement_tier`, `enhancement_preset`, `fidelity`, `bit_depth` — see each field. Price = resolution tier (1080p 1 · 2k 2 · 4k 4 · 6k 8 · 8k 16 credits/s) × every started 30 fps (60 = 2×, 120 = 4×) × tier (fast 0.5×, pro 10×). Source-length caps: 6K 120s, 8K 60s, Pro 30s, otherwise 300s.',
         '"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.',
@@ -2535,12 +2635,25 @@ function registerGenerateTools(server, client, options = {}) {
       scale: z.number().optional()
         .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". Not used by "blackforestlabs/flux-video-upscale" — use `scale` instead.'),
+        .describe('Target resolution (e.g. "4k", "2k", "1080p"; Bytedance Upscaler also "6k", "8k"). 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".'),
+        .describe('Target frame rate (e.g. 24, 30, 60). Used with operation="upscale". Bytedance Upscaler: 24-120, default 30; price multiplies per started 30 fps.'),
       enhancement_model: z.string().optional()
         .describe('Topaz enhancement engine for operation="upscale" on model "topaz/upscale/video". Families: Precision (faithful — "Proteus", "Artemis High Quality", "Iris", "Dione TV", "Gaia CG", "Gaia 2"), Denoise ("Nyx", "Nyx Fast"), Generative (rebuilds detail that is not in the source — "Starlight Fast 2", "Starlight HQ", "Starlight Precise 2.6"), Creative ("Astra 2", always renders 4K). Generative and Creative engines cost several times the Precision rate. Omit for the default.'),
 
+      // Bytedance Upscaler ("bytedance-upscaler/upscale/video") controls. Validated, priced and
+      // duration-capped server-side (kolbo-api services/globalVideoEditing/bytedanceUpscale.js).
+      enhancement_tier: z.enum(['fast', 'standard', 'pro']).optional()
+        .describe('Bytedance Upscaler quality tier for operation="upscale". "fast" = half price, lighter enhancement; "standard" (default); "pro" = large-model restoration at 10× credits, source ≤30s, required for 10/12-bit.'),
+      enhancement_preset: z.enum(['general', 'ugc', 'short_series', 'aigc', 'old_film']).optional()
+        .describe('Bytedance Upscaler content type for operation="upscale": "general" (default), "ugc" (phone/social shorts), "short_series" (short dramas), "aigc" (AI-generated footage), "old_film" (classic film restoration). Same price for all.'),
+      fidelity: z.enum(['high', 'medium']).optional()
+        .describe('Bytedance Upscaler enhancement strength for operation="upscale": "high" (default, mild and source-faithful) or "medium" (stronger, balanced). Same price.'),
+      bit_depth: z.union([z.literal(8), z.literal(10), z.literal(12)]).optional()
+        .describe('Bytedance Upscaler output bit depth for operation="upscale": 8 (default), 10 or 12. 10/12 require enhancement_tier="pro" and are delivered as HEVC.'),
+      scale_ratio: z.number().min(1.1).max(10).optional()
+        .describe('Bytedance Upscaler custom scale (1.1-10) for operation="upscale", used INSTEAD of `resolution`. Output must stay within 4K; billed on the 1080p/2k/4k tier it lands in. For 6K/8K use `resolution`.'),
+
       // ── reframe ────────────────────────────────────────────
       aspect_ratio: z.string().optional()
         .describe(aspectRatioDescribe() + ' Required for operation="reframe".'),
@@ -2612,6 +2725,7 @@ function registerGenerateTools(server, client, options = {}) {
       video_url, operation, model, aspect_ratio, scale, prompt,
       image_url, audio_url, duration, mode,
       target_fps, resolution, enhancement_model,
+      enhancement_tier, enhancement_preset, fidelity, bit_depth, scale_ratio,
       grid_position_x, grid_position_y,
       sound_effect_prompt, background_music_prompt, original_sound, cfg_strength,
       audio_format, segments,
@@ -2645,6 +2759,7 @@ function registerGenerateTools(server, client, options = {}) {
         video_url, operation, model, aspect_ratio, scale, prompt, enhancement_model,
         image_url, audio_url, duration, mode,
         target_fps, resolution,
+        enhancement_tier, enhancement_preset, fidelity, bit_depth, scale_ratio,
         grid_position_x, grid_position_y,
         sound_effect_prompt, background_music_prompt, original_sound, cfg_strength,
         audio_format, segments,
@@ -2662,10 +2777,14 @@ function registerGenerateTools(server, client, options = {}) {
       };
 
       if (operation === 'draft_quote') return { content: [{ type: 'text', text: JSON.stringify(gen, null, 2) }] };
+      const cardSettings = {
+        mode: operation, duration, aspect_ratio, resolution,
+        details: editDetails(operation, { scale, enhancement_model, target_fps, mode, enhancement_tier, enhancement_preset, bit_depth, scale_ratio }),
+      };
       if (returnsImmediately()) return submittedResult({
         tool: 'edit_video', kind: 'video', gen, client, model,
-        prompt: prompt || operation,
-        settings: { mode: operation, duration, aspect_ratio, resolution },
+        prompt: prompt || '',
+        settings: cardSettings,
         ...editRefs
       });
 
@@ -2678,8 +2797,8 @@ function registerGenerateTools(server, client, options = {}) {
 
       return uiCompleted({
         tool: 'edit_video', kind: 'video', gen, client, model,
-        prompt: prompt || operation,
-        settings: { mode: operation, duration, aspect_ratio, resolution },
+        prompt: prompt || '',
+        settings: cardSettings,
         ...editRefs,
         urls: result.result?.urls || [],
         duration: result.result?.duration || null,