@kolbo/mcp 1.6.5 → 1.6.9

package/package.json

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

package/src/client.js

@@ -198,12 +198,21 @@ class KolboClient {
 
   async _doRequest(method, reqPath, body = null) {
     const url = `${this.baseUrl}${reqPath}`;
+    const headers = {
+      'X-API-Key': this.apiKey,
+      'Content-Type': 'application/json'
+    };
+    // Stable per-app-launch identifier from the parent process (Kolbo Code
+    // sets this in the MCP env when spawning us). kolbo-api tags every
+    // CreditUsage record with it so the desktop UI and the get_session_usage
+    // tool can aggregate spend without enumerating individual generations.
+    const callerSessionId = process.env.KOLBO_CALLER_SESSION_ID;
+    if (callerSessionId) {
+      headers['X-Kolbo-Caller-Session-Id'] = callerSessionId;
+    }
     const options = {
       method,
-      headers: {
-        'X-API-Key': this.apiKey,
-        'Content-Type': 'application/json'
-      }
+      headers,
     };
 
     if (body) {
@@ -248,6 +257,10 @@ class KolboClient {
     return this.request('GET', reqPath);
   }
 
+  async put(reqPath, body = null) {
+    return this.request('PUT', reqPath, body);
+  }
+
   async delete(reqPath) {
     return this.request('DELETE', reqPath);
   }
@@ -266,6 +279,11 @@ class KolboClient {
       'X-API-Key': this.apiKey,
       ...formData.getHeaders()
     };
+    // Same caller-session header as JSON requests — see _doRequest.
+    const callerSessionId = process.env.KOLBO_CALLER_SESSION_ID;
+    if (callerSessionId) {
+      headers['X-Kolbo-Caller-Session-Id'] = callerSessionId;
+    }
 
     // Serialize form-data to a Buffer before passing to fetch(). Node's
     // built-in fetch (undici) can't consume legacy Node.js streams from

package/src/tools/_shared.js

@@ -200,6 +200,36 @@ async function resolveToBuffer(source, kind, opts = {}) {
   };
 }
 
+/**
+ * Extract real, multiplier-adjusted credit cost from a polled getStatus
+ * response. kolbo-api returns `credits_used` (final number deducted) and
+ * `credits_breakdown` (per-CreditUsage detail) when the generation is
+ * complete. Returns `{}` when the API didn't include them so spreading
+ * the result into a tool's response object is a no-op (forward-compatible
+ * with old kolbo-api versions).
+ *
+ * Usage in every generation tool:
+ *   return {
+ *     content: [{ type: 'text', text: JSON.stringify({
+ *       urls: result.result.urls,
+ *       model: result.result.model,
+ *       ...creditFields(result),   // adds credits_used + credits_breakdown
+ *       _followup_hint: '...',
+ *     }, null, 2) }]
+ *   };
+ */
+function creditFields(polledResult) {
+  if (!polledResult) return {};
+  const out = {};
+  if (typeof polledResult.credits_used === 'number') {
+    out.credits_used = polledResult.credits_used;
+  }
+  if (Array.isArray(polledResult.credits_breakdown) && polledResult.credits_breakdown.length) {
+    out.credits_breakdown = polledResult.credits_breakdown;
+  }
+  return out;
+}
+
 module.exports = {
   MAX_FILE_BYTES,
   VISUAL_DNA_MAX_BYTES,
@@ -208,5 +238,6 @@ module.exports = {
   safeFetch,
   guessFilename,
   guessContentType,
-  resolveToBuffer
+  resolveToBuffer,
+  creditFields,
 };

package/src/tools/app_builder.js

@@ -119,8 +119,7 @@ function registerAppBuilderTools(server, client) {
       edit_prompt: z.string().describe('Natural language instruction describing the change to make.')
     },
     async ({ session_id, generation_id, edit_prompt }) => {
-      await client.request(
-        'PUT',
+      await client.put(
         `/app-builder/generation/${encodeURIComponent(session_id)}/${encodeURIComponent(generation_id)}`,
         { editPrompt: edit_prompt }
       );

package/src/tools/chat.js

@@ -5,6 +5,7 @@
 
 const { z } = require('zod');
 const { pollUntilDone } = require('../polling');
+const { creditFields } = require('./_shared');
 
 function registerChatTools(server, client) {
   // ─── chat_send_message ─────────────────────────────────────
@@ -49,6 +50,7 @@ function registerChatTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             session_id: gen.session_id,
             message_id: gen.message_id,
             model: r.model || gen.model,

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer } = require('./_shared');
+const { resolveToBuffer, creditFields } = require('./_shared');
 
 function registerGenerateTools(server, client) {
   // ─── generate_image ────────────────────────────────────────
@@ -19,11 +19,11 @@ function registerGenerateTools(server, client) {
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
       num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1'),
-      reference_images: z.array(z.string()).optional().describe('Array of image URLs used as composition/style references (NOT as source images for editing — use generate_image_edit for that).'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) to apply for character / style / product / scene consistency. Pass the `id` field of each profile. Use this when the user wants to keep the same character or style across multiple images.'),
+      reference_images: z.array(z.string()).optional().describe('STYLE/COMPOSITION inspiration only — does NOT embed reference pixels. Array of image URLs used to guide the look-and-feel of a brand-new generation. The model interprets the references and regenerates approximations conditioned on them. It will NOT copy pixels from these images into the output. To embed a specific logo, icon, watermark, or asset pixel-accurately, use generate_image_edit with the asset in source_images. To EDIT an existing image, also use generate_image_edit.'),
+      visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) for character / style / product / scene consistency. How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (this is by design — the description carries the identity signal, independent of enhance_prompt). Practical implication: do NOT also write physical descriptors of the same subject in your own prompt — they will compete with the DNA description text. For pixel-accurate face anchoring of a specific person, prefer passing the DNA\'s reference image directly via source_images on generate_image_edit and OMIT visual_dna_ids. visual_dna_ids is best for style / scene / product DNAs and for soft consistency across a set.'),
       moodboard_id: z.string().optional().describe('Moodboard ID (from list_moodboards / get_moodboard) whose master_prompt and style_guide should be applied to this generation.'),
       enable_web_search: z.boolean().optional().describe('Enable web-search grounding for the prompt (useful for current events, brand references, real-world accuracy). Default: false'),
-      resolution: z.string().optional().describe('Image resolution tier: "1K" (~1024px), "2K" (Full HD), "3K" (QHD), or "4K" (UHD). Model-dependent — call list_models and read supported_resolutions on the chosen model. Read resolutionMultipliers on the same model to predict credit cost. Omit to use the model default.'),
+      resolution: z.string().optional().describe('Image resolution tier: "1K" (~1024px), "2K" (Full HD), "3K" (QHD), or "4K" (UHD). Model-dependent — call list_models and read supported_resolutions on the chosen model. Read resolution_multipliers on the same model to predict credit cost. Omit to use the model default.'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="image" to apply a saved style preset to this generation.')
     },
     async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id }) => {
@@ -41,9 +41,11 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
-            prompt_used: result.result.prompt_used
+            prompt_used: result.result.prompt_used,
+            _followup_hint: 'If the user asks to edit/change/modify this image next, pass urls[0] to generate_image_edit (free-form edits) or edit_image (upscale/reframe/removebg/enhance_skin/magic_edit). Do NOT call generate_image again.'
           }, null, 2)
         }]
       };
