@kolbo/mcp 1.35.1 → 1.37.0

package/README.md

@@ -230,11 +230,15 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_models` | Current model catalog with costs and capabilities |
 | `list_voices` | TTS voices (presets + cloned) |
 | `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
+| `list_cinematic_presets` | "Cinema mode" presets grouped by dimension (camera, lens, focal_length, aperture, angle, shot_type, color_palette, lighting) — pass ids via the `cinematic` arg on `generate_image` / `generate_image_edit`. Only when the user wants a specific cinematic look |
 | `list_projects` | List owned + shared projects (id, name, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
 | `move_session` | Move a session (generation, chat, transcription…) and ALL its media to another project |
 | `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): author project-scoped HTML documents, edit them, get public share links |
+| `generate_character_sheet` | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna for stronger character consistency |
 | `list_visual_dna_folders` / `create_visual_dna_folder` / `update_visual_dna_folder` / `delete_visual_dna_folder` / `move_visual_dna_to_folder` | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
+| `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents (reusable named personas; `description` is the system instruction) |
+| `get_creative_director_status` | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a `_timed_out` Director run) |
 | `list_sessions` | Enumerate sessions across all types, filterable by project and type |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes, read the synthesized living brief |
 | `create_moodboard` / `update_moodboard` / `delete_moodboard` | Build/edit moodboards from image URLs (AI style analysis → master prompt) |

package/package.json

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

package/skill/GENERATED.md

@@ -1,7 +1,7 @@
 # AUTO-GENERATED — do not edit
 
 This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@d3a54fb.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@82f9072.
 
 It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
 To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.7.0
+version: 0.7.1
 name: kolbo
 description: |
   Generate, edit, or analyze creative media via the Kolbo AI MCP server:
