@hubfluencer/mcp 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.8.1",
+  "version": "0.9.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/campaign.ts

@@ -686,7 +686,7 @@ export async function runCreateCampaign(
 		items,
 		summary,
 		steps,
-		next: `get_campaign_pack({ id: ${campaignPackId} }) to review the drafts; then, for EACH draft you want to publish, generate it EXPLICITLY (a SEPARATE, PAID step): editor_ad/short → start_autopilot({ slug }) or the granular generate/render tools; carousel → generate_slider({ slug }).`,
+		next: `get_campaign_pack({ id: ${campaignPackId} }) to review the drafts; then quote each editor draft with start_autopilot({ slug }) and, after approval, launch with start_autopilot({ slug, max_credits: approved_cap }); use generate_short/generate_slider for approved short/carousel drafts.`,
 		note:
 			`Campaign pack ${campaignPackId} created with ${summary.created} item(s), ${draftable} materialized into editable DRAFTS. ` +
 			(positioning ? `Positioning: ${positioning}. ` : "") +

package/src/client.ts

@@ -251,7 +251,10 @@ export class HubfluencerClient {
 					);
 				}
 				throw e instanceof Error
-					? new Error(`Network error on ${method} ${path}: ${e.message}`)
+					? Object.assign(
+							new Error(`Network error on ${method} ${path}: ${e.message}`),
+							{ retryable: isRetryableNetworkError(e) },
+						)
 					: e;
 			}
 

package/src/core.ts

@@ -265,6 +265,20 @@ export interface NormalizedStatus {
 	ready: boolean;
 	video_url: string | null;
 	error: string | null;
+	/** Editor only: the newest delivered render no longer matches the live project. */
+	stale?: boolean;
+	/** Editor only: current scene ids that are still generating. */
+	active_segment_ids?: Array<number | string>;
+	/** Editor only: completed current scene ids invalidated by continuity edits. */
+	stale_segment_ids?: Array<number | string>;
+	/** Short only (additive, absent on older APIs): the newest render row is a free re-render. */
+	latest_render_free?: boolean;
+	/**
+	 * Short only (additive): the newest render row is a FAILED free re-render.
+	 * The delivered video stays intact (stage/latest_render fall back to the
+	 * latest completed render), so the agent can just retry rerender_short — free.
+	 */
+	last_free_rerender_failed?: boolean;
 }
 
 /** The structured fields of an API error envelope errMessage formats from. */