@@ -57,11 +59,11 @@ function registerGenerateTools(server, client) {
     {
       prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
       model: z.string().optional().describe('Model identifier. Use list_models type="image_editing" to see options. Omit for Smart Select.'),
-      source_images: z.array(z.string()).describe('Array of source image URLs to edit. Typically one, but some models accept multiple for compositing.'),
+      source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image"). Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
       num_images: z.number().optional().describe('Number of output images. Default: 1'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for consistency with an existing character / style / product.'),
+      visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs for character / style / product consistency. How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (by design — independent of enhance_prompt). For pixel-accurate face anchoring of a specific person on this tool, the PREFERRED pattern is to pass the face photo directly via source_images and OMIT visual_dna_ids — that way the face pixels anchor the output and no description text competes. Do NOT pass visual_dna_ids if source_images already contains the same person\'s face (face averaging). visual_dna_ids is best here for style / product DNAs.'),
       moodboard_id: z.string().optional().describe('Moodboard ID whose master_prompt and style_guide should be applied.'),
       enable_web_search: z.boolean().optional().describe('Enable web-search grounding. Default: false'),
       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.')
@@ -72,18 +74,24 @@ function registerGenerateTools(server, client) {
         visual_dna_ids, moodboard_id, enable_web_search, resolution
       });
 
+      // Multi-source compositing or DNA-anchored edits routinely exceed 120s
+      // server-side. Extend the polling window in those cases to avoid forcing
+      // every call into the timeout-and-recover path via get_generation_status.
+      const heavy = (source_images && source_images.length > 1) || (visual_dna_ids && visual_dna_ids.length > 0);
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
-        timeout: 120000
+        timeout: heavy ? 240000 : 120000
       });
 
       return {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
-            prompt_used: result.result.prompt_used
+            prompt_used: result.result.prompt_used,
+            _followup_hint: 'If the user asks for another edit on this output, pass urls[0] back into generate_image_edit as source_images. For targeted ops (upscale/reframe/removebg/enhance_skin) use edit_image instead. Do NOT call generate_image from scratch.'
           }, null, 2)
         }]
       };