@@ -113,7 +113,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 |------|---------|
 | `list_models` / `list_voices` / `check_credits` / `get_generation_status` / `get_session_usage` | Discovery + status |
 | `upload_media` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md` |
-| `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA + character folders — see `workflows/visual-dna.md` |
+| `create_visual_dna` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
 | `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools. |
 | `list_projects` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls; `move_session` relocates a whole session + its media when work landed in the wrong project. NOT the same as `app_builder_list_projects`. See "Projects — Where Work Lands" below. |
@@ -264,6 +264,9 @@ Chat renders markdown natively. `![alt](url)` = inline image. `[label](url)` = l
 
 Avoid bare URL dumps and HTML `<table>` grids — canvas already provides a gallery.
 
+- **3D models (`generate_3d`)**: NEVER paste the raw GLB/FBX/OBJ/USDZ file URLs as a link list. The result renders as a card with a live 3D preview + Download buttons ("View in Canvas"). Just say the model is ready and describe it — the user grabs formats from the card.
+- **NEVER surface a raw provider domain** (e.g. `*.fal.media`, `replicate.delivery`) in chat or `.kolbo/production.md`. All Kolbo outputs are Kolbo-hosted; if you ever see a provider URL in a result, treat it as a bug — report it, don't echo it.
+
 **After `generate_creative_director` completes** — share results as individual URLs, one per scene. Do NOT create an HTML grid artifact.
 
 **Always** record every URL in `.kolbo/production.md` — see `references/workflows/production-log.md`.

package/skill/VERSION

@@ -1 +1 @@
-0.7.0
+0.7.1

package/skill/references/workflows/visual-dna.md

@@ -242,3 +242,10 @@ Tools: `list_visual_dna_folders`, `create_visual_dna_folder` (`name`, optional h
 - **Deleting a folder never deletes DNAs** — contents move back to root (`items_moved_to_root` in the response). Mention this instead of asking for confirmation on non-empty folders.
 - **Creating many characters for one production?** Create the folder FIRST, then `move_visual_dna_to_folder` each DNA right after `create_visual_dna` — don't leave a big cast unsorted at root.
 - To list a folder's contents: `list_visual_dnas` and filter by each profile's `folder_id` (there is no server-side folder filter).
+
+## Character sheet — offer it for character DNAs
+
+`generate_character_sheet` builds a multi-angle turnaround from reference image URLs — the strongest consistency booster for a character DNA. It CHARGES CREDITS, so:
+- When the user is about to create a **character** DNA, proactively OFFER it: "want me to generate a character sheet first? It makes the character far more consistent and costs a few credits." Run it only on a yes.
+- Flow: `generate_character_sheet {image_urls}` → show the sheet → `create_visual_dna {name, images, character_sheet_url: <url>}`.
+- For non-character DNAs (style/product/environment), skip it.

package/src/index.js

@@ -69,6 +69,7 @@ const { registerPresetTools } = require('./tools/presets');
 const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
+const { registerAgentTools } = require('./tools/agents');
 const { registerDocTools } = require('./tools/docs');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
@@ -115,7 +116,9 @@ function createServer(opts = {}) {
       '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `app_builder_list_projects` is a DIFFERENT tool that scopes App Builder coding sessions only — never use one where the other is meant.',
       '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
       '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
-      '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).'
+      '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
+      '6. DIRECTOR / BATCH JOBS: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal. Video batches can take many minutes. If the tool returns `_timed_out:true`, the batch is STILL RUNNING on the server — call `get_creative_director_status` with the returned generation_id and keep checking until state="completed" to collect all scene outputs. NEVER conclude a Director run failed and fall back to plain generate_image/generate_video without first checking status — doing so wastes the user\'s credits by paying twice. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
+      '7. SESSION CONTINUITY: keep one workflow in ONE session. chat_send_message and the generation tools return a `session_id` — for follow-ups, refinements, retries, or additional steps on the SAME task/theme, pass that same `session_id` back on the next call instead of starting fresh. Only OMIT session_id (start a new session) when the user genuinely switches to an unrelated task. Do not open a new conversation/session for every message of the same workflow — it fragments the user\'s history and loses context.'
     ].join('\n')
   });
 
@@ -135,6 +138,7 @@ function createServer(opts = {}) {
   registerAppBuilderTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);
   registerProjectTools(server, client, toolOptions);
+  registerAgentTools(server, client, toolOptions);
   registerDocTools(server, client, toolOptions);
   registerMusicLibraryTools(server, client, toolOptions);
   registerStockLibraryTools(server, client, toolOptions);

package/src/tools/agents.js

@@ -0,0 +1,78 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const { z } = require('zod');
+
+function registerAgentTools(server, client) {
+  // ─── list_agents ───────────────────────────────────────────
+  server.tool(
+    'list_agents',
+    'List the user\'s custom chat agents (personal + any global/org preset agents visible to them). A custom agent is a reusable, named persona for the chat tool — its `description` is the system instruction the model adopts. Use this to resolve an agent NAME the user mentioned into its id, or to show what agents exist. Returns id, name, description, emoji, is_global. Personal agents (is_global:false) are editable/deletable; global presets are not.',
+    { search: z.string().optional().describe('Optional case-insensitive name filter.') },
+    async ({ search }) => {
+      const qs = search ? `?search=${encodeURIComponent(search)}` : '';
+      const result = await client.get(`/v1/agents${qs}`);
+      return { content: [{ type: 'text', text: JSON.stringify({
+        agents: result.agents || [],
+        count: result.count || (result.agents || []).length
+      }, null, 2) }] };
+    }
+  );
+
+  // ─── create_agent ──────────────────────────────────────────
+  server.tool(
+    'create_agent',
+    'Create a reusable custom chat agent (a named persona for the chat tool). The `description` IS the agent\'s system instruction — write it as the persona + behavior you want ("You are a senior creative director. Turn any brief into a structured shot list…"). Use when the user wants a persistent, reusable assistant ("make me a creative-director agent", "set up a support-triage bot"). For a ONE-OFF persona on a single conversation, pass `system_prompt` to chat_send_message instead — no need to create an agent. Plan limits apply (server rejects when the custom-agent cap is reached).',
+    {
+      name: z.string().optional().describe('Agent name. If omitted, a name is generated from the description.'),
+      description: z.string().describe('The agent persona + instructions (max 2000 chars). This becomes the system prompt the model adopts in every conversation that uses the agent.'),
+      emoji: z.string().optional().describe('Optional emoji avatar (auto-picked if omitted).'),
+      thumbnail: z.string().optional().describe('Optional thumbnail image URL.')
+    },
+    async ({ name, description, emoji, thumbnail }) => {
+      const body = { description };
+      if (name !== undefined) body.name = name;
+      if (emoji !== undefined) body.emoji = emoji;
+      if (thumbnail !== undefined) body.thumbnail = thumbnail;
+      const result = await client.post('/v1/agents', body);
+      return { content: [{ type: 'text', text: JSON.stringify({ agent: result.agent, _hint: 'Reuse this agent by selecting it in the chat tool. Its description is the system instruction applied to every conversation using it.' }, null, 2) }] };
+    }
+  );
+
+  // ─── update_agent ──────────────────────────────────────────
+  server.tool(
+    'update_agent',
+    'Update a custom chat agent\'s name, description (persona/instructions), or emoji/thumbnail. Only personal agents you own can be edited — global preset agents are protected. Resolve the agent id with list_agents first.',
+    {
+      agent_id: z.string().describe('Agent id (from list_agents).'),
+      name: z.string().optional().describe('New name.'),
+      description: z.string().optional().describe('New persona/instructions (replaces the old description; max 2000 chars).'),
+      emoji: z.string().optional().describe('New emoji avatar.'),
+      thumbnail: z.string().optional().describe('New thumbnail image URL.')
+    },
+    async ({ agent_id, name, description, emoji, thumbnail }) => {
+      const body = {};
+      if (name !== undefined) body.name = name;
+      if (description !== undefined) body.description = description;
+      if (emoji !== undefined) body.emoji = emoji;
+      if (thumbnail !== undefined) body.thumbnail = thumbnail;
+      const result = await client.put(`/v1/agents/${encodeURIComponent(agent_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify({ agent: result.agent }, null, 2) }] };
+    }
+  );
+
+  // ─── delete_agent ──────────────────────────────────────────
+  server.tool(
+    'delete_agent',
+    'Delete a custom chat agent you own. Global preset agents cannot be deleted. This removes the agent config only — it does not touch any conversations that used it.',
+    { agent_id: z.string().describe('Agent id (from list_agents).') },
+    async ({ agent_id }) => {
+      const result = await client.delete(`/v1/agents/${encodeURIComponent(agent_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}
+
+module.exports = { registerAgentTools };

package/src/tools/generate.js

@@ -9,6 +9,34 @@ const { pollUntilDone } = require('../polling');
 const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId } = require('../apps');
 
+// ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
+// Kolbo's "Cinema mode": eight independent photographic dimensions, each an OPTIONAL
+// preset id fetched from list_cinematic_presets. Any dimension left unset = "Auto" (the
+// enhancer decides). Applies ONLY when the user explicitly wants a deliberate cinematic
+// look — omit the whole object for a normal generation. Ids are validated server-side
+// against their dimension (passing a lighting id in the camera slot is a 400). The
+// selected fragments are woven into the prompt before enhancement.
+// NOTE: dimensions are data-driven — always call list_cinematic_presets for the live set
+// and valid ids; the keys below mirror the current catalog (Genre was removed).
+const cinematicDim = (label) => z.string().nullable().optional()
+  .describe(`${label} preset id from list_cinematic_presets. Omit or null for Auto.`);
+const CINEMATIC_SCHEMA = z.object({
+  camera:        cinematicDim('Camera body/format (e.g. ARRI Alexa, 16mm film, smartphone)'),
+  lens:          cinematicDim('Lens character (e.g. anamorphic, vintage prime, macro)'),
+  focal_length:  cinematicDim('Focal length / field of view (e.g. 24mm wide, 85mm portrait)'),
+  aperture:      cinematicDim('Aperture / depth of field (e.g. f/1.4 shallow, f/8 deep)'),
+  angle:         cinematicDim('Camera angle (e.g. low angle, birds-eye, eye level)'),
+  shot_type:     cinematicDim('Shot type / framing (e.g. close-up, wide shot, full shot)'),
+  color_palette: cinematicDim('Color grade (e.g. teal & orange, technicolor, classic B&W)'),
+  lighting:      cinematicDim('Lighting technique (e.g. rim light, golden hour, low-key)'),
+}).optional().describe(
+  'Cinema mode — an optional deliberate photographic treatment. Pass preset ids obtained from ' +
+  'list_cinematic_presets (at most one per dimension). Only include a dimension the user actually ' +
+  'wants; every omitted/null dimension is Auto (the enhancer completes the look in the spirit of the ' +
+  'ones you set). Omit the whole object entirely for an ordinary, non-cinematic generation. Ids are ' +
+  'validated against their dimension server-side. Dimensions are data-driven — never hardcode ids.'
+);
+
 function registerGenerateTools(server, client, options = {}) {
   // Only enabled by hosts that explicitly opt in (the remote HTTP connector).
   // stdio hosts (Kolbo Code, Claude Desktop, Cursor) leave this false, so their
@@ -34,13 +62,14 @@ function registerGenerateTools(server, client, options = {}) {
       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 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.'),
+      cinematic: CINEMATIC_SCHEMA,
       project_id: projectIdField
     },
-    async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, project_id }) => {
+    async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, cinematic, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image', {
         prompt, model, aspect_ratio, enhance_prompt, num_images,
-        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, project_id
+        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, preset_id, cinematic, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -85,13 +114,14 @@ function registerGenerateTools(server, client, options = {}) {
       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.'),
+      cinematic: CINEMATIC_SCHEMA,
       project_id: projectIdField
     },
-    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, project_id }) => {
+    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, project_id }) => {
       model = await canonicalModelId(client, model); // 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, project_id
+        visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -151,11 +181,43 @@ function registerGenerateTools(server, client, options = {}) {
         enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
-        interval: (gen.poll_interval_hint || 5) * 1000,
-        timeout: 600000,
-        statusUrl: `/v1/generate/creative-director/${gen.generation_id}/status`
-      });
+      const cdStatusUrl = `/v1/generate/creative-director/${gen.generation_id}/status`;
+      // Video mode runs N scenes as parallel video generations, each of which
+      // can take several minutes — a whole batch routinely exceeds the 10-min
+      // image window. Give video batches 30 min (the server watchdog finalizes
+      // stuck batches around 15-30 min, so this aligns client + server).
+      const cdTimeout = workflow_type === 'video' ? 1800000 : 600000;
+
+      let result;
+      try {
+        result = await pollUntilDone(client, gen.generation_id, {
+          interval: (gen.poll_interval_hint || 5) * 1000,
+          timeout: cdTimeout,
+          statusUrl: cdStatusUrl
+        });
+      } catch (err) {
+        // On a client-side poll timeout the batch is almost always STILL
+        // running (or already finished) on the server. Don't lose the work:
+        // return whatever scenes have landed plus the exact re-check path,
+        // instead of throwing an opaque timeout at the agent.
+        if (err && err.timedOut) {
+          let partial = null;
+          try { partial = await client.get(cdStatusUrl); } catch (_) { /* ignore */ }
+          const doneScenes = (partial?.scenes || []).filter(s => s.status === 'completed').map(s => ({
+            scene_number: s.scene_number, title: s.title, image_urls: s.image_urls, video_urls: s.video_urls
+          }));
+          return { content: [{ type: 'text', text: JSON.stringify({
+            state: partial?.state || 'processing',
+            generation_id: gen.generation_id,
+            scenes: doneScenes,
+            total_scenes: partial?.scenes?.length || 0,
+            completed_scenes: doneScenes.length,
+            _timed_out: true,
+            _hint: `Still running after the poll window. Call get_creative_director_status with generation_id="${gen.generation_id}" to keep checking until state="completed" — do NOT re-run generate_creative_director.`
+          }, null, 2) }] };
+        }
+        throw err;
+      }
 
       const scenes = (result.scenes || [])
         .filter(s => s.status === 'completed')
@@ -187,6 +249,42 @@ function registerGenerateTools(server, client, options = {}) {
     }
   );
 
+  // ─── get_creative_director_status ──────────────────────────
+  // Creative Director uses a DEDICATED status route (per-scene state + all
+  // scene image/video URLs). The generic get_generation_status hits
+  // /v1/generate/:id/status and CANNOT read a CD batch — so a long or
+  // backgrounded CD run (especially parallel VIDEO scenes that exceed the
+  // blocking poll window) needs this tool to be re-checked until done.
+  server.tool(
+    'get_creative_director_status',
+    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Use this to resume checking a batch that was still running when generate_creative_director returned `_timed_out: true` — poll it until state="completed" to collect ALL parallel scene outputs at once. Do NOT use the generic get_generation_status for Creative Director ids; it points at the wrong endpoint.',
+    {
+      generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.')
+    },
+    async ({ generation_id }) => {
+      const status = await client.get(`/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`);
+      const scenes = (status.scenes || []).map(s => ({
+        scene_number: s.scene_number,
+        status: s.status,
+        title: s.title,
+        image_urls: s.image_urls || null,
+        video_urls: s.video_urls || null
+      }));
+      const completed = scenes.filter(s => s.status === 'completed').length;
+      return { content: [{ type: 'text', text: JSON.stringify({
+        state: status.state,
+        generation_id,
+        progress: status.progress,
+        scenes,
+        total_scenes: scenes.length,
+        completed_scenes: completed,
+        _hint: status.state === 'completed'
+          ? 'All scenes terminal. Every completed scene\'s image_urls/video_urls are final.'
+          : 'Still running — call get_creative_director_status again in a few seconds until state="completed".'
+      }, null, 2) }] };
+    }
+  );
+
   // ─── generate_video ────────────────────────────────────────
   // NOTE: text-to-video does NOT support Visual DNA — the textToVideoGeneration
   // controller in kolbo-api never reads visualDnaIds. For character-consistent
@@ -204,12 +302,13 @@ function registerGenerateTools(server, client, options = {}) {
       reference_images: z.array(z.string()).optional().describe('Array of image URLs used as visual references (style / composition / subject). **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       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.'),
+      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.'),
       project_id: projectIdField
     },
-    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, project_id }) => {
+    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/video', {
-        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, project_id
+        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -252,13 +351,14 @@ function registerGenerateTools(server, client, options = {}) {
       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'),
       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. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false` the model ignores DNA entirely.**'),
-      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.'),
+      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.'),
       project_id: projectIdField
     },
-    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, project_id }) => {
+    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, project_id }) => {
       model = await canonicalModelId(client, model); // 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, project_id
+        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, project_id
       });
 
       if (ui()) return uiGenerating({

package/src/tools/presets.js

@@ -50,6 +50,35 @@ function registerPresetTools(server, client, options = {}) {
       return { content: [{ type: 'text', text }] };
     }
   );
+
+  // ─── list_cinematic_presets ────────────────────────────────
+  server.tool(
+    'list_cinematic_presets',
+    'List Kolbo "Cinema mode" presets for image generation/editing — a deliberate photographic ' +
+    'treatment layered onto the prompt. Returns presets grouped by DIMENSION (data-driven from the ' +
+    'live catalog; today: camera, lens, focal_length, aperture, angle, shot_type, color_palette, ' +
+    'lighting). Each preset has id, name, description, thumbnail. ONLY call this when the user wants a ' +
+    'specific cinematic look; then pass the chosen ids via the `cinematic` arg of generate_image / ' +
+    'generate_image_edit — at most one id per dimension. "Auto" is the absence of a selection: omit a ' +
+    'dimension (or the whole `cinematic` object) to let the enhancer decide. For an ordinary generation ' +
+    'do not call this at all. Never hardcode ids — dimensions and presets change; always fetch here.',
+    {},
+    async () => {
+      const result = await client.get('/v1/cinematic-presets');
+      // The public route serves the raw grouped map ({ camera:[...], lens:[...] });
+      // the SDK envelope wraps it as { dimensions:{...} }. Accept either shape.
+      const dimensions = (result && result.dimensions) || result || {};
+      const text = JSON.stringify({
+        dimensions,
+        available_dimensions: Object.keys(dimensions),
+        _usage_hint: 'Include ONLY the dimensions the user actually wants; pass their ids as the ' +
+          '`cinematic` arg on generate_image / generate_image_edit, e.g. {"camera":"<id>","lighting":"<id>"}. ' +
+          'Every omitted/null dimension is Auto — the enhancer completes the look in the spirit of the ones ' +
+          'you set. Omit the whole object for a non-cinematic generation. Ids are validated per-dimension server-side.'
+      }, null, 2);
+      return { content: [{ type: 'text', text }] };
+    }
+  );
 }
 
 module.exports = { registerPresetTools };

