@kolbo/mcp 1.76.1 → 1.76.3

package/package.json

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

package/src/apps/theme.js

@@ -144,20 +144,31 @@ body {
 .k-skel.portrait { aspect-ratio: 3 / 4; }
 .k-skel::after {
   content: ''; position: absolute; inset: 0;
+  /* The shimmer covers the WHOLE cell and outlives the skeleton — .k-skel.done
+     only clears its paint, not its box. A pseudo-element hit-tests as its
+     originating element, so every click on a finished cell landed on the cell
+     instead of the media inside it: image cells still worked (their handler is
+     ON the cell), but a <video>'s native controls never saw a single event —
+     play, scrub, volume and fullscreen were all dead. It is decoration; it must
+     never take a click. */
+  pointer-events: none;
   background: linear-gradient(90deg, transparent 0%, rgba(255,255,255,0.06) 40%, rgba(255,255,255,0.10) 50%, rgba(255,255,255,0.06) 60%, transparent 100%);
   background-size: 200% 100%;
   animation: k-sweep 1.6s ease-in-out infinite;
 }
 @keyframes k-sweep { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }
 /* Batch grid: per-cell prompt caption + a cell that already finished */
-.k-skel-cap { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2;
+/* bottom: 0 puts this exactly where a <video> draws its control bar, so it has
+   to be click-through too — the caption is a label, not a target. The full text
+   stays reachable: the title tooltip moved onto the cell. */
+.k-skel-cap { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2; pointer-events: none;
   padding: 12px 8px 6px; font-size: 10.5px; color: #fff;
   background: linear-gradient(transparent, rgba(0, 0, 0, 0.65));
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .k-skel.done::after { animation: none; background: none; }
 .k-cell-fill { width: 100%; height: 100%; object-fit: contain; display: block; background: #000; }
 .k-gen-badge {
-  position: absolute; top: 10px; left: 10px; z-index: 2;
+  position: absolute; top: 10px; left: 10px; z-index: 2; pointer-events: none;
   display: inline-flex; align-items: center; gap: 6px;
   padding: 4px 10px; border-radius: 999px;
   background: rgba(0, 0, 0, 0.65); /* no backdrop-filter: nested blur over the

package/src/apps/widgets/generation.js

@@ -586,8 +586,12 @@ function fillBatchCell(sc, i, g) {
   cell.classList.add('done');
   var cap = (sc.prompts && sc.prompts[i])
     ? '<span class="k-skel-cap" title="' + esc(sc.prompts[i]) + '">' + esc(sc.prompts[i]) + '</span>' : '';
+  if (sc.prompts && sc.prompts[i]) cell.title = sc.prompts[i];
+  // The controls attribute is not optional here: this cell is a FINISHED result
+  // the user is meant to watch, and without it the tile was a muted poster with
+  // no way to play, seek or unmute until the whole batch finished and repainted.
   cell.innerHTML = (sc.kind === 'video'
-    ? '<video class="k-cell-fill" src="' + esc(u) + '"' + (r.thumbnail_url ? ' poster="' + esc(r.thumbnail_url) + '"' : '') + ' muted playsinline preload="metadata"></video>'
+    ? '<video class="k-cell-fill" src="' + esc(u) + '"' + (r.thumbnail_url ? ' poster="' + esc(r.thumbnail_url) + '"' : '') + ' controls playsinline preload="metadata"></video>'
     : '<img class="k-cell-fill" src="' + esc(u) + '" alt="">') + cap;
   window.kolbo.notifySize();
 }
@@ -767,7 +771,8 @@ function renderBatchGrid(sc) {
   var shape = items[0].type === 'video' ? 'video' : 'square';
   el('stage').innerHTML = '<div class="k-gen-grid n' + Math.min(items.length, 4) + '">' +
     items.map(function (it, i) {
-      return '<div class="k-skel done ' + shape + '" data-focus="' + i + '">' +
+      return '<div class="k-skel done ' + shape + '" data-focus="' + i + '"' +
+        (it.label ? ' title="' + esc(it.label) + '"' : '') + '>' +
         (it.type === 'video'
           ? '<video class="k-cell-fill" src="' + esc(it.url) + '" controls playsinline preload="metadata"></video>'
           : '<img class="k-cell-fill" src="' + esc(it.url) + '" alt="" loading="lazy" style="cursor:zoom-in">') +
@@ -803,7 +808,8 @@ function renderStatusGrid(sc) {
         // file — the tool only knows a url came back, not what kind it is.
         it.kind = refKind(it.url, 'image');
         var shape = it.kind === 'video' ? 'video' : 'square';
-        return '<div class="k-skel done ' + shape + '" data-focus="' + i + '">' +
+        return '<div class="k-skel done ' + shape + '" data-focus="' + i + '"' +
+          (it.title ? ' title="' + esc(it.title) + '"' : '') + '>' +
           (it.kind === 'video'
             ? '<video class="k-cell-fill" src="' + esc(it.url) + '" controls playsinline preload="metadata"></video>'
             : it.kind === 'audio'

package/src/tools/_shared.js

@@ -639,7 +639,11 @@ async function uiCompleted(p, textPayload, extraContent) {
     ...chip,
     prompt: p.prompt,
     count: p.count || 1,
-    settings: p.settings || {},
+    // Omitted entirely when the caller has none. A live generation card merges
+    // an incoming status payload over its own state, so an empty-but-present
+    // `settings` wiped the resolution / aspect / DNA chips off the finished
+    // card. Every reader already does `sc.settings || {}`.
+    ...(p.settings ? { 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)

package/src/tools/generate.js

@@ -119,6 +119,22 @@ function mediaKind(url) {
   return 'image';
 }
 
+const isUrlSource = (source) => typeof source === 'string' && /^https?:\/\//i.test(source);
+
+// Which multipart kind a LOCAL file should upload as. mediaKind answers for the
+// card; the upload routes only know these three, and the kind decides the
+// content type a receiving controller dispatches on (kolbo-api's elements
+// controller buckets req.files by `file.mimetype`), so guessing 'image' for
+// everything filed a local .mp4 as a reference image.
+const uploadKind = (source) => {
+  const kind = mediaKind(source);
+  return kind === 'video' || kind === 'audio' ? kind : 'image';
+};
+
+// The elements route's own multer ceiling (kolbo-api sdk/index.js). Cap here so
+// an oversized file fails with a readable message instead of after the upload.
+const ELEMENTS_MAX_UPLOAD_BYTES = 200 * 1024 * 1024;
+
 // ─── Widget settings block ──────────────────────────────────────────────────
 // What the CALLER actually asked for, for the generation card AND for the model
 // reading the tool result. Undefined/false keys are dropped by JSON.stringify, so
@@ -1044,7 +1060,6 @@ function registerGenerateTools(server, client, options = {}) {
           // generation, so 'Generations' here overwrote the real model name on
           // the finished card the moment the live widget merged this payload in.
           model: res.model || 'Generations', gen: { generation_id: single.generation_id },
-          settings: {},
           state: single.state,
           urls: done ? urls : undefined,
           thumbnail_url: res.thumbnail_url,
@@ -1166,11 +1181,11 @@ function registerGenerateTools(server, client, options = {}) {
     {
       prompt: z.string().describe('Locked Intro prompt (Seedance/Elements): Total line, [GLOBAL LOOK], [CAST] with @ExactDNAName for every visual_dna_ids entry, [LOCATION], then SHOT N. Not SCENE CONTEXT/OPTICS/ACTION packs. Never substitute "the left man" or "Zohar\'s" for @Name.'),
       model: z.string().optional().describe('Model identifier. If the user already named a family (Grok / Kling / Veo / Seedance / …), pass THAT family — never default to Seedance because Elements often uses it. Use list_models type="elements" for exact ids and elements_max_* caps. Do NOT omit (omitting = Smart Select).'),
-      reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
-      reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs. **Cap: pass at most `elements_max_videos` URLs from list_models — if the cap is 0 the model rejects videos.**'),
-      reference_audio_urls: z.array(z.string()).optional().describe('Array of reference audio URLs for models that accept audio inputs. **Cap: pass at most `elements_max_audio` URLs from list_models.** `audio_url` remains supported as the legacy single-track form.'),
-      audio_url: z.string().optional().describe('URL of a reference audio track. **Audio constraints: `elements_max_audio` from list_models gates whether audio is accepted at all; audio duration must fall within `min_audio_duration`-`max_audio_duration`; format must be in `supported_audio_formats` (if specified).**'),
-      files: z.array(z.string()).optional().describe('Array of URLs or absolute local paths — alternative to reference_images. Use this when you have local files to upload. Each item can be a URL OR a local path. **Total count across files + reference_images still capped by `elements_max_images`.**'),
+      reference_images: z.array(z.string()).optional().describe('Array of image references (product shots, character references, etc.). Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
+      reference_videos: z.array(z.string()).optional().describe('Array of reference videos for models that accept video inputs. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_videos` URLs from list_models — if the cap is 0 the model rejects videos.**'),
+      reference_audio_urls: z.array(z.string()).optional().describe('Array of reference audio tracks for models that accept audio inputs. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_audio` URLs from list_models.** `audio_url` remains supported as the legacy single-track form.'),
+      audio_url: z.string().optional().describe('A single reference audio track — legacy form of reference_audio_urls. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Audio constraints: `elements_max_audio` from list_models gates whether audio is accepted at all; audio duration must fall within `min_audio_duration`-`max_audio_duration`; format must be in `supported_audio_formats` (if specified).**'),
+      files: z.array(z.string()).optional().describe('Untyped catch-all for mixed media — images, videos AND audio, each a URL or an absolute local path. The kind is detected from the file extension and the item is routed to the matching reference list, so a local .mp4 is sent as a video and a local .mp3 as audio. Prefer the typed lists (reference_images / reference_videos / reference_audio_urls) when you already know the kind; they accept local paths too. URLs given here are forwarded as URLs, never re-uploaded. **Caps still apply per kind: `elements_max_images` / `elements_max_videos` / `elements_max_audio` from list_models. Local uploads are capped at 200MB each.**'),
       duration: z.number().optional().describe('Output duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in `supported_aspect_ratios` from list_models. Default: "16:9"'),
       motion: z.string().optional().describe('Motion style / intensity hint (optional)'),
@@ -1193,40 +1208,105 @@ function registerGenerateTools(server, client, options = {}) {
       model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt) throw new Error('prompt is required');
 
-      let startResponse;
-      if (files && files.length > 0) {
-        // Multipart mode: resolve each file source to a buffer and upload.
-        const resolved = await Promise.all(files.map(src => resolveToBuffer(src, 'image')));
+      // Elements is the one tool that takes all three modalities, and either a
+      // URL or a local path for any of them. Bucket every input by the kind the
+      // API expects, then split by transport:
+      //   URL   → forwarded AS a url. Downloading one only to re-upload it
+      //           costs the round-trip, risks the 200MB multer ceiling, and
+      //           duplicates an asset that already lives on the CDN. `files`
+      //           used to do exactly that to every URL handed to it.
+      //   local → the only thing that becomes a multipart part, uploaded under
+      //           its real kind. `files` forced 'image' on everything, so a
+      //           local .mp4/.mp3 arrived with the wrong content type and the
+      //           elements controller — which buckets req.files by mimetype —
+      //           never saw it as video or audio.
+      const media = { image: [], video: [], audio: [] };
+      const collect = (list, forced) => {
+        for (const src of Array.isArray(list) ? list : (list ? [list] : [])) {
+          if (typeof src !== 'string' || !src.trim()) continue;
+          // The typed lists declare their own kind; `files` is the untyped
+          // catch-all, so it is classified by extension.
+          const bucket = media[forced || uploadKind(src)];
+          if (!bucket.includes(src)) bucket.push(src);
+        }
+      };
+      collect(reference_images, 'image');
+      collect(reference_videos, 'video');
+      collect(reference_audio_urls, 'audio');
+      collect(audio_url, 'audio'); // legacy single-track form; the API merges it into audioUrls anyway
+      collect(files);
+
+      const urlsOf = (kind) => media[kind].filter(isUrlSource);
+      const locals = ['image', 'video', 'audio']
+        .flatMap((kind) => media[kind].filter((src) => !isUrlSource(src)).map((src) => ({ src, kind })));
+      const some = (list) => (list.length ? list : undefined);
+      const body = {
+        prompt, model,
+        reference_images: some(urlsOf('image')),
+        reference_videos: some(urlsOf('video')),
+        reference_audio_urls: some(urlsOf('audio')),
+        duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids,
+        resolution, sound_enabled, keyframes, multi_shots, multi_shot_count,
+        session_name, project_id, session_id
+      };
+
+      const startElements = async () => {
+        if (!locals.length) {
+          return client.post('/v1/generate/elements', body);
+        }
+        const resolved = await Promise.all(locals.map(({ src, kind }) =>
+          resolveToBuffer(src, kind, { maxBytes: ELEMENTS_MAX_UPLOAD_BYTES })));
         const form = new FormData();
-        form.append('prompt', prompt);
-        if (model) form.append('model', model);
-        if (duration !== undefined) form.append('duration', String(duration));
-        if (aspect_ratio) form.append('aspect_ratio', aspect_ratio);
-        if (motion) form.append('motion', motion);
-        if (preset_id) form.append('preset_id', preset_id);
-        if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
-        if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
-        if (reference_images) form.append('reference_images', JSON.stringify(reference_images));
-        if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
-        if (reference_audio_urls) form.append('reference_audio_urls', JSON.stringify(reference_audio_urls));
-        if (audio_url) form.append('audio_url', audio_url);
-        if (resolution) form.append('resolution', resolution);
-        if (sound_enabled !== undefined) form.append('sound_enabled', String(sound_enabled));
-        if (keyframes) form.append('keyframes', JSON.stringify(keyframes));
-        if (multi_shots !== undefined) form.append('multi_shots', String(multi_shots));
-        if (multi_shot_count !== undefined) form.append('multi_shot_count', String(multi_shot_count));
-        if (session_name) form.append('session_name', session_name);
-        if (project_id) form.append('project_id', project_id);
-        if (session_id) form.append('session_id', session_id);
+        for (const [key, value] of Object.entries(body)) {
+          if (value === undefined || value === null) continue;
+          // The two URL lists are read by DIFFERENT parsers on the API side and
+          // only one shape satisfies both. reference_videos/_audio_urls go
+          // through parseJsonArray, which needs a JSON string (a bare url makes
+          // JSON.parse throw and the list is dropped). reference_images goes
+          // through collectHttpMediaUrls, which walks strings and arrays but
+          // never JSON-decodes — so a stringified array fails its
+          // `^https?://` test and every URL reference is silently lost. Repeated
+          // form fields arrive as a string (one) or an array (several), and that
+          // walker handles both.
+          if (key === 'reference_images') {
+            for (const url of value) form.append('reference_images', url);
+            continue;
+          }
+          form.append(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+        }
         for (const f of resolved) {
           form.append('files', f.buffer, { filename: f.filename, contentType: f.contentType });
         }
-        startResponse = await client.postMultipart('/v1/generate/elements', form);
-      } else {
-        // URL-only mode: plain JSON.
-        startResponse = await client.post('/v1/generate/elements', {
-          prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, sound_enabled, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id
-        });
+        return client.postMultipart('/v1/generate/elements', form);
+      };
+
+      let startResponse;
+      try {
+        startResponse = await startElements();
+      } catch (err) {
+        // The elements trust gate only accepts remote references that are BOTH
+        // Kolbo-hosted AND registered to this caller's library/project — any
+        // other public URL 400s with this code, even though every schema here
+        // says "public URL, forwarded as-is". Agents used to recover by hand
+        // (upload_media, then resend). Do that detour for them: rehost every
+        // remote reference into the caller's library and retry ONCE. The gate
+        // fires before any charge, so the failed first attempt costs nothing.
+        if (err?.code !== 'UNTRUSTED_REFERENCE_MEDIA_URL') throw err;
+        for (const kind of ['image', 'video', 'audio']) {
+          media[kind] = await Promise.all(media[kind].map(async (src) => {
+            if (!isUrlSource(src)) return src;
+            const file = await resolveToBuffer(src, kind, { maxBytes: ELEMENTS_MAX_UPLOAD_BYTES });
+            const form = new FormData();
+            form.append('file', file.buffer, { filename: file.filename, contentType: file.contentType });
+            if (project_id) form.append('project_id', project_id);
+            const uploaded = await client.postMultipart('/v1/media/upload', form);
+            return uploaded?.media?.url || uploaded?.url || src;
+          }));
+        }
+        body.reference_images = some(urlsOf('image'));
+        body.reference_videos = some(urlsOf('video'));
+        body.reference_audio_urls = some(urlsOf('audio'));
+        startResponse = await startElements();
       }
 
       if (ui()) return uiGenerating({
@@ -1237,16 +1317,11 @@ function registerGenerateTools(server, client, options = {}) {
           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))
-        ],
-        // 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] : [])]
+        // Already bucketed and deduped above, so a URL handed to `files`
+        // renders under its real kind instead of being dropped or double-listed.
+        reference_images: [...urlsOf('image'), ...(keyframes || []).map((keyframe) => keyframe.image_url)],
+        reference_videos: urlsOf('video'),
+        reference_audio: urlsOf('audio')
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1264,13 +1339,9 @@ function registerGenerateTools(server, client, options = {}) {
           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] : [])],
+        reference_images: [...urlsOf('image'), ...(keyframes || []).map((keyframe) => keyframe.image_url)],
+        reference_videos: urlsOf('video'),
+        reference_audio: urlsOf('audio'),
         urls: result.result?.urls || [],
         thumbnail_url: result.result?.thumbnail_url || null,
         duration: result.result?.duration || null,
@@ -1289,12 +1360,12 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_first_last_frame ─────────────────────────────
   server.tool(
     'generate_first_last_frame',
-    'Generate a video that morphs / interpolates from a FIRST frame to a LAST frame. Provide the two frames as URLs (first_frame_url + last_frame_url) OR as local file paths (first_frame + last_frame). Optional prompt describes the desired motion/transition. Do NOT mix URL and file inputs. Returns the final video URL when complete.',
+    'Generate a video that morphs / interpolates from a FIRST frame to a LAST frame. Provide the two frames as URLs (first_frame_url + last_frame_url) or as URLs/absolute local paths (first_frame + last_frame) — the pairs are interchangeable and may be mixed. Optional prompt describes the desired motion/transition. Returns the final video URL when complete.',
     {
-      first_frame_url: z.string().optional().describe('Public URL of the first frame image (URL mode)'),
-      last_frame_url: z.string().optional().describe('Public URL of the last frame image (URL mode)'),
-      first_frame: z.string().optional().describe('URL or absolute local path to the first frame (file mode — alternative to first_frame_url)'),
-      last_frame: z.string().optional().describe('URL or absolute local path to the last frame (file mode — alternative to last_frame_url)'),
+      first_frame_url: z.string().optional().describe('Public URL of the first frame image. Interchangeable with first_frame.'),
+      last_frame_url: z.string().optional().describe('Public URL of the last frame image. Interchangeable with last_frame.'),
+      first_frame: z.string().optional().describe('URL or absolute local path to the first frame — alternative to first_frame_url. A URL here is forwarded as a URL, not re-uploaded.'),
+      last_frame: z.string().optional().describe('URL or absolute local path to the last frame — alternative to last_frame_url. A URL here is forwarded as a URL, not re-uploaded.'),
       prompt: z.string().optional().describe('Optional description of the desired motion between the two frames (e.g. "smooth camera dolly in")'),
       model: z.string().optional().describe('Model identifier. Use list_models type="firstlastgenerations" to see options. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
@@ -1308,20 +1379,24 @@ function registerGenerateTools(server, client, options = {}) {
     },
     async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'firstlastgenerations'); // lenient id resolution ("z-image" → "z-image/turbo")
-      const urlMode = first_frame_url && last_frame_url;
-      const fileMode = first_frame && last_frame;
-      if (!urlMode && !fileMode) {
-        throw new Error('Provide either both first_frame_url + last_frame_url OR both first_frame + last_frame (URL/local path).');
-      }
-      if (urlMode && fileMode) {
-        throw new Error('Do not mix URL and file inputs. Provide either URLs OR file sources, not both.');
+      // One frame per position, whichever arg carried it. The two arg pairs were
+      // treated as two exclusive MODES, so a URL handed to first_frame/last_frame
+      // (which their own descriptions invite) took the multipart path and got
+      // downloaded and re-uploaded — a pointless round-trip that also had to fit
+      // the route's 10MB upload ceiling a plain URL never touches. Transport is
+      // now decided per frame by what the value IS, not which arg it arrived in,
+      // which also makes one-URL-one-local work instead of erroring out.
+      const firstSource = first_frame_url || first_frame;
+      const lastSource = last_frame_url || last_frame;
+      if (!firstSource || !lastSource) {
+        throw new Error('Provide both frames: first_frame_url + last_frame_url (URLs) or first_frame + last_frame (URL or absolute local path).');
       }
 
       let startResponse;
-      if (fileMode) {
+      if (!isUrlSource(firstSource) || !isUrlSource(lastSource)) {
         const [firstResolved, lastResolved] = await Promise.all([
-          resolveToBuffer(first_frame, 'image'),
-          resolveToBuffer(last_frame, 'image')
+          resolveToBuffer(firstSource, 'image'),
+          resolveToBuffer(lastSource, 'image')
         ]);
         const form = new FormData();
         form.append('files', firstResolved.buffer, { filename: firstResolved.filename, contentType: firstResolved.contentType });
@@ -1339,15 +1414,15 @@ function registerGenerateTools(server, client, options = {}) {
         startResponse = await client.postMultipart('/v1/generate/first-last-frame', form);
       } else {
         startResponse = await client.post('/v1/generate/first-last-frame', {
-          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution, sound_enabled, project_id, session_id
+          first_frame_url: firstSource, last_frame_url: lastSource,
+          prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution, sound_enabled, project_id, session_id
         });
       }
 
       if (ui()) return uiGenerating({
         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 || ''))
+        reference_images: [firstSource, lastSource].filter(isUrlSource)
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1360,8 +1435,7 @@ function registerGenerateTools(server, client, options = {}) {
       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 || '')),
+        reference_images: [firstSource, lastSource].filter(isUrlSource),
         urls: result.result?.urls || [],
         thumbnail_url: result.result?.thumbnail_url || null,
         duration: result.result?.duration || null,
@@ -1531,10 +1605,18 @@ function registerGenerateTools(server, client, options = {}) {
           highlighted: z.object({ font: z.string().optional(), weight: z.number().int().min(100).max(900).optional(), color: z.string().optional() }).optional().describe('Highlighted word tier styling.'),
         }).optional(),
       }).optional().describe('VEED Subtitles only: style overrides. Any omitted field keeps the preset default. Best supported by Basic presets.'),
+      enhancement_model: z.string().optional()
+        .describe('Topaz Slow Motion only (model "topaz/interpolate/video"): retiming engine — "Apollo" (smooth motion, default), "Chronos" (complex motion and occlusion), or "Aion" (highest quality for extreme slow motion, and the most expensive).'),
+      target_fps: z.number().optional()
+        .describe('Topaz Slow Motion only: frames per second of the OUTPUT (16-120, default 60). Higher rates generate more frames and cost proportionally more.'),
+      slowdown_factor: z.number().optional()
+        .describe('Topaz Slow Motion only: how many times longer the output runs (1-8, default 1). 4 turns a 5s clip into 20s of slow motion. Billing is on the OUTPUT length, so an 8x pass costs 8x a 1x pass.'),
+      output_format: z.string().optional()
+        .describe('Topaz HDR only (model "topaz/sdr-to-hdr/video"): "mp4" for 10-bit H.265 HDR10 (default) or "prores" for 10-bit ProRes 422 HQ. Both are HDR masters — the in-app player shows a tone-mapped SDR preview and the HDR file is the download.'),
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, project_id, session_id }) => {
+    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, enhancement_model, target_fps, slowdown_factor, output_format, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'video_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source_video) throw new Error('source_video is required');
 
@@ -1544,7 +1626,9 @@ function registerGenerateTools(server, client, options = {}) {
         startResponse = await client.post('/v1/generate/video-from-video', {
           video_url: source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled,
           reference_images, reference_videos, elements, preset, source_language, translation_language,
-          srt_content, srt_file_url, vocabulary, customization, project_id, session_id
+          srt_content, srt_file_url, vocabulary, customization,
+          enhancement_model, target_fps, slowdown_factor, output_format,
+          project_id, session_id
         });
       } else {
         const resolved = await resolveToBuffer(source_video, 'video');
@@ -1568,6 +1652,10 @@ function registerGenerateTools(server, client, options = {}) {
         if (reference_images) form.append('reference_images', JSON.stringify(reference_images));
         if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
         if (elements) form.append('elements', JSON.stringify(elements));
+        if (enhancement_model) form.append('enhancement_model', enhancement_model);
+        if (target_fps !== undefined) form.append('target_fps', String(target_fps));
+        if (slowdown_factor !== undefined) form.append('slowdown_factor', String(slowdown_factor));
+        if (output_format) form.append('output_format', output_format);
         if (project_id) form.append('project_id', project_id);
         if (session_id) form.append('session_id', session_id);
         startResponse = await client.postMultipart('/v1/generate/video-from-video', form);
@@ -1777,7 +1865,8 @@ function registerGenerateTools(server, client, options = {}) {
         'camera_angle',
         'split', 'split_upscale',
         'multi_shot',
-        'magic_edit'
+        'magic_edit',
+        'enhance'
       ]).describe([
         'Edit operation:',
         '"upscale" — increase resolution by 2×, 3×, or 4× (use `scale`). "clarity_upscale" — AI-powered clarity upscale with detail enhancement (use `resolution`).',
@@ -1786,6 +1875,7 @@ function registerGenerateTools(server, client, options = {}) {
         '"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" — 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).',
@@ -1800,7 +1890,13 @@ function registerGenerateTools(server, client, options = {}) {
 
       // ── upscale ────────────────────────────────────────────
       scale: z.number().optional()
-        .describe('Upscale factor: 2, 3, or 4. Used with operation="upscale". Default: 2.'),
+        .describe('Upscale factor: 1, 2, 4 or 8. Used with operation="upscale". Default: 2.'),
+
+      enhancement_model: z.string().optional()
+        .describe('Topaz engine. With operation="upscale" on model "topaz/upscale/image" it selects the engine family: "Standard V2" / "High Fidelity V3" / "CGI" / "Text Refine" (faithful), "Wonder 3.5" (rebuilds natural detail), "Bloom 2" (reinvents detail — most expensive), "Transparent" (keeps the alpha channel). With operation="enhance" it selects the correction engine for the chosen model. Omit for the model default. Call list_models to see the engines a model offers.'),
+
+      output_format: z.string().optional()
+        .describe('Output image format: "jpeg" or "png". Used with Topaz "upscale" and "enhance". Defaults to jpeg (the transparent upscaler always returns png).'),
 
       resolution: z.string().optional()
         .describe('Target output resolution (e.g. "4k", "2k", "1080p"). Used with "clarity_upscale", "split_upscale", "multi_shot".'),
@@ -1857,6 +1953,7 @@ function registerGenerateTools(server, client, options = {}) {
       image_url, operation, model, scale, aspect_ratio, skin_strength, 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,
       project_id, session_id
     }) => {
       // No `type` argument: these are operation-routed tools (upscale / reframe /
@@ -1866,6 +1963,9 @@ function registerGenerateTools(server, client, options = {}) {
 
       // Basic validation
       if (operation === 'reframe' && !aspect_ratio) throw new Error('aspect_ratio is required for reframe');
+      if (operation === 'enhance' && !model) {
+        throw new Error('model is required for enhance — pick one of: topaz/adjust/image, topaz/sharpen/image, topaz/denoise/image, topaz/restore/image');
+      }
       if (operation === 'background_replace' && !prompt) throw new Error('prompt is required for background_replace');
       if (operation === 'face_swap' && !mask_image_url && !(additional_images && additional_images.length > 0)) {
         throw new Error('mask_image_url (face reference) is required for face_swap');
@@ -1875,6 +1975,7 @@ function registerGenerateTools(server, client, options = {}) {
         image_url, operation, model, scale, aspect_ratio, skin_strength, 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,
         project_id, session_id
       });
 
@@ -1947,6 +2048,8 @@ function registerGenerateTools(server, client, options = {}) {
         .describe('Target resolution (e.g. "4k", "2k", "1080p"). Used with "upscale" and "reframe".'),
       target_fps: z.number().optional()
         .describe('Target frame rate (e.g. 24, 30, 60). Used with operation="upscale".'),
+      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.'),
 
       // ── reframe ────────────────────────────────────────────
       aspect_ratio: z.string().optional()
@@ -2010,7 +2113,7 @@ function registerGenerateTools(server, client, options = {}) {
     async ({
       video_url, operation, model, aspect_ratio, scale, prompt,
       image_url, audio_url, duration, mode,
-      target_fps, resolution,
+      target_fps, resolution, enhancement_model,
       grid_position_x, grid_position_y,
       sound_effect_prompt, background_music_prompt, original_sound, cfg_strength,
       refine_edges, subject_is_person,
@@ -2033,7 +2136,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (operation === 'extend'        && !duration)    throw new Error('duration is required for extend');
 
       const gen = await client.post('/v1/edit/video', {
-        video_url, operation, model, aspect_ratio, scale, prompt,
+        video_url, operation, model, aspect_ratio, scale, prompt, enhancement_model,
         image_url, audio_url, duration, mode,
         target_fps, resolution,
         grid_position_x, grid_position_y,