@kolbo/mcp 1.48.0 → 1.50.0

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
+const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
@@ -43,8 +43,8 @@ function registerGenerateTools(server, client, options = {}) {
   // tool output is unchanged: a text block with the image URL.
   const inlineImages = !!options.inlineImages;
   // MCP Apps hosts (claude.ai remote connector, Claude Desktop) get an instant
-  // "submitted" response + a live ui://kolbo/generation.html widget that polls
-  // get_generation_status itself. Text-only hosts never take this branch.
+  // "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);
   // ─── generate_image ────────────────────────────────────────
   server.tool(
@@ -79,10 +79,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
         timeout: 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
       return {
@@ -135,10 +137,12 @@ function registerGenerateTools(server, client, options = {}) {
       // server-side. Extend the polling window in those cases to avoid forcing
       // every call into the timeout-and-recover path via get_generation_status.
       const heavy = (source_images && source_images.length > 1) || (visual_dna_ids && visual_dna_ids.length > 0);
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
         timeout: heavy ? 240000 : 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
       return {
@@ -183,6 +187,15 @@ function registerGenerateTools(server, client, options = {}) {
       });
 
       const cdStatusUrl = `/v1/generate/creative-director/${gen.generation_id}/status`;
+      if (ui()) return uiGenerating({
+        tool: 'generate_creative_director', kind: 'scenes', gen, client, model, prompt,
+        count: scene_count || 4,
+        settings: { duration, resolution, aspect_ratio, mode: workflow_type || 'image' },
+        reference_image: reference_images?.[0],
+        poll_tool: 'get_creative_director_status',
+        status_args: { generation_id: gen.generation_id, wait: true }
+      });
+
       // Video mode runs N scenes as parallel video generations, each of which
       // can take several minutes — a whole batch routinely exceeds the 10-min
       // image window. Give video batches 30 min (the server watchdog finalizes
@@ -237,15 +250,6 @@ function registerGenerateTools(server, client, options = {}) {
         _followup_hint: 'Each scene is a separate asset. If the user asks to edit one scene, find that scene by scene_number/title and pass its image_urls[0] (or video_urls[0]) to generate_image_edit / edit_image / edit_video / generate_video_from_video. Do NOT re-run generate_creative_director unless the user explicitly wants a brand-new set.'
       }, null, 2);
 
-      // Creative Director polls a dedicated status route the widget can't reach
-      // through get_generation_status, so it stays blocking on UI hosts too and
-      // renders the completed scene gallery.
-      if (ui()) return uiCompleted({
-        tool: 'generate_creative_director', kind: 'scenes', gen, client, model, prompt,
-        settings: { duration, resolution, mode: workflow_type }, scenes,
-        credits_used: creditFields(result).credits_used
-      }, cdText);
-
       return { content: [{ type: 'text', text: cdText }] };
     }
   );
@@ -258,12 +262,30 @@ 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. Use this to resume checking a batch that was still running when generate_creative_director returned `_timed_out: true` — poll it until state="completed" to collect ALL parallel scene outputs at once. Do NOT use the generic get_generation_status for Creative Director ids; it points at the wrong endpoint.',
+    '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. Do NOT use the generic get_generation_status for Creative Director ids; it points at the wrong endpoint.',
     {
-      generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.')
+      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.')
     },
-    async ({ generation_id }) => {
-      const status = await client.get(`/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`);
+    async ({ generation_id, wait }) => {
+      const statusUrl = `/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`;
+      let status;
+      if (wait) {
+        try {
+          status = await pollUntilDone(client, generation_id, {
+            interval: 15000,
+            timeout: 180000,
+            statusUrl
+          });
+        } catch (err) {
+          // A tracking timeout is not a failed paid generation. Return the
+          // latest batch state so the widget can start one new long wait.
+          if (!err?.timedOut) throw err;
+          status = await client.get(statusUrl);
+        }
+      } else {
+        status = await client.get(statusUrl);
+      }
       const scenes = (status.scenes || []).map(s => ({
         scene_number: s.scene_number,
         status: s.status,
@@ -273,6 +295,7 @@ function registerGenerateTools(server, client, options = {}) {
       }));
       const completed = scenes.filter(s => s.status === 'completed').length;
       return { content: [{ type: 'text', text: JSON.stringify({
+        ...creditFields(status),
         state: status.state,
         generation_id,
         progress: status.progress,
@@ -281,7 +304,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 again in a few seconds until state="completed".'
+          : 'Still running. Call get_creative_director_status once with wait=true; do not poll it in a loop.'
       }, null, 2) }] };
     }
   );
@@ -318,10 +341,15 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      // 15 min — Kling O3 4K, Veo 3.1 at higher durations/resolutions, Hailuo 2.3,
+      // and Seedance 2 routinely run 5-12 min under provider queue load; the old
+      // 5-min window forced routine calls into the timeout-and-recover path.
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
-        timeout: 300000
+        timeout: 900000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -368,10 +396,14 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: image_url
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      // 15 min — same real-world generation times as generate_video (Kling O3 4K,
+      // Veo 3.1, Hailuo 2.3, Seedance 2 at higher durations/resolutions).
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
-        timeout: 300000
+        timeout: 900000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -429,10 +461,12 @@ function registerGenerateTools(server, client, options = {}) {
         settings: { mode: instrumental ? 'instrumental' : (style || undefined) },
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 300000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -501,10 +535,12 @@ function registerGenerateTools(server, client, options = {}) {
         settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions }
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -558,10 +594,12 @@ function registerGenerateTools(server, client, options = {}) {
         settings: { duration }
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -596,14 +634,17 @@ function registerGenerateTools(server, client, options = {}) {
       const checkOne = async (id) => {
         try {
           if (wait) {
-            const result = await pollUntilDone(client, id, { interval: 5000, timeout: 180000 });
+            // 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 });
             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', 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 3 min of waiting — call get_generation_status again with wait=true.' };
           }
           if (err.name === 'GenerationFailedError') {
             return { generation_id: id, state: 'failed', error: err.message };
@@ -621,8 +662,8 @@ function registerGenerateTools(server, client, options = {}) {
         : '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.';
 
       // Single-id calls keep the original flat shape — the generation widget
-      // polls this tool with { generation_id } and reads state/result at the
-      // top level.
+      // waits on this tool with { generation_id, wait:true } and reads
+      // state/result at the top level.
       if (!generation_ids || generation_ids.length === 0) {
         const single = results[0];
         single._hint = pending.length === 0
@@ -712,10 +753,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -791,10 +834,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: first_frame_url || undefined
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 300000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -901,10 +946,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: sourceIsUrl && !/\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? source : undefined,
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1001,10 +1048,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1069,15 +1118,18 @@ function registerGenerateTools(server, client, options = {}) {
           widget: 'transcript', phase: 'generating',
           generation_id: startResponse.generation_id,
           poll_tool: 'get_generation_status',
+          status_args: { generation_id: startResponse.generation_id, wait: true },
           audio_url: isUrl ? source : undefined,
           open_url: buildOpenUrl('transcribe_audio', startResponse),
         });
       }
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 5) * 1000,
         timeout: 1800000 // 30 minutes — long podcasts are a thing
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1136,10 +1188,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 900000 // 15 minutes — 3D generation is slow
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1258,10 +1312,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: image_url
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 300000 // 5 min — split_upscale and multi_shot can take longer
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1416,10 +1472,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: image_url
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{