package/src/tools/visual_dna.js

@@ -20,16 +20,17 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── create_visual_dna ─────────────────────────────────────
   server.tool(
     'create_visual_dna',
-    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each.',
+    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each. For CHARACTER DNAs, a multi-angle character sheet dramatically improves consistency — offer to generate one with `generate_character_sheet` first, then pass its URL as `character_sheet_url` here (see that tool).',
     {
       name: z.string().describe('Name of the Visual DNA profile. **Pick a short, lowercase, no-space single token** (e.g. `maya`, `tokyo_neon`, `brand_red`, `esther_model`) — never names with spaces (`Sarah Johnson` ❌). The user/LLM types this as `@<name>` inside generation prompts, and the @ parser stops at the first space, so `@Sarah Johnson` matches only `Sarah` and the binding silently drops. Multi-word concepts should use underscores or be a single token. Names are case-insensitive on lookup, but **reserved** values rejected on creation: `Image1`, `Image2`, …, `Video1`, …, `Audio1`, … (any-language characters allowed; max 100 chars).'),
       dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene", "environment". Default: "character"'),
       prompt_helper: z.string().optional().describe('Optional description/notes to guide DNA extraction'),
       images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4.'),
       video: z.string().optional().describe('Optional video source (URL or absolute local path)'),
-      audio: z.string().optional().describe('Optional audio source (URL or absolute local path)')
+      audio: z.string().optional().describe('Optional audio source (URL or absolute local path)'),
+      character_sheet_url: z.string().optional().describe('URL of a multi-angle character sheet (from `generate_character_sheet`) to set as the DNA\'s primary reference. Strongly recommended for character DNAs — it is the single biggest consistency booster. Omit for non-character DNAs or when the user declines.')
     },
-    async ({ name, dna_type, prompt_helper, images, video, audio }) => {
+    async ({ name, dna_type, prompt_helper, images, video, audio, character_sheet_url }) => {
       if (!name || !name.trim()) {
         throw new Error('name is required');
       }
@@ -53,6 +54,7 @@ function registerVisualDnaTools(server, client, options = {}) {
       form.append('name', name);
       if (dna_type) form.append('dnaType', dna_type);
       if (prompt_helper) form.append('promptHelper', prompt_helper);
+      if (character_sheet_url) form.append('characterSheetUrl', character_sheet_url);
 
       for (const f of imageFiles) {
         form.append('images', f.buffer, { filename: f.filename, contentType: f.contentType });
@@ -159,6 +161,28 @@ function registerVisualDnaTools(server, client, options = {}) {
     }
   );
 
+  // ─── generate_character_sheet ──────────────────────────────
+  server.tool(
+    'generate_character_sheet',
+    'Generate a multi-angle character sheet (turnaround) from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers. The sheet is the single strongest consistency booster for a character DNA. CHARGES CREDITS, so when the user is about to create a character DNA, OFFER this first ("want me to generate a character sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna`.',
+    {
+      image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the character (front/side/varied angles work best). Use generated-image URLs or upload_media output.')
+    },
+    async ({ image_urls }) => {
+      const result = await client.post('/v1/visual-dna/character-sheet', { image_urls });
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            character_sheet_url: result.character_sheet_url,
+            credits_used: result.credits_used,
+            _hint: 'Show the sheet to the user, then pass character_sheet_url to create_visual_dna as that DNA\'s reference.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
   // ─── Visual DNA folders (organize characters) ──────────────
   // Folders are user-scoped and flat. Only PERSONAL Visual DNAs can live in
   // folders — global/organization presets are rejected by the server.