@hubfluencer/mcp 0.8.2 → 0.9.1

package/src/index.ts

@@ -10,7 +10,7 @@
  *   One-shot : make_video({ prompt })  → finished MP4 (create→start→poll→download)
  *   Shorts   : create_short → generate_short → wait_for_completion → download_result
  *              (then iterate free: update_short → rerender_short, 0 credits)
- *   Editor   : create_editor_ad (creates + starts autopilot) → wait_for_completion → download_result
+ *   Editor   : create_editor_ad (create + assets + quote; max_credits launches) → wait_for_completion → download_result
  *   Granular : create_editor_draft → generate_scenario|set_scenario → get_editor
  *              → apply_scenario (scenario → scene prompts) | set_scene_count + set_segment_prompt
  *              → generate_segment(s) (+ regenerate_segment to re-roll a completed scene)
@@ -116,7 +116,14 @@ import {
 } from "./series-calendar.js";
 import {
 	CATALOG_ASSET_EXTS,
+	closePreparedUploadFile,
 	IMAGE_EXTS,
+	MAX_CLOSING_IMAGE_BYTES,
+	MAX_LOGO_BYTES,
+	MAX_PRODUCT_IMAGE_BYTES,
+	type PreparedUploadFile,
+	preparedUploadIdentity,
+	prepareImageUpload,
 	resolveVideoReadPath,
 	uploadCatalogAsset,
 	uploadImageFile,
@@ -146,6 +153,98 @@ async function fetchStatus(
 	return normalizeStatus(kind, slug, asRecord(res).data);
 }
 
+async function editorAutopilotQuote(
+	client: HubfluencerClient,
+	slug: string,
+	overrides: {
+		language?: string;
+		product_subject?: string;
+		product_prompt?: string;
+		restart?: boolean;
+	} = {},
+): Promise<{
+	estimated_credits: number | null;
+	available_credits: number | null;
+	affordable: boolean;
+}> {
+	try {
+		const params = new URLSearchParams();
+		if (overrides.language) params.set("language", overrides.language);
+		if (overrides.product_subject)
+			params.set("product_subject", overrides.product_subject);
+		if (overrides.product_prompt)
+			params.set("product_prompt", overrides.product_prompt);
+		if (overrides.restart) params.set("restart", "true");
+		const query = params.toString();
+		const response = await client.get<{ data: unknown }>(
+			`/editor/${slug}/autopilot/cost${query ? `?${query}` : ""}`,
+		);
+		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;
+		return {
+			estimated_credits,
+			available_credits,
+			affordable:
+				estimated_credits !== null &&
+				available_credits !== null &&
+				available_credits >= estimated_credits,
+		};
+	} catch (error) {
+		const apiError = error as Partial<HubfluencerError>;
+		if (
+			typeof apiError.status === "number" &&
+			apiError.status >= 400 &&
+			apiError.status < 500 &&
+			apiError.status !== 429
+		) {
+			// Authentication, scope, validation, and unknown-slug errors are stable
+			// and actionable. Preserve them rather than disguising them as a pricing
+			// outage. Only transient/network/server failures use the fail-closed quote.
+			throw error;
+		}
+		// A spend cap cannot be enforced without a live price. Fail closed: callers
+		// receive a free draft/quote response and can retry the preflight later.
+		return {
+			estimated_credits: null,
+			available_credits: null,
+			affordable: false,
+		};
+	}
+}
+
+async function editorChargeReceipt(
+	client: HubfluencerClient,
+	slug: string,
+	action: "scene_regeneration" | "voice_generation" | "music_generation",
+	listPriceCredits: number,
+): Promise<Record<string, unknown>> {
+	try {
+		const response = await client.get<{ data: unknown }>(`/editor/${slug}`);
+		const editor = asRecord(asRecord(response).data);
+		return {
+			action,
+			list_price_credits: listPriceCredits,
+			project_spend: editor.project_spend ?? null,
+			approved_cap: editor.autopilot_max_credits ?? null,
+			approved_run_spend: editor.autopilot_credits_spent ?? null,
+		};
+	} catch {
+		// The paid mutation already succeeded. Never make a receipt-enrichment GET
+		// look like a failed charge that an agent should retry.
+		return {
+			action,
+			list_price_credits: listPriceCredits,
+			project_spend: null,
+			enrichment_unavailable: true,
+		};
+	}
+}
+
 function isRecompositeInProgressConflict(e: unknown): boolean {
 	const err = e as Partial<HubfluencerError>;
 	if (err?.status !== 409) return false;
@@ -501,14 +600,14 @@ const WRITE = {
 const SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product page — into finished, post-ready vertical videos and image carousels, and can run the surrounding content operation (plan → draft → review → schedule → measure → repeat).
 
 MAKE ONE ASSET (simplest)
-- make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_short / create_editor_ad are the per-product one-shots; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
+- make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_editor_ad creates/configures/prices an editor and launches only with max_credits; create_short creates a short draft; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
 - Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → apply_scenario → review/edit prompts (set_segment_prompt) → generate_segment(s) → generate_voice + generate_music → render; regenerate_segment re-rolls a completed scene as a new version). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
 
 DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 1. ONBOARD a product: extract_product_page(url) pulls facts + imagery (SSRF-hardened, 0cr); import_product_image saves its picture/logo. Persist identity once with create_product_profile + create_brand_profile so every later draft inherits it instead of re-describing the brand.
 2. PLAN ($0, free quota — not credits): plan_campaign proposes angles/formats + a per-item credit estimate; generate_hook_variations writes hook options. create_campaign(url | product_profile_id) does 1-2 end-to-end and returns a pack of editable DRAFTS.
 3. PACK & MATERIALIZE ($0): create_campaign_pack / add_pack_variations assemble items; materialize_pack_item turns each into a 0-credit draft (editor_ad/short → a video project, carousel → a slider). list_campaign_packs lists packs; get_campaign_pack({ id }) shows every item's draft slug + credit estimate.
-4. GENERATE per draft (CREDITS — a separate, explicit step): run start_autopilot/generate_short/generate_slider on each draft slug. Nothing above this line spends video credits.
+4. GENERATE per draft (CREDITS — a separate, explicit step): start_autopilot({slug}) quotes free; after approval, start_autopilot({slug,max_credits:approved_cap}) launches. Run generate_short/generate_slider for approved short/carousel drafts. Nothing above this line spends video credits.
 5. REVIEW: create_review_link mints a no-login page where a human approves/comments (list_review_links / revoke_review_link manage them). Gate spend or posting on approval.
 6. CALENDAR (reminder-only): schedule_post / list_scheduled_posts / reschedule_post / cancel_scheduled_post stage a calendar that pushes REMINDERS to the user — it does NOT auto-publish (posting to TikTok/IG stays a human step in the app). After the user posts the presigned export, call mark_scheduled_posted.
 7. MEASURE → DOUBLE DOWN: record_performance logs views/engagement (tag creatives via set_item_attributes); get_recommendations gives a CAUTIOUS, non-causal read of your own best hook/format (present its confidence + note as-is, never upgrade them); make_more_like_winner spins fresh hooks from a proven item — feed a winner back into add_pack_variations → step 4.
@@ -516,11 +615,11 @@ DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 
 CREDITS (spent server-side; each tool prices before charging — see its description)
 - Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
-- Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video/create_* report the estimate first — pass dry_run to preview, max_credits to cap.
+- Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video supports dry_run/max_credits; create_editor_ad/start_autopilot require max_credits before launching.
 - AI ASSISTS (all generate_*/enhance/suggest/plan/hook tools) draw a FREE daily quota (20/day), NOT credits. On 429, set auto_unlock:true to spend 1 credit for +10 assists (retried once), or write the copy yourself and use the set_* tools.
 
 WAITING & RESUMING
-- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout.
+- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout. A terminal result is not always ready: an editor can go terminal in a needs-action stage (editing_required = stale after edits, regenerate the flagged scenes/audio; insufficient_credits = batch parked, top up / reduce scope; idle = draft with nothing generating, start generation first) — act on those instead of re-polling.
 - Creates and charged actions are idempotency-keyed: a transport retry is safe; a genuine re-run after a terminal FAILURE restarts rather than replaying the dead attempt.
 
 LOCAL FILES (sandboxed)
@@ -843,6 +942,8 @@ registerTool(
 				),
 			max_credits: z
 				.number()
+				.int()
+				.nonnegative()
 				.optional()
 				.describe(
 					"Spend cap: refuse to start (no charge) if the priced estimate exceeds this. Returns the estimate.",
@@ -1024,9 +1125,9 @@ registerTool(
 				slug = created.data.slug;
 			}
 
-			// 2) Preflight cost vs the live balance BEFORE charging. Best-effort: if
-			//    pricing can't be read we proceed (the charge itself still 402s
-			//    cleanly), surfacing nulls rather than blocking on a transient error.
+			// 2) Preflight cost vs the live balance BEFORE charging. Shorts retain
+			//    their fixed-price compatibility behavior, but an editor without a
+			//    readable quote must never fall through to the API's uncapped launch.
 			const costPath =
 				kind === "short"
 					? `/shorts/${slug}/cost`
@@ -1043,13 +1144,14 @@ registerTool(
 						? cost.available_credits
 						: null;
 			} catch {
-				// pricing unavailable — fall through (do not block an affordable run)
+				// The editor branch below fails closed unless the caller supplied an
+				// explicit cap that the launch endpoint can enforce independently.
 			}
 
 			const resume =
 				kind === "short"
 					? `generate_short({ slug: "${slug}"${args.skip_auto_text ? ", skip_auto_text: true" : ""} })`
-					: `start_autopilot({ slug: "${slug}" })`;
+					: `start_autopilot({ slug: "${slug}", max_credits: ${estimated_credits ?? "<approved cap>"} })`;
 			const affordable =
 				available_credits === null ||
 				estimated_credits === null ||
@@ -1058,17 +1160,28 @@ registerTool(
 				args.max_credits != null &&
 				estimated_credits != null &&
 				estimated_credits > args.max_credits;
-
-			// 3) Stop BEFORE charging on dry_run, an over-cap estimate, or a balance
-			//    we already know is too low. The free draft is returned so the caller
-			//    can top up / raise the cap and resume — no wasted charge, no orphan
-			//    on retry (the create idempotency key reuses this slug).
-			if (args.dry_run || overCap || !affordable) {
+			const editorPriceUnavailableWithoutCap =
+				kind === "editor" &&
+				estimated_credits === null &&
+				args.max_credits == null;
+
+			// 3) Stop BEFORE charging on dry_run, an uncapped editor with no live
+			//    quote, an over-cap estimate, or a balance we already know is too
+			//    low. The free draft is returned so the caller can retry the quote,
+			//    top up, or raise the cap without an orphan or surprise charge.
+			if (
+				args.dry_run ||
+				editorPriceUnavailableWithoutCap ||
+				overCap ||
+				!affordable
+			) {
 				const note = args.dry_run
 					? `Dry run — created a free draft and priced it (${estimated_credits ?? "?"} credits, have ${available_credits ?? "?"}). To run it: ${resume}.`
-					: overCap
-						? `Estimated ${estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged. Raise max_credits, or run ${resume}.`
-						: `Not enough credits (needs ${estimated_credits ?? "?"}, have ${available_credits ?? "?"}); nothing charged. Top up, then run ${resume}.`;
+					: editorPriceUnavailableWithoutCap
+						? `Pricing is temporarily unavailable, so the editor was left as a free draft and nothing was charged. Retry the quote, then run start_autopilot({ slug: "${slug}", max_credits: <approved cap> }).`
+						: overCap
+							? `Estimated ${estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged. Raise max_credits, or run ${resume}.`
+							: `Not enough credits (needs ${estimated_credits ?? "?"}, have ${available_credits ?? "?"}); nothing charged. Top up, then run ${resume}.`;
 				return ok({
 					slug,
 					kind,
@@ -1116,9 +1229,20 @@ registerTool(
 					`gen-short:${slug}:${startState}${args.skip_auto_text ? ":bare" : ""}`,
 				);
 			} else {
+				const approvedCap = args.max_credits ?? estimated_credits;
+				if (approvedCap === null) {
+					// Belt-and-suspenders invariant behind the fail-closed branch above:
+					// never let a future condition refactor revive an uncapped editor POST.
+					throw new Error(
+						"Editor autopilot launch requires max_credits or a live quote",
+					);
+				}
 				await client.post(
 					`/editor/${slug}/autopilot`,
-					undefined,
+					// Use the caller's explicit cap when given, otherwise the live
+					// estimate. The API recomputes under its launch lock and rejects a
+					// price increase before any state change or charge.
+					{ max_credits: approvedCap },
 					// Fold the create-affecting params AND the failure-state discriminator
 					// into the start key so it tracks the inputs + current state, not just
 					// the slug. This key is only compared against a retry of *this* tool on
@@ -2343,8 +2467,8 @@ registerTool(
 			"FREE re-render: applies the short's current text/style/CTA/end-card state over the already-paid " +
 			"footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks. 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; the pinned music bed is faded to fit rather than " +
-			"regenerated — for perfectly synced music after such a change, use generate_short. " +
+			"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 " +
@@ -2817,18 +2941,20 @@ registerTool(
 registerTool(
 	"create_editor_ad",
 	{
-		title: "Create a multi-scene editor ad (autopilot)",
+		title: "Create, configure, and price a multi-scene editor ad",
 		description:
-			"Creates an editor project from a product prompt and starts autopilot (server-orchestrated " +
+			"Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " +
+			"and prices autopilot (server-orchestrated " +
 			"scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " +
-			"Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " +
-			"make_video for the one-shot path. " +
-			"BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " +
-			"create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " +
-			"start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " +
+			"Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " +
+			"the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " +
+			"wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " +
+			"Supplying assets here is safer than adding them after autopilot because the scenario and scenes are grounded " +
+			"in the real product from the start. (Editor ads carry their copy in-scene/narration, not as a " +
 			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.) " +
-			"For product_only or presenter_led cast modes, use create_editor_draft and configure the required " +
-			"product/presenter before start_autopilot; this one-shot tool intentionally uses automatic casting.",
+			"For a mascot or hero product that must stay visually identical with no human presenter, set " +
+			"cast_mode:'product_only' together with product_image_path. Presenter-led casting still belongs on " +
+			"create_editor_draft because it requires a separately configured presenter.",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -2884,6 +3010,61 @@ registerTool(
 				.enum(["9:16", "16:9", "1:1"])
 				.optional()
 				.describe('Aspect ratio (default "9:16")'),
+			product_image_path: z
+				.string()
+				.optional()
+				.describe(
+					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot.",
+				),
+			product_description: z
+				.string()
+				.max(500)
+				.optional()
+				.describe(
+					"Exact product/character description used with product_image_path.",
+				),
+			closing_image_path: z
+				.string()
+				.optional()
+				.describe("Local closing-card image (.jpg/.jpeg/.png, ≤20 MiB)."),
+			logo_path: z
+				.string()
+				.optional()
+				.describe("Local logo (.jpg/.jpeg/.png, ≤1 MiB) to overlay."),
+			logo_treatment: z
+				.enum(["intro", "outro", "both", "none"])
+				.optional()
+				.describe(
+					'When the logo bumper plays: "intro", "outro", "both" (default), or "none". Requires logo_path.',
+				),
+			logo_position: z
+				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
+				.optional()
+				.describe(
+					'Logo corner: "top-left", "top-right" (default), "bottom-left", or "bottom-right". Requires logo_path.',
+				),
+			logo_duration_seconds: z
+				.number()
+				.min(0.5)
+				.max(3)
+				.optional()
+				.describe(
+					"Logo bumper duration in seconds, 0.5–3 (default 1.5). Requires logo_path.",
+				),
+			cast_mode: z
+				.literal("product_only")
+				.optional()
+				.describe(
+					"Lock every AI scene to the supplied product/mascot reference with no people. Requires product_image_path.",
+				),
+			max_credits: z
+				.number()
+				.int()
+				.nonnegative()
+				.optional()
+				.describe(
+					"Explicit spend cap. Omit to create/configure/price only; no credits are charged.",
+				),
 		},
 		outputSchema: createEditorOutput,
 		annotations: { title: "Create editor ad", ...WRITE, idempotentHint: true },
@@ -2900,47 +3081,219 @@ registerTool(
 				theme?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
+				product_image_path?: string;
+				product_description?: string;
+				closing_image_path?: string;
+				logo_path?: string;
+				logo_treatment?: "intro" | "outro" | "both" | "none";
+				logo_position?:
+					| "top-left"
+					| "top-right"
+					| "bottom-left"
+					| "bottom-right";
+				logo_duration_seconds?: number;
+				cast_mode?: "product_only";
+				max_credits?: number;
 			},
 			client,
 		) => {
-			const langErr = validateLanguage(args.language);
-			if (langErr) return fail(langErr);
-			const promptErr = validateProductPrompt(args.product_prompt);
-			if (promptErr) return fail(promptErr);
+			const prepared: PreparedUploadFile[] = [];
+			let productImage: PreparedUploadFile | undefined;
+			let closingImage: PreparedUploadFile | undefined;
+			let logo: PreparedUploadFile | undefined;
+			try {
+				const langErr = validateLanguage(args.language);
+				if (langErr) return fail(langErr);
+				const promptErr = validateProductPrompt(args.product_prompt);
+				if (promptErr) return fail(promptErr);
+				if (args.cast_mode === "product_only" && !args.product_image_path) {
+					return fail(
+						"cast_mode product_only requires product_image_path so identity can be locked before generation.",
+					);
+				}
+				// Fail fast on settings that would otherwise be silently dropped: the
+				// logo PATCH is gated on logo_path and the product_description is only
+				// sent with product_image_path, so a logo_* / product_description passed
+				// without its asset is a caller mistake. Reject BEFORE creating even a
+				// free draft (consistent with the asset validation just below), rather
+				// than accepting the call and ignoring the field.
+				if (
+					(args.logo_treatment !== undefined ||
+						args.logo_position !== undefined ||
+						args.logo_duration_seconds !== undefined) &&
+					!args.logo_path
+				) {
+					return fail(
+						"logo_treatment/logo_position/logo_duration_seconds require logo_path (the logo image they style). Provide logo_path or drop these settings.",
+					);
+				}
+				if (
+					args.product_description !== undefined &&
+					!args.product_image_path
+				) {
+					return fail(
+						"product_description requires product_image_path (the product image it describes). Provide product_image_path or drop product_description.",
+					);
+				}
 
-			const created = await client.post<{ data: { slug: string } }>(
-				"/editor",
-				{
-					language: args.language ?? "en",
-					product_prompt: args.product_prompt,
-					product_subject: args.product_subject,
-					project_intent: args.project_intent,
-					creative_format: args.creative_format,
-					visual_language: args.visual_language,
-					theme: args.theme,
-					voice_id: args.voice_id,
-					export_aspect_ratio: args.export_aspect_ratio,
-				},
-				// Fold every create-affecting param into the key so two calls that
-				// differ only by style/theme/voice/aspect get distinct drafts.
-				// Composition lives in core.ts, shared with the golden-pin test.
-				editorAdCreateKey(args),
-			);
-			const slug = created.data.slug;
-			const started = await client.post<{ data: unknown }>(
-				`/editor/${slug}/autopilot`,
-				undefined,
-				// 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
-				// field set/order differs from make_video / start_autopilot on
-				// purpose (server cache is path+key scoped, slug is unique per
-				// draft), so the keys are not interchangeable across tools.
-				// Composition lives in core.ts, shared with the golden-pin test.
-				editorAdAutopilotKey(slug, args),
-			);
-			const status = normalizeStatus("editor", slug, asRecord(started).data);
-			return ok({ slug, kind: "editor", status, next: "wait_for_completion" });
+				// Validate every local asset before creating even a free draft, so a typo,
+				// traversal attempt, bad extension, or oversized logo cannot leave an
+				// orphaned project behind.
+				if (args.product_image_path) {
+					productImage = await prepareImageUpload(
+						args.product_image_path,
+						MAX_PRODUCT_IMAGE_BYTES,
+					);
+					prepared.push(productImage);
+				}
+				if (args.closing_image_path) {
+					closingImage = await prepareImageUpload(
+						args.closing_image_path,
+						MAX_CLOSING_IMAGE_BYTES,
+					);
+					prepared.push(closingImage);
+				}
+				if (args.logo_path) {
+					logo = await prepareImageUpload(args.logo_path, MAX_LOGO_BYTES);
+					prepared.push(logo);
+				}
+
+				const created = await client.post<{ data: { slug: string } }>(
+					"/editor",
+					{
+						language: args.language ?? "en",
+						product_prompt: args.product_prompt,
+						product_subject: args.product_subject,
+						project_intent: args.project_intent,
+						creative_format: args.creative_format,
+						visual_language: args.visual_language,
+						theme: args.theme,
+						voice_id: args.voice_id,
+						export_aspect_ratio: args.export_aspect_ratio,
+						cast_mode: args.cast_mode,
+					},
+					// Fold every create-affecting param into the key so two calls that
+					// differ only by style/theme/voice/aspect get distinct drafts.
+					// Composition lives in core.ts, shared with the golden-pin test.
+					editorAdCreateKey({
+						...args,
+						product_image_identity: productImage
+							? preparedUploadIdentity(productImage)
+							: undefined,
+						closing_image_identity: closingImage
+							? preparedUploadIdentity(closingImage)
+							: undefined,
+						logo_identity: logo ? preparedUploadIdentity(logo) : undefined,
+					}),
+				);
+				const slug = created.data.slug;
+				let configured = {} as Record<string, unknown>;
+				if (
+					args.product_image_path ||
+					args.closing_image_path ||
+					args.logo_path
+				) {
+					const current = await client.get<{ data: unknown }>(
+						`/editor/${slug}`,
+					);
+					configured = asRecord(asRecord(current).data);
+				}
+
+				if (productImage && !configured.product_url) {
+					const { s3_key } = await uploadImageFile(
+						client,
+						`/editor/${slug}/product/presign`,
+						productImage,
+						MAX_PRODUCT_IMAGE_BYTES,
+					);
+					await client.post(`/editor/${slug}/product/confirm`, {
+						s3_key,
+						product_description: args.product_description,
+					});
+				}
+				if (closingImage && !configured.closing_image_url) {
+					const { s3_key } = await uploadImageFile(
+						client,
+						`/editor/${slug}/closing-image/presign`,
+						closingImage,
+						MAX_CLOSING_IMAGE_BYTES,
+					);
+					await client.post(`/editor/${slug}/closing-image/confirm`, {
+						s3_key,
+					});
+				}
+				if (logo && !configured.logo_url) {
+					const { s3_key } = await uploadImageFile(
+						client,
+						`/editor/${slug}/logo/presign`,
+						logo,
+						MAX_LOGO_BYTES,
+					);
+					await client.post(`/editor/${slug}/logo/confirm`, { s3_key });
+				}
+				const logoSettings: Record<string, unknown> = {};
+				if (args.logo_treatment !== undefined)
+					logoSettings.logo_treatment = args.logo_treatment;
+				if (args.logo_position !== undefined)
+					logoSettings.logo_position = args.logo_position;
+				if (args.logo_duration_seconds !== undefined)
+					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 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.`;
+					return ok({
+						slug,
+						kind: "editor",
+						...quote,
+						charged: false,
+						note,
+						next: "start_autopilot",
+					});
+				}
+
+				const started = await client.post<{ data: unknown }>(
+					`/editor/${slug}/autopilot`,
+					{ max_credits: args.max_credits },
+					// 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
+					// field set/order differs from make_video / start_autopilot on
+					// purpose (server cache is path+key scoped, slug is unique per
+					// draft), so the keys are not interchangeable across tools.
+					// Composition lives in core.ts, shared with the golden-pin test.
+					editorAdAutopilotKey(slug, args),
+				);
+				const status = normalizeStatus("editor", slug, asRecord(started).data);
+				return ok({
+					slug,
+					kind: "editor",
+					status,
+					...quote,
+					charged: true,
+					next: "wait_for_completion",
+				});
+			} finally {
+				await Promise.all(prepared.map(closePreparedUploadFile));
+			}
 		},
 	),
 );
@@ -2951,10 +3304,11 @@ registerTool(
 		title: "Start autopilot on an existing editor draft",
 		description:
 			"Starts server-orchestrated autopilot (scenario → segments → narration → voice → music → render) on an " +
-			"EXISTING editor project/draft. Spends credits — preview the estimate first with the autopilot/cost endpoint " +
-			"or make_video({ dry_run:true }). Each call is a genuine start attempt (like tapping Launch in the app): " +
+			"EXISTING editor project/draft. Without max_credits it returns the live quote and charges nothing. Supply an " +
+			"explicit max_credits cap to authorize launch; the tool refuses if pricing is unavailable, the estimate exceeds " +
+			"the cap, or the balance is insufficient. Each authorized call is a genuine start attempt (like tapping Launch in the app): " +
 			"if a run is already in progress for this slug the server returns already_running — it never double-starts " +
-			"or double-charges. Once finished, failed, or cancelled, calling again relaunches it (resume after a top-up, raising your spend cap, or a mid-pipeline failure). Then poll with " +
+			"or double-charges. Failed or cancelled runs resume normally. For a completed project, set restart:true to quote and build a fresh creative run; omitting it only resumes pending edits. Then poll with " +
 			'wait_for_completion({ slug, kind: "editor" }).',
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
@@ -2977,7 +3331,22 @@ registerTool(
 				.string()
 				.optional()
 				.describe("Optional freeform brief to set/replace before launch."),
+			max_credits: z
+				.number()
+				.int()
+				.nonnegative()
+				.optional()
+				.describe(
+					"Explicit spend cap. Omit to quote only; no credits are charged.",
+				),
+			restart: z
+				.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.",
+				),
 		},
+		outputSchema: createEditorOutput,
 		annotations: { title: "Start autopilot", ...WRITE, idempotentHint: false },
 	},
 	tool(
@@ -2987,6 +3356,8 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				max_credits?: number;
+				restart?: boolean;
 			},
 			client,
 		) => {
@@ -2996,16 +3367,49 @@ registerTool(
 			if (promptErr) return fail(promptErr);
 
 			const slug = args.slug;
-			const overrides: Record<string, unknown> = {};
+			const overrides: {
+				language?: string;
+				product_subject?: string;
+				product_prompt?: string;
+				restart?: boolean;
+			} = {};
 			if (args.language !== undefined) overrides.language = args.language;
 			if (args.product_subject !== undefined)
 				overrides.product_subject = args.product_subject;
 			if (args.product_prompt !== undefined)
 				overrides.product_prompt = args.product_prompt;
+			if (args.restart) overrides.restart = true;
+
+			const quote = await editorAutopilotQuote(client, slug, overrides);
+			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
+			) {
+				return ok({
+					slug,
+					kind: "editor",
+					...quote,
+					charged: false,
+					note:
+						args.max_credits === undefined
+							? `Quote only: estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}). Pass max_credits to authorize launch.`
+							: quote.estimated_credits === null
+								? "Pricing is unavailable; launch refused because the spend cap cannot be enforced."
+								: 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.`,
+				});
+			}
 
 			const started = await client.post<{ data: unknown }>(
 				`/editor/${slug}/autopilot`,
-				Object.keys(overrides).length > 0 ? overrides : undefined,
+				{ ...overrides, max_credits: args.max_credits },
 				// Each call is a genuine new start attempt (matching the in-app Launch
 				// button). A per-invocation nonce makes the idempotency key unique so the
 				// server's 24h idempotency cache can't replay a PRIOR start's response on
@@ -3020,6 +3424,8 @@ registerTool(
 				slug,
 				kind: "editor",
 				status,
+				...quote,
+				charged: true,
 				next: "wait_for_completion",
 			});
 		},
@@ -3087,7 +3493,7 @@ registerTool(
 		title: "Create an editor draft (no autopilot)",
 		description:
 			"Creates an editor project from a product prompt and stops (NO autopilot). Costs 0 credits. Returns the " +
-			"slug. Use this to drive the pipeline step by step (vs create_editor_ad which runs autopilot end to end). " +
+			"slug. Use this to drive the pipeline step by step (vs create_editor_ad which configures, quotes, and can launch autopilot with a spend cap). " +
 			"Each AI-generated scene renders to a fixed 8 seconds (uploaded clips keep their own length). " +
 			"product_prompt is optional content: send 10–5000 chars, or omit it entirely (empty is treated as omit).",
 		inputSchema: {
@@ -3654,7 +4060,15 @@ registerTool(
 				args.prompt !== undefined ? { prompt: args.prompt } : undefined,
 				undefined,
 			);
-			return ok(asRecord(res).data ?? res);
+			return ok({
+				...asRecord(asRecord(res).data ?? res),
+				charge_receipt: await editorChargeReceipt(
+					client,
+					args.slug,
+					"scene_regeneration",
+					4,
+				),
+			});
 		},
 	),
 );
@@ -3863,7 +4277,15 @@ registerTool(
 			{ voice_id: args.voice_id },
 			await voiceKey(client, args.slug, args.voice_id),
 		);
-		return ok(asRecord(res).data ?? res);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			charge_receipt: await editorChargeReceipt(
+				client,
+				args.slug,
+				"voice_generation",
+				3,
+			),
+		});
 	}),
 );
 
@@ -3911,7 +4333,15 @@ registerTool(
 				body,
 				undefined,
 			);
-			return ok(asRecord(res).data ?? res);
+			return ok({
+				...asRecord(asRecord(res).data ?? res),
+				charge_receipt: await editorChargeReceipt(
+					client,
+					args.slug,
+					"music_generation",
+					5,
+				),
+			});
 		},
 	),
 );
