@kolbo/mcp 1.48.0 → 1.50.0

package/README.md

@@ -4,7 +4,7 @@ Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Deskt
 
 Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
 
-**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
+**✨ Interactive widgets (v1.30+):** in claude.ai, Claude Desktop, and Codex Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video or audio player, and one-click **Animate · Edit · Recreate · Download** actions. Multi-audio generations render every track with its own player and Download button. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Codex CLI, Cursor) keep the classic text responses.
 
 ## Set up — paste one prompt, or one config block (keyless, no API key)
 
@@ -113,7 +113,7 @@ Just ask your agent naturally:
 
 Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
 
-## Available Tools (86)
+## Available Tools (95)
 
 **Generation**
 | Tool | Description |
@@ -193,16 +193,18 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 |------|-------------|
 | `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
 
-**Music Library** (stock / production music)
+**SYNCI Music Library** (licensed production music)
 | Tool | Description |
 |------|-------------|
-| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
-| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
-| `browse_music_library` | Browse the catalog without a query (paginated). |
-| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
-| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
-| `get_music_track_related` | Get stems + alternate versions of a track. |
-| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
+| `search_music_library` | Search the licensed catalog; results contain watermarked previews only. |
+| `analyze_script_for_music` | Turn a script or scene description into a music search. |
+| `browse_music_library` | Browse the catalog without a query. |
+| `get_music_library_facets` | List genres, moods, instruments, BPM, and duration filters. |
+| `get_music_track_audio` | Get watermarked preview URLs for a track. |
+| `acquire_clean_music_track` | Spend one SYNCI vendor credit and return clean MP3/WAV signed URLs. Idempotent with `request_id`. |
+| `import_music_track_to_library` | Spend one vendor credit and copy a clean MP3/WAV into Kolbo's media library. |
+| `get_music_track_related` | Get stems/alternate-version metadata (purchasing remains unsupported). |
+| `get_music_track_lyrics` | Get lyrics metadata. |
 
 **Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
 | Tool | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -43,7 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "1.29.0",
-    "form-data": "^4.0.5",
+    "form-data": "^4.0.6",
     "zod": "^3.25.0"
   },
   "overrides": {

package/skill/SKILL.md

@@ -115,7 +115,8 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `upload_media` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md` |
 | `create_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
-| `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools. |
+| `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. |
+| `search_music_library` / `browse_music_library` / `get_music_track_audio` / `acquire_clean_music_track` / `import_music_track_to_library` | SYNCI licensed music. Search/playback is watermarked preview-only. `acquire_clean_music_track` and `import_music_track_to_library` immediately consume one SYNCI vendor credit and return/import an unwatermarked MP3/WAV; reuse `request_id` on retries. |
 | `list_projects` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls; `move_session` relocates a whole session + its media when work landed in the wrong project. NOT the same as `app_builder_list_projects`. See "Projects — Where Work Lands" below. |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` / `list_sessions` | Project lifecycle + session inventory (deletion stays in-app). Create a project when the user starts new work, then pass its id on EVERY call. |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes; `get_project_profile` = the living brief — read it to ground work in the project |

package/skill/references/models/music.md

@@ -8,7 +8,7 @@ Load this file when the user wants AI-generated **music** — full songs, lyrics
 
 **Kolbo MCP routing:** call `generate_music`. Suno is a model option — use `list_models({ type: "music_gen" })` to see versions. Pass `instrumental` and `duration` as separate params; pass the Style/Description text as `style` and the Lyrics as `lyrics`.
 
-**Wants an EXISTING track, not a new song?** ("background music", "stock music", "royalty-free track") → don't generate. Use `search_stock_media` with `mediaType: "music"` (semantic vibe query — "tense cinematic pulse", "uplifting corporate background") → `get_stock_asset` for download URLs. Free, no credits. The older `*_music_library` tools are deprecated adapters over the stock library — prefer the stock tools.
+**Wants an EXISTING track, not a new song?** ("background music", "stock music", "royalty-free track") → don't generate. Use `search_stock_media` with `mediaType: "music"` for free Kolbo/Coverr results. For SYNCI's licensed catalog use `search_music_library`; its playback URLs are watermarked previews. Final use must call `acquire_clean_music_track` or `import_music_track_to_library`, which immediately consumes one SYNCI vendor credit and returns/imports a clean MP3/WAV. Reuse `request_id` when retrying the same action.
 
 ## CRITICAL Kolbo Platform Rules
 

