@kolbo/mcp 1.63.0 → 1.65.1

package/package.json

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

package/skill/SKILL.md

@@ -99,7 +99,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_video` | Text-to-video. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
-| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** |
+| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Supports `multi_shots` / `multi_shot_count` (badge/metadata/native flag only — never rewrites the prompt) and short `session_name`. Crafted demos: `enhance_prompt:false` + put shot structure in the prompt. |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
 | `generate_lipsync` | Lipsync audio to an image or video face. |
 | `generate_music` | Music generation (Suno + variants). |

package/skill/references/models/seedance.md

@@ -9,6 +9,8 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 **Kolbo MCP routing:** Seedance is a video model — call `generate_video` (text-to-video) or `generate_elements` (when video references / Visual DNA / first-last frames are involved). Run `list_models({ type: "text_to_video" })` and pick a Seedance variant by name.
 
+**Multishot (Elements):** Seedance has **no** native provider Multishot switch. Pass `multi_shots: true` on `generate_elements` (optional `multi_shot_count`) for the UI Multishot badge only — it does **not** rewrite or reshape your prompt. **Always send `enhance_prompt: false` for crafted demos** (MCP default) so the prompt stays RAW. Put shot structure in the prompt yourself (`Multishot ON`, `Total: … / N shots`, numbered shots). Optional `session_name` sets a short sidebar title (skips AI auto-name from boilerplate).
+
 ## Universal Rules (apply to EVERY Seedance prompt)
 
 - **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too. For connected narrative sequences the proven phrasing is `N connected cinematic shots, 15 seconds total, 16:9, Multishot ON` — use it and keep `Multishot ON` for any multi-shot story.

package/skill/references/workflows/marketing-studio.md

@@ -123,7 +123,7 @@ If the user gives a **product URL** instead of a photo, see `workflows/research-
 
 ## Multi-Slot Board Method (structured shot specs + character consistency)
 
-For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. This is a prompt-only convention — no special MCP mode; it uses `generate_image` (board) + `generate_elements` / `generate_video_from_image` (per-slot animate) that already exist.
+For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. Prefer `generate_elements` with `multi_shots: true` (and a short `session_name`) when animating a single multi-cut Seedance spot; board-first still uses `generate_image` + `generate_elements` / `generate_video_from_image` per slot when you need separate clips.
 
 ### 1. Structured input slots
 

package/src/apps/widgets/generation.js

@@ -293,7 +293,8 @@ function releaseSeen() {
 function schedulePoll(sc) {
   if (cancelRequested) return;
   if (!seen) { whenSeenFns.push(function () { schedulePoll(sc); }); return; }
-  // The call itself long-waits server-side (normally up to three minutes).
+  // The call itself long-waits server-side, for one transport-safe window
+  // (~45s over the remote connector — see WAIT_WINDOW_MS in tools/generate.js).
   // This short pause only separates successive wait windows — the FIRST call
   // goes out immediately, so a card revealed by scrolling resolves at once.
   var delay = pollStart ? 1500 : 0;

package/src/polling.js

@@ -100,12 +100,71 @@ async function pollUntilDone(client, generationId, options = {}) {
     }
 
     // Still running: put a byte on the wire before going quiet again, so no
-    // intermediary mistakes a 3-minute wait for a dead connection.
+    // intermediary mistakes a long wait for a dead connection.
     await progress.tick();
 
-    // Wait before next poll
-    await new Promise(resolve => setTimeout(resolve, interval));
+    // Wait before next poll — but never past the deadline. The check at the top
+    // of the loop only runs BETWEEN sleeps, so an unclamped sleep let the call
+    // overshoot `timeout` by up to a full interval (a 45s window with a 15s
+    // cadence could return at 60s). That is the difference between landing
+    // inside the caller's transport window and blowing straight through it.
+    const remaining = timeout - (Date.now() - startTime);
+    await new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(interval, remaining))));
   }
 }
 
