@kolbo/mcp 1.88.3 → 1.89.0

package/src/toolAnnotations.js

@@ -8,8 +8,8 @@
  * or non-boolean entries whenever the registered tool surface changes.
  */
 
-const READ_ONLY = [
-  'list_fonts', 'get_font', 'get_font_upload_status',
+const READ_ONLY = [
+  'list_fonts', 'get_font', 'get_font_upload_status',
   'get_creative_director_status', 'get_generation_status', 'list_models',
   'check_credits', 'show_plans', 'get_session_usage', 'list_voices',
   'chat_list_conversations', 'chat_get_messages',
@@ -21,7 +21,7 @@ const READ_ONLY = [
   'list_projects', 'get_project', 'list_sessions', 'list_project_context', 'get_project_profile',
   'list_project_assets',
   'list_session_generations',
-  'list_agents', 'list_docs', 'get_doc',
+  'list_agents', 'list_skills', 'list_docs', 'get_doc',
   'get_review_storage_usage', 'list_review_assets', 'get_review_asset',
   'list_review_collections', 'list_review_comments', 'list_review_share_links',
   'search_music_library', 'analyze_script_for_music', 'browse_music_library',
@@ -36,8 +36,9 @@ const OPEN_WORLD_READ_ONLY = [
   'blender_get_command_status',
 ];
 
-const PRIVATE_WRITE = [
-  'upload_font', 'rename_font', 'create_font_upload_ticket', 'font_upload_widget',
+const PRIVATE_WRITE = [
+  'upload_font', 'rename_font', 'create_font_upload_ticket', 'font_upload_widget',
+  'create_video_editor_session',
   'media_upload_widget', 'create_upload_ticket', 'upload_media',
   'favorite_media', 'unfavorite_media',
   'create_media_folder', 'update_media_folder',
@@ -56,7 +57,7 @@ const PRIVATE_WRITE = [
   'create_project', 'duplicate_project', 'update_project',
   'archive_project', 'unarchive_project', 'add_project_context',
   'link_project_asset', 'unlink_project_asset',
-  'create_agent',
+  'create_agent', 'create_skill',
   'create_doc',
   'create_review_asset', 'update_review_asset', 'add_review_version',
   'set_review_status', 'create_review_collection', 'update_review_collection',
@@ -65,8 +66,9 @@ const PRIVATE_WRITE = [
   'import_stock_asset',
 ];
 
-const DESTRUCTIVE_WRITE = [
-  'delete_font',
+const DESTRUCTIVE_WRITE = [
+  'delete_font',
+  'export_video_editor_session',
   // These actions spend credits, enqueue irreversible work, or cancel it.
   'generate_image', 'generate_image_edit', 'generate_creative_director',
   'generate_video', 'generate_video_from_image', 'generate_music',
@@ -89,7 +91,7 @@ const DESTRUCTIVE_WRITE = [
   'delete_session',
   'delete_project_context', 'regenerate_project_profile',
   'update_project_asset',
-  'update_agent', 'delete_agent', 'update_doc', 'delete_doc',
+  'update_agent', 'delete_agent', 'update_skill', 'delete_skill', 'update_doc', 'delete_doc',
   'delete_review_asset', 'delete_review_collection',
   'edit_review_comment', 'delete_review_comment',
 ];

package/src/tools/_shared.js

@@ -990,7 +990,11 @@ async function uiCompleted(p, textPayload, extraContent) {
     // `settings` wiped the resolution / aspect / DNA chips off the finished
     // card. Every reader already does `sc.settings || {}`.
     ...(settings ? { settings } : {}),
-    visual_dnas: await resolveVisualDnas(p.client, (settings || {}).visual_dna_ids),
+    ...(Array.isArray(p.visual_dnas)
+      ? { visual_dnas: p.visual_dnas }
+      : Array.isArray(settings?.visual_dna_ids)
+        ? { visual_dnas: await resolveVisualDnas(p.client, settings.visual_dna_ids) }
+        : {}),
     moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
     ...mediaRefs(p),
     urls: preferOwnedUrls(p.urls),
@@ -1058,11 +1062,12 @@ const MAX_TEXT_CHARS = 20000;
  * @param {object}   opts
  * @param {string[]} opts.fields  keys to keep per row, in order (others dropped)
  * @param {number}   [opts.cap]   max rows to include (default 50)
- * @param {number}   [opts.total] true total, so the model knows more exist
+ * @param {number}   [opts.total] true total, so the model knows more exist
+ * @param {number}   [opts.maxChars] text budget; Infinity for bounded server pages that must remain complete
  * @param {object}   [opts.extra] extra top-level keys to merge in
  * @param {string}   [opts.note]  guidance on how to fetch the rest
  */
-function compactList(items, { fields, cap = 50, total, extra, note } = {}) {
+function compactList(items, { fields, cap = 50, total, extra, note, maxChars = MAX_TEXT_CHARS } = {}) {
   const rows = Array.isArray(items) ? items : [];
   const kept = rows.slice(0, cap).map((row) => {
     if (!row || typeof row !== 'object') return row;
@@ -1085,11 +1090,11 @@ function compactList(items, { fields, cap = 50, total, extra, note } = {}) {
   }
 
   let text = JSON.stringify(payload);
-  if (text.length > MAX_TEXT_CHARS) {
+  if (text.length > maxChars) {
     // Still too big even trimmed (very long descriptions). Halve until it fits
     // rather than returning something the host will truncate at a random byte.
     let n = kept.length;
-    while (n > 1 && text.length > MAX_TEXT_CHARS) {
+    while (n > 1 && text.length > maxChars) {
       n = Math.floor(n / 2);
       payload.items = kept.slice(0, n);
       payload.count = n;

package/src/tools/agents.js

@@ -6,15 +6,39 @@
 const { z } = require('zod');
 const { listResult } = require('../apps');
 
+/**
+ * Skills rename (2026-09-09). The product surface is called Skills; the original tools
+ * were called *_agent. Because a published tool name can never be withdrawn (commandment
+ * above), every tool is registered TWICE from one definition:
+ *
+ *   list_skill s/create_skill/update_skill/delete_skill  — current vocabulary
+ *   list_agents/create_agent/update_agent/delete_agent   — original, still supported
+ *
+ * Same handler, same behaviour. Only the tool name, the id ARG name (`skill_id` vs the
+ * original `agent_id`) and the prose differ — the legacy arg name must keep working
+ * exactly as published, so it is not renamed, only shadowed by the new one.
+ *
+ * The server route is `/v1/skills`, which the backend also serves at `/v1/agents`.
+ */
 function registerAgentTools(server, client) {
-  // ─── list_agents ───────────────────────────────────────────
+  registerSkillCrud(server, client, { noun: 'skill', idArg: 'skill_id', suffix: 'skill', plural: 'skills' });
+  registerSkillCrud(server, client, { noun: 'agent', idArg: 'agent_id', suffix: 'agent', plural: 'agents' });
+}
+
+function registerSkillCrud(server, client, { noun, idArg, suffix, plural }) {
+  const legacyNote = noun === 'agent'
+    ? ' NOTE: "agent" is the original name for this feature; the product now calls them Skills. New integrations should prefer list_skills/create_skill/update_skill/delete_skill — these keep working unchanged.'
+    : '';
+  const idDesc = `${noun[0].toUpperCase() + noun.slice(1)} id (from list_${plural}).`;
+
+  // ─── list_skills / 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.',
+    `list_${plural}`,
+    `List the user's custom ${plural} (personal + any platform/org preset ${plural} visible to them). A ${noun} is a reusable, named persona for the chat tool — its \`description\` is the system instruction the model adopts. Use this to resolve a ${noun} NAME the user mentioned into its id, or to show what ${plural} exist. Returns id, name, description, emoji, is_global. Personal ${plural} (is_global:false) are editable/deletable; platform presets are not.${legacyNote}`,
     { 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}`);
+      const result = await client.get(`/v1/skills${qs}`);
       const agents = result.agents || [];
       const text = JSON.stringify({
         agents,
@@ -23,26 +47,26 @@ function registerAgentTools(server, client) {
 
       return listResult(text, {
         widget: 'list',
-        title: 'Your Agents',
+        title: noun === 'skill' ? 'Your Skills' : 'Your Agents',
         items: agents.map(a => ({
           id: a.id,
           title: (a.emoji ? a.emoji + ' ' : '') + a.name,
           subtitle: a.description,
           badge: a.is_global ? 'preset' : null,
-          use_hint: 'Use my "{TITLE}" agent (agent_id: {ID}) for this conversation.'
+          use_hint: `Use my "{TITLE}" ${noun} (${idArg}: {ID}) for this conversation.`
         })),
         total: agents.length
       });
     }
   );
 
-  // ─── create_agent ──────────────────────────────────────────
+  // ─── create_skill / 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).',
+    `create_${suffix}`,
+    `Create a reusable custom ${noun} (a named persona for the chat tool). The \`description\` IS the ${noun}'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 ${noun}", "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 a ${noun}. Plan limits apply (server rejects when the ${noun} cap is reached).${legacyNote}`,
     {
-      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.'),
+      name: z.string().optional().describe(`${noun[0].toUpperCase() + noun.slice(1)} name. If omitted, a name is generated from the description.`),
+      description: z.string().describe(`The ${noun} persona + instructions (max 2000 chars). This becomes the system prompt the model adopts in every conversation that uses the ${noun}.`),
       emoji: z.string().optional().describe('Optional emoji avatar (auto-picked if omitted).'),
       thumbnail: z.string().optional().describe('Optional thumbnail image URL.')
     },
@@ -51,40 +75,42 @@ function registerAgentTools(server, client) {
       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) }] };
+      const result = await client.post('/v1/skills', body);
+      return { content: [{ type: 'text', text: JSON.stringify({ agent: result.agent, _hint: `Reuse this ${noun} by selecting it in the chat tool. Its description is the system instruction applied to every conversation using it.` }, null, 2) }] };
     }
   );
 
-  // ─── update_agent ──────────────────────────────────────────
+  // ─── update_skill / update_agent ───────────────────────────
   server.tool(
-    'update_agent',
-    'Edit a custom chat agent in place: name, description (persona/instructions), or emoji/thumbnail. NEVER delete and recreate an agent to change its persona — conversations already reference this agent_id. Only personal agents you own can be edited — global preset agents are protected. Resolve the agent id with list_agents first.',
+    `update_${suffix}`,
+    `Edit a custom ${noun} in place: name, description (persona/instructions), or emoji/thumbnail. NEVER delete and recreate a ${noun} to change its persona — conversations already reference this id. Only personal ${plural} you own can be edited — platform presets are protected. Resolve the id with list_${plural} first.${legacyNote}`,
     {
-      agent_id: z.string().describe('Agent id (from list_agents).'),
+      [idArg]: z.string().describe(idDesc),
       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 }) => {
+    async (args) => {
+      const id = args[idArg];
+      const { name, description, emoji, thumbnail } = args;
       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);
+      const result = await client.put(`/v1/skills/${encodeURIComponent(id)}`, body);
       return { content: [{ type: 'text', text: JSON.stringify({ agent: result.agent }, null, 2) }] };
     }
   );
 
-  // ─── delete_agent ──────────────────────────────────────────
+  // ─── delete_skill / 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)}`);
+    `delete_${suffix}`,
+    `Delete a custom ${noun} you own. Platform preset ${plural} cannot be deleted. This removes the ${noun} config only — it does not touch any conversations that used it.${legacyNote}`,
+    { [idArg]: z.string().describe(idDesc) },
+    async (args) => {
+      const result = await client.delete(`/v1/skills/${encodeURIComponent(args[idArg])}`);
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
   );

package/src/tools/chat.js

@@ -20,11 +20,12 @@ function registerChatTools(server, client) {
       web_search: z.boolean().optional().describe('Enable web search for this message. Default: false'),
       deep_think: z.boolean().optional().describe('Enable deep think (extended reasoning). Default: false'),
       thinking_level: z.string().optional().describe('Thinking effort ID from list_models type="text" thinkingLevels. The server uses the model catalog default when omitted or invalid. Separate from legacy deep_think; safeguards take precedence.'),
+      routing_mode: z.enum(['fast', 'balanced', 'smart']).optional().describe('Auto routing mode. Use fast, balanced, or smart when model is Auto; omitted uses the server default (balanced).'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
       media_urls: z.array(z.string()).optional().describe('Public URLs of images, videos, or audio files to analyze. The model auto-routes to a vision-capable model when media is present. For a local file, get a URL first via the LOCAL FILE route in this tool\'s description.'),
       project_id: projectIdField
     },
-    async ({ message, model, session_id, system_prompt, web_search, deep_think, thinking_level, enhance_prompt = false, media_urls, project_id }) => {
+    async ({ message, model, session_id, system_prompt, web_search, deep_think, thinking_level, routing_mode, enhance_prompt = false, media_urls, project_id }) => {
       // Every generate_* tool resolves its model this way; chat was the one
       // `model` arg that went straight to the API, which has no fuzzy matching.
       // So the display names list_models hands back ("Claude Fable 5") came
@@ -40,6 +41,7 @@ function registerChatTools(server, client) {
         web_search,
         deep_think,
         ...(thinking_level !== undefined ? { thinking_level } : {}),
+        ...(routing_mode !== undefined ? { routing_mode } : {}),
         enhance_prompt,
         media_urls,
         project_id

package/src/tools/editor.js

@@ -0,0 +1,22 @@
+'use strict';
+const { z } = require('zod');
+
+function registerEditorTools(server, client) {
+  server.tool('create_video_editor_session',
+    'Create an editable timeline from existing Kolbo-hosted images/video, audio layers and text. No new media generation. Requires project_id with edit access. Returns session_id and editor_url. Preserve the returned ID; creation is not a polling operation.',
+    {
+      project_id: z.string().min(1), name: z.string().min(1).max(120),
+      format: z.enum(['16:9', '9:16', '1:1', '4:5', '21:9']).optional(),
+      clips: z.array(z.object({ url: z.string().url(), name: z.string().optional(), duration_ms: z.number().finite().min(0).max(1800000).optional(), trim_start_ms: z.number().finite().min(0).max(1800000).optional(), trim_end_ms: z.number().finite().min(0).max(1800000).optional(), volume: z.number().finite().min(0).max(2).optional(), muted: z.boolean().optional() })).min(1).max(60),
+      audio: z.array(z.object({ url: z.string().url(), name: z.string().optional(), start_ms: z.number().finite().min(0).max(1800000).optional(), duration_ms: z.number().finite().min(0).max(1800000).optional(), volume: z.number().finite().min(0).max(2).optional(), fade_in_ms: z.number().finite().min(0).max(1800000).optional(), fade_out_ms: z.number().finite().min(0).max(1800000).optional() })).max(16).optional(),
+      texts: z.array(z.object({ content: z.string().min(1).max(2000), start_ms: z.number().finite().min(0).max(1800000).optional(), duration_ms: z.number().finite().min(0).max(1800000).optional(), font_size: z.number().finite().min(8).max(512).optional(), color: z.string().optional(), vertical: z.enum(['top', 'middle', 'bottom']).optional() })).max(120).optional(),
+    },
+    async args => ({ content: [{ type: 'text', text: JSON.stringify(await client.post('/v1/editor/sessions', args)) }] })
+  );
+  server.tool('export_video_editor_session',
+    'Export an owned Video Editor timeline to MP4. Identical snapshots reuse the same job. If pending, call again with the returned job_id; do not recreate the timeline. retry_failed explicitly retries a terminal failed/cancelled snapshot and cannot be combined with job_id. This exports media to the library, not a public website.',
+    { session_id: z.string().min(1), quality: z.enum(['480p', '720p', '1080p']).optional(), job_id: z.string().min(1).max(100).optional(), retry_failed: z.boolean().optional() },
+    async args => ({ content: [{ type: 'text', text: JSON.stringify(await client.post('/v1/editor/exports', args)) }] })
+  );
+}
+module.exports = { registerEditorTools };

package/src/tools/generate.js

@@ -182,6 +182,8 @@ const imageSettings = (a = {}) => ({
   resolution: a.resolution,
   aspect_ratio: a.aspect_ratio,
   quality: a.quality,
+  background: a.background,
+  output_format: a.output_format,
   ...refSettings(a),
 });
 
@@ -269,20 +271,25 @@ function registerGenerateTools(server, client, options = {}) {
       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 resolution_multipliers on the same model to predict credit cost. Omit to use the model default.'),
-      quality: z.string().optional().describe('Quality tier for models that support it (e.g. "low", "medium", "high", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
+      quality: z.string().optional().describe('Quality tier for models that support it (e.g. "low", "medium", "high", "xhigh", "max", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
+      background: z.enum(['auto', 'opaque', 'transparent']).optional().describe('Output background. Before passing "transparent", call list_models for the chosen image model and require supports_transparent_background=true. Use PNG or WebP (PNG is selected by default when omitted). Kolbo forwards the setting and appends the exact phrase "no background" once to the effective prompt; prompt wording alone is not sufficient.'),
+      output_format: z.enum(['png', 'jpeg', 'webp']).optional().describe('Output file format on supported OpenAI image models. Default: png.'),
+      output_compression: z.number().int().min(0).max(100).optional().describe('JPEG/WebP output compression quality (0-100); not applicable to PNG.'),
+      moderation: z.enum(['auto', 'low']).optional().describe('Moderation setting on supported OpenAI image models. Default: auto.'),
+      mask_image_url: z.string().url().optional().describe('Optional public PNG mask URL for supported OpenAI edits with source/reference images. Transparent regions indicate areas to edit.'),
       preset_id: z.string().optional().describe('Exact preset ID from list_presets type="image". If the user requests any image preset, resolve it with list_presets and pass it here; do not omit it.'),
       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,
       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, session_id, font_ids }) => {
+    async ({ prompt, prompts, model, aspect_ratio, enhance_prompt = false, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, background, output_format, output_compression, moderation, mask_image_url, preset_id, cinematic, skip_color_palette, project_id, session_id, font_ids }) => {
       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")
       aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, 'text_to_img');
       const shared = {
         model, aspect_ratio, enhance_prompt, font_ids,
-        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id
+        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, background, output_format, output_compression, moderation, mask_image_url, preset_id, cinematic, skip_color_palette, project_id, session_id
       };
 
       // Batch mode: N different prompts, one widget owning all generation ids.
@@ -355,20 +362,25 @@ 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.'),
-      quality: z.string().optional().describe('Quality tier for edit models that support it (e.g. "low", "medium", "high", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
+      quality: z.string().optional().describe('Quality tier for edit models that support it (e.g. "low", "medium", "high", "xhigh", "max", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
+      background: z.enum(['auto', 'opaque', 'transparent']).optional().describe('Output background. Before passing "transparent", call list_models for the chosen image-edit model and require supports_transparent_background=true. Use PNG or WebP (PNG is selected by default when omitted). Kolbo forwards the setting and appends the exact phrase "no background" once to the effective prompt; prompt wording alone is not sufficient.'),
+      output_format: z.enum(['png', 'jpeg', 'webp']).optional().describe('Output file format on supported OpenAI image models. Default: png.'),
+      output_compression: z.number().int().min(0).max(100).optional().describe('JPEG/WebP output compression quality (0-100); not applicable to PNG.'),
+      moderation: z.enum(['auto', 'low']).optional().describe('Moderation setting on supported OpenAI image models. Default: auto.'),
+      mask_image_url: z.string().url().optional().describe('Optional public PNG mask URL for supported OpenAI edits with source/reference images. Transparent regions indicate areas to edit.'),
       preset_id: z.string().optional().describe('Exact preset ID from list_presets type="image_edit" to apply an image-editing preset. If the user requests a preset, resolve and pass it; do not silently omit it.'),
       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,
       session_id: sessionIdField
     },
-    async ({ prompt, prompts, model, source_images, reference_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id, font_ids }) => {
+    async ({ prompt, prompts, model, source_images, reference_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, background, output_format, output_compression, moderation, mask_image_url, preset_id, cinematic, skip_color_palette, project_id, session_id, font_ids }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
       model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
       aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, 'image_editing');
       const shared = {
         model, source_images, reference_images, aspect_ratio, enhance_prompt, font_ids,
-        visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id, session_id
+        visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, background, output_format, output_compression, moderation, mask_image_url, preset_id, cinematic, skip_color_palette, project_id, session_id
       };
       const settings = imageSettings(shared);
 

package/src/tools/media.js

@@ -9,10 +9,8 @@ const { resolveToBuffer, DEFAULT_MAX_FILE_MB, compactList } = require('./_shared
 const { ownedUrl } = require('./owned-url');
 const { UI, uiResult, listResult } = require('../apps');
 
-// How many tiles the media grid renders. A rendering limit only — the text
-// payload always carries the full page, and `total` reports the real library
-// count, so a capped grid can never be mistaken for "that's everything".
-const GRID_CAP = 24;
+// Server pagination bounds the page. Never slice it again: both text readers
+// and the widget advance by the server's page size and would skip hidden rows.
 
 async function mintUploadTicket(client) {
   const ticket = await client.post('/v1/media/upload-ticket', {});
@@ -272,7 +270,8 @@ function registerMediaTools(server, client, options = {}) {
       // locates an item; get_media returns one in full.
       const text = compactList(media, {
         fields: ['id', 'filename', 'media_type', 'url', 'thumbnail_url', 'size', 'project_id', 'created_at'],
-        cap: 50,
+        cap: media.length,
+        maxChars: Infinity,
         total: pagination ? (pagination.total_items != null ? pagination.total_items : pagination.total) : media.length,
         extra: pagination ? { pagination } : undefined,
         note: 'Narrow with `type`, `category`, `project_id`, `folder_id`, or `search`; get_media returns one item in full.',
@@ -289,7 +288,7 @@ function registerMediaTools(server, client, options = {}) {
       const totalItems = pagination
         ? (pagination.total_items != null ? pagination.total_items : pagination.total)
         : null;
-      const items = media.slice(0, GRID_CAP).map((m) => ({
+      const items = media.map((m) => ({
         id: m.id,
         title: m.filename,
         subtitle: m.media_type + (m.size ? ' · ' + Math.round(m.size / 1024) + 'KB' : ''),
@@ -302,8 +301,9 @@ function registerMediaTools(server, client, options = {}) {
         widget: 'media-grid',
         title: 'Media Library',
         items,
-        total: totalItems != null ? totalItems : media.length,
-        shown: Math.min(media.length, GRID_CAP),
+        total: totalItems != null && totalItems >= 0 ? totalItems : null,
+        ...(typeof pagination?.has_next === 'boolean' ? { has_next: pagination.has_next } : {}),
+        shown: media.length,
         // Everything "Load more" needs to fetch page N+1 ITSELF. The button used
         // to send a chat message asking the model to run the next page, on the
         // belief that a widget cannot invoke a tool — it can
@@ -311,8 +311,8 @@ function registerMediaTools(server, client, options = {}) {
         // with). Worse, the payload carried no page and no filters, so the model
         // could not reconstruct the query either and typically re-ran page 1.
         page_tool: 'list_media',
-        page: page || 1,
-        page_size: page_size || 50,
+        page: pagination?.page || page || 1,
+        page_size: pagination?.page_size || page_size || 50,
         query: { project_id, folder_id, type, category, source_type, sort, search }
       });
     }

package/src/tools/models.js

@@ -49,7 +49,9 @@ function modelChips(m) {
     const ds = [...m.supported_durations].sort((a, b) => a - b);
     chips.push(ds.length > 1 ? `${ds[0]}-${ds[ds.length - 1]}s` : `${ds[0]}s`);
   }
-  if (m.supports_visual_dna) chips.push('DNA');
+  if (m.supports_custom_fonts) chips.unshift('Fonts');
+  if (m.supports_transparent_background) chips.unshift('No BG');
+  if (m.supports_visual_dna) chips.push('DNA');
   if (m.new_model || m.newModel) chips.push('NEW');
   return chips.slice(0, 3);
 }
@@ -101,7 +103,9 @@ function buildCatalogStructured(models, type, compact) {
 
 // One row per model — every identifier, nothing else. ~90 bytes/model, so the
 // whole 400+ model catalog fits in a payload an agent can actually read.
-const identifierRow = (m) => ({
+const identifierRow = (m) => ({
+  supports_custom_fonts: m.supports_custom_fonts === true,
+  supports_transparent_background: m.supports_transparent_background === true,
   identifier: m.identifier,
   name: m.name,
   types: m.types,
@@ -190,8 +194,9 @@ function registerModelTools(server, client, options = {}) {
       // "this model rejects DNA" (cap = 0) from "I don't know" (field
       // missing). Now an explicit `max_dna: 0 (DNA not supported)` says the
       // model says no, and absence means the API doesn't expose the field.
-      const formatSpecs = m => {
-        const parts = [];
+      const formatSpecs = m => {
+        const parts = [];
+        parts.push('supports_custom_fonts: ' + (m.supports_custom_fonts === true));
         if (m.haveThinking && Array.isArray(m.thinkingLevels) && m.thinkingLevels.length) {
           parts.push(`thinking_level: ${m.thinkingLevels.map(level => level.id).join('/')} (default ${m.thinkingDefault})`);
         }
@@ -205,7 +210,8 @@ function registerModelTools(server, client, options = {}) {
         const isLipsyncVideo = types.includes('lipsync-video');
         const isLipsyncImage = types.includes('lipsync-image');
         const isImageEdit = types.includes('image_editing');
-        const isImage = types.includes('text_to_img') || isImageEdit;
+        const isImage = types.includes('text_to_img') || isImageEdit;
+        if (isImage) parts.push('supports_transparent_background: ' + (m.supports_transparent_background === true));
 
         if (Array.isArray(m.supported_resolutions) && m.supported_resolutions.length) {
           const mult = m.resolution_multipliers || {};

package/src/tools/visual_dna.js

@@ -177,7 +177,7 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── get_visual_dna ────────────────────────────────────────
   server.tool(
     'get_visual_dna',
-    'Fetch a single Visual DNA profile by ID. Returns the full profile including system_prompt and all reference images. To fetch a teammate\'s Visual DNA that lives in a shared project, pass project_id (you need edit+ on it).',
+    'Fetch a single Visual DNA profile by ID. Returns the full stored description, character attributes, and all reference images. Internal extraction system prompts are not exposed. To fetch a teammate\'s Visual DNA that lives in a shared project, pass project_id (you need edit+ on it).',
     {
       visual_dna_id: z.string().describe('The Visual DNA profile ID'),
       project_id: projectScopeReadField