@hubfluencer/mcp 0.11.0 → 0.13.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. For a mascot/hero product that must remain identical with no humans, pass `cast_mode:"product_only"` plus `product_image_path`. | **0** until capped launch |
+| `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 awaiting/running/paused editor batch. Destructive after scene dispatch: prepaid credits are not refunded (an awaiting-preview batch is refunded server-side). | **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** |
@@ -99,20 +101,21 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 
 | Tool | What it does | Cost |
 |---|---|---|
-| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme` / `cast_mode` (`product_only` needs `set_product` before generation; `presenter_led` needs a configured presenter). | **0** |
+| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme`; the prompt is the complete scene-content contract. | **0** |
 | `get_editor` | Full project state by default for compatibility; pass `response_format:"concise"` for a smaller review projection. | **0** |
 | `set_scenario` / `generate_scenario` | Write your own scenario (free) **or** AI-draft it. `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. | free / 1 assist |
 | `apply_scenario` | Compile the **ready** scenario into per-scene prompts on the timeline (`segments_count` 0 or 3..10; omitted uses the generated scenario count, then 5; AI scenes replaced, uploads preserved). Polls until applied (~2 min budget). | **0** |
 | `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 it. | free / 1 assist |
+| `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** |
-| `list_renders` | List every render version for an editor project (id, version, status, video_url, error) — find a failed render or recover a finished URL. | **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 |
 
@@ -130,8 +133,7 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `upload_video` | Upload a local clip into an editor project (presign → PUT, resumable multipart for large files → confirm → poll to ready) and, by default, add it to the timeline. An uploaded clip keeps its native duration. |
 | `add_segment_from_upload` | Append a **ready** upload to the timeline as a new scene. |
 | `use_asset_for_segment` | Set a specific scene's video from a ready upload **or** a completed scene in the same project (pass exactly one). Returns downstream continuity impact plus narration/voice/music staleness that must be resolved before render. |
-| `set_product` | Upload an editor product image (JPEG/PNG, ≤8 MiB) and attach it as the project product. |
-| `set_product_placement` | Set where the product appears on pending AI scenes: `throughout` or `end`. |
+| `set_product` | Upload an editor product image (JPEG/PNG, ≤8 MiB). Its pixels guide product identity in every generated AI scene and its confirmed description grounds scenario/narration. The exact photo is also linked as the closing image unless a separate closing image was authored. Small generated label text can still vary. |
 | `set_closing_image` | Set the ~2s end-card image (JPEG/PNG, ≤20 MiB; upload a file, or reuse the product image with `from_product:true`). |
 | `set_logo` | Upload a brand logo overlay (JPEG/PNG, ≤5 MiB; editor only; optional treatment/position/duration). |
 | `set_short_product` | Attach a product image (JPEG/PNG, ≤20 MiB) to a **short**. |
@@ -154,6 +156,31 @@ does not match the live timeline; regenerate the reported stale scenes/audio and
 An absent/`null` server `is_stale` is **unknown** (for example a legacy render), not proof that
 the render is current. Failure stages take precedence over active stages and are terminal.
 
+Editor state uses `narration_status` (`none | generating | ready | failed`),
+`current_audio`, and `current_music` (selected version status `pending | processing |
+completed | failed`). Batch state is `idle | preparing | awaiting_previews | running |
+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. 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
+`batch_command_required` (client >= 0.12 sends them automatically). For
+`paused_insufficient_credits`, top up or reduce scope and invoke generation/render again.
+
+For raw REST Autopilot calls, reuse one `Idempotency-Key` only for transport retries of the
+same logical launch. Mint a fresh key for a deliberate resume, restart, or changed cap; a
+successful response is replayed for 24 hours under the old key.
+
 ### Campaign engine — onboard a product, plan, and draft (the delegation surface)
 
 Everything here is **$0** (draft creates + planning against the free assist quota). Generation
@@ -263,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** —