@hubfluencer/mcp 0.9.1 → 0.11.0

package/package.json

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

@@ -265,6 +265,16 @@ export interface NormalizedStatus {
 	ready: boolean;
 	video_url: string | null;
 	error: string | null;
+	/** Short only: exact API failure phase instead of a collapsed terminal state. */
+	failed_stage?: string;
+	/** Short only: stable machine-readable terminal failure classification. */
+	failure_code?: string;
+	/** Short only: structured provider/QC details for recovery decisions. */
+	failure_details?: Record<string, unknown>;
+	/** Short only: worker/recovery layer that finalized the failed attempt. */
+	failure_source?: string;
+	/** Short only: paid generation attempt number that failed. */
+	failure_attempt?: number;
 	/** Editor only: the newest delivered render no longer matches the live project. */
 	stale?: boolean;
 	/** Editor only: current scene ids that are still generating. */
@@ -341,6 +351,16 @@ export function normalizeStatus(
 			video_url: videoUrl,
 			error: (d.error_message as string) ?? null,
 		};
+		if (typeof d.failed_stage === "string")
+			status.failed_stage = d.failed_stage;
+		if (typeof d.failure_code === "string")
+			status.failure_code = d.failure_code;
+		if (d.failure_details && typeof d.failure_details === "object")
+			status.failure_details = d.failure_details as Record<string, unknown>;
+		if (typeof d.failure_source === "string")
+			status.failure_source = d.failure_source;
+		if (typeof d.failure_attempt === "number")
+			status.failure_attempt = d.failure_attempt;
 		// 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
@@ -437,15 +457,14 @@ export function normalizeStatus(
 	);
 	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.
+	// awaiting_previews (previews generating), and running. "queued" is not a real
+	// value and was dropped. paused_for_retry is deliberately NOT active: no worker
+	// owns it until the user explicitly retries or cancels the paused batch.
 	const batchActive =
 		batchStatus === "running" ||
 		batchStatus === "preparing" ||
-		batchStatus === "awaiting_previews" ||
-		batchStatus === "paused_for_retry";
+		batchStatus === "awaiting_previews";
+	const batchRetryRequired = 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).
@@ -546,14 +565,39 @@ export function normalizeStatus(
 		currentMusic.status === "processing" ||
 		newerAudioVersions.some(versionActive) ||
 		newerMusicVersions.some(versionActive);
-	const workActive =
-		autopilotActive ||
+	const childWorkActive =
 		batchActive ||
 		renderActive ||
 		scenarioActive ||
 		narrationActive ||
 		audioActive ||
 		activeSegments.length > 0;
+	// A resumed Autopilot briefly exposes the previous attempt's failed child
+	// states before its new worker reaches and clears them. Suppress that history
+	// only while real child work is active or for a short, timestamped hand-off
+	// window. A parent stuck "running" with no worker must eventually surface the
+	// child failure instead of making wait_for_completion poll forever.
+	const autopilotStartedAt =
+		typeof d.autopilot_started_at === "string"
+			? Date.parse(d.autopilot_started_at)
+			: Number.NaN;
+	const now = Date.now();
+	const autopilotResumeGraceActive =
+		autopilotActive &&
+		Number.isFinite(autopilotStartedAt) &&
+		autopilotStartedAt <= now &&
+		now - autopilotStartedAt <= 120_000;
+	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
+	// Retrying a paused batch deliberately leaves the failed parent Autopilot
+	// marker in place while the already-paid child batch finishes. In that one
+	// state combination the parent/old scene failures are history, not a reason
+	// to return terminal immediately. Once the batch settles, the parent failure
+	// becomes actionable again and the agent can quote/relaunch Autopilot.
+	const batchRecoveryActive = autopilotFailed && batchActive;
+	const childFailureActionable =
+		!batchRecoveryActive &&
+		(!autopilotActive || (!childWorkActive && !autopilotResumeGraceActive));
+	const workActive = autopilotActive || childWorkActive;
 	// Orchestration failures are historical once a repaired timeline has a fresh,
 	// completed MP4. Keeping them terminal would permanently block download_result
 	// after a successful granular recovery.
@@ -566,17 +610,26 @@ export function normalizeStatus(
 		failedSegments.length === 0 &&
 		!audioFailed;
 	const ready = deliveredArtifactSupersedesOrchestrationFailure;
-	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
-	const renderFailed = renderStatus === "failed";
+	const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
+	const renderFailed = renderStatus === "failed" && childFailureActionable;
 	const failed =
-		(autopilotFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
+		(parentFailureActionable &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
 		renderFailed ||
-		(scenarioApplyFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		(scenarioFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		(narrationFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		(batchFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		failedSegments.length > 0 ||
-		audioFailed;
+		(childFailureActionable &&
+			scenarioApplyFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable &&
+			scenarioFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable &&
+			narrationFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable &&
+			batchFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable && failedSegments.length > 0) ||
+		(childFailureActionable && 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
@@ -585,21 +638,35 @@ export function normalizeStatus(
 	// 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;
+	const terminal =
+		ready ||
+		failed ||
+		batchRetryRequired ||
+		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 (ready) stage = "completed";
-	else if (autopilot === "failed") stage = "failed";
-	else if (autopilot === "cancelled") stage = "cancelled";
+	// A paused child batch is the immediate recovery gate even when its parent
+	// Autopilot run has already failed/cancelled. Reporting only the generic
+	// parent terminal state hides the one action that must happen before a new
+	// Autopilot run is allowed to start.
+	else if (batchRetryRequired) stage = "batch_retry_required";
+	else if (parentFailureActionable && autopilot === "failed") stage = "failed";
+	else if (parentFailureActionable && 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 (childFailureActionable && scenarioApplyFailed)
+		stage = "scenario_apply_failed";
+	else if (childFailureActionable && scenarioFailed) stage = "scenario_failed";
+	else if (childFailureActionable && narrationFailed)
+		stage = "narration_failed";
+	else if (childFailureActionable && batchFailed) stage = "batch_failed";
+	else if (childFailureActionable && failedSegments.length > 0)
+		stage = "segment_failed";
+	else if (childFailureActionable && audioFailed) stage = "audio_failed";
 	else if (batchInsufficientCredits) stage = "insufficient_credits";
 	else if (activeSegments.length > 0) stage = "segment_processing";
 	else if (batchActive) stage = "segment_generation";
@@ -613,6 +680,15 @@ export function normalizeStatus(
 		.find(
 			(value): value is string => typeof value === "string" && value.length > 0,
 		);
+	const actionableChildError = childFailureActionable
+		? ((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)
+		: null;
 	return {
 		kind,
 		slug,
@@ -622,17 +698,15 @@ export function normalizeStatus(
 		video_url: videoUrl,
 		error: ready
 			? null
-			: ((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)),
+			: batchRetryRequired
+				? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing."
+				: ((parentFailureActionable
+						? (d.autopilot_error_message as string)
+						: null) ??
+					actionableChildError ??
+					(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)