@kolbo/mcp 1.89.3 → 1.90.1

package/README.md

@@ -314,3 +314,14 @@ Both are optional — the local install logs in via the browser on first use.
 ### Chat thinking level
 
 `chat_send_message` accepts optional `thinking_level`, using an ID from `list_models` with `type: "text"`. The server validates it against the resolved model; omitted or invalid values use `thinkingDefault`. Existing safeguards and legacy `deep_think` take precedence. Discover allowed levels through `thinkingLevels`; no package update is required when the server changes a model capability. For the Auto model, optional `routing_mode` accepts `fast`, `balanced`, or `smart`; omitted uses the server default of `balanced`.
+
+## Agentic Video Editor
+
+| Tool | Purpose |
+| --- | --- |
+| `get_video_editor_schema` | Complete writable settings and operation contract |
+| `list_video_editor_sessions` | Paginated project timelines |
+| `get_video_editor_session` | Full saved timeline and revision |
+| `update_video_editor_session` | Atomic rename, settings, tracks, clips, trims, speed, captions and effects |
+
+`create_video_editor_session` also accepts optional advanced `session_data` instead of clips/audio/texts. Read the schema and saved revision before editing. Changes affect saved state; reload an already-open editor before manual editing. Existing create/export names and arguments remain supported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.89.3",
+  "version": "1.90.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,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@73b21c8, the single source of truth.
+This tree is mirrored from kolbo-code@b77c8b4, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -102,11 +102,14 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Confirm **cost** or validate **resolution / aspect / duration** against model caps | `references/workflows/cost-and-validation.md` |
 | Hit an **auth / MCP / 429** issue | `references/workflows/troubleshooting.md` |
 | Inspect or change a connected **Blender** scene, render, import Kolbo media, or run approved Blender Python | `references/workflows/blender.md` |