-module.exports = { pollUntilDone, PollingTimeoutError, GenerationFailedError };
+// ─── Blocking-wait window for the STATUS tools ──────────────────────────────
+// How long get_generation_status / get_creative_director_status may block
+// inside ONE tool call before handing back a non-terminal result the caller
+// re-issues. This is NOT the generation's lifetime — the job keeps running
+// server-side either way.
+//
+// It used to be a flat 180s, which over the remote HTTP connector no caller
+// could ever reach: there the whole tool call has to fit inside a single
+// POST /mcp response, and every hop in front of us has a shorter fuse.
+//
+//   • MCP client request timeout — 60s (SDK DEFAULT_REQUEST_TIMEOUT_MSEC), and
+//     it only resets on a progress notification when the client opted into
+//     resetTimeoutOnProgress, whose SDK default is false. We cannot make that
+//     choice on the host's behalf, so this is the ceiling we must respect.
+//   • Cloudflare origin read — 100s. api.kolbo.ai is Cloudflare-proxied.
+//   • kolbo-api httpServer.timeout — 120s. Measured against the production
+//     settings: a SILENT stream is RST at exactly 120.0s, while a 15s write
+//     cadence survives 200s. So progress.tick() does defeat this hop — but no
+//     amount of ticking defeats a client timeout that does not reset.
+//
+// Net effect of the old 180s: a 185s music generation made wait=true fail with
+// "the connector's server isn't responding" every single time, on a perfectly
+// healthy paid generation. Returning early with state:"processing" is strictly
+// better than erroring — the caller re-issues and nothing is lost.
+//
+// stdio hosts have no hop in between and do reset on our ticks, so they keep
+// the long window. KOLBO_MCP_WAIT_MS overrides both without a release, if a
+// host ever proves tighter still.
+const TRANSPORT_CEILING_MS = 60000;
+// Headroom for everything that happens AFTER the last poll and before the
+// response is on the wire: the final status read, addDisplayNames' catalog
+// lookups, JSON serialization.
+const RESULT_ASSEMBLY_BUDGET_MS = 10000;
+const REMOTE_WAIT_MS = 45000;
+const STDIO_WAIT_MS = 180000;
+
+/**
+ * @param {object} [options] tool options; `apps === true` is the remote-HTTP
+ *   transport signal (set only by kolbo-api's connector).
+ */
+function waitWindowMs(options = {}) {
+  const override = Number(process.env.KOLBO_MCP_WAIT_MS);
+  if (Number.isFinite(override) && override > 0) return override;
+  return options.apps === true ? REMOTE_WAIT_MS : STDIO_WAIT_MS;
+}
+
+module.exports = {
+  pollUntilDone,
+  PollingTimeoutError,
+  GenerationFailedError,
+  waitWindowMs,
+  TRANSPORT_CEILING_MS,
+  RESULT_ASSEMBLY_BUDGET_MS,
+  REMOTE_WAIT_MS,
+};

package/src/tools/generate.js

@@ -5,7 +5,7 @@
 
 const { z } = require('zod');
 const FormData = require('form-data');
-const { pollUntilDone } = require('../polling');
+const { pollUntilDone, waitWindowMs } = require('../polling');
 const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, sessionIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo } = require('../apps');
 