@@ -133,9 +141,11 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             scenes,
             total_scenes: result.scenes?.length || 0,
-            completed_scenes: scenes.length
+            completed_scenes: scenes.length,
+            _followup_hint: 'Each scene is a separate asset. If the user asks to edit one scene, find that scene by scene_number/title and pass its image_urls[0] (or video_urls[0]) to generate_image_edit / edit_image / edit_video / generate_video_from_video. Do NOT re-run generate_creative_director unless the user explicitly wants a brand-new set.'
           }, null, 2)
         }]
       };
@@ -143,9 +153,13 @@ function registerGenerateTools(server, client) {
   );
 
   // ─── generate_video ────────────────────────────────────────
+  // NOTE: text-to-video does NOT support Visual DNA — the textToVideoGeneration
+  // controller in kolbo-api never reads visualDnaIds. For character-consistent
+  // video, use generate_elements (which DOES honor visual_dna_ids) or animate a
+  // DNA-locked still via generate_video_from_image.
   server.tool(
     'generate_video',
-    'Generate a video from a text prompt using Kolbo AI. For animating an existing still image into motion, use generate_video_from_image instead. For a coordinated multi-scene video campaign, use generate_creative_director with workflow_type="video". Supports Visual DNA profiles (for character consistency) and reference images (for style guidance). Returns the final video URL when complete.',
+    'Generate a video from a text prompt using Kolbo AI. For animating an existing still image into motion, use generate_video_from_image instead. For a coordinated multi-scene video campaign, use generate_creative_director with workflow_type="video". Supports reference images (for style/composition guidance). Does NOT support Visual DNA — for character-consistent video use generate_elements or animate a DNA-locked still via generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Text description of the video to generate'),
       model: z.string().optional().describe('Model identifier. Use list_models type="text_to_video" to see options. Check supported_durations and supported_aspect_ratios.'),
@@ -153,13 +167,12 @@ function registerGenerateTools(server, client) {
       duration: z.number().optional().describe('Duration in seconds. Must be a value the chosen model supports — check supported_durations from list_models. Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       reference_images: z.array(z.string()).optional().describe('Array of image URLs used as visual references (style / composition / subject).'),
-      visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to keep a character / style consistent with prior generations.'),
-      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. Read resolutionMultipliers to predict cost.'),
+      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. Read resolution_multipliers to predict cost.'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" to apply a saved motion/style preset to this generation.')
     },
