@hubfluencer/mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,2310 @@
+#!/usr/bin/env node
+/**
+ * Hubfluencer MCP server.
+ *
+ * Exposes a small, high-level tool set so an agent (e.g. Claude Code) can turn
+ * a text prompt into a finished, post-ready ad — without orchestrating the
+ * multi-step pipeline itself. Maps onto the public REST API; auth is an opaque
+ * bearer token passed through from the `HUBFLUENCER_API_TOKEN` env var.
+ *
+ *   One-shot : make_video({ prompt })  → finished MP4 (create→start→poll→download)
+ *   Shorts   : create_short → generate_short → wait_for_completion → download_result
+ *   Editor   : create_editor_ad (creates + starts autopilot) → wait_for_completion → download_result
+ *   Granular : create_editor_draft → generate_scenario|set_scenario → get_editor
+ *              → set_scene_count → set_segment_prompt → generate_segment(s)
+ *              → set_narration_script|generate_narration → generate_voice + generate_music
+ *              → render → wait_for_completion → download_result
+ */
+
+import { writeFile } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+	clientFromEnv,
+	type HubfluencerClient,
+	type HubfluencerError,
+} from "./client.js";
+import {
+	asRecord,
+	assertSafeFetchUrl,
+	idemKey,
+	inferKind,
+	type Kind,
+	type NormalizedStatus,
+	normalizeStatus,
+	resolveSavePath,
+} from "./core.js";
+import {
+	IMAGE_EXTS,
+	uploadImageFile,
+	uploadVideoFile,
+	VIDEO_EXTS,
+} from "./uploads.js";
+
+async function fetchStatus(
+	client: HubfluencerClient,
+	kind: Kind,
+	slug: string,
+): Promise<NormalizedStatus> {
+	const path = kind === "short" ? `/shorts/${slug}` : `/editor/${slug}`;
+	const res = await client.get<{ data: unknown }>(path);
+	return normalizeStatus(kind, slug, asRecord(res).data);
+}
+
+// The video_url comes back in API JSON — allow loopback http only when the API
+// base itself is local (dev), mirroring uploads.ts and the base-URL exception.
+const ALLOW_LOOPBACK_FETCH =
+	/^http:\/\/(localhost|127\.0\.0\.1|\[?::1\]?)/.test(
+		process.env.HUBFLUENCER_BASE_URL || "",
+	);
+
+async function downloadTo(
+	videoUrl: string,
+	savePath: string,
+): Promise<{ saved_to: string; bytes: number }> {
+	const target = resolveSavePath(savePath);
+	// The video_url is server-supplied — refuse an insecure or private/internal
+	// host so a compromised/MITM'd response can't drive an SSRF write to disk.
+	assertSafeFetchUrl(videoUrl, { allowLoopback: ALLOW_LOOPBACK_FETCH });
+	// Bound the download: a presigned URL could in theory hang or point at
+	// something huge, so cap both time and size instead of buffering blindly.
+	const MAX_BYTES = 1024 * 1024 * 1024; // 1 GB — generous for a short ad
+	const resp = await fetch(videoUrl, { signal: AbortSignal.timeout(120_000) });
+	if (!resp.ok)
+		throw new Error(`Failed to download video (HTTP ${resp.status}).`);
+	// Fast path: trust a present content-length to reject an oversize body before
+	// reading a single byte.
+	const declared = Number(resp.headers.get("content-length") ?? "");
+	if (Number.isFinite(declared) && declared > MAX_BYTES) {
+		throw new Error(
+			`Video is ${declared} bytes — over the ${MAX_BYTES}-byte download cap.`,
+		);
+	}
+	// Stream the body and abort as soon as the running total exceeds the cap, so
+	// a missing/lying content-length can't OOM the process by buffering blindly.
+	if (!resp.body) throw new Error("Download returned an empty body.");
+	const reader = resp.body.getReader();
+	const chunks: Buffer[] = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			total += value.byteLength;
+			if (total > MAX_BYTES) {
+				throw new Error(
+					`Video exceeds the ${MAX_BYTES}-byte download cap (aborted mid-stream).`,
+				);
+			}
+			chunks.push(Buffer.from(value));
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	const buf = Buffer.concat(chunks, total);
+	await writeFile(target, buf);
+	return { saved_to: target, bytes: buf.length };
+}
+
+/** An MCP `resource_link` content block — points at a media asset by URL. */
+type ResourceLink = {
+	type: "resource_link";
+	uri: string;
+	name: string;
+	mimeType?: string;
+	description?: string;
+};
+
+/**
+ * Wraps a tool's JSON payload as a text block (the universal fallback) and,
+ * alongside it, a `structuredContent` copy for clients that consume typed
+ * output — plus any media `resource_link`s. Text stays the source of truth so
+ * older clients keep working.
+ */
+function ok(payload: unknown, links: ResourceLink[] = []) {
+	const content: Array<{ type: "text"; text: string } | ResourceLink> = [
+		{ type: "text", text: JSON.stringify(payload, null, 2) },
+		...links,
+	];
+	const result: {
+		content: typeof content;
+		structuredContent?: Record<string, unknown>;
+	} = { content };
+	if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+		result.structuredContent = payload as Record<string, unknown>;
+	}
+	return result;
+}
+
+/** Builds a `resource_link` for a finished MP4 so clients can surface it as media. */
+function mp4Link(url: string, slug: string): ResourceLink {
+	return {
+		type: "resource_link",
+		uri: url,
+		name: `${slug}.mp4`,
+		mimeType: "video/mp4",
+		description: "Finished, post-ready MP4 (presigned, ~24h TTL).",
+	};
+}
+
+function fail(message: string) {
+	return { isError: true, content: [{ type: "text" as const, text: message }] };
+}
+
+function errMessage(e: unknown): string {
+	const he = e as HubfluencerError;
+	if (he && typeof he.status === "number") {
+		const base = `API error (HTTP ${he.status}${he.code ? `, ${he.code}` : ""}): ${he.message}`;
+		// Surface the structured credit fields the server attaches to 402s so the
+		// agent can report exactly how short it is instead of a bare sentence.
+		const body = he.body as Record<string, unknown> | undefined;
+		if (
+			body &&
+			(body.required_credits != null || body.available_credits != null)
+		) {
+			const req = body.required_credits;
+			const have = body.available_credits;
+			return `${base} (needs ${req ?? "?"} credits, have ${have ?? "?"}).`;
+		}
+		return base;
+	}
+	return e instanceof Error ? e.message : String(e);
+}
+
+/**
+ * Idempotency key for an unlock purchase, keyed on the CURRENT quota snapshot
+ * (used + bonus), which advances after every successful unlock.
+ *
+ * Why not a constant key: unlock is a *repeatable* purchase (1 credit → +10
+ * assists, call again for more). The server caches idempotent POSTs for 24h, so
+ * a constant key would make every later unlock replay the first response —
+ * silently no-op'ing the purchase (no credit spent, no assists added) while
+ * still returning 200. Snapshotting means a transport retry of the SAME unlock
+ * replays safely (no double-charge), but a DISTINCT "buy another batch" call
+ * gets a fresh key and executes. Falls back to no key (each call executes) if
+ * the snapshot can't be read — safer than risking a replayed no-op.
+ */
+async function unlockKey(client: HubfluencerClient): Promise<string> {
+	try {
+		const res = await client.get<{ data: unknown }>("/ai-assists");
+		const d = asRecord(asRecord(res).data);
+		return idemKey(
+			"unlock-ai-assists",
+			String(d.used ?? ""),
+			String(d.bonus ?? ""),
+		);
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Idempotency key for voice synthesis, keyed on the INPUTS that determine the
+ * output: the current narration script + the chosen voice. Voice TTS is
+ * deterministic, so replaying an identical (narration, voice) call is correct
+ * and free, while regenerating after the narration or voice changes gets a
+ * fresh key and actually re-runs — a fixed slug+voice key would replay stale
+ * audio for 24h after a narration edit. Falls back to no key on read failure.
+ */
+async function voiceKey(
+	client: HubfluencerClient,
+	slug: string,
+	voiceId: string,
+): Promise<string> {
+	try {
+		const res = await client.get<{ data: unknown }>(`/editor/${slug}`);
+		const d = asRecord(asRecord(res).data);
+		return idemKey(
+			"gen-voice",
+			slug,
+			voiceId,
+			String(d.narration_script ?? ""),
+		);
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Runs an assist-consuming call (`fn`), handling the daily AI-assist quota.
+ *
+ * AI assists are a free daily quota (20/day) shared by helper endpoints
+ * (generate-scenario, generate-narration, enhance-prompt, suggest-*). When the
+ * quota is exhausted the server returns 429 `ai_assist_quota_exceeded` with a
+ * structured body `{remaining, unlock_cost, can_unlock, ...}`.
+ *
+ * Behaviour (HARD CAP — at most one unlock + one retry, never a loop):
+ *   - 429 + autoUnlock=false → re-throw so the caller surfaces the structured
+ *     quota body to the agent (it can then unlock or write content itself).
+ *   - 429 + autoUnlock=true  → POST /ai-assists/unlock ONCE (1 credit → +10
+ *     assists), then retry `fn` ONCE. If unlock itself 402s
+ *     (credits_insufficient), throw — clean fail, no loop.
+ *   - any non-429 error → re-throw unchanged (402 credit errors flow straight
+ *     through to the caller's fail()).
+ */
+async function withAssist<T>(
+	client: HubfluencerClient,
+	autoUnlock: boolean,
+	fn: () => Promise<T>,
+): Promise<T> {
+	try {
+		return await fn();
+	} catch (e) {
+		const he = e as HubfluencerError;
+		if (!he || he.status !== 429) throw e;
+		if (!autoUnlock) throw e;
+		// One unlock (1 credit → +10 assists), then one retry. A 402 here means
+		// the account is out of credits — let it propagate to a clean fail().
+		await client.post("/ai-assists/unlock", undefined, await unlockKey(client));
+		return await fn();
+	}
+}
+
+interface ToolExtra {
+	_meta?: { progressToken?: string | number };
+	sendNotification?: (n: unknown) => Promise<void>;
+}
+
+/** Emits an MCP progress notification if the client requested one. Best-effort. */
+async function reportProgress(
+	extra: ToolExtra | undefined,
+	progress: number,
+	message: string,
+	total?: number,
+) {
+	const token = extra?._meta?.progressToken;
+	if (token === undefined || !extra?.sendNotification) return;
+	try {
+		await extra.sendNotification({
+			method: "notifications/progress",
+			params: { progressToken: token, progress, total, message },
+		});
+	} catch {
+		// progress is advisory — never fail the tool over it
+	}
+}
+
+/** Wraps a tool body with uniform client resolution + error handling. */
+function tool<A>(
+	fn: (
+		args: A,
+		client: HubfluencerClient,
+		extra: ToolExtra,
+	) => Promise<ReturnType<typeof ok>>,
+) {
+	// `extra` is the SDK's RequestHandlerExtra; typed loosely here and narrowed
+	// to ToolExtra internally to avoid coupling to SDK generic variance.
+	return async (args: A, extra: unknown) => {
+		let client: HubfluencerClient;
+		try {
+			client = clientFromEnv();
+		} catch (e) {
+			return fail(errMessage(e));
+		}
+		try {
+			return await fn(args, client, extra as ToolExtra);
+		} catch (e) {
+			return fail(errMessage(e));
+		}
+	};
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const kindSchema = z.enum(["short", "editor"]).describe("Project kind");
+
+const RO = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+const WRITE = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	openWorldHint: true,
+};
+
+const server = new McpServer({ name: "hubfluencer", version: "0.1.0" });
+
+// The SDK's `registerTool` is generic over the Zod input shape; with this many
+// tools its conditional types hit TS2589 ("excessively deep"). Inputs are still
+// validated by Zod at runtime (the real method runs); we bind it through a
+// loose, non-generic signature so the heavy generic never instantiates at
+// compile time. Handler arg types remain annotated per tool below.
+type LooseRegister = (
+	name: string,
+	config: object,
+	handler: (...args: never[]) => unknown,
+) => void;
+const registerTool = server.registerTool.bind(
+	server,
+) as unknown as LooseRegister;
+
+async function pollToTerminal(
+	client: HubfluencerClient,
+	kind: Kind,
+	slug: string,
+	extra: ToolExtra,
+	budgetMs: number,
+	intervalMs: number,
+): Promise<NormalizedStatus> {
+	const deadline = Date.now() + budgetMs;
+	let status = await fetchStatus(client, kind, slug);
+	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);
+	}
+	return status;
+}
+
+/**
+ * Polls ONE editor segment until it reaches a terminal state ("completed" or
+ * "failed"), or the budget runs out. Returns the segment's final status plus
+ * any error_message.
+ *
+ * generate_all_segments must gate each scene on its OWN completion — the
+ * editor-level status (normalizeStatus) only goes terminal on a finished/failed
+ * RENDER, which never happens mid-batch during granular generation, so polling
+ * the project status would burn the whole budget every iteration and never
+ * observe a failed scene. Segment status flows pending → processing →
+ * completed | failed (set server-side in editor/generation.ex).
+ */
+async function pollSegmentToTerminal(
+	client: HubfluencerClient,
+	slug: string,
+	segmentId: string | number,
+	extra: ToolExtra,
+	budgetMs: number,
+	intervalMs: number,
+): Promise<{ status: string; error: string | null; timed_out: boolean }> {
+	const deadline = Date.now() + budgetMs;
+	const sid = String(segmentId);
+	const read = async (): Promise<{ status: string; error: string | null }> => {
+		const res = await client.get<{ data: unknown }>(`/editor/${slug}`);
+		const data = asRecord(asRecord(res).data);
+		const segments = Array.isArray(data.segments)
+			? (data.segments as Record<string, unknown>[])
+			: [];
+		const seg = segments.find((s) => String(s.id) === sid);
+		return {
+			status: seg ? ((seg.status as string) ?? "unknown") : "unknown",
+			error: seg ? ((seg.error_message as string) ?? null) : null,
+		};
+	};
+	let n = 0;
+	let { status, error } = await read();
+	while (
+		status !== "completed" &&
+		status !== "failed" &&
+		Date.now() + intervalMs <= deadline
+	) {
+		await reportProgress(extra, ++n, `segment ${sid}: ${status}`);
+		await sleep(intervalMs);
+		({ status, error } = await read());
+	}
+	return {
+		status,
+		error,
+		timed_out: status !== "completed" && status !== "failed",
+	};
+}
+
+// ── One-shot: make_video ─────────────────────────────────────────────────────
+
+registerTool(
+	"make_video",
+	{
+		title: "Make a video from a prompt (one shot)",
+		description:
+			"The simplest path: give a prompt, get a finished MP4. Creates the project (free), PRICES it against " +
+			"your live credit balance, then — only if it's affordable and within max_credits — starts generation, " +
+			"polls to completion (emitting progress), and (if save_path is given) downloads the result. " +
+			"Spends credits (15 for a short; a multi-scene editor ad ~28). Pass dry_run:true to preview the cost " +
+			"WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " +
+			"spend. kind defaults to 'auto' — a multi-scene editor ad for ad/promo/story briefs, a single-clip short " +
+			"for simple/short ones; the chosen kind is reported back as kind_inferred. If it returns terminal=false " +
+			"the render is still running — call wait_for_completion with the returned slug to finish.",
+		// Schema kept intentionally flat (no .min/.max/.int chains) — the SDK's
+		// generic inference on registerTool hits TS2589 ("excessively deep") on
+		// larger schemas with chained validators. Ranges are enforced in code.
+		inputSchema: {
+			prompt: z
+				.string()
+				.describe("What the ad/video should be about (min 10 chars)"),
+			kind: z
+				.string()
+				.optional()
+				.describe(
+					"'short' (fast, 1 clip), 'editor' (multi-scene), or 'auto' (default — inferred)",
+				),
+			language: z
+				.string()
+				.optional()
+				.describe('Language code, e.g. "en" (default)'),
+			aspect: z
+				.string()
+				.optional()
+				.describe("Aspect ratio for editor: 9:16 (default), 16:9, or 1:1"),
+			voice_id: z
+				.string()
+				.optional()
+				.describe(
+					"Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover",
+				),
+			save_path: z
+				.string()
+				.optional()
+				.describe(
+					"Optional .mp4 path to download to (confined to HUBFLUENCER_OUTPUT_DIR or cwd)",
+				),
+			max_wait_seconds: z
+				.number()
+				.optional()
+				.describe("Block budget seconds (default 240, capped 10–280)"),
+			dry_run: z
+				.boolean()
+				.optional()
+				.describe(
+					"Preview only: create a free draft, price it, and STOP before spending credits. " +
+						"Returns {estimated_credits, available_credits, slug}. Resume with generate_short / start_autopilot.",
+				),
+			max_credits: z
+				.number()
+				.optional()
+				.describe(
+					"Spend cap: refuse to start (no charge) if the priced estimate exceeds this. Returns the estimate.",
+				),
+		},
+		annotations: { title: "Make a video", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				prompt: string;
+				kind?: string;
+				language?: string;
+				aspect?: string;
+				voice_id?: string;
+				save_path?: string;
+				max_wait_seconds?: number;
+				dry_run?: boolean;
+				max_credits?: number;
+			},
+			client,
+			extra,
+		) => {
+			if (!args.prompt || args.prompt.trim().length < 10) {
+				return fail("prompt must be at least 10 characters.");
+			}
+			const requestedKind =
+				args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
+			const kind: Kind = requestedKind ?? inferKind(args.prompt);
+			const waitSeconds = Math.min(
+				280,
+				Math.max(10, args.max_wait_seconds ?? 240),
+			);
+			const budgetMs = waitSeconds * 1000;
+
+			// Validate the save_path up front so we fail before spending credits.
+			if (args.save_path) resolveSavePath(args.save_path);
+
+			// 1) Create the project — FREE (0 credits) for both kinds. Creating
+			//    first lets us price the job against the server's real cost endpoint
+			//    before any charge; the stable idempotency key means a retried
+			//    make_video (or a dry_run then a real run) reuses this same draft.
+			let slug: string;
+			if (kind === "short") {
+				const created = await client.post<{ data: { slug: string } }>(
+					"/shorts",
+					{ product_prompt: args.prompt, language: args.language },
+					// Fold every create-affecting param into the key: two calls that
+					// differ only in language must NOT dedup to the same draft, and a
+					// transport retry of an identical call must reuse it.
+					idemKey("make-short", args.prompt, args.language ?? ""),
+				);
+				slug = created.data.slug;
+			} else {
+				const created = await client.post<{ data: { slug: string } }>(
+					"/editor",
+					{
+						language: args.language ?? "en",
+						product_prompt: args.prompt,
+						export_aspect_ratio: args.aspect,
+						voice_id: args.voice_id,
+					},
+					idemKey(
+						"make-editor",
+						args.prompt,
+						args.language ?? "en",
+						args.aspect ?? "",
+						args.voice_id ?? "",
+					),
+				);
+				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.
+			const costPath =
+				kind === "short"
+					? `/shorts/${slug}/cost`
+					: `/editor/${slug}/autopilot/cost`;
+			let estimated_credits: number | null = null;
+			let available_credits: number | null = null;
+			try {
+				const cost = asRecord(
+					asRecord(await client.get<{ data: unknown }>(costPath)).data,
+				);
+				estimated_credits = typeof cost.total === "number" ? cost.total : null;
+				available_credits =
+					typeof cost.available_credits === "number"
+						? cost.available_credits
+						: null;
+			} catch {
+				// pricing unavailable — fall through (do not block an affordable run)
+			}
+
+			const resume =
+				kind === "short"
+					? `generate_short({ slug: "${slug}" })`
+					: `start_autopilot({ slug: "${slug}" })`;
+			const affordable =
+				available_credits === null ||
+				estimated_credits === null ||
+				available_credits >= estimated_credits;
+			const overCap =
+				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 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}.`;
+				return ok({
+					slug,
+					kind,
+					kind_inferred: requestedKind === undefined,
+					estimated_credits,
+					available_credits,
+					affordable,
+					charged: false,
+					note,
+				});
+			}
+
+			// 4) Affordable and authorized — start the charging pipeline.
+			if (kind === "short") {
+				await client.post(
+					`/shorts/${slug}/generate`,
+					undefined,
+					`gen-short:${slug}`,
+				);
+			} else {
+				await client.post(
+					`/editor/${slug}/autopilot`,
+					undefined,
+					`autopilot:${slug}`,
+				);
+			}
+
+			await reportProgress(extra, 0, `started ${kind} ${slug}`);
+			const status = await pollToTerminal(
+				client,
+				kind,
+				slug,
+				extra,
+				budgetMs,
+				15000,
+			);
+
+			let saved_to: string | null = null;
+			if (status.ready && status.video_url && args.save_path) {
+				saved_to = (await downloadTo(status.video_url, args.save_path))
+					.saved_to;
+			}
+
+			const result = {
+				...status,
+				kind_inferred: requestedKind === undefined,
+				estimated_credits,
+				available_credits,
+				charged: true,
+				saved_to,
+				timed_out: !status.terminal,
+			};
+			// Thread the caller's save_path into the resume hint so the one-shot
+			// "download to this path" intent survives a mid-render timeout —
+			// wait_for_completion accepts save_path and finishes the download.
+			const resumeArgs = `{ slug: "${slug}", kind: "${kind}"${
+				args.save_path ? `, save_path: "${args.save_path}"` : ""
+			} }`;
+			const links =
+				status.ready && status.video_url
+					? [mp4Link(status.video_url, slug)]
+					: [];
+			return ok(
+				{
+					...result,
+					note: status.ready
+						? "Done. Presigned ~24h URL — download promptly."
+						: status.terminal
+							? `Terminal (${status.stage}). ${status.error ?? ""}`.trim()
+							: `Still rendering — call wait_for_completion(${resumeArgs}).`,
+				},
+				links,
+			);
+		},
+	),
+);
+
+// ── Credits ───────────────────────────────────────────────────────────────
+
+registerTool(
+	"get_credits",
+	{
+		title: "Get credit balance",
+		description:
+			"Returns the authenticated account's credit balance. A short costs 15 credits.",
+		inputSchema: {},
+		annotations: { title: "Get credits", ...RO },
+	},
+	tool(async (_args, client) => ok(await client.get("/studio/credits"))),
+);
+
+// ── Voices ────────────────────────────────────────────────────────────────
+
+registerTool(
+	"list_voices",
+	{
+		title: "List voices",
+		description:
+			"Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " +
+			"make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
+		inputSchema: {},
+		annotations: { title: "List voices", ...RO },
+	},
+	tool(async (_args, client) => ok(await client.get("/voices"))),
+);
+
+// ── Projects ──────────────────────────────────────────────────────────────
+
+registerTool(
+	"list_projects",
+	{
+		title: "List recent projects",
+		description:
+			"Lists the caller's recent shorts and editor/video-factory projects, each normalized to " +
+			"{slug, stage, terminal, ready, video_url}. By default the shorts listing is limited to " +
+			"in-progress/failed; pass include_completed:true to also surface finished shorts — useful to " +
+			"recover a lost slug. Capped to the most recent items per kind (use get_status for authoritative state).",
+		inputSchema: {
+			include_completed: z
+				.boolean()
+				.optional()
+				.describe("Also include completed shorts (default false)"),
+			limit: z
+				.number()
+				.optional()
+				.describe("Max items per kind (default 25, capped at 100)"),
+		},
+		annotations: { title: "List projects", ...RO },
+	},
+	tool(
+		async (args: { include_completed?: boolean; limit?: number }, client) => {
+			const cap = Math.min(100, Math.max(1, args.limit ?? 25));
+			const [shortsRaw, factoriesRaw] = await Promise.all([
+				client
+					.get<{ data: unknown }>(
+						"/shorts",
+						args.include_completed ? { include_completed: "true" } : undefined,
+					)
+					.catch(() => ({ data: [] })),
+				client
+					.get<{ data: unknown }>("/video-factories")
+					.catch(() => ({ data: [] })),
+			]);
+
+			const rows = (raw: unknown): Record<string, unknown>[] => {
+				const d = asRecord(raw).data;
+				return Array.isArray(d) ? (d as Record<string, unknown>[]) : [];
+			};
+			const shortRows = rows(shortsRaw);
+			const factoryRows = rows(factoriesRaw);
+
+			const shorts = shortRows
+				.slice(0, cap)
+				.map((s) => normalizeStatus("short", String(s.slug ?? ""), s));
+			// /video-factories spans editor + campaign + creative kinds; normalize
+			// each through the editor shape so the agent gets one consistent status
+			// envelope instead of a heavy, unlabeled raw payload.
+			const projects = factoryRows.slice(0, cap).map((f) => ({
+				...normalizeStatus("editor", String(f.slug ?? ""), f),
+				kind_detail: (f.kind as string) ?? null,
+			}));
+
+			return ok({
+				shorts,
+				projects,
+				note:
+					shortRows.length > cap || factoryRows.length > cap
+						? `Showing up to ${cap} per kind; more exist — raise limit or use get_status.`
+						: undefined,
+			});
+		},
+	),
+);
+
+// ── Shorts ──────────────────────────────────────────────────────────────────
+
+registerTool(
+	"create_short",
+	{
+		title: "Create a short (draft)",
+		description:
+			"Creates a short draft from a product prompt (min 10 chars). Returns the slug. Costs 0 credits. " +
+			"Follow with generate_short to render. Prefer make_video for the one-shot path.",
+		inputSchema: {
+			product_prompt: z
+				.string()
+				.min(10)
+				.describe("What the short should be about"),
+			language: z
+				.string()
+				.optional()
+				.describe('Language code, e.g. "en" (default)'),
+			theme: z.string().optional(),
+			headline: z.string().optional(),
+			subheadline: z.string().optional(),
+			music_vibe: z.string().optional(),
+		},
+		annotations: { title: "Create short", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: Record<string, unknown>, client) => {
+		const res = await client.post<{ data: { slug: string } }>(
+			"/shorts",
+			args,
+			idemKey("create-short", String(args.product_prompt ?? "")),
+		);
+		return ok({ slug: res.data.slug, kind: "short", next: "generate_short" });
+	}),
+);
+
+registerTool(
+	"generate_short",
+	{
+		title: "Generate (render) a short",
+		description:
+			"Deducts 15 credits and starts the render pipeline for an existing short. Idempotent per slug " +
+			"(safe to retry). Then poll with get_status or wait_for_completion (kind=short).",
+		inputSchema: { slug: z.string().describe("Short slug from create_short") },
+		annotations: { title: "Generate short", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/shorts/${args.slug}/generate`,
+			undefined,
+			`gen-short:${args.slug}`,
+		);
+		const status = normalizeStatus("short", args.slug, asRecord(res).data);
+		return ok(status);
+	}),
+);
+
+// ── Editor ───────────────────────────────────────────────────────────────────
+
+registerTool(
+	"create_editor_ad",
+	{
+		title: "Create a multi-scene editor ad (autopilot)",
+		description:
+			"Creates an editor project from a product prompt and starts 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.",
+		inputSchema: {
+			product_prompt: z
+				.string()
+				.min(10)
+				.describe("Brief for the ad (min 10 chars)"),
+			language: z
+				.string()
+				.optional()
+				.describe('Language code, e.g. "en" (default)'),
+			theme: z
+				.string()
+				.optional()
+				.describe('Visual theme (default "realistic")'),
+			voice_id: z
+				.string()
+				.optional()
+				.describe(
+					"Preferred narration voice id (see list_voices); omit for the default voice",
+				),
+			export_aspect_ratio: z
+				.enum(["9:16", "16:9", "1:1"])
+				.optional()
+				.describe('Aspect ratio (default "9:16")'),
+		},
+		annotations: { title: "Create editor ad", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: Record<string, unknown>, client) => {
+		const created = await client.post<{ data: { slug: string } }>(
+			"/editor",
+			{
+				language: args.language ?? "en",
+				product_prompt: args.product_prompt,
+				theme: args.theme,
+				voice_id: args.voice_id,
+				export_aspect_ratio: args.export_aspect_ratio,
+			},
+			idemKey("create-editor", String(args.product_prompt ?? "")),
+		);
+		const slug = created.data.slug;
+		const started = await client.post<{ data: unknown }>(
+			`/editor/${slug}/autopilot`,
+			undefined,
+			`autopilot:${slug}`,
+		);
+		const status = normalizeStatus("editor", slug, asRecord(started).data);
+		return ok({ slug, kind: "editor", status, next: "wait_for_completion" });
+	}),
+);
+
+registerTool(
+	"start_autopilot",
+	{
+		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 }). Idempotent per slug (safe to retry). Use this to run a draft created by " +
+			"make_video dry_run, or to resume after topping up / raising your spend cap. Then poll with " +
+			'wait_for_completion({ slug, kind: "editor" }).',
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: { title: "Start autopilot", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: { slug: string }, client) => {
+		const started = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/autopilot`,
+			undefined,
+			`autopilot:${args.slug}`,
+		);
+		const status = normalizeStatus("editor", args.slug, asRecord(started).data);
+		return ok({
+			slug: args.slug,
+			kind: "editor",
+			status,
+			next: "wait_for_completion",
+		});
+	}),
+);
+
+// ── AI assists (free daily quota) ───────────────────────────────────────────
+
+registerTool(
+	"get_ai_assists",
+	{
+		title: "Get AI assist quota",
+		description:
+			"Returns the free daily AI-assist quota {used, limit, bonus, remaining, resets_at, unlock_cost, " +
+			"unlock_batch_size}. AI assists power helper calls (generate_scenario, generate_narration, " +
+			"enhance_prompt, suggest_next_scene, suggest_music_prompt). Default limit is 20/day. When remaining " +
+			"hits 0 those helpers return 429 — either unlock_ai_assists (1 credit → +10) or write the content " +
+			"yourself with set_scenario / set_narration_script / set_segment_prompt (those are free, no quota).",
+		inputSchema: {},
+		annotations: { title: "Get AI assists", ...RO },
+	},
+	tool(async (_args, client) => ok(await client.get("/ai-assists"))),
+);
+
+registerTool(
+	"unlock_ai_assists",
+	{
+		title: "Unlock more AI assists",
+		description:
+			"Spends 1 credit to add 10 AI assists to today's quota (bonus allowance). Call it again to buy another batch — each call adds 10 (a transport retry won't double-charge). " +
+			"Returns the fresh quota status. If the account is out of credits the server returns 402 " +
+			"credits_insufficient — this tool fails cleanly (it does NOT loop or retry).",
+		inputSchema: {},
+		annotations: {
+			title: "Unlock AI assists",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (_args, client) =>
+		ok(
+			await client.post(
+				"/ai-assists/unlock",
+				undefined,
+				await unlockKey(client),
+			),
+		),
+	),
+);
+
+// ── Granular editor pipeline ─────────────────────────────────────────────────
+//
+// These tools expose the step-by-step editor pipeline so an agent can build an
+// ad with full control (review the scenario, write its own prompts, etc.)
+// instead of one-shot autopilot (create_editor_ad / make_video).
+//   create_editor_draft → generate_scenario|set_scenario → get_editor (REVIEW)
+//   → set_scene_count → set_segment_prompt → generate_segment|generate_all_segments
+//   → set_narration_script|generate_narration → generate_voice + generate_music
+//   → render → wait_for_completion(kind:"editor") → download_result.
+
+registerTool(
+	"create_editor_draft",
+	{
+		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). " +
+			"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: {
+			product_prompt: z
+				.string()
+				.min(10)
+				.max(5000)
+				.optional()
+				.describe("Brief for the ad — 10–5000 chars, or omit entirely"),
+			language: z
+				.string()
+				.min(2)
+				.max(10)
+				.optional()
+				.describe('Language code, e.g. "en" (default)'),
+			theme: z
+				.string()
+				.optional()
+				.describe('Visual theme (default "realistic")'),
+			voice_id: z
+				.string()
+				.regex(/^[A-Za-z0-9_-]+$/)
+				.max(64)
+				.optional()
+				.describe(
+					"Preferred narration voice id (see list_voices); ≤64 chars, [A-Za-z0-9_-] only",
+				),
+			export_aspect_ratio: z
+				.enum(["9:16", "16:9", "1:1"])
+				.optional()
+				.describe('Aspect ratio (default "9:16")'),
+			project_intent: z
+				.enum(["social_ad", "creative_story"])
+				.optional()
+				.describe("Project intent (optional)"),
+		},
+		annotations: {
+			title: "Create editor draft",
+			...WRITE,
+			idempotentHint: true,
+		},
+	},
+	tool(
+		async (
+			args: {
+				product_prompt?: string;
+				language?: string;
+				theme?: string;
+				voice_id?: string;
+				export_aspect_ratio?: string;
+				project_intent?: string;
+			},
+			client,
+		) => {
+			const prompt = args.product_prompt?.trim();
+			const body: Record<string, unknown> = {
+				language: args.language ?? "en",
+				theme: args.theme,
+				voice_id: args.voice_id,
+				export_aspect_ratio: args.export_aspect_ratio,
+				project_intent: args.project_intent,
+			};
+			if (prompt) body.product_prompt = prompt;
+			const created = await client.post<{ data: { slug: string } }>(
+				"/editor",
+				body,
+				idemKey("create-editor-draft", prompt ?? "", args.language ?? "en"),
+			);
+			return ok({
+				slug: created.data.slug,
+				kind: "editor",
+				next: "generate_scenario | set_scenario, then get_editor to review",
+			});
+		},
+	),
+);
+
+registerTool(
+	"get_editor",
+	{
+		title: "Get full editor state (review step)",
+		description:
+			"Returns the full editor project state: scenario_prompt, segments[] (with prompts + status), " +
+			"narration_script/status, music, latest_render, segments_count, ai_assist_quota. This is the REVIEW " +
+			"step — call it after generating the scenario/segments to inspect and decide what to edit.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: { title: "Get editor", ...RO },
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
+		return ok(asRecord(res).data);
+	}),
+);
+
+registerTool(
+	"set_scenario",
+	{
+		title: "Set the editor scenario",
+		description:
+			"Writes your own scenario prompt (1–50000 chars) instead of generating one. Free — consumes NO AI " +
+			"assist and NO credits. Use this in place of generate_scenario when you want full control over the story.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			scenario_prompt: z
+				.string()
+				.min(1)
+				.max(50000)
+				.describe("The scenario / story prompt (1–50000 chars)"),
+		},
+		annotations: { title: "Set scenario", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: { slug: string; scenario_prompt: string }, client) => {
+		const res = await client.patch<{ data: unknown }>(
+			`/editor/${args.slug}/scenario`,
+			{ scenario_prompt: args.scenario_prompt },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"generate_scenario",
+	{
+		title: "Generate the editor scenario (AI assist)",
+		description:
+			"Generates a scenario with AI. CONSUMES 1 AI ASSIST (free daily quota; check get_ai_assists). On 429 " +
+			"(quota exhausted) either set auto_unlock:true to spend 1 credit for +10 assists and retry once, or " +
+			"write the scenario yourself with set_scenario. Server default segments_count is 5.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe("How many scenes (3–10, server default 5)"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Generate scenario",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				segments_count?: number;
+				auto_unlock?: boolean;
+			},
+			client,
+		) => {
+			const body: Record<string, unknown> = {};
+			if (args.segments_count !== undefined)
+				body.segments_count = args.segments_count;
+			const res = await withAssist(client, args.auto_unlock ?? false, () =>
+				client.post<{ data: unknown }>(
+					`/editor/${args.slug}/generate-scenario`,
+					body,
+				),
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_scene_count",
+	{
+		title: "Set the number of scenes",
+		description:
+			"Adjusts the editor to exactly `count` scenes (1–20) by adding pending segments to grow, or deleting " +
+			"only TRAILING un-generated (pending) segments to shrink. Never deletes completed/processing segments — " +
+			"if a shrink would require that, it stops and reports. Free (no credits, no assist). Each AI-generated " +
+			"scene is a fixed 8 seconds, so `count` scenes ≈ count×8s of AI footage (uploaded clips keep their own length).",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			count: z
+				.number()
+				.int()
+				.min(1)
+				.max(20)
+				.describe("Target scene count (1–20)"),
+		},
+		annotations: { title: "Set scene count", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string; count: number }, client) => {
+		const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
+		const data = asRecord(asRecord(res).data);
+		const segments = Array.isArray(data.segments)
+			? (data.segments as Record<string, unknown>[])
+			: [];
+		const current = segments.length;
+		const target = args.count;
+
+		if (target > current) {
+			for (let i = current; i < target; i++) {
+				await client.post(
+					`/editor/${args.slug}/segments`,
+					{},
+					idemKey("add-segment", args.slug, String(i)),
+				);
+			}
+		} else if (target < current) {
+			// Delete only trailing pending segments (never completed/processing).
+			const isPending = (s: Record<string, unknown>) => {
+				const st = (s.status as string) ?? (s.generation_status as string);
+				return (
+					st === undefined ||
+					st === "pending" ||
+					st === "draft" ||
+					st === "failed"
+				);
+			};
+			let removable = 0;
+			for (let i = segments.length - 1; i >= target; i--) {
+				if (!isPending(segments[i])) break;
+				removable++;
+			}
+			if (current - removable > target) {
+				return fail(
+					`Cannot shrink to ${target} scenes: only ${removable} trailing pending segment(s) are safe to ` +
+						`delete (the rest are completed/processing). Currently ${current} scenes.`,
+				);
+			}
+			for (let i = segments.length - 1; i >= target; i--) {
+				const seg = segments[i];
+				// Mirror the safety pre-check exactly: never delete a segment that
+				// isn't pending, so the two loops can't diverge (e.g. a future edit to
+				// one). The pre-check already guarantees this range is all-pending; this
+				// keeps the invariant local and self-consistent.
+				if (!isPending(seg)) break;
+				const id = seg.id;
+				if (id === undefined) break;
+				await client.del(`/editor/${args.slug}/segments/${String(id)}`);
+			}
+		}
+
+		const after = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
+		const afterData = asRecord(asRecord(after).data);
+		const finalCount = Array.isArray(afterData.segments)
+			? (afterData.segments as unknown[]).length
+			: undefined;
+		return ok({ slug: args.slug, requested: target, scene_count: finalCount });
+	}),
+);
+
+registerTool(
+	"set_segment_prompt",
+	{
+		title: "Set a segment prompt",
+		description:
+			"Writes the prompt for one scene/segment (1–2000 chars). Free — no credits, no assist. Identify the " +
+			"segment by its id (from get_editor). Generate it afterwards with generate_segment.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Segment id (from get_editor)"),
+			prompt: z
+				.string()
+				.min(1)
+				.max(2000)
+				.describe("Scene prompt (1–2000 chars)"),
+		},
+		annotations: {
+			title: "Set segment prompt",
+			...WRITE,
+			idempotentHint: true,
+		},
+	},
+	tool(
+		async (
+			args: { slug: string; segment_id: number | string; prompt: string },
+			client,
+		) => {
+			const res = await client.patch<{ data: unknown }>(
+				`/editor/${args.slug}/segments/${String(args.segment_id)}`,
+				{ prompt: args.prompt },
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"generate_segment",
+	{
+		title: "Generate one segment (5 credits)",
+		description:
+			"Renders the video for one scene. Each AI-generated scene is a fixed 8 seconds long. Costs 5 credits. " +
+			"Re-call to retry a failed scene or regenerate after a prompt edit — the server blocks regenerating one that's still processing, so no double-charge. Visual" +
+			"continuity is handled server-side (this scene uses the previous scene's last frame). 402 " +
+			"credits_insufficient fails cleanly. Generate scenes in position order for correct continuity.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Segment id (from get_editor)"),
+		},
+		annotations: { title: "Generate segment", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string; segment_id: number | string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/segments/${String(args.segment_id)}/generate`,
+			undefined,
+			undefined,
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"generate_all_segments",
+	{
+		title: "Generate all pending segments (sequential)",
+		description:
+			"Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting" +
+			"the next (preserves visual continuity). Each AI-generated scene is a fixed 8 seconds, so N scenes ≈ N×8s of footage. Costs 5 credits per segment generated. Stops and reports what " +
+			"completed if a scene errors on submit (e.g. 402 credits_insufficient) or fails while rendering; if a " +
+			"scene is still rendering past the budget it returns timed_out so you can re-run to continue (completed " +
+			"scenes are skipped). Tip: to generate everything at lowest cost, skip this and just call render — it auto-generates any ungenerated scenes at the batch rate (4 credits/scene for ≥3); use this tool when you want to review or stop per scene. May take several minutes.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: {
+			title: "Generate all segments",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string }, client, extra) => {
+		const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
+		const data = asRecord(asRecord(res).data);
+		const segments = Array.isArray(data.segments)
+			? (data.segments as Record<string, unknown>[])
+			: [];
+		const pending = segments.filter((s) => {
+			const st = (s.status as string) ?? (s.generation_status as string);
+			return (
+				st === undefined ||
+				st === "pending" ||
+				st === "draft" ||
+				st === "failed"
+			);
+		});
+
+		const generated: Array<string | number> = [];
+		let n = 0;
+		for (const seg of pending) {
+			const id = seg.id;
+			if (id === undefined) continue;
+			const sid = id as string | number;
+			await reportProgress(
+				extra,
+				++n,
+				`generating segment ${String(sid)} (${n}/${pending.length})`,
+				pending.length,
+			);
+			try {
+				await client.post(
+					`/editor/${args.slug}/segments/${String(sid)}/generate`,
+					undefined,
+					undefined,
+				);
+			} catch (e) {
+				return ok({
+					slug: args.slug,
+					generated,
+					stopped_at: sid,
+					error: errMessage(e),
+					note: "Stopped on first error — fix the cause (often credits) and re-run; completed scenes are skipped, failed/pending are retried.",
+				});
+			}
+			// Gate on THIS segment finishing before starting the next, so the next
+			// scene can build on this one's last frame (visual continuity). Poll the
+			// segment itself — the project-level status never goes terminal mid-batch.
+			const seg_result = await pollSegmentToTerminal(
+				client,
+				args.slug,
+				sid,
+				extra,
+				6 * 60 * 1000,
+				15000,
+			);
+			if (seg_result.status === "failed") {
+				return ok({
+					slug: args.slug,
+					generated,
+					stopped_at: sid,
+					error: seg_result.error ?? "segment generation failed",
+					note: "A scene failed — stopped here. Fix its prompt with set_segment_prompt if needed, then re-run generate_all_segments: it retries failed/pending scenes and skips completed ones.",
+				});
+			}
+			if (seg_result.timed_out) {
+				return ok({
+					slug: args.slug,
+					generated,
+					stopped_at: sid,
+					timed_out: true,
+					note: "A scene is still rendering after the poll budget. Re-run generate_all_segments later to continue (it retries failed/pending, skips completed), or watch it with get_editor.",
+				});
+			}
+			generated.push(sid);
+		}
+		return ok({
+			slug: args.slug,
+			generated,
+			count: generated.length,
+			note: "All pending segments generated. Next: narration + voice/music, then render.",
+		});
+	}),
+);
+
+registerTool(
+	"set_narration_script",
+	{
+		title: "Set the narration script",
+		description:
+			"Writes your own narration script (1–12000 chars) instead of generating one. Free — no credits, no AI " +
+			"assist. Use this in place of generate_narration when you want to control the voiceover text. Changing the narration after generating voice/music marks them stale — regenerate (generate_voice / generate_music) before render.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			script: z
+				.string()
+				.min(1)
+				.max(12000)
+				.describe("Narration / voiceover text (1–12000 chars)"),
+		},
+		annotations: { title: "Set narration", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: { slug: string; script: string }, client) => {
+		const res = await client.patch<{ data: unknown }>(`/editor/${args.slug}`, {
+			narration_script: args.script,
+		});
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"generate_narration",
+	{
+		title: "Generate the narration (AI assist)",
+		description:
+			"Generates the narration script with AI from the timeline. CONSUMES 1 AI ASSIST (free daily quota) — " +
+			"it is free of CREDITS but NOT free of quota. On 429 set auto_unlock:true (1 credit → +10 assists, " +
+			"retried once) or write the script yourself with set_narration_script.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Generate narration",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string; auto_unlock?: boolean }, client) => {
+		const res = await withAssist(client, args.auto_unlock ?? false, () =>
+			client.post<{ data: unknown }>(`/editor/${args.slug}/generate-narration`),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"generate_voice",
+	{
+		title: "Generate the voiceover (3 credits)",
+		description:
+			"Synthesizes the voiceover from the narration script. Costs 3 credits. Safe to retry; re-call after changing the narration or voice to regenerate." +
+			"voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			voice_id: z
+				.string()
+				.regex(/^[A-Za-z0-9_-]+$/)
+				.max(64)
+				.describe("Narration voice id from list_voices (required)"),
+		},
+		annotations: { title: "Generate voice", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: { slug: string; voice_id: string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/generate-voice`,
+			{ voice_id: args.voice_id },
+			await voiceKey(client, args.slug, args.voice_id),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"generate_music",
+	{
+		title: "Generate the background music (5 credits)",
+		description:
+			"Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" +
+			"music-direction prompt (≤1200 chars; longer is silently truncated server-side). 402 fails cleanly.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			description: z
+				.string()
+				.max(1200)
+				.optional()
+				.describe("Music direction prompt (≤1200 chars, truncated if longer)"),
+			mood: z.string().optional().describe("Optional mood hint"),
+			genre: z.string().optional().describe("Optional genre hint"),
+			tempo: z.string().optional().describe("Optional tempo hint"),
+			instruments: z.string().optional().describe("Optional instruments hint"),
+		},
+		annotations: { title: "Generate music", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				description?: string;
+				mood?: string;
+				genre?: string;
+				tempo?: string;
+				instruments?: string;
+			},
+			client,
+		) => {
+			const body: Record<string, unknown> = {};
+			if (args.description !== undefined) body.prompt = args.description;
+			if (args.mood !== undefined) body.mood = args.mood;
+			if (args.genre !== undefined) body.genre = args.genre;
+			if (args.tempo !== undefined) body.tempo = args.tempo;
+			if (args.instruments !== undefined) body.instruments = args.instruments;
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/generate-music`,
+				body,
+				undefined,
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"render",
+	{
+		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; " +
+			'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") },
+		annotations: { title: "Render", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string }, client) => {
+		try {
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/render`,
+				undefined,
+				undefined,
+			);
+			return ok(asRecord(res).data ?? res);
+		} catch (e) {
+			// Turn the staleness 422s into an actionable instruction naming the
+			// exact regenerate step, instead of a bare code the agent must decode.
+			// These codes are machine-stable server-side.
+			const he = e as HubfluencerError;
+			const fix: Record<string, string> = {
+				editor_narration_stale:
+					"The narration is stale (timeline changed). Regenerate it (generate_narration or set_narration_script), then generate_voice, then render.",
+				editor_voice_stale:
+					"The voiceover is stale (narration/timeline changed). Call generate_voice again, then render.",
+				editor_music_stale:
+					"The background music is stale (timeline changed). Call generate_music again, then render.",
+			};
+			if (he?.code && fix[he.code]) {
+				return fail(`${errMessage(e)} → ${fix[he.code]}`);
+			}
+			throw e;
+		}
+	}),
+);
+
+registerTool(
+	"enhance_prompt",
+	{
+		title: "Enhance a segment prompt (AI assist)",
+		description:
+			"Rewrites/expands one segment's prompt with AI. CONSUMES 1 AI ASSIST (free daily quota). On 429 set " +
+			"auto_unlock:true (1 credit → +10 assists, retried once) or edit the prompt yourself with " +
+			"set_segment_prompt.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Segment id (from get_editor)"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: { title: "Enhance prompt", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				segment_id: number | string;
+				auto_unlock?: boolean;
+			},
+			client,
+		) => {
+			const res = await withAssist(client, args.auto_unlock ?? false, () =>
+				client.post<{ data: unknown }>(
+					`/editor/${args.slug}/segments/${String(args.segment_id)}/enhance-prompt`,
+				),
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"suggest_next_scene",
+	{
+		title: "Suggest the next scene (AI assist)",
+		description:
+			"Suggests a prompt for the next scene with AI. CONSUMES 1 AI ASSIST (free daily quota). On 429 set " +
+			"auto_unlock:true (1 credit → +10 assists, retried once) or write the next scene yourself.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Suggest next scene",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string; auto_unlock?: boolean }, client) => {
+		const res = await withAssist(client, args.auto_unlock ?? false, () =>
+			client.post<{ data: unknown }>(`/editor/${args.slug}/suggest-next-scene`),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"suggest_music_prompt",
+	{
+		title: "Suggest a music prompt (AI assist)",
+		description:
+			"Suggests a background-music direction prompt with AI. CONSUMES 1 AI ASSIST (free daily quota). On 429 " +
+			"set auto_unlock:true (1 credit → +10 assists, retried once) or write the music direction yourself and " +
+			"pass it to generate_music.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Suggest music prompt",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string; auto_unlock?: boolean }, client) => {
+		const res = await withAssist(client, args.auto_unlock ?? false, () =>
+			client.post<{ data: unknown }>(
+				`/editor/${args.slug}/suggest-music-prompt`,
+			),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+// ── Renders: list / retry (R5) ───────────────────────────────────────────────
+
+registerTool(
+	"list_renders",
+	{
+		title: "List renders for an editor project",
+		description:
+			"Lists every render version for an editor project: {id, version, status, video_url, duration_seconds, " +
+			"error_message, inserted_at}. Use it to find a FAILED render to retry, or to recover a finished video_url " +
+			"(presigned, ~24h). Read-only.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: { title: "List renders", ...RO },
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.get<{ data: unknown }>(
+			`/editor/${args.slug}/renders`,
+		);
+		return ok({ slug: args.slug, renders: asRecord(res).data ?? [] });
+	}),
+);
+
+registerTool(
+	"retry_render",
+	{
+		title: "Retry a failed render (0 credits)",
+		description:
+			"Re-runs a FAILED render from its exact saved snapshot (segments/voice/music as they were) — recovery without " +
+			"re-driving the pipeline. Get render_id from list_renders. Only failed renders are retryable " +
+			'(editor_render_not_retryable otherwise). Then wait_for_completion({ slug, kind: "editor" }).',
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			render_id: z
+				.union([z.number(), z.string()])
+				.describe("Render id from list_renders"),
+		},
+		annotations: { title: "Retry render", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string; render_id: number | string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/renders/${String(args.render_id)}/retry`,
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+// ── Uploads & local assets (R1) ───────────────────────────────────────────────
+//
+// Bring the agent's OWN media into a project: upload local video clips onto the
+// timeline, and attach a product image / closing card / brand logo. All local
+// paths are confined to HUBFLUENCER_INPUT_DIR (or cwd) with an extension
+// allowlist (see uploads.ts) so a prompt-injected file_path can't exfiltrate
+// arbitrary files. Uploads are 0 credits.
+
+/**
+ * Polls ONE editor upload until it finishes async processing ("ready") or
+ * "failed", or the budget runs out. Processing extracts metadata/frames after
+ * confirm, so a just-confirmed upload is "pending"/"processing" — it must reach
+ * "ready" before it can be placed on the timeline.
+ */
+async function pollUploadToReady(
+	client: HubfluencerClient,
+	slug: string,
+	uploadId: string | number,
+	extra: ToolExtra,
+	budgetMs: number,
+	intervalMs: number,
+): Promise<{ status: string; error: string | null; timed_out: boolean }> {
+	const deadline = Date.now() + budgetMs;
+	const uid = String(uploadId);
+	const read = async (): Promise<{ status: string; error: string | null }> => {
+		const res = await client.get<{ data: unknown }>(`/editor/${slug}/uploads`);
+		const data = asRecord(res).data;
+		const list = Array.isArray(data) ? (data as Record<string, unknown>[]) : [];
+		const row = list.find((u) => String(u.id) === uid);
+		return {
+			status: row ? ((row.status as string) ?? "unknown") : "unknown",
+			error: row ? ((row.error_message as string) ?? null) : null,
+		};
+	};
+	let n = 0;
+	let { status, error } = await read();
+	while (
+		status !== "ready" &&
+		status !== "failed" &&
+		Date.now() + intervalMs <= deadline
+	) {
+		await reportProgress(extra, ++n, `upload ${uid}: ${status}`);
+		await sleep(intervalMs);
+		({ status, error } = await read());
+	}
+	return {
+		status,
+		error,
+		timed_out: status !== "ready" && status !== "failed",
+	};
+}
+
+registerTool(
+	"upload_video",
+	{
+		title: "Upload a local video clip into an editor project",
+		description:
+			"Uploads a local video FILE (your own footage) into an editor project and, by default, adds it to the timeline " +
+			"as a finished scene. Unlike an AI-generated scene (a fixed 8 seconds), an uploaded clip keeps its own native " +
+			"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 " +
+			"placed — call add_segment_from_upload later.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			file_path: z
+				.string()
+				.describe(
+					"Local video file path (inside HUBFLUENCER_INPUT_DIR or cwd)",
+				),
+			add_to_timeline: z
+				.boolean()
+				.optional()
+				.describe("Append as a new scene once ready (default true)"),
+			fit_mode: z
+				.string()
+				.optional()
+				.describe(
+					'"cover" or "blur" (default blur) — how the clip fills the frame',
+				),
+			max_wait_seconds: z
+				.number()
+				.optional()
+				.describe("Processing wait budget (default 240, capped 10–280)"),
+		},
+		annotations: { title: "Upload video", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				file_path: string;
+				add_to_timeline?: boolean;
+				fit_mode?: string;
+				max_wait_seconds?: number;
+			},
+			client,
+			extra,
+		) => {
+			const uploaded = await uploadVideoFile(
+				client,
+				args.slug,
+				args.file_path,
+				{
+					fitMode: args.fit_mode,
+				},
+			);
+			await reportProgress(
+				extra,
+				0,
+				`uploaded ${uploaded.upload_id}, processing…`,
+			);
+			const waitSeconds = Math.min(
+				280,
+				Math.max(10, args.max_wait_seconds ?? 240),
+			);
+			const poll = await pollUploadToReady(
+				client,
+				args.slug,
+				uploaded.upload_id,
+				extra,
+				waitSeconds * 1000,
+				5000,
+			);
+			if (poll.status === "failed") {
+				return fail(
+					`Upload ${uploaded.upload_id} failed to process: ${poll.error ?? "unknown error"}.`,
+				);
+			}
+			if (poll.timed_out) {
+				return ok({
+					upload_id: uploaded.upload_id,
+					status: poll.status,
+					timed_out: true,
+					note: "Still processing. Re-check with get_editor (uploads[]); once status is 'ready' call add_segment_from_upload to place it.",
+				});
+			}
+			if (args.add_to_timeline === false) {
+				return ok({
+					upload_id: uploaded.upload_id,
+					status: "ready",
+					note: "Uploaded and ready. Call add_segment_from_upload to place it on the timeline.",
+				});
+			}
+			try {
+				const seg = await client.post<{ data: unknown }>(
+					`/editor/${args.slug}/segments/from-upload`,
+					{ upload_id: uploaded.upload_id },
+				);
+				return ok({
+					upload_id: uploaded.upload_id,
+					status: "ready",
+					segment: asRecord(seg).data ?? null,
+					note: "Uploaded and added to the timeline as a new scene.",
+				});
+			} catch (e) {
+				const he = e as HubfluencerError;
+				if (he?.code === "batch_generation_active") {
+					return ok({
+						upload_id: uploaded.upload_id,
+						status: "ready",
+						note: "Uploaded and ready, but a generation/render is running so it wasn't placed. Retry add_segment_from_upload({ slug, upload_id }) once that finishes.",
+					});
+				}
+				throw e;
+			}
+		},
+	),
+);
+
+registerTool(
+	"add_segment_from_upload",
+	{
+		title: "Add a ready upload to the timeline as a scene",
+		description:
+			"Appends a READY upload (from upload_video / get_editor uploads[]) to the editor timeline as a new finished " +
+			"scene. 0 credits. Fails with editor_upload_not_ready if still processing, batch_generation_active if a " +
+			"generation/render is running, or editor_segment_limit at 20 scenes.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			upload_id: z
+				.union([z.number(), z.string()])
+				.describe("A ready upload id"),
+		},
+		annotations: {
+			title: "Add segment from upload",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string; upload_id: number | string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/segments/from-upload`,
+			{ upload_id: args.upload_id },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"use_asset_for_segment",
+	{
+		title: "Reuse a clip/asset for a specific scene (0 credits)",
+		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.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Target scene id (from get_editor)"),
+			upload_id: z
+				.union([z.number(), z.string()])
+				.optional()
+				.describe("Source: a ready upload id"),
+			source_segment_id: z
+				.union([z.number(), z.string()])
+				.optional()
+				.describe("Source: a completed scene id"),
+		},
+		annotations: {
+			title: "Use asset for segment",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				segment_id: number | string;
+				upload_id?: number | string;
+				source_segment_id?: number | string;
+			},
+			client,
+		) => {
+			const hasUpload = args.upload_id !== undefined;
+			const hasSource = args.source_segment_id !== undefined;
+			if (hasUpload === hasSource) {
+				return fail("Provide exactly one of upload_id or source_segment_id.");
+			}
+			const body: Record<string, unknown> = hasUpload
+				? { upload_id: args.upload_id }
+				: { source_segment_id: args.source_segment_id };
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/segments/${String(args.segment_id)}/use-asset`,
+				body,
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_product",
+	{
+		title: "Attach a product image (from a local file)",
+		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 " +
+			"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: {
+			slug: z.string().describe("Editor project slug"),
+			file_path: z
+				.string()
+				.describe("Local product image path (.jpg/.jpeg/.png)"),
+			description: z
+				.string()
+				.max(500)
+				.optional()
+				.describe("Product description (≤500 chars)"),
+		},
+		annotations: { title: "Set product", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: { slug: string; file_path: string; description?: string },
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/editor/${args.slug}/product/presign`,
+				args.file_path,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/product/confirm`,
+				{ s3_key, product_description: args.description },
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_product_placement",
+	{
+		title: "Set default product placement on pending scenes (0 credits)",
+		description:
+			"Sets where the product appears across pending (never-generated) AI scenes. mode is 'throughout' (every scene) " +
+			"or 'end' (closing scene only; requires a first+last-frame capable model). 0 credits. Add a product first with " +
+			"set_product. (There is no 'none' — to remove the product, that's a separate action.)",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			mode: z.enum(["throughout", "end"]).describe("'throughout' or 'end'"),
+		},
+		annotations: {
+			title: "Set product placement",
+			...WRITE,
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { slug: string; mode: "throughout" | "end" }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/product/apply-default-placement`,
+			{ placement: args.mode },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"set_closing_image",
+	{
+		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 " +
+			"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).",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			file_path: z
+				.string()
+				.optional()
+				.describe("Local image to upload as the end card"),
+			from_product: z
+				.boolean()
+				.optional()
+				.describe(
+					"Reuse the product image (0-credit copy) instead of uploading",
+				),
+			overwrite: z
+				.boolean()
+				.optional()
+				.describe("Replace an existing closing image"),
+		},
+		annotations: {
+			title: "Set closing image",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				file_path?: string;
+				from_product?: boolean;
+				overwrite?: boolean;
+			},
+			client,
+		) => {
+			if (args.from_product) {
+				const res = await client.post<{ data: unknown }>(
+					`/editor/${args.slug}/closing-image/from-product`,
+					{ overwrite: args.overwrite === true },
+				);
+				return ok(asRecord(res).data ?? res);
+			}
+			if (!args.file_path) {
+				return fail("Provide file_path (a local image) or from_product:true.");
+			}
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/editor/${args.slug}/closing-image/presign`,
+				args.file_path,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/closing-image/confirm`,
+				{ s3_key },
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_logo",
+	{
+		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 " +
+			"transparency), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. Optional placement controls: treatment, " +
+			"position, duration_seconds.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			file_path: z.string().describe("Local logo image (.png/.jpg/.jpeg)"),
+			treatment: z.string().optional().describe("Optional logo treatment"),
+			position: z.string().optional().describe("Optional logo position"),
+			duration_seconds: z
+				.number()
+				.optional()
+				.describe("Optional on-screen duration (seconds)"),
+		},
+		annotations: { title: "Set logo", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				file_path: string;
+				treatment?: string;
+				position?: string;
+				duration_seconds?: number;
+			},
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/editor/${args.slug}/logo/presign`,
+				args.file_path,
+			);
+			const confirmed = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/logo/confirm`,
+				{ s3_key },
+			);
+			let result = asRecord(confirmed).data ?? confirmed;
+			const settings: Record<string, unknown> = {};
+			if (args.treatment !== undefined)
+				settings.logo_treatment = args.treatment;
+			if (args.position !== undefined) settings.logo_position = args.position;
+			if (args.duration_seconds !== undefined)
+				settings.logo_duration_seconds = args.duration_seconds;
+			if (Object.keys(settings).length > 0) {
+				const updated = await client.patch<{ data: unknown }>(
+					`/editor/${args.slug}/logo`,
+					settings,
+				);
+				result = asRecord(updated).data ?? updated;
+			}
+			return ok(result);
+		},
+	),
+);
+
+// ── Status / waiting ──────────────────────────────────────────────────────────
+
+registerTool(
+	"get_status",
+	{
+		title: "Get generation status",
+		description:
+			"Returns a normalized status {stage, terminal, ready, video_url, error} for a short or editor " +
+			"project. ready:true means the post-ready MP4 is at video_url.",
+		inputSchema: { slug: z.string(), kind: kindSchema },
+		annotations: { title: "Get status", ...RO },
+	},
+	tool(async (args: { slug: string; kind: Kind }, client) => {
+		const status = await fetchStatus(client, args.kind, args.slug);
+		return ok(status);
+	}),
+);
+
+registerTool(
+	"wait_for_completion",
+	{
+		title: "Wait for a render to finish",
+		description:
+			"Polls status (emitting progress) until terminal (ready/failed) or the wait budget is exhausted. " +
+			"Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " +
+			"Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render).",
+		inputSchema: {
+			slug: z.string(),
+			kind: kindSchema,
+			max_wait_seconds: z
+				.number()
+				.int()
+				.min(10)
+				.max(280)
+				.optional()
+				.describe("Default 240, capped at 280"),
+			poll_interval_seconds: z
+				.number()
+				.int()
+				.min(5)
+				.max(60)
+				.optional()
+				.describe("Default 15"),
+			save_path: z
+				.string()
+				.optional()
+				.describe(
+					"Optional .mp4 path to download to when ready (confined to HUBFLUENCER_OUTPUT_DIR or cwd)",
+				),
+		},
+		annotations: { title: "Wait for completion", ...RO },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				kind: Kind;
+				max_wait_seconds?: number;
+				poll_interval_seconds?: number;
+				save_path?: string;
+			},
+			client,
+			extra,
+		) => {
+			// Validate the save_path up front so a bad path fails before the wait.
+			if (args.save_path) resolveSavePath(args.save_path);
+			const budgetMs = (args.max_wait_seconds ?? 240) * 1000;
+			const intervalMs = (args.poll_interval_seconds ?? 15) * 1000;
+			const status = await pollToTerminal(
+				client,
+				args.kind,
+				args.slug,
+				extra,
+				budgetMs,
+				intervalMs,
+			);
+			let saved_to: string | null = null;
+			if (status.ready && status.video_url && args.save_path) {
+				saved_to = (await downloadTo(status.video_url, args.save_path))
+					.saved_to;
+			}
+			const out = { ...status, saved_to, timed_out: !status.terminal };
+			const links =
+				status.ready && status.video_url
+					? [mp4Link(status.video_url, args.slug)]
+					: [];
+			return ok(out, links);
+		},
+	),
+);
+
+// ── Download ──────────────────────────────────────────────────────────────────
+
+registerTool(
+	"download_result",
+	{
+		title: "Get / download the finished video",
+		description:
+			"Returns the post-ready MP4 URL for a completed project (presigned, ~24h TTL — use promptly). " +
+			"If save_path is given (confined to HUBFLUENCER_OUTPUT_DIR or cwd), the file is downloaded there.",
+		inputSchema: {
+			slug: z.string(),
+			kind: kindSchema,
+			save_path: z
+				.string()
+				.optional()
+				.describe("Optional .mp4 path inside the output base"),
+		},
+		annotations: { title: "Download result", ...RO },
+	},
+	tool(
+		async (args: { slug: string; kind: Kind; save_path?: string }, client) => {
+			const status = await fetchStatus(client, args.kind, args.slug);
+			if (!status.ready || !status.video_url) {
+				return fail(
+					`Not ready to download (stage=${status.stage}, ready=${status.ready}). Wait for completion first.`,
+				);
+			}
+			const link = [mp4Link(status.video_url, args.slug)];
+			if (args.save_path) {
+				const { saved_to, bytes } = await downloadTo(
+					status.video_url,
+					args.save_path,
+				);
+				return ok({ video_url: status.video_url, saved_to, bytes }, link);
+			}
+			return ok(
+				{
+					video_url: status.video_url,
+					note: "Presigned ~24h URL — download promptly.",
+				},
+				link,
+			);
+		},
+	),
+);
+
+// ── Boot ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	// stderr is safe; stdout is reserved for the MCP protocol.
+	console.error("hubfluencer-mcp running on stdio");
+}
+
+main().catch((e) => {
+	console.error("Fatal:", e);
+	process.exit(1);
+});