@@ -126,6 +126,18 @@ function registerGenerateTools(server, client, options = {}) {
   // "submitted" response + a live ui://kolbo/generation.html widget that keeps
   // one wait=true status call in flight. Text-only hosts never take this branch.
   const ui = () => appsEnabled(server, options);
+
+  // How long the STATUS tools may block inside one tool call before handing
+  // back a non-terminal result the caller re-issues. Bounded by the transport,
+  // not by the generation — full reasoning and the measured numbers live next
+  // to the constants in ../polling.js.
+  const WAIT_WINDOW_MS = waitWindowMs(options);
+  const WAIT_WINDOW_S = Math.round(WAIT_WINDOW_MS / 1000);
+  // What to tell a caller holding a still-running generation. Never "don't call
+  // again" — for anything longer than the window, calling again IS the protocol.
+  const stillRunningHint = (idsPhrase) =>
+    `Still running — this is NOT a failure and no credits were lost. Each wait=true call blocks for at most ~${WAIT_WINDOW_S}s and then returns whatever the state is, so a long job (music ~3 min, video can be longer) legitimately needs SEVERAL wait=true calls in a row. Call get_generation_status again with wait=true${idsPhrase}. Do not spin with wait=false, and do not re-run the generation tool.`;
+
   // ─── generate_image ────────────────────────────────────────
   server.tool(
     'generate_image',
@@ -367,10 +379,10 @@ function registerGenerateTools(server, client, options = {}) {
   // blocking poll window) needs this tool to be re-checked until done.
   server.tool(
     'get_creative_director_status',
-    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block for up to ~3 minutes instead of repeatedly calling this tool. Prefer this over the generic get_generation_status for Creative Director ids — the generic tool now returns the same scene data (it delegates here), but this one is the direct route.',
+    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block until the batch is terminal or the wait window closes, whichever comes first — a batch longer than one window returns state="processing" and you simply call again with wait=true. Prefer this over the generic get_generation_status for Creative Director ids — the generic tool now returns the same scene data (it delegates here), but this one is the direct route.',
     {
       generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.'),
-      wait: z.boolean().optional().describe('If true, block until the batch is terminal, up to ~3 minutes. Use this instead of repeatedly checking in a loop.')
+      wait: z.boolean().optional().describe(`If true, block until the batch is terminal, for at most ~${WAIT_WINDOW_S}s per call. A batch that outlives one window comes back state="processing" (not an error) — call again with wait=true until it is terminal. Always prefer this over polling with wait=false.`)
     },
     async ({ generation_id, wait }) => {
       const statusUrl = `/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`;
@@ -379,7 +391,7 @@ function registerGenerateTools(server, client, options = {}) {
         try {
           status = await pollUntilDone(client, generation_id, {
             interval: 15000,
-            timeout: 180000,
+            timeout: WAIT_WINDOW_MS,
             statusUrl
           });
         } catch (err) {
@@ -409,7 +421,7 @@ function registerGenerateTools(server, client, options = {}) {
         completed_scenes: completed,
         _hint: status.state === 'completed'
           ? 'All scenes terminal. Every completed scene\'s image_urls/video_urls are final.'
-          : 'Still running. Call get_creative_director_status once with wait=true; do not poll it in a loop.'
+          : `Still running — not a failure. Each wait=true call blocks for at most ~${WAIT_WINDOW_S}s, and a video batch routinely outlasts several windows, so call get_creative_director_status again with wait=true and keep going until state is terminal. Scenes that already carry image_urls/video_urls are done; never re-run generate_creative_director.`
       }, null, 2) }] };
     }
   );
@@ -817,11 +829,11 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
-    'Check the status of one or more generations. Use after a generation tool returned "submitted" (widget hosts) or timed out. Tracking SEVERAL concurrent generations? Pass them ALL in generation_ids — one call returns an all_done summary. Need the final result? Set wait=true and the server blocks until every generation finishes (up to ~3 min). NEVER call this tool repeatedly in a loop — one wait=true call replaces the whole loop.',
+    `Check the status of one or more generations. Use after a generation tool returned "submitted" (widget hosts) or timed out. Tracking SEVERAL concurrent generations? Pass them ALL in generation_ids — one call returns an all_done summary. Need the final result? Set wait=true and the server blocks until every generation finishes, for at most ~${WAIT_WINDOW_S}s per call. A job that outlives one window (music is ~3 min, video longer) comes back state="processing" — that is a normal result, not an error: call again with wait=true and keep going until every id is terminal. Never poll with wait=false in a loop.`,
     {
       generation_id: z.string().optional().describe('A single generation ID to check'),
       generation_ids: z.array(z.string()).optional().describe('Multiple generation IDs to check in ONE call. Returns { all_done, pending, generations[] } — always prefer this over checking IDs one by one.'),
-      wait: z.boolean().optional().describe('If true, block until every generation reaches a terminal state (completed/failed), up to ~3 minutes, then return the final results. Use this instead of re-calling the tool in a loop.')
+      wait: z.boolean().optional().describe(`If true, block until every generation reaches a terminal state (completed/failed), for at most ~${WAIT_WINDOW_S}s per call, then return whatever state they are in. Anything still processing is reported, not errored — re-issue with wait=true and only the still-pending ids. This is always better than polling with wait=false.`)
     },
     async ({ generation_id, generation_ids, wait }) => {
       const ids = (generation_ids && generation_ids.length > 0)
@@ -836,15 +848,16 @@ function registerGenerateTools(server, client, options = {}) {
           if (wait) {
             // Widgets use this long-wait path. A 15s API check cadence keeps
             // completion responsive without multiplying backend traffic for
-            // every card left open in a host conversation.
-            const result = await pollUntilDone(client, id, { interval: 15000, timeout: 180000 });
+            // every card left open in a host conversation. The window itself is
+            // bounded by the transport — see WAIT_WINDOW_MS above.
+            const result = await pollUntilDone(client, id, { interval: 15000, timeout: WAIT_WINDOW_MS });
             return { generation_id: id, ...result };
           }
           const result = await client.get(`/v1/generate/${encodeURIComponent(id)}/status`);
           return { generation_id: id, ...result };
         } catch (err) {
           if (err.timedOut) {
-            return { generation_id: id, state: 'processing', _timed_out: true, note: 'Still running after 3 min of waiting — call get_generation_status again with wait=true.' };
+            return { generation_id: id, state: 'processing', _timed_out: true, note: `Still running after this ~${WAIT_WINDOW_S}s wait window — call get_generation_status again with wait=true.` };
           }
           if (err.name === 'GenerationFailedError') {
             return { generation_id: id, state: 'failed', error: err.message };
@@ -858,9 +871,15 @@ function registerGenerateTools(server, client, options = {}) {
 
       const pending = results.filter(r => r.state !== 'completed' && r.state !== 'failed' && r.state !== 'cancelled');
       const doneHint = 'ALL generations are in a final state — do NOT poll again. Report the results to the user.';
-      const pendingHint = wait
-        ? 'Some generations are still running after the wait window. Call get_generation_status ONCE more with wait=true and the remaining generation_ids — do not spin without wait.'
-        : 'Some generations are still processing. Do NOT re-call this tool in a loop — call it ONCE with wait=true (and all pending generation_ids) to block until they finish.';
+      // The old wait=false hint said "call it ONCE with wait=true ... to block
+      // until they finish". That is the advice that broke: one wait=true call
+      // cannot outlast a 185s music job, and a caller that obeyed it got a
+      // transport error instead of a result. Say what actually works.
+      const pendingIds = pending.map(r => r.generation_id);
+      const idsPhrase = pendingIds.length > 1
+        ? ` and ONLY the still-pending ids: ${JSON.stringify(pendingIds)}`
+        : '';
+      const pendingHint = stillRunningHint(idsPhrase);
 
       // Single-id calls keep the original flat shape — the generation widget
       // waits on this tool with { generation_id, wait:true } and reads
@@ -968,10 +987,13 @@ function registerGenerateTools(server, client, options = {}) {
         image_url: z.string().describe('Public URL of the keyframe image'),
         timestamp_seconds: z.number().describe('Moment on the OUTPUT timeline (seconds, 0 = first frame) where this image is pinned')
       })).optional().describe('Timeline-pinned keyframes for multi-keyframe models (e.g. "flux-3-keyframes", "luma-ray-3-2-storyboard"): the model generates the motion BETWEEN the pinned images. Only models with `supports_keyframes: true` in list_models accept this; cap = `max_keyframes` (FLUX 3: 10). Requires an explicit `duration` — timestamps beyond it are clamped. Ignored by ordinary elements models. OPTIONAL for flux-3-keyframes: if omitted, pass the images via reference_images instead — they are played through IN ORDER, timed from timing language in the prompt or spaced evenly. Pass explicit keyframes only when you need exact control.'),
+      multi_shots: z.boolean().optional().describe('Enable Multishot metadata/UI badge (and native provider flag when the model supportsMultiShot). Never rewrites or reshapes the prompt — craft shot structure yourself (`Multishot ON`, Total/SHOT lines). MCP default enhance_prompt=false keeps the prompt raw; multi_shots alone is badge/flag only. For crafted demos: enhance_prompt:false + multi_shots:true.'),
+      multi_shot_count: z.number().optional().describe('Explicit shot count when multi_shots=true (e.g. 2). Clamped to ~2 shots/sec of duration.'),
+      session_name: z.string().optional().describe('Short sidebar session title (max ~60 chars), e.g. "UGC — Hana bathroom light". When set, skips AI auto-naming from the prompt boilerplate.'),
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, project_id, session_id }) => {
+    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt) throw new Error('prompt is required');
 
@@ -994,6 +1016,9 @@ function registerGenerateTools(server, client, options = {}) {
         if (audio_url) form.append('audio_url', audio_url);
         if (resolution) form.append('resolution', resolution);
         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 f of resolved) {
@@ -1003,7 +1028,7 @@ function registerGenerateTools(server, client, options = {}) {
       } 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, keyframes, project_id, session_id
+          prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id
         });
       }
 

package/src/tools/visual_dna.js

@@ -197,7 +197,7 @@ function registerVisualDnaTools(server, client, options = {}) {
     'Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
     {
       image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the subject (for characters: front/side/varied angles work best). Use generated-image URLs or upload_media output.'),
-      sheet_type: z.enum(['character', 'product', 'environment', 'style']).optional().describe('Which sheet layout to generate — match the DNA type it will be attached to. Defaults to character.')
+      sheet_type: z.enum(['character', 'character_headless', '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). 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 } : {}) });