@@ -3922,7 +4352,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). Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " +
+			"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.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
@@ -4168,7 +4599,7 @@ registerTool(
 			"duration. Runs presign → PUT (resumable multipart for large files) → confirm, then polls until the " +
 			"upload is processed (ready). file_path is a LOCAL path confined to HUBFLUENCER_INPUT_DIR (or cwd). Accepted: " +
 			VIDEO_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤500 MB, ≤5 min). Costs 0 credits. If add_to_timeline is false (default true) the clip is uploaded but not " +
+			" (≤500 MB decimal = 500,000,000 bytes, ≤5 min). Costs 0 credits. If add_to_timeline is false (default true) the clip is uploaded but not " +
 			"placed — call add_segment_from_upload later.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
@@ -4315,7 +4746,8 @@ registerTool(
 		description:
 			"Sets a specific scene's video from an existing asset — either a ready upload (upload_id) OR a completed scene " +
 			"in the same project (source_segment_id). Provide EXACTLY ONE. 0 credits. Use it to reuse one uploaded clip " +
-			"across scenes, or to swap a generated scene for your own footage.",
+			"across scenes, or to swap a generated scene for your own footage. The response includes continuity impact and " +
+			"current narration/voice/music staleness. If the replacement duration differs, regenerate stale audio before render.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			segment_id: z
@@ -4358,7 +4790,58 @@ registerTool(
 				`/editor/${args.slug}/segments/${String(args.segment_id)}/use-asset`,
 				body,
 			);
-			return ok(asRecord(res).data ?? res);
+			const segment = asRecord(asRecord(res).data ?? res);
+			const impact = asRecord(segment.impact);
+			const staleSegmentIds = Array.isArray(impact.stale_video_segment_ids)
+				? impact.stale_video_segment_ids
+				: [];
+			const requiresRegeneration =
+				impact.requires_regeneration === true || staleSegmentIds.length > 0;
+			// The swap has already SUCCEEDED (the POST above returned). The follow-up
+			// GET only enriches the response with project-level audio staleness — a
+			// transient failure on that read must NOT turn a successful swap into a
+			// thrown error, or the agent would believe the swap failed and retry it,
+			// minting a redundant segment version. Guard it: on failure return success
+			// with the mutation's own impact data and audio-staleness marked unknown
+			// (null) rather than propagating.
+			let timeline: Record<string, unknown>;
+			try {
+				const current = await client.get<{ data: unknown }>(
+					`/editor/${args.slug}`,
+				);
+				const editor = asRecord(asRecord(current).data);
+				timeline = {
+					narration_stale: editor.narration_stale === true,
+					voice_stale: editor.voice_stale === true,
+					music_stale: editor.music_stale === true,
+					stale_segment_ids: staleSegmentIds,
+					requires_regeneration: requiresRegeneration,
+				};
+			} catch {
+				timeline = {
+					// Enrichment GET failed after a successful swap — audio staleness is
+					// unknown (null, not false) so the agent doesn't assume "not stale".
+					narration_stale: null,
+					voice_stale: null,
+					music_stale: null,
+					stale_segment_ids: staleSegmentIds,
+					requires_regeneration: requiresRegeneration,
+					enrichment_unavailable: true,
+				};
+			}
+			return ok({
+				...segment,
+				timeline,
+				next:
+					timeline.requires_regeneration ||
+					timeline.narration_stale ||
+					timeline.voice_stale ||
+					timeline.music_stale
+						? "Regenerate the reported stale scenes/audio before render."
+						: timeline.enrichment_unavailable
+							? "Scene swap succeeded, but audio staleness could not be verified (enrichment fetch failed) — call get_status before render to confirm."
+							: "Timeline is current and can be rendered.",
+			});
 		},
 	),
 );
@@ -4370,7 +4853,7 @@ registerTool(
 		description:
 			"Uploads a local product image and attaches it to the project as the product. Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " +
+			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " +
 			"defaults every pending AI scene to feature it 'throughout' (change with set_product_placement). Optional " +
 			"description (≤500 chars) guides how it's woven into scenes.",
 		inputSchema: {
@@ -4395,6 +4878,7 @@ registerTool(
 				client,
 				`/editor/${args.slug}/product/presign`,
 				args.file_path,
+				MAX_PRODUCT_IMAGE_BYTES,
 			);
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/product/confirm`,
@@ -4437,7 +4921,7 @@ registerTool(
 	{
 		title: "Set the closing-card image (0 credits)",
 		description:
-			"Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MB, confined " +
+			"Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MiB, confined " +
 			"to HUBFLUENCER_INPUT_DIR/cwd) OR reuse the project's product image (from_product:true — a 0-credit server-side " +
 			"copy, no upload). If a closing image already exists, pass overwrite:true to replace it (else " +
 			"editor_closing_image_exists).",
@@ -4488,6 +4972,7 @@ registerTool(
 				client,
 				`/editor/${args.slug}/closing-image/presign`,
 				args.file_path,
+				MAX_CLOSING_IMAGE_BYTES,
 			);
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/closing-image/confirm`,
@@ -4503,7 +4988,7 @@ registerTool(
 	{
 		title: "Set a brand logo overlay (0 credits)",
 		description:
-			"Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤20 MB; PNG keeps " +
+			"Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤1 MiB; PNG keeps " +
 			"transparency), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. Optional placement controls: treatment, " +
 			"position, duration_seconds.",
 		inputSchema: {
@@ -4533,6 +5018,7 @@ registerTool(
 				client,
 				`/editor/${args.slug}/logo/presign`,
 				args.file_path,
+				MAX_LOGO_BYTES,
 			);
 			const confirmed = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/logo/confirm`,
@@ -4571,7 +5057,7 @@ registerTool(
 			"Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " +
 			"Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " +
+			" (≤20 MiB = 20,971,520 bytes), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " +
 			"(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " +
 			"(This is the shorts equivalent of set_product for editor projects.)",
 		inputSchema: {
@@ -4618,7 +5104,7 @@ registerTool(
 			"Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " +
 			"render from 12s to 14s). Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤20 MB), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
+			" (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
 			"again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
 		inputSchema: {
 			slug: z.string().describe("Short slug (from create_short)"),
@@ -4688,8 +5174,13 @@ registerTool(
 	{
 		title: "Wait for a render to finish",
 		description:
-			"Polls status (emitting progress) until terminal (ready/failed) or the wait budget is exhausted. " +
+			"Polls status (emitting progress) until terminal or the wait budget is exhausted. " +
 			"Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " +
+			"terminal=true does NOT always mean ready=true: an editor can go terminal in a needs-action stage " +
+			'(stage "editing_required" — a delivered render is stale after edits, regenerate the reported scenes/audio; ' +
+			'stage "insufficient_credits" — a batch is parked, top up or reduce scope; ' +
+			'stage "idle" — a draft with nothing generating, start generation first) that only a further tool call ' +
+			"can advance — do NOT just re-poll those. " +
 			"Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render). " +
 			'Works for kind:"slider" too, but a carousel has no MP4 — it just goes terminal when composited; read the slide ' +
 			"images with get_slider (save_path is ignored for sliders).",
@@ -6065,7 +6556,7 @@ registerTool(
 		return ok({
 			...episode,
 			next: episode.draft_slug
-				? "Generate this draft EXPLICITLY (a separate, PAID step): editor_ad/short → start_autopilot({ slug }); carousel → generate_slider({ slug })."
+				? "Price this draft with start_autopilot({ slug }); after approval launch it with start_autopilot({ slug, max_credits: approved_cap }). Carousel generation remains a separate paid generate_slider call."
 				: "Draft created — review it with list_series_episodes.",
 		});
 	}),
@@ -6872,7 +7363,7 @@ registerTool(
 		title: "Upload a local file to your reusable asset catalog",
 		description:
 			"Uploads a local IMAGE or VIDEO into your reusable asset catalog so it can be reused across projects. " +
-			`Allowed types: ${CATALOG_ASSET_EXTS.map((e) => `.${e}`).join(", ")} — images ≤20 MiB, videos ≤500 MB. ` +
+			`Allowed types: ${CATALOG_ASSET_EXTS.map((e) => `.${e}`).join(", ")} — images ≤20 MiB (20,971,520 bytes), videos ≤500 MB decimal (500,000,000 bytes). ` +
 			"Runs presign → PUT → confirm; the confirm HEADs the object and validates size/type, so a mismatch 422s. " +
 			"For a VIDEO you MUST pass duration_seconds (≤60; the server rejects a video with no/over-long duration). " +
 			"Spends 0 credits. Scope: video:generate. Rate limit: 30/min. Requires an ACTIVE SUBSCRIPTION (402 " +