package/src/apps/bridge.js

@@ -69,7 +69,7 @@ const BRIDGE_JS = `
     } else if (m.method === 'ui/notifications/tool-input' || m.method === 'ui/notifications/tool-input-partial') {
       // Fires while the tool is still RUNNING — lets widgets show a real
       // "preparing" state instead of a blank card until the result lands.
-      toolInputFns.forEach(function (f) { try { f((m.params && m.params.arguments) || {}); } catch (e) {} });
+      toolInputFns.forEach(function (f) { try { f((m.params && m.params.arguments) || {}, m.params || {}); } catch (e) {} });
     } else if (m.method === 'ui/notifications/host-context-changed') {
       hostContext = (m.params && m.params.hostContext) || m.params || hostContext;
       themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });

package/src/apps/index.js

@@ -124,7 +124,19 @@ function appsEnabled(server, opts = {}) {
   if (opts.apps === true || process.env.KOLBO_MCP_APPS === '1') return true;
   try {
     const caps = server?.server?.getClientCapabilities?.();
-    return getUiCapability(caps) !== undefined;
+    if (getUiCapability(caps) !== undefined) return true;
+
+    // Codex Desktop currently mounts MCP App resources from tool `_meta`, but
+    // its initialize handshake identifies as `codex-mcp-client` with an empty
+    // capabilities object. Without this compatibility path the host mounts a
+    // "Preparing" card while the tool takes the blocking/text fallback, so the
+    // completed media never reaches the iframe as structuredContent.
+    //
+    // Keep the desktop-origin check: Codex CLI uses the same client name but is
+    // a text surface, where returning immediately would remove the final URLs.
+    const info = server?.server?.getClientVersion?.();
+    const origin = process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE || '';
+    return info?.name === 'codex-mcp-client' && /codex desktop/i.test(origin);
   } catch (_) {
     return false;
   }
@@ -272,9 +284,9 @@ const TOOL_WIDGETS = {
   // media grid
   list_media: UI.mediaGrid,
   search_stock_media: UI.mediaGrid,
-  get_stock_collections: UI.mediaGrid,
   search_music_library: UI.mediaGrid,
   browse_music_library: UI.mediaGrid,
+  get_stock_collections: UI.mediaGrid,
   list_presets: UI.mediaGrid,
   list_voices: UI.mediaGrid,
   list_visual_dnas: UI.mediaGrid,

package/src/apps/theme.js

@@ -259,6 +259,24 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-audio-meta { flex: 1; min-width: 0; }
 .k-audio-title { font-size: 12.5px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .k-audio-sub { font-size: 11px; color: var(--text-faint); }
+.k-generated-audio {
+  display: grid; grid-template-columns: 40px minmax(0, 1fr) auto;
+  align-items: center; gap: 7px 10px;
+}
+.k-generated-audio .k-audio-placeholder {
+  display: flex; align-items: center; justify-content: center; color: var(--brand);
+}
+.k-generated-audio .k-audio-placeholder svg { width: 19px; height: 19px; }
+.k-generated-audio .k-audio-download { white-space: nowrap; }
+.k-generated-audio .k-audio-player {
+  grid-column: 2 / -1; display: block; width: 100%; min-width: 0; height: 34px;
+}
+@media (max-width: 520px) {
+  .k-generated-audio { grid-template-columns: 36px minmax(0, 1fr); }
+  .k-generated-audio .k-audio-art { width: 36px; height: 36px; }
+  .k-generated-audio .k-audio-download { grid-column: 2; justify-self: start; }
+  .k-generated-audio .k-audio-player { grid-column: 1 / -1; }
+}
 .k-play {
   width: 32px; height: 32px; border-radius: 50%; flex: none; border: 1px solid rgba(255,255,255,0.18);
   background: rgba(0,0,0,0.5); color: #fff; cursor: pointer;

package/src/apps/widgets/generation.js

@@ -17,6 +17,7 @@ const { widgetPage } = require('../html');
  *   settings: { duration, resolution, aspect_ratio, audio, voice, mode },
  *   reference_image,                   // thumbnail URL (optional)
  *   urls, thumbnail_url, title, duration, credits_used,
+ *   tracks: [{ title, duration, thumbnail_url, model }], // optional audio metadata by URL index
  *   scenes: [{ scene_number, title, image_urls, video_urls }],
  *   error,
  *   open_url                           // "Open in Kolbo" target (optional)
@@ -53,6 +54,8 @@ const SCRIPT = `
 var state = null;          // current structuredContent
 var selected = 0;          // selected result index
 var pollTimer = null;