+| Create or edit a saved **Video Editor** timeline, clips, trims, speed or captions | `references/workflows/video-editor.md` |
 
 Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/src/config/systemPrompt.js` — same battle-tuned rules that power Kolbo's web-app help widget. Keep parity (see `packages/opencode/CLAUDE.md` "MCP & Skill Sync Rule").
 
 ## Available MCP Tools
 
+For editable video timelines, read `references/workflows/video-editor.md`. Use `get_video_editor_schema`, `list_video_editor_sessions`, `get_video_editor_session`, `create_video_editor_session`, `update_video_editor_session`, and `export_video_editor_session`. Edit existing sessions in place using their saved revision; do not recreate them to rename or change clips.
+
 For personal font uploads, font selection, or reuse, read `references/workflows/personal-fonts.md`. Use the dedicated My Fonts tools; never the media-upload path or agent-rendered specimens.
 
 Font tools (when exposed by the installed MCP): `list_fonts`, `get_font`, `upload_font`, `get_font_upload_status`, `create_font_upload_ticket`, `font_upload_widget`, `rename_font`, `delete_font`. Image creation/editing and image-mode Creative Director accept `font_ids` only on models with `supports_custom_fonts`.
@@ -294,7 +297,7 @@ A user-named tool — in any language — overrides every other rule. Recognized
 4. **Pick the model**:
    - User named one → that name is a **family lock**, not a single catalog row. Use it. Identifiers resolve leniently — `"z-image"` / `"nano banana 2"` / `"grok imagine"` auto-resolve, including to the sibling for the tool you are calling (`grok-imagine-text-to-video` on `generate_video_from_image` becomes `grok-imagine-image-to-video`). `list_models` is still authoritative for constraints, caps, and pricing — not for swapping brands.
    - **Never cheapest-swap a named family.** After compaction, "animate those images" is still Grok if the user said Grok. Seedance / Kling / Veo are not a "best balance" substitute. If the named family has no variant for this modality, ASK — do not silently switch.
-   - Auto-select → **only when no model was named on this task**. Then pick from "Auto-selectable" (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
+   - Auto-select → **only when no model was named on this task**. Then pick from "Auto-selectable" (models with a `summary`). Follow Media selection preferences below: ordinary production uses the eligible general workhorse; select specialists for matching tasks and budget models for explicit cheap tests/drafts. Cost breaks ties between suitable choices.
    - Never auto-select from "Named-only" section.
 5. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
 6. **Fire the call(s)** — then follow "⚠️ Generation lifecycle" below for waiting, status, and failure handling.
@@ -440,3 +443,18 @@ HTML/SVG/Mermaid artifacts have a **Share** button in the preview toolbar that u
 ---
 
 If at this point you still don't know which `references/` file to load, default to `references/models/prompt-copilot.md` for generation prompts or `references/workflows/cost-and-validation.md` for cost/validation questions, or just keep going with this core file's rules.
+
+## Media selection preferences
+Honor explicit models, presets, budget and inputs. Choose only eligible catalog candidates with all required capabilities. Use requested presets; otherwise use fitting presets when useful. For video generation, editing and lip-sync, when the user has not explicitly selected an output resolution, use the cheapest supported output resolution from the live catalog and pass it explicitly; do not inherit an expensive provider default. Preserve explicit user-selected resolution/settings. Finish fully, cinematic, professional, final, production and available credits are NOT permission to increase resolution. Never infer output resolution from reference media or export settings. A budget is a ceiling, not a spending target. Do not upscale or regenerate at a higher tier without explicit user authorization. If pricing or supported resolutions cannot be verified, inspect the catalog before dispatch; never invent a tier. Models with fixed output resolution use their native output. Never treat a policy refusal as a technical failure or route around safeguards.
+Default images and edits: GPT Image 2.5 Flare/Sunburst; medium for value, high for ordinary maximum quality. Reserve xhigh/max for exceptional dense or difficult multilingual text after medium/high prove insufficient; do not automatically spend on retries. Nano Banana 2 is secondary. Seedream 5.0 Pro favors cinematic aesthetics over complex instruction fidelity; Wan 2.7 Pro is another creative alternative. Z Image/P Image for cheap tests. Midjourney for artistic concepts only, never editing. Soul V2 for realistic people/UGC concepts; derive character sheets before registering finished Visual DNA. Mirage Film 2 for environments and cinematic inspiration.
+Default video: Seedance 2.5. Kling specializes in controlled single-image and first/last-frame shots. Wan 3.0 specializes in motion graphics and Hebrew/dialogue work. MiniMax H3 offers higher resolution; H3 Max favors speed at lower resolution. Gemini Omni Flash is a secondary Hebrew option (up to 10 seconds); Grok Imagine 1.5 and Seedance 2.0 are alternatives. P Video/Draft for cheap fast tests. Use base, edit or extend variants only with their required inputs.
+Existing-video lip-sync: Sync 3 for active-speaker handling; PixVerse for cartoons/2D and economical faster work. Portrait lip-sync: Veed Fabric or HeyGen Avatar; P Avatar for budget work. LTX Audio to Video for camera/environment motion with audio-driven performance.
+Default music: Suno v6. ElevenLabs Music is an alternative, especially for duration-directed scoring. Both accept custom duration requests; validate the selected tool schema and inspect actual output duration.
+
+## Capability and result honesty
+- Your current tools and mode define what you can do. In Act, use available authorized tools to generate/edit media, manage project assets and Visual DNA, import originals, or build/export an editable video timeline. In Ask or a prompt-only/final-answer stage without those tools, explain, write prompts or navigate; never pretend to execute. Do not claim access to every Kolbo feature, the user's browser/computer, private accounts or unrelated projects.
+- Match the live model and tool schema to the task: inputs, reference slots, duration, resolution, quality, native audio and output format. A model preference is not a capability guarantee. Reuse recent catalog evidence; refresh only when missing or contradicted. If a requested operation is unavailable, explain the specific limitation and a supported alternative without silently changing the brief.
+- Website media discovery reads public page markup and embedded data; it is not interactive browsing and does not execute page scripts. Discovery is not import. Use verified original assets, retain attribution and report blocked/missing assets honestly. When an existing logo is requested, never invent or substitute a generated logo for the original. Original logo design is a separate supported creative task when requested.
+- Distinguish planned, submitted, running, generated, saved, exported and inspected. A playable render is not an editable timeline; only a successful editor-session result proves a saved edit exists. Tool success proves execution, not visual fidelity, exact logos, readable text, lip-sync or absence of black frames. Inspect with available tools before claiming quality; otherwise mark it unverified.
+- A timeout is not proof of failure. Reconcile existing job IDs before retrying. Submit independent work together; describe queued versus running work truthfully. Never promise unlimited concurrency, automatic refunds, exact credit costs or approval outcomes. Use current receipts/pricing and preserve authorized budgets.
+- Continue within granted autonomy and the current approved scope. Ask only for essential missing input or required approval. Content-policy refusals do not authorize switching providers to bypass safeguards. Support may review a restriction, but never promise an exception or entitlement.

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

@@ -32,9 +32,10 @@ Load this file when the user wants a **GPT Image 2 or GPT Image 2.5** image (Ope
 
 ## Latency vs Fidelity (recommend `quality` param)
 
-- **low**: high-volume batches, drafts, ideation, latency-sensitive cases. Often "good enough" — default for variant exploration.
-- **medium**: balanced. Style probing, normal exploration.
+- **low**: only when the user prioritizes minimum cost or latency; medium remains the ordinary GPT Image 2.5 default.
+- **medium**: default best price/quality for ordinary generations, edits and exploration.
 - **high**: final assets, small/dense text, multi-font layouts, close-up portraits, identity-sensitive edits, infographics, diagrams, posters, UI with labels, scientific visuals, slides with charts/footnotes.
+- **xhigh/max** (GPT Image 2.5 only, when listed): exceptional dense text or difficult multilingual/Hebrew typography after medium/high are insufficient. Do not auto-run retries or raise spending without authorization.
 
 ## Use Cases (text → image)
 

package/skill/references/models/html-presentation.md

@@ -6,7 +6,7 @@
 
 Load this file when the user wants to **build / create / generate an HTML presentation, slide deck, or pitch deck**. For landing pages see `models/landing-page.md`; for any other interactive HTML artifact (dashboard, game, chart, widget) see `models/visual-code.md`.
 
-**Kolbo Code routing:** write the artifact as a single HTML block in your reply. The Kolbo Code panel renders it as a previewable artifact card. Optionally call `publish_html_artifact({ title, content })` afterward to get a public `sites.kolbo.ai` URL.
+**Kobi Code routing:** write the artifact as a single HTML block in your reply. The Kobi Code panel renders it as a previewable artifact card. Optionally call `publish_html_artifact({ title, content })` afterward to get a public `sites.kolbo.ai` URL.
 
 ## 🚨 NON-NEGOTIABLE: Viewport Fitting
 

package/skill/references/models/landing-page.md

@@ -6,7 +6,7 @@
 
 Load this file when the user wants to **build / create a landing page, marketing site, one-pager, product page, app launch page, SaaS sign-up page, or event page**. For slide decks see `models/html-presentation.md`; for dashboards / games / charts / widgets see `models/visual-code.md`.
 
-**Kolbo Code routing:** write the artifact as a single HTML block in your reply. Kolbo Code's panel renders it as a previewable artifact card. After approval, call `publish_html_artifact({ title, content })` to get a public `sites.kolbo.ai` URL.
+**Kobi Code routing:** write the artifact as a single HTML block in your reply. Kobi Code's panel renders it as a previewable artifact card. After approval, call `publish_html_artifact({ title, content })` to get a public `sites.kolbo.ai` URL.
 
 ## 🎯 Design Thinking — Commit Before You Code
 

package/skill/references/models/seedance25.md

@@ -13,7 +13,7 @@ Load this file when the user wants a **Seedance 2.5** video (they said "2.5" / "
 
 **Dialogue language: English.** Other languages are not reliably performed, and Hebrew does not work — it returns accented gibberish or English-shaped mouth movement. Never offer a user "Hebrew dialogue directly". This restriction applies to rendered dialogue/prose only, never to binding identifiers: preserve an exact stored Hebrew Visual DNA or moodboard tag such as `@אביב` / `#ישראל` literally. See `models/seedance.md` for the three honest alternatives.
 