-    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids, resolution, preset_id }) => {
+    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id }) => {
       const gen = await client.post('/v1/generate/video', {
-        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, visual_dna_ids, resolution, preset_id
+        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -171,11 +184,13 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
             thumbnail_url: result.result.thumbnail_url,
-            prompt_used: result.result.prompt_used
+            prompt_used: result.result.prompt_used,
+            _followup_hint: 'If the user asks to edit/restyle/extend this video next, pass urls[0] to edit_video (upscale/reframe/face_swap/extend/generate_audio/lipsync/magic_edit) or generate_video_from_video (restyle). Do NOT call generate_video from scratch.'
           }, null, 2)
         }]
       };
@@ -194,7 +209,7 @@ function registerGenerateTools(server, client) {
       duration: z.number().optional().describe('Duration in seconds. Must be a value the chosen model supports. Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the motion prompt. Default: true'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to maintain consistency with prior characters / styles.'),
-      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. Read resolutionMultipliers to predict cost.')
+      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. Read resolution_multipliers to predict cost.')
     },
     async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution }) => {
       const gen = await client.post('/v1/generate/video/from-image', {
@@ -210,10 +225,12 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
-            thumbnail_url: result.result.thumbnail_url
+            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.'
           }, null, 2)
         }]
       };
@@ -248,6 +265,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             title: result.result.title,
             duration: result.result.duration,
@@ -282,6 +300,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             voice: result.result.voice,
             duration: result.result.duration
@@ -315,6 +334,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             duration: result.result.duration
           }, null, 2)
