@kolbo/mcp 1.87.11 → 1.87.13

package/src/tools/_shared.js

@@ -1,1191 +1,1213 @@
-/* Shared helpers for MCP tools. No server.tool() registrations here.
- *
- * This file centralizes the URL-or-local-path → Buffer resolver used by
- * every tool that accepts file-ish arguments (visual_dna, elements,
- * first_last_frame, lipsync, video_from_video, transcription, media upload,
- * future additions). It also owns the SSRF guard applied to any URL we
- * fetch on the user's local machine.
- *
- * SSRF defense in depth:
- *   1. Only http: / https: protocols.
- *   2. Block IP literals in private / loopback / link-local / multicast /
- *      reserved ranges (IPv4 and IPv6).
- *   3. Block common internal hostnames (localhost, *.local, *.internal,
- *      metadata.google.internal, metadata.goog).
- *   4. Manual redirect following so every hop is re-validated (a crafted
- *      public URL could 302 to 169.254.169.254 — global fetch would follow
- *      silently).
- *
- * If you add a new tool that fetches URLs, import resolveToBuffer from here
- * rather than reinventing the guard.
- */
-
-const fs = require('fs');
-const path = require('path');
-const net = require('net');
-const dns = require('dns').promises;
-const { Agent, fetch: undiciFetch } = require('undici');
-
-const MAX_FILE_BYTES = 500 * 1024 * 1024; // 500 MB — larger than visual_dna because
-                                           // lipsync/v2v/transcription accept full
-                                           // videos and long audio tracks.
-const VISUAL_DNA_MAX_BYTES = 25 * 1024 * 1024; // kept for visual_dna backward-compat
-const REMOTE_FETCH_MAX_BYTES = 100 * 1024 * 1024;
-const MAX_REDIRECTS = 5;
-
-// THE single statement of how a local file gets into Kolbo. It is repeated to
-// the model on several surfaces — the server `instructions` block (src/index.js),
-// the media tool descriptions, and both local-path errors below — so it lives
-// here and is imported, not retyped. It was previously pasted in five places and
-// a change to it updated only two, leaving `instructions` teaching the opposite.
-const LOCAL_FILE_ROUTING =
-  'If you are using Kolbo over a remote connector (e.g. claude.ai), local files are not reachable. ' +
-  'DO NOT upload the file yourself with cloud credentials or a shell command — Kolbo has a tool for this. ' +
-  'If you can run shell commands, call `create_upload_ticket` and POST the file to the returned upload_url. ' +
-  'Otherwise call `media_upload_widget` to have the user pick the file, or `upload_media` ' +
-  'when the file IS reachable from where the MCP server runs, then pass the returned https:// URL here. ' +
-  'A URL from `list_media` also works if the asset is already in the library.';
-
-// Every tool that takes user media as INPUT. Their descriptions promise "URL or
-// absolute local path" — true on a stdio install, a lie over a remote connector,
-// where the model would read it, see no filesystem, and tell the user Kolbo
-// cannot take their file at all. attachFileInputHints() below appends the route
-// that actually works for the current transport, so the refusal never happens.
-const FILE_INPUT_TOOLS = [
-  'generate_image', 'generate_image_edit', 'generate_creative_director',
-  'generate_video', 'generate_video_from_image', 'generate_video_from_video',
-  'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
-  'generate_3d', 'edit_image', 'edit_video', 'transcribe_audio',
-  'create_visual_dna', 'update_visual_dna', 'generate_character_sheet', 'clone_voice',
-  'chat_send_message', 'create_moodboard', 'update_moodboard',
-  'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
-  'analyze_video'
-];
-
-const REMOTE_FILE_HINT =
-  ' LOCAL FILE (on the user\'s machine, or attached to this chat)? NEVER reply that you cannot upload files — Kolbo uploads it for you. ' +
-  'Call `media_upload_widget` so the user picks the file (claude.ai web/mobile), or `create_upload_ticket` and POST the file yourself if you can run shell/HTTP commands; ' +
-  'either way you get an https:// URL to pass here. Ignore any "absolute local path" wording in the args below — this server cannot read the caller\'s disk, so a path will fail.';
-
-const LOCAL_FILE_HINT =
-  ' LOCAL FILE? Absolute local paths work here (server and client share a filesystem). ' +
-  'Never reply that you cannot upload files — for a file you will reference more than once, call `upload_media` first and reuse the returned https:// URL. ' +
-  'IMAGE/VIDEO PASTED OR ATTACHED IN THIS CHAT with no path? You can see it but Kolbo cannot — NEVER substitute a text description of it for the file. ' +
-  'Call `media_upload_widget` so the user hands Kolbo the file (or ask for its path), then pass the returned URL — for "make this image X" use generate_image_edit with it in `source_images`.';
-const REMOTE_TEXT_FILE_HINT =
-  ' REMOTE FILE INPUT: This client cannot send local filesystem paths or render Kolbo\'s upload widget. ' +
-  'Use an existing public https:// URL. If the attachment has no public URL, ask the user to upload it in the Kolbo Media Library and paste the resulting URL; never invent a URL or claim a local path is usable here.';
-
-/**
- * Append the transport-correct local-file route to every media-input tool's
- * description, post-registration (same pattern as attachToolWidgetMeta).
- * `options.remote === true` is set only by kolbo-api's remote per-request
- * server. Do not use `appsEnabled()` as the transport signal: stdio hosts can
- * render widgets while still sharing a filesystem with this process.
- */
-function attachFileInputHints(server, options = {}) {
-  const hint = options.asyncGenerations
-    ? REMOTE_TEXT_FILE_HINT
-    : (options.remote === true || options.apps === true ? REMOTE_FILE_HINT : LOCAL_FILE_HINT);
-  const registered = server._registeredTools || {};
-  for (const name of FILE_INPUT_TOOLS) {
-    const t = registered[name];
-    if (t && typeof t.description === 'string' && !t.description.includes(hint)) {
-      t.description += hint;
-    }
-  }
-}
-
-// Per-kind upload caps advertised to callers when the ticket endpoint omits them.
-// Mirrors MAX_MB in kolbo-api src/modules/mcpConnector/upload.js.
-const DEFAULT_MAX_FILE_MB = { image: 50, video: 500, audio: 200, document: 50 };
-
-function isHttpUrl(s) {
-  return typeof s === 'string' && /^https?:\/\//i.test(s);
-}
-
-function isPrivateIPv4(ip) {
-  const parts = ip.split('.').map(Number);
-  if (parts.length !== 4 || parts.some(p => Number.isNaN(p) || p < 0 || p > 255)) return true;
-  const [a, b] = parts;
-  if (a === 10) return true;
-  if (a === 100 && b >= 64 && b <= 127) return true;
-  if (a === 127) return true;
-  if (a === 0) return true;
-  if (a === 169 && b === 254) return true; // includes 169.254.169.254 cloud metadata
-  if (a === 172 && b >= 16 && b <= 31) return true;
-  if (a === 192 && b === 168) return true;
-  if (a === 192 && b === 0 && parts[2] === 0) return true;
-  if (a === 198 && (b === 18 || b === 19)) return true;
-  if (a >= 224) return true;
-  return false;
-}
-
-function isPrivateIPv6(ip) {
-  const lower = ip.toLowerCase();
-  if (lower === '::' || lower === '::1') return true;
-  if (lower.startsWith('fe80:') || lower.startsWith('fe8') ||
-      lower.startsWith('fe9') || lower.startsWith('fea') ||
-      lower.startsWith('feb')) return true;
-  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
-  if (lower.startsWith('ff')) return true;
-  // IPv4-mapped / compat in dotted form: ::ffff:1.2.3.4 or ::1.2.3.4
-  const mappedDot = lower.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
-  if (mappedDot) return isPrivateIPv4(mappedDot[1]);
-  // IPv4-mapped in pure hex form: ::ffff:7f00:1 (Node normalizes
-  // ::ffff:127.0.0.1 → ::ffff:7f00:1). Extract last 2 hextets → 4 bytes.
-  const mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-  if (mappedHex) {
-    const hi = parseInt(mappedHex[1], 16);
-    const lo = parseInt(mappedHex[2], 16);
-    const dotted = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
-    return isPrivateIPv4(dotted);
-  }
-  return false;
-}
-
-function isBlockedHostname(hostname) {
-  // new URL('http://[::1]/').hostname returns "[::1]" (brackets kept).
-  // Strip them so net.isIP and our private-range checks see the bare address.
-  let host = hostname.toLowerCase();
-  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
-  const blockedNames = new Set([
-    'localhost',
-    'ip6-localhost',
-    'ip6-loopback',
-    'metadata.google.internal',
-    'metadata.goog'
-  ]);
-  if (blockedNames.has(host)) return true;
-  if (host.endsWith('.local') || host.endsWith('.internal') || host.endsWith('.localhost')) return true;
-  const ipFamily = net.isIP(host);
-  if (ipFamily === 4 && isPrivateIPv4(host)) return true;
-  if (ipFamily === 6 && isPrivateIPv6(host)) return true;
-  return false;
-}
-
-function assertSafeUrl(rawUrl) {
-  let u;
-  try { u = new URL(rawUrl); }
-  catch (_) { throw new Error(`Invalid URL: ${rawUrl}`); }
-  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
-    throw new Error(`Unsupported URL protocol "${u.protocol}" — only http/https allowed`);
-  }
-  if (isBlockedHostname(u.hostname)) {
-    throw new Error(`Refusing to fetch from private / loopback / metadata host: ${u.hostname}`);
-  }
-  return u;
-}
-
-async function resolvePublicAddresses(hostname) {
-  let host = hostname.toLowerCase();
-  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
-  const literalFamily = net.isIP(host);
-  if (literalFamily) return [{ address: host, family: literalFamily }];
-
-  let timer;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`DNS lookup timed out for ${host}`)), 3000);
-  });
-  let rows;
-  try {
-    rows = await Promise.race([dns.lookup(host, { all: true, verbatim: true }), timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
-  if (!rows.length) throw new Error(`DNS lookup returned no addresses for ${host}`);
-  for (const row of rows) {
-    const blocked = row.family === 4 ? isPrivateIPv4(row.address) : isPrivateIPv6(row.address);
-    if (blocked) throw new Error(`Refusing private / loopback / metadata DNS target for ${host}`);
-  }
-  return rows;
-}
-
-function pinnedDispatcher(addresses) {
-  let cursor = 0;
-  return new Agent({
-    connect: {
-      lookup(_hostname, options, callback) {
-        if (options?.all) return callback(null, addresses);
-        const row = addresses[cursor++ % addresses.length];
-        return callback(null, row.address, row.family);
-      },
-    },
-  });
-}
-
-async function safeFetch(rawUrl, opts = {}) {
-  let current = rawUrl;
-  for (let i = 0; i <= MAX_REDIRECTS; i++) {
-    const url = assertSafeUrl(current);
-    const addresses = await resolvePublicAddresses(url.hostname);
-    const dispatcher = pinnedDispatcher(addresses);
-    let res;
-    try {
-      res = await undiciFetch(current, { redirect: 'manual', signal: opts.signal, dispatcher });
-    } catch (err) {
-      await dispatcher.close().catch(() => {});
-      throw err;
-    }
-    if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
-      const next = new URL(res.headers.get('location'), current).toString();
-      await res.body?.cancel().catch(() => {});
-      await dispatcher.close().catch(() => {});
-      current = next;
-      continue;
-    }
-    // close() waits for this response body to be consumed, so schedule it but
-    // do not await it before returning the Response to the caller.
-    dispatcher.close().catch(() => {});
-    return res;
-  }
-  throw new Error(`Too many redirects fetching ${rawUrl}`);
-}
-
-async function discardResponse(res) {
-  try { await res?.body?.cancel(); } catch (_) {}
-}
-
-async function readResponseBuffer(res, maxBytes) {
-  if (!res?.body || typeof res.body.getReader !== 'function') {
-    throw new Error('Remote response has no readable body');
-  }
-  const reader = res.body.getReader();
-  const chunks = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const chunk = Buffer.from(value);
-      total += chunk.length;
-      if (total > maxBytes) {
-        await reader.cancel().catch(() => {});
-        throw new Error(`Remote response exceeds ${maxBytes}-byte limit`);
-      }
-      chunks.push(chunk);
-    }
-  } finally {
-    try { reader.releaseLock(); } catch (_) {}
-  }
-  return Buffer.concat(chunks, total);
-}
-
-function guessFilename(source, fallbackExt) {
-  if (isHttpUrl(source)) {
-    try {
-      const u = new URL(source);
-      const base = path.basename(u.pathname) || `upload${fallbackExt}`;
-      return base.includes('.') ? base : `${base}${fallbackExt}`;
-    } catch (_) {
-      return `upload${fallbackExt}`;
-    }
-  }
-  return path.basename(source);
-}
-
-function guessContentType(filename) {
-  const ext = path.extname(filename).toLowerCase();
-  const map = {
-    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
-    '.webp': 'image/webp', '.gif': 'image/gif', '.bmp': 'image/bmp',
-    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
-    '.mkv': 'video/x-matroska', '.avi': 'video/x-msvideo',
-    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
-    '.m4a': 'audio/mp4', '.flac': 'audio/flac', '.aac': 'audio/aac'
-  };
-  return map[ext] || 'application/octet-stream';
-}
-
-/**
- * Resolve a URL or absolute local path into an in-memory Buffer.
- *   - URLs: fetched via safeFetch (SSRF-guarded, manual redirect handling)
- *   - Local paths: read via fs.readFileSync (must be absolute)
- *
- * @param {string} source - URL or absolute local path
- * @param {'image'|'video'|'audio'} kind - hint for default filename extension
- * @param {Object} [opts]
- * @param {number} [opts.maxBytes] - override the default size cap
- * @returns {Promise<{buffer: Buffer, filename: string, contentType: string, size: number}>}
- */
-async function resolveToBuffer(source, kind, opts = {}) {
-  const requestedMaxBytes = opts.maxBytes || MAX_FILE_BYTES;
-  const maxBytes = opts.allowLocalFiles === false
-    ? Math.min(requestedMaxBytes, REMOTE_FETCH_MAX_BYTES)
-    : requestedMaxBytes;
-  const defaultExt = kind === 'image' ? '.png' : kind === 'video' ? '.mp4' : '.mp3';
-
-  if (isHttpUrl(source)) {
-    const res = await safeFetch(source);
-    if (!res.ok) {
-      await discardResponse(res);
-      throw new Error(`Failed to fetch ${source}: ${res.status} ${res.statusText}`);
-    }
-    const contentLen = parseInt(res.headers.get('content-length') || '0', 10);
-    if (contentLen && contentLen > maxBytes) {
-      await discardResponse(res);
-      throw new Error(`File at ${source} (${contentLen} bytes) exceeds ${maxBytes}-byte limit`);
-    }
-    const buffer = await readResponseBuffer(res, maxBytes);
-    const filename = guessFilename(source, defaultExt);
-    return {
-      buffer,
-      filename,
-      contentType: res.headers.get('content-type') || guessContentType(filename),
-      size: buffer.length
-    };
-  }
-
-  if (opts.allowLocalFiles === false) {
-    throw new Error(
-      'This remote connector accepts public https:// URLs only. Upload the file to the Kolbo Media Library and pass its public URL.'
-    );
-  }
-
-  if (!path.isAbsolute(source)) {
-    // `path.isAbsolute` is platform-specific: on a POSIX server (every remote
-    // connector deployment) a valid Windows path like `C:\Users\...` or
-    // `\\server\share\...` returns false, so "must be absolute" is a lie that
-    // sends the caller off retrying slash variants. `path.win32.isAbsolute`
-    // answers the same question with Node's own grammar.
-    throw new Error(
-      (path.win32.isAbsolute(source)
-        ? `This Kolbo server cannot read files off the calling machine, so the Windows path ${source} is unreachable from here. `
-        : `Local file paths must be absolute: ${source}. `) +
-      LOCAL_FILE_ROUTING
-    );
-  }
-  let stat;
-  try {
-    stat = fs.statSync(source);
-  } catch (err) {
-    throw new Error(
-      `Local file not found or unreadable: ${source}. ` +
-      LOCAL_FILE_ROUTING +
-      (err && err.code ? ` [${err.code}]` : '')
-    );
-  }
-  if (stat.size > maxBytes) {
-    throw new Error(`File ${source} (${stat.size} bytes) exceeds ${maxBytes}-byte limit`);
-  }
-  const buffer = fs.readFileSync(source);
-  const filename = path.basename(source);
-  return {
-    buffer,
-    filename,
-    contentType: guessContentType(filename),
-    size: buffer.length
-  };
-}
-
-// ─── 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.
-//
-// CRITICAL: when the poll window times out, we UNTRACK the generation so that
-// when the MCP host eventually aborts the tool call (e.g., at ~180s), it does
-// NOT cancel the server-side generation. The generation keeps running, and the
-// caller can collect it later with get_generation_status.
-const { pollUntilDone } = require('../polling');
-const progress = require('../progress');
-
-/**
- * @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;
-    // Untrack so the MCP host aborting this tool call does NOT cancel the generation.
-    progress.untrackGeneration(generationId);
-    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
- * `credits_breakdown` (per-CreditUsage detail) when the generation is
- * complete. Returns `{}` when the API didn't include them so spreading
- * the result into a tool's response object is a no-op (forward-compatible
- * with old kolbo-api versions).
- *
- * Usage in every generation tool:
- *   return {
- *     content: [{ type: 'text', text: JSON.stringify({
- *       urls: result.result.urls,
- *       model: result.result.model,
- *       ...creditFields(result),   // adds credits_used + credits_breakdown
- *       _followup_hint: '...',
- *     }, null, 2) }]
- *   };
- */
-function creditFields(polledResult) {
-  if (!polledResult) return {};
-  const out = {};
-  if (typeof polledResult.credits_used === 'number') {
-    out.credits_used = polledResult.credits_used;
-  }
-  if (Array.isArray(polledResult.credits_breakdown) && polledResult.credits_breakdown.length) {
-    out.credits_breakdown = polledResult.credits_breakdown;
-  }
-  return out;
-}
-
-// Shared zod schema for the optional `project_id` arg every generation tool
-// accepts. Keep this in one place so the description never drifts across the
-// 17 tools that use it. When omitted, the generation lands in the user's
-// auto-created "API Generations" project. Call `list_projects` first to
-// resolve a name → ObjectId.
-const { z } = require('zod');
-const projectIdField = z.string().optional().describe(
-  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). IMPORTANT: this is per-call, NOT sticky — once the user has named a working project, pass its id on EVERY generation call in the conversation; any call that omits it silently lands in the default "API Generations" project instead. Requires owner / edit / full permission on the project; view-only is rejected.'
-);
-
-// Shared zod schema for the optional `session_id` arg on generation tools.
-// WHY IT EXISTS: without it, each generation call gets its own session, so a
-// set of related clips lands in the app's left rail as a stack of near-identical
-// single-item sessions. (The server has a per-day fallback bucket, but it is not
-// something a caller can rely on — see kolbo-api sdkSessionManager.) Threading
-// the id returned by the FIRST call is the deterministic way to group a batch.
-const sessionIdField = z.string().optional().describe(
-  'Existing session to add this generation to, so a related set lands in ONE session instead of a stack of single-item sessions in the Kolbo sidebar. HOW TO USE: omit it on the FIRST call of a PLAN BUCKET (Cast, Locations, Props, or one Scene NN), read `session_id` off that result, `rename_session` to the plan name, then pass that SAME value on every follow-up in that bucket (another character, shot 2, a retake, "make it darker"). Only omit it again when the plan starts a NEW scene or NEW concept — never per take or per tool call. Image tools and video tools cannot share an id. `list_sessions` also returns ids. When set, `project_id` is ignored — the session\'s own project wins.'
-);
-
-// Read-scope variant for list/get tools that can surface a SHARED project's
-// assets (a teammate's Visual DNAs / moodboards). Pass a project id you have
-// edit+ on to also see that project owner's shared assets; omit to see only your
-// own + global/org. View-only members and non-members get nothing extra.
-const projectScopeReadField = z.string().optional().describe(
-  "Project ObjectId (from `list_projects`) to ALSO surface that shared project's assets (a teammate's, when the project is shared with you). Requires edit / full / owner on the project — view-only members and non-members get only their own. Omit to see just your own + global/org."
-);
-
-// ─── Optional inline-image content blocks ────────────────────────────────────
-// When a host opts in (the remote HTTP connector sets inlineImages:true), turn
-// generated IMAGE urls into MCP `image` content blocks so clients render them
-// inline instead of a "Show Image" link. Strictly gated + bounded:
-//   - only runs when opts.enabled is true (stdio/Kolbo Code never enables it,
-//     so their behavior is byte-identical: text URL only);
-//   - caps the number of images and the bytes per image;
-//   - ONLY embeds responses whose content-type is image/* — a video/audio URL
-//     can never be base64-embedded even if mistakenly passed in;
-//   - any fetch/decoding failure silently falls back to URL-only.
-const INLINE_IMG_MAX_COUNT = 4;
-// Cap kept conservative on purpose: a base64 image rides inside the JSON-RPC
-// tool result, and chat clients (claude.ai etc.) drop the WHOLE result if it's
-// too large — which looks like "no image at all". Anything over the cap is left
-// to the URL in the text payload (clients render a "Show Image" affordance from
-// it), so a big image degrades to a click instead of vanishing.
-const INLINE_IMG_MAX_BYTES = 1.5 * 1024 * 1024; // 1.5 MB per image
-const INLINE_IMG_FETCH_TIMEOUT_MS = 8000; // never hang the tool response on a slow CDN
-
-async function inlineImageBlocks(urls, opts = {}) {
-  if (!opts || !opts.enabled) return [];
-  if (!Array.isArray(urls) || urls.length === 0) return [];
-  // Fetch the (≤4) images in parallel — they're independent, the cap already
-  // bounds concurrency, and this sits on the connector response path right
-  // after generation. Order is preserved by map-then-filter; any failure (size,
-  // type, timeout, network) returns null and falls back to URL-only.
-  const maxCount = Math.min(INLINE_IMG_MAX_COUNT, Math.max(1, Number(opts.maxCount) || INLINE_IMG_MAX_COUNT));
-  const maxBytes = Math.min(INLINE_IMG_MAX_BYTES, Math.max(1, Number(opts.maxBytes) || INLINE_IMG_MAX_BYTES));
-  const fetchTimeoutMs = Math.min(INLINE_IMG_FETCH_TIMEOUT_MS, Math.max(1, Number(opts.fetchTimeoutMs) || INLINE_IMG_FETCH_TIMEOUT_MS));
-  const blocks = await Promise.all(
-    urls.slice(0, maxCount).map(async (url) => {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), fetchTimeoutMs);
-      try {
-        if (typeof url !== 'string' || !isHttpUrl(url)) return null;
-        const res = await safeFetch(url, { signal: controller.signal });
-        if (!res.ok) {
-          await discardResponse(res);
-          return null;
-        }
-        const contentType = (res.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
-        if (!contentType.startsWith('image/')) {
-          await discardResponse(res);
-          return null; // never embed non-images
-        }
-        const declaredLen = Number(res.headers.get('content-length') || 0);
-        if (declaredLen && declaredLen > maxBytes) {
-          await discardResponse(res);
-          return null;
-        }
-        const buffer = await readResponseBuffer(res, maxBytes);
-        return { type: 'image', data: buffer.toString('base64'), mimeType: contentType };
-      } catch (_) {
-        return null;
-      } finally {
-        clearTimeout(timer);
-      }
-    })
-  );
-  return blocks.filter(Boolean);
-}
-
-// ─── "Open in Kolbo" deep links ───────────────────────────────────────────────
-// kolbo-api submit responses include `session_id` + `project_id`. Map each MCP
-// tool to the frontend page + tool slug whose session view can RESUME that
-// session (mirrors kolbo-map src/constants/sessionTypes.js resumeUrl map — the
-// route must match the SESSION MODEL the SDK created, per sdkSessionManager):
-//   ImageSession (image AND image_edit) → /image-tools?tool=create-image
-//   imgEditSession (edit_image / global_image_edit — the Canvas) → /image-tools?tool=canvas
-//   imgToVideoSession (video, video_from_image, elements, first_last_frame)
-//     → /video-tools?tool=create-video
-//   videoToVideoSession → /video-tools?tool=video-to-video
-//   lipsyncSession → /video-tools?tool=lipsync
-//   MusicGeneratorSession / TextToSpeechSession / textToSoundSession /
-//   speechToTextSession → /audio-tools with the matching slug
-//   CreativeDirectorSession → /creative-director?session=... (no tool param)
-// RETIRED — do NOT reintroduce as separate destinations. "Image Editing" folded
-// into Create Image and "Text to Video" folded into Create Video (a mode inside
-// it); sdkSessionManager already routes image_edit → ImageSession and video →
-// imgToVideoSession. The old ?tool=image-editing / ?tool=text-to-video slugs
-// still redirect, but nothing new should emit them.
-// Intentionally ABSENT (no deep-linkable session page — widget falls back to
-// plain https://app.kolbo.ai): edit_video (GlobalVideoEditSession has no
-// session deep-link), generate_3d (project-scoped, no session), shorts render.
-const APP_BASE_URL = 'https://app.kolbo.ai';
-const OPEN_URL_ROUTES = {
-  generate_image:             { path: '/image-tools', tool: 'create-image' },
-  generate_image_edit:        { path: '/image-tools', tool: 'create-image' },
-  edit_image:                 { path: '/image-tools', tool: 'canvas' },
-  generate_video:             { path: '/video-tools', tool: 'create-video' },
-  generate_video_from_image:  { path: '/video-tools', tool: 'create-video' },
-  generate_elements:          { path: '/video-tools', tool: 'create-video', mode: 'elements' },
-  generate_first_last_frame:  { path: '/video-tools', tool: 'create-video', mode: 'first-last' },
-  generate_video_from_video:  { path: '/video-tools', tool: 'video-to-video' },
-  generate_lipsync:           { path: '/video-tools', tool: 'lipsync' },
-  generate_music:             { path: '/audio-tools', tool: 'music-generator' },
-  generate_speech:            { path: '/audio-tools', tool: 'text-to-speech' },
-  generate_sound:             { path: '/audio-tools', tool: 'text-to-sound' },
-  transcribe_audio:           { path: '/audio-tools', tool: 'speech-to-text' },
-  generate_creative_director: { path: '/creative-director' },
-};
-// SDK tracking `type` on get_generation_status — same session model as the
-// generate_* tool that created the job, so "Open in Kolbo" still deep-links
-// after a status poll overwrites the live card.
-const TYPE_TO_TOOL = {
-  image: 'generate_image',
-  image_edit: 'generate_image_edit',
-  global_image_edit: 'edit_image',
-  video: 'generate_video',
-  video_from_image: 'generate_video_from_image',
-  elements: 'generate_elements',
-  first_last_frame: 'generate_first_last_frame',
-  video_from_video: 'generate_video_from_video',
-  lipsync: 'generate_lipsync',
-  music: 'generate_music',
-  speech: 'generate_speech',
-  sound: 'generate_sound',
-  transcription: 'transcribe_audio',
-  creative_director: 'generate_creative_director',
-};
-
-function sessionOf(gen) {
-  if (!gen || typeof gen !== 'object') return undefined;
-  return gen.session_id || gen.sessionId || undefined;
-}
-
-function projectOf(gen) {
-  if (!gen || typeof gen !== 'object') return undefined;
-  return gen.project_id || gen.projectId || undefined;
-}
-
-/**
- * Build the "Open in Kolbo" deep link for a generation's actual session.
- * Returns undefined (widget falls back to app.kolbo.ai) when the tool has no
- * deep-linkable page or the submit response carried no session_id (older
- * kolbo-api, shorts render, 3D).
- */
-function buildOpenUrl(tool, gen) {
-  const sid = sessionOf(gen);
-  if (!sid) return undefined;
-  const key = OPEN_URL_ROUTES[tool] ? tool : (TYPE_TO_TOOL[gen && gen.type] || TYPE_TO_TOOL[tool]);
-  const route = OPEN_URL_ROUTES[key];
-  if (!route) return undefined;
-  let url = `${APP_BASE_URL}${route.path}?session=${encodeURIComponent(sid)}`;
-  if (route.tool) url += `&tool=${route.tool}`;
-  if (route.mode) url += `&mode=${route.mode}`;
-  const pid = projectOf(gen);
-  if (pid) url += `&project=${encodeURIComponent(pid)}`;
-  return url;
-}
-
-function linkFields(tool, gen) {
-  const sid = sessionOf(gen);
-  const pid = projectOf(gen);
-  const href = buildOpenUrl(tool, gen);
-  return {
-    ...(sid ? { session_id: String(sid) } : {}),
-    ...(pid ? { project_id: String(pid) } : {}),
-    ...(href ? { open_url: href } : {}),
-  };
-}
-
-/**
- * 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
-// ui://kolbo/generation.html widget takes over: live progress, inline result,
-// action buttons. Text-only hosts never enter this path — their blocking
-// behavior and response bytes are UNCHANGED.
-const { UI, uiResult, appsEnabled, modelInfo } = require('../apps');
-
-/**
- * Chip identity for a model: the CLEAN display name + its icon, resolved from
- * the same /v1/models catalog `list_models` renders. Callers pass whatever the
- * user/LLM supplied (an identifier like `google_tts`, `fal-ai/…/omnihuman/v1.5`,
- * or a display name) — the card must never show the raw id.
- */
-async function modelChipFields(client, model) {
-  const info = await modelInfo(client, model).catch(() => null);
-  return {
-    model: model || 'Smart Select',
-    model_name: (info && info.name) || model || 'Smart Select',
-    model_icon: (info && info.icon) || null,
-  };
-}
-
-/**
- * Resolve `visual_dna_ids` to {id, name, thumbnail} so the card can show WHICH
- * characters are locked in, not just how many. An id tells the user nothing;
- * the face does.
- *
- * One list fetch per process, cached — the DNA catalog barely moves within a
- * session, and a generation card must never add a round-trip per chip. A miss
- * (id not in the caller's own DNAs) degrades to the bare id, which is exactly
- * what the card showed before.
- */
-const _dnaChipCache = new Map();
-let _dnaChipLoaded = 0;
-const DNA_CHIP_TTL = 5 * 60 * 1000;
-
-function dnaThumb(row) {
-  if (!row || typeof row !== 'object') return null;
-  const first = Array.isArray(row.images) ? row.images[0] : null;
-  return row.sheet_url
-    || row.thumbnail_url
-    || row.characterSheet
-    || (typeof first === 'string' ? first : first && first.url)
-    || null;
-}
-
-function rememberDna(row, fallbackId) {
-  if (!row || typeof row !== 'object') return null;
-  const id = String(row.id || row._id || fallbackId || '');
-  if (!id) return null;
-  const rec = { id, name: row.name || id, thumbnail: dnaThumb(row) };
-  _dnaChipCache.set(id, rec);
-  return rec;
-}
-
-async function resolveVisualDnas(client, ids) {
-  const list = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id) : [];
-  if (!list.length) return [];
-
-  const stale = Date.now() - _dnaChipLoaded > DNA_CHIP_TTL;
-  if (stale || list.some((id) => !_dnaChipCache.has(id))) {
-    try {
-      const res = await client.get('/v1/visual-dna?scope=mine');
-      const rows = res?.visual_dnas || res?.data || [];
-      for (const row of rows) rememberDna(row);
-      _dnaChipLoaded = Date.now();
-    } catch {
-      // Offline / rate-limited — fall through to per-id fetch.
-    }
-  }
-
-  // scope=mine misses global / shared / teammate DNAs. The generating card
-  // then printed "1 Visual DNA" with no face. Fetch the missing ids directly.
-  const missing = list.filter((id) => !_dnaChipCache.has(id));
-  if (missing.length) {
-    await Promise.all(missing.map(async (id) => {
-      try {
-        const res = await client.get(`/v1/visual-dna/${encodeURIComponent(id)}`);
-        rememberDna(res && res.visual_dna ? res.visual_dna : res, id);
-      } catch {
-        // Leave the bare id — the chip still names it.
-      }
-    }));
-  }
-
-  return list.map((id) => _dnaChipCache.get(id) || { id, name: id, thumbnail: null });
-}
-
-const _presetCache = new Map();
-let _presetLoaded = 0;
-const PRESET_TTL = 10 * 60 * 1000;
-
-async function resolvePreset(client, presetId) {
-  if (!presetId) return null;
-  const key = String(presetId);
-  const stale = Date.now() - _presetLoaded > PRESET_TTL;
-  if (!stale && _presetCache.has(key)) return _presetCache.get(key);
-  if (stale || _presetCache.size === 0) {
-    try {
-      const res = await client.get('/v1/presets');
-      for (const row of res?.presets || res?.data || []) {
-        const id = row?.id || row?._id || row?.identifier;
-        if (!id) continue;
-        _presetCache.set(String(id), {
-          id: String(id),
-          name: row.name || String(id),
-          thumbnail: row.thumbnail_url || row.thumbnail || null,
-        });
-      }
-      _presetLoaded = Date.now();
-    } catch {
-      // Offline — the chip keeps the word "preset".
-    }
-  }
-  return _presetCache.get(key) || null;
-}
-
-async function decorateSettings(client, settings) {
-  const s = { ...(settings || {}) };
-  if (!s.preset_id) return s;
-  const preset = await resolvePreset(client, s.preset_id);
-  if (!preset) return s;
-  return {
-    ...s,
-    preset_name: preset.name,
-    ...(preset.thumbnail ? { preset_thumbnail: preset.thumbnail } : {}),
-  };
-}
-
-const _mbChipCache = new Map();
-let _mbChipLoaded = 0;
-
-function rememberMoodboard(row, fallbackId) {
-  if (!row || typeof row !== 'object') return null;
-  const id = String(row.id || row._id || fallbackId || '');
-  if (!id) return null;
-  const rec = {
-    id,
-    name: row.name || id,
-    thumbnail: row.thumbnail_url || row.thumbnail || row.cover_url || (Array.isArray(row.images) ? row.images[0] : null) || null,
-  };
-  _mbChipCache.set(id, rec);
-  return rec;
-}
-
-async function resolveMoodboards(client, ids) {
-  const list = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id) : [];
-  if (!list.length) return [];
-  const stale = Date.now() - _mbChipLoaded > DNA_CHIP_TTL;
-  if (stale || list.some((id) => !_mbChipCache.has(id))) {
-    try {
-      const res = await client.get('/v1/moodboards');
-      for (const row of res?.moodboards || res?.data || []) rememberMoodboard(row);
-      _mbChipLoaded = Date.now();
-    } catch { /* fall through to per-id */ }
-  }
-  const missing = list.filter((id) => !_mbChipCache.has(id));
-  if (missing.length) {
-    await Promise.all(missing.map(async (id) => {
-      try {
-        const res = await client.get(`/v1/moodboards/${encodeURIComponent(id)}`);
-        rememberMoodboard(res && res.moodboard ? res.moodboard : res, id);
-      } catch { /* bare id */ }
-    }));
-  }
-  return list.map((id) => _mbChipCache.get(id) || { id, name: id, thumbnail: null });
-}
-
-function mediaRefs(p) {
-  const images = Array.isArray(p.reference_images)
-    ? p.reference_images.filter(Boolean)
-    : (p.reference_image ? [p.reference_image] : []);
-  return {
-    // Omitted when empty: a live card MERGES status payloads over its own
-    // state, so a present-but-empty reference_images (the single-id status
-    // path has no input refs of its own) wiped the submit-time thumbnails
-    // off the finished card.
-    ...(images.length ? { reference_images: images, reference_image: p.reference_image || images[0] } : {}),
-    ...(Array.isArray(p.reference_videos) && p.reference_videos.length
-      ? { reference_videos: p.reference_videos.filter(Boolean) } : {}),
-    ...(Array.isArray(p.reference_audio) && p.reference_audio.length
-      ? { reference_audio: p.reference_audio.filter(Boolean) } : {}),
-  };
-}
-
-function moodboardIds(settings) {
-  const s = settings || {};
-  if (Array.isArray(s.moodboard_ids) && s.moodboard_ids.length) return s.moodboard_ids;
-  return s.moodboard_id ? [s.moodboard_id] : [];
-}
-
-/**
- * Build the "submitted — widget is live" tool result for a UI host.
- * @param {object} p
- *   tool           MCP tool name (e.g. 'generate_image')
- *   kind           'image' | 'video' | 'audio' | '3d' | 'scenes'
- *   gen            the submit response ({ generation_id, poll_interval_hint })
- *   client         KolboClient (for model icon lookup)
- *   model, prompt, count, settings, reference_images, estimated_seconds
- *   voice          resolved voice record { name, thumbnail } (speech only)
- *   poll_tool      widget-side status tool (default 'get_generation_status')
- *   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.
-  const chip = await modelChipFields(p.client, p.model);
-  const settings = await decorateSettings(p.client, p.settings || {});
-  const structured = {
-    phase: 'generating',
-    widget: 'generation',
-    kind: p.kind,
-    tool: p.tool,
-    generation_id: p.gen.generation_id,
-    poll_tool: p.poll_tool || 'get_generation_status',
-    // 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 },
-    ...chip,
-    ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
-    prompt: p.prompt,
-    count: p.count || 1,
-    settings,
-    visual_dnas: await resolveVisualDnas(p.client, settings.visual_dna_ids),
-    moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
-    // `reference_image` is retained for older widget builds. New widgets render
-    // every browser-loadable image supplied to the generation.
-    ...mediaRefs(p),
-    ...linkFields(p.tool, p.gen),
-  };
-  // Batch mode (prompts[] fan-out): ONE widget tracks every id in the set.
-  if (Array.isArray(p.generation_ids) && p.generation_ids.length > 1) {
-    structured.generation_ids = p.generation_ids;
-    structured.prompts = p.prompts;
-  }
-  const text = JSON.stringify({
-    status: 'submitted',
-    generation_id: p.gen.generation_id,
-    // The session this landed in. Pass it back as `session_id` on the next call
-    // of the same set to keep the whole set in one session (see sessionIdField).
-    session_id: p.gen.session_id,
-    ...(Array.isArray(p.generation_ids) && p.generation_ids.length > 1
-      ? { batch: true, generation_ids: p.generation_ids } : {}),
-    ...(p.failed_submissions && p.failed_submissions.length
-      ? { failed_submissions: p.failed_submissions } : {}),
-    ...(p.warning ? { _warning: p.warning } : {}),
-    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update. CREDIT GUARD: END YOUR TURN now — do not keep Thinking, writing skills/files, or planning while the card spins (that burns coding credits). Do NOT poll in a loop. If you need the output URLs for a follow-up step, call get_generation_status ONCE with wait=true as the only next tool — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
-    _paid_note: 'This generation is RUNNING and the user is paying for it. If you now realize the tool, model, or parameters were wrong, call cancel_generation with this generation_id FIRST, then start the replacement — never leave a wrong generation running alongside its retry (the user gets two cards and two charges).',
-  }, null, 2);
-  return uiResult(UI.generation, text, structured);
-}
-
-/**
- * Return a paid generation immediately for hosts that cannot render MCP Apps
- * and enforce short tool-call timeouts (for example Manus custom MCP). This is
- * deliberately plain MCP content: no ui:// resource and no promise of a card.
- * The existing get_generation_status tool is the durable status endpoint.
- */
-function asyncGenerating(p) {
-  const ids = Array.isArray(p.generation_ids) && p.generation_ids.length
-    ? p.generation_ids
-    : [p.gen.generation_id].filter(Boolean);
-  const defaultStatusArgs = ids.length > 1
-    ? { generation_ids: ids, wait: false }
-    : { generation_id: ids[0], wait: false };
-  const pollTool = p.poll_tool || 'get_generation_status';
-  const statusArgs = { ...(p.status_args || defaultStatusArgs), wait: false };
-  const structured = {
-    status: 'submitted',
-    generation_id: p.gen.generation_id,
-    session_id: p.gen.session_id,
-    ...(ids.length > 1 ? { batch: true, generation_ids: ids } : {}),
-    ...(p.failed_submissions && p.failed_submissions.length
-      ? { failed_submissions: p.failed_submissions } : {}),
-    ...(p.warning ? { warning: p.warning } : {}),
-    poll_tool: pollTool,
-    status_args: statusArgs,
-    next_action: `The job is running. Do not submit it again. When the result is needed, call ${pollTool} with the supplied status_args. If it is still processing, tell the user and check again later; do not poll in a tight loop.`,
-    paid_job_notice: ids.length > 1
-      ? `This is a paid batch. Only if the user asks to stop or approves a replacement, cancel every running generation first: ${ids.join(', ')}.`
-      : 'This is a paid generation. Only if the user asks to stop or approves a replacement, cancel this generation before starting the replacement.',
-  };
-  return {
-    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-    structuredContent: structured,
-  };
-}
-
-/**
- * Wrap an already-completed generation result with the widget.
- *
- * Used by tools that stay blocking even on UI hosts (creative director), AND —
- * since structuredContent costs a text host nothing — by every generation tool
- * on its normal blocking return. That second case is why model names, model
- * avatars and Visual DNA chips were missing in Kolbo Code: it does not advertise
- * MCP Apps, so `ui()` is false, `uiGenerating` never runs, and the host had to
- * rebuild the card from raw text that carries only a model IDENTIFIER. Shipping
- * the resolved payload here fixes every non-Apps host at once, exactly the way
- * the list tools already do it (see listResult).
- *
- * The TEXT is unchanged, so text-only hosts see precisely what they saw before.
- */
-function preferOwnedUrls(urls) {
-  const list = Array.isArray(urls) ? urls.filter((item) => typeof item === 'string' && item) : [];
-  const ours = list.filter((item) => {
-    try {
-      const host = new URL(item).hostname;
-      return /(?:^|\.)kolbo\.ai$/.test(host) || /digitaloceanspaces\.com$/.test(host);
-    } catch {
-      return false;
-    }
-  });
-  return ours.length ? ours : (list.length ? list : urls);
-}
-
-async function uiCompleted(p, textPayload, extraContent) {
-  const chip = await modelChipFields(p.client, p.model);
-  const settings = p.settings ? await decorateSettings(p.client, p.settings) : undefined;
-  const structured = {
-    phase: 'completed',
-    widget: 'generation',
-    kind: p.kind,
-    tool: p.tool,
-    ...chip,
-    prompt: p.prompt,
-    count: p.count || 1,
-    // 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 || {}`.
-    ...(settings ? { settings } : {}),
-    visual_dnas: await resolveVisualDnas(p.client, (settings || {}).visual_dna_ids),
-    moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
-    ...mediaRefs(p),
-    urls: preferOwnedUrls(p.urls),
-    thumbnail_url: p.thumbnail_url,
-    title: p.title,
-    duration: p.duration,
-    scenes: p.scenes,
-    // Independent per-item results (get_generation_status checking several ids
-    // at once) — each one carries its OWN state/media, unlike `scenes`/`urls`
-    // above which assume everything finished together. Only set when the
-    // caller actually has this shape; every existing caller is unaffected.
-    ...(Array.isArray(p.items) ? { items: p.items } : {}),
-    // Transcription payload. get_generation_status is the ONLY way the live
-    // transcript widget learns its result, and it reads text/srt_url/txt_url off
-    // this object — but uiCompleted is shaped for the generation card and
-    // dropped every one, so a finished transcription rendered "(empty
-    // transcript)" with no SRT/TXT buttons while the text sat in the status
-    // response. structuredContent SHADOWS the text block on widget hosts, so
-    // omitting a field here is the same as deleting it.
-    ...(typeof p.text === 'string' ? { text: p.text } : {}),
-    ...(p.srt_url ? { srt_url: p.srt_url } : {}),
-    ...(p.word_by_word_srt_url ? { word_by_word_srt_url: p.word_by_word_srt_url } : {}),
-    ...(p.txt_url ? { txt_url: p.txt_url } : {}),
-    ...(p.audio_url ? { audio_url: p.audio_url } : {}),
-    // The voice, by name and portrait. uiGenerating has carried this since the
-    // chips were introduced; uiCompleted never did, so it silently dropped a
-    // resolved voice its caller had already looked up — every FINISHED speech
-    // card fell back to `settings.voice`, printing a raw ElevenLabs id where the
-    // name belongs and rendering the generic note placeholder instead of the
-    // voice's face. Exactly the "never show a raw id on a card" rule, broken on
-    // the one path the user actually ends up looking at.
-    ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
-    // The RAW generation state, when the caller has one. `phase` above is
-    // hardcoded 'completed' — it means "this tool call finished", not "the
-    // generation finished" — so a status check on a still-running job looked
-    // done to every reader. A live generation card polls get_generation_status
-    // from its own iframe and reads `state` FIRST; without it, a processing job
-    // resolved as completed-with-no-media and painted a red failure card.
-    ...(p.state ? { state: p.state } : {}),
-    credits_used: p.credits_used,
-    ...linkFields(p.tool, p.gen),
-  };
-  const out = uiResult(UI.generation, textPayload, structured);
-  if (Array.isArray(extraContent) && extraContent.length) {
-    out.content = [...out.content, ...extraContent];
-  }
-  return out;
-}
-
-// ─── Text-payload budget ─────────────────────────────────────────────────────
-//
-// Whatever a tool returns as TEXT is what the model actually reads, and hosts
-// reject or spill-to-disk anything much past this. A list tool that dumps every
-// field of every row blows it instantly: list_presets measured 632,919 chars,
-// get_stock_categories 257,817, list_voices 190,286 — all pretty-printed with
-// `JSON.stringify(x, null, 2)` and no cap. The widget path already slims rows to
-// id/title/thumbnail; the text path has to do the same or the tool is unusable
-// on exactly the text hosts (Claude Code, Cursor, Codex) that depend on it.
-const MAX_TEXT_CHARS = 20000;
-
-/**
- * Build a compact text payload for a list-shaped result.
- *
- * @param {object[]} items   rows from the API
- * @param {object}   opts
- * @param {string[]} opts.fields  keys to keep per row, in order (others dropped)
- * @param {number}   [opts.cap]   max rows to include (default 50)
- * @param {number}   [opts.total] true total, so the model knows more exist
- * @param {object}   [opts.extra] extra top-level keys to merge in
- * @param {string}   [opts.note]  guidance on how to fetch the rest
- */
-function compactList(items, { fields, cap = 50, total, extra, note } = {}) {
-  const rows = Array.isArray(items) ? items : [];
-  const kept = rows.slice(0, cap).map((row) => {
-    if (!row || typeof row !== 'object') return row;
-    const out = {};
-    for (const f of fields || Object.keys(row)) {
-      // Drop empties — a row of nulls costs tokens and tells the model nothing.
-      if (row[f] !== undefined && row[f] !== null && row[f] !== '') out[f] = row[f];
-    }
-    return out;
-  });
-
-  const payload = { ...(extra || {}), items: kept, count: kept.length };
-  if (total != null) payload.total = total;
-  const omitted = Math.max(rows.length - kept.length, 0);
-  if (omitted > 0 || (total != null && total > kept.length)) {
-    payload._truncated = {
-      omitted_from_this_page: omitted,
-      hint: note || 'Narrow with the tool\'s filter args, or page for more.',
-    };
-  }
-
-  let text = JSON.stringify(payload);
-  if (text.length > MAX_TEXT_CHARS) {
-    // Still too big even trimmed (very long descriptions). Halve until it fits
-    // rather than returning something the host will truncate at a random byte.
-    let n = kept.length;
-    while (n > 1 && text.length > MAX_TEXT_CHARS) {
-      n = Math.floor(n / 2);
-      payload.items = kept.slice(0, n);
-      payload.count = n;
-      payload._truncated = {
-        omitted_from_this_page: rows.length - n,
-        hint: note || 'Result was too large for one response; narrow with filter args.',
-      };
-      text = JSON.stringify(payload);
-    }
-  }
-  return text;
-}
-
-/**
- * Turn a 403 INSUFFICIENT_CREDITS into the plans/upgrade card.
- *
- * Without this the user just sees the raw API sentence and has to go find the
- * pricing page themselves. The card states the shortfall, shows live
- * promo-adjusted plans, and links to app.kolbo.ai/pricing.
- *
- * Returns null for any other error so callers can rethrow untouched. The plan
- * fetch is best-effort: if it fails we still return a card carrying the
- * balance/shortfall and the pricing link, because the ONE thing this path must
- * never do is swallow the reason the generation did not run.
- */
-async function insufficientCreditsResult(client, err) {
-  if (!err || err.code !== 'INSUFFICIENT_CREDITS') return null;
-
-  let data = null;
-  try {
-    data = await client.get('/v1/account/plans');
-  } catch {
-    // Offline / rate-limited — fall through to the minimal card.
-  }
-
-  const balance = err.data?.balance ?? data?.credits?.total;
-  const required = err.data?.required;
-  const structured = {
-    widget: 'plans',
-    reason: 'insufficient_credits',
-    balance,
-    required,
-    shortfall: (Number.isFinite(balance) && Number.isFinite(required))
-      ? Math.max(0, required - balance) : undefined,
-    current_plan: data?.current_plan || null,
-    plans: data?.plans || [],
-    credit_packs: data?.credit_packs || [],
-    pricing_url: err.data?.pricing_url || data?.pricing_url || 'https://app.kolbo.ai/pricing',
-  };
-
-  // structuredContent shadows the text on widget hosts, so the refusal reason
-  // has to be inside the object too — an agent that only reads structured
-  // content must still understand that nothing was generated.
-  structured.error = err.message;
-  structured._hint = 'The generation did NOT run and nothing was charged. An upgrade card is shown to the user. Tell them they are out of credits and point at the card; do not retry the generation, and do not attempt to purchase anything for them.';
-
-  const text = JSON.stringify({
-    error: err.message,
-    code: 'INSUFFICIENT_CREDITS',
-    balance,
-    required,
-    pricing_url: structured.pricing_url,
-    _hint: structured._hint,
-  }, null, 2);
-
-  return uiResult(UI.plans, text, structured);
-}
-
-module.exports = {
-  MAX_FILE_BYTES,
-  MAX_TEXT_CHARS,
-  compactList,
-  VISUAL_DNA_MAX_BYTES,
-  LOCAL_FILE_ROUTING,
-  FILE_INPUT_TOOLS,
-  attachFileInputHints,
-  DEFAULT_MAX_FILE_MB,
-  isHttpUrl,
-  assertSafeUrl,
-  safeFetch,
-  readResponseBuffer,
-  guessFilename,
-  guessContentType,
-  resolveToBuffer,
-  pollOrTimedOut,
-  creditFields,
-  projectIdField,
-  sessionIdField,
-  projectScopeReadField,
-  inlineImageBlocks,
-  buildOpenUrl,
-  linkFields,
-  buildProjectUrl,
-  uiGenerating,
-  asyncGenerating,
-  uiCompleted,
-  insufficientCreditsResult,
-  appsEnabled,
-};
+/* Shared helpers for MCP tools. No server.tool() registrations here.
+ *
+ * This file centralizes the URL-or-local-path → Buffer resolver used by
+ * every tool that accepts file-ish arguments (visual_dna, elements,
+ * first_last_frame, lipsync, video_from_video, transcription, media upload,
+ * future additions). It also owns the SSRF guard applied to any URL we
+ * fetch on the user's local machine.
+ *
+ * SSRF defense in depth:
+ *   1. Only http: / https: protocols.
+ *   2. Block IP literals in private / loopback / link-local / multicast /
+ *      reserved ranges (IPv4 and IPv6).
+ *   3. Block common internal hostnames (localhost, *.local, *.internal,
+ *      metadata.google.internal, metadata.goog).
+ *   4. Manual redirect following so every hop is re-validated (a crafted
+ *      public URL could 302 to 169.254.169.254 — global fetch would follow
+ *      silently).
+ *
+ * If you add a new tool that fetches URLs, import resolveToBuffer from here
+ * rather than reinventing the guard.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+const dns = require('dns').promises;
+const { Agent, fetch: undiciFetch } = require('undici');
+
+const MAX_FILE_BYTES = 500 * 1024 * 1024; // 500 MB — larger than visual_dna because
+                                           // lipsync/v2v/transcription accept full
+                                           // videos and long audio tracks.
+const VISUAL_DNA_MAX_BYTES = 25 * 1024 * 1024; // kept for visual_dna backward-compat
+const REMOTE_FETCH_MAX_BYTES = 100 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+
+// THE single statement of how a local file gets into Kolbo. It is repeated to
+// the model on several surfaces — the server `instructions` block (src/index.js),
+// the media tool descriptions, and both local-path errors below — so it lives
+// here and is imported, not retyped. It was previously pasted in five places and
+// a change to it updated only two, leaving `instructions` teaching the opposite.
+const LOCAL_FILE_ROUTING =
+  'If you are using Kolbo over a remote connector (e.g. claude.ai), local files are not reachable. ' +
+  'DO NOT upload the file yourself with cloud credentials or a shell command — Kolbo has a tool for this. ' +
+  'If you can run shell commands, call `create_upload_ticket` and POST the file to the returned upload_url. ' +
+  'Otherwise call `media_upload_widget` to have the user pick the file, or `upload_media` ' +
+  'when the file IS reachable from where the MCP server runs, then pass the returned https:// URL here. ' +
+  'A URL from `list_media` also works if the asset is already in the library.';
+
+// Every tool that takes user media as INPUT. Their descriptions promise "URL or
+// absolute local path" — true on a stdio install, a lie over a remote connector,
+// where the model would read it, see no filesystem, and tell the user Kolbo
+// cannot take their file at all. attachFileInputHints() below appends the route
+// that actually works for the current transport, so the refusal never happens.
+const FILE_INPUT_TOOLS = [
+  'generate_image', 'generate_image_edit', 'generate_creative_director',
+  'generate_video', 'generate_video_from_image', 'generate_video_from_video',
+  'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
+  'generate_3d', 'edit_image', 'edit_video', 'transcribe_audio',
+  'create_visual_dna', 'update_visual_dna', 'generate_character_sheet', 'clone_voice',
+  'chat_send_message', 'create_moodboard', 'update_moodboard',
+  'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
+  'analyze_video'
+];
+
+const REMOTE_FILE_HINT =
+  ' LOCAL FILE (on the user\'s machine, or attached to this chat)? NEVER reply that you cannot upload files — Kolbo uploads it for you. ' +
+  'Call `media_upload_widget` so the user picks the file (claude.ai web/mobile), or `create_upload_ticket` and POST the file yourself if you can run shell/HTTP commands; ' +
+  'either way you get an https:// URL to pass here. Ignore any "absolute local path" wording in the args below — this server cannot read the caller\'s disk, so a path will fail.';
+
+const LOCAL_FILE_HINT =
+  ' LOCAL FILE? Absolute local paths work here (server and client share a filesystem). ' +
+  'Never reply that you cannot upload files — for a file you will reference more than once, call `upload_media` first and reuse the returned https:// URL. ' +
+  'IMAGE/VIDEO PASTED OR ATTACHED IN THIS CHAT with no path? You can see it but Kolbo cannot — NEVER substitute a text description of it for the file. ' +
+  'Call `media_upload_widget` so the user hands Kolbo the file (or ask for its path), then pass the returned URL — for "make this image X" use generate_image_edit with it in `source_images`.';
+const REMOTE_TEXT_FILE_HINT =
+  ' REMOTE FILE INPUT: This client cannot send local filesystem paths or render Kolbo\'s upload widget. ' +
+  'Use an existing public https:// URL. If the attachment has no public URL, ask the user to upload it in the Kolbo Media Library and paste the resulting URL; never invent a URL or claim a local path is usable here.';
+
+/**
+ * Append the transport-correct local-file route to every media-input tool's
+ * description, post-registration (same pattern as attachToolWidgetMeta).
+ * `options.remote === true` is set only by kolbo-api's remote per-request
+ * server. Do not use `appsEnabled()` as the transport signal: stdio hosts can
+ * render widgets while still sharing a filesystem with this process.
+ */
+function attachFileInputHints(server, options = {}) {
+  const hint = options.asyncGenerations
+    ? REMOTE_TEXT_FILE_HINT
+    : (options.remote === true || options.apps === true ? REMOTE_FILE_HINT : LOCAL_FILE_HINT);
+  const registered = server._registeredTools || {};
+  for (const name of FILE_INPUT_TOOLS) {
+    const t = registered[name];
+    if (t && typeof t.description === 'string' && !t.description.includes(hint)) {
+      t.description += hint;
+    }
+  }
+}
+
+// Per-kind upload caps advertised to callers when the ticket endpoint omits them.
+// Mirrors MAX_MB in kolbo-api src/modules/mcpConnector/upload.js.
+const DEFAULT_MAX_FILE_MB = { image: 50, video: 500, audio: 200, document: 50 };
+
+function isHttpUrl(s) {
+  return typeof s === 'string' && /^https?:\/\//i.test(s);
+}
+
+function isPrivateIPv4(ip) {
+  const parts = ip.split('.').map(Number);
+  if (parts.length !== 4 || parts.some(p => Number.isNaN(p) || p < 0 || p > 255)) return true;
+  const [a, b] = parts;
+  if (a === 10) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 127) return true;
+  if (a === 0) return true;
+  if (a === 169 && b === 254) return true; // includes 169.254.169.254 cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 192 && b === 0 && parts[2] === 0) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+function isPrivateIPv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === '::' || lower === '::1') return true;
+  if (lower.startsWith('fe80:') || lower.startsWith('fe8') ||
+      lower.startsWith('fe9') || lower.startsWith('fea') ||
+      lower.startsWith('feb')) return true;
+  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
+  if (lower.startsWith('ff')) return true;
+  // IPv4-mapped / compat in dotted form: ::ffff:1.2.3.4 or ::1.2.3.4
+  const mappedDot = lower.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
+  if (mappedDot) return isPrivateIPv4(mappedDot[1]);
+  // IPv4-mapped in pure hex form: ::ffff:7f00:1 (Node normalizes
+  // ::ffff:127.0.0.1 → ::ffff:7f00:1). Extract last 2 hextets → 4 bytes.
+  const mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mappedHex) {
+    const hi = parseInt(mappedHex[1], 16);
+    const lo = parseInt(mappedHex[2], 16);
+    const dotted = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    return isPrivateIPv4(dotted);
+  }
+  return false;
+}
+
+function isBlockedHostname(hostname) {
+  // new URL('http://[::1]/').hostname returns "[::1]" (brackets kept).
+  // Strip them so net.isIP and our private-range checks see the bare address.
+  let host = hostname.toLowerCase();
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  const blockedNames = new Set([
+    'localhost',
+    'ip6-localhost',
+    'ip6-loopback',
+    'metadata.google.internal',
+    'metadata.goog'
+  ]);
+  if (blockedNames.has(host)) return true;
+  if (host.endsWith('.local') || host.endsWith('.internal') || host.endsWith('.localhost')) return true;
+  const ipFamily = net.isIP(host);
+  if (ipFamily === 4 && isPrivateIPv4(host)) return true;
+  if (ipFamily === 6 && isPrivateIPv6(host)) return true;
+  return false;
+}
+
+function assertSafeUrl(rawUrl) {
+  let u;
+  try { u = new URL(rawUrl); }
+  catch (_) { throw new Error(`Invalid URL: ${rawUrl}`); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`Unsupported URL protocol "${u.protocol}" — only http/https allowed`);
+  }
+  if (isBlockedHostname(u.hostname)) {
+    throw new Error(`Refusing to fetch from private / loopback / metadata host: ${u.hostname}`);
+  }
+  return u;
+}
+
+async function resolvePublicAddresses(hostname) {
+  let host = hostname.toLowerCase();
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  const literalFamily = net.isIP(host);
+  if (literalFamily) return [{ address: host, family: literalFamily }];
+
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`DNS lookup timed out for ${host}`)), 3000);
+  });
+  let rows;
+  try {
+    rows = await Promise.race([dns.lookup(host, { all: true, verbatim: true }), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!rows.length) throw new Error(`DNS lookup returned no addresses for ${host}`);
+  for (const row of rows) {
+    const blocked = row.family === 4 ? isPrivateIPv4(row.address) : isPrivateIPv6(row.address);
+    if (blocked) throw new Error(`Refusing private / loopback / metadata DNS target for ${host}`);
+  }
+  return rows;
+}
+
+function pinnedDispatcher(addresses) {
+  let cursor = 0;
+  return new Agent({
+    connect: {
+      lookup(_hostname, options, callback) {
+        if (options?.all) return callback(null, addresses);
+        const row = addresses[cursor++ % addresses.length];
+        return callback(null, row.address, row.family);
+      },
+    },
+  });
+}
+
+async function safeFetch(rawUrl, opts = {}) {
+  let current = rawUrl;
+  for (let i = 0; i <= MAX_REDIRECTS; i++) {
+    const url = assertSafeUrl(current);
+    const addresses = await resolvePublicAddresses(url.hostname);
+    const dispatcher = pinnedDispatcher(addresses);
+    let res;
+    try {
+      res = await undiciFetch(current, { redirect: 'manual', signal: opts.signal, dispatcher });
+    } catch (err) {
+      await dispatcher.close().catch(() => {});
+      throw err;
+    }
+    if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+      const next = new URL(res.headers.get('location'), current).toString();
+      await res.body?.cancel().catch(() => {});
+      await dispatcher.close().catch(() => {});
+      current = next;
+      continue;
+    }
+    // close() waits for this response body to be consumed, so schedule it but
+    // do not await it before returning the Response to the caller.
+    dispatcher.close().catch(() => {});
+    return res;
+  }
+  throw new Error(`Too many redirects fetching ${rawUrl}`);
+}
+
+async function discardResponse(res) {
+  try { await res?.body?.cancel(); } catch (_) {}
+}
+
+async function readResponseBuffer(res, maxBytes) {
+  if (!res?.body || typeof res.body.getReader !== 'function') {
+    throw new Error('Remote response has no readable body');
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = Buffer.from(value);
+      total += chunk.length;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {});
+        throw new Error(`Remote response exceeds ${maxBytes}-byte limit`);
+      }
+      chunks.push(chunk);
+    }
+  } finally {
+    try { reader.releaseLock(); } catch (_) {}
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function guessFilename(source, fallbackExt) {
+  if (isHttpUrl(source)) {
+    try {
+      const u = new URL(source);
+      const base = path.basename(u.pathname) || `upload${fallbackExt}`;
+      return base.includes('.') ? base : `${base}${fallbackExt}`;
+    } catch (_) {
+      return `upload${fallbackExt}`;
+    }
+  }
+  return path.basename(source);
+}
+
+function guessContentType(filename) {
+  const ext = path.extname(filename).toLowerCase();
+  const map = {
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+    '.webp': 'image/webp', '.gif': 'image/gif', '.bmp': 'image/bmp',
+    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+    '.mkv': 'video/x-matroska', '.avi': 'video/x-msvideo',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+    '.m4a': 'audio/mp4', '.flac': 'audio/flac', '.aac': 'audio/aac'
+  };
+  return map[ext] || 'application/octet-stream';
+}
+
+/**
+ * Resolve a URL or absolute local path into an in-memory Buffer.
+ *   - URLs: fetched via safeFetch (SSRF-guarded, manual redirect handling)
+ *   - Local paths: read via fs.readFileSync (must be absolute)
+ *
+ * @param {string} source - URL or absolute local path
+ * @param {'image'|'video'|'audio'} kind - hint for default filename extension
+ * @param {Object} [opts]
+ * @param {number} [opts.maxBytes] - override the default size cap
+ * @returns {Promise<{buffer: Buffer, filename: string, contentType: string, size: number}>}
+ */
+async function resolveToBuffer(source, kind, opts = {}) {
+  const requestedMaxBytes = opts.maxBytes || MAX_FILE_BYTES;
+  const maxBytes = opts.allowLocalFiles === false
+    ? Math.min(requestedMaxBytes, REMOTE_FETCH_MAX_BYTES)
+    : requestedMaxBytes;
+  const defaultExt = kind === 'image' ? '.png' : kind === 'video' ? '.mp4' : '.mp3';
+
+  if (isHttpUrl(source)) {
+    const res = await safeFetch(source);
+    if (!res.ok) {
+      await discardResponse(res);
+      throw new Error(`Failed to fetch ${source}: ${res.status} ${res.statusText}`);
+    }
+    const contentLen = parseInt(res.headers.get('content-length') || '0', 10);
+    if (contentLen && contentLen > maxBytes) {
+      await discardResponse(res);
+      throw new Error(`File at ${source} (${contentLen} bytes) exceeds ${maxBytes}-byte limit`);
+    }
+    const buffer = await readResponseBuffer(res, maxBytes);
+    const filename = guessFilename(source, defaultExt);
+    return {
+      buffer,
+      filename,
+      contentType: res.headers.get('content-type') || guessContentType(filename),
+      size: buffer.length
+    };
+  }
+
+  if (opts.allowLocalFiles === false) {
+    throw new Error(
+      'This remote connector accepts public https:// URLs only. Upload the file to the Kolbo Media Library and pass its public URL.'
+    );
+  }
+
+  if (!path.isAbsolute(source)) {
+    // `path.isAbsolute` is platform-specific: on a POSIX server (every remote
+    // connector deployment) a valid Windows path like `C:\Users\...` or
+    // `\\server\share\...` returns false, so "must be absolute" is a lie that
+    // sends the caller off retrying slash variants. `path.win32.isAbsolute`
+    // answers the same question with Node's own grammar.
+    throw new Error(
+      (path.win32.isAbsolute(source)
+        ? `This Kolbo server cannot read files off the calling machine, so the Windows path ${source} is unreachable from here. `
+        : `Local file paths must be absolute: ${source}. `) +
+      LOCAL_FILE_ROUTING
+    );
+  }
+  let stat;
+  try {
+    stat = fs.statSync(source);
+  } catch (err) {
+    throw new Error(
+      `Local file not found or unreadable: ${source}. ` +
+      LOCAL_FILE_ROUTING +
+      (err && err.code ? ` [${err.code}]` : '')
+    );
+  }
+  if (stat.size > maxBytes) {
+    throw new Error(`File ${source} (${stat.size} bytes) exceeds ${maxBytes}-byte limit`);
+  }
+  const buffer = fs.readFileSync(source);
+  const filename = path.basename(source);
+  return {
+    buffer,
+    filename,
+    contentType: guessContentType(filename),
+    size: buffer.length
+  };
+}
+
+// ─── 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.
+//
+// CRITICAL: when the poll window times out, we UNTRACK the generation so that
+// when the MCP host eventually aborts the tool call (e.g., at ~180s), it does
+// NOT cancel the server-side generation. The generation keeps running, and the
+// caller can collect it later with get_generation_status.
+const { pollUntilDone } = require('../polling');
+const progress = require('../progress');
+
+/**
+ * @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;
+    // Untrack so the MCP host aborting this tool call does NOT cancel the generation.
+    progress.untrackGeneration(generationId);
+    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
+ * `credits_breakdown` (per-CreditUsage detail) when the generation is
+ * complete. Returns `{}` when the API didn't include them so spreading
+ * the result into a tool's response object is a no-op (forward-compatible
+ * with old kolbo-api versions).
+ *
+ * Usage in every generation tool:
+ *   return {
+ *     content: [{ type: 'text', text: JSON.stringify({
+ *       urls: result.result.urls,
+ *       model: result.result.model,
+ *       ...creditFields(result),   // adds credits_used + credits_breakdown
+ *       _followup_hint: '...',
+ *     }, null, 2) }]
+ *   };
+ */
+function creditFields(polledResult) {
+  if (!polledResult) return {};
+  const out = {};
+  if (typeof polledResult.credits_used === 'number') {
+    out.credits_used = polledResult.credits_used;
+  }
+  if (Array.isArray(polledResult.credits_breakdown) && polledResult.credits_breakdown.length) {
+    out.credits_breakdown = polledResult.credits_breakdown;
+  }
+  return out;
+}
+
+// Shared zod schema for the optional `project_id` arg every generation tool
+// accepts. Keep this in one place so the description never drifts across the
+// 17 tools that use it. When omitted, the generation lands in the user's
+// auto-created "API Generations" project. Call `list_projects` first to
+// resolve a name → ObjectId.
+const { z } = require('zod');
+const projectIdField = z.string().optional().describe(
+  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). IMPORTANT: this is per-call, NOT sticky — once the user has named a working project, pass its id on EVERY generation call in the conversation; any call that omits it silently lands in the default "API Generations" project instead. Requires owner / edit / full permission on the project; view-only is rejected.'
+);
+
+// Shared zod schema for the optional `session_id` arg on generation tools.
+// WHY IT EXISTS: without it, each generation call gets its own session, so a
+// set of related clips lands in the app's left rail as a stack of near-identical
+// single-item sessions. (The server has a per-day fallback bucket, but it is not
+// something a caller can rely on — see kolbo-api sdkSessionManager.) Threading
+// the id returned by the FIRST call is the deterministic way to group a batch.
+const sessionIdField = z.string().optional().describe(
+  'Existing session to add this generation to, so a related set lands in ONE session instead of a stack of single-item sessions in the Kolbo sidebar. HOW TO USE: omit it on the FIRST call of a PLAN BUCKET (Cast, Locations, Props, or one Scene NN), read `session_id` off that result, `rename_session` to the plan name, then pass that SAME value on every follow-up in that bucket (another character, shot 2, a retake, "make it darker"). Only omit it again when the plan starts a NEW scene or NEW concept — never per take or per tool call. Image tools and video tools cannot share an id. `list_sessions` also returns ids. When set, `project_id` is ignored — the session\'s own project wins.'
+);
+
+// Read-scope variant for list/get tools that can surface a SHARED project's
+// assets (a teammate's Visual DNAs / moodboards). Pass a project id you have
+// edit+ on to also see that project owner's shared assets; omit to see only your
+// own + global/org. View-only members and non-members get nothing extra.
+const projectScopeReadField = z.string().optional().describe(
+  "Project ObjectId (from `list_projects`) to ALSO surface that shared project's assets (a teammate's, when the project is shared with you). Requires edit / full / owner on the project — view-only members and non-members get only their own. Omit to see just your own + global/org."
+);
+
+// ─── Optional inline-image content blocks ────────────────────────────────────
+// When a host opts in (the remote HTTP connector sets inlineImages:true), turn
+// generated IMAGE urls into MCP `image` content blocks so clients render them
+// inline instead of a "Show Image" link. Strictly gated + bounded:
+//   - only runs when opts.enabled is true (stdio/Kolbo Code never enables it,
+//     so their behavior is byte-identical: text URL only);
+//   - caps the number of images and the bytes per image;
+//   - ONLY embeds responses whose content-type is image/* — a video/audio URL
+//     can never be base64-embedded even if mistakenly passed in;
+//   - any fetch/decoding failure silently falls back to URL-only.
+const INLINE_IMG_MAX_COUNT = 4;
+// Cap kept conservative on purpose: a base64 image rides inside the JSON-RPC
+// tool result, and chat clients (claude.ai etc.) drop the WHOLE result if it's
+// too large — which looks like "no image at all". Anything over the cap is left
+// to the URL in the text payload (clients render a "Show Image" affordance from
+// it), so a big image degrades to a click instead of vanishing.
+const INLINE_IMG_MAX_BYTES = 1.5 * 1024 * 1024; // 1.5 MB per image
+const INLINE_IMG_FETCH_TIMEOUT_MS = 8000; // never hang the tool response on a slow CDN
+
+async function inlineImageBlocks(urls, opts = {}) {
+  if (!opts || !opts.enabled) return [];
+  if (!Array.isArray(urls) || urls.length === 0) return [];
+  // Fetch the (≤4) images in parallel — they're independent, the cap already
+  // bounds concurrency, and this sits on the connector response path right
+  // after generation. Order is preserved by map-then-filter; any failure (size,
+  // type, timeout, network) returns null and falls back to URL-only.
+  const maxCount = Math.min(INLINE_IMG_MAX_COUNT, Math.max(1, Number(opts.maxCount) || INLINE_IMG_MAX_COUNT));
+  const maxBytes = Math.min(INLINE_IMG_MAX_BYTES, Math.max(1, Number(opts.maxBytes) || INLINE_IMG_MAX_BYTES));
+  const fetchTimeoutMs = Math.min(INLINE_IMG_FETCH_TIMEOUT_MS, Math.max(1, Number(opts.fetchTimeoutMs) || INLINE_IMG_FETCH_TIMEOUT_MS));
+  const blocks = await Promise.all(
+    urls.slice(0, maxCount).map(async (url) => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), fetchTimeoutMs);
+      try {
+        if (typeof url !== 'string' || !isHttpUrl(url)) return null;
+        const res = await safeFetch(url, { signal: controller.signal });
+        if (!res.ok) {
+          await discardResponse(res);
+          return null;
+        }
+        const contentType = (res.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
+        if (!contentType.startsWith('image/')) {
+          await discardResponse(res);
+          return null; // never embed non-images
+        }
+        const declaredLen = Number(res.headers.get('content-length') || 0);
+        if (declaredLen && declaredLen > maxBytes) {
+          await discardResponse(res);
+          return null;
+        }
+        const buffer = await readResponseBuffer(res, maxBytes);
+        return { type: 'image', data: buffer.toString('base64'), mimeType: contentType };
+      } catch (_) {
+        return null;
+      } finally {
+        clearTimeout(timer);
+      }
+    })
+  );
+  return blocks.filter(Boolean);
+}
+
+// ─── "Open in Kolbo" deep links ───────────────────────────────────────────────
+// kolbo-api submit responses include `session_id` + `project_id`. Map each MCP
+// tool to the frontend page + tool slug whose session view can RESUME that
+// session (mirrors kolbo-map src/constants/sessionTypes.js resumeUrl map — the
+// route must match the SESSION MODEL the SDK created, per sdkSessionManager):
+//   ImageSession (image AND image_edit) → /image-tools?tool=create-image
+//   imgEditSession (edit_image / global_image_edit — the Canvas) → /image-tools?tool=canvas
+//   imgToVideoSession (video, video_from_image, elements, first_last_frame)
+//     → /video-tools?tool=create-video
+//   videoToVideoSession → /video-tools?tool=video-to-video
+//   lipsyncSession → /video-tools?tool=lipsync
+//   MusicGeneratorSession / TextToSpeechSession / textToSoundSession /
+//   speechToTextSession → /audio-tools with the matching slug
+//   CreativeDirectorSession → /creative-director?session=... (no tool param)
+// RETIRED — do NOT reintroduce as separate destinations. "Image Editing" folded
+// into Create Image and "Text to Video" folded into Create Video (a mode inside
+// it); sdkSessionManager already routes image_edit → ImageSession and video →
+// imgToVideoSession. The old ?tool=image-editing / ?tool=text-to-video slugs
+// still redirect, but nothing new should emit them.
+// Intentionally ABSENT (no deep-linkable session page — widget falls back to
+// plain https://app.kolbo.ai): edit_video (GlobalVideoEditSession has no
+// session deep-link), generate_3d (project-scoped, no session), shorts render.
+const APP_BASE_URL = 'https://app.kolbo.ai';
+const OPEN_URL_ROUTES = {
+  generate_image:             { path: '/image-tools', tool: 'create-image' },
+  generate_image_edit:        { path: '/image-tools', tool: 'create-image' },
+  edit_image:                 { path: '/image-tools', tool: 'canvas' },
+  generate_video:             { path: '/video-tools', tool: 'create-video' },
+  generate_video_from_image:  { path: '/video-tools', tool: 'create-video' },
+  generate_elements:          { path: '/video-tools', tool: 'create-video', mode: 'elements' },
+  generate_first_last_frame:  { path: '/video-tools', tool: 'create-video', mode: 'first-last' },
+  generate_video_from_video:  { path: '/video-tools', tool: 'video-to-video' },
+  generate_lipsync:           { path: '/video-tools', tool: 'lipsync' },
+  generate_music:             { path: '/audio-tools', tool: 'music-generator' },
+  generate_speech:            { path: '/audio-tools', tool: 'text-to-speech' },
+  generate_sound:             { path: '/audio-tools', tool: 'text-to-sound' },
+  transcribe_audio:           { path: '/audio-tools', tool: 'speech-to-text' },
+  generate_creative_director: { path: '/creative-director' },
+};
+// SDK tracking `type` on get_generation_status — same session model as the
+// generate_* tool that created the job, so "Open in Kolbo" still deep-links
+// after a status poll overwrites the live card.
+const TYPE_TO_TOOL = {
+  image: 'generate_image',
+  image_edit: 'generate_image_edit',
+  global_image_edit: 'edit_image',
+  video: 'generate_video',
+  video_from_image: 'generate_video_from_image',
+  elements: 'generate_elements',
+  first_last_frame: 'generate_first_last_frame',
+  video_from_video: 'generate_video_from_video',
+  lipsync: 'generate_lipsync',
+  music: 'generate_music',
+  speech: 'generate_speech',
+  sound: 'generate_sound',
+  transcription: 'transcribe_audio',
+  creative_director: 'generate_creative_director',
+};
+
+function sessionOf(gen) {
+  if (!gen || typeof gen !== 'object') return undefined;
+  return gen.session_id || gen.sessionId || undefined;
+}
+
+function projectOf(gen) {
+  if (!gen || typeof gen !== 'object') return undefined;
+  return gen.project_id || gen.projectId || undefined;
+}
+
+/**
+ * Build the "Open in Kolbo" deep link for a generation's actual session.
+ * Returns undefined (widget falls back to app.kolbo.ai) when the tool has no
+ * deep-linkable page or the submit response carried no session_id (older
+ * kolbo-api, shorts render, 3D).
+ */
+function buildOpenUrl(tool, gen) {
+  const sid = sessionOf(gen);
+  if (!sid) return undefined;
+  const key = OPEN_URL_ROUTES[tool] ? tool : (TYPE_TO_TOOL[gen && gen.type] || TYPE_TO_TOOL[tool]);
+  const route = OPEN_URL_ROUTES[key];
+  if (!route) return undefined;
+  let url = `${APP_BASE_URL}${route.path}?session=${encodeURIComponent(sid)}`;
+  if (route.tool) url += `&tool=${route.tool}`;
+  if (route.mode) url += `&mode=${route.mode}`;
+  const pid = projectOf(gen);
+  if (pid) url += `&project=${encodeURIComponent(pid)}`;
+  return url;
+}
+
+function linkFields(tool, gen) {
+  const sid = sessionOf(gen);
+  const pid = projectOf(gen);
+  const href = buildOpenUrl(tool, gen);
+  return {
+    ...(sid ? { session_id: String(sid) } : {}),
+    ...(pid ? { project_id: String(pid) } : {}),
+    ...(href ? { open_url: href } : {}),
+  };
+}
+
+/**
+ * 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
+// ui://kolbo/generation.html widget takes over: live progress, inline result,
+// action buttons. Text-only hosts never enter this path — their blocking
+// behavior and response bytes are UNCHANGED.
+const { UI, uiResult, appsEnabled, modelInfo } = require('../apps');
+
+/**
+ * Chip identity for a model: the CLEAN display name + its icon, resolved from
+ * the same /v1/models catalog `list_models` renders. Callers pass whatever the
+ * user/LLM supplied (an identifier like `google_tts`, `fal-ai/…/omnihuman/v1.5`,
+ * or a display name) — the card must never show the raw id.
+ */
+async function modelChipFields(client, model) {
+  const info = await modelInfo(client, model).catch(() => null);
+  return {
+    model: model || 'Smart Select',
+    model_name: (info && info.name) || model || 'Smart Select',
+    model_icon: (info && info.icon) || null,
+  };
+}
+
+/**
+ * Resolve `visual_dna_ids` to {id, name, thumbnail} so the card can show WHICH
+ * characters are locked in, not just how many. An id tells the user nothing;
+ * the face does.
+ *
+ * One list fetch per process, cached — the DNA catalog barely moves within a
+ * session, and a generation card must never add a round-trip per chip. A miss
+ * (id not in the caller's own DNAs) degrades to the bare id, which is exactly
+ * what the card showed before.
+ */
+const _dnaChipCache = new Map();
+let _dnaChipLoaded = 0;
+const DNA_CHIP_TTL = 5 * 60 * 1000;
+
+function dnaThumb(row) {
+  if (!row || typeof row !== 'object') return null;
+  const first = Array.isArray(row.images) ? row.images[0] : null;
+  return row.sheet_url
+    || row.thumbnail_url
+    || row.characterSheet
+    || (typeof first === 'string' ? first : first && first.url)
+    || null;
+}
+
+function rememberDna(row, fallbackId) {
+  if (!row || typeof row !== 'object') return null;
+  const id = String(row.id || row._id || fallbackId || '');
+  if (!id) return null;
+  const rec = { id, name: row.name || id, thumbnail: dnaThumb(row) };
+  _dnaChipCache.set(id, rec);
+  return rec;
+}
+
+async function resolveVisualDnas(client, ids) {
+  const list = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id) : [];
+  if (!list.length) return [];
+
+  const stale = Date.now() - _dnaChipLoaded > DNA_CHIP_TTL;
+  if (stale || list.some((id) => !_dnaChipCache.has(id))) {
+    try {
+      const res = await client.get('/v1/visual-dna?scope=mine');
+      const rows = res?.visual_dnas || res?.data || [];
+      for (const row of rows) rememberDna(row);
+      _dnaChipLoaded = Date.now();
+    } catch {
+      // Offline / rate-limited — fall through to per-id fetch.
+    }
+  }
+
+  // scope=mine misses global / shared / teammate DNAs. The generating card
+  // then printed "1 Visual DNA" with no face. Fetch the missing ids directly.
+  const missing = list.filter((id) => !_dnaChipCache.has(id));
+  if (missing.length) {
+    await Promise.all(missing.map(async (id) => {
+      try {
+        const res = await client.get(`/v1/visual-dna/${encodeURIComponent(id)}`);
+        rememberDna(res && res.visual_dna ? res.visual_dna : res, id);
+      } catch {
+        // Leave the bare id — the chip still names it.
+      }
+    }));
+  }
+
+  return list.map((id) => _dnaChipCache.get(id) || { id, name: id, thumbnail: null });
+}
+
+const _presetCache = new Map();
+let _presetLoaded = 0;
+const PRESET_TTL = 10 * 60 * 1000;
+
+async function resolvePreset(client, presetId) {
+  if (!presetId) return null;
+  const key = String(presetId);
+  const stale = Date.now() - _presetLoaded > PRESET_TTL;
+  if (!stale && _presetCache.has(key)) return _presetCache.get(key);
+  if (stale || _presetCache.size === 0) {
+    try {
+      const res = await client.get('/v1/presets');
+      for (const row of res?.presets || res?.data || []) {
+        const id = row?.id || row?._id || row?.identifier;
+        if (!id) continue;
+        _presetCache.set(String(id), {
+          id: String(id),
+          name: row.name || String(id),
+          thumbnail: row.thumbnail_url || row.thumbnail || null,
+        });
+      }
+      _presetLoaded = Date.now();
+    } catch {
+      // Offline — the chip keeps the word "preset".
+    }
+  }
+  return _presetCache.get(key) || null;
+}
+
+async function decorateSettings(client, settings) {
+  const s = { ...(settings || {}) };
+  if (!s.preset_id) return s;
+  const preset = await resolvePreset(client, s.preset_id);
+  if (!preset) return s;
+  return {
+    ...s,
+    preset_name: preset.name,
+    ...(preset.thumbnail ? { preset_thumbnail: preset.thumbnail } : {}),
+  };
+}
+
+const _mbChipCache = new Map();
+let _mbChipLoaded = 0;
+
+function rememberMoodboard(row, fallbackId) {
+  if (!row || typeof row !== 'object') return null;
+  const id = String(row.id || row._id || fallbackId || '');
+  if (!id) return null;
+  const rec = {
+    id,
+    name: row.name || id,
+    thumbnail: row.thumbnail_url || row.thumbnail || row.cover_url || (Array.isArray(row.images) ? row.images[0] : null) || null,
+  };
+  _mbChipCache.set(id, rec);
+  return rec;
+}
+
+async function resolveMoodboards(client, ids) {
+  const list = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id) : [];
+  if (!list.length) return [];
+  const stale = Date.now() - _mbChipLoaded > DNA_CHIP_TTL;
+  if (stale || list.some((id) => !_mbChipCache.has(id))) {
+    try {
+      const res = await client.get('/v1/moodboards');
+      for (const row of res?.moodboards || res?.data || []) rememberMoodboard(row);
+      _mbChipLoaded = Date.now();
+    } catch { /* fall through to per-id */ }
+  }
+  const missing = list.filter((id) => !_mbChipCache.has(id));
+  if (missing.length) {
+    await Promise.all(missing.map(async (id) => {
+      try {
+        const res = await client.get(`/v1/moodboards/${encodeURIComponent(id)}`);
+        rememberMoodboard(res && res.moodboard ? res.moodboard : res, id);
+      } catch { /* bare id */ }
+    }));
+  }
+  return list.map((id) => _mbChipCache.get(id) || { id, name: id, thumbnail: null });
+}
+
+function mediaRefs(p) {
+  const images = Array.isArray(p.reference_images)
+    ? p.reference_images.filter(Boolean)
+    : (p.reference_image ? [p.reference_image] : []);
+  return {
+    // Omitted when empty: a live card MERGES status payloads over its own
+    // state, so a present-but-empty reference_images (the single-id status
+    // path has no input refs of its own) wiped the submit-time thumbnails
+    // off the finished card.
+    ...(images.length ? { reference_images: images, reference_image: p.reference_image || images[0] } : {}),
+    ...(Array.isArray(p.reference_videos) && p.reference_videos.length
+      ? { reference_videos: p.reference_videos.filter(Boolean) } : {}),
+    ...(Array.isArray(p.reference_audio) && p.reference_audio.length
+      ? { reference_audio: p.reference_audio.filter(Boolean) } : {}),
+  };
+}
+
+function moodboardIds(settings) {
+  const s = settings || {};
+  if (Array.isArray(s.moodboard_ids) && s.moodboard_ids.length) return s.moodboard_ids;
+  return s.moodboard_id ? [s.moodboard_id] : [];
+}
+
+/**
+ * Build the "submitted — widget is live" tool result for a UI host.
+ * @param {object} p
+ *   tool           MCP tool name (e.g. 'generate_image')
+ *   kind           'image' | 'video' | 'audio' | '3d' | 'scenes'
+ *   gen            the submit response ({ generation_id, poll_interval_hint })
+ *   client         KolboClient (for model icon lookup)
+ *   model, prompt, count, settings, reference_images, estimated_seconds
+ *   voice          resolved voice record { name, thumbnail } (speech only)
+ *   poll_tool      widget-side status tool (default 'get_generation_status')
+ *   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.
+  const chip = await modelChipFields(p.client, p.model);
+  const settings = await decorateSettings(p.client, p.settings || {});
+  const structured = {
+    phase: 'generating',
+    widget: 'generation',
+    kind: p.kind,
+    tool: p.tool,
+    generation_id: p.gen.generation_id,
+    poll_tool: p.poll_tool || 'get_generation_status',
+    // 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 },
+    ...chip,
+    ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
+    prompt: p.prompt,
+    count: p.count || 1,
+    settings,
+    visual_dnas: await resolveVisualDnas(p.client, settings.visual_dna_ids),
+    moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
+    // `reference_image` is retained for older widget builds. New widgets render
+    // every browser-loadable image supplied to the generation.
+    ...mediaRefs(p),
+    ...linkFields(p.tool, p.gen),
+  };
+  // Batch mode (prompts[] fan-out): ONE widget tracks every id in the set.
+  if (Array.isArray(p.generation_ids) && p.generation_ids.length > 1) {
+    structured.generation_ids = p.generation_ids;
+    structured.prompts = p.prompts;
+  }
+  const text = JSON.stringify({
+    status: 'submitted',
+    generation_id: p.gen.generation_id,
+    // The session this landed in. Pass it back as `session_id` on the next call
+    // of the same set to keep the whole set in one session (see sessionIdField).
+    session_id: p.gen.session_id,
+    ...(Array.isArray(p.generation_ids) && p.generation_ids.length > 1
+      ? { batch: true, generation_ids: p.generation_ids } : {}),
+    ...(p.failed_submissions && p.failed_submissions.length
+      ? { failed_submissions: p.failed_submissions } : {}),
+    ...(p.warning ? { _warning: p.warning } : {}),
+    _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update. CREDIT GUARD: END YOUR TURN now — do not keep Thinking, writing skills/files, or planning while the card spins (that burns coding credits). Do NOT poll in a loop. If you need the output URLs for a follow-up step, call get_generation_status ONCE with wait=true as the only next tool — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
+    _paid_note: 'This generation is RUNNING and the user is paying for it. If you now realize the tool, model, or parameters were wrong, call cancel_generation with this generation_id FIRST, then start the replacement — never leave a wrong generation running alongside its retry (the user gets two cards and two charges).',
+  }, null, 2);
+  return uiResult(UI.generation, text, structured);
+}
+
+/**
+ * Return a paid generation immediately for hosts that cannot render MCP Apps
+ * and enforce short tool-call timeouts (for example Manus custom MCP). This is
+ * deliberately plain MCP content: no ui:// resource and no promise of a card.
+ * The existing get_generation_status tool is the durable status endpoint.
+ */
+function asyncGenerating(p) {
+  const ids = Array.isArray(p.generation_ids) && p.generation_ids.length
+    ? p.generation_ids
+    : [p.gen.generation_id].filter(Boolean);
+  const defaultStatusArgs = ids.length > 1
+    ? { generation_ids: ids, wait: false }
+    : { generation_id: ids[0], wait: false };
+  const pollTool = p.poll_tool || 'get_generation_status';
+  const statusArgs = { ...(p.status_args || defaultStatusArgs), wait: false };
+  const structured = {
+    status: 'submitted',
+    generation_id: p.gen.generation_id,
+    session_id: p.gen.session_id,
+    ...(ids.length > 1 ? { batch: true, generation_ids: ids } : {}),
+    ...(p.failed_submissions && p.failed_submissions.length
+      ? { failed_submissions: p.failed_submissions } : {}),
+    ...(p.warning ? { warning: p.warning } : {}),
+    poll_tool: pollTool,
+    status_args: statusArgs,
+    next_action: `The job is running. Do not submit it again. When the result is needed, call ${pollTool} with the supplied status_args. If it is still processing, tell the user and check again later; do not poll in a tight loop.`,
+    paid_job_notice: ids.length > 1
+      ? `This is a paid batch. Only if the user asks to stop or approves a replacement, cancel every running generation first: ${ids.join(', ')}.`
+      : 'This is a paid generation. Only if the user asks to stop or approves a replacement, cancel this generation before starting the replacement.',
+  };
+  return {
+    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+    structuredContent: structured,
+  };
+}
+
+/**
+ * Wrap an already-completed generation result with the widget.
+ *
+ * Used by tools that stay blocking even on UI hosts (creative director), AND —
+ * since structuredContent costs a text host nothing — by every generation tool
+ * on its normal blocking return. That second case is why model names, model
+ * avatars and Visual DNA chips were missing in Kolbo Code: it does not advertise
+ * MCP Apps, so `ui()` is false, `uiGenerating` never runs, and the host had to
+ * rebuild the card from raw text that carries only a model IDENTIFIER. Shipping
+ * the resolved payload here fixes every non-Apps host at once, exactly the way
+ * the list tools already do it (see listResult).
+ *
+ * The TEXT is unchanged, so text-only hosts see precisely what they saw before.
+ */
+function preferOwnedUrls(urls) {
+  const list = Array.isArray(urls) ? urls.filter((item) => typeof item === 'string' && item) : [];
+  const ours = list.filter((item) => {
+    try {
+      const host = new URL(item).hostname;
+      return /(?:^|\.)kolbo\.ai$/.test(host) || /digitaloceanspaces\.com$/.test(host);
+    } catch {
+      return false;
+    }
+  });
+  return ours.length ? ours : (list.length ? list : urls);
+}
+
+async function uiCompleted(p, textPayload, extraContent) {
+  const chip = await modelChipFields(p.client, p.model);
+  const settings = p.settings ? await decorateSettings(p.client, p.settings) : undefined;
+  const structured = {
+    phase: 'completed',
+    widget: 'generation',
+    kind: p.kind,
+    tool: p.tool,
+    ...chip,
+    prompt: p.prompt,
+    count: p.count || 1,
+    // 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 || {}`.
+    ...(settings ? { settings } : {}),
+    visual_dnas: await resolveVisualDnas(p.client, (settings || {}).visual_dna_ids),
+    moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
+    ...mediaRefs(p),
+    urls: preferOwnedUrls(p.urls),
+    thumbnail_url: p.thumbnail_url,
+    title: p.title,
+    duration: p.duration,
+    scenes: p.scenes,
+    // Independent per-item results (get_generation_status checking several ids
+    // at once) — each one carries its OWN state/media, unlike `scenes`/`urls`
+    // above which assume everything finished together. Only set when the
+    // caller actually has this shape; every existing caller is unaffected.
+    ...(Array.isArray(p.items) ? { items: p.items } : {}),
+    // Transcription payload. get_generation_status is the ONLY way the live
+    // transcript widget learns its result, and it reads text/srt_url/txt_url off
+    // this object — but uiCompleted is shaped for the generation card and
+    // dropped every one, so a finished transcription rendered "(empty
+    // transcript)" with no SRT/TXT buttons while the text sat in the status
+    // response. structuredContent SHADOWS the text block on widget hosts, so
+    // omitting a field here is the same as deleting it.
+    ...(typeof p.text === 'string' ? { text: p.text } : {}),
+    ...(p.srt_url ? { srt_url: p.srt_url } : {}),
+    ...(p.word_by_word_srt_url ? { word_by_word_srt_url: p.word_by_word_srt_url } : {}),
+    ...(p.txt_url ? { txt_url: p.txt_url } : {}),
+    ...(p.audio_url ? { audio_url: p.audio_url } : {}),
+    // The voice, by name and portrait. uiGenerating has carried this since the
+    // chips were introduced; uiCompleted never did, so it silently dropped a
+    // resolved voice its caller had already looked up — every FINISHED speech
+    // card fell back to `settings.voice`, printing a raw ElevenLabs id where the
+    // name belongs and rendering the generic note placeholder instead of the
+    // voice's face. Exactly the "never show a raw id on a card" rule, broken on
+    // the one path the user actually ends up looking at.
+    ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
+    // The RAW generation state, when the caller has one. `phase` above is
+    // hardcoded 'completed' — it means "this tool call finished", not "the
+    // generation finished" — so a status check on a still-running job looked
+    // done to every reader. A live generation card polls get_generation_status
+    // from its own iframe and reads `state` FIRST; without it, a processing job
+    // resolved as completed-with-no-media and painted a red failure card.
+    ...(p.state ? { state: p.state } : {}),
+    credits_used: p.credits_used,
+    ...linkFields(p.tool, p.gen),
+  };
+  const out = uiResult(UI.generation, textPayload, structured);
+  if (Array.isArray(extraContent) && extraContent.length) {
+    out.content = [...out.content, ...extraContent];
+  }
+  return out;
+}
+
+// ─── Text-payload budget ─────────────────────────────────────────────────────
+//
+// Whatever a tool returns as TEXT is what the model actually reads, and hosts
+// reject or spill-to-disk anything much past this. A list tool that dumps every
+// field of every row blows it instantly: list_presets measured 632,919 chars,
+// get_stock_categories 257,817, list_voices 190,286 — all pretty-printed with
+// `JSON.stringify(x, null, 2)` and no cap. The widget path already slims rows to
+// id/title/thumbnail; the text path has to do the same or the tool is unusable
+// on exactly the text hosts (Claude Code, Cursor, Codex) that depend on it.
+const MAX_TEXT_CHARS = 20000;
+
+/**
+ * Build a compact text payload for a list-shaped result.
+ *
+ * @param {object[]} items   rows from the API
+ * @param {object}   opts
+ * @param {string[]} opts.fields  keys to keep per row, in order (others dropped)
+ * @param {number}   [opts.cap]   max rows to include (default 50)
+ * @param {number}   [opts.total] true total, so the model knows more exist
+ * @param {object}   [opts.extra] extra top-level keys to merge in
+ * @param {string}   [opts.note]  guidance on how to fetch the rest
+ */
+function compactList(items, { fields, cap = 50, total, extra, note } = {}) {
+  const rows = Array.isArray(items) ? items : [];
+  const kept = rows.slice(0, cap).map((row) => {
+    if (!row || typeof row !== 'object') return row;
+    const out = {};
+    for (const f of fields || Object.keys(row)) {
+      // Drop empties — a row of nulls costs tokens and tells the model nothing.
+      if (row[f] !== undefined && row[f] !== null && row[f] !== '') out[f] = row[f];
+    }
+    return out;
+  });
+
+  const payload = { ...(extra || {}), items: kept, count: kept.length };
+  if (total != null) payload.total = total;
+  const omitted = Math.max(rows.length - kept.length, 0);
+  if (omitted > 0 || (total != null && total > kept.length)) {
+    payload._truncated = {
+      omitted_from_this_page: omitted,
+      hint: note || 'Narrow with the tool\'s filter args, or page for more.',
+    };
+  }
+
+  let text = JSON.stringify(payload);
+  if (text.length > MAX_TEXT_CHARS) {
+    // Still too big even trimmed (very long descriptions). Halve until it fits
+    // rather than returning something the host will truncate at a random byte.
+    let n = kept.length;
+    while (n > 1 && text.length > MAX_TEXT_CHARS) {
+      n = Math.floor(n / 2);
+      payload.items = kept.slice(0, n);
+      payload.count = n;
+      payload._truncated = {
+        omitted_from_this_page: rows.length - n,
+        hint: note || 'Result was too large for one response; narrow with filter args.',
+      };
+      text = JSON.stringify(payload);
+    }
+  }
+  return text;
+}
+
+/**
+ * Turn a 403 INSUFFICIENT_CREDITS into the plans/upgrade card.
+ *
+ * Without this the user just sees the raw API sentence and has to go find the
+ * pricing page themselves. The card states the shortfall, shows live
+ * promo-adjusted plans, and links to app.kolbo.ai/pricing.
+ *
+ * Returns null for any other error so callers can rethrow untouched. The plan
+ * fetch is best-effort: if it fails we still return a card carrying the
+ * balance/shortfall and the pricing link, because the ONE thing this path must
+ * never do is swallow the reason the generation did not run.
+ */
+async function insufficientCreditsResult(client, err, options = {}) {
+  if (!err || err.code !== 'INSUFFICIENT_CREDITS') return null;
+  if (options.commerce === false) {
+    // ChatGPT profile: no plans, no prices, no pricing link — OpenAI's
+    // directory treats those as disallowed digital-goods commerce. The card
+    // states the refusal; where to add credits is the user's own business.
+    const balance = err.data?.balance;
+    const structured = {
+      widget: 'generation',
+      phase: 'failed',
+      error: 'This needs more Kolbo credits than the account has left. Nothing was generated or charged.',
+      balance,
+      required: err.data?.required,
+      _hint: 'The generation did NOT run and nothing was charged. Tell the user their Kolbo account is out of credits for this request. Do not quote prices, do not link to pricing or checkout, and do not offer to purchase anything.',
+    };
+    const text = JSON.stringify({
+      error: structured.error,
+      code: 'INSUFFICIENT_CREDITS',
+      balance,
+      required: structured.required,
+      _hint: structured._hint,
+    }, null, 2);
+    return uiResult(UI.generation, text, structured);
+  }
+
+  let data = null;
+  try {
+    data = await client.get('/v1/account/plans');
+  } catch {
+    // Offline / rate-limited — fall through to the minimal card.
+  }
+
+  const balance = err.data?.balance ?? data?.credits?.total;
+  const required = err.data?.required;
+  const structured = {
+    widget: 'plans',
+    reason: 'insufficient_credits',
+    balance,
+    required,
+    shortfall: (Number.isFinite(balance) && Number.isFinite(required))
+      ? Math.max(0, required - balance) : undefined,
+    current_plan: data?.current_plan || null,
+    plans: data?.plans || [],
+    credit_packs: data?.credit_packs || [],
+    pricing_url: err.data?.pricing_url || data?.pricing_url || 'https://app.kolbo.ai/pricing',
+  };
+
+  // structuredContent shadows the text on widget hosts, so the refusal reason
+  // has to be inside the object too — an agent that only reads structured
+  // content must still understand that nothing was generated.
+  structured.error = err.message;
+  structured._hint = 'The generation did NOT run and nothing was charged. An upgrade card is shown to the user. Tell them they are out of credits and point at the card; do not retry the generation, and do not attempt to purchase anything for them.';
+
+  const text = JSON.stringify({
+    error: err.message,
+    code: 'INSUFFICIENT_CREDITS',
+    balance,
+    required,
+    pricing_url: structured.pricing_url,
+    _hint: structured._hint,
+  }, null, 2);
+
+  return uiResult(UI.plans, text, structured);
+}
+
+module.exports = {
+  MAX_FILE_BYTES,
+  MAX_TEXT_CHARS,
+  compactList,
+  VISUAL_DNA_MAX_BYTES,
+  LOCAL_FILE_ROUTING,
+  FILE_INPUT_TOOLS,
+  attachFileInputHints,
+  DEFAULT_MAX_FILE_MB,
+  isHttpUrl,
+  assertSafeUrl,
+  safeFetch,
+  readResponseBuffer,
+  guessFilename,
+  guessContentType,
+  resolveToBuffer,
+  pollOrTimedOut,
+  creditFields,
+  projectIdField,
+  sessionIdField,
+  projectScopeReadField,
+  inlineImageBlocks,
+  buildOpenUrl,
+  linkFields,
+  buildProjectUrl,
+  uiGenerating,
+  asyncGenerating,
+  uiCompleted,
+  insufficientCreditsResult,
+  appsEnabled,
+};