@hubfluencer/mcp 0.12.0 → 0.14.0

package/README.md

@@ -68,7 +68,7 @@ claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hub
 
 ## Tools
 
-95 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+97 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
 below are the ground truth. **"$0" means it spends no video credits**; planning/AI-helper tools
 instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_assists`: 1 credit
 → +10). Reads need the `video:read` scope; writes need `video:generate`. Nothing here needs
@@ -82,12 +82,14 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `create_short` | Create a short draft (12s vertical: two 6s AI segments + title overlay + music; 14s when it ends on a poster or brand-lockup end card). Set `headline` (≈4 words, ≤40 chars), `subheadline`, `music_vibe`, and an explicit `visual_language` (`kinetic_creator` is a strong default) — and **always `cta_text`** (a short without a CTA doesn't convert; blank `cta_text` → the server renders a neutral localized ask, e.g. "Learn more" — a truly CTA-less short is not currently supported). End-card fields: `closing_claim` (≤80), `brand_name` (≤40), `end_card` (`"auto"`\|`"none"`). Other opt-in conversion graphics: `offer_text`/`badge_text`/`star_rating` — only what you can substantiate. | **0** |
 | `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, end-card fields (`closing_claim`/`brand_name`/`poster_includes_lockup`/`end_card`), logo overlay placement (`short_logo_position`/`short_logo_treatment`), or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Apply text/style/CTA/end-card/logo edits to a generated short free with `rerender_short`; footage/music edits need `generate_short`. | **0** |
 | `generate_short` | Render an existing short — re-rolls the footage + music (fresh AI generation). If headline/subheadline/beats are all blank the server auto-writes the copy first (`skip_auto_text:true` for a deliberately bare clip). Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
+| `cancel_short_generation` | Stop the caller-observed paid short attempt, fence late workers from publishing, preserve the draft, and restore its 15 credits idempotently. Requires `generation_attempt` from `get_status`; stale commands cannot cancel a newer run. | **full refund** |
 | `rerender_short` | **FREE re-render** — applies the short's current text/style/CTA/end-card/logo state over the already-paid footage + music. Use after `update_short` for copy/style/CTA tweaks, or after a logo change (`set_short_logo`, or `short_logo_position`/`short_logo_treatment`); footage or music changes need `generate_short` instead. Needs one completed generation first (422 `short_not_ready` otherwise); changed footage/music inputs return 422 `short_paid_regeneration_required`. A failed free re-render leaves the delivered video intact — retry `rerender_short`, it stays free. | **0** |
 | `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
 | `create_editor_ad` | Create an editor project, attach optional local product/logo/closing assets, and return the live autopilot quote. Omit `max_credits` to stop free; provide an approved cap to launch. Write every required person, product, object, and continuity decision directly in the prompt. | **0** until capped launch |
 | `start_autopilot` | Quote autopilot on an **existing** editor draft when called with only `slug`; launch only with an explicit `max_credits` that covers the estimate and an adequate balance. On a completed project, pass `restart:true` to quote and build a fresh creative run; omit it to resume pending edits. | **0** quote; credits on capped launch |
 | `retry_editor_batch` | Recover `batch_retry_required` by atomically re-queueing the failed scene and resuming its prepaid batch. If the parent Autopilot run is terminal, quote/relaunch it separately afterward. | **0 additional** |
 | `cancel_editor_batch` | Cancel an editor batch only while it is `preparing` or `paused_for_retry` (awaiting-previews/running batches are worker-owned and not cancellable). Preparing cancellation releases the uncharged preflight; paused cancellation is destructive — prepaid credits are not refunded. | **0 additional** |
+| `cancel_autopilot` | Stop a **running** Autopilot run: flips `autopilot_status` to `cancelled` so the chain (scenario → scenes → narration → voice → music → render) advances no further. Charged scenes stay charged and all completed work is kept; a step already enqueued may still finish. Idempotent — a no-op when Autopilot isn't running. (Use `cancel_editor_batch` for a non-Autopilot prepaid batch, `cancel_segment_generation` for one scene.) | **0 additional** |
 | `create_slider` | Create an image-carousel draft: one prompt → N still slides + a ready-to-post caption + hashtags. `mode` `creative` (story) or `ad_driven` (facts). | **0** |
 | `generate_slider` | Render a carousel (copy → AI backgrounds → composite). Poll `get_slider` until `completed`. | **1 / slide** (3–10) |
 | `get_slider` | Read a carousel's status and, when completed, the per-slide image URLs + caption + hashtags. | **0** |
@@ -106,12 +108,13 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `set_scene_count` | Grow/shrink to N scenes (1–20); deletes only trailing un-generated scenes. Each AI scene is a fixed 8s. | **0** |
 | `set_segment_prompt` | Write one scene's prompt (1–2000 chars), identified by segment id. | **0** |
 | `generate_segment` | Render one **pending/failed** scene (re-call to retry a failed one). | **5** |
+| `cancel_segment_generation` | Stop the caller-observed individually generated scene, fence its provider job from publishing, and restore any charged credits idempotently. Requires that scene's `generation_claim_token` from `get_editor`; stale commands cannot cancel a newer attempt. Batch/Autopilot scenes use their workflow-level controls. | **full refund** |
 | `regenerate_segment` | Re-roll a **completed** scene as a new version (optional new `prompt`). Mid-timeline: the next scene's transition can degrade because it was seeded from the old version's last frame. | **4** |
 | `generate_all_segments` | Render every not-yet-completed scene in order (continuity preserved); capped ~280s → re-run to continue. | **5 / segment** |
 | `set_narration_script` / `generate_narration` | Write your own voiceover script (free) **or** AI-draft one coherent script after every scene has completed with a known positive duration. AI drafting requires at least one scene without retained original audio and consumes an assist only when a fresh job is queued (exact retries dedupe for free). | free / 1 assist |
 | `generate_voice` | Synthesize the voiceover. `voice_id` required (see `list_voices`). | **3** |
 | `generate_music` | Generate background music (each call is a fresh take). | **5** |
-| `render` | Final MP4. Auto-charges any still-ungenerated scenes first (4/scene in a batch of ≥3). | **0** |
+| `render` | Final MP4. Auto-charges and generates any pending or failed scenes first (4/scene in a batch of ≥3). | **0** |
 | `list_renders` | List every render version for an editor project (`id`, `version`, `status`, `video_url`, `thumbnail_url`, `duration_seconds`, `error_message`, `retryable`, `combination_hash`, `is_stale`, `inserted_at`) — find a failed render or recover a finished URL. | **0** |
 | `retry_render` | Re-run a **failed** render from its exact saved snapshot (recovery without re-driving the pipeline). | **0** |
 | `enhance_prompt` / `suggest_next_scene` / `suggest_music_prompt` | AI helpers along the way. | 1 assist each |
@@ -159,9 +162,15 @@ completed | failed`). Batch state is `idle | preparing | awaiting_previews | run
 paused_for_retry | paused_insufficient_credits | completed | cancelled | failed`.
 Only `paused_for_retry` is resumed by `retry_editor_batch`; `cancel_editor_batch` works
 only while the batch is `preparing` or `paused_for_retry` — awaiting-previews/running