@@ -386,13 +406,13 @@ function registerGenerateTools(server, client) {
   // ─── generate_elements ─────────────────────────────────────
   server.tool(
     'generate_elements',
-    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elementsMaxImages / elementsMaxVideos / elementsMaxAudio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Text description of the desired video / animation'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="elements" to see options (Seedance 2, Kling O3 Reference, Grok Imagine, Veo 3.1, etc.). Check elementsMaxImages / elementsMaxVideos / elementsMaxAudio on the model. Omit for Smart Select.'),
-      reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). Check elementsMaxImages on the chosen model — pass at most that many URLs.'),
-      reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs (elementsMaxVideos > 0). Check elementsMaxVideos on the chosen model from list_models before passing.'),
-      audio_url: z.string().optional().describe('URL of a reference audio track for models that accept audio inputs (elementsMaxAudio > 0). Check elementsMaxAudio on the chosen model from list_models before passing.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="elements" to see options (Seedance 2, Kling O3 Reference, Grok Imagine, Veo 3.1, etc.). Check elements_max_images / elements_max_videos / elements_max_audio on the model. Omit for Smart Select.'),
+      reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). Check elements_max_images on the chosen model — pass at most that many URLs.'),
+      reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs (elements_max_videos > 0). Check elements_max_videos on the chosen model from list_models before passing.'),
+      audio_url: z.string().optional().describe('URL of a reference audio track for models that accept audio inputs (elements_max_audio > 0). Check elements_max_audio on the chosen model from list_models before passing.'),
       files: z.array(z.string()).optional().describe('Array of URLs or absolute local paths — alternative to reference_images. Use this when you have local files to upload. Each item can be a URL OR a local path.'),
       duration: z.number().optional().describe('Duration in seconds. Default: 5'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"'),
@@ -442,6 +462,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -511,6 +532,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -581,6 +603,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -594,19 +617,19 @@ function registerGenerateTools(server, client) {
   // ─── generate_video_from_video ─────────────────────────────
   server.tool(
     'generate_video_from_video',
-    'Restyle / transform an existing video using a text prompt (video-to-video). Use for style transfer, scene restyling, subject swap, motion transfer, or character replacement. Source video can be a URL or absolute local path. IMPORTANT: different models support different extra inputs — call list_models type="video_to_video" and read maxImages / maxVideos / maxElements on the chosen model before generating. Pass reference_images for models with maxImages > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with maxVideos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with maxElements > 0. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.',
+    'Restyle / transform an existing video using a text prompt (video-to-video). Use for style transfer, scene restyling, subject swap, motion transfer, or character replacement. Source video can be a URL or absolute local path. IMPORTANT: different models support different extra inputs — call list_models type="video_to_video" and read max_images / max_videos / max_elements on the chosen model before generating. Pass reference_images for models with max_images > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with max_videos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with max_elements > 0. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.',
     {
       source_video: z.string().describe('URL or absolute local path to the primary source video to restyle. For models that use reference_videos as their primary input (e.g. WAN 2.6 reference-to-video), pass the first reference video here and also include it in reference_videos.'),
       prompt: z.string().describe('Text description of the desired restyle / transformation'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check maxImages / maxVideos / maxElements per model. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check max_images / max_videos / max_elements per model. Omit for Smart Select.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio. Default: matches source'),
       duration: z.number().optional().describe('Duration in seconds (default: matches source)'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for character/style consistency.'),
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.'),
-      reference_images: z.array(z.string()).optional().describe('Array of reference image URLs for models that support additional image inputs (maxImages > 0). Examples: character reference images for Kling O1/O3, style reference for Aleph/gen4_aleph, character image for WAN VACE video-edit. Check maxImages on the model from list_models before passing.'),
-      reference_videos: z.array(z.string()).optional().describe('Array of additional reference video URLs for models that support multiple video inputs (maxVideos > 1). Example: WAN 2.6 reference-to-video accepts 1–3 reference videos. Check maxVideos on the model from list_models before passing.'),
-      elements: z.array(z.string()).optional().describe('Array of element image URLs for models with maxElements > 0. Elements are used as style or character reference assets alongside the main video. Check maxElements on the model from list_models before passing.')
+      reference_images: z.array(z.string()).optional().describe('Array of reference image URLs for models that support additional image inputs (max_images > 0). Examples: character reference images for Kling O1/O3, style reference for Aleph/gen4_aleph, character image for WAN VACE video-edit. Check max_images on the model from list_models before passing.'),
+      reference_videos: z.array(z.string()).optional().describe('Array of additional reference video URLs for models that support multiple video inputs (max_videos > 1). Example: WAN 2.6 reference-to-video accepts 1–3 reference videos. Check max_videos on the model from list_models before passing.'),
+      elements: z.array(z.string()).optional().describe('Array of element image URLs for models with max_elements > 0. Elements are used as style or character reference assets alongside the main video. Check max_elements on the model from list_models before passing.')
     },
     async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, reference_images, reference_videos, elements }) => {
       if (!source_video) throw new Error('source_video is required');
@@ -645,6 +668,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -685,6 +709,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             text: result.result?.text || '',
             srt_url: result.result?.srt_url || null,
             word_by_word_srt_url: result.result?.word_by_word_srt_url || null,
@@ -737,6 +762,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             mode: result.result?.mode || null,
@@ -778,6 +804,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             edit_type: result.result?.edit_type || null,
             model: result.result?.model || null
@@ -826,6 +853,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             download_url: result.result?.download_url || null,
             edit_type: result.result?.edit_type || null,

package/src/tools/models.js

@@ -21,8 +21,64 @@ function registerModelTools(server, client) {
       const withSummary = result.models.filter(m => m.summary && m.summary.trim() !== '');
       const withoutSummary = result.models.filter(m => !m.summary || m.summary.trim() === '');
 
+      // Format the per-model spec line. The agent NEEDS this — without it,
+      // it has to guess `supported_resolutions`/`supported_durations` and
+      // either invents values (then the API silently substitutes) or asks
+      // the user to clarify what's only knowable from this list.
+      const formatSpecs = m => {
+        const parts = [];
+
+        if (Array.isArray(m.supported_resolutions) && m.supported_resolutions.length) {
+          const mult = m.resolution_multipliers || {};
+          parts.push(
+            'resolutions: ' +
+              m.supported_resolutions
+                .map(r => (mult[r] != null && mult[r] !== 1 ? `${r} (${mult[r]}×)` : r))
+                .join(' · ')
+          );
+        }
+
+        if (Array.isArray(m.supported_durations) && m.supported_durations.length) {
+          const ds = m.supported_durations;
+          // Compact ranges like 4-15 if it's a contiguous run.
+          const sorted = [...ds].sort((a, b) => a - b);
+          const isRange = sorted.length > 2 && sorted.every((v, i) => i === 0 || v - sorted[i - 1] === 1);
+          parts.push(`durations: ${isRange ? `${sorted[0]}-${sorted[sorted.length - 1]}s` : sorted.join('/') + 's'}`);
+        }
+
+        if (Array.isArray(m.supported_aspect_ratios) && m.supported_aspect_ratios.length) {
+          parts.push(`aspect: ${m.supported_aspect_ratios.join(', ')}`);
+        }
+
+        // Elements-type caps (only show when at least one is non-zero)
+        const eImg = m.elements_max_images, eVid = m.elements_max_videos, eAud = m.elements_max_audio;
+        if ((eImg ?? 0) > 0 || (eVid ?? 0) > 0 || (eAud ?? 0) > 0) {
+          parts.push(`elements: ${eImg ?? 0} imgs / ${eVid ?? 0} vids / ${eAud ?? 0} audio`);
+        }
+
+        // Video-to-video / multi-input caps
+        const mImg = m.max_images, mVid = m.max_videos, mElm = m.max_elements;
+        if ((mImg ?? 0) > 0 || (mVid ?? 0) > 0 || (mElm ?? 0) > 0) {
+          parts.push(`refs: ${mImg ?? 0} imgs / ${mVid ?? 0} vids / ${mElm ?? 0} elms`);
+        }
+
+        if ((m.max_visual_dna ?? 0) > 0) parts.push(`max_dna: ${m.max_visual_dna}`);
+
+        // Sound (only show when sound costs more or is generated natively)
+        if (m.sound_generation_type === 'native') {
+          const mult = m.sound_credit_multiplier && m.sound_credit_multiplier !== 1
+            ? ` (${m.sound_credit_multiplier}×)`
+            : '';
+          parts.push(`sound: native${mult}${m.sound_enabled_by_default ? ' on-by-default' : ''}`);
+        }
+
+        if (m.max_audio_duration != null) parts.push(`audio_max: ${m.max_audio_duration}s`);
+
+        return parts.length ? `\n   ${parts.join(' | ')}` : '';
+      };
+
       const formatModel = m =>
-        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${m.summary}` : ''}`;
+        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${m.summary}` : ''}${formatSpecs(m)}`;
 
       const sections = [];
       if (withSummary.length > 0) {
@@ -57,6 +113,38 @@ function registerModelTools(server, client) {
       };
     }
   );
+
+  // ─── get_session_usage ─────────────────────────────────────
+  // Real, multiplier-adjusted credit spend tagged with the caller's
+  // X-Kolbo-Caller-Session-Id (set automatically by the parent process —
+  // no need to pass it). Use this to give the user an honest "you've spent
+  // X credits in this app session" instead of estimating from base credits.
+  server.tool(
+    'get_session_usage',
+    'Fetch real, multiplier-adjusted credit spend for the current Kolbo Code app session. Use when the user asks "how much did I spend?" or before/after a large bulk job so you can quote actual cost (not an estimate from base credits). Returns total + per-tool breakdown + per-model breakdown + a recent list. The caller-session-id is forwarded automatically by the MCP HTTP client.',
+    {},
+    async () => {
+      try {
+        const r = await client.get('/credit-usage/by-caller-session');
+        // The endpoint returns { message, data: { total, count, by_tool, by_model, recent[] } }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(r.data || r, null, 2)
+          }]
+        };
+      } catch (err) {
+        // 400 from the endpoint means no caller-session-id was forwarded —
+        // surface a clear hint instead of a generic API error.
+        const hint = err?.status === 400
+          ? 'No caller-session-id was forwarded. Ensure the parent process (Kolbo Code / desktop sidecar) sets KOLBO_CALLER_SESSION_ID in this MCP\'s env, or call again after at least one media generation has fired.'
+          : err?.message || 'Failed to fetch session usage';
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: hint }, null, 2) }]
+        };
+      }
+    }
+  );
 }
 
 module.exports = { registerModelTools };