+var originTool = null;
+var originArgs = {};
 
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
 el('action-cancel').innerHTML = ICONS.x;
@@ -122,23 +125,26 @@ function renderGenerating(sc) {
   schedulePoll(sc);
 }
 
-// Poll ceilings so the card never spins "Generating" forever. A generation
-// that genuinely stalls, or a status call that keeps failing (e.g. the record
-// can't be resolved), surfaces an error + Try Again instead of hanging.
-var MAX_POLL_MS = 12 * 60 * 1000;   // hard wall-clock ceiling (covers slow 4K video)
-var MAX_POLL_ERRORS = 12;           // ~48s of consecutive status-call failures → give up
+// Poll ceilings so the card never spins forever. Losing widget-side tracking
+// is not a generation failure: keep retries disabled because the paid server
+// job may still complete.
+var MAX_POLL_MS = 35 * 60 * 1000;
+var MAX_POLL_ERRORS = 30;
 var pollStart = 0, pollErrors = 0;
 
 function schedulePoll(sc) {
   if (!pollStart) pollStart = Date.now();
   clearTimeout(pollTimer);
-  pollTimer = setTimeout(function () { poll(sc); }, 4000);
+  // The call itself long-waits server-side (normally up to three minutes).
+  // This short pause only separates successive wait windows.
+  var delay = 1500;
+  pollTimer = setTimeout(function () { poll(sc); }, delay);
 }
 function poll(sc) {
   if (pollStart && (Date.now() - pollStart) > MAX_POLL_MS) {
-    return renderError('This is taking longer than expected and may have stalled. Try again — if it keeps happening the model may be busy. Any finished result will also appear in your Kolbo library.');
+    return renderTrackingIssue('This is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }
-  var args = sc.status_args || { generation_id: sc.generation_id };
+  var args = sc.status_args || { generation_id: sc.generation_id, wait: true };
   window.kolbo.callTool(sc.poll_tool || 'get_generation_status', args).then(function (res) {
     var st = structured(res) || {};
     var stateName = st.state || st.phase || st.status;
@@ -146,7 +152,7 @@ function poll(sc) {
     // generation state — count it toward the consecutive-error cap so a record
     // that can't be resolved errors out fast instead of polling forever.
     if ((res && res.isError) || st.success === false || (st.error && !stateName)) {
-      if (++pollErrors >= MAX_POLL_ERRORS) return renderError(st.error || 'Could not track this generation. Please try again.');
+      if (++pollErrors >= MAX_POLL_ERRORS) return renderTrackingIssue(st.error || 'Tracking paused. The generation may still be running.');
       return schedulePoll(sc);
     }
     if (stateName === 'completed') {
@@ -163,9 +169,13 @@ function poll(sc) {
       renderResult(done);
       // Let the model know the outcome without it having to poll.
       try {
+        var completedUrls = (done.urls || []).slice();
+        (done.scenes || []).forEach(function (scene) {
+          completedUrls = completedUrls.concat(scene.image_urls || [], scene.video_urls || []);
+        });
         window.kolbo.updateModelContext(
           'Generation ' + (sc.generation_id || '') + ' completed (' + (sc.tool || '') + ').' +
-          '\\nOutput URLs:\\n' + (done.urls || []).join('\\n') +
+          '\\nOutput URLs:\\n' + completedUrls.join('\\n') +
           (done.credits_used != null ? '\\nCredits used: ' + done.credits_used : ''));
       } catch (e) {}
     } else if (stateName === 'failed' || stateName === 'error' || stateName === 'cancelled') {
@@ -175,7 +185,7 @@ function poll(sc) {
       schedulePoll(sc);
     }
   }).catch(function () {
-    if (++pollErrors >= MAX_POLL_ERRORS) return renderError('Lost connection while tracking this generation. Please try again.');
+    if (++pollErrors >= MAX_POLL_ERRORS) return renderTrackingIssue('Tracking paused after repeated connection errors. The generation may still be running.');
     schedulePoll(sc);
   });
 }
@@ -240,13 +250,35 @@ function renderVideo(sc, urls) {
 
 function renderAudio(sc, urls) {
   el('stage').innerHTML = urls.map(function (u, i) {
-    var title = sc.title || ((TOOL_TITLES[sc.tool] || 'Audio') + (urls.length > 1 ? ' ' + (i + 1) : ''));
-    return '<div class="k-audio-row">' +
-      (sc.thumbnail_url ? '<img class="k-audio-art" src="' + esc(sc.thumbnail_url) + '">' : '<div class="k-audio-art"></div>') +
+    var track = (sc.tracks && sc.tracks[i]) || {};
+    var titleBase = track.title || sc.title || (TOOL_TITLES[sc.tool] || 'Audio');
+    var title = titleBase + (urls.length > 1 ? ' — Track ' + (i + 1) : '');
+    var duration = track.duration != null ? track.duration : sc.duration;
+    var artwork = track.thumbnail_url || sc.thumbnail_url;
+    return '<div class="k-audio-row k-generated-audio">' +
+      (artwork ? '<img class="k-audio-art" src="' + esc(artwork) + '" alt="">' :
+        '<div class="k-audio-art k-audio-placeholder">' + ICONS.audio + '</div>') +
       '<div class="k-audio-meta"><div class="k-audio-title">' + esc(title) + '</div>' +
-      '<div class="k-audio-sub">' + esc(sc.model || '') + (sc.duration ? ' · ' + fmtDur(sc.duration) : '') + '</div></div>' +
-      '<audio src="' + esc(u) + '" controls style="height:32px;max-width:260px"></audio></div>';
+      '<div class="k-audio-sub">' + esc(track.model || sc.model || '') +
+      (duration ? ' · ' + fmtDur(duration) : '') + '</div></div>' +
+      '<button class="k-btn k-audio-download" data-audio-download="' + esc(u) +
+      '" aria-label="Download ' + esc(title) + '">' + ICONS.download + ' Download</button>' +
+      '<audio class="k-audio-player" src="' + esc(u) + '" controls preload="metadata" aria-label="Play ' +
+      esc(title) + '"></audio></div>';
   }).join('');
+  Array.prototype.forEach.call(el('stage').querySelectorAll('[data-audio-download]'), function (b) {
+    b.onclick = function () {
+      window.kolbo.openLink(downloadUrl(b.getAttribute('data-audio-download')));
+    };
+  });
+  var players = el('stage').querySelectorAll('.k-audio-player');
+  Array.prototype.forEach.call(players, function (player) {
+    player.addEventListener('play', function () {
+      Array.prototype.forEach.call(players, function (other) {
+        if (other !== player) other.pause();
+      });
+    });
+  });
 }
 
 function render3d(sc, urls) {
@@ -363,6 +395,22 @@ function renderError(msg) {
   window.kolbo.notifySize();
 }
 
+function renderTrackingIssue(msg) {
+  clearTimeout(pollTimer);
+  setPhaseChip('Still working', false);
+  el('stage').innerHTML = '<div class="k-error">' + ICONS.clock + ' ' + esc(msg) + '</div>';
+  el('actions').innerHTML = '<button class="k-btn primary" id="status-btn">' + ICONS.clock + ' Check status</button>' +
+    '<button class="k-btn ghost" id="tracking-open">Open in Kolbo ' + ICONS.open + '</button>';
+  el('status-btn').onclick = function () {
+    window.kolbo.sendMessage('Check the existing Kolbo generation status without retrying it.' +
+      (state && state.generation_id ? '\\nGeneration ID: ' + state.generation_id : ''));
+  };
+  el('tracking-open').onclick = function () {
+    window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai');
+  };
+  window.kolbo.notifySize();
+}
+
 /* ---------- fullscreen viewer ---------- */
 var isFullscreen = false;
 function toggleFullscreen() {
@@ -417,9 +465,10 @@ function renderActions(sc) {
   }
   if (sc.kind === 'video') {
     a.push('<button class="k-btn primary" id="btn-download">' + ICONS.download + ' Download</button>');
-  } else if (hasSingleUrl) {
+  } else if (hasSingleUrl && sc.kind !== 'audio') {
     // Scenes (Creative Director) have no single "current" url — per-item hover
-    // download buttons cover them instead.
+    // download buttons cover them instead. Audio has a visible download button
+    // on every track so multi-output generations never download only track 1.
     a.push('<button class="k-btn" id="btn-download">' + ICONS.download + ' Download</button>');
   }
   a.push('<button class="k-btn" id="btn-recreate">' + ICONS.retry + ' Recreate</button>');
@@ -471,6 +520,8 @@ function openPromptRow(placeholder, onSend) {
    take many seconds (model resolution, file upload, submit). Show a live
    shell immediately instead of a blank card. */
 function bootPre(toolName, args) {
+  if (toolName) originTool = toolName;
+  if (args) originArgs = args;
   if (state) return; // real data already arrived
   el('tool-title').textContent = TOOL_TITLES[toolName] || 'Generation';
   if (args && (args.prompt || args.text)) {
@@ -484,23 +535,61 @@ function bootPre(toolName, args) {
   window.kolbo.notifySize();
 }
 
+function kindFromTool(tool, sc) {
+  if (sc && sc.scenes) return 'scenes';
+  if (/video|lipsync|elements|first_last/i.test(tool || '')) return 'video';
+  if (/music|speech|sound/i.test(tool || '')) return 'audio';
+  if (/3d/i.test(tool || '')) return '3d';
+  var firstUrl = sc && Array.isArray(sc.urls) ? String(sc.urls[0] || '').split('?')[0].toLowerCase() : '';
+  if (/\\.(mp4|mov|webm|mkv)$/.test(firstUrl)) return 'video';
+  if (/\\.(mp3|wav|m4a|aac|ogg|flac)$/.test(firstUrl)) return 'audio';
+  if (/\\.(glb|gltf|fbx|obj|usdz)$/.test(firstUrl)) return '3d';
+  return 'image';
+}
+
+// Recover a successful legacy/text result when a host mounted the iframe from
+// declaration metadata but the server did not recognize its Apps capability.
+function completedFromPlain(sc) {
+  if (!sc || (!Array.isArray(sc.urls) && !Array.isArray(sc.scenes))) return null;
+  return Object.assign({}, sc, {
+    widget: 'generation',
+    phase: 'completed',
+    tool: originTool,
+    kind: kindFromTool(originTool, sc),
+    prompt: originArgs.prompt || originArgs.text || sc.prompt_used || '',
+    model: sc.model || originArgs.model,
+    settings: {
+      duration: sc.duration || originArgs.duration,
+      resolution: originArgs.resolution,
+      aspect_ratio: originArgs.aspect_ratio
+    },
+    urls: sc.urls || []
+  });
+}
+
 /* ---------- wire host events ---------- */
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
   if (sc && (sc.phase || sc.widget)) return boot(sc);
+  var recovered = completedFromPlain(sc);
+  if (recovered) return boot(recovered);
   // Tool errored (or returned plain text): show it instead of a dead blank card.
   var txt = '';
   try { txt = (result.content || []).filter(function (c) { return c.type === 'text'; }).map(function (c) { return c.text; }).join(' '); } catch (e) {}
+  if (/timed out|timeout/i.test(txt)) {
+    return renderTrackingIssue((txt || 'Tracking timed out. The generation may still be running.').slice(0, 300));
+  }
   if (result.isError || /error|failed/i.test(txt)) {
     renderError((txt || 'The request failed.').slice(0, 300));
   }
 });
-window.kolbo.onToolInput(function (args) { bootPre(null, args); });
+window.kolbo.onToolInput(function (args, info) { bootPre(info && info.name, args); });
 window.kolbo.ready(function (ctx) {
   var info = ctx && ctx.toolInfo;
   if (!state && info) {
+    originTool = (info.tool && info.tool.name) || originTool;
     if (info.result && info.result.structuredContent) return boot(info.result.structuredContent);
-    bootPre(info.tool && info.tool.name, null);
+    bootPre(originTool, null);
   }
 });
 `;

package/src/apps/widgets/transcript.js

@@ -36,7 +36,7 @@ const BODY = `
 const SCRIPT = `
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
 el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai'); };
-var state = null, pollTimer = null;
+var state = null, pollTimer = null, originArgs = {};
 
 function boot(sc) {
   if (!sc) return;
@@ -83,40 +83,68 @@ function boot(sc) {
 }
 
 var pollStart = 0, pollErrors = 0;
-var MAX_POLL_MS = 12 * 60 * 1000, MAX_POLL_ERRORS = 12;
+var MAX_POLL_MS = 35 * 60 * 1000, MAX_POLL_ERRORS = 30;
 function poll() {
   if (!pollStart) pollStart = Date.now();
   if ((Date.now() - pollStart) > MAX_POLL_MS) {
-    return boot(Object.assign({}, state, { phase: 'failed', error: 'Transcription is taking longer than expected and may have stalled — please try again.' }));
+    return trackingIssue('This transcription is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }
-  window.kolbo.callTool(state.poll_tool || 'get_generation_status', { generation_id: state.generation_id })
+  var args = state.status_args || { generation_id: state.generation_id, wait: true };
+  window.kolbo.callTool(state.poll_tool || 'get_generation_status', args)
     .then(function (res) {
       var st = structured(res) || {};
       var s = st.state || st.phase;
       if ((res && res.isError) || st.success === false || (st.error && !s)) {
-        if (++pollErrors >= MAX_POLL_ERRORS) return boot(Object.assign({}, state, { phase: 'failed', error: st.error || 'Could not track this transcription. Please try again.' }));
-        pollTimer = setTimeout(poll, 5000); return;
+        if (++pollErrors >= MAX_POLL_ERRORS) return trackingIssue(st.error || 'Tracking paused. The transcription may still be running.');
+        pollTimer = setTimeout(poll, pollDelay()); return;
       }
       if (s === 'completed') {
         var r = st.result || st;
         boot(Object.assign({}, state, r, { phase: 'completed', credits_used: st.credits_used }));
       } else if (s === 'failed' || s === 'cancelled') {
         boot(Object.assign({}, state, { phase: 'failed', error: st.error }));
-      } else { pollErrors = 0; pollTimer = setTimeout(poll, 5000); }
+      } else { pollErrors = 0; pollTimer = setTimeout(poll, pollDelay()); }
     }).catch(function () {
-      if (++pollErrors >= MAX_POLL_ERRORS) return boot(Object.assign({}, state, { phase: 'failed', error: 'Lost connection while tracking this transcription. Please try again.' }));
-      pollTimer = setTimeout(poll, 5000);
+      if (++pollErrors >= MAX_POLL_ERRORS) return trackingIssue('Tracking paused after repeated connection errors. The transcription may still be running.');
+      pollTimer = setTimeout(poll, pollDelay());
     });
 }
 
+function pollDelay() {
+  // The call itself long-waits server-side; only briefly back off between
+  // successive wait windows.
+  return 1500;
+}
+
+function trackingIssue(msg) {
+  clearTimeout(pollTimer);
+  el('phase-chip').style.display = '';
+  el('phase-chip').textContent = 'Still working';
+  el('stage').classList.remove('k-empty');
+  el('stage').innerHTML = '<div class="k-error">' + ICONS.clock + ' ' + esc(msg) + '</div>';
+  el('actions').innerHTML = '<button class="k-btn primary" id="transcript-status">' + ICONS.clock + ' Check status</button>';
+  el('transcript-status').onclick = function () {
+    window.kolbo.sendMessage('Check the existing Kolbo transcription status without retrying it.' +
+      (state && state.generation_id ? '\\nGeneration ID: ' + state.generation_id : ''));
+  };
+  window.kolbo.notifySize();
+}
+
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
   // Only boot on a real widget contract (phase present). A text-JSON
   // fallback like { status: 'submitted' } has no phase and would render a
   // bogus "(empty transcript)" completed view.
   if (sc && (sc.phase || sc.widget === 'transcript')) return boot(sc);
+  if (sc && (typeof sc.text === 'string' || sc.srt_url || sc.txt_url)) {
+    return boot(Object.assign({}, sc, {
+      widget: 'transcript', phase: 'completed',
+      audio_url: originArgs.source && /^https?:\\/\\//i.test(originArgs.source) ? originArgs.source : undefined
+    }));
+  }
   var txt = '';
   try { txt = (result.content || []).filter(function (c) { return c.type === 'text'; }).map(function (c) { return c.text; }).join(' '); } catch (e) {}
+  if (/timed out|timeout/i.test(txt)) return trackingIssue((txt || 'Tracking timed out.').slice(0, 300));
   if (result.isError || /error|failed/i.test(txt)) {
     el('phase-chip').style.display = 'none';
     el('stage').classList.remove('k-empty');
@@ -129,6 +157,7 @@ window.kolbo.onToolResult(function (result) {
   if (card) card.style.display = 'none';
   window.kolbo.notifySize();
 });
+window.kolbo.onToolInput(function (args) { originArgs = args || {}; });
 `;
 
 function transcriptWidgetHtml() {

package/src/index.js

@@ -115,7 +115,7 @@ function createServer(opts = {}) {
       '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
       '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
       '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
-      '6. DIRECTOR / BATCH JOBS: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal. Video batches can take many minutes. If the tool returns `_timed_out:true`, the batch is STILL RUNNING on the server — call `get_creative_director_status` with the returned generation_id and keep checking until state="completed" to collect all scene outputs. NEVER conclude a Director run failed and fall back to plain generate_image/generate_video without first checking status — doing so wastes the user\'s credits by paying twice. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
+      '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
       '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE: (A) User has a LOCAL file (audio, video, image, document) on their machine: if you have filesystem access (Claude Desktop / Code / IDE / any stdio MCP client) → call `upload_media` with the absolute local path OR pass the path directly to tools like `transcribe_audio` which accept local paths natively. If you have NO filesystem access (claude.ai browser/mobile) → call `media_upload_widget` IMMEDIATELY, an upload card appears, the user uploads, and a `media.kolbo.ai` CDN URL comes back — use that URL for any follow-up tool call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly to the tool. All Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 a large file — use upload_media instead.',
       '9. MODEL SELECTION: ALWAYS pass a specific `model` on every generation tool — do NOT omit it. Omitting falls back to "Smart Select" auto-routing, which we deliberately avoid because it hides the model choice from the user and often picks a generic default. Choose the model that best fits the task and the user\'s intent (quality, speed, style, capability). If you are unsure which model to use for a given type, call `list_models` with the matching `type` and pick the recommended/flagship one, then pass its `identifier`. Only use Smart Select (omit `model`) if the user EXPLICITLY asks you to auto-pick.',

package/src/tools/_shared.js

@@ -214,6 +214,45 @@ async function resolveToBuffer(source, kind, opts = {}) {
   };
 }
 
+// ─── Universal graceful-timeout convention ───────────────────────────────────
+// pollUntilDone throws PollingTimeoutError (err.timedOut === true) when the
+// CLIENT-SIDE poll window elapses — the generation is almost always still
+// running server-side (or already done). Originally only
+// generate_creative_director caught this and returned a non-throwing
+// "_timed_out" result; every other tool let it propagate, so the MCP SDK
+// wrapped it as isError:true and recovery depended entirely on the calling
+// LLM reading hint text. pollOrTimedOut() is the one place that decision now
+// lives — every generation/chat tool routes its pollUntilDone call through
+// it instead of duplicating the try/catch. Genuine failures (state
+// failed/cancelled → GenerationFailedError) are NOT caught here; they still
+// throw and surface as a real tool error.
+const { pollUntilDone } = require('../polling');
+
+/**
+ * @returns {Promise<{result: object}|{timedOut: object}>}
+ *   Callers do: `const poll = await pollOrTimedOut(...); if (poll.timedOut) return poll.timedOut; const result = poll.result;`
+ */
+async function pollOrTimedOut(client, generationId, pollOpts) {
+  try {
+    return { result: await pollUntilDone(client, generationId, pollOpts) };
+  } catch (err) {
+    if (!err || !err.timedOut) throw err;
+    return {
+      timedOut: {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            state: 'processing',
+            generation_id: generationId,
+            _timed_out: true,
+            _hint: `Still running on the server after the poll window — this is NOT a failure, no credits were lost. Call get_generation_status with generation_id="${generationId}" (wait=true) to keep checking until state="completed". Do NOT re-run this tool.`
+          }, null, 2)
+        }]
+      }
+    };
+  }
+}
+
 /**
  * Extract real, multiplier-adjusted credit cost from a polled getStatus
  * response. kolbo-api returns `credits_used` (final number deducted) and
@@ -363,6 +402,19 @@ function buildOpenUrl(tool, gen) {
   return url;
 }
 
+/**
+ * Build the "Open in Kolbo" deep link for a PROJECT. Lands on the Media hub
+ * (all-assets view) pre-filtered to this project, where the user sees every
+ * generation/media item in it and can switch projects via the in-page selector.
+ * The media page reads `?project=<id>` on load and selects it. Returns undefined
+ * for a missing id or the default "API Generations" bucket (no useful landing —
+ * it is the catch-all, not a real workspace the user navigates to).
+ */
+function buildProjectUrl(projectId, opts = {}) {
+  if (!projectId || opts.is_default) return undefined;
+  return `${APP_BASE_URL}/media?project=${encodeURIComponent(projectId)}`;
+}
+
 // ─── MCP Apps generation widget helpers ──────────────────────────────────────
 // When the host renders MCP Apps (claude.ai via the remote connector, Claude
 // Desktop over stdio), generation tools return IMMEDIATELY after submit and the
@@ -380,7 +432,7 @@ const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
  *   client         KolboClient (for model icon lookup)
  *   model, prompt, count, settings, reference_image, estimated_seconds
  *   poll_tool      widget-side status tool (default 'get_generation_status')
- *   status_args    args for poll_tool (default { generation_id })
+ *   status_args    args for poll_tool (default { generation_id, wait: true })
  */
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
@@ -392,7 +444,10 @@ async function uiGenerating(p) {
     tool: p.tool,
     generation_id: p.gen.generation_id,
     poll_tool: p.poll_tool || 'get_generation_status',
-    status_args: p.status_args,
+    // Keep at most one long-wait status call in flight per widget. Without
+    // wait=true, every open card calls tools/call every few seconds, flooding
+    // the host's global progress/context stream and API rate limits.
+    status_args: p.status_args || { generation_id: p.gen.generation_id, wait: true },
     model: p.model || 'Smart Select',
     model_icon: icon,
     prompt: p.prompt,
@@ -446,11 +501,13 @@ module.exports = {
   guessFilename,
   guessContentType,
   resolveToBuffer,
+  pollOrTimedOut,
   creditFields,
   projectIdField,
   projectScopeReadField,
   inlineImageBlocks,
   buildOpenUrl,
+  buildProjectUrl,
   uiGenerating,
   uiCompleted,
   appsEnabled,

package/src/tools/chat.js

@@ -4,8 +4,7 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
-const { pollUntilDone } = require('../polling');
-const { creditFields, projectIdField } = require('./_shared');
+const { pollOrTimedOut, creditFields, projectIdField } = require('./_shared');
 
 function registerChatTools(server, client) {
   // ─── chat_send_message ─────────────────────────────────────
@@ -40,10 +39,12 @@ function registerChatTools(server, client) {
       // extra time when web_search is on (may fetch + analyze multiple pages).
       const timeout = deep_think ? 600000 : (web_search ? 240000 : 120000);
 
-      const result = await pollUntilDone(client, gen.message_id, {
+      const poll = await pollOrTimedOut(client, gen.message_id, {
         interval: (gen.poll_interval_hint || 2) * 1000,
         timeout
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       // Chat status shape (from extractResult in kolbo-api sdk/controller.js):
       // { content, reasoning_content, image_urls?, video_urls?, audio_urls?, model, created_at }