-batches are worker-owned and cannot be cancelled. Preparing cancellation releases the
-uncharged preflight (nothing was charged yet); paused cancellation is destructive and
-non-refundable. Both tools re-read the editor state and echo `expected_batch_run_id` +
+batches are worker-owned and cannot be cancelled. While `paused_for_retry` you may first
+REPAIR the one failed scene before retrying: `set_segment_prompt` edits its prompt (and
+`use_previous_frame`), but only for the exact failed position the server names in
+`batch_generation_failed_position` — the rest of the paused batch stays mutation-locked, and
+explicit paused retries are capped (`free_retries_exhausted`). Preparing cancellation releases
+the uncharged preflight (nothing was charged yet); paused cancellation is destructive and
+non-refundable. To stop a **running** parent Autopilot run (not a paused batch), use
+`cancel_autopilot` — it flips `autopilot_status` to `cancelled`, keeps completed work and
+charged scenes, and is a no-op once the run has finished. Both tools re-read the editor state and echo `expected_batch_run_id` +
 `expected_batch_status` with the REST command, so a phase change between poll and command
 is a safe 409 `batch_command_stale` (re-poll and retry) instead of acting on newer work;
 the REST endpoints reject editor commands that omit these fields with 409
@@ -281,7 +290,7 @@ If it returns `terminal:false`, the render is still going — call `wait_for_com
 `create_short` → optional `generate_hook_variations` (test hook angles free) / `generate_short_text` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
 `create_editor_ad` (free configure + quote) → obtain spend approval → `start_autopilot {slug, max_credits}` → `wait_for_completion {kind:"editor"}` → `download_result`.
 
-If waiting returns `stage:"batch_retry_required"`, call `retry_editor_batch` to continue the prepaid failed scene, or `cancel_editor_batch` to abandon the batch. Resolve that child batch before calling `start_autopilot` again; a retry does not itself authorize a new parent Autopilot run.
+If waiting returns `stage:"batch_retry_required"`, call `retry_editor_batch` to continue the prepaid failed scene (optionally repairing its prompt first with `set_segment_prompt` — see the batch-state notes above), or `cancel_editor_batch` to abandon the batch. Resolve that child batch before calling `start_autopilot` again; a retry does not itself authorize a new parent Autopilot run. To halt a **running** Autopilot run outright, call `cancel_autopilot`.
 
 **Iterate a short for free (never re-roll):** the first `generate_short` (15 credits) buys the footage +
 music; after that, every text/style/CTA/end-card/logo tweak re-renders over them for **0 credits** —

package/dist/index.js

@@ -29508,6 +29508,15 @@ function normalizeStatus(kind, slug, data) {
       status.failure_source = d.failure_source;
     if (typeof d.failure_attempt === "number")
       status.failure_attempt = d.failure_attempt;
+    if (typeof d.generation_attempt === "number")
+      status.generation_attempt = d.generation_attempt;
+    if (typeof d.segments_completed === "number")
+      status.segments_completed = d.segments_completed;
+    if (typeof d.segments_total === "number")
+      status.segments_total = d.segments_total;
+    if (Array.isArray(d.active_segment_positions) && d.active_segment_positions.every((position) => typeof position === "number")) {
+      status.active_segment_positions = d.active_segment_positions;
+    }
     if (typeof d.latest_render_free === "boolean") {
       status.latest_render_free = d.latest_render_free;
     }
@@ -30257,7 +30266,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.12.0",
+  version: "0.14.0",
   description: "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   license: "MIT",
   author: "Monocursive <contact@monocursive.com>",
@@ -30575,6 +30584,10 @@ var getStatusOutput = exports_external.object({
   failure_details: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe("Short only: structured provider/QC details for recovery."),
   failure_source: exports_external.string().optional().describe("Short only: worker/recovery layer that finalized the failure."),
   failure_attempt: exports_external.number().optional().describe("Short only: paid generation attempt number that failed."),
+  generation_attempt: exports_external.number().optional().describe("Short only: current paid attempt; echo when cancelling."),
+  segments_completed: exports_external.number().optional(),
+  segments_total: exports_external.number().optional(),
+  active_segment_positions: exports_external.array(exports_external.number()).optional(),
   latest_render_free: exports_external.boolean().optional(),
   last_free_rerender_failed: exports_external.boolean().optional()
 }).passthrough();
@@ -30594,6 +30607,10 @@ var waitForCompletionOutput = exports_external.object({
   failure_details: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe("Short only: structured provider/QC details for recovery."),
   failure_source: exports_external.string().optional().describe("Short only: worker/recovery layer that finalized the failure."),
   failure_attempt: exports_external.number().optional().describe("Short only: paid generation attempt number that failed."),
+  generation_attempt: exports_external.number().optional().describe("Short only: current paid attempt; echo when cancelling."),
+  segments_completed: exports_external.number().optional(),
+  segments_total: exports_external.number().optional(),
+  active_segment_positions: exports_external.array(exports_external.number()).optional(),
   latest_render_free: exports_external.boolean().optional(),
   last_free_rerender_failed: exports_external.boolean().optional(),
   saved_to: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
@@ -31798,6 +31815,23 @@ var VISUAL_LANGUAGES = [
   "startup_explainer",
   "luxury_minimal"
 ];
+var SCENARIO_THEMES = [
+  "none",
+  "realistic",
+  "cinematic",
+  "anime",
+  "sci_fi",
+  "fantasy",
+  "noir",
+  "superhero",
+  "horror",
+  "mockumentary",
+  "sports",
+  "gaming",
+  "retro_80s",
+  "minimalist",
+  "cyberpunk"
+];
 var LANGUAGES = [
   "en",
   "fr",
@@ -31924,7 +31958,7 @@ registerTool("make_video", {
     music_instruments: exports_external.array(exports_external.string()).optional().describe('SHORTS only: instrument hints woven into the music (≤10, each ≤40 chars), e.g. ["piano", "strings"]'),
     creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("SHORTS + EDITOR: narrative arc / segment structure. Omit for Auto/generic."),
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("SHORTS + EDITOR: visual style direction and render look. Default app choice is kinetic_creator."),
-    theme: exports_external.string().optional().describe("Visual theme: editor genre overlay, and legacy shorts fallback only when visual_language is unset. " + "For editor, when visual_language is set it drives the look and 'none' is ignored. " + "none (literal — no imposed style), realistic (default), cinematic, " + "anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " + "minimalist, cyberpunk"),
+    theme: exports_external.enum(SCENARIO_THEMES).optional().describe("Visual theme: editor genre overlay, and legacy shorts fallback only when visual_language is unset. " + "For editor, visual_language drives the look when present; make_video defaults theme to none " + "(literal — no imposed genre style). Options: none, realistic, cinematic, " + "anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " + "minimalist, cyberpunk"),
     save_path: exports_external.string().optional().describe("Optional .mp4 path to download to (confined to HUBFLUENCER_OUTPUT_DIR or cwd)"),
     max_wait_seconds: exports_external.number().optional().describe("Block budget seconds (default 240, capped 10–280)"),
     dry_run: exports_external.boolean().optional().describe("Preview only: create a free draft, price it, and STOP before spending credits. " + "Returns {estimated_credits, available_credits, slug}. Resume with generate_short / start_autopilot."),
@@ -32003,8 +32037,8 @@ registerTool("make_video", {
       voice_id: args.voice_id,
       creative_format: args.creative_format,
       visual_language: args.visual_language,
-      theme: args.theme
-    }, makeVideoEditorCreateKey(args));
+      theme: args.theme ?? "none"
+    }, makeVideoEditorCreateKey({ ...args, theme: args.theme ?? "none" }));
     slug = created.data.slug;
   }
   const costPath = kind === "short" ? `/shorts/${slug}/cost` : `/editor/${slug}/autopilot/cost`;
@@ -32109,7 +32143,30 @@ registerTool("list_voices", {
   description: "Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " + "make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
   inputSchema: {},
   annotations: { title: "List voices", ...RO }
-}, tool(async (_args, client) => ok(await client.get("/voices"))));
+}, tool(async (_args, client) => {
+  const response = asRecord(await client.get("/voices"));
+  const data = asRecord(response.data ?? response);
+  const voices = Array.isArray(data.voices) ? data.voices.map(asRecord) : [];
+  return ok({
+    voices: voices.map((voice) => {
+      const verified = Array.isArray(voice.verified_languages) ? voice.verified_languages.map(asRecord) : [];
+      return {
+        voice_id: voice.voice_id,
+        name: voice.name,
+        category: voice.category,
+        description: voice.description,
+        labels: voice.labels,
+        preview_url: voice.preview_url,
+        languages: [
+          ...new Set(verified.map((language) => language.language).filter((language) => typeof language === "string"))
+        ]
+      };
+    }),
+    has_more: data.has_more,
+    total_count: data.total_count,
+    next_page_token: data.next_page_token
+  });
+}));
 registerTool("list_projects", {
   title: "List recent projects",
   description: "Lists the caller's recent shorts and editor/video-factory projects, each normalized to " + "{slug, stage, terminal, ready, video_url}. By default the shorts listing is limited to " + "in-progress/failed; pass include_completed:true to also surface finished shorts — useful to " + "recover a lost slug. Capped to the most recent items per kind (use get_status for authoritative state).",
@@ -32155,7 +32212,7 @@ registerTool("create_short", {
     subheadline: exports_external.string().max(200).optional().describe("The SECONDARY title / supporting line under the headline. ≤200 chars."),
     creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("Optional structure: problem_solution, mistake_fix, myth_vs_reality, before_after, proof_demo, product_reveal. Omit for Auto."),
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Visual language for Veo direction and render styling. Good default: kinetic_creator."),
-    theme: exports_external.string().optional().describe("Deprecated for shorts: legacy visual theme used only when visual_language is unset."),
+    theme: exports_external.enum(SCENARIO_THEMES).optional().describe("Deprecated for shorts: legacy visual theme used only when visual_language is unset."),
     music_vibe: exports_external.string().optional().describe("Background-music mood. Recognized: Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz."),
     music_instruments: exports_external.array(exports_external.string().max(40)).max(10).optional().describe('Optional instrument hints (≤10, each ≤40 chars), e.g. ["piano", "strings"]'),
     text_position: exports_external.enum(["top", "center", "bottom"]).optional().describe("Where the title overlay sits (default bottom)"),
@@ -32253,7 +32310,7 @@ registerTool("update_short", {
     subheadline: exports_external.string().max(200).optional().describe("Secondary title / supporting line. ≤200 chars."),
     creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("Structure: problem_solution, mistake_fix, myth_vs_reality, before_after, proof_demo, product_reveal."),
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Visual language for Veo direction and render styling."),
-    theme: exports_external.string().optional().describe("Deprecated for shorts: legacy visual theme used only when visual_language is unset."),
+    theme: exports_external.enum(SCENARIO_THEMES).optional().describe("Deprecated for shorts: legacy visual theme used only when visual_language is unset."),
     music_vibe: exports_external.string().optional().describe("Background-music mood: Upbeat, Cinematic, Minimal, Luxury, Playful, Jazz."),
     music_instruments: exports_external.array(exports_external.string().max(40)).max(10).optional().describe('Instrument hints (≤10, each ≤40 chars), e.g. ["piano", "strings"]'),
     text_position: exports_external.enum(["top", "center", "bottom"]).optional().describe("Where the title overlay sits."),
@@ -32348,7 +32405,13 @@ registerTool("update_short", {
   const res = await client.patch(`/shorts/${args.slug}`, body);
   const data = asRecord(res).data ?? res;
   return ok({
-    ...asRecord(data),
+    slug: args.slug,
+    kind: "short",
+    stage: asRecord(data).stage,
+    status: asRecord(data).status,
+    updated: body,
+    end_card_mode: asRecord(data).end_card_mode,
+    resolved_cta_text: asRecord(data).resolved_cta_text,
     next: "Saved. Only text/style/CTA/end-card/logo changed on an already-generated short? " + `rerender_short({ slug: "${args.slug}" }) applies it for 0 credits. Footage/music edits ` + "(prompt, product image, format, visual_language, theme, music_*, language) need " + "generate_short (15 credits)."
   });
 }));
@@ -32516,6 +32579,31 @@ registerTool("generate_short", {
     throw e;
   }
 }));
+registerTool("cancel_short_generation", {
+  title: "Cancel a running short generation",
+  description: "Stops the caller-observed paid Short attempt, fences late provider callbacks, and refunds the 15-credit " + "generation exactly once. Pass generation_attempt from get_status so a delayed command cannot cancel a " + "newer run on the same draft. The draft is preserved for editing and regeneration. Safe to repeat with " + "the same attempt after a successful cancellation. Scope: video:generate.",
+  inputSchema: {
+    slug: exports_external.string().describe("Slug of the processing short"),
+    generation_attempt: exports_external.number().int().min(0).describe("generation_attempt from the latest get_status response")
+  },
+  annotations: {
+    title: "Cancel short generation",
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    idempotentHint: true
+  }
+}, tool(async (args, client) => {
+  const res = await client.post(`/shorts/${args.slug}/cancel`, { generation_attempt: args.generation_attempt }, undefined);
+  const data = asRecord(asRecord(res).data ?? res);
+  return ok({
+    ...data,
+    slug: args.slug,
+    charged: false,
+    refund: "refunded" in data ? data.refunded : "settled (idempotent — no new credits minted on repeat)",
+    next: "Edit the preserved draft, then call generate_short when ready."
+  });
+}));
 registerTool("rerender_short", {
   title: "Re-render a short (FREE — 0 credits)",
   description: "FREE re-render: applies the short's current text/style/CTA/end-card/logo state over the already-paid " + "footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks, or after a logo change " + "(set_short_logo, or short_logo_position/short_logo_treatment via update_short). Footage or music " + "changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " + "end_card) can shift the video between 12s and 14s; when the pinned music bed is shorter than the " + "export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " + "Requires a completed generation to re-render over " + "(422 short_not_ready otherwise — run generate_short once first); while any generation/render is in " + "flight it reports in-progress (409) rather than duplicating. Then poll with get_status or " + "wait_for_completion (kind=short). A failed free re-render leaves the delivered video intact — retry " + "rerender_short, it stays free (the status fields latest_render_free / last_free_rerender_failed " + "report this when the server sends them).",
@@ -32767,7 +32855,7 @@ registerTool("create_editor_ad", {
     language: exports_external.enum(LANGUAGES).optional().describe('Language (default "en"). Bare ISO-639-1 code only — no region/script subtag (use "es", not "es-MX"). ' + "Drives the WHOLE video: scenario, narration script, narration voice, and captions. " + "Ask the user / infer from their locale."),
     creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("Narrative arc / segment structure. Omit for Auto/generic."),
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored."),
-    theme: exports_external.string().optional().describe('Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
+    theme: exports_external.enum(SCENARIO_THEMES).optional().describe('Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id (see list_voices); omit for the default voice"),
     export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")'),
     product_image_path: exports_external.string().optional().describe("Local product image (.jpg/.jpeg/.png, ≤8 MiB) used as the product-identity reference for every generated Editor scene and linked as the exact closing image unless one was already authored."),
@@ -32818,11 +32906,12 @@ registerTool("create_editor_ad", {
       project_intent: args.project_intent,
       creative_format: args.creative_format,
       visual_language: args.visual_language,
-      theme: args.theme,
+      theme: args.theme ?? "none",
       voice_id: args.voice_id,
       export_aspect_ratio: args.export_aspect_ratio
     }, editorAdCreateKey({
       ...args,
+      theme: args.theme ?? "none",
       product_image_identity: productImage ? preparedUploadIdentity(productImage) : undefined,
       closing_image_identity: closingImage ? preparedUploadIdentity(closingImage) : undefined,
       logo_identity: logo ? preparedUploadIdentity(logo) : undefined
@@ -32946,7 +33035,7 @@ registerTool("start_autopilot", {
 }));
 registerTool("retry_editor_batch", {
   title: "Retry a paused editor batch",
-  description: "Recovers an editor whose normalized status is batch_retry_required by atomically re-queueing the failed " + "scene and resuming its prepaid batch. This spends 0 additional credits: the batch generation was already " + "paid. It does not authorize or restart a failed parent Autopilot run; after retrying, wait for the batch " + "to settle. If the parent is then terminal, call start_autopilot without max_credits for a fresh quote and " + "relaunch only with an approved cap. A batch parked on " + "insufficient_credits needs a top-up/scope change instead. Scope: video:generate.",
+  description: "Recovers an editor whose normalized status is batch_retry_required by atomically re-queueing the failed " + "scene and resuming its prepaid batch. This spends 0 additional credits: the batch generation was already " + "paid. Before retrying you may REPAIR the one failed scene: while paused_for_retry, set_segment_prompt can " + "edit that scene's prompt (and use_previous_frame) — but only for the exact failed position the server " + "names in batch_generation_failed_position (from get_editor); the rest of the paused batch stays " + "mutation-locked. Explicit paused retries are capped — once the failure code is free_retries_exhausted a " + "further retry is rejected (start a fresh run instead). It does not authorize or restart a failed parent " + "Autopilot run; after retrying, wait for the batch " + "to settle. If the parent is then terminal, call start_autopilot without max_credits for a fresh quote and " + "relaunch only with an approved cap. A batch parked on " + "insufficient_credits needs a top-up/scope change instead. Scope: video:generate.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: {
     title: "Retry editor batch",
@@ -33031,7 +33120,7 @@ registerTool("create_editor_draft", {
     language: exports_external.enum(LANGUAGES).optional().describe('Language code, e.g. "en" (default). Bare ISO-639-1 code only — no region/script subtag like ' + '"en-US". Drives scenario, narration, voice, and captions.'),
     creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("Narrative arc / segment structure. Omit for Auto/generic."),
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored."),
-    theme: exports_external.string().optional().describe('Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
+    theme: exports_external.enum(SCENARIO_THEMES).optional().describe('Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
     voice_id: exports_external.string().regex(/^[A-Za-z0-9_-]+$/).max(64).optional().describe("Preferred narration voice id (see list_voices); ≤64 chars, [A-Za-z0-9_-] only"),
     export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")'),
     project_intent: exports_external.enum(["social_ad", "creative_story"]).optional().describe("social_ad for promotional/ad content (product focus + CTA), creative_story for brand " + "narratives (default).")
@@ -33049,14 +33138,14 @@ registerTool("create_editor_draft", {
     product_subject: args.product_subject,
     creative_format: args.creative_format,
     visual_language: args.visual_language,
-    theme: args.theme,
+    theme: args.theme ?? "none",
     voice_id: args.voice_id,
     export_aspect_ratio: args.export_aspect_ratio,
     project_intent: args.project_intent
   };
   if (prompt)
     body.product_prompt = prompt;
-  const created = await client.post("/editor", body, idemKey("create-editor-draft", prompt ?? "", args.product_subject ?? "", args.project_intent ?? "", args.language ?? "en", args.creative_format ?? "", args.visual_language ?? "", args.theme ?? "", args.voice_id ?? "", args.export_aspect_ratio ?? ""));
+  const created = await client.post("/editor", body, idemKey("create-editor-draft", prompt ?? "", args.product_subject ?? "", args.project_intent ?? "", args.language ?? "en", args.creative_format ?? "", args.visual_language ?? "", args.theme ?? "none", args.voice_id ?? "", args.export_aspect_ratio ?? ""));
   return ok({
     slug: created.data.slug,
     kind: "editor",
@@ -33080,6 +33169,7 @@ function conciseEditorState(value) {
     "scenario_prompt",
     "batch_generation_status",
     "batch_generation_run_id",
+    "batch_generation_failed_position",
     "auto_render_after_batch",
     "narration_status",
     "narration_script",
@@ -33104,6 +33194,7 @@ function conciseEditorState(value) {
     prompt: segment.prompt,
     status: segment.status,
     source_type: segment.source_type,
+    generation_claim_token: segment.generation_claim_token,
     use_previous_frame: segment.use_previous_frame,
     video_stale: segment.video_stale,
     error_code: segment.error_code,
@@ -33145,7 +33236,7 @@ registerTool("generate_scenario", {
     segments_count: exports_external.number().int().min(3).max(10).optional().describe("How many scenes (3–10, server default 5)"),
     creative_format: exports_external.union([exports_external.enum(CREATIVE_FORMATS), exports_external.literal("")]).optional().describe("Persist the narrative arc / segment structure before generating. Omit to leave it unchanged; pass an empty string to clear."),
     visual_language: exports_external.union([exports_external.enum(VISUAL_LANGUAGES), exports_external.literal("")]).optional().describe("Persist the visual style / render look before generating. Omit to leave it unchanged; pass an empty string to clear. When set it drives the look and a theme of 'none' is ignored."),
-    theme: exports_external.string().optional().describe("Persist the genre overlay / theme before generating (e.g. realistic, cinematic, anime, none)."),
+    theme: exports_external.enum(SCENARIO_THEMES).optional().describe("Persist the genre overlay / theme before generating (e.g. realistic, cinematic, anime, none)."),
     auto_unlock: exports_external.boolean().optional().describe("On 429, spend 1 credit to unlock +10 assists and retry once (default false)")
   },
   annotations: {
@@ -33300,6 +33391,50 @@ registerTool("generate_segment", {
   const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/generate`, undefined, undefined);
   return ok(asRecord(res).data ?? res);
 }));
