@hubfluencer/mcp 0.15.0 → 0.16.0

package/README.md

@@ -85,8 +85,8 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `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 |
+| `create_editor_ad` | Create an editor project, attach optional local product/logo/closing assets, and return the live autopilot quote. Pass `segments_count` (3–10) as the exact structural target. 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`; `segments_count` (3–10) overrides an older brief and is reflected in the matching quote. 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** |
@@ -111,7 +111,7 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `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 |
+| `set_narration_script` / `generate_narration` | Write the exact words to read aloud (free)—never pass a production prompt, camera directions, or a creative brief as `script`—**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). Optional `instruments` is a string array (≤10 non-empty hints, ≤80 chars each), not a comma-separated string. | **5** |
 | `render` | Final MP4. Auto-charges and generates any pending or failed scenes first (4/scene in a batch of ≥3). | **0** |
@@ -137,7 +137,7 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `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**. |
-| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**; choose its preferred corner and `throughout`/`end_card`/`none` (hide) treatment. Forge moves it away from text/CTA/chips. The logo is never sent to the video model. |
+| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**. The corner is preferred and Forge moves it away from text/CTA/chips. Omit treatment to auto-select: transparent marks use `throughout`, opaque square lockups use `end_card`; explicit `throughout`/`end_card`/`none` still wins. The logo is never sent to the video model. |
 | `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Phone-shaped portrait art is cover-cropped to 9:16; square, classic portrait, and landscape art is contained over a blurred backdrop. Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA and an end-card-only logo so they don't collide. |
 
 ### Status & delivery
@@ -152,9 +152,9 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 
 ### Creative export contract
 
-- Production prompts (`product_prompt`, `scenario_prompt`, and scene `prompt`) are visual directions. Narration scripts are read aloud verbatim, so `set_narration_script.script` must contain only the exact spoken words—never camera notes, prompt syntax, labels, or scene directions. Prefer `generate_narration` or Autopilot when exact wording is unnecessary.
+- Production prompts (`product_prompt`, `scenario_prompt`, and scene `prompt`) are visual directions. Narration scripts are read aloud verbatim, so `set_narration_script.script` must contain only the exact spoken words—never camera notes, prompt syntax, labels, or scene directions. Never copy a creative brief into `script`; prefer `generate_narration` or Autopilot unless the user supplied final voice-over copy.
 - Do not rely on the video model to spell essential brand names, UI, signs, prices, offers, or CTAs. Put exact copy in Hubfluencer overlays, narration, or supplied ending artwork.
-- `short_logo_position` is a preferred corner. Forge moves the logo away from headline, captions, CTA, offer, and badge areas. Use a tight transparent wordmark; use square/full-bleed art as the poster. `end_card` logos are suppressed when `poster_includes_lockup:true` to avoid double branding.
+- `short_logo_position` is a preferred corner. Forge moves the logo away from headline, captions, CTA, offer, and badge areas. Omit treatment so transparent marks default to `throughout` and opaque square lockups default to `end_card`. Use a tight transparent wordmark; use square/full-bleed art as the poster. `end_card` logos are suppressed when `poster_includes_lockup:true` to avoid double branding.
 - Short posters fill the ending frame: phone-shaped portrait art is cover-cropped, while square, classic portrait, and landscape art is contained over a blurred backdrop. Editor closing images are always cover-cropped. Keep important content in the central 9:16 safe area. An Editor closing image gets no generic CTA, so put the CTA in the artwork or state it in the preceding narration/scene.
 - Each Editor AI scene is 8 seconds. Request 3 scenes (about 24 seconds) for a concise social ad unless the brief needs a longer story.
 

package/dist/index.js

@@ -29578,6 +29578,7 @@ function normalizeStatus(kind, slug, data) {
   const renderStale = latest.is_stale === true;
   const renderFresh = latest.is_stale === false;
   const stale = renderStale || staleSegments.length > 0 || audioStale;
+  const autopilotContractIncomplete = autopilot === "completed" && d.autopilot_contract_satisfied === false && !stale;
   const renderActive = renderStatus === "pending" || renderStatus === "rendering" || renderStatus === "processing";
   const scenarioActive = d.scenario_status === "generating" || d.scenario_apply_status === "pending" || d.scenario_apply_status === "applying";
   const narrationActive = d.narration_status === "generating";
@@ -29617,7 +29618,7 @@ function normalizeStatus(kind, slug, data) {
   const batchRecoveryActive = autopilotFailed && batchActive;
   const childFailureActionable = !batchRecoveryActive && (!autopilotActive || !childWorkActive && !autopilotResumeGraceActive);
   const workActive = autopilotActive || childWorkActive;
-  const deliveredArtifactSupersedesOrchestrationFailure = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed;
+  const deliveredArtifactSupersedesOrchestrationFailure = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed && !autopilotContractIncomplete;
   const ready = deliveredArtifactSupersedesOrchestrationFailure;
   const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
   const renderFailed = renderStatus === "failed" && childFailureActionable;
@@ -29648,6 +29649,8 @@ function normalizeStatus(kind, slug, data) {
     stage = "audio_failed";
   else if (batchInsufficientCredits)
     stage = "insufficient_credits";
+  else if (autopilotContractIncomplete)
+    stage = "contract_incomplete";
   else if (activeSegments.length > 0)
     stage = "segment_processing";
   else if (batchActive)
@@ -29673,10 +29676,13 @@ function normalizeStatus(kind, slug, data) {
     terminal,
     ready,
     video_url: videoUrl,
-    error: ready ? null : batchRetryRequired ? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing." : (parentFailureActionable ? d.autopilot_error_message : null) ?? actionableChildError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry." : null),
+    error: ready ? null : batchRetryRequired ? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing." : (parentFailureActionable ? d.autopilot_error_message : null) ?? actionableChildError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry." : null) ?? (autopilotContractIncomplete ? "Autopilot completed without every quoted deliverable. Resume Autopilot to repair the missing component." : null),
     stale,
     active_segment_ids: activeSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string"),
-    stale_segment_ids: staleSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string")
+    stale_segment_ids: staleSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string"),
+    ...typeof d.autopilot_contract_satisfied === "boolean" ? {
+      autopilot_contract_satisfied: d.autopilot_contract_satisfied
+    } : {}
   };
 }
 function startStateDiscriminator(kind, data) {
@@ -29700,16 +29706,16 @@ function idemKey(...parts) {
   return createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 32);
 }
 function makeVideoEditorCreateKey(a) {
-  return idemKey("make-editor", a.prompt, a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "");
+  return idemKey("make-editor", a.prompt, a.segments_count === undefined ? "" : String(a.segments_count), a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "");
 }
 function makeVideoAutopilotKey(slug, a, startState) {
-  return idemKey("autopilot", slug, a.prompt, a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", startState);
+  return idemKey("autopilot", slug, a.prompt, a.segments_count === undefined ? "" : String(a.segments_count), a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", startState);
 }
 function editorAdCreateKey(a) {
-  return idemKey("create-editor", a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_image_identity ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.closing_image_identity ?? "", a.logo_path ?? "", a.logo_identity ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds));
+  return idemKey("create-editor", a.product_prompt ?? "", a.segments_count === undefined ? "" : String(a.segments_count), a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_image_identity ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.closing_image_identity ?? "", a.logo_path ?? "", a.logo_identity ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds));
 }
 function editorAdAutopilotKey(slug, a) {
-  return idemKey("autopilot", slug, a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.logo_path ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.max_credits === undefined ? "" : String(a.max_credits));
+  return idemKey("autopilot", slug, a.product_prompt ?? "", a.segments_count === undefined ? "" : String(a.segments_count), a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.logo_path ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.max_credits === undefined ? "" : String(a.max_credits));
 }
 function sliderCreateKey(a) {
   return idemKey("create-slider", a.prompt, a.mode ?? "", a.template ?? "", a.slide_count === undefined ? "" : String(a.slide_count), a.aspect_ratio ?? "", a.accent_color ?? "", a.text_position ?? "");
@@ -30266,7 +30272,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.15.0",
+  version: "0.16.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>",
@@ -30992,6 +30998,38 @@ function assetSubscriptionErrorText(status, code, message) {
   return `${message} The reusable asset catalog requires an ACTIVE SUBSCRIPTION; ` + "this is a billing gate, not a scope or credit issue, so retrying won't help — " + "subscribe in the app first. (Generating videos/carousels does not require this.)";
 }
 
+// src/polling.ts
+async function pollWithFinalReconciliation({
+  read,
+  isTerminal: isTerminal2,
+  budgetMs,
+  intervalMs,
+  onPoll,
+  now = Date.now,
+  sleep: sleep3 = (milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds))
+}) {
+  const deadline = now() + budgetMs;
+  let value = await read(deadline);
+  let pollNumber = 0;
+  while (!isTerminal2(value)) {
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0)
+      break;
+    await onPoll?.(value, ++pollNumber);
+    await sleep3(Math.min(intervalMs, remainingMs));
+    if (now() >= deadline)
+      break;
+    value = await read(deadline);
+  }
+  if (!isTerminal2(value)) {
+    const finalReadDeadline = now() + Math.min(5000, Math.max(1000, intervalMs));
+    try {
+      value = await read(finalReadDeadline);
+    } catch {}
+  }
+  return value;
+}
+
 // src/series-calendar.ts
 var SERIES_FIELDS = [
   "brand_profile_id",
@@ -31590,6 +31628,8 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
       params.set("product_subject", overrides.product_subject);
     if (overrides.product_prompt !== undefined)
       params.set("product_prompt", overrides.product_prompt);
+    if (overrides.segments_count !== undefined)
+      params.set("segments_count", String(overrides.segments_count));
     if (overrides.restart)
       params.set("restart", "true");
     const query = params.toString();
@@ -31597,9 +31637,13 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
     const cost = asRecord(asRecord(response).data);
     const estimated_credits = typeof cost.total === "number" ? cost.total : null;
     const available_credits = typeof cost.available_credits === "number" ? cost.available_credits : null;
+    const scene_count = typeof cost.scene_count === "number" ? cost.scene_count : null;
+    const target_duration_seconds = typeof cost.target_duration_seconds === "number" ? cost.target_duration_seconds : null;
     return {
       estimated_credits,
       available_credits,
+      scene_count,
+      target_duration_seconds,
       affordable: estimated_credits !== null && available_credits !== null && available_credits >= estimated_credits
     };
   } catch (error2) {
@@ -31610,6 +31654,8 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
     return {
       estimated_credits: null,
       available_credits: null,
+      scene_count: null,
+      target_duration_seconds: null,
       affordable: false
     };
   }
@@ -31885,15 +31931,13 @@ AUTH: set HUBFLUENCER_API_TOKEN (Settings → Access tokens) or run \`npx -y @hu
 var server = new McpServer({ name: "hubfluencer", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
 var registerTool = server.registerTool.bind(server);
 async function pollToTerminal(client, kind, slug, extra, budgetMs, intervalMs) {
-  const deadline = Date.now() + budgetMs;
-  let status = await fetchStatus(client, kind, slug, deadline);
-  let n = 0;
-  while (!status.terminal && Date.now() + intervalMs <= deadline) {
-    await reportProgress(extra, ++n, `stage: ${status.stage}`);
-    await sleep4(intervalMs);
-    status = await fetchStatus(client, kind, slug, deadline);
-  }
-  return status;
+  return pollWithFinalReconciliation({
+    read: (deadline) => fetchStatus(client, kind, slug, deadline),
+    isTerminal: (status) => status.terminal,
+    budgetMs,
+    intervalMs,
+    onPoll: (status, pollNumber) => reportProgress(extra, pollNumber, `stage: ${status.stage}`)
+  });
 }
 async function pollSegmentToTerminal(client, slug, segmentId, extra, deadline, intervalMs) {
   const sid = String(segmentId);
@@ -31928,6 +31972,7 @@ registerTool("make_video", {
     kind: exports_external.string().optional().describe("'short' (fast, 1 clip), 'editor' (multi-scene), or 'auto' (default — inferred)"),
     product_subject: exports_external.string().max(300).optional().describe('EDITOR only: the concrete product / main subject the video must be about (e.g. "Bordeaux red ' + 'wine, dark green bottle"). Hard-grounds the AI so it cannot invent an unrelated product. ' + "Recommended for ads."),
     project_intent: exports_external.enum(["social_ad", "creative_story"]).optional().describe("EDITOR only: social_ad for promotional content (product focus + CTA) or creative_story (default)."),
+    segments_count: exports_external.number().int().min(3).max(10).optional().describe("EDITOR only: exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad."),
     language: exports_external.enum(LANGUAGES).optional().describe('Language (default "en"). Bare ISO-639-1 code only — no region/script subtag ' + '(use "pt", never "pt-BR"/"en-US"). Drives scenario, narration, voice, and captions.'),
     aspect: exports_external.string().optional().describe("Aspect ratio for editor: 9:16 (default), 16:9, or 1:1"),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover"),
@@ -31979,6 +32024,9 @@ registerTool("make_video", {
     return fail(kindErr);
   const requestedKind = args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
   const kind = requestedKind ?? inferKind(args.prompt);
+  if (kind !== "editor" && args.segments_count !== undefined) {
+    return fail("segments_count is only supported for editor videos.");
+  }
   const waitSeconds = Math.min(280, Math.max(10, args.max_wait_seconds ?? 240));
   const budgetMs = waitSeconds * 1000;
   if (args.star_rating !== undefined && (args.star_rating < 0 || args.star_rating > 5)) {
@@ -32031,6 +32079,7 @@ registerTool("make_video", {
     const created = await client.post("/editor", {
       language: args.language ?? "en",
       product_prompt: args.prompt,
+      segments_count: args.segments_count,
       product_subject: args.product_subject,
       project_intent: args.project_intent,
       export_aspect_ratio: args.aspect,
@@ -32889,6 +32938,7 @@ registerTool("create_editor_ad", {
     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")'),
+    segments_count: exports_external.number().int().min(3).max(10).optional().describe("Exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad; omit to retain the server default."),
     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."),
     product_description: exports_external.string().max(500).optional().describe("Product description used to ground the scenario and narration when product_image_path is supplied."),
     closing_image_path: exports_external.string().optional().describe("Local closing-card image (.jpg/.jpeg/.png, ≤20 MiB)."),
@@ -32933,6 +32983,7 @@ registerTool("create_editor_ad", {
     const created = await client.post("/editor", {
       language: args.language ?? "en",
       product_prompt: args.product_prompt,
+      segments_count: args.segments_count,
       product_subject: args.product_subject,
       project_intent: args.project_intent,
       creative_format: args.creative_format,
@@ -32979,7 +33030,9 @@ registerTool("create_editor_ad", {
       logoSettings.logo_duration_seconds = args.logo_duration_seconds;
     if (args.logo_path && Object.keys(logoSettings).length > 0)
       await client.patch(`/editor/${slug}/logo`, logoSettings);
-    const quote = await editorAutopilotQuote(client, slug);
+    const quote = await editorAutopilotQuote(client, slug, {
+      segments_count: args.segments_count
+    });
     const overCap = args.max_credits !== undefined && quote.estimated_credits !== null && quote.estimated_credits > args.max_credits;
     if (args.max_credits === undefined || quote.estimated_credits === null || overCap || !quote.affordable) {
       const note = args.max_credits === undefined ? `Free draft configured. Estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}); nothing charged. Relaunch with start_autopilot({ slug: "${slug}", max_credits: ${quote.estimated_credits ?? "<approved cap>"} }).` : quote.estimated_credits === null ? "Pricing is temporarily unavailable, so the paid pipeline was not started. Retry the quote later." : overCap ? `Estimated ${quote.estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged.` : `Not enough credits (needs ${quote.estimated_credits}, have ${quote.available_credits ?? "?"}); nothing charged.`;
@@ -32992,7 +33045,10 @@ registerTool("create_editor_ad", {
         next: "start_autopilot"
       });
     }
-    const started = await client.post(`/editor/${slug}/autopilot`, { max_credits: args.max_credits }, editorAdAutopilotKey(slug, args));
+    const started = await client.post(`/editor/${slug}/autopilot`, {
+      max_credits: args.max_credits,
+      segments_count: args.segments_count
+    }, editorAdAutopilotKey(slug, args));
     const status = normalizeStatus("editor", slug, asRecord(started).data);
     return ok({
       slug,
@@ -33017,6 +33073,7 @@ registerTool("start_autopilot", {
     language: exports_external.enum(LANGUAGES).optional().describe('Optional language override applied before launch. Bare ISO-639-1 code only, e.g. "fr" — no ' + "region/script subtag. Drives scenario, narration, voice, and captions."),
     product_subject: exports_external.string().max(300).optional().describe("Optional locked product / main subject applied before launch so the AI cannot invent an " + "unrelated product. Omit to keep the stored subject; send blank to clear it."),
     product_prompt: exports_external.string().optional().describe("Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it."),
+    segments_count: exports_external.number().int().min(3).max(10).optional().describe("Optional exact number of 8-second AI scenes (3–10). Omit to keep the stored structural target."),
     max_credits: exports_external.number().int().nonnegative().optional().describe("Explicit spend cap. Omit to quote only; no credits are charged."),
     restart: exports_external.boolean().optional().describe("Set true only on a completed project to quote/build a fresh creative run. The delivered timeline stays available until replacement apply.")
   },
@@ -33037,6 +33094,8 @@ registerTool("start_autopilot", {
     overrides.product_subject = args.product_subject;
   if (args.product_prompt !== undefined)
     overrides.product_prompt = args.product_prompt;
+  if (args.segments_count !== undefined)
+    overrides.segments_count = args.segments_count;
   if (args.restart)
     overrides.restart = true;
   const quote = await editorAutopilotQuote(client, slug, overrides);
@@ -34020,7 +34079,7 @@ registerTool("set_short_logo", {
     slug: exports_external.string().describe("Short slug"),
     file_path: exports_external.string().describe("Local logo image (.png/.jpg/.jpeg)"),
     position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Preferred logo corner (default top-right; auto-relocated to avoid text)"),
-    treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe("When the logo appears (default throughout)")
+    treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe("When the logo appears. Omit for automatic treatment: transparent wordmarks run throughout; opaque square artwork moves to the end card.")
   },
   annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
@@ -34028,7 +34087,7 @@ registerTool("set_short_logo", {
   const res = await client.post(`/shorts/${args.slug}/logo/confirm`, {
     s3_key,
     position: args.position ?? "top-right",
-    treatment: args.treatment ?? "throughout"
+    ...args.treatment ? { treatment: args.treatment } : {}
   });
   return ok(asRecord(res).data ?? res);
 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.15.0",
+  "version": "0.16.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

@@ -289,6 +289,8 @@ export interface NormalizedStatus {
 	active_segment_ids?: Array<number | string>;
 	/** Editor only: completed current scene ids invalidated by continuity edits. */
 	stale_segment_ids?: Array<number | string>;
+	/** Editor Autopilot only: server-verified quoted delivery contract. */
+	autopilot_contract_satisfied?: boolean;
 	/** Short only (additive, absent on older APIs): the newest render row is a free re-render. */
 	latest_render_free?: boolean;
 	/**
@@ -515,6 +517,21 @@ export function normalizeStatus(
 	// Legacy/null/omitted freshness is unknown and must never be promoted to ready.
 	const renderFresh = latest.is_stale === false;
 	const stale = renderStale || staleSegments.length > 0 || audioStale;
+	// A completed Autopilot run the API reports as NOT satisfying its delivery
+	// contract — gated on a FRESH timeline. The server recomputes
+	// autopilot_contract_satisfied LIVE for completed runs, folding in staleness,
+	// so any ordinary post-delivery edit (e.g. adding narration makes music stale)
+	// flips it false even though the run genuinely delivered. Gating on !stale
+	// keeps this signal to the real missing-component case — canonically a legacy
+	// "music-only" run where nothing is stale but voice/narration were never
+	// produced — and lets the stale/editing_required semantics win everywhere once
+	// an edit lands. Declared after `stale` (which it depends on); the raw
+	// autopilot_contract_satisfied wire field is still passed through verbatim
+	// below, only this derived stage/error signal is freshness-gated.
+	const autopilotContractIncomplete =
+		autopilot === "completed" &&
+		d.autopilot_contract_satisfied === false &&
+		!stale;
 	// A render in flight is active work too — fold it into workActive so the
 	// terminal computation below can never fire while a render is queued/running.
 	// "pending" here is NOT an idle default: a video_results row only exists once
@@ -638,7 +655,8 @@ export function normalizeStatus(
 		!stale &&
 		!workActive &&
 		failedSegments.length === 0 &&
-		!audioFailed;
+		!audioFailed &&
+		!autopilotContractIncomplete;
 	const ready = deliveredArtifactSupersedesOrchestrationFailure;
 	const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
 	const renderFailed = renderStatus === "failed" && childFailureActionable;
@@ -698,6 +716,7 @@ export function normalizeStatus(
 		stage = "segment_failed";
 	else if (childFailureActionable && audioFailed) stage = "audio_failed";
 	else if (batchInsufficientCredits) stage = "insufficient_credits";
+	else if (autopilotContractIncomplete) stage = "contract_incomplete";
 	else if (activeSegments.length > 0) stage = "segment_processing";
 	else if (batchActive) stage = "segment_generation";
 	else if (autoRenderHandoffActive) stage = "rendering";
@@ -727,6 +746,13 @@ export function normalizeStatus(
 		terminal,
 		ready,
 		video_url: videoUrl,
+		// Mirror the stage chain's precedence EXACTLY so the error text always
+		// matches the stage the caller sees. batch-retry, then the actionable
+		// parent/child failures, then insufficient-credits, and only last the
+		// contract-incomplete message — because a completed-autopilot editor with a
+		// later paused manual batch reports stage "batch_retry_required", so it must
+		// read the retry guidance, not "Resume Autopilot" (the one action
+		// start_autopilot refuses while a batch is paused).
 		error: ready
 			? null
 			: batchRetryRequired
@@ -737,6 +763,9 @@ export function normalizeStatus(
 					actionableChildError ??
 					(batchInsufficientCredits
 						? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry."
+						: null) ??
+					(autopilotContractIncomplete
+						? "Autopilot completed without every quoted deliverable. Resume Autopilot to repair the missing component."
 						: null)),
 		stale,
 		active_segment_ids: activeSegments
@@ -751,6 +780,12 @@ export function normalizeStatus(
 				(id): id is number | string =>
 					typeof id === "number" || typeof id === "string",
 			),
+		...(typeof d.autopilot_contract_satisfied === "boolean"
+			? {
+					autopilot_contract_satisfied:
+						d.autopilot_contract_satisfied as boolean,
+				}
+			: {}),
 	};
 }
 
@@ -817,6 +852,7 @@ export function idemKey(...parts: string[]): string {
 /** make_video's editor draft-create key (`POST /editor`). */
 export interface MakeVideoEditorCreateArgs {
 	prompt: string;
+	segments_count?: number;
 	product_subject?: string;
 	project_intent?: string;
 	language?: string;
@@ -831,6 +867,7 @@ export function makeVideoEditorCreateKey(a: MakeVideoEditorCreateArgs): string {
 	return idemKey(
 		"make-editor",
 		a.prompt,
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -857,6 +894,7 @@ export function makeVideoAutopilotKey(
 		"autopilot",
 		slug,
 		a.prompt,
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -872,6 +910,7 @@ export function makeVideoAutopilotKey(
 /** create_editor_ad's draft-create and autopilot-start key argument set. */
 export interface EditorAdKeyArgs {
 	product_prompt?: string;
+	segments_count?: number;
 	product_subject?: string;
 	project_intent?: string;
 	language?: string;
@@ -906,6 +945,7 @@ export function editorAdCreateKey(a: EditorAdKeyArgs): string {
 	return idemKey(
 		"create-editor",
 		a.product_prompt ?? "",
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -943,6 +983,7 @@ export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
 		"autopilot",
 		slug,
 		a.product_prompt ?? "",
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",

package/src/index.ts

@@ -101,6 +101,7 @@ import {
 	validatePerformanceMetrics,
 	validateReviewOutput,
 } from "./perf-review-assets.js";
+import { pollWithFinalReconciliation } from "./polling.js";
 import {
 	buildScheduledPostBody,
 	calendarScopeErrorText,
@@ -161,11 +162,14 @@ async function editorAutopilotQuote(
 		language?: string;
 		product_subject?: string;
 		product_prompt?: string;
+		segments_count?: number;
 		restart?: boolean;
 	} = {},
 ): Promise<{
 	estimated_credits: number | null;
 	available_credits: number | null;
+	scene_count: number | null;
+	target_duration_seconds: number | null;
 	affordable: boolean;
 }> {
 	try {
@@ -175,6 +179,8 @@ async function editorAutopilotQuote(
 			params.set("product_subject", overrides.product_subject);
 		if (overrides.product_prompt !== undefined)
 			params.set("product_prompt", overrides.product_prompt);
+		if (overrides.segments_count !== undefined)
+			params.set("segments_count", String(overrides.segments_count));
 		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
 		const response = await client.get<{ data: unknown }>(
@@ -187,9 +193,17 @@ async function editorAutopilotQuote(
 			typeof cost.available_credits === "number"
 				? cost.available_credits
 				: null;
+		const scene_count =
+			typeof cost.scene_count === "number" ? cost.scene_count : null;
+		const target_duration_seconds =
+			typeof cost.target_duration_seconds === "number"
+				? cost.target_duration_seconds
+				: null;
 		return {
 			estimated_credits,
 			available_credits,
+			scene_count,
+			target_duration_seconds,
 			affordable:
 				estimated_credits !== null &&
 				available_credits !== null &&
@@ -213,6 +227,8 @@ async function editorAutopilotQuote(
 		return {
 			estimated_credits: null,
 			available_credits: null,
+			scene_count: null,
+			target_duration_seconds: null,
 			affordable: false,
 		};
 	}
@@ -674,15 +690,14 @@ async function pollToTerminal(
 	budgetMs: number,
 	intervalMs: number,
 ): Promise<NormalizedStatus> {
-	const deadline = Date.now() + budgetMs;
-	let status = await fetchStatus(client, kind, slug, deadline);
-	let n = 0;
-	while (!status.terminal && Date.now() + intervalMs <= deadline) {
-		await reportProgress(extra, ++n, `stage: ${status.stage}`);
-		await sleep(intervalMs);
-		status = await fetchStatus(client, kind, slug, deadline);
-	}
-	return status;
+	return pollWithFinalReconciliation({
+		read: (deadline) => fetchStatus(client, kind, slug, deadline),
+		isTerminal: (status) => status.terminal,
+		budgetMs,
+		intervalMs,
+		onPoll: (status, pollNumber) =>
+			reportProgress(extra, pollNumber, `stage: ${status.stage}`),
+	});
 }
 
 /**
@@ -799,6 +814,15 @@ registerTool(
 				.describe(
 					"EDITOR only: social_ad for promotional content (product focus + CTA) or creative_story (default).",
 				),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"EDITOR only: exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad.",
+				),
 			language: z
 				.enum(LANGUAGES)
 				.optional()
@@ -978,6 +1002,7 @@ registerTool(
 				kind?: string;
 				product_subject?: string;
 				project_intent?: string;
+				segments_count?: number;
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
@@ -1022,6 +1047,9 @@ registerTool(
 			const requestedKind =
 				args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
 			const kind: Kind = requestedKind ?? inferKind(args.prompt);
+			if (kind !== "editor" && args.segments_count !== undefined) {
+				return fail("segments_count is only supported for editor videos.");
+			}
 			const waitSeconds = Math.min(
 				280,
 				Math.max(10, args.max_wait_seconds ?? 240),
@@ -1128,6 +1156,7 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.prompt,
+						segments_count: args.segments_count,
 						product_subject: args.product_subject,
 						project_intent: args.project_intent,
 						export_aspect_ratio: args.aspect,
@@ -3245,6 +3274,15 @@ registerTool(
 				.enum(["9:16", "16:9", "1:1"])
 				.optional()
 				.describe('Aspect ratio (default "9:16")'),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"Exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad; omit to retain the server default.",
+				),
 			product_image_path: z
 				.string()
 				.optional()
@@ -3310,6 +3348,7 @@ registerTool(
 				theme?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
+				segments_count?: number;
 				product_image_path?: string;
 				product_description?: string;
 				closing_image_path?: string;
@@ -3386,6 +3425,7 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.product_prompt,
+						segments_count: args.segments_count,
 						product_subject: args.product_subject,
 						project_intent: args.project_intent,
 						creative_format: args.creative_format,
@@ -3464,7 +3504,9 @@ registerTool(
 				if (args.logo_path && Object.keys(logoSettings).length > 0)
 					await client.patch(`/editor/${slug}/logo`, logoSettings);
 
-				const quote = await editorAutopilotQuote(client, slug);
+				const quote = await editorAutopilotQuote(client, slug, {
+					segments_count: args.segments_count,
+				});
 				const overCap =
 					args.max_credits !== undefined &&
 					quote.estimated_credits !== null &&
@@ -3495,7 +3537,10 @@ registerTool(
 
 				const started = await client.post<{ data: unknown }>(
 					`/editor/${slug}/autopilot`,
-					{ max_credits: args.max_credits },
+					{
+						max_credits: args.max_credits,
+						segments_count: args.segments_count,
+					},
 					// Fold the create-affecting params into the start key so it tracks
 					// inputs, not just the slug. Self-consistent per-tool only: this key
 					// is compared against retries of *this* tool on *this* slug. The
@@ -3561,6 +3606,15 @@ registerTool(
 				.describe(
 					"Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it.",
 				),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"Optional exact number of 8-second AI scenes (3–10). Omit to keep the stored structural target.",
+				),
 			max_credits: z
 				.number()
 				.int()
@@ -3586,6 +3640,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				segments_count?: number;
 				max_credits?: number;
 				restart?: boolean;
 			},
@@ -3601,6 +3656,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				segments_count?: number;
 				restart?: boolean;
 			} = {};
 			if (args.language !== undefined) overrides.language = args.language;
@@ -3608,6 +3664,8 @@ registerTool(
 				overrides.product_subject = args.product_subject;
 			if (args.product_prompt !== undefined)
 				overrides.product_prompt = args.product_prompt;
+			if (args.segments_count !== undefined)
+				overrides.segments_count = args.segments_count;
 			if (args.restart) overrides.restart = true;
 
 			const quote = await editorAutopilotQuote(client, slug, overrides);
@@ -5665,7 +5723,9 @@ registerTool(
 			treatment: z
 				.enum(["throughout", "end_card", "none"])
 				.optional()
-				.describe("When the logo appears (default throughout)"),
+				.describe(
+					"When the logo appears. Omit for automatic treatment: transparent wordmarks run throughout; opaque square artwork moves to the end card.",
+				),
 		},
 		annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false },
 	},
@@ -5690,7 +5750,7 @@ registerTool(
 				{
 					s3_key,
 					position: args.position ?? "top-right",
-					treatment: args.treatment ?? "throughout",
+					...(args.treatment ? { treatment: args.treatment } : {}),
 				},
 			);
 			return ok(asRecord(res).data ?? res);

package/src/polling.ts

@@ -0,0 +1,51 @@
+export interface PollOptions<T> {
+	read: (deadline: number) => Promise<T>;
+	isTerminal: (value: T) => boolean;
+	budgetMs: number;
+	intervalMs: number;
+	onPoll?: (value: T, pollNumber: number) => Promise<void>;
+	now?: () => number;
+	sleep?: (milliseconds: number) => Promise<void>;
+}
+
+/**
+ * Poll within a fixed budget, then perform one separately bounded
+ * reconciliation read. The final read closes the common race where work
+ * finishes during the last partial interval and the caller otherwise returns
+ * the stale pre-completion snapshot.
+ */
+export async function pollWithFinalReconciliation<T>({
+	read,
+	isTerminal,
+	budgetMs,
+	intervalMs,
+	onPoll,
+	now = Date.now,
+	sleep = (milliseconds) =>
+		new Promise<void>((resolve) => setTimeout(resolve, milliseconds)),
+}: PollOptions<T>): Promise<T> {
+	const deadline = now() + budgetMs;
+	let value = await read(deadline);
+	let pollNumber = 0;
+
+	while (!isTerminal(value)) {
+		const remainingMs = deadline - now();
+		if (remainingMs <= 0) break;
+		await onPoll?.(value, ++pollNumber);
+		await sleep(Math.min(intervalMs, remainingMs));
+		if (now() >= deadline) break;
+		value = await read(deadline);
+	}
+
+	if (!isTerminal(value)) {
+		const finalReadDeadline =
+			now() + Math.min(5_000, Math.max(1_000, intervalMs));
+		try {
+			value = await read(finalReadDeadline);
+		} catch {
+			// The normal timeout/resume contract uses the last successful state.
+		}
+	}
+
+	return value;
+}