-**Draft at 480p.** Resolution is a credit MULTIPLIER, not a flat rate. Relative to 720p: 480p ×0.44, 1080p ×2.25. A 30s pass costs ~540cr at 480p against ~1230cr at 720p and ~2770cr at 1080p. Block the film at 480p, get the user's sign-off on staging, performance and timing, then re-run only the approved cut at delivery resolution.
+**Use the cheapest supported tier unless the user selected an output resolution.** Resolution is a credit MULTIPLIER, not a flat rate. Relative to 720p: 480p ×0.44, 1080p ×2.25. A 30s pass costs ~540cr at 480p against ~1230cr at 720p and ~2770cr at 1080p. When no output resolution was selected and 480p is the cheapest supported tier, block the film at 480p, get the user's sign-off on staging, performance and timing, then re-run only the approved cut at a higher delivery resolution if the user explicitly authorizes that resolution increase. Approval of the creative cut alone does not authorize a more expensive resolution. If no output resolution was selected, use the cheapest supported tier from the live catalog even for final work; pass it explicitly.
 
 ## What's NEW in 2.5 (verified — never hedge)
 

package/skill/references/models/visual-code.md

@@ -8,7 +8,7 @@ Load this file when the user wants to **build an interactive HTML artifact where
 
 If the user asks for a **presentation** → see `models/html-presentation.md`. If they ask for a **landing page** → see `models/landing-page.md`. Everything else visual-and-interactive is here.
 