+registerTool("cancel_segment_generation", {
+  title: "Cancel one editor scene generation",
+  description: "Stops one caller-observed, individually processing Editor scene; its generation_claim_token fence " + "prevents a delayed command from cancelling a newer attempt. The token is returned by get_editor. " + "Refunds that scene's charge idempotently (a free retry creates no refund). Use cancel_editor_batch or " + "cancel_autopilot for workflow-owned scenes. After cancellation, edit the prompt if needed and call " + "generate_segment again. Scope: video:generate.",
+  inputSchema: {
+    slug: exports_external.string().describe("Editor project slug"),
+    segment_id: exports_external.union([exports_external.number(), exports_external.string()]).describe("Processing segment id (from get_editor)"),
+    generation_claim_token: exports_external.string().nullable().describe("generation_claim_token from that processing segment")
+  },
+  annotations: {
+    title: "Cancel segment generation",
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    idempotentHint: true
+  }
+}, tool(async (args, client) => {
+  const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/cancel`, { expected_generation_claim_token: args.generation_claim_token }, undefined);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    slug: args.slug,
+    charged: false,
+    next: "set_segment_prompt or generate_segment"
+  });
+}));
+registerTool("cancel_autopilot", {
+  title: "Cancel a running Autopilot run",
+  description: "Stops an in-flight Autopilot run on an editor project: sets autopilot_status to cancelled so the " + "orchestration chain (scenario → scenes → narration → voice → music → render) advances no further. Use " + "this when Autopilot is still running and you want to halt it. Any scenes already charged stay charged and " + "all completed work (generated scenes, voice, music, a finished render) is kept — a step already enqueued " + "may still finish, but nothing new is started. Idempotent: a no-op that returns the project unchanged when " + "Autopilot is not running (already completed, failed, cancelled, or never launched), so it is safe to " + "repeat. It does NOT itself refund or re-run anything. For a non-Autopilot prepaid batch " + "(batch_generation_status preparing / paused_for_retry) use cancel_editor_batch; to stop one " + "individually-generated scene use cancel_segment_generation. Scope: video:generate.",
+  inputSchema: { slug: exports_external.string().describe("Editor project slug") },
+  annotations: {
+    title: "Cancel autopilot",
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    idempotentHint: true
+  }
+}, tool(async (args, client) => {
+  const res = await client.post(`/editor/${args.slug}/autopilot/cancel`, undefined, undefined);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    slug: args.slug,
+    charged: false,
+    next: "get_status"
+  });
+}));
 registerTool("regenerate_segment", {
   title: "Regenerate a completed segment (new version, 4 credits)",
   description: "Re-rolls a COMPLETED scene as a NEW VERSION of that segment — the previous version is kept (switch back " + "in the app). Costs 4 credits. Use generate_segment for pending/failed scenes; use THIS for a completed " + "scene you want different — optionally with a new prompt (omit it to re-roll the current prompt). The new " + "version starts rendering immediately; watch it with get_editor (status processing → completed|failed). " + "KNOWN LIMITATION: scenes chain visual continuity off the previous scene's last frame, so regenerating a " + "MID-TIMELINE scene can degrade the transition into the FOLLOWING scene (it was seeded from the old " + "version's last frame). A scene still processing returns editor_segment_busy (no double charge); 402 " + "credits_insufficient fails cleanly.",
@@ -33322,7 +33457,7 @@ registerTool("regenerate_segment", {
 }));
 registerTool("generate_all_segments", {
   title: "Generate all pending segments (sequential)",
-  description: "Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting" + "the next (preserves visual continuity). Each AI-generated scene is a fixed 8 seconds, so N scenes ≈ N×8s of footage. Costs 5 credits per segment generated. Stops and reports what " + "completed if a scene errors on submit (e.g. 402 credits_insufficient) or fails while rendering; if a " + "scene is still rendering past the budget it returns timed_out so you can re-run to continue (completed " + "scenes are skipped). The whole call is capped at ~280s: on a project with many scenes it processes as " + "many as fit, returns timed_out, and you re-run to continue (it picks up the remaining pending scenes). " + "Tip: to generate everything at lowest cost, skip this and just call render — it auto-generates any ungenerated scenes at the batch rate (4 credits/scene for ≥3); use this tool when you want to review or stop per scene. May take several minutes.",
+  description: "Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting " + "the next (preserves visual continuity). Each AI-generated scene is a fixed 8 seconds, so N scenes ≈ N×8s of footage. Costs 5 credits per segment generated. Stops and reports what " + "completed if a scene errors on submit (e.g. 402 credits_insufficient) or fails while rendering; if a " + "scene is still rendering past the budget it returns timed_out so you can re-run to continue (completed " + "scenes are skipped). The whole call is capped at ~280s: on a project with many scenes it processes as " + "many as fit, returns timed_out, and you re-run to continue (it picks up the remaining pending scenes). " + "Tip: to generate everything at lowest cost, skip this and just call render — it auto-generates any ungenerated scenes at the batch rate (4 credits/scene for ≥3); use this tool when you want to review or stop per scene. May take several minutes.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: {
     title: "Generate all segments",
@@ -33500,7 +33635,7 @@ registerTool("generate_music", {
     mood: exports_external.string().optional().describe("Optional mood hint"),
     genre: exports_external.string().optional().describe("Optional genre hint"),
     tempo: exports_external.string().optional().describe("Optional tempo hint"),
-    instruments: exports_external.string().optional().describe("Optional instruments hint")
+    instruments: exports_external.array(exports_external.string().min(1).max(80)).max(10).optional().describe('Optional instrument hints, e.g. ["piano", "strings"]')
   },
   annotations: { title: "Generate music", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
@@ -33523,7 +33658,7 @@ registerTool("generate_music", {
 }));
 registerTool("render", {
   title: "Render the final editor video (0 credits)",
-  description: "Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " + "segments are auto-charged at generation cost first). Render NEVER generates or charges for voice/music; a new " + "music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " + 'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' + "STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
+  description: "Renders the final MP4 from the generated segments + voice + music. Costs 0 credits. Pending or previously " + "failed AI scenes are generated first and charged as a new batch. Render NEVER generates or charges for voice/music; a new " + "music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " + 'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' + "STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: { title: "Render", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
@@ -33763,7 +33898,7 @@ registerTool("use_asset_for_segment", {
 }));
 registerTool("set_product", {
   title: "Attach a product image (from a local file)",
-  description: "Uploads a local product image and attaches it to the project as the product. Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " + "in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " + "is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary.",
+  description: "Uploads a local product image and attaches it to the project as the product. Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " + "in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " + "is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary. " + "WARNING: replacing the product photo on a project that already has generated AI scenes invalidates their product " + "identity — those scenes were built from the old photo and must be regenerated to match the new one.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     file_path: exports_external.string().describe("Local product image path (.jpg/.jpeg/.png)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   "license": "MIT",
   "author": "Monocursive <contact@monocursive.com>",

package/src/core.ts

@@ -275,6 +275,14 @@ export interface NormalizedStatus {
 	failure_source?: string;
 	/** Short only: paid generation attempt number that failed. */
 	failure_attempt?: number;
+	/** Short only: current paid attempt; echo when cancelling. */
+	generation_attempt?: number;
+	/** Short only: completed/current Veo clip count for useful long-poll progress. */
+	segments_completed?: number;
+	/** Short only: total current Veo clips in the paid attempt. */
+	segments_total?: number;
+	/** Short only: clip positions that are pending or processing. */
+	active_segment_positions?: number[];
 	/** Editor only: the newest delivered render no longer matches the live project. */
 	stale?: boolean;
 	/** Editor only: current scene ids that are still generating. */
@@ -361,6 +369,20 @@ export function normalizeStatus(
 			status.failure_source = d.failure_source;
 		if (typeof d.failure_attempt === "number")
 			status.failure_attempt = d.failure_attempt;
+		if (typeof d.generation_attempt === "number")
+			status.generation_attempt = d.generation_attempt;
+		if (typeof d.segments_completed === "number")
+			status.segments_completed = d.segments_completed;
+		if (typeof d.segments_total === "number")
+			status.segments_total = d.segments_total;
+		if (
+			Array.isArray(d.active_segment_positions) &&
+			d.active_segment_positions.every(
+				(position) => typeof position === "number",
+			)
+		) {
+			status.active_segment_positions = d.active_segment_positions as number[];
+		}
 		// Additive free-re-render bookkeeping (2026-07 API): surfaced only when
 		// the server actually sends the booleans, so older payloads normalize
 		// byte-identically. A failed free re-render does NOT flip stage to

package/src/index.ts

@@ -565,6 +565,25 @@ const VISUAL_LANGUAGES = [
 	"startup_explainer",
 	"luxury_minimal",
 ] as const;
+// Closed API enum from VideoFactories.ScenarioThemes. Keeping this explicit in
+// MCP prevents an agent typo from spending a round trip on an avoidable 422.
+const SCENARIO_THEMES = [
+	"none",
+	"realistic",
+	"cinematic",
+	"anime",
+	"sci_fi",
+	"fantasy",
+	"noir",
+	"superhero",
+	"horror",
+	"mockumentary",
+	"sports",
+	"gaming",
+	"retro_80s",
+	"minimalist",
+	"cyberpunk",
+] as const;
 // The languages the API's VideoFactory.language accepts (video_factory.ex
 // @supported_languages, validate_inclusion at create + autopilot). It's a CLOSED
 // set of bare ISO-639-1 codes — the server rejects region/script subtags ("en",
@@ -914,12 +933,12 @@ registerTool(
 					"SHORTS + EDITOR: visual style direction and render look. Default app choice is kinetic_creator.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Visual theme: editor genre overlay, and legacy shorts fallback only when visual_language is unset. " +
-						"For editor, when visual_language is set it drives the look and 'none' is ignored. " +
-						"none (literal — no imposed style), realistic (default), cinematic, " +
+						"For editor, visual_language drives the look when present; make_video defaults theme to none " +
+						"(literal — no imposed genre style). Options: none, realistic, cinematic, " +
 						"anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " +
 						"minimalist, cyberpunk",
 				),
@@ -1115,12 +1134,14 @@ registerTool(
 						voice_id: args.voice_id,
 						creative_format: args.creative_format,
 						visual_language: args.visual_language,
-						theme: args.theme,
+						// Prompt-first default: do not silently inject the API's legacy
+						// realistic/neutral art direction when the caller authored a look.
+						theme: args.theme ?? "none",
 					},
 					// Fold every create-affecting param into the key so two calls that
 					// differ only by style/theme/voice/aspect get distinct drafts (shared
 					// with the golden-pin test via core.ts).
-					makeVideoEditorCreateKey(args),
+					makeVideoEditorCreateKey({ ...args, theme: args.theme ?? "none" }),
 				);
 				slug = created.data.slug;
 			}
@@ -1396,7 +1417,40 @@ registerTool(
 		inputSchema: {},
 		annotations: { title: "List voices", ...RO },
 	},
-	tool(async (_args, client) => ok(await client.get("/voices"))),
+	tool(async (_args, client) => {
+		const response = asRecord(await client.get("/voices"));
+		const data = asRecord(response.data ?? response);
+		const voices = Array.isArray(data.voices) ? data.voices.map(asRecord) : [];
+
+		return ok({
+			voices: voices.map((voice) => {
+				const verified = Array.isArray(voice.verified_languages)
+					? voice.verified_languages.map(asRecord)
+					: [];
+				return {
+					voice_id: voice.voice_id,
+					name: voice.name,
+					category: voice.category,
+					description: voice.description,
+					labels: voice.labels,
+					preview_url: voice.preview_url,
+					languages: [
+						...new Set(
+							verified
+								.map((language) => language.language)
+								.filter(
+									(language): language is string =>
+										typeof language === "string",
+								),
+						),
+					],
+				};
+			}),
+			has_more: data.has_more,
+			total_count: data.total_count,
+			next_page_token: data.next_page_token,
+		});
+	}),
 );
 
 // ── Projects ──────────────────────────────────────────────────────────────
@@ -1530,7 +1584,7 @@ registerTool(
 					"Visual language for Veo direction and render styling. Good default: kinetic_creator.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Deprecated for shorts: legacy visual theme used only when visual_language is unset.",
@@ -1837,7 +1891,7 @@ registerTool(
 				.optional()
 				.describe("Visual language for Veo direction and render styling."),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Deprecated for shorts: legacy visual theme used only when visual_language is unset.",
@@ -2092,7 +2146,13 @@ registerTool(
 			);
 			const data = asRecord(res).data ?? res;
 			return ok({
-				...asRecord(data),
+				slug: args.slug,
+				kind: "short",
+				stage: asRecord(data).stage,
+				status: asRecord(data).status,
+				updated: body,
+				end_card_mode: asRecord(data).end_card_mode,
+				resolved_cta_text: asRecord(data).resolved_cta_text,
 				next:
 					"Saved. Only text/style/CTA/end-card/logo changed on an already-generated short? " +
 					`rerender_short({ slug: "${args.slug}" }) applies it for 0 credits. Footage/music edits ` +
@@ -2529,6 +2589,55 @@ registerTool(
 	}),
 );
 
+registerTool(
+	"cancel_short_generation",
+	{
+		title: "Cancel a running short generation",
+		description:
+			"Stops the caller-observed paid Short attempt, fences late provider callbacks, and refunds the 15-credit " +
+			"generation exactly once. Pass generation_attempt from get_status so a delayed command cannot cancel a " +
+			"newer run on the same draft. The draft is preserved for editing and regeneration. Safe to repeat with " +
+			"the same attempt after a successful cancellation. Scope: video:generate.",
+		inputSchema: {
+			slug: z.string().describe("Slug of the processing short"),
+			generation_attempt: z
+				.number()
+				.int()
+				.min(0)
+				.describe("generation_attempt from the latest get_status response"),
+		},
+		annotations: {
+			title: "Cancel short generation",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { slug: string; generation_attempt: number }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/shorts/${args.slug}/cancel`,
+			{ generation_attempt: args.generation_attempt },
+			undefined,
+		);
+		const data = asRecord(asRecord(res).data ?? res);
+		return ok({
+			...data,
+			slug: args.slug,
+			charged: false,
+			// The cancel endpoint returns the short's STATE, not a refund receipt,
+			// so don't assert refunded:true on every call — a repeat cancel is a
+			// no-op that mints no new credits. Echo the server's own flag if it ever
+			// sends one; otherwise describe the honest idempotent settlement.
+			refund:
+				"refunded" in data
+					? data.refunded
+					: "settled (idempotent — no new credits minted on repeat)",
+			next: "Edit the preserved draft, then call generate_short when ready.",
+		});
+	}),
+);
+
 registerTool(
 	"rerender_short",
 	{
@@ -3066,10 +3175,10 @@ registerTool(
 					"Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
-					'Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
+					'Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
 				),
 			voice_id: z
 				.string()
@@ -3226,7 +3335,7 @@ registerTool(
 						project_intent: args.project_intent,
 						creative_format: args.creative_format,
 						visual_language: args.visual_language,
-						theme: args.theme,
+						theme: args.theme ?? "none",
 						voice_id: args.voice_id,
 						export_aspect_ratio: args.export_aspect_ratio,
 					},
@@ -3235,6 +3344,7 @@ registerTool(
 					// Composition lives in core.ts, shared with the golden-pin test.
 					editorAdCreateKey({
 						...args,
+						theme: args.theme ?? "none",
 						product_image_identity: productImage
 							? preparedUploadIdentity(productImage)
 							: undefined,
@@ -3507,7 +3617,12 @@ registerTool(
 		description:
 			"Recovers an editor whose normalized status is batch_retry_required by atomically re-queueing the failed " +
 			"scene and resuming its prepaid batch. This spends 0 additional credits: the batch generation was already " +
-			"paid. It does not authorize or restart a failed parent Autopilot run; after retrying, wait for the batch " +
+			"paid. Before retrying you may REPAIR the one failed scene: while paused_for_retry, set_segment_prompt can " +
+			"edit that scene's prompt (and use_previous_frame) — but only for the exact failed position the server " +
+			"names in batch_generation_failed_position (from get_editor); the rest of the paused batch stays " +
+			"mutation-locked. Explicit paused retries are capped — once the failure code is free_retries_exhausted a " +
+			"further retry is rejected (start a fresh run instead). It does not authorize or restart a failed parent " +
+			"Autopilot run; after retrying, wait for the batch " +
 			"to settle. If the parent is then terminal, call start_autopilot without max_credits for a fresh quote and " +
 			"relaunch only with an approved cap. A batch parked on " +
 			"insufficient_credits needs a top-up/scope change instead. Scope: video:generate.",
@@ -3713,10 +3828,10 @@ registerTool(
 					"Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
-					'Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
+					'Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
 				),
 			voice_id: z
 				.string()
@@ -3766,7 +3881,7 @@ registerTool(
 				product_subject: args.product_subject,
 				creative_format: args.creative_format,
 				visual_language: args.visual_language,
-				theme: args.theme,
+				theme: args.theme ?? "none",
 				voice_id: args.voice_id,
 				export_aspect_ratio: args.export_aspect_ratio,
 				project_intent: args.project_intent,
@@ -3786,7 +3901,7 @@ registerTool(
 					args.language ?? "en",
 					args.creative_format ?? "",
 					args.visual_language ?? "",
-					args.theme ?? "",
+					args.theme ?? "none",
 					args.voice_id ?? "",
 					args.export_aspect_ratio ?? "",
 				),
@@ -3817,6 +3932,7 @@ function conciseEditorState(value: unknown): Record<string, unknown> {
 		"scenario_prompt",
 		"batch_generation_status",
 		"batch_generation_run_id",
+		"batch_generation_failed_position",
 		"auto_render_after_batch",
 		"narration_status",
 		"narration_script",
@@ -3841,6 +3957,7 @@ function conciseEditorState(value: unknown): Record<string, unknown> {
 				prompt: segment.prompt,
 				status: segment.status,
 				source_type: segment.source_type,
+				generation_claim_token: segment.generation_claim_token,
 				use_previous_frame: segment.use_previous_frame,
 				video_stale: segment.video_stale,
 				error_code: segment.error_code,
@@ -3938,7 +4055,7 @@ registerTool(
 					"Persist the visual style / render look before generating. Omit to leave it unchanged; pass an empty string to clear. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Persist the genre overlay / theme before generating (e.g. realistic, cinematic, anime, none).",
@@ -4247,6 +4364,96 @@ registerTool(
 	}),
 );
 
+registerTool(
+	"cancel_segment_generation",
+	{
+		title: "Cancel one editor scene generation",
+		description:
+			"Stops one caller-observed, individually processing Editor scene; its generation_claim_token fence " +
+			"prevents a delayed command from cancelling a newer attempt. The token is returned by get_editor. " +
+			"Refunds that scene's charge idempotently (a free retry creates no refund). Use cancel_editor_batch or " +
+			"cancel_autopilot for workflow-owned scenes. After cancellation, edit the prompt if needed and call " +
+			"generate_segment again. Scope: video:generate.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Processing segment id (from get_editor)"),
+			generation_claim_token: z
+				.string()
+				.nullable()
+				.describe("generation_claim_token from that processing segment"),
+		},
+		annotations: {
+			title: "Cancel segment generation",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: true,
+		},
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				segment_id: number | string;
+				generation_claim_token: string | null;
+			},
+			client,
+		) => {
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/segments/${String(args.segment_id)}/cancel`,
+				{ expected_generation_claim_token: args.generation_claim_token },
+				undefined,
+			);
+			return ok({
+				...asRecord(asRecord(res).data ?? res),
+				slug: args.slug,
+				charged: false,
+				next: "set_segment_prompt or generate_segment",
+			});
+		},
+	),
+);
+
+registerTool(
+	"cancel_autopilot",
+	{
+		title: "Cancel a running Autopilot run",
+		description:
+			"Stops an in-flight Autopilot run on an editor project: sets autopilot_status to cancelled so the " +
+			"orchestration chain (scenario → scenes → narration → voice → music → render) advances no further. Use " +
+			"this when Autopilot is still running and you want to halt it. Any scenes already charged stay charged and " +
+			"all completed work (generated scenes, voice, music, a finished render) is kept — a step already enqueued " +
+			"may still finish, but nothing new is started. Idempotent: a no-op that returns the project unchanged when " +
+			"Autopilot is not running (already completed, failed, cancelled, or never launched), so it is safe to " +
+			"repeat. It does NOT itself refund or re-run anything. For a non-Autopilot prepaid batch " +
+			"(batch_generation_status preparing / paused_for_retry) use cancel_editor_batch; to stop one " +
+			"individually-generated scene use cancel_segment_generation. Scope: video:generate.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: {
+			title: "Cancel autopilot",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/autopilot/cancel`,
+			undefined,
+			undefined,
+		);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			slug: args.slug,
+			charged: false,
+			next: "get_status",
+		});
+	}),
+);
+
 registerTool(
 	"regenerate_segment",
 	{
@@ -4308,7 +4515,7 @@ registerTool(
 	{
 		title: "Generate all pending segments (sequential)",
 		description:
-			"Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting" +
+			"Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting " +
 			"the next (preserves visual continuity). Each AI-generated scene is a fixed 8 seconds, so N scenes ≈ N×8s of footage. Costs 5 credits per segment generated. Stops and reports what " +
 			"completed if a scene errors on submit (e.g. 402 credits_insufficient) or fails while rendering; if a " +
 			"scene is still rendering past the budget it returns timed_out so you can re-run to continue (completed " +
@@ -4610,7 +4817,11 @@ registerTool(
 			mood: z.string().optional().describe("Optional mood hint"),
 			genre: z.string().optional().describe("Optional genre hint"),
 			tempo: z.string().optional().describe("Optional tempo hint"),
-			instruments: z.string().optional().describe("Optional instruments hint"),
+			instruments: z
+				.array(z.string().min(1).max(80))
+				.max(10)
+				.optional()
+				.describe('Optional instrument hints, e.g. ["piano", "strings"]'),
 		},
 		annotations: { title: "Generate music", ...WRITE, idempotentHint: false },
 	},
@@ -4622,7 +4833,7 @@ registerTool(
 				mood?: string;
 				genre?: string;
 				tempo?: string;
-				instruments?: string;
+				instruments?: string[];
 			},
 			client,
 		) => {
@@ -4655,8 +4866,8 @@ registerTool(
 	{
 		title: "Render the final editor video (0 credits)",
 		description:
-			"Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " +
-			"segments are auto-charged at generation cost first). Render NEVER generates or charges for voice/music; a new " +
+			"Renders the final MP4 from the generated segments + voice + music. Costs 0 credits. Pending or previously " +
+			"failed AI scenes are generated first and charged as a new batch. Render NEVER generates or charges for voice/music; a new " +
 			"music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " +
 			'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' +
 			"STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
@@ -5160,7 +5371,9 @@ registerTool(
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
 			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " +
 			"in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " +
-			"is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary.",
+			"is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary. " +
+			"WARNING: replacing the product photo on a project that already has generated AI scenes invalidates their product " +
+			"identity — those scenes were built from the old photo and must be regenerated to match the new one.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			file_path: z

package/src/output-schemas.ts

@@ -91,6 +91,13 @@ export const getStatusOutput = z
 			.number()
 			.optional()
 			.describe("Short only: paid generation attempt number that failed."),
+		generation_attempt: z
+			.number()
+			.optional()
+			.describe("Short only: current paid attempt; echo when cancelling."),
+		segments_completed: z.number().optional(),
+		segments_total: z.number().optional(),
+		active_segment_positions: z.array(z.number()).optional(),
 		latest_render_free: z.boolean().optional(),
 		last_free_rerender_failed: z.boolean().optional(),
 	})
@@ -134,6 +141,13 @@ export const waitForCompletionOutput = z
 			.number()
 			.optional()
 			.describe("Short only: paid generation attempt number that failed."),
+		generation_attempt: z
+			.number()
+			.optional()
+			.describe("Short only: current paid attempt; echo when cancelling."),
+		segments_completed: z.number().optional(),
+		segments_total: z.number().optional(),
+		active_segment_positions: z.array(z.number()).optional(),
 		latest_render_free: z.boolean().optional(),
 		last_free_rerender_failed: z.boolean().optional(),
 		saved_to: z.union([z.string(), z.null()]).optional(),