@@ -318,7 +332,7 @@ export function normalizeStatus(
 
 	if (kind === "short") {
 		const stage = (d.stage as string) ?? "unknown";
-		return {
+		const status: NormalizedStatus = {
 			kind,
 			slug,
 			stage,
@@ -327,6 +341,19 @@ export function normalizeStatus(
 			video_url: videoUrl,
 			error: (d.error_message as string) ?? null,
 		};
+		// Additive free-re-render bookkeeping (2026-07 API): surfaced only when
+		// the server actually sends the booleans, so older payloads normalize
+		// byte-identically. A failed free re-render does NOT flip stage to
+		// "failed" server-side — the delivered video stays visible — so these
+		// flags are the only signal that the newest render row was a free
+		// re-render (or a failed one worth retrying, still free).
+		if (typeof d.latest_render_free === "boolean") {
+			status.latest_render_free = d.latest_render_free;
+		}
+		if (typeof d.last_free_rerender_failed === "boolean") {
+			status.last_free_rerender_failed = d.last_free_rerender_failed;
+		}
+		return status;
 	}
 
 	if (kind === "tracking") {
@@ -374,23 +401,249 @@ export function normalizeStatus(
 		};
 	}
 
-	// editor
+	// editor. A completed render is only "ready" when it still represents the
+	// CURRENT timeline and no newer scene/audio work is active or stale. The API
+	// intentionally keeps the last successful MP4 available after edits; treating
+	// that historical delivery as current made get_status/wait_for_completion
+	// return immediately while paid regenerations were still running.
 	const autopilot = (d.autopilot_status as string) ?? "unknown";
 	const renderStatus = (latest.status as string) ?? null;
-	const ready = renderStatus === "completed" && Boolean(videoUrl);
-	const terminal =
-		ready ||
-		autopilot === "failed" ||
-		autopilot === "cancelled" ||
-		renderStatus === "failed";
+	const segments = Array.isArray(d.segments) ? d.segments.map(asRecord) : [];
+	// "Active" means a scene is genuinely mid-generation. Crucially it must NOT
+	// include the *idle* defaults: segment.status "pending" and preview_status
+	// "pending" are the never-generated / cleared-preview defaults the API stamps
+	// on every fresh scene (video_segment.ex: status default "pending",
+	// preview_status default "pending"). Counting either as active made a fully
+	// idle draft report stage "segment_processing" with every scene in
+	// active_segment_ids, so wait_for_completion burned its whole budget on a
+	// project that isn't generating anything. The real in-flight states are
+	// segment.status "processing" and preview_status "generating" (its wire enum
+	// is pending|generating|completed|failed|stale — "processing" is kept only as
+	// a defensive alias, it never appears).
+	const activeSegments = segments.filter((segment) => {
+		const status = segment.status as string | undefined;
+		const preview = segment.preview_status as string | undefined;
+		return (
+			status === "processing" ||
+			preview === "processing" ||
+			preview === "generating"
+		);
+	});
+	const staleSegments = segments.filter(
+		(segment) => segment.video_stale === true && segment.status === "completed",
+	);
+	const failedSegments = segments.filter(
+		(segment) => segment.status === "failed",
+	);
+	const batchStatus = (d.batch_generation_status as string) ?? null;
+	// The batch enum's ACTIVE states (video_factory.ex): preparing (spinning up),
+	// awaiting_previews (previews generating), running, and paused_for_retry
+	// (auto-resuming). "queued" is not a real value and was dropped; "preparing"
+	// and "awaiting_previews" were missing, so an in-flight batch briefly looked
+	// idle and could be reported terminal mid-run.
+	const batchActive =
+		batchStatus === "running" ||
+		batchStatus === "preparing" ||
+		batchStatus === "awaiting_previews" ||
+		batchStatus === "paused_for_retry";
+	// A parked batch that ran out of credits: it cannot progress without the user
+	// topping up or reducing scope, so it is a needs-user-action TERMINAL state
+	// (not active work to wait on).
+	const batchInsufficientCredits =
+		batchStatus === "paused_insufficient_credits";
+	const batchFailed = batchStatus === "failed";
+	const autopilotActive = [
+		"pending",
+		"running",
+		"generating",
+		"rendering",
+	].includes(autopilot);
+	const audioStale =
+		d.narration_stale === true ||
+		d.voice_stale === true ||
+		d.music_stale === true;
+	const renderStale = latest.is_stale === true;
+	// Only an explicit false proves the completed render matches the live editor.
+	// 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 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
+	// a render was actually requested, so a pending latest render is queued work.
+	const renderActive =
+		renderStatus === "pending" ||
+		renderStatus === "rendering" ||
+		renderStatus === "processing";
+	// Scenario text generation / scenario apply run as async workers too
+	// (scenario_status: none|generating|ready|failed; scenario_apply_status:
+	// idle|applying|failed) — count them as active so a wait right after
+	// generate_scenario/apply_scenario doesn't bail out as an "idle" draft.
+	const scenarioActive =
+		d.scenario_status === "generating" ||
+		d.scenario_apply_status === "applying";
+	// Narration generation is a distinct async worker that runs before an
+	// AudioVersion exists. Without this gate, a project with an older completed
+	// render looks ready/terminal during narration regeneration and
+	// wait_for_completion can return that old MP4 while the new script is still
+	// being produced.
+	const narrationActive = d.narration_status === "generating";
+	const scenarioFailed = d.scenario_status === "failed";
+	const scenarioApplyFailed = d.scenario_apply_status === "failed";
+	const narrationFailed = d.narration_status === "failed";
+	// First-time generation is visible through the current selection. A
+	// regeneration intentionally keeps the prior completed version current until
+	// the replacement lands, so inspect the version histories as well; otherwise
+	// an old matching render can look ready while a paid replacement is running.
+	const currentAudio = asRecord(d.current_audio);
+	const currentMusic = asRecord(d.current_music);
+	const audioVersions = Array.isArray(d.audio_versions)
+		? d.audio_versions.map(asRecord)
+		: [];
+	const musicVersions = Array.isArray(d.music_versions)
+		? d.music_versions.map(asRecord)
+		: [];
+	const numericVersion = (version: unknown): number =>
+		typeof version === "number" && Number.isFinite(version) ? version : 0;
+	const selectedAudioVersion = numericVersion(currentAudio.version);
+	const selectedMusicVersion = numericVersion(currentMusic.version);
+	const newerAudioVersions = audioVersions.filter(
+		(version) => numericVersion(version.version) > selectedAudioVersion,
+	);
+	const newerMusicVersions = musicVersions.filter(
+		(version) => numericVersion(version.version) > selectedMusicVersion,
+	);
+	const versionActive = (version: Record<string, unknown>) =>
+		version.status === "pending" || version.status === "processing";
+	const newestVersion = (versions: Array<Record<string, unknown>>) =>
+		versions.reduce<Record<string, unknown> | null>((latest, version) => {
+			if (!latest) return version;
+			return numericVersion(version.version) > numericVersion(latest.version)
+				? version
+				: latest;
+		}, null);
+	const newestReplacementAudio = newestVersion(newerAudioVersions);
+	const newestReplacementMusic = newestVersion(newerMusicVersions);
+	const audioFailed =
+		currentAudio.status === "failed" ||
+		currentMusic.status === "failed" ||
+		newestReplacementAudio?.status === "failed" ||
+		newestReplacementMusic?.status === "failed";
+	const audioError = [
+		newestReplacementAudio?.error_message,
+		newestReplacementMusic?.error_message,
+		currentAudio.error_message,
+		currentMusic.error_message,
+	].find(
+		(value): value is string =>
+			typeof value === "string" && value.trim().length > 0,
+	);
+	const audioActive =
+		currentAudio.status === "pending" ||
+		currentAudio.status === "processing" ||
+		currentMusic.status === "pending" ||
+		currentMusic.status === "processing" ||
+		newerAudioVersions.some(versionActive) ||
+		newerMusicVersions.some(versionActive);
+	const workActive =
+		autopilotActive ||
+		batchActive ||
+		renderActive ||
+		scenarioActive ||
+		narrationActive ||
+		audioActive ||
+		activeSegments.length > 0;
+	const ready =
+		renderStatus === "completed" &&
+		Boolean(videoUrl) &&
+		renderFresh &&
+		!stale &&
+		!workActive &&
+		failedSegments.length === 0 &&
+		!audioFailed &&
+		!scenarioFailed &&
+		!scenarioApplyFailed &&
+		!narrationFailed &&
+		!batchFailed;
+	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
+	const renderFailed = renderStatus === "failed";
+	const failed =
+		autopilotFailed ||
+		renderFailed ||
+		scenarioApplyFailed ||
+		scenarioFailed ||
+		narrationFailed ||
+		batchFailed ||
+		failedSegments.length > 0 ||
+		audioFailed;
+	// Terminal = control should return to the agent because nothing will progress
+	// without another tool call. With every async job type folded into workActive
+	// above (autopilot, batch, segments, scenario, narration, audio, render), NO
+	// work active means exactly that — whether the project is ready, failed,
+	// stale (editing_required), parked on credits, or a pristine idle draft, only
+	// a new tool call can move it, so wait_for_completion must return instead of
+	// polling its full budget. (ready is subsumed by !workActive but kept for
+	// clarity; explicit failure states are terminal even while cleanup work spins.)
+	const terminal = ready || failed || batchInsufficientCredits || !workActive;
+	let stage = autopilot;
+	// Failure always wins over an unrelated active flag. Workers can leave an
+	// outer autopilot/batch state active after a child stage has failed; reporting
+	// the active stage would make agents poll forever instead of taking action.
+	if (autopilot === "failed") stage = "failed";
+	else if (autopilot === "cancelled") stage = "cancelled";
+	else if (renderFailed) stage = "render_failed";
+	else if (scenarioApplyFailed) stage = "scenario_apply_failed";
+	else if (scenarioFailed) stage = "scenario_failed";
+	else if (narrationFailed) stage = "narration_failed";
+	else if (batchFailed) stage = "batch_failed";
+	else if (failedSegments.length > 0) stage = "segment_failed";
+	else if (audioFailed) stage = "audio_failed";
+	else if (batchInsufficientCredits) stage = "insufficient_credits";
+	else if (activeSegments.length > 0) stage = "segment_processing";
+	else if (batchActive) stage = "segment_generation";
+	else if (renderActive) stage = "rendering";
+	else if (scenarioActive) stage = "scenario_processing";
+	else if (narrationActive) stage = "narration_processing";
+	else if (audioActive) stage = "audio_processing";
+	else if (!workActive && stale) stage = "editing_required";
+	else if (ready) stage = "completed";
+	const segmentError = failedSegments
+		.map((segment) => segment.error_message)
+		.find(
+			(value): value is string => typeof value === "string" && value.length > 0,
+		);
 	return {
 		kind,
 		slug,
-		stage: autopilot,
+		stage,
 		terminal,
 		ready,
 		video_url: videoUrl,
-		error: (d.autopilot_error_message as string) ?? null,
+		error:
+			(d.autopilot_error_message as string) ??
+			(latest.error_message as string) ??
+			(d.scenario_apply_error_message as string) ??
+			(d.scenario_error_message as string) ??
+			(d.narration_error_message as string) ??
+			(d.batch_generation_error_message as string) ??
+			segmentError ??
+			audioError ??
+			(batchInsufficientCredits
+				? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume."
+				: null),
+		stale,
+		active_segment_ids: activeSegments
+			.map((segment) => segment.id)
+			.filter(
+				(id): id is number | string =>
+					typeof id === "number" || typeof id === "string",
+			),
+		stale_segment_ids: staleSegments
+			.map((segment) => segment.id)
+			.filter(
+				(id): id is number | string =>
+					typeof id === "number" || typeof id === "string",
+			),
 	};
 }
 
@@ -520,6 +773,26 @@ export interface EditorAdKeyArgs {
 	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?: string;
+	logo_position?: string;
+	logo_duration_seconds?: number;
+	cast_mode?: string;
+	/** Identities of the retained, pre-create asset byte snapshots. */
+	product_image_identity?: string;
+	closing_image_identity?: string;
+	logo_identity?: string;
+	/**
+	 * The approved spend cap forwarded to the launch POST. Folded into the
+	 * autopilot-start key ONLY (not the draft-create key) so that re-calling
+	 * create_editor_ad with a RAISED cap after a failed/over-cap launch mints a
+	 * fresh key and re-enqueues, instead of replaying the server's 24h-cached dead
+	 * 202 from the earlier lower-cap attempt.
+	 */
+	max_credits?: number;
 }
 
 /** create_editor_ad's editor draft-create key (`POST /editor`). */
@@ -535,14 +808,30 @@ export function editorAdCreateKey(a: EditorAdKeyArgs): string {
 		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),
+		a.cast_mode ?? "",
 	);
 }
 
 /**
  * create_editor_ad's autopilot-start key (`POST /editor/:slug/autopilot`). Folds
- * the create params (not a startState — this tool starts right after create, so
- * there is no prior terminal state to guard against) so it tracks the inputs, not
- * just the slug. Self-consistent per-tool only.
+ * the create params AND the approved max_credits cap. There is no startState
+ * discriminator (this tool starts right after create, so there is no prior
+ * terminal state to guard against), so max_credits is what lets a re-call with a
+ * RAISED cap after a failed/over-cap launch mint a fresh key and re-enqueue
+ * rather than replay the server's 24h-cached dead 202. Self-consistent per-tool
+ * only.
  */
 export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
 	return idemKey(
@@ -557,6 +846,17 @@ export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
 		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.cast_mode ?? "",
+		a.max_credits === undefined ? "" : String(a.max_credits),
 	);
 }
 
@@ -616,9 +916,22 @@ export function addSegmentKey(
  */
 export function resolveSavePath(savePath: string): string {
 	const base = resolve(process.env.HUBFLUENCER_OUTPUT_DIR || process.cwd());
-	const target = isAbsolute(savePath)
-		? resolve(savePath)
-		: resolve(base, savePath);
+	let target: string;
+	if (isAbsolute(savePath)) {
+		target = resolve(savePath);
+	} else {
+		// Accept both output-root-relative paths ("campaign/ad.mp4") and
+		// workspace-relative paths that already include the configured output
+		// directory ("videos/campaign/ad.mp4"). Always choose a candidate only
+		// when it remains confined to `base`; this fixes /videos/videos/... without
+		// weakening the traversal guard.
+		const workspaceCandidate = resolve(process.cwd(), savePath);
+		const workspaceCandidateInsideBase =
+			workspaceCandidate === base || workspaceCandidate.startsWith(base + sep);
+		target = workspaceCandidateInsideBase
+			? workspaceCandidate
+			: resolve(base, savePath);
+	}
 	if (!target.toLowerCase().endsWith(".mp4")) {
 		throw new Error("save_path must end in .mp4");
 	}