-**Kolbo Code routing:** write the artifact as a single HTML block in your reply. Kolbo Code's panel renders it as a previewable artifact card. Call `publish_html_artifact({ title, content })` to publish to `sites.kolbo.ai` after approval.
+**Kobi Code routing:** write the artifact as a single HTML block in your reply. Kobi Code's panel renders it as a previewable artifact card. Call `publish_html_artifact({ title, content })` to publish to `sites.kolbo.ai` after approval.
 
 ## What This Skill Is For
 

package/skill/references/workflows/cost-and-validation.md

@@ -102,18 +102,15 @@ Normal cost formula: `final_cost = credit × output_seconds × resolution_multip
    - ✅ Show them the supported set in one line and ask:
      > "Seedance 2 elements supports `[720p, 1080p, 1440p, 2160p]` — 480p isn't available. Closest cheap option is 720p (~+0 credits over your intent). Want 720p, or pick another?"
    - Only fire after they reply.
-2. **User specified quality intent without numbers** ("draft", "quick test", "final delivery", "for client", "production"):
-   - draft / quick / preview → cheapest in `supported_resolutions` (1K / 720p)
-   - normal / standard → middle tier (typically 2K / 1080p)
-   - final / production / hero → highest the user's budget allows (3K-4K / 1440p-2160p)
-3. **No quality signal AND cost difference >2×** OR total batch ≥4 outputs → **ask the user once** with a one-line cost comparison, then default to standard if they don't reply.
-4. **No quality signal AND cost difference ≤1.5×** → quietly use the cheapest supported, no need to interrupt.
+2. **No explicit video output resolution**: choose the cheapest supported tier using current catalog pricing and pass it explicitly. This applies to drafts, normal work and final delivery alike. Do not default to 720p/1080p when a cheaper supported tier exists. Fixed-resolution models use their native output.
+3. **Creative intent is not spending authorization**: "finish fully", "cinematic", "professional", "final", "production", "hero" and "don't ask me" do not authorize higher resolution, upscaling or a second high-resolution generation. A budget is a ceiling, not a target. Reference-video resolution and export resolution do not authorize matching generation resolution.
+4. Preserve explicit user-selected settings. Otherwise proceed economically without a resolution approval loop. Inspect missing pricing/capabilities before dispatch. Upgrade only when the user explicitly selects a higher output tier or authorizes the resolution increase; never treat silence as approval. Image quality follows the image-model guidance (GPT Image 2.5 medium by default), not a generic final-work maximum.
 5. **Sound on a video model with `sound_credit_multiplier > 1`** → if user didn't ask for sound, leave it off. If user said "with sound" / "with music", enable it.
 
 ## Defaults When Nothing Is Specified
 
 - **Image**: `1K` (or the cheapest in `supported_resolutions`).
-- **Video**: `720p` (or the cheapest), with `default_duration` (or shortest in `supported_durations`).
+- **Video**: cheapest supported output resolution from current catalog pricing, passed explicitly. Use the duration required by the user/task; do not lengthen clips to spend the available budget.
 - **Sound**: respect `sound_enabled_by_default`; if false, leave off.
 
 ## Log Approved Resolution / Duration / Sound Choices

package/skill/references/workflows/filmmaking.md

@@ -145,4 +145,4 @@ Fix errors before delivery. Report warnings that represent genuine creative trad
 
 Read [workflows.md](references/filmmaking/workflows.md) for single shots, dialogue scenes, music performance, connected sequences, impossible shots, and feature workflows.
 
-This workflow is part of the canonical Kolbo skill. The Kolbo Code sync pipeline mirrors it to MCP and plugin consumers; product surfaces may compile the same filmmaking truth through their own model adapters.
+This workflow is part of the canonical Kolbo skill. The Kobi Code sync pipeline mirrors it to MCP and plugin consumers; product surfaces may compile the same filmmaking truth through their own model adapters.

package/skill/references/workflows/troubleshooting.md

@@ -73,9 +73,9 @@ Branch on `failure.category` / `failure.retryable`:
 - `retryable === true` (transient: network, rate limit, provider 5xx) → retry once with the same payload after a short pause. If it fails again, surface to user.
 - `retryable === false` and unknown category → surface the raw `message` to the user, don't retry.
 
-## Kolbo Code Documentation
+## Kobi Code Documentation
 
-Full public documentation for Kolbo Code (the CLI you are running inside) lives at **[docs.kolbo.ai/docs/kolbo-code](https://docs.kolbo.ai/docs/kolbo-code)**. If the user asks about installation, authentication, voice input, supported languages, commands, or how to uninstall, point them to the matching page below rather than guessing:
+Full public documentation for Kobi Code (the CLI you are running inside) lives at **[docs.kolbo.ai/docs/kolbo-code](https://docs.kolbo.ai/docs/kolbo-code)**. If the user asks about installation, authentication, voice input, supported languages, commands, or how to uninstall, point them to the matching page below rather than guessing:
 
 | Topic | Path |
 |-------|------|

package/skill/references/workflows/video-editor.md

@@ -0,0 +1,28 @@
+# Agentic Video Editor
+
+Use these tools for a saved timeline the user can reopen and edit in Kolbo.
+
+1. Call `list_video_editor_sessions` with the project ID, or use a session ID supplied by the user.
+2. Call `get_video_editor_schema` for the current writable fields and operation schemas.
+3. Call `get_video_editor_session`. Preserve its revision and stable track/item IDs.
+4. Call `update_video_editor_session` with that revision as expected_revision and a bounded batch of operations. On REVISION_CONFLICT, read again and reapply the user's intent. Never blindly retry an old full timeline.
+5. Read back the saved result. Export with `export_video_editor_session` only when a rendered deliverable is requested. Reuse a pending export's job_id.
+
+For creation, `create_video_editor_session` accepts the original clips/audio/texts builder or advanced session_data, never both. Advanced data supports blank, text-only and caption-only timelines. Supply the name and authorized project ID. Import external media into Kolbo before adding its URL.
+
+## Editing semantics
+
+- session_flags changes isPinned, isArchived or isLocked using the same revision. A locked session requires an explicit isLocked=false request before content changes.
+
+- session_data patches name, format, dimensions, fps, duration, background, and mediaLibrary. Supplying tracks replaces the full track array, so prefer operations for existing edits.
+- Operations add/update/remove tracks and items, move items between tracks, order tracks, and order clips sequentially. Read the schema for exact argument names.
+- Source trimStart and trimEnd are milliseconds removed from the source head and tail. originalDuration remains the source length. Changing trims or playbackRate recalculates timeline duration unless explicitly supplied. Fractional milliseconds are retained.
+- reorder_items lays every item in one track end-to-end from the requested start. It does not move other tracks. move_item preserves duration. Track order is bottom-to-top.
+- Nested settings replace the previous value. Use unset to clear an optional setting; do not merge grading presets.
+- Session duration expands for new content but does not automatically shrink. Set duration explicitly to remove trailing background.
+- Caption items support content, words, typography, RTL, background, stroke, shadow and captionStyle. Word startTime/endTime use absolute timeline milliseconds and must fit inside the caption item. Moving/reordering captions moves their words too. To derive captions from speech, use `transcribe_audio` first; edits themselves do not transcribe or generate media.
+- Settings include transforms, opacity, visibility, audio volume/gain/fades, playback rate, grading, motion and the available text/caption effects. Consult the schema rather than inventing fields.
+
+The tools edit saved state. Updated browser editors receive each saved change automatically and preserve the playhead and view. Unsaved manual edits pause autosave and show a conflict choice. Browser and agent writes both use revision checks. This requires the updated API and browser; it does not stream an agent's unsaved intermediate operations.
+
+Saved settings and successful exports do not prove visual parity for every renderer effect. Inspect the output before claiming visual quality. Respect the user's deployment, publishing and generation-spend boundaries.

package/src/toolAnnotations.js

@@ -9,6 +9,7 @@
  */
 
 const READ_ONLY = [
+  'get_video_editor_schema', 'list_video_editor_sessions', 'get_video_editor_session',
   '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',
@@ -67,6 +68,8 @@ const PRIVATE_WRITE = [
 ];
 
 const DESTRUCTIVE_WRITE = [
+  'extend_music', 'cover_music',
+  'update_video_editor_session',
   'delete_font',
   'export_video_editor_session',
   // These actions spend credits, enqueue irreversible work, or cancel it.
@@ -96,7 +99,8 @@ const DESTRUCTIVE_WRITE = [
   'edit_review_comment', 'delete_review_comment',
 ];
 
-const OPEN_WORLD_WRITE = [
+const OPEN_WORLD_WRITE = [
+  'import_music_audio',
   'publish_html_artifact', 'create_review_share_link', 'blender_capture_viewport',
 ];
 

package/src/tools/editor.js

@@ -2,12 +2,31 @@
 const { z } = require('zod');
 
 function registerEditorTools(server, client) {
+  const output = data => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
+  server.tool('get_video_editor_schema',
+    'Read the full writable Video Editor schema before advanced edits. Documents every clip, track, caption and session setting, timing units, revision checks and operation semantics.', {},
+    async () => output(await client.get('/v1/editor/schema')));
+  server.tool('list_video_editor_sessions',
+    'List saved Video Editor sessions in an accessible project. Paginated; use get_video_editor_session for full timeline data.',
+    { project_id: z.string().min(1), limit: z.number().int().min(1).max(100).optional(), offset: z.number().int().min(0).max(100000).optional() },
+    async args => output(await client.get(`/v1/editor/sessions?${new URLSearchParams(Object.entries(args).filter(([, value]) => value !== undefined))}`)));
+  server.tool('get_video_editor_session',
+    'Read an existing Video Editor timeline: stable track/item IDs, all settings, clips, captions and revision. Always read before updating.',
+    { session_id: z.string().min(1).max(100) },
+    async ({ session_id }) => output(await client.get(`/v1/editor/sessions/${encodeURIComponent(session_id)}`)));
+  server.tool('update_video_editor_session',
+    'Edit or rename a saved Video Editor session. First read get_video_editor_schema and get_video_editor_session. session_data patches settings (name, format, duration, fps, dimensions, background) or replaces tracks. operations support add/update/remove/move items and tracks, reorder_items and reorder_tracks. Full clip settings include source trims, speed, transforms, grading, audio, text and word-timed captions. Nested values replace rather than merge. All times are milliseconds. Requires the revision from the read; conflicts require re-reading. Changes save atomically without generation credits. Reload an already-open editor before manual edits.',
+    { session_id: z.string().min(1).max(100), expected_revision: z.string().min(1).max(100),
+      session_flags: z.object({ isPinned: z.boolean().optional(), isArchived: z.boolean().optional(), isLocked: z.boolean().optional() }).strict().optional(),
+      session_data: z.record(z.unknown()).optional(), operations: z.array(z.record(z.unknown())).min(1).max(200).optional() },
+    async args => output(await client.patch('/v1/editor/sessions', args)));
   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.',
     {
+      session_data: z.record(z.unknown()).optional().describe('Advanced initial timeline settings and tracks; read get_video_editor_schema. Use instead of clips/audio/texts. Supports blank or caption-only sessions.'),
       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),
+      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).optional(),
       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(),
     },

package/src/tools/generate.js

@@ -852,6 +852,96 @@ function registerGenerateTools(server, client, options = {}) {
     }
   );
 
+  // ─── music import / extend / cover ─────────────────────────
+  // Three tools over the SDK's /v1/generate/music/{import,extend,cover}. The web app has
+  // had upload-extend and upload-cover for a long time; agents could not reach either
+  // until those routes existed.
+  const musicSourceFields = {
+    audio_url: z.string().optional().describe('PUBLIC URL of the source audio. Either this (with rights_confirmed) or upload_id is required. Local file? Call upload_media first and pass the returned https:// URL.'),
+    upload_id: z.string().optional().describe('Upload id from import_music_audio. Use this to reuse one imported file across several calls instead of re-importing it.'),
+    rights_confirmed: z.boolean().optional().describe('REQUIRED with audio_url: confirms the caller holds the rights to the source audio. Not needed when passing upload_id (it was confirmed at import).'),
+    prompt: z.string().optional().describe('What the new material should sound like.'),
+    style: z.string().optional().describe('Music style / genre for the new material.'),
+    title: z.string().optional().describe('Title for the result. Generated if omitted.'),
+    instrumental: z.boolean().optional().describe('Produce instrumental only, no vocals. Default: false'),
+    lyrics: z.string().optional().describe('Custom lyrics. Omit to have them generated, or set instrumental.'),
+    model: z.string().optional().describe('Model identifier. Omit for the Suno default.'),
+    project_id: projectIdField,
+    session_id: sessionIdField
+  };
+
+  server.tool(
+    'import_music_audio',
+    'Import a PUBLIC audio URL into Kolbo as a reusable music source, returning an upload_id for extend_music / cover_music. Use it when the same track feeds several calls — both of those tools also accept audio_url directly for a one-shot. LOCAL FILE? Call upload_media first and pass the returned https:// URL; this tool cannot read the caller\'s disk. You must set rights_confirmed: true — Kolbo requires the caller to hold the rights to audio they upload.',
+    {
+      audio_url: z.string().describe('PUBLIC URL of the audio file to import.'),
+      upload_type: z.string().optional().describe('What the import is for: "extend" or "cover". Must match the tool you later call with it. Default: "extend".'),
+      rights_confirmed: z.boolean().describe('REQUIRED true: confirms the caller holds the rights to this audio.'),
+      confirmation_text: z.string().optional().describe('Optional free-text rights confirmation recorded with the upload.'),
+      project_id: projectIdField,
+      session_id: sessionIdField
+    },
+    async ({ audio_url, upload_type, rights_confirmed, confirmation_text, project_id, session_id }) => {
+      const r = await client.post('/v1/generate/music/import', {
+        audio_url, upload_type: upload_type || 'extend', rights_confirmed, confirmation_text, project_id, session_id
+      });
+      return result(r);
+    }
+  );
+
+  // Both generation tools share one runner — the only difference is the route and the label.
+  const runMusicSourceOp = async (route, toolName, args) => {
+    const { model: rawModel, continue_at, ...rest } = args;
+    const model = await canonicalModelId(client, rawModel, 'music_gen');
+    const gen = await client.post(route, { ...rest, model, ...(continue_at !== undefined ? { continue_at } : {}) });
+
+    if (returnsImmediately()) return submittedResult({
+      tool: toolName, kind: 'audio', gen, client, model: model || 'Suno', prompt: rest.prompt,
+      settings: { mode: rest.instrumental ? 'instrumental' : (rest.style || undefined) },
+    });
+
+    const poll = await pollOrTimedOut(client, gen.generation_id, {
+      interval: (gen.poll_interval_hint || 8) * 1000,
+      timeout: 150000
+    });
+    if (poll.timedOut) return poll.timedOut;
+    const res = poll.result;
+
+    return uiCompleted({
+      tool: toolName, kind: 'audio', gen, client, model: model || 'Suno', prompt: rest.prompt,
+      settings: { mode: rest.instrumental ? 'instrumental' : (rest.style || undefined) },
+      urls: res.result.urls,
+      playback_urls: res.result.playback_urls,
+      tracks: res.result.tracks,
+      title: res.result.title,
+      duration: res.result.duration,
+      credits_used: creditFields(res).credits_used,
+    }, JSON.stringify({
+      ...creditFields(res),
+      session_id: gen.session_id,
+      urls: res.result.urls,
+      tracks: res.result.tracks,
+      title: res.result.title,
+      duration: res.result.duration,
+      lyrics: res.result.lyrics
+    }, null, 2));
+  };
+
+  server.tool(
+    'extend_music',
+    'Continue an existing track — Kolbo generates new music that carries on from a point in the source audio. Pass audio_url (with rights_confirmed) or an upload_id from import_music_audio. There is NO target-length control here: the length follows the source and continue_at, which is why duration_seconds is not accepted. Returns the final audio URL when complete.',
+    { ...musicSourceFields, continue_at: z.number().optional().describe('Seconds into the source audio to continue FROM. Omit to continue from the end.') },
+    async (args) => runMusicSourceOp('/v1/generate/music/extend', 'extend_music', args)
+  );
+
+  server.tool(
+    'cover_music',
+    'Re-record an existing track in a new style, keeping its musical identity — a lo-fi cover of a rock song, an acoustic take on an electronic track. Pass audio_url (with rights_confirmed) or an upload_id from import_music_audio. There is NO target-length control here: a cover follows the length of its source, which is why duration_seconds is not accepted. Returns the final audio URL when complete.',
+    { ...musicSourceFields },
+    async (args) => runMusicSourceOp('/v1/generate/music/cover', 'cover_music', args)
+  );
+
+
   // ─── generate_speech ───────────────────────────────────────
   server.tool(
     'generate_speech',