@kolbo/mcp 1.62.0 → 1.64.0

package/package.json

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

package/skill/SKILL.md

@@ -177,6 +177,7 @@ Everything in Kolbo — sessions, generations, media, docs — lives inside a PR
 1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in the conversation. It is **per-call, NOT sticky** — any call that omits it silently lands in the default "API Generations" bucket (`is_default: true`).
 2. **No project mentioned** → omit `project_id`; the default bucket is correct. Don't ask unless intent is ambiguous.
 3. **Work landed in the wrong project? MOVE it, never regenerate**: `move_session` relocates a whole session + all its media (works for any session type — the `session_id` from generation responses, chats, transcriptions); `move_media` / `bulk_move_media` / `move_folder_contents` relocate individual media items.
+4. **Inside the project, keep a related set in ONE session.** Every generation response returns a `session_id`. When a set needs several calls — shot 2, 3, 4 of a sequence, or more takes of the same idea — pass the FIRST call's `session_id` back on each follow-up. Without it every call opens its own session and the user's sidebar fills with near-identical single-item sessions. Prefer a real batch where one exists (`prompts` on `generate_image` / `generate_video`, `items` on `generate_video_from_image` — up to 8 `{image_url, prompt}` pairs animated in one call and one widget — `num_images`, `generate_creative_director`); use `session_id` for the tools that animate/edit one thing per call (`generate_elements`, `generate_first_last_frame`, `generate_lipsync`, `generate_video_from_video`, `edit_image`, `edit_video`), and across batches when a sequence runs longer than 8. Start a NEW session (omit it) when the next generation is unrelated.
 
 
 ## Cost Awareness — Quick Rules

package/skill/references/workflows/media-library.md

@@ -53,6 +53,12 @@ URLs to any generation tool.
 curl -X POST "<upload_url>" -H "Authorization: Bearer <token>" -F "file=@/abs/path/clip.mp3"
 ```
 
+**Pace a batch.** The upload endpoint is rate limited — the ticket response says by
+how much in `rate_limit` (currently 40 uploads per 60s). Firing 55 files back to
+back stalls at file 41. Sleep ~2s between files, or read the 429: it carries a
+`Retry-After` header and `retry_after_seconds` in the body. Wait exactly that long
+and continue — a 429 is a "not yet", not a failed upload, and nothing was charged.
+
 Do **not** fall back to `upload_media`'s `source_base64` for anything but a tiny file —
 it pushes the whole file through the model's context, twice. And do not reach for
 cloud credentials or a bucket of your own; the ticket is the sanctioned path.

package/src/apps/widgets/generation.js

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

package/src/client.js

@@ -47,6 +47,35 @@ function isAbortError(err) {
   return err && (err.name === 'TimeoutError' || err.name === 'AbortError');
 }
 
+// ---------------------------------------------------------------------------
+// 429 handling
+// ---------------------------------------------------------------------------
+// A 429 is rejected by the rate-limit middleware BEFORE the handler runs: no
+// credits spent, no generation started, nothing half-done. That makes it the
+// one status it is safe to replay — but only ONCE, and only when the server
+// told us how long to wait. An unbounded backoff loop would hide a real
+// capacity problem and stall the tool call past the host's own timeout.
+const RETRY_429_MAX_WAIT_S = 65;
+
+function retryAfterSeconds(response) {
+  const raw = response.headers.get('retry-after');
+  if (!raw) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+async function retryOnce429(attempt) {
+  try {
+    return await attempt();
+  } catch (err) {
+    const wait = err && err.status === 429 ? err.retryAfterSeconds : null;
+    if (wait === null || wait === undefined || wait > RETRY_429_MAX_WAIT_S) throw err;
+    await progress.tick(); // keepalive — the wait can be up to a minute
+    await new Promise((resolve) => setTimeout(resolve, (wait + 1) * 1000));
+    return attempt();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Partner / whitelabel resolution (mirrors CLI's brand/partner.ts)
 // ---------------------------------------------------------------------------
@@ -326,11 +355,13 @@ class KolboClient {
         data._kolbo_auth_expired = true;
         fullMessage = `${fullMessage} [KOLBO_AUTH_EXPIRED]`;
       }
-      throw new KolboApiError(fullMessage, {
+      const apiError = new KolboApiError(fullMessage, {
         code,
         status: response.status,
         data
       });
+      if (response.status === 429) apiError.retryAfterSeconds = retryAfterSeconds(response);
+      throw apiError;
     }
 
     const generationId = data?.generation_id || data?.generationId;
@@ -360,13 +391,21 @@ class KolboClient {
     return this.request('DELETE', reqPath, body);
   }
 
+  // Uploads are the one thing agents genuinely do in a tight loop (`upload_media`
+  // per file), and /v1/media/upload shares the per-minute SDK generation bucket —
+  // so a batch trips 429 long before the user's patience does. Absorb exactly one
+  // of those, honouring the server's Retry-After. Everything else (including the
+  // poll loop, which does its own capped backoff in polling.js) still surfaces
+  // the 429 straight to the caller, now with the wait spelled out in the message.
   async postMultipart(reqPath, formData) {
     if (!this.apiKey) await this._ensureLogin();
-    const result = await this._doMultipart(reqPath, formData);
-    if (result._status === 401 && this._tryRefreshKey()) {
-      return this._doMultipart(reqPath, formData);
-    }
-    return result;
+    return retryOnce429(async () => {
+      const result = await this._doMultipart(reqPath, formData);
+      if (result._status === 401 && this._tryRefreshKey()) {
+        return this._doMultipart(reqPath, formData);
+      }
+      return result;
+    });
   }
 
   async _doMultipart(reqPath, formData) {
@@ -428,11 +467,13 @@ class KolboClient {
         data._kolbo_auth_expired = true;
         fullMessage = `${fullMessage} [KOLBO_AUTH_EXPIRED]`;
       }
-      throw new KolboApiError(fullMessage, {
+      const apiError = new KolboApiError(fullMessage, {
         code,
         status: response.status,
         data
       });
+      if (response.status === 429) apiError.retryAfterSeconds = retryAfterSeconds(response);
+      throw apiError;
     }
 
     return data;

package/src/index.js

@@ -124,7 +124,7 @@ function createServer(opts = {}) {
       '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
       '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly; all Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
-      '9. MODEL SELECTION: ALWAYS pass a specific `model` on every generation tool — do NOT omit it. Omitting falls back to "Smart Select" auto-routing, which we deliberately avoid because it hides the model choice from the user and often picks a generic default. Choose the model that best fits the task and the user\'s intent (quality, speed, style, capability). If you are unsure which model to use for a given type, call `list_models` with the matching `type` and pick the recommended/flagship one, then pass its `identifier`. Only use Smart Select (omit `model`) if the user EXPLICITLY asks you to auto-pick.',
+      '9. MODEL SELECTION — ROUTE BY THE STRENGTHS SUMMARY, NEVER BY THE BADGE OR THE PRICE TAG: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). To choose: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost. That summary IS the routing instruction: match it against what the user actually asked for (subject, style, motion, length, quality bar, speed), then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
       '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit` (it runs on strong dedicated editing models, same as image generation). Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.'
     ].join('\n')
   });

package/src/polling.js

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

package/src/tools/_shared.js

@@ -356,6 +356,16 @@ 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 set, read `session_id` off that call\'s result, then pass that SAME value on every follow-up call belonging to the same set (e.g. shot 2, 3, 4 of one sequence). Only group things that genuinely belong together — an unrelated generation should start a fresh session by omitting this. The id must come from a session of the same kind (image tools share one session type, video tools another); `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
@@ -543,6 +553,9 @@ async function uiGenerating(p) {
   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
@@ -661,6 +674,7 @@ module.exports = {
   pollOrTimedOut,
   creditFields,
   projectIdField,
+  sessionIdField,
   projectScopeReadField,
   inlineImageBlocks,
   buildOpenUrl,

package/src/tools/chat.js

@@ -14,7 +14,7 @@ function registerChatTools(server, client) {
     'Send a chat message to Kolbo AI. Starts a new conversation (omit session_id) or continues an existing one. Returns the assistant response when complete. Supports image/video/audio analysis via media_urls — pass public URLs and the model auto-routes to a vision-capable model (e.g. Gemini) when media is detected. Supports web search and deep think modes.',
     {
       message: z.string().describe('The user message to send'),
-      model: z.string().optional().describe('Model identifier from list_models type="text". Identifiers resolve leniently, so the DISPLAY NAME that list_models shows works too ("Grok 4.5" → its identifier). Do NOT hardcode an id you have not seen in list_models — the text catalog turns over fast. Prefer passing a SPECIFIC model — omitting falls back to Smart Select auto-routing, which we avoid unless the user explicitly asks for auto-pick. Exception: when media_urls contains video or audio, omitting is fine — routing goes to a Gemini vision model regardless of this field.'),
+      model: z.string().optional().describe('Model identifier from list_models type="text". Identifiers resolve leniently, so the DISPLAY NAME that list_models shows works too ("Grok 4.5" → its identifier). Do NOT hardcode an id you have not seen in list_models — the text catalog turns over fast. Prefer passing a SPECIFIC model — omitting falls back to Smart Select auto-routing, which we avoid unless the user explicitly asks for auto-pick. Choose it by matching the task to each model\'s STRENGTHS SUMMARY in `list_models type="text"` — not by the newest/biggest name. Chat bills PER TOKEN, so the listed credit number is not the cost: a frontier model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model whose summary covers the task (Claude Sonnet, Gemini Flash, GPT nano/mini class) and reserve the frontier tier for hard reasoning or long-form code the user asked for. Exception: when media_urls contains video or audio, omitting is fine — routing goes to a Gemini vision model regardless of this field.'),
       session_id: z.string().optional().describe('Existing chat session ID to continue. Omit to start a new conversation.'),
       system_prompt: z.string().optional().describe('System prompt for the conversation. Only applied when creating a new session.'),
       web_search: z.boolean().optional().describe('Enable web search for this message. Default: false'),

package/src/tools/generate.js

@@ -5,8 +5,8 @@
 
 const { z } = require('zod');
 const FormData = require('form-data');
-const { pollUntilDone } = require('../polling');
-const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
+const { pollUntilDone, waitWindowMs } = require('../polling');
+const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, sessionIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
@@ -37,8 +37,8 @@ const CINEMATIC_SCHEMA = z.object({
   'validated against their dimension server-side. Dimensions are data-driven — never hardcode ids.'
 );
 
-// ─── Batch fan-out (prompts[]) ──────────────────────────────────────────────
-// One tool call, N DIFFERENT prompts → N generations tracked by ONE widget.
+// ─── Batch fan-out (prompts[] / items[]) ────────────────────────────────────
+// One tool call, N DIFFERENT inputs → N generations tracked by ONE widget.
 // The manual-control twin of generate_creative_director: no orchestration pass,
 // the user's exact prompts verbatim. Submit failures never sink the batch —
 // successful ids proceed, failed prompts are reported alongside.
@@ -47,22 +47,32 @@ const CINEMATIC_SCHEMA = z.object({
 // the caller had no way to know which prompt vanished. `promptsField` also caps
 // the array in the schema (so hosts see `maxItems` before calling); the guard
 // below is the choke point EVERY batch tool routes through, and names the count.
+//
+// An item is EITHER a bare prompt string (generate_image / generate_video, where
+// only the prompt varies) OR an object carrying its own per-item inputs
+// alongside the prompt (generate_video_from_image: `{ image_url, prompt }` — the
+// image is what varies, and that is the whole point). Either way the widget
+// captions each tile with the item's prompt, so that is the label we carry.
 const MAX_BATCH_PROMPTS = 8;
-async function submitBatch(rawPrompts, submitOne) {
-  if (rawPrompts.length > MAX_BATCH_PROMPTS) {
+async function submitBatch(rawItems, submitOne) {
+  if (rawItems.length > MAX_BATCH_PROMPTS) {
     throw new Error(
-      `Too many prompts: ${rawPrompts.length} received, max ${MAX_BATCH_PROMPTS} per call. ` +
-      `Split them across ${Math.ceil(rawPrompts.length / MAX_BATCH_PROMPTS)} calls of at most ${MAX_BATCH_PROMPTS}.`
+      `Too many prompts: ${rawItems.length} received, max ${MAX_BATCH_PROMPTS} per call. ` +
+      `Split them across ${Math.ceil(rawItems.length / MAX_BATCH_PROMPTS)} calls of at most ${MAX_BATCH_PROMPTS}.`
     );
   }
-  const prompts = rawPrompts.map((s) => String(s).trim()).filter(Boolean);
-  const settled = await Promise.allSettled(prompts.map((p) => submitOne(p)));
+  const items = rawItems
+    .map((it) => (typeof it === 'object' && it !== null
+      ? { input: it, label: String(it.prompt || '').trim() }
+      : { input: String(it).trim(), label: String(it).trim() }))
+    .filter((x) => x.label);
+  const settled = await Promise.allSettled(items.map((x) => submitOne(x.input)));
   const ok = [], failed = [];
   settled.forEach((s, i) => {
-    if (s.status === 'fulfilled' && s.value && s.value.generation_id) ok.push({ prompt: prompts[i], gen: s.value });
-    else failed.push({ prompt: prompts[i], error: (s.reason && s.reason.message) || 'submit failed' });
+    if (s.status === 'fulfilled' && s.value && s.value.generation_id) ok.push({ prompt: items[i].label, gen: s.value });
+    else failed.push({ prompt: items[i].label, error: (s.reason && s.reason.message) || 'submit failed' });
   });
-  if (!ok.length) throw new Error(`All ${prompts.length} batch submissions failed: ${failed[0].error}`);
+  if (!ok.length) throw new Error(`All ${items.length} batch submissions failed: ${failed[0].error}`);
   return { ok, failed, ids: ok.map((o) => o.gen.generation_id) };
 }
 
@@ -77,6 +87,7 @@ async function pollBatch(client, batch, { interval, timeout }) {
       type: 'text',
       text: JSON.stringify({
         batch: true,
+        session_id: batch.ok[0].gen.session_id,
         generations,
         failed_submissions: batch.failed.length ? batch.failed : undefined
       }, null, 2)
@@ -115,6 +126,18 @@ function registerGenerateTools(server, client, options = {}) {
   // "submitted" response + a live ui://kolbo/generation.html widget that keeps
   // one wait=true status call in flight. Text-only hosts never take this branch.
   const ui = () => appsEnabled(server, options);
+
+  // How long the STATUS tools may block inside one tool call before handing
+  // back a non-terminal result the caller re-issues. Bounded by the transport,
+  // not by the generation — full reasoning and the measured numbers live next
+  // to the constants in ../polling.js.
+  const WAIT_WINDOW_MS = waitWindowMs(options);
+  const WAIT_WINDOW_S = Math.round(WAIT_WINDOW_MS / 1000);
+  // What to tell a caller holding a still-running generation. Never "don't call
+  // again" — for anything longer than the window, calling again IS the protocol.
+  const stillRunningHint = (idsPhrase) =>
+    `Still running — this is NOT a failure and no credits were lost. Each wait=true call blocks for at most ~${WAIT_WINDOW_S}s and then returns whatever the state is, so a long job (music ~3 min, video can be longer) legitimately needs SEVERAL wait=true calls in a row. Call get_generation_status again with wait=true${idsPhrase}. Do not spin with wait=false, and do not re-run the generation tool.`;
+
   // ─── generate_image ────────────────────────────────────────
   server.tool(
     'generate_image',
@@ -135,14 +158,15 @@ function registerGenerateTools(server, client, options = {}) {
       preset_id: z.string().optional().describe('Preset ID from list_presets type="image" to apply a saved style preset to this generation.'),
       cinematic: CINEMATIC_SCHEMA,
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one image ungraded.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ prompt, prompts, model, aspect_ratio, enhance_prompt = false, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id }) => {
+    async ({ prompt, prompts, model, aspect_ratio, enhance_prompt = false, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
       model = await canonicalModelId(client, model, 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       const shared = {
         model, aspect_ratio, enhance_prompt,
-        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id
+        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id
       };
 
       // Batch mode: N different prompts, one widget owning all generation ids.
@@ -180,6 +204,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             model: result.result.model,
             prompt_used: result.result.prompt_used,
@@ -207,13 +232,14 @@ function registerGenerateTools(server, client, options = {}) {
       resolution: z.string().optional().describe('Image resolution tier: "1K" / "2K" / "3K" / "4K". Model-dependent — call list_models and read supported_resolutions. Default: "1K" for most edit models.'),
       cinematic: CINEMATIC_SCHEMA,
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one edit ungraded.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id }) => {
+    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image-edit', {
         prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
-        visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id
+        visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id, session_id
       });
 
       if (ui()) return uiGenerating({
@@ -240,6 +266,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             model: result.result.model,
             prompt_used: result.result.prompt_used,
@@ -352,10 +379,10 @@ function registerGenerateTools(server, client, options = {}) {
   // blocking poll window) needs this tool to be re-checked until done.
   server.tool(
     'get_creative_director_status',
-    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block for up to ~3 minutes instead of repeatedly calling this tool. Prefer this over the generic get_generation_status for Creative Director ids — the generic tool now returns the same scene data (it delegates here), but this one is the direct route.',
+    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block until the batch is terminal or the wait window closes, whichever comes first — a batch longer than one window returns state="processing" and you simply call again with wait=true. Prefer this over the generic get_generation_status for Creative Director ids — the generic tool now returns the same scene data (it delegates here), but this one is the direct route.',
     {
       generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.'),
-      wait: z.boolean().optional().describe('If true, block until the batch is terminal, up to ~3 minutes. Use this instead of repeatedly checking in a loop.')
+      wait: z.boolean().optional().describe(`If true, block until the batch is terminal, for at most ~${WAIT_WINDOW_S}s per call. A batch that outlives one window comes back state="processing" (not an error) — call again with wait=true until it is terminal. Always prefer this over polling with wait=false.`)
     },
     async ({ generation_id, wait }) => {
       const statusUrl = `/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`;
@@ -364,7 +391,7 @@ function registerGenerateTools(server, client, options = {}) {
         try {
           status = await pollUntilDone(client, generation_id, {
             interval: 15000,
-            timeout: 180000,
+            timeout: WAIT_WINDOW_MS,
             statusUrl
           });
         } catch (err) {
@@ -394,7 +421,7 @@ function registerGenerateTools(server, client, options = {}) {
         completed_scenes: completed,
         _hint: status.state === 'completed'
           ? 'All scenes terminal. Every completed scene\'s image_urls/video_urls are final.'
-          : 'Still running. Call get_creative_director_status once with wait=true; do not poll it in a loop.'
+          : `Still running — not a failure. Each wait=true call blocks for at most ~${WAIT_WINDOW_S}s, and a video batch routinely outlasts several windows, so call get_creative_director_status again with wait=true and keep going until state is terminal. Scenes that already carry image_urls/video_urls are done; never re-run generate_creative_director.`
       }, null, 2) }] };
     }
   );
@@ -419,13 +446,14 @@ function registerGenerateTools(server, client, options = {}) {
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" to apply a saved motion/style preset to this generation.'),
       sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Veo 3.1, Kling V3/2.6, PixVerse V6). On `sound_generation_type: "none"` models the flag has no effect. Omit to use the model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio. Enabling sound may apply `sound_credit_multiplier` to cost.'),
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one video ungraded.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ prompt, prompts, model, aspect_ratio, duration, enhance_prompt = false, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id }) => {
+    async ({ prompt, prompts, model, aspect_ratio, duration, enhance_prompt = false, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id, session_id }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
       model = await canonicalModelId(client, model, 'text_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       const shared = {
-        model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id
+        model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id, session_id
       };
 
       // Batch mode: N different prompts, one widget owning all generation ids.
@@ -465,6 +493,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
@@ -480,10 +509,16 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_video_from_image ─────────────────────────────
   server.tool(
     'generate_video_from_image',
-    'Animate an existing still image into a video using Kolbo AI. The image comes from `image_url`; `prompt` describes the motion (not the subject — the subject is already in the image). For generating a video from scratch, use generate_video. Returns the final video URL when complete.',
+    'Animate an existing still image into a video using Kolbo AI. The image comes from `image_url`; `prompt` describes the motion (not the subject — the subject is already in the image). For generating a video from scratch, use generate_video. ANIMATING SEVERAL SHOTS OF THE SAME SEQUENCE? Pass them ALL in `items` in ONE call (one combined widget) — never a series of separate calls, which buries the chat under one widget per clip. Across calls (a sequence longer than the batch cap), make the first call without `session_id`, take the `session_id` from its result, and pass that same `session_id` on every following call — otherwise each clip becomes its own session and the user gets a stack of near-identical single-clip sessions in the Kolbo sidebar. Returns the final video URL(s) when complete.',
     {
-      image_url: z.string().describe('URL of the source image to animate'),
-      prompt: z.string().describe('Text description of the desired MOTION (e.g., "camera slowly pans right while the character walks forward")'),
+      image_url: z.string().optional().describe('URL of the source image to animate. Required unless `items` is provided.'),
+      prompt: z.string().optional().describe('Text description of the desired MOTION (e.g., "camera slowly pans right while the character walks forward"). Required unless `items` is provided.'),
+      items: z.array(z.object({
+        image_url: z.string().describe('URL of the source image to animate for THIS clip.'),
+        prompt: z.string().describe('Text description of the desired MOTION for THIS clip.'),
+      })).max(MAX_BATCH_PROMPTS).optional().describe(
+        `BATCH MODE — several DIFFERENT stills (2–${MAX_BATCH_PROMPTS}) animated concurrently in ONE call and rendered together in ONE combined widget. Unlike the \`prompts\` array on generate_image / generate_video, each entry pairs its OWN \`image_url\` with its OWN motion \`prompt\` — the image is what varies, and that is the point. **Hard cap: ${MAX_BATCH_PROMPTS} items per call — more than that is REJECTED with an error (never silently truncated), so split a longer sequence across several calls of at most ${MAX_BATCH_PROMPTS}.** Whenever the user wants several stills animated (a shot sequence, a storyboard, an animatic), ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All items share the same model / duration / resolution / aspect_ratio / sound_enabled / project_id / session_id. When set, \`image_url\` and \`prompt\` are ignored.`
+      ),
       model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "seedance-2" (versatile) or "veo3" (Veo 3.1, cinematic + native audio); the Kling family (call list_models for exact ids like kling-video/v3/pro/image-to-video) is strongest for motion. Call list_models type="img_to_video" to see all options and choose per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
       duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
@@ -492,13 +527,34 @@ function registerGenerateTools(server, client, options = {}) {
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions.'),
       sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Veo 3.1 Lite, Kling V3 4K, PixVerse V6, Kling 2.6/v3). On `sound_generation_type: "none"` models the flag has no effect. Omit to use the model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio. Enabling sound may apply `sound_credit_multiplier` to cost.'),
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one video ungraded.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id }) => {
+    async ({ image_url, prompt, items, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id, session_id }) => {
+      if (!(items && items.length) && !(image_url && prompt)) throw new Error('Provide image_url + prompt, or items');
       model = await canonicalModelId(client, model, 'img_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
-      const gen = await client.post('/v1/generate/video/from-image', {
-        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id
-      });
+      const shared = {
+        model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id, session_id
+      };
+
+      // Batch mode: N different stills, one widget owning all generation ids.
+      // Same fan-out as generate_video's prompts[], except the varying part is
+      // the (image_url, prompt) PAIR — submitBatch carries the prompt as the
+      // per-tile caption either way.
+      if (items && items.length) {
+        const batch = await submitBatch(items, (it) => client.post('/v1/generate/video/from-image', { ...shared, image_url: it.image_url, prompt: it.prompt }));
+        if (ui()) return uiGenerating({
+          tool: 'generate_video_from_image', kind: 'video', gen: batch.ok[0].gen, client, model,
+          count: batch.ids.length, settings: { duration, resolution, aspect_ratio },
+          generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
+          failed_submissions: batch.failed,
+          status_args: { generation_ids: batch.ids, wait: true },
+          reference_image: items[0].image_url
+        });
+        return pollBatch(client, batch, { interval: (batch.ok[0].gen.poll_interval_hint || 8) * 1000, timeout: 900000 });
+      }
+
+      const gen = await client.post('/v1/generate/video/from-image', { ...shared, image_url, prompt });
 
       if (ui()) return uiGenerating({
         tool: 'generate_video_from_image', kind: 'video', gen, client, model, prompt,
@@ -520,11 +576,12 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
             thumbnail_url: result.result.thumbnail_url,
-            _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video or generate_video_from_video. Do NOT re-run generate_video_from_image unless they want a fresh animation from a different source image.'
+            _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video or generate_video_from_video. Do NOT re-run generate_video_from_image unless they want a fresh animation from a different source image. Animating more shots of THIS same sequence? Pass the session_id above back on each of those calls so they all land in one session.'
           }, null, 2)
         }]
       };
@@ -555,15 +612,16 @@ function registerGenerateTools(server, client, options = {}) {
       use_composition_plan: z.boolean().optional().describe('Suno: enable structured composition planning (verse/chorus structure).'),
       singing_dna_id: z.string().optional().describe('Visual DNA character id whose singing voice to use (must be owned by the caller).'),
       singing_voice_id: z.string().optional().describe('Custom cloned singing-voice id (must be owned by the caller).'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt = false, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, project_id }) => {
+    async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt = false, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'music_gen'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/music', {
         prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags,
         duration_seconds, enhance_prompt, preset_id,
         style_weight, weirdness, audio_weight, persona_id, use_composition_plan,
-        singing_dna_id, singing_voice_id, project_id
+        singing_dna_id, singing_voice_id, project_id, session_id
       });
 
       if (ui()) return uiGenerating({
@@ -583,6 +641,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             title: result.result.title,
             duration: result.result.duration,
@@ -627,9 +686,10 @@ function registerGenerateTools(server, client, options = {}) {
       minimax_vol: z.number().optional().describe('MiniMax volume, 0–10. Default 1.'),
       minimax_intensity: z.number().optional().describe('MiniMax voice intensity.'),
       minimax_timbre: z.number().optional().describe('MiniMax voice timbre.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ text, voice, model, language, style_instructions, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id }) => {
+    async ({ text, voice, model, language, style_instructions, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'text_to_speech'); // lenient id resolution ("z-image" → "z-image/turbo")
       // Resolve the requested voice against the REAL catalog (cached) so the card
       // can show its display name + portrait instead of a raw id, and so an id
@@ -647,7 +707,7 @@ function registerGenerateTools(server, client, options = {}) {
         similarity_boost, style, use_speaker_boost,
         variance, tempo, promptBoost, seed, accentControl, voiceTitle,
         minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre,
-        project_id
+        project_id, session_id
       });
 
       if (ui()) return uiGenerating({
@@ -669,6 +729,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             voice: result.result.voice,
             duration: result.result.duration,
@@ -701,15 +762,16 @@ function registerGenerateTools(server, client, options = {}) {
       seed_pitch: z.number().optional().describe('FAL Seed-Audio: pitch shift in semitones.'),
       seed_reference_audio_urls: z.array(z.string()).optional().describe('FAL Seed-Audio: up to 3 reference audio URLs to condition the sound.'),
       seed_reference_image_url: z.string().optional().describe('FAL Seed-Audio: a reference image URL to condition the sound.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ prompt, model, duration, prompt_influence, cfg_strength, sound_loop, sound_tempo, sound_key, seed_voice, seed_speed, seed_volume, seed_pitch, seed_reference_audio_urls, seed_reference_image_url, project_id }) => {
+    async ({ prompt, model, duration, prompt_influence, cfg_strength, sound_loop, sound_tempo, sound_key, seed_voice, seed_speed, seed_volume, seed_pitch, seed_reference_audio_urls, seed_reference_image_url, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'text_to_sound'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/sound', {
         prompt, model, duration, prompt_influence,
         cfg_strength, sound_loop, sound_tempo, sound_key,
         seed_voice, seed_speed, seed_volume, seed_pitch,
-        seed_reference_audio_urls, seed_reference_image_url, project_id
+        seed_reference_audio_urls, seed_reference_image_url, project_id, session_id
       });
 
       if (ui()) return uiGenerating({
@@ -729,6 +791,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result.urls,
             duration: result.result.duration
           }, null, 2)
@@ -766,11 +829,11 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
-    'Check the status of one or more generations. Use after a generation tool returned "submitted" (widget hosts) or timed out. Tracking SEVERAL concurrent generations? Pass them ALL in generation_ids — one call returns an all_done summary. Need the final result? Set wait=true and the server blocks until every generation finishes (up to ~3 min). NEVER call this tool repeatedly in a loop — one wait=true call replaces the whole loop.',
+    `Check the status of one or more generations. Use after a generation tool returned "submitted" (widget hosts) or timed out. Tracking SEVERAL concurrent generations? Pass them ALL in generation_ids — one call returns an all_done summary. Need the final result? Set wait=true and the server blocks until every generation finishes, for at most ~${WAIT_WINDOW_S}s per call. A job that outlives one window (music is ~3 min, video longer) comes back state="processing" — that is a normal result, not an error: call again with wait=true and keep going until every id is terminal. Never poll with wait=false in a loop.`,
     {
       generation_id: z.string().optional().describe('A single generation ID to check'),
       generation_ids: z.array(z.string()).optional().describe('Multiple generation IDs to check in ONE call. Returns { all_done, pending, generations[] } — always prefer this over checking IDs one by one.'),
-      wait: z.boolean().optional().describe('If true, block until every generation reaches a terminal state (completed/failed), up to ~3 minutes, then return the final results. Use this instead of re-calling the tool in a loop.')
+      wait: z.boolean().optional().describe(`If true, block until every generation reaches a terminal state (completed/failed), for at most ~${WAIT_WINDOW_S}s per call, then return whatever state they are in. Anything still processing is reported, not errored — re-issue with wait=true and only the still-pending ids. This is always better than polling with wait=false.`)
     },
     async ({ generation_id, generation_ids, wait }) => {
       const ids = (generation_ids && generation_ids.length > 0)
@@ -785,15 +848,16 @@ function registerGenerateTools(server, client, options = {}) {
           if (wait) {
             // Widgets use this long-wait path. A 15s API check cadence keeps
             // completion responsive without multiplying backend traffic for
-            // every card left open in a host conversation.
-            const result = await pollUntilDone(client, id, { interval: 15000, timeout: 180000 });
+            // every card left open in a host conversation. The window itself is
+            // bounded by the transport — see WAIT_WINDOW_MS above.
+            const result = await pollUntilDone(client, id, { interval: 15000, timeout: WAIT_WINDOW_MS });
             return { generation_id: id, ...result };
           }
           const result = await client.get(`/v1/generate/${encodeURIComponent(id)}/status`);
           return { generation_id: id, ...result };
         } catch (err) {
           if (err.timedOut) {
-            return { generation_id: id, state: 'processing', _timed_out: true, note: 'Still running after 3 min of waiting — call get_generation_status again with wait=true.' };
+            return { generation_id: id, state: 'processing', _timed_out: true, note: `Still running after this ~${WAIT_WINDOW_S}s wait window — call get_generation_status again with wait=true.` };
           }
           if (err.name === 'GenerationFailedError') {
             return { generation_id: id, state: 'failed', error: err.message };
@@ -807,9 +871,15 @@ function registerGenerateTools(server, client, options = {}) {
 
       const pending = results.filter(r => r.state !== 'completed' && r.state !== 'failed' && r.state !== 'cancelled');
       const doneHint = 'ALL generations are in a final state — do NOT poll again. Report the results to the user.';
-      const pendingHint = wait
-        ? 'Some generations are still running after the wait window. Call get_generation_status ONCE more with wait=true and the remaining generation_ids — do not spin without wait.'
-        : 'Some generations are still processing. Do NOT re-call this tool in a loop — call it ONCE with wait=true (and all pending generation_ids) to block until they finish.';
+      // The old wait=false hint said "call it ONCE with wait=true ... to block
+      // until they finish". That is the advice that broke: one wait=true call
+      // cannot outlast a 185s music job, and a caller that obeyed it got a
+      // transport error instead of a result. Say what actually works.
+      const pendingIds = pending.map(r => r.generation_id);
+      const idsPhrase = pendingIds.length > 1
+        ? ` and ONLY the still-pending ids: ${JSON.stringify(pendingIds)}`
+        : '';
+      const pendingHint = stillRunningHint(idsPhrase);
 
       // Single-id calls keep the original flat shape — the generation widget
       // waits on this tool with { generation_id, wait:true } and reads
@@ -917,9 +987,10 @@ function registerGenerateTools(server, client, options = {}) {
         image_url: z.string().describe('Public URL of the keyframe image'),
         timestamp_seconds: z.number().describe('Moment on the OUTPUT timeline (seconds, 0 = first frame) where this image is pinned')
       })).optional().describe('Timeline-pinned keyframes for multi-keyframe models (e.g. "flux-3-keyframes", "luma-ray-3-2-storyboard"): the model generates the motion BETWEEN the pinned images. Only models with `supports_keyframes: true` in list_models accept this; cap = `max_keyframes` (FLUX 3: 10). Requires an explicit `duration` — timestamps beyond it are clamped. Ignored by ordinary elements models. OPTIONAL for flux-3-keyframes: if omitted, pass the images via reference_images instead — they are played through IN ORDER, timed from timing language in the prompt or spaced evenly. Pass explicit keyframes only when you need exact control.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, project_id }) => {
+    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt) throw new Error('prompt is required');
 
@@ -943,6 +1014,7 @@ function registerGenerateTools(server, client, options = {}) {
         if (resolution) form.append('resolution', resolution);
         if (keyframes) form.append('keyframes', JSON.stringify(keyframes));
         if (project_id) form.append('project_id', project_id);
+        if (session_id) form.append('session_id', session_id);
         for (const f of resolved) {
           form.append('files', f.buffer, { filename: f.filename, contentType: f.contentType });
         }
@@ -950,7 +1022,7 @@ function registerGenerateTools(server, client, options = {}) {
       } else {
         // URL-only mode: plain JSON.
         startResponse = await client.post('/v1/generate/elements', {
-          prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, keyframes, project_id
+          prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, keyframes, project_id, session_id
         });
       }
 
@@ -972,6 +1044,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: startResponse.session_id,
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -998,9 +1071,10 @@ function registerGenerateTools(server, client, options = {}) {
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false`, DNA is silently ignored.**'),
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt = false, visual_dna_ids, resolution, project_id }) => {
+    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt = false, visual_dna_ids, resolution, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'firstlastgenerations'); // lenient id resolution ("z-image" → "z-image/turbo")
       const urlMode = first_frame_url && last_frame_url;
       const fileMode = first_frame && last_frame;
@@ -1028,10 +1102,11 @@ function registerGenerateTools(server, client, options = {}) {
         if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
         if (resolution) form.append('resolution', resolution);
         if (project_id) form.append('project_id', project_id);
+        if (session_id) form.append('session_id', session_id);
         startResponse = await client.postMultipart('/v1/generate/first-last-frame', form);
       } else {
         startResponse = await client.post('/v1/generate/first-last-frame', {
-          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution, project_id
+          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution, project_id, session_id
         });
       }
 
@@ -1053,6 +1128,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: startResponse.session_id,
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -1088,9 +1164,10 @@ function registerGenerateTools(server, client, options = {}) {
         bounding_boxes_url: z.string().optional().describe('URL to a JSON file with per-frame boxes.'),
         face_image: z.string().optional().describe('Base64-encoded reference face image.')
       }).optional().describe('Sync-3 only: choose which speaker gets synced in a multi-person video. Use auto_detect:true for automatic, or coordinates + frame_number to pin a specific face.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ source, audio, text_prompt, model, bounding_box_target, sync_mode, model_mode, emotion, temperature, occlusion_detection_enabled, active_speaker_detection, project_id }) => {
+    async ({ source, audio, text_prompt, model, bounding_box_target, sync_mode, model_mode, emotion, temperature, occlusion_detection_enabled, active_speaker_detection, project_id, session_id }) => {
       model = await canonicalModelId(client, model, ['lipsync-image', 'lipsync-video']); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source) throw new Error('source is required (URL or absolute local path to image/video)');
       if (!audio) throw new Error('audio is required (URL or absolute local path to audio file)');
@@ -1114,7 +1191,7 @@ function registerGenerateTools(server, client, options = {}) {
           temperature,
           occlusion_detection_enabled,
           active_speaker_detection,
-          project_id
+          project_id, session_id
         });
       } else {
         // File mode (or mixed — resolve any local paths, pass URLs through as body fields)
@@ -1144,6 +1221,7 @@ function registerGenerateTools(server, client, options = {}) {
         if (occlusion_detection_enabled !== undefined) form.append('occlusion_detection_enabled', String(occlusion_detection_enabled));
         if (active_speaker_detection) form.append('active_speaker_detection', JSON.stringify(active_speaker_detection));
         if (project_id) form.append('project_id', project_id);
+        if (session_id) form.append('session_id', session_id);
         startResponse = await client.postMultipart('/v1/generate/lipsync', form);
       }
 
@@ -1165,6 +1243,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: startResponse.session_id,
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -1209,9 +1288,10 @@ function registerGenerateTools(server, client, options = {}) {
           highlighted: z.object({ font: z.string().optional(), weight: z.number().int().min(100).max(900).optional(), color: z.string().optional() }).optional().describe('Highlighted word tier styling.'),
         }).optional(),
       }).optional().describe('VEED Subtitles only: style overrides. Any omitted field keeps the preset default. Best supported by Basic presets.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, project_id }) => {
+    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'video_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source_video) throw new Error('source_video is required');
 
@@ -1221,7 +1301,7 @@ function registerGenerateTools(server, client, options = {}) {
         startResponse = await client.post('/v1/generate/video-from-video', {
           video_url: source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution,
           reference_images, reference_videos, elements, preset, source_language, translation_language,
-          srt_content, srt_file_url, vocabulary, customization, project_id
+          srt_content, srt_file_url, vocabulary, customization, project_id, session_id
         });
       } else {
         const resolved = await resolveToBuffer(source_video, 'video');
@@ -1245,6 +1325,7 @@ function registerGenerateTools(server, client, options = {}) {
         if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
         if (elements) form.append('elements', JSON.stringify(elements));
         if (project_id) form.append('project_id', project_id);
+        if (session_id) form.append('session_id', session_id);
         startResponse = await client.postMultipart('/v1/generate/video-from-video', form);
       }
 
@@ -1267,6 +1348,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: startResponse.session_id,
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -1291,15 +1373,16 @@ function registerGenerateTools(server, client, options = {}) {
       words_per_line: z.number().optional().describe('SRT: max words per subtitle line, 1–18. Default: 12.'),
       lines_per_subtitle: z.number().optional().describe('SRT: max lines per subtitle cue, 1–4. Default: 2.'),
       stretch_captions: z.boolean().optional().describe('SRT: extend each cue\'s end time to the next cue\'s start (gap-free subtitles). Default: true.'),
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
-    async ({ source, language, diarize, tag_audio_events, remove_punctuation, generate_srt, words_per_line, lines_per_subtitle, stretch_captions, project_id }) => {
+    async ({ source, language, diarize, tag_audio_events, remove_punctuation, generate_srt, words_per_line, lines_per_subtitle, stretch_captions, project_id, session_id }) => {
       if (!source) throw new Error('source is required (URL or absolute local path)');
 
       // Advanced transcription controls forwarded when provided (undefined keys are dropped by the client).
       const opts = {
         language, diarize, tag_audio_events, remove_punctuation,
-        generate_srt, words_per_line, lines_per_subtitle, stretch_captions, project_id
+        generate_srt, words_per_line, lines_per_subtitle, stretch_captions, project_id, session_id
       };
 
       const isUrl = /^https?:\/\//i.test(source);
@@ -1343,6 +1426,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: startResponse.session_id,
             text: result.result?.text || '',
             srt_url: result.result?.srt_url || null,
             word_by_word_srt_url: result.result?.word_by_word_srt_url || null,
@@ -1506,13 +1590,14 @@ function registerGenerateTools(server, client, options = {}) {
       ai_optimize: z.boolean().optional()
         .describe('Whether to let Kolbo AI enhance your prompt before sending to the model. Default: false — your prompt reaches the model exactly as written. Only pass true if the user explicitly asks to enhance/improve the prompt.'),
 
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
     async ({
       image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
       mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize = false,
       zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
-      project_id
+      project_id, session_id
     }) => {
       // No `type` argument: these are operation-routed tools (upscale / reframe /
       // removebg / …), each operation with its own model family — there is no single
@@ -1530,7 +1615,7 @@ function registerGenerateTools(server, client, options = {}) {
         image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
         mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize,
         zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
-        project_id
+        project_id, session_id
       });
 
       if (ui()) return uiGenerating({
@@ -1552,6 +1637,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result?.urls || [],
             edit_type: result.result?.edit_type || null,
             model: result.result?.model || null
@@ -1656,7 +1742,8 @@ function registerGenerateTools(server, client, options = {}) {
       start_time: z.number().optional()
         .describe('Start time in seconds of the segment to retake. Used with operation="retake".'),
 
-      project_id: projectIdField
+      project_id: projectIdField,
+      session_id: sessionIdField
     },
     async ({
       video_url, operation, model, aspect_ratio, scale, prompt,
@@ -1668,7 +1755,7 @@ function registerGenerateTools(server, client, options = {}) {
       text_prompt, context,
       mask_video_url, object_prompt, video_strength,
       start_time,
-      project_id
+      project_id, session_id
     }) => {
       // No `type` argument: these are operation-routed tools (upscale / reframe /
       // removebg / …), each operation with its own model family — there is no single
@@ -1693,7 +1780,7 @@ function registerGenerateTools(server, client, options = {}) {
         text_prompt, context,
         mask_video_url, object_prompt, video_strength,
         start_time,
-        project_id
+        project_id, session_id
       });
 
       if (ui()) return uiGenerating({
@@ -1715,6 +1802,7 @@ function registerGenerateTools(server, client, options = {}) {
           type: 'text',
           text: JSON.stringify({
             ...creditFields(result),
+            session_id: gen.session_id,
             urls: result.result?.urls || [],
             download_url: result.result?.download_url || null,
             edit_type: result.result?.edit_type || null,

package/src/tools/media.js

@@ -27,17 +27,26 @@ async function mintUploadTicket(client) {
 // holding a token they must use immediately, and telling one of them to go call
 // another tool to learn the POST shape would spend the round trip this whole
 // path exists to remove.
+// The ticket is reusable for a whole batch, but the endpoint is rate limited —
+// and a batch uploader that only learns that from the 41st POST has already
+// stalled halfway through. kolbo-api sends the real numbers in `rate_limit`;
+// this fallback covers an older deployment that predates that field.
+const DEFAULT_UPLOAD_RATE = { max_uploads: 40, per_seconds: 60 };
+
 function uploadTicketPayload(ticket) {
+  const rate = ticket.rate_limit || DEFAULT_UPLOAD_RATE;
   return {
     upload_url: ticket.upload_url,
     token: ticket.token,
     expires_in_seconds: ticket.expires_in,
     max_file_mb: ticket.max_file_mb || DEFAULT_MAX_FILE_MB,
     accepted: ticket.accepted,
+    rate_limit: rate,
     how_to_upload: {
       example: 'curl -X POST "<upload_url>" -H "Authorization: Bearer <token>" -F "file=@/absolute/path/to/file.mp3"',
       optional_fields: ['project_id', 'description'],
       response: 'JSON — the stable CDN URL is at media.url. One POST per file; reuse the ticket for a batch.',
+      pacing: `RATE LIMIT: ${rate.max_uploads} uploads per ${rate.per_seconds}s. For a batch larger than that, pace it (e.g. sleep ${Math.max(1, Math.ceil(rate.per_seconds / rate.max_uploads))}s between files) instead of firing them back to back. Over the limit you get HTTP 429 with a Retry-After header and retry_after_seconds in the body — wait that long, then continue; do not guess a backoff and do not treat it as a failed upload.`,
       // Git Bash hands curl a POSIX-style /c/Users/... path that Windows curl
       // cannot open (exit 26). Real trap — it cost a round trip to find.
       windows_note: 'Give curl a native path (C:/Users/...) — a Git Bash /c/Users/... path fails to open.',
@@ -119,7 +128,7 @@ function registerMediaTools(server, client, options = {}) {
   // ─── create_upload_ticket ──────────────────────────────────
   server.tool(
     'create_upload_ticket',
-    'Get a short-lived ticket for uploading LOCAL files straight into the user\'s Kolbo media library, with NO upload card and no user interaction. ' + ticketRouting + ' Why it exists: when the server cannot read the caller\'s disk, the only other ways in are making the user click an upload card (`media_upload_widget`) or inlining the file as base64 via `upload_media` — base64 is slow and burns context in proportion to file size, so do not use it for anything but a tiny file. Returns `upload_url` + `token`; POST each file as multipart field `file` with header `Authorization: Bearer <token>` and read the CDN URL from `media.url` in the response. One POST per file; the ticket is reusable until it expires. Then pass those URLs to any generation tool (transcribe_audio, generate_image_edit, generate_video_from_image, generate_lipsync, visual DNA, …).',
+    'Get a short-lived ticket for uploading LOCAL files straight into the user\'s Kolbo media library, with NO upload card and no user interaction. ' + ticketRouting + ' Why it exists: when the server cannot read the caller\'s disk, the only other ways in are making the user click an upload card (`media_upload_widget`) or inlining the file as base64 via `upload_media` — base64 is slow and burns context in proportion to file size, so do not use it for anything but a tiny file. Returns `upload_url` + `token`; POST each file as multipart field `file` with header `Authorization: Bearer <token>` and read the CDN URL from `media.url` in the response. One POST per file; the ticket is reusable until it expires. The endpoint is RATE LIMITED (the exact cap and window come back in the ticket\'s `rate_limit` field — currently 40 uploads/minute): pace a batch bigger than that rather than firing every file at once, and on HTTP 429 honour the `Retry-After` header / `retry_after_seconds` body field instead of guessing a backoff. Then pass those URLs to any generation tool (transcribe_audio, generate_image_edit, generate_video_from_image, generate_lipsync, visual DNA, …).',
     {},
     async () => {
       const ticket = await mintUploadTicket(client);

package/src/tools/models.js

@@ -325,8 +325,14 @@ function registerModelTools(server, client, options = {}) {
         const flat = String(s).replace(/\s+/g, ' ').trim();
         return flat.length > 130 ? flat.slice(0, 127).trimEnd() + '…' : flat;
       };
+      // Text models bill per token — the flat `credit` is not what the user pays,
+      // so show the real per-1K rates when the API supplies them. Without this the
+      // "cheapest model that fits" rule is unusable for chat.
+      const cost = m => (m.output_token_rate != null
+        ? `${m.input_token_rate ?? '?'}/${m.output_token_rate} credits per 1K tokens (in/out)`
+        : `${m.credit} credits`);
       const formatModel = m =>
-        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${detailed ? m.summary : brief(m.summary)}` : ''}${detailed ? formatSpecs(m) : ''}`;
+        `${m.identifier} (${m.name}) - ${cost(m)}${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${detailed ? m.summary : brief(m.summary)}` : ''}${detailed ? formatSpecs(m) : ''}`;
 
       const sections = [];
 
@@ -341,7 +347,10 @@ function registerModelTools(server, client, options = {}) {
         }
         const text = `Kolbo model catalog — ${result.count} models total.\n\n`
           + `${sections.join('\n\n')}\n\n`
-          + 'This is the curated shortlist, not the full catalog. To see everything in a '
+          + 'This shortlist is BADGE-BASED (recommended/new) — it is not a recommendation to '
+          + 'use the newest or biggest model. To pick properly, re-call with `type` and choose by '
+          + 'each model\'s strengths summary, taking the cheapest one that covers the task. '
+          + 'To see everything in a '
           + 'category (with per-model resolutions, durations, aspect ratios and reference-image '
           + 'caps), re-call with `type`:\n'
           + '  text_to_img · image_editing · text_to_video · img_to_video · video_to_video ·\n'
@@ -354,7 +363,7 @@ function registerModelTools(server, client, options = {}) {
       }
 
       if (withSummary.length > 0) {
-        sections.push(`Auto-selectable models (${withSummary.length}) — safe to pick based on quality + cost:\n${withSummary.map(formatModel).join('\n')}`);
+        sections.push(`Auto-selectable models (${withSummary.length}) — CHOOSE BY THE SUMMARY after each "—": match it to what the user asked for, then take the CHEAPEST model that fits. Credit cost, [NEW] and [RECOMMENDED] are not reasons to pick a model:\n${withSummary.map(formatModel).join('\n')}`);
       }
       if (withoutSummary.length > 0) {
         sections.push(`Named-only models (${withoutSummary.length}) — only use if the user explicitly requests by name:\n${withoutSummary.map(formatModel).join('\n')}`);

package/src/tools/music_library.js

@@ -30,7 +30,7 @@ function tracksResult(ui, title, tracks, total) {
   if (!tracks.length) return { content: [{ type: 'text', text: 'No SYNCI tracks found.' }] };
   const text = [
     `Found ${tracks.length} track${tracks.length === 1 ? '' : 's'}${total ? ` (of ${total})` : ''}.`,
-    'Playback URLs are watermarked previews. Use acquire_clean_music_track for final use; it consumes one SYNCI vendor credit.',
+    'Playback URLs are watermarked previews. Use acquire_clean_music_track for final use. ' + "Free for subscribers, org members and anyone who already bought the track; for everyone else it COSTS CREDITS (the search response carries the exact price in cleanTrackCredits, and cleanAccess:false means this caller will be charged). State the cost and get the user's agreement BEFORE calling it.",
     '',
     tracks.map(trackLine).join('\n\n'),
   ].join('\n');
@@ -68,12 +68,12 @@ function registerMusicLibraryTools(server, client, options = {}) {
     'search_music_library',
     'Search the licensed SYNCI catalog — the PAID third-party option. ' +
     '⚠️ NOT the default for music. Kolbo has its OWN large AI music library that is FREE and ' +
-    'costs no vendor credit: call search_stock_media with source="kolbo-ai" and mediaType="music" ' +
+    'is usually cheaper or free: call search_stock_media with source="kolbo-ai" and mediaType="music" ' +
     '(it also supports natural-language vibe search, e.g. "uplifting hopeful corporate background"). ' +
     'Reach for SYNCI only when the user explicitly asks for the licensed/SYNCI catalog, names a real ' +
     'artist or commercial track, or needs stems / a specific licensed cue. ' +
     'Results here contain watermarked preview audio only; any download or timeline use requires ' +
-    'acquire_clean_music_track, which consumes one SYNCI vendor credit.',
+    'acquire_clean_music_track. ' + "Free for subscribers, org members and anyone who already bought the track; for everyone else it COSTS CREDITS (the search response carries the exact price in cleanTrackCredits, and cleanAccess:false means this caller will be charged). State the cost and get the user's agreement BEFORE calling it.",
     {
       query: z.string().max(200).optional(),
       mood: z.string().optional(),
@@ -171,7 +171,7 @@ function registerMusicLibraryTools(server, client, options = {}) {
 
   server.tool(
     'acquire_clean_music_track',
-    'Acquire a clean, unwatermarked SYNCI MP3 or WAV for download or Adobe timeline use. This immediately consumes one SYNCI vendor credit with no confirmation dialog. Reuse request_id when retrying the same intended action.',
+    'Acquire a clean, unwatermarked SYNCI MP3 or WAV for download or Adobe timeline use. Charges IMMEDIATELY with no confirmation dialog. ' + "Free for subscribers, org members and anyone who already bought the track; for everyone else it COSTS CREDITS (the search response carries the exact price in cleanTrackCredits, and cleanAccess:false means this caller will be charged). State the cost and get the user's agreement BEFORE calling it." + ' Once bought, the track is owned permanently: the other format, its stems and every re-download are free. Reuse request_id when retrying the same intended action.',
     {
       track_id: z.string().min(1).max(64),
       format: z.enum(['mp3', 'wav']).optional().describe('Default mp3. Use wav only when the search result reports hqAvailable=true.'),
@@ -193,7 +193,7 @@ function registerMusicLibraryTools(server, client, options = {}) {
 
   server.tool(
     'import_music_track_to_library',
-    'Acquire one clean SYNCI file and copy it into the Kolbo media library. This immediately consumes one SYNCI vendor credit unless the track is already in the library. Defaults to clean MP3.',
+    'Acquire one clean SYNCI file and copy it into the Kolbo media library. Charges IMMEDIATELY unless the track is already in the library or already owned. ' + "Free for subscribers, org members and anyone who already bought the track; for everyone else it COSTS CREDITS (the search response carries the exact price in cleanTrackCredits, and cleanAccess:false means this caller will be charged). State the cost and get the user's agreement BEFORE calling it." + ' Defaults to clean MP3.',
     {
       track_id: z.string().min(1).max(64),
       format: z.enum(['mp3', 'wav']).optional(),

package/src/tools/stock_library.js

@@ -7,12 +7,17 @@ const { compactList } = require('./_shared');
 
 // Compact one-line render of a normalized stock asset.
 function assetLine(a) {
+  // What THIS caller would pay, stamped per asset by the API. 0/absent = free
+  // (subscriber, org member, or already bought). Surfaced in the text the agent
+  // reads so it can warn before spending someone's credits.
+  const price = a.meta && a.meta.priceCredits;
+  const cost = (a.meta && a.meta.owned) ? '  [purchased]' : (price ? `  [${price} credits]` : '');
   const dims = a.width && a.height ? `${a.width}x${a.height}` : null;
   const dur = a.durationSeconds != null ? `${Math.round(a.durationSeconds)}s` : null;
   const meta = [a.mediaType, dims, dur].filter(Boolean).join(' · ');
   const by = a.author?.name ? ` by ${a.author.name}` : '';
   const variants = Array.isArray(a.downloadVariants) ? a.downloadVariants.map((v) => v.label).join('/') : '';
-  return `[${a.source}:${a.sourceId}] ${a.title || '(untitled)'}${by}\n   ${meta}${variants ? `  variants: ${variants}` : ''}${a.thumbnailUrl ? `\n   thumb: ${a.thumbnailUrl}` : ''}`;
+  return `[${a.source}:${a.sourceId}] ${a.title || '(untitled)'}${by}${cost}\n   ${meta}${variants ? `  variants: ${variants}` : ''}${a.thumbnailUrl ? `\n   thumb: ${a.thumbnailUrl}` : ''}`;
 }
 
 // Returns the raw querystring (no leading '?'). Callers inline it as
@@ -37,7 +42,7 @@ function registerStockLibraryTools(server, client, options = {}) {
   server.tool(
     'search_stock_media',
     'Search the Kolbo unified stock media library and return matching assets. ' +
-    '★ THE DEFAULT TOOL FOR MUSIC: Kolbo\'s own AI music library is FREE (no vendor credit) — ' +
+    '★ THE DEFAULT TOOL FOR MUSIC: Kolbo\'s own AI music library, free for subscribers and org members and priced per track otherwise (every result states its own cost) — ' +
     'use source="kolbo-ai" with mediaType="music" for background/score/bed requests. Prefer it over ' +
     'search_music_library (SYNCI), which is the paid licensed catalog and should only be used when the ' +
     'user explicitly asks for it. ' +
@@ -84,7 +89,12 @@ function registerStockLibraryTools(server, client, options = {}) {
             media_type: mt,
             url: (a.downloadVariants?.[0]?.url) || a.thumbnailUrl,
             preview_audio: mt === 'audio' ? (a.previewUrl || a.downloadVariants?.[0]?.url) : undefined,
-            use_hint: 'Import this stock asset into my media library: import_stock_asset source="' + a.source + '" id="' + a.sourceId + '" ("{TITLE}")'
+            badge: (a.meta && a.meta.owned) ? 'Purchased' : ((a.meta && a.meta.priceCredits) ? a.meta.priceCredits + ' credits' : undefined),
+            price_credits: (a.meta && a.meta.priceCredits) || undefined,
+            owned: (a.meta && a.meta.owned) || undefined,
+            use_hint: (a.meta && a.meta.priceCredits)
+              ? 'Costs ' + a.meta.priceCredits + ' credits for this account. Confirm with the user, then: import_stock_asset source="' + a.source + '" id="' + a.sourceId + '" ("{TITLE}")'
+              : 'Import this stock asset into my media library: import_stock_asset source="' + a.source + '" id="' + a.sourceId + '" ("{TITLE}")'
           };
         });
         return uiResult(UI.mediaGrid, text, {
@@ -206,7 +216,7 @@ function registerStockLibraryTools(server, client, options = {}) {
   // ─── import_stock_asset ───────────────────────────────────────
   server.tool(
     'import_stock_asset',
-    "Copy a stock asset into the account's Kolbo media library (downloaded to Kolbo's CDN with a stable URL) so it can be used in projects/generations. Free. Returns the created media library item. Works for Kolbo SFX (source='kolbo-ai', mediaType='sfx') and supported external visual/audio sources. For SYNCI music use import_music_track_to_library; that paid action acquires a clean licensed file.",
+    "Copy a stock asset into the account's Kolbo media library (downloaded to Kolbo's CDN with a stable URL) so it can be used in projects/generations. FREE for images, video and 3D. Kolbo's own MUSIC and SFX are free for subscribers, org members and anyone who already bought the track; for everyone else they COST CREDITS (search results carry the exact price in meta.priceCredits; 0/absent means free for this caller). When a price is shown, tell the user the cost and get agreement BEFORE calling this. Returns the created media library item. Works for Kolbo SFX (source='kolbo-ai', mediaType='sfx') and supported external visual/audio sources. For SYNCI music use import_music_track_to_library; that paid action acquires a clean licensed file.",
     {
       source: z.enum(['kolbo-ai', 'pexels', 'pixabay', 'sketchfab', 'freesound']).describe('The asset source.'),
       id: z.string().describe('The provider asset id (sourceId).'),