@kolbo/mcp 1.69.0 → 1.70.1

package/README.md

@@ -236,7 +236,12 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_presets` | Generation presets across image/image-edit/video/music/text-to-video catalogs. Pass the selected exact id as `preset_id`; never claim a preset was applied without it. |
 | `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 |
+| `move_session` | Move ONE session (generation, chat, transcription…) and ALL its generations + media to another project |
+| `bulk_move_sessions` | Move up to 100 sessions into one project in a single call — mixed types allowed, per-session failures reported |
+| `list_session_generations` | A session's generations as complete groups (prompt + all its outputs) — the ids the two organize tools below take |
+| `move_generations_to_session` | Move selected generations (and only THEIR output media) into another existing session |
+| `split_session` | Carve selected generations out into a brand-new named session, atomically |
+| `undo_session_organization` | Reverse a move/split within 15 minutes, using the `operation_id` it returned |
 | `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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.69.0",
+  "version": "1.70.1",
   "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@8a08c7e.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@3a7950b.
 
 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

@@ -65,6 +65,7 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | If the user wants to… | Read first |
 |---|---|
 | Generate a **Seedance 2** video | `references/models/seedance.md` |
+| Generate a **Seedance 2.5** video | `references/models/seedance25.md` (also load `seedance.md` for the locked intro + craft layer) |
 | Generate a **GPT Image 2** image | `references/models/gpt-image.md` |
 | Generate a **Nano Banana / Gemini** image | `references/models/nano-banana.md` |
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
@@ -99,11 +100,11 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_video` | Text-to-video. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
-| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Supports `multi_shots` / `multi_shot_count` (badge/metadata/native flag only — never rewrites the prompt) and short `session_name`. Crafted demos: `enhance_prompt:false` + put shot structure in the prompt. |
+| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
 | `generate_lipsync` | Lipsync audio to an image or video face. |
 | `generate_music` | Music generation (Suno + variants). |
-| `generate_speech` | TTS. Use `list_voices` to pick a voice. Pass provider controls: Google/Gemini `style_instructions_preset_id` (warm/dramatic/whisper/excited/calm/cheerful/serious/storyteller/sad/intimate/british/commercial) or free-form `style_instructions` + `language` as Accent; DeepDub/MiniMax/Cartesia `selected_style`/`emotion`; `speaking_speed`; ElevenLabs `similarity_boost`/`style`; MiniMax `minimax_pitch`/`minimax_vol`/…. |
+| `generate_speech` | TTS. Use `list_voices` to pick a voice. |
 | `generate_sound` | Sound effects. |
 | `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. |
 
@@ -125,7 +126,6 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
 | `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
 | `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): YOU author full HTML documents (plans, briefs, scripts, research) saved into the user's project, editable in the Kolbo app. `share_doc` returns a public link. `update_doc` content replaces the WHOLE doc — `get_doc` first. |
-| `create_review_asset` / `list_review_assets` / `get_review_asset` / `update_review_asset` / `add_review_version` / `set_review_status` / `delete_review_asset` / `get_review_storage_usage` / review collection + comment + share-link tools | **Kolbo Review** (Frame.io-style): upload first via `upload_media` / ticket / widget → pass `media_id` to `create_review_asset`. Comments are text + optional timecodes. `create_review_share_link` returns a guest URL. |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 
@@ -166,6 +166,7 @@ A user-named tool — in any language — overrides every other rule. Recognized
    - User named one → use it. Model identifiers resolve leniently — shorthand like `"z-image"` or `"nano banana 2"` auto-resolves to the exact identifier, so don't over-engineer exact-id lookups (`list_models` is still authoritative for constraints, caps, and pricing).
    - Auto-select → only from "Auto-selectable" section (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
    - Never auto-select from "Named-only" section.
+   - **Photoreal photo edits** (object removal, keep one person / remove the crowd, inpainting, "edit this photo") → `generate_image_edit` with **Nano Banana 2** or **GPT Image 2** only. Do not auto-pick Flux 2 / Flux Klein — those are generate-from-scratch / style, named-only for editing.
 4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
 5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` instantly — the card updates on its own; you only need `get_generation_status` when a follow-up step needs the output URLs.
 6. **Checking status — NEVER poll in a loop**: `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.
@@ -177,10 +178,9 @@ Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`,
 
 Everything in Kolbo — sessions, generations, media, docs — lives inside a PROJECT. Getting this wrong is the #1 user complaint ("my work went to the wrong project").
 
-1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in the conversation. It is **per-call, NOT sticky** — any call that omits it silently lands in the default "API Generations" bucket (`is_default: true`).
+1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in the conversation. It is **per-call, NOT sticky** — any call that omits it silently lands in the default "API Generations" bucket (`is_default: true`). Accounts often hold hundreds of projects, so pass `list_projects({ search: "acme" })` rather than listing everything; the list is paginated (50/page) and hides archived projects unless you pass `include_archived: true`.
 2. **No project mentioned** → omit `project_id`; the default bucket is correct. Don't ask unless intent is ambiguous.
 3. **Work landed in the wrong project? MOVE it, never regenerate**: `move_session` relocates a whole session + all its media (works for any session type — the `session_id` from generation responses, chats, transcriptions); `move_media` / `bulk_move_media` / `move_folder_contents` relocate individual media items.
-4. **Inside the project, keep a related set in ONE session.** Every generation response returns a `session_id`. When a set needs several calls — shot 2, 3, 4 of a sequence, or more takes of the same idea — pass the FIRST call's `session_id` back on each follow-up. Without it every call opens its own session and the user's sidebar fills with near-identical single-item sessions. Prefer a real batch where one exists (`prompts` on `generate_image` / `generate_video`, `items` on `generate_video_from_image` — up to 8 `{image_url, prompt}` pairs animated in one call and one widget — `num_images`, `generate_creative_director`); use `session_id` for the tools that animate/edit one thing per call (`generate_elements`, `generate_first_last_frame`, `generate_lipsync`, `generate_video_from_video`, `edit_image`, `edit_video`), and across batches when a sequence runs longer than 8. Start a NEW session (omit it) when the next generation is unrelated.
 
 
 ## Cost Awareness — Quick Rules
@@ -228,7 +228,7 @@ You are NOT allowed to:
 
 Existing video → modify → **single `generate_video_from_video` call** with source video URL + edit prompt.
 
-**Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, `pika/pikadditions/video-to-video`, `pika/pikaswaps/video-to-video`, `pika/pikaffects/video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
+**Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
 
 **Motion-control / animate-move models invert the inputs**: `reference_images[0]` = the CHARACTER IMAGE to animate, `source_video` = the driving/reference video whose motion is transferred. Omitting the character image returns a `MOTION_CONTROL_INPUTS` error.
 

package/skill/references/models/gpt-image.md

@@ -6,7 +6,7 @@
 
 Load this file when the user wants a **GPT Image 2 / gpt-image-2** image (OpenAI). For other image models see `models/nano-banana.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
 
-**Kolbo MCP routing:** call `generate_image` (text-to-image) or `generate_image_edit` (edits with `source_images`). Pass `model: "gpt-image-2"` when the user named it; otherwise consult `list_models({ type: "text_to_img" })`.
+**Kolbo MCP routing:** call `generate_image` (text-to-image) or `generate_image_edit` (edits with `source_images`). Pass `model: "gpt-image-2"` when the user named it. For photoreal photo edits that need identity lock or readable on-image text, default to `gpt-image-2` via `generate_image_edit` — consult `list_models({ type: "image_editing" })`. Do not auto-pick Flux.
 
 ## CRITICAL Kolbo Platform Rules
 

package/skill/references/models/nano-banana.md

@@ -6,7 +6,7 @@
 
 Load this file when the user wants a **Nano Banana 2 (Gemini 3.1 Flash Image)** or **Nano Banana Pro (Gemini 3 Pro Image)** image. For other image models see `models/gpt-image.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
 
-**Kolbo MCP routing:** call `generate_image` or `generate_image_edit`. Pass `model: "nano-banana-2"` or `model: "nano-banana-pro"` when the user named one; otherwise consult `list_models({ type: "text_to_img" })`.
+**Kolbo MCP routing:** call `generate_image` or `generate_image_edit`. Pass `model: "nano-banana-2"` or `model: "nano-banana-pro"` when the user named one. For prompt-driven photoreal photo edits (object removal, keep subject / remove others), default to `nano-banana-2` via `generate_image_edit` — consult `list_models({ type: "image_editing" })`. Do not auto-pick Flux.
 
 ## CRITICAL Kolbo Platform Rules
 

package/skill/references/models/prompt-copilot.md

@@ -123,6 +123,7 @@ If during the conversation it becomes clear the user is actually working with on
 | User mentions / asks for | Switch to |
 |---|---|
 | Seedance / Seedance 2 / Bytedance video | `models/seedance.md` |
+| Seedance 2.5 | `models/seedance25.md` (also load `models/seedance.md`) |
 | GPT Image 2 / gpt-image-2 / OpenAI image | `models/gpt-image.md` |
 | Nano Banana / Gemini image / Gemini 3 Pro Image | `models/nano-banana.md` |
 | Veo / Veo 3 / Veo 3.1 / Google video | `models/veo.md` |

package/skill/references/models/seedance.md

@@ -9,15 +9,13 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 **Kolbo MCP routing:** Seedance is a video model — call `generate_video` (text-to-video) or `generate_elements` (when video references / Visual DNA / first-last frames are involved). Run `list_models({ type: "text_to_video" })` and pick a Seedance variant by name.
 
-**Multishot (Elements):** Seedance has **no** native provider Multishot switch. Pass `multi_shots: true` on `generate_elements` (optional `multi_shot_count`) for the UI Multishot badge only — it does **not** rewrite or reshape your prompt. **Always send `enhance_prompt: false` for crafted demos** (MCP default) so the prompt stays RAW. Put shot structure in the prompt yourself (`Multishot ON`, `Total: … / N shots`, numbered shots). Optional `session_name` sets a short sidebar title (skips AI auto-name from boilerplate).
-
 ## Universal Rules (apply to EVERY Seedance prompt)
 
 - **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too. For connected narrative sequences the proven phrasing is `N connected cinematic shots, 15 seconds total, 16:9, Multishot ON` — use it and keep `Multishot ON` for any multi-shot story.
-- **Order inside each shot**: Subject → Action → Camera → Style → Constraints → (Audio/SFX if relevant).
-- **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 8000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
-- **Character lock**: if a character recurs, open with `same character throughout all shots` to stop identity drift.
-- **Max 3 shots per single-shot prompt; max 6 shots in a multi-shot montage.** More causes drift.
+- **Then the Locked Intro** — `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` — before any shot. A one-liner `same character throughout` is not a character lock.
+- **Order inside each shot**: Subject → Action → Camera → Constraints → (Audio/SFX if relevant). Do NOT restack GLOBAL LOOK style inside the shot.
+- **Prompt length**: simple single-idea pieces ~120–280 words. Locked-intro cinematic typically 400–900 words. Shorter than ~120 words = random output. The 8000-char cap below always wins.
+- **Shot count is user-directed, not capped at 3 or 6.** If the user asks for N shots, deliver exactly N shots in one prompt unless they explicitly ask to split it.
 - **Always describe at least one camera movement per shot.**
 - **Tell Seedance what the camera is NOT doing** (e.g. `no cuts, no zoom, natural head movement`) — this is what locks POV.
 - **Final prompt is always English**, wrapped in a copy-ready code block. Detect intent in any language and reply in the user's language, but the prompt itself is English.
@@ -28,13 +26,42 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
   - **Never** split into multiple prompts, multiple code blocks, or "part 1 / part 2" to evade the cap.
   - Before outputting, internally count the characters of the final prompt as a single string. If > 8000, rewrite tighter and re-count. Repeat until ≤ 8000. Only then show the user.
 
+## Locked Intro (DEFAULT for any multi-shot cinematic)
+
+After the Total line, every multi-shot prompt — and any piece with recurring people or a recurring place — opens with three locked blocks. Same camera, same people, same world in every cut. Do not skip them. Do not restack this look as per-shot style.
+
+Skip only for: true single-shot POV/orb, 3×3 grid-panel mode, or video-edit tasks. UGC/phone pieces still use the three headers, but GLOBAL LOOK is phone-native (no "cinematic", no film-camera body).
+
+```
+Total: Xs / N shots / AR
+N connected cinematic shots, Xs total, AR, Multishot ON
+
+[GLOBAL LOOK – LOCKED, APPLIES TO EVERY SHOT]
+Arricam LT, Cooke S4/i primes, 35mm Kodak Vision3 500T, 1.85:1 spherical, T2.8. Shallow depth of field, halation on highlights, fine organic grain, lifted milky blacks, low contrast, no sharpening, no HDR. [Named] grade: [hero tone], [field colors], [shadows], [bloom]. Handheld with micro-drift, never locked off. Naturalistic performance, real dialogue sync, no music.
+
+[CAST – IDENTICAL IN EVERY SHOT]
+NAME: age, build, hair, face, wardrobe, skin, signature details. @Tag when a reference or DNA exists.
+PROP: recurring object.
+
+[LOCATION]
+Place in materials + light + color field. Blocking: who sits/stands where. Background LIFE (extras, ambient motion).
+
+SHOT 1 — 0:00–0:02 — Medium / camera position
+(director-dictated action — physical verbs, timed acting, quoted dialogue)
+Total: Xs / N shots / AR
+```
+
+Adapt the GLOBAL LOOK package to THIS world — never paste a beach grade onto a night interior. Equipment names (body / lens / stock / stop) live in GLOBAL LOOK only. Never name a real director.
+
+**Acting:** shot size → physical action → line → timing. `laughs obnoxiously for half a second, then flat and certain` — unbounded laughs eat 2s. Background LIFE on every wide/medium or the frame reads as a ghost town.
+
 ## The 5 Formats
 
 ### 1. Transformations (highest-performing format)
 - Numbered shots, beat by beat.
 - Escalation arc: **calm → threat → transformation → aftermath**.
 - 6 shots / 15s / 16:9 is the proven structure.
-- Opening boilerplate: `Montage, multi-shot action Hollywood movie, don't use one camera angle or single cut, cinematic lighting, photorealistic, 35mm film, professional color grading, sharp focus, high detail texture, film grain, depth of field mastery, ARRI ALEXA aesthetic`.
+- Prefer the **Locked Intro** over a style dump. For a quick action montage with no recurring cast, a short GLOBAL LOOK still beats the old ARRI-prefix pile.
 - **Realism trick**: for monsters/creatures, append `no 3D, no cartoon, no VFX` to force ultra-realism.
 - **Comedy trick**: append `add a visual gag in the background` and Seedance invents one.
 
@@ -54,7 +81,7 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 - Always supply: **clear location, clear power mismatch, defined escalation arc**.
 - Describe choreography beat by beat — Seedance executes what you write.
 - Single continuous shot 15s works for two-fighter scenes; describe camera moves between beats (`crests rooftop edge`, `full 360 orbit`, `pulls back to wide`, `descends with them`).
-- Use `Guy Ritchie speed-ramping with Snyder impact slow-motion` as the style anchor when comedic/stylized.
+- Use speed-ramping with impact slow-motion as the style anchor when comedic/stylized.
 
 ### 5. Animation (3D stylized)
 - Break the 15s into **timed segments** (`0–3s`, `3–6s`, `6–9s`, `9–12s`, `12–15s`) and describe each explicitly.
@@ -66,10 +93,7 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 Use whenever the user gives named characters or multiple reference images (`@Image1`, `@Image2`, …) — a tactical unit clearing a bunker, a duel between two referenced characters, a war scene. **This is always an Elements-mode prompt** (route the card to `elements`). Structure:
 
-1. **Labeled scene header FIRST** (grounds the scene before any shot):
-   - `Time of day:` — hour + light quality + atmosphere (dust, haze, heavy silence before action).
-   - `Location:` — the environment in concrete physical detail (materials, wear, light direction, high-contrast blown-out entrance, etc.).
-   - `Characters:` — ONE line per person: `Name @ImageN — wardrobe, position in frame, what they carry`. End with "All must match their character references exactly."
+1. **Locked Intro FIRST** (GLOBAL LOOK / CAST / LOCATION) — CAST is one line per person: `Name @ImageN — wardrobe, position in frame, what they carry`. End CAST with "All must match their character references exactly." LOCATION carries time-of-day + materials + light direction.
 2. **REFERENCE CONSISTENCY block** — map every reference and pin what must NOT change: `Reference Image 1 is <X>. Preserve exact face, hair, anatomy, wardrobe, colors, props.` Add per-character energy/aura color rules, and any already-established story state (e.g. "the gem is already shattered — no intact gem, no red glow"). End with "Do not redesign, morph, recolor, or swap either character, their clothing, anatomy, weapons, or the environment."
 3. **Shots** — either titled (`Shot 1 — Medium Wide / Tactical Positioning`) or timecoded (`SHOT 1 — 0:00–0:03`); timecodes must sum to the total duration. Under each shot use **Camera → Action → Audio** in that order.
 4. **Continuity** — to chain a series, open with `Begin as a seamless continuation from <the exact last beat of the previous video>.`
@@ -104,16 +128,9 @@ The model reacts to what can be **seen and measured**, not to mood words. Transl
 - ❌ "tense scene" → ✅ "man freezes, slowly clenches his fist, light only from the side, half his face in shadow"
 - ❌ "cool cinematic shot of a car, epic, fast" → ✅ "low tracking shot alongside the car as it powers through a wet curve, headlights glowing, spray off the tyres, hard buffeting camera shake"
 
-### Style — DISTRIBUTED, not a prefix
-
-Never pile all style tokens at the top of the prompt. Each aspect lives in the block that already governs it:
+### Style — LOCKED at the top, not redistributed
 
-- Lighting → inside the shot's LIGHTING description
-- Lens / FOV → in OPTICS
-- Color → either an explicit grade (when strong / stylized) or folded into LOCATION + LIGHTING for naturalistic looks
-- Skin / acting → in PERFORMANCE
-- Physics → in PHYSICS
-- Format / resolution / grain → at the END as a suffix stack (before LOCKS)
+The GLOBAL LOOK block is the prefix. Per-shot style is ONLY what changes (shot size, move, height, this-shot light). Do not re-state film stock / lens / grade per shot. Do not pile a second style dump at the end.
 
 ### Shot sizes
 
@@ -153,7 +170,7 @@ Use only the discrete steps. Not "23°" — use 18° or 29°.
 - **Emotion through muscle movement**, not labels. ❌ "she looks sad" → ✅ "her eyes drop to the table, jaw tightens, she swallows once before answering."
 - **WB in Kelvin.** 3200K / 4000K / 5600K / 8500K. Pick ONE for the scene's mood.
 - **Color as material + light + role**, never a flat list. ❌ "she wears red, he wears blue" → ✅ "crimson silk scarf catching the cold tungsten spill from the corridor".
-- **No equipment names**, no director references, no "shot on ARRI / Sigma 85mm / Roger Deakins".
+- **Equipment names live in GLOBAL LOOK only** (body, lens, stock, stop). Never inside shots. **Never name a real director** and never write "in the style of [person]".
 
 ### Cuts and timing
 
@@ -176,18 +193,19 @@ Use only the discrete steps. Not "23°" — use 18° or 29°.
 
 ### Camera placement
 
-Place CAMERA in the **3rd position** of each shot's core layers (Subject → Action → Camera → Style → Constraints). FOV gets ignored at the end, conflicts with identity at the front.
+Place CAMERA in the **3rd position** of each shot's core layers (Subject → Action → Camera → Constraints). FOV gets ignored at the end, conflicts with identity at the front. GLOBAL LOOK already owns lens / stock / grade.
 
 ### Pre-flight checklist (before output)
 
-- Distributed style (no top-pile)?
+- Locked Intro present (`[GLOBAL LOOK]`, `[CAST]`, `[LOCATION]`) unless a documented skip?
+- GLOBAL LOOK not restated inside shots? Equipment names only there? No director names?
+- Acting timed? Background LIFE on wides/mediums?
 - One camera movement per time slice?
 - FOV in degrees from the table (not mm, not arbitrary)?
 - WB in Kelvin?
 - Speed in km/h, atmosphere in % or meters?
-- Color via material + light + role?
+- Color via material + light + role (grade named as law in GLOBAL LOOK)?
 - Positive phrasing (no "does not X")?
-- No equipment / director names?
 - Emotion through muscle, not labels?
 - Multishot: FOV per segment + "no drift mid-segment"?
 - 8000-char cap honored?

package/skill/references/models/seedance25.md

@@ -0,0 +1,65 @@
+<!-- PARITY: this file mirrors getSeedance25PromptSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js.
+     Craft layer (formats, optics, grid mode) lives in models/seedance.md —
+     load that file too. Locked Intro is the same three blocks on both versions. -->
+
+# Seedance 2.5 — Prompt Rules
+
+Load this file when the user wants a **Seedance 2.5** video (they said "2.5" / "25", or they need longer than 15s, more than ~10 shots, or a large cast of references). Also load `models/seedance.md` for the shared craft layer.
+
+**Kolbo MCP routing:** `generate_video` or `generate_elements` (refs / Visual DNA / first-last). Run `list_models({ type: "text_to_video" })` and pick the Seedance 2.5 variant by name.
+
+## What's NEW in 2.5 (verified — never hedge)
+
+- **Duration 4–30 seconds**, whole seconds. 30s IS supported.
+- **Up to 30 shots/cuts in ONE generation.** Deliver exactly N if N ≤ 30.
+- **Prompt cap 10,000 characters** for the entire prompt as one string.
+- **Up to 50 reference medias / Visual DNA mentions** (`@Name`, `@ImageN`, `#Moodboard`). Every referenced asset must be tagged in the prompt text.
+- **Multimodal refs:** images + video clips + audio can all anchor one generation.
+
+## Locked Intro (DEFAULT — same shape as Seedance 2)
+
+After the Total line, every multi-shot cinematic opens with:
+
+```
+[GLOBAL LOOK – LOCKED, APPLIES TO EVERY SHOT]
+[CAST – IDENTICAL IN EVERY SHOT]
+[LOCATION]
+```
+
+then timecoded `SHOT N — 0:00–0:02 — Medium / camera position` beats. Full skeleton, acting rules, and optical craft: `models/seedance.md`.
+
+2.5 is where this format earns its keep: 15 shots timed to 30s, ~5k characters, one locked look so every cut matches camera / grade / cast. Do not skip the three blocks. Do not restack GLOBAL LOOK inside shots.
+
+UGC / phone vertical: NEVER write "cinematic". GLOBAL LOOK is phone-native. Use `N connected phone shots, Xs total, 9:16, Multishot ON` and restate `9:16 vertical phone frame` inside every shot.
+
+## Prompt length
+
+Simple ≤15s ~120–280 words. Locked-intro cinematic 15s typically 400–900 words. Full 30s / 15+ shots typically 700–1200 words / ~4k–9k chars. Hard cap 10,000. Never split into part 1 / part 2.
+
+## Feature-Block (optional, UNDER the Locked Intro)
+
+Reach for extra department passes only when the user wants "their best possible 30 seconds" AND the 10k budget still has room after GLOBAL LOOK / CAST / LOCATION. Never replace the Locked Intro.
+
+May add above GLOBAL LOOK: **EMOTIONAL INTENT** + **SIGNATURE MOMENT**.
+May add under the shot list: CAMERA timecode pass, SOUND timestamps, PHYSICS contract, EDITING/CONTINUITY, DIRECTORIAL NOTES.
+Skip CORE STYLE / SUBJECT / ENVIRONMENT — the three locked blocks already own those.
+
+## References (ByteDance 2.5)
+
+- Limits: up to 30 images (each ≤4K), up to 10 videos (≤30s combined), up to 10 audio clips (≤30s combined); up to 50 materials total.
+- Role mapping is mandatory, one line per material:
+  - `@Image N defines <subject>'s <appearance, clothing, structure, or material>.`
+  - `@Video N defines <motion, camera movement, or pacing>.`
+  - `@Audio N defines <character or sound type>'s <voice, dialogue, ambience, or music>.`
+- Add exclusions when a material's people/background could leak: "Do not use the image background." / "Do not use the people in the image."
+
+## Task-locked parameters
+
+- **Video editing:** aspect + duration auto-preserve the source. Do NOT declare AR / duration / shot-count headers. Use `[Edit Goal]` / `[Source Video Role]` / `[Target Material Role]` / `[Edit Scope]` / `[Content to Preserve]`.
+- **First-frame / first-and-last-frame:** AR comes from the FIRST image. Duration CAN be set.
+- **Video extension:** AR auto-preserves the input; duration CAN be set.
+
+## Where to run in Kolbo
+
+Same routing as Seedance 2 (`first_last_frame` / `elements` / `image_to_video` / `text_to_video`). Pair Visual DNA with `generate_elements` and tag `@<dna-name>` inside the prompt.

package/skill/references/workflows/marketing-studio.md

@@ -123,7 +123,7 @@ If the user gives a **product URL** instead of a photo, see `workflows/research-
 
 ## Multi-Slot Board Method (structured shot specs + character consistency)
 
-For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. Prefer `generate_elements` with `multi_shots: true` (and a short `session_name`) when animating a single multi-cut Seedance spot; board-first still uses `generate_image` + `generate_elements` / `generate_video_from_image` per slot when you need separate clips.
+For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. This is a prompt-only convention — no special MCP mode; it uses `generate_image` (board) + `generate_elements` / `generate_video_from_image` (per-slot animate) that already exist.
 
 ### 1. Structured input slots
 

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

@@ -42,7 +42,7 @@ client share a filesystem. Choose by transport:
 |---|---|
 | **Local (stdio) install** — `npx @kolbo/mcp` on the same machine | `upload_media` with the absolute path |
 | **Remote connector + you can run shell commands** (Claude Code, Codex, Cursor, CI) | `create_upload_ticket`, then POST each file to `upload_url` |
-| **Remote connector, no filesystem** (claude.ai web/mobile) | `media_upload_widget` — the user picks the file. On Claude iOS/Android the card opens a full-screen uploader (in-chat file pickers are dropped by WebKit); after upload the user pastes the copied CDN URLs back into chat. |
+| **Remote connector, no filesystem** (claude.ai web/mobile) | `media_upload_widget` — the user picks the file |
 
 `create_upload_ticket` returns `upload_url` + a short-lived `token`. Upload with
 multipart field `file` and `Authorization: Bearer <token>`; the stable CDN URL comes
@@ -50,20 +50,9 @@ back at `media.url`. One POST per file, ticket reusable for a batch. Then pass t
 URLs to any generation tool.
 
 ```bash
-curl -X POST "<upload_url>" -H "Authorization: Bearer <token>" -F "file=@/abs/path/clip.mp3;type=audio/mpeg"
+curl -X POST "<upload_url>" -H "Authorization: Bearer <token>" -F "file=@/abs/path/clip.mp3"
 ```
 
-**Declare the type.** `curl` labels the part from its own mime table and falls back to
-`application/octet-stream` for anything missing from it — `.mp3` included — which the
-endpoint can reject as an unsupported type. Append `;type=<mime>` (`audio/mpeg`,
-`audio/wav`, `video/mp4`, `image/png`, `application/pdf`, …) and it never comes up.
-
-**Pace a batch.** The upload endpoint is rate limited — the ticket response says by
-how much in `rate_limit` (currently 40 uploads per 60s). Firing 55 files back to
-back stalls at file 41. Sleep ~2s between files, or read the 429: it carries a
-`Retry-After` header and `retry_after_seconds` in the body. Wait exactly that long
-and continue — a 429 is a "not yet", not a failed upload, and nothing was charged.
-
 Do **not** fall back to `upload_media`'s `source_base64` for anything but a tiny file —
 it pushes the whole file through the model's context, twice. And do not reach for
 cloud credentials or a bucket of your own; the ticket is the sanctioned path.

package/src/apps/widgets/generation.js

@@ -16,7 +16,8 @@ const { widgetPage } = require('../html');
  *   model, model_icon, prompt, count,
  *   settings: { duration, resolution, aspect_ratio, quality, audio, voice, mode,
  *               enhance_prompt, web_search, visual_dna, moodboard, preset, cinematic },
- *   reference_image,                   // thumbnail URL (optional)
+ *   reference_images,                  // all reference thumbnail URLs (optional)
+ *   reference_image,                   // legacy single-thumbnail fallback
  *   urls, thumbnail_url, title, duration, credits_used,
  *   tracks: [{ title, duration, thumbnail_url, model }], // optional audio metadata by URL index
  *   scenes: [{ scene_number, title, image_urls, video_urls }],
@@ -135,7 +136,11 @@ function renderChips(sc) {
   }
   if (s.mode) h += chip(esc(s.mode));
   if (sc.count > 1) h += chip('×' + sc.count);
-  if (sc.reference_image) h += '<img class="k-ref-thumb" src="' + esc(sc.reference_image) + '" alt="" loading="lazy" title="Reference image" onerror="this.style.display=\\'none\\'">';
+  var refs = Array.isArray(sc.reference_images) && sc.reference_images.length
+    ? sc.reference_images : (sc.reference_image ? [sc.reference_image] : []);
+  for (var i = 0; i < refs.length; i++) {
+    h += '<img class="k-ref-thumb" src="' + esc(refs[i]) + '" alt="" loading="lazy" title="Reference image ' + (i + 1) + ' of ' + refs.length + '" onerror="this.style.display=\\'none\\'">';
+  }
   el('chips').innerHTML = h;
 }
 function chip(inner) { return '<span class="k-chip">' + inner + '</span>'; }

package/src/client.js

@@ -47,6 +47,26 @@ function isAbortError(err) {
   return err && (err.name === 'TimeoutError' || err.name === 'AbortError');
 }
 
+function composeSignals(signals) {
+  const active = signals.filter(Boolean);
+  if (active.length === 0) return { signal: undefined, cleanup: () => {} };
+  if (active.length === 1) return { signal: active[0], cleanup: () => {} };
+
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  for (const item of active) {
+    if (item.aborted) {
+      controller.abort();
+      break;
+    }
+    item.addEventListener('abort', onAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => active.forEach(item => item.removeEventListener('abort', onAbort))
+  };
+}
+
 // ---------------------------------------------------------------------------
 // 429 handling
 // ---------------------------------------------------------------------------
@@ -279,18 +299,18 @@ class KolboClient {
     return false;
   }
 
-  async request(method, reqPath, body = null) {
+  async request(method, reqPath, body = null, requestOptions = {}) {
     if (!this.apiKey) await this._ensureLogin();
-    const result = await this._doRequest(method, reqPath, body);
+    const result = await this._doRequest(method, reqPath, body, requestOptions);
 
     // On 401, try re-reading auth store and retry once
     if (result._status === 401 && this._tryRefreshKey()) {
-      return this._doRequest(method, reqPath, body);
+      return this._doRequest(method, reqPath, body, requestOptions);
     }
     return result;
   }
 
-  async _doRequest(method, reqPath, body = null) {
+  async _doRequest(method, reqPath, body = null, requestOptions = {}) {
     const url = `${this.baseUrl}${reqPath}`;
     const headers = {
       'X-API-Key': this.apiKey,
@@ -313,21 +333,32 @@ class KolboClient {
       options.body = JSON.stringify(body);
     }
 
-    options.signal = timeoutSignal(REQUEST_TIMEOUT_MS);
+    const callerSignal = requestOptions.ignoreCallerSignal ? null : progress.signal();
+    const requestTimeoutMs = requestOptions.timeoutMs || REQUEST_TIMEOUT_MS;
+    const composed = composeSignals([callerSignal, timeoutSignal(requestTimeoutMs)]);
+    options.signal = composed.signal;
 
     let response;
     try {
       response = await fetch(url, options);
     } catch (err) {
       if (isAbortError(err)) {
+        if (callerSignal?.aborted) {
+          throw new KolboApiError(
+            `Request cancelled by caller: ${method} ${reqPath}`,
+            { code: 'REQUEST_CANCELLED', status: 499 }
+          );
+        }
         throw new KolboApiError(
-          `Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${method} ${reqPath}. ` +
+          `Request timed out after ${requestTimeoutMs / 1000}s: ${method} ${reqPath}. ` +
           'The job may still be running server-side — poll get_generation_status before retrying. ' +
           'Raise KOLBO_HTTP_TIMEOUT_MS if this is a legitimately slow endpoint.',
           { code: 'REQUEST_TIMEOUT', status: 504 }
         );
       }
       throw err;
+    } finally {
+      composed.cleanup();
     }
 
     let data;
@@ -367,16 +398,37 @@ class KolboClient {
     const generationId = data?.generation_id || data?.generationId;
     if (method === 'POST' && generationId) {
       await progress.generation(generationId);
+      if (!requestOptions.suppressGenerationTracking) {
+        progress.trackGeneration(generationId, () => this._cancelAfterCallerAbort(generationId));
+      }
     }
     return data;
   }
 
-  async post(reqPath, body) {
-    return this.request('POST', reqPath, body);
+  async _cancelAfterCallerAbort(generationId) {
+    try {
+      await this._doRequest(
+        'POST',
+        `/v1/generate/${encodeURIComponent(generationId)}/cancel`,
+        {},
+        {
+          ignoreCallerSignal: true,
+          suppressGenerationTracking: true,
+          timeoutMs: 30000
+        }
+      );
+    } catch (_) {
+      // The host has already cancelled the visible tool call. This is a
+      // best-effort cleanup and must never become an unhandled rejection.
+    }
+  }
+
+  async post(reqPath, body, requestOptions) {
+    return this.request('POST', reqPath, body, requestOptions);
   }
 
-  async get(reqPath) {
-    return this.request('GET', reqPath);
+  async get(reqPath, requestOptions) {
+    return this.request('GET', reqPath, null, requestOptions);
   }
 
   async put(reqPath, body = null) {
@@ -426,16 +478,24 @@ class KolboClient {
     const body = formData.getBuffer();
     headers['Content-Length'] = String(body.length);
 
+    const callerSignal = progress.signal();
+    const composed = composeSignals([callerSignal, timeoutSignal(UPLOAD_TIMEOUT_MS)]);
     let response;
     try {
       response = await fetch(url, {
         method: 'POST',
         headers,
         body,
-        signal: timeoutSignal(UPLOAD_TIMEOUT_MS)
+        signal: composed.signal
       });
     } catch (err) {
       if (isAbortError(err)) {
+        if (callerSignal?.aborted) {
+          throw new KolboApiError(
+            `Upload cancelled by caller: POST ${reqPath}`,
+            { code: 'REQUEST_CANCELLED', status: 499 }
+          );
+        }
         throw new KolboApiError(
           `Upload timed out after ${UPLOAD_TIMEOUT_MS / 1000}s: POST ${reqPath} ` +
           `(${Math.round(body.length / 1024)}KB). Raise KOLBO_UPLOAD_TIMEOUT_MS for slow links.`,
@@ -443,6 +503,8 @@ class KolboClient {
         );
       }
       throw err;
+    } finally {
+      composed.cleanup();
     }
 
     let data;
@@ -476,6 +538,11 @@ class KolboClient {
       throw apiError;
     }
 
+    const generationId = data?.generation_id || data?.generationId;
+    if (generationId) {
+      await progress.generation(generationId);
+      progress.trackGeneration(generationId, () => this._cancelAfterCallerAbort(generationId));
+    }
     return data;
   }
 }

package/src/index.js

@@ -127,7 +127,7 @@ function createServer(opts = {}) {
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
       '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE. (A) User has a LOCAL file (audio, video, image, document) on their machine. What matters is WHERE THIS SERVER RUNS, not what your client can do — your own filesystem access is irrelevant if the server is somewhere else. On a LOCAL stdio install (server and client share a machine) → call `upload_media` with the absolute path, or pass the path straight to tools like `transcribe_audio` that accept local paths. Over a REMOTE connector the server cannot see that path no matter how capable you are, so a local path will always fail: if you can run shell commands or issue HTTP requests → call `create_upload_ticket` and POST the file to the returned upload_url yourself (fastest, no user interaction); if you cannot → call `media_upload_widget` IMMEDIATELY, the user uploads, and a `media.kolbo.ai` CDN URL comes back for any follow-up call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly; all Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 anything but a tiny file — it costs context in proportion to file size; use the ticket or the widget instead.',
       '9. MODEL SELECTION — ROUTE BY THE STRENGTHS SUMMARY, NEVER BY THE BADGE OR THE PRICE TAG: ALWAYS pass a specific `model` on every generation tool — do NOT omit it (omitting falls back to "Smart Select" auto-routing, which hides the choice from the user; use it ONLY if the user explicitly asks you to auto-pick). To choose: call `list_models` with the matching `type` and read each model\'s STRENGTHS SUMMARY — the "— …" clause printed after the credit cost. That summary IS the routing instruction: match it against what the user actually asked for (subject, style, motion, length, quality bar, speed), then pick the CHEAPEST model whose summary covers the task. `[NEW]` and `[RECOMMENDED]` badges, a high credit number, and "flagship"/"most intelligent" wording are NOT selection signals — never pick a model because it is newest, biggest or most expensive. Escalate to a premium/frontier model only when the user explicitly asks for maximum quality, or when no cheaper summary covers the requirement. Models printed under "Named-only" (no summary) are opt-in: use them only when the user names them. TEXT/CHAT: `chat_send_message` bills PER TOKEN, so the listed credit number is not the cost — a frontier text model (Claude Fable 5, GPT-5.6 Sol, Pro-class) costs 5-30x a mid-tier one per reply. Default ordinary chat (writing, brainstorming, Q&A, summarising) to a balanced mid-tier model and reserve the frontier tier for hard reasoning or long-form code the user asked for.',
-      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit` (it runs on strong dedicated editing models, same as image generation). Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
+      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit`. Auto-pick only Nano Banana 2 (`nano-banana-2` / `nano-banana-2-image-editing`) or GPT Image 2 (`gpt-image-2` / `gpt-image-2/edit`) for photoreal photo edits, object removal, keep-subject/remove-others, or crowd cleanup. Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style, named-only for editing. Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.',
       '11. PRESET CONTRACT: if the user asks for a preset, names a preset, or says to use one of their/Kolbo presets, you MUST call `list_presets` with the matching type before generation, resolve the named or closest matching preset, and pass its exact returned `id` as `preset_id`. Use type="image" for generate_image and type="image_edit" for generate_image_edit. Never silently ignore a preset request, never invent an id, and never claim a preset was applied unless `preset_id` was present in the generation call.'
     ].join('\n')
   });

package/src/polling.js

@@ -80,7 +80,7 @@ async function pollUntilDone(client, generationId, options = {}) {
         }
         const backoff = Math.min(interval * Math.pow(1.5, Math.min(transientFailures - 1, 5)), 30000);
         await progress.tick(); // same keepalive as the normal path — backoff waits up to 30s
-        await new Promise((resolve) => setTimeout(resolve, backoff));
+        await progress.wait(backoff);
         continue;
       }
       // Non-transient (auth, 4xx other than 408/425/429) — bubble up.
@@ -109,7 +109,7 @@ async function pollUntilDone(client, generationId, options = {}) {
     // cadence could return at 60s). That is the difference between landing
     // inside the caller's transport window and blowing straight through it.
     const remaining = timeout - (Date.now() - startTime);
-    await new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(interval, remaining))));
+    await progress.wait(Math.max(0, Math.min(interval, remaining)));
   }
 }
 

package/src/progress.js

@@ -2,8 +2,79 @@ const { AsyncLocalStorage } = require('async_hooks');
 
 const storage = new AsyncLocalStorage();
 
-function run(extra, fn) {
-  return storage.run(extra, fn);
+async function run(extra, fn) {
+  return storage.run(extra, async () => {
+    try {
+      return await fn();
+    } finally {
+      if (extra?.signal && extra.__kolboAbortListener) {
+        extra.signal.removeEventListener('abort', extra.__kolboAbortListener);
+      }
+      if (extra) {
+        delete extra.__kolboAbortListener;
+        delete extra.__kolboTrackedGenerations;
+      }
+    }
+  });
+}
+
+function signal() {
+  return storage.getStore()?.signal;
+}
+
+function abortError() {
+  const error = new Error('The MCP tool call was cancelled by the caller.');
+  error.name = 'AbortError';
+  return error;
+}
+
+/** Wait without keeping a cancelled tool call alive until the next poll tick. */
+function wait(ms) {
+  const callerSignal = signal();
+  if (!callerSignal) return new Promise(resolve => setTimeout(resolve, ms));
+  if (callerSignal.aborted) return Promise.reject(abortError());
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      callerSignal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      callerSignal.removeEventListener('abort', onAbort);
+      reject(abortError());
+    };
+    callerSignal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Associate a submitted backend generation with the current MCP tool call.
+ * If Kolbo Code, Claude, or another MCP host cancels the tool while it is
+ * polling, every submitted generation is cancelled server-side as well.
+ */
+function trackGeneration(id, cancel) {
+  const extra = storage.getStore();
+  if (!extra?.signal || !id || typeof cancel !== 'function') return;
+
+  if (!extra.__kolboTrackedGenerations) extra.__kolboTrackedGenerations = new Map();
+  extra.__kolboTrackedGenerations.set(String(id), cancel);
+
+  const cancelTracked = () => {
+    const tracked = extra.__kolboTrackedGenerations;
+    if (!tracked) return;
+    extra.__kolboTrackedGenerations = new Map();
+    for (const cancelOne of tracked.values()) {
+      Promise.resolve().then(cancelOne).catch(() => {});
+    }
+  };
+
+  if (!extra.__kolboAbortListener) {
+    extra.__kolboAbortListener = cancelTracked;
+    extra.signal.addEventListener('abort', cancelTracked, { once: true });
+  }
+
+  if (extra.signal.aborted) cancelTracked();
 }
 
 async function generation(id) {
@@ -52,4 +123,4 @@ async function sendGenerationProgress(extra, token, id) {
   });
 }
 
-module.exports = { run, generation, tick };
+module.exports = { run, generation, tick, signal, wait, trackGeneration };

package/src/tools/_shared.js

@@ -518,7 +518,7 @@ async function modelChipFields(client, model) {
  *   kind           'image' | 'video' | 'audio' | '3d' | 'scenes'
  *   gen            the submit response ({ generation_id, poll_interval_hint })
  *   client         KolboClient (for model icon lookup)
- *   model, prompt, count, settings, reference_image, estimated_seconds
+ *   model, prompt, count, settings, reference_images, estimated_seconds
  *   voice          resolved voice record { name, thumbnail } (speech only)
  *   poll_tool      widget-side status tool (default 'get_generation_status')
  *   status_args    args for poll_tool (default { generation_id, wait: true })
@@ -542,7 +542,12 @@ async function uiGenerating(p) {
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},
-    reference_image: p.reference_image,
+    // `reference_image` is retained for older widget builds. New widgets render
+    // every browser-loadable image supplied to the generation.
+    reference_images: Array.isArray(p.reference_images)
+      ? p.reference_images.filter(Boolean)
+      : (p.reference_image ? [p.reference_image] : []),
+    reference_image: p.reference_image || p.reference_images?.find(Boolean),
     open_url: buildOpenUrl(p.tool, p.gen),
   };
   // Batch mode (prompts[] fan-out): ONE widget tracks every id in the set.
@@ -581,7 +586,10 @@ async function uiCompleted(p, textPayload) {
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},
-    reference_image: p.reference_image,
+    reference_images: Array.isArray(p.reference_images)
+      ? p.reference_images.filter(Boolean)
+      : (p.reference_image ? [p.reference_image] : []),
+    reference_image: p.reference_image || p.reference_images?.find(Boolean),
     urls: p.urls,
     thumbnail_url: p.thumbnail_url,
     title: p.title,

package/src/tools/generate.js

@@ -178,7 +178,7 @@ function registerGenerateTools(server, client, options = {}) {
           generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
           failed_submissions: batch.failed,
           status_args: { generation_ids: batch.ids, wait: true },
-          reference_image: reference_images?.[0]
+          reference_images
         });
         return pollBatch(client, batch, { interval: (batch.ok[0].gen.poll_interval_hint || 3) * 1000, timeout: 240000 });
       }
@@ -188,7 +188,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_image', kind: 'image', gen, client, model, prompt,
         count: num_images, settings: imageSettings(shared),
-        reference_image: reference_images?.[0]
+        reference_images
       });
 
       const poll = await pollOrTimedOut(client, gen.generation_id, {
@@ -221,7 +221,7 @@ function registerGenerateTools(server, client, options = {}) {
     'THE tool for ANY prompt-driven / content edit of an existing image — changing the scene ("make it night", "change the sky to sunset"), adding/removing/replacing objects, restyling, recoloring, compositing, or any "edit this image to…" request. This is the image-editing equivalent of generate_image and runs on strong dedicated editing models (nano-banana-2, gpt-image-2). Provide the source image URL(s) in `source_images` and the instruction in `prompt`. Supports Visual DNA profiles, moodboards, and Kolbo image-editing presets. PRESET CONTRACT: if the user requests a preset, call list_presets type="image_edit" and pass its exact id as `preset_id`; never silently omit it. Do NOT use `edit_image` for these — that tool is only for mechanical enhancements (upscale/reframe/remove-background/skin). For a brand-new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
       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 — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Many text-to-image ids double as editors: the server auto-routes a base id to its editing variant when source_images is present (e.g. "gpt-image-2" → gpt-image-2/edit, "nano-banana-2" → nano-banana-2/edit) — passing the bare id is fine, no need to hunt for the "/edit" suffix yourself. BUT this only works for models that actually have a registered edit variant (most flagship models do: gpt-image, nano-banana, flux-2, seedream, qwen, wan, grok-imagine, kling-image families). Models with none (Midjourney, Flux Pro/Ultra, Imagen4, Ideogram, Recraft, Higgsfield Soul, Krea, Dreamina, and others) silently ignore source_images if passed here instead of erroring — if unsure, confirm the model appears in `list_models type="image_editing"` before trusting a bare id, or just use a known-safe default: "nano-banana-pro/edit" (best general prompt editor), "gpt-image-2" (photoreal, strong text), or "flux-2/edit".'),
+      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Many text-to-image ids double as editors: the server auto-routes a base id to its editing variant when source_images is present (e.g. "gpt-image-2" → gpt-image-2/edit, "nano-banana-2" → nano-banana-2-image-editing) — passing the bare id is fine, no need to hunt for the "/edit" suffix yourself. BUT this only works for models that actually have a registered edit variant. For prompt-driven photoreal photo edits (object removal, keep-this-person/remove-the-rest, crowd cleanup, inpainting) the ONLY auto-pick defaults are "nano-banana-2" or "gpt-image-2" (use GPT Image 2 when the image needs readable text). Do NOT auto-pick Flux 2 / flux-2/edit / Flux Klein — those are generate-from-scratch / style models; use them only if the user names Flux. If unsure, confirm the model appears in `list_models type="image_editing"` and choose by the strengths summary — Flux edit variants are named-only.'),
       source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** 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") or use @image1/@image2 tags. 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"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
@@ -247,7 +247,7 @@ function registerGenerateTools(server, client, options = {}) {
         tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
         count: num_images,
         settings: imageSettings({ resolution, aspect_ratio, enhance_prompt, enable_web_search, visual_dna_ids, moodboard_id, preset_id, cinematic }),
-        reference_image: source_images?.[0]
+        reference_images: source_images
       });
 
       // Multi-source compositing or DNA-anchored edits routinely exceed 120s
@@ -309,7 +309,7 @@ function registerGenerateTools(server, client, options = {}) {
         tool: 'generate_creative_director', kind: 'scenes', gen, client, model, prompt,
         count: scene_count || 4,
         settings: { duration, resolution, aspect_ratio, mode: workflow_type || 'image' },
-        reference_image: reference_images?.[0],
+        reference_images,
         poll_tool: 'get_creative_director_status',
         status_args: { generation_id: gen.generation_id, wait: true }
       });
@@ -466,7 +466,7 @@ function registerGenerateTools(server, client, options = {}) {
           generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
           failed_submissions: batch.failed,
           status_args: { generation_ids: batch.ids, wait: true },
-          reference_image: reference_images?.[0]
+          reference_images
         });
         return pollBatch(client, batch, { interval: (batch.ok[0].gen.poll_interval_hint || 8) * 1000, timeout: 900000 });
       }
@@ -476,7 +476,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_video', kind: 'video', gen, client, model, prompt,
         settings: { duration, resolution, aspect_ratio },
-        reference_image: reference_images?.[0]
+        reference_images
       });
 
       // 15 min — Kling O3 4K, Veo 3.1 at higher durations/resolutions, Hailuo 2.3,
@@ -550,7 +550,7 @@ function registerGenerateTools(server, client, options = {}) {
           generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
           failed_submissions: batch.failed,
           status_args: { generation_ids: batch.ids, wait: true },
-          reference_image: items[0].image_url
+          reference_images: items.map((item) => item.image_url)
         });
         return pollBatch(client, batch, { interval: (batch.ok[0].gen.poll_interval_hint || 8) * 1000, timeout: 900000 });
       }
@@ -560,7 +560,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_video_from_image', kind: 'video', gen, client, model, prompt,
         settings: { duration, resolution, aspect_ratio },
-        reference_image: image_url
+        reference_images: [image_url]
       });
 
       // 15 min — same real-world generation times as generate_video (Kling O3 4K,
@@ -791,7 +791,8 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_sound', kind: 'audio', gen, client, model, prompt,
-        settings: { duration }
+        settings: { duration },
+        reference_images: seed_reference_image_url ? [seed_reference_image_url] : []
       });
 
       const poll = await pollOrTimedOut(client, gen.generation_id, {
@@ -1050,7 +1051,11 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_elements', kind: 'video', gen: startResponse, client, model, prompt,
         settings: { duration, resolution, aspect_ratio },
-        reference_image: reference_images?.[0]
+        reference_images: [
+          ...(reference_images || []),
+          ...(keyframes || []).map((keyframe) => keyframe.image_url),
+          ...(files || []).filter((source) => /^https?:\/\//i.test(source))
+        ]
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1134,7 +1139,8 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_first_last_frame', kind: 'video', gen: startResponse, client, model, prompt,
         settings: { duration, resolution, aspect_ratio },
-        reference_image: first_frame_url || undefined
+        reference_images: [first_frame_url || first_frame, last_frame_url || last_frame]
+          .filter((source) => /^https?:\/\//i.test(source || ''))
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1249,7 +1255,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_lipsync', kind: 'video', gen: startResponse, client, model,
         prompt: text_prompt, settings: { mode: 'lipsync' },
-        reference_image: sourceIsUrl && !/\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? source : undefined,
+        reference_images: sourceIsUrl && !/\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? [source] : [],
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1354,7 +1360,7 @@ function registerGenerateTools(server, client, options = {}) {
         tool: 'generate_video_from_video', kind: 'video', gen: startResponse, client, model,
         prompt: prompt || (preset ? `Subtitles preset: ${preset}` : undefined),
         settings: { duration, resolution, aspect_ratio, mode: preset ? 'subtitles' : 'restyle' },
-        reference_image: reference_images?.[0]
+        reference_images: [...(reference_images || []), ...(elements || [])]
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1497,7 +1503,7 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_3d', kind: '3d', gen: startResponse, client, model, prompt,
         settings: { mode: mode || (reference_images?.length > 1 ? 'multi' : reference_images?.length === 1 ? 'single' : 'text') },
-        reference_image: reference_images?.[0]
+        reference_images
       });
 
       const poll = await pollOrTimedOut(client, startResponse.generation_id, {
@@ -1643,7 +1649,7 @@ function registerGenerateTools(server, client, options = {}) {
         tool: 'edit_image', kind: 'image', gen, client, model,
         prompt: prompt || operation,
         settings: { mode: operation, aspect_ratio, scale, resolution },
-        reference_image: image_url
+        reference_images: [image_url, mask_image_url, ...(additional_images || [])].filter(Boolean)
       });
 
       const poll = await pollOrTimedOut(client, gen.generation_id, {
@@ -1808,7 +1814,7 @@ function registerGenerateTools(server, client, options = {}) {
         tool: 'edit_video', kind: 'video', gen, client, model,
         prompt: prompt || operation,
         settings: { mode: operation, duration, aspect_ratio, resolution },
-        reference_image: image_url
+        reference_images: image_url ? [image_url] : []
       });
 
       const poll = await pollOrTimedOut(client, gen.generation_id, {

package/src/tools/projects.js

@@ -85,7 +85,6 @@ function registerProjectTools(server, client, options = {}) {
       };
     }
   );
-
   // ─── bulk_move_sessions ────────────────────────────────────
   server.tool(
     'bulk_move_sessions',