@viralspin/mcp 0.1.0 → 0.3.1

package/dist/tools/render-locally.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderLocallyStatusTool = exports.renderLocallyTool = void 0;
+exports.tm = tm;
+const client_js_1 = require("../client.js");
+const tokens_js_1 = require("../local-render/tokens.js");
+const render_js_1 = require("../local-render/render.js");
+const login_js_1 = require("../local-render/login.js");
+const jobs = new Map();
+let tokens = null;
+function tm() {
+    if (!tokens) {
+        // Nothing to sign in with (first time, or the 30-day refresh ran out): open the browser and let the person approve. No pasted tokens.
+        const interactive = process.env.VIRALSPIN_NO_BROWSER_LOGIN !== "1";
+        tokens = new tokens_js_1.TokenManager({
+            apiBase: client_js_1.PY_API_URL,
+            signIn: interactive ? async () => { await (0, login_js_1.login)({ apiBase: client_js_1.PY_API_URL, log: (l) => process.stderr.write(`[render_locally] ${l}\n`) }); } : undefined,
+        });
+    }
+    return tokens;
+}
+/** "Which reel?" with no arguments: the newest one the app sent to this person's computer and nobody has taken yet. */
+async function discover(log) {
+    const jobs = await (0, render_js_1.listPendingJobs)({ apiBase: client_js_1.PY_API_URL, tokens: tm() });
+    const { job, others, busy } = (0, render_js_1.pickJob)(jobs);
+    if (!job) {
+        if (busy.length) {
+            return { job: null, message: `Your reel "${busy[0].title || busy[0].job_id.slice(0, 8)}" is already being drawn on a computer (sent ${(0, render_js_1.ago)(busy[0].created_at)}). ` +
+                    `If that is this computer, call render_locally_status; to draw it again here, pass job_id "${busy[0].job_id}".` };
+        }
+        return { job: null, message: "There is no reel waiting for your computer. In the ViralSpin app, open a reel's style picker, choose \"On my computer\" and tap \"Send to my computer\" - then say \"Render my ViralSpin reel\" again." };
+    }
+    const name = job.title ? `"${job.title}"` : `job ${job.job_id.slice(0, 8)}`;
+    log(`[pick] your newest waiting reel: ${name}${job.duration_sec ? `, ${Math.round(Number(job.duration_sec))} s` : ""}, sent ${(0, render_js_1.ago)(job.created_at)}` +
+        (job.phase === "planning" ? " (ViralSpin is still preparing it - waiting for that)" : "") +
+        (others.length ? `; ${others.length} older one${others.length > 1 ? "s" : ""} also waiting - ask again afterwards to render the next` : ""));
+    return { job };
+}
+function tail(lines, n = 14) {
+    return lines.slice(-n).join("\n");
+}
+function report(r, lines) {
+    const head = r.dry_run
+        ? `Dry run OK - everything except the draw works on this computer (job ${r.job_id}).`
+        : `Rendered on this computer: ${r.output_path}`;
+    return [
+        head,
+        r.timing_path ? `timing: ${r.timing_path}` : "",
+        r.timing ? `draw ${r.timing.drawSeconds}s + mux ${r.timing.muxSeconds}s, ${r.timing.frames} frames, concurrency ${r.timing.concurrency}, ${r.timing.cores} threads, ${r.timing.ramGB} GB RAM, file ${r.timing.fileBytes} bytes` : "",
+        `prep: toolkit ${r.seconds.kit}s, plan ${r.seconds.plan}s, media ${r.seconds.download}s (${r.media.downloaded} downloaded, ${r.media.cached} cached); total ${r.seconds.total}s`,
+        r.completed ? (r.output_url ? "Done. The finished reel is in your ViralSpin app now (0 credits)." : "Reported back to ViralSpin (0 credits).") : "",
+        "",
+        "last log lines:",
+        tail(lines),
+        "",
+        JSON.stringify(r),
+    ].filter((x) => x !== "").join("\n");
+}
+exports.renderLocallyTool = {
+    name: "render_locally",
+    description: "Render a ViralSpin REEL on THIS computer (Mac or Windows) instead of the cloud: ViralSpin plans the reel and hands over the media, " +
+        "this machine does the Remotion draw and the audio mix, and the finished mp4 stays on disk (nothing is published or uploaded; 0 credits). " +
+        "First use downloads a ~0.5 GB render kit into ~/.viralspin/kit (needs Node 20+ and 8 GB free disk); later runs reuse it. " +
+        "WITH NO ARGUMENTS it renders the newest reel the person sent to their computer from the ViralSpin app (it says which one it picked); " +
+        "the first time it opens the browser once so they can approve ViralSpin (no tokens to paste). The finished reel is uploaded back so it appears in the app. " +
+        "Or give a job_id, a render_id (a reel the app already planned) or a reel request {plan, aroll_url}. dry_run:true does everything except the draw, to check the setup. " +
+        "A real run takes minutes; pass background:true to return at once and poll with render_locally_status.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "A job the app sent to this computer. Leave out to take the newest waiting one." },
+            upload: { type: "boolean", description: "Upload the finished mp4 so it appears in the app. Default true for app jobs." },
+            render_id: { type: "string", description: "A reel ViralSpin already planned (its render_id)." },
+            request: {
+                type: "object",
+                description: "OR the same body as POST /v1/reel/renders: { plan, aroll_url, style?, style_source? }.",
+                properties: { plan: { type: "object" }, aroll_url: { type: "string" }, style: { type: "string" }, style_source: { type: "object" } },
+                required: ["plan", "aroll_url"],
+            },
+            concurrency: { type: "number", description: `Frames drawn in parallel. Default min(4, cores/2) = ${(0, render_js_1.defaultConcurrency)()} here; 6+ was measured slower.` },
+            dry_run: { type: "boolean", description: "Install/update the kit, prepare the reel, download media, start the draw stack - then stop before drawing." },
+            complete: { type: "boolean", description: "After the draw, tell ViralSpin it finished (status + timing). Nothing is uploaded. Default false." },
+            background: { type: "boolean", description: "Return immediately with a job id; check progress with render_locally_status." },
+        },
+    },
+    async execute(args = {}, onProgress) {
+        const lines = [];
+        const log = (l) => {
+            lines.push(l);
+            process.stderr.write(`[render_locally] ${l}\n`);
+            onProgress?.(l);
+        };
+        // An app job (picked or named by job_id) is reported back and uploaded by default: the app is waiting for it.
+        let job_id = args.job_id;
+        const explicit = Boolean(args.render_id || args.request);
+        if (!job_id && !explicit) {
+            const found = await discover(log);
+            if (!found.job)
+                return found.message;
+            job_id = found.job.job_id;
+        }
+        const appJob = Boolean(job_id);
+        const run = () => (0, render_js_1.renderLocally)({
+            apiBase: client_js_1.PY_API_URL, tokens: tm(), render_id: args.render_id, request: args.request, job_id,
+            concurrency: args.concurrency, dryRun: args.dry_run, complete: args.complete ?? (appJob && !args.dry_run),
+            upload: args.upload, log,
+        });
+        if (args.background) {
+            const id = `bg-${Date.now().toString(36)}`;
+            const job = { state: "running", lines, started: Date.now() };
+            jobs.set(id, job);
+            run().then((r) => { job.state = "done"; job.result = r; }).catch((e) => { job.state = "failed"; job.error = String(e?.message || e); });
+            return `Started in the background: ${id}. Call render_locally_status with job_id "${id}" to follow it.`;
+        }
+        const r = await run();
+        return report(r, lines);
+    },
+};
+exports.renderLocallyStatusTool = {
+    name: "render_locally_status",
+    description: "Progress of a render_locally job started with background:true. With no job_id: your reels waiting for / being drawn on a computer, from ViralSpin.",
+    inputSchema: {
+        type: "object",
+        properties: { job_id: { type: "string" } },
+    },
+    async execute(args = {}) {
+        if (args.job_id) {
+            const j = jobs.get(args.job_id);
+            if (j) {
+                const secs = Math.round((Date.now() - j.started) / 1000);
+                if (j.state === "running")
+                    return `running (${secs}s)\n${tail(j.lines)}`;
+                if (j.state === "failed")
+                    return `failed after ${secs}s: ${j.error}\n${tail(j.lines)}`;
+                return report(j.result, j.lines);
+            }
+            // not a background handle of this process: it may be an app job id
+            const v = await tm().request("GET", `${client_js_1.PY_API_URL}/v1/reel/local-jobs/${encodeURIComponent(args.job_id)}`).catch(() => null);
+            if (!v)
+                return `No such local render job: ${args.job_id}`;
+            return describeJob(v);
+        }
+        const running = [...jobs.entries()].filter(([, j]) => j.state === "running");
+        const lines = running.map(([id, j]) => `${id}: running here (${Math.round((Date.now() - j.started) / 1000)}s)\n${tail(j.lines, 4)}`);
+        const pending = await (0, render_js_1.listPendingJobs)({ apiBase: client_js_1.PY_API_URL, tokens: tm() });
+        for (const p of pending)
+            lines.push(describeJob(p));
+        return lines.length ? lines.join("\n\n") : "Nothing is waiting or rendering. Send a reel from the ViralSpin app (style picker > On my computer > Send to my computer).";
+    },
+};
+function describeJob(v) {
+    const name = v.title ? `"${v.title}"` : v.job_id.slice(0, 8);
+    const says = {
+        planning: "ViralSpin is preparing it", waiting: "ready, waiting for your computer", rendering: "being drawn on a computer",
+        done: "finished - it is in the app", failed: `failed: ${v.error_message || "no reason given"}`, cancelled: "cancelled",
+    };
+    return `${name} (${v.job_id}): ${says[v.phase ?? ""] ?? v.status}, sent ${(0, render_js_1.ago)(v.created_at)}`;
+}

package/dist/tools/review.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkReviewStatusTool = exports.createReviewLinkTool = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const client_js_1 = require("../client.js");
+const APP_BASE = process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai";
+function makeToken() {
+    return crypto_1.default.randomBytes(9).toString("base64url").slice(0, 12);
+}
+exports.createReviewLinkTool = {
+    name: "create_review_link",
+    description: "After assembling a video, generate a private shareable review link for a client. " +
+        "The client opens the link in their browser — no account required — sees the video in a " +
+        "premium 'Private Review Room', and clicks Approve or Request Changes. " +
+        "Returns the review URL to paste into an email or DM.",
+    inputSchema: {
+        type: "object",
+        required: ["output_path"],
+        properties: {
+            output_path: {
+                type: "string",
+                description: "The local file path or public URL of the rendered MP4 — e.g. the path returned by create_video_assembly.",
+            },
+            metadata: {
+                type: "object",
+                description: "Optional context shown in the review room: caption, hook_text, style, format, platform_targets.",
+                properties: {
+                    caption: { type: "string" },
+                    hook_text: { type: "string" },
+                    style: { type: "string" },
+                    format: { type: "string", enum: ["9x16", "1x1", "16x9"] },
+                    platform_targets: { type: "array", items: { type: "string" } },
+                },
+            },
+            pin: {
+                type: "string",
+                description: "Optional 4-digit PIN the client must enter before viewing the review.",
+            },
+            expires_hours: {
+                type: "number",
+                description: "How many hours until the link expires (default: 168 = 7 days).",
+            },
+        },
+    },
+    async execute(args) {
+        const token = makeToken();
+        const expiresHours = args.expires_hours ?? 168;
+        await (0, client_js_1.post)("/v1/review-sessions", {
+            token,
+            output_path: args.output_path,
+            metadata: args.metadata ?? {},
+            pin: args.pin ?? null,
+            expires_hours: expiresHours,
+        });
+        const reviewUrl = `${APP_BASE}/review/${token}`;
+        return [
+            `✅ Review link created:`,
+            ``,
+            `  ${reviewUrl}`,
+            ``,
+            `Send this link to your client. They'll see the video in a private premiere room`,
+            `and can Approve or Request Changes — no account required.`,
+            args.pin ? `PIN required: ${args.pin}` : ``,
+            `Link expires in ${expiresHours >= 24 ? `${Math.round(expiresHours / 24)} days` : `${expiresHours}h`}.`,
+            ``,
+            `To check if they've approved: check_review_status with token "${token}"`,
+        ]
+            .filter((l) => l !== undefined)
+            .join("\n");
+    },
+};
+exports.checkReviewStatusTool = {
+    name: "check_review_status",
+    description: "Check whether a client has approved or requested changes on a review link. " +
+        "Pass the token from the URL (e.g. 'abc123xyz456' from /review/abc123xyz456).",
+    inputSchema: {
+        type: "object",
+        required: ["token"],
+        properties: {
+            token: {
+                type: "string",
+                description: "The 12-character review token from the review URL.",
+            },
+        },
+    },
+    async execute({ token }) {
+        const data = await (0, client_js_1.get)(`/v1/review-sessions/${token}/status`);
+        const statusLine = data.status === "approved"
+            ? `✅ Approved${data.approved_at ? ` on ${new Date(data.approved_at).toLocaleString()}` : ""}`
+            : data.status === "rejected"
+                ? `📝 Changes requested`
+                : `⏳ Pending — client hasn't reviewed yet`;
+        const lines = [statusLine];
+        if (data.feedback)
+            lines.push(``, `Client feedback: "${data.feedback}"`);
+        if (data.status === "approved")
+            lines.push(``, `Ready to publish with publish_now or schedule_post.`);
+        return lines.join("\n");
+    },
+};

package/dist/tools/timeline-edit.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keepWindowsTool = exports.removeSpansTool = exports.getTranscriptTool = exports.trimSilencesTool = exports.renderProjectTool = exports.reorderScenesTool = exports.removeSpanTool = exports.trimClipTool = void 0;
+/**
+ * Granular timeline edit verbs for a HOSTED Swap & Refine project (a narrative
+ * job). These widen Claude's editing vocabulary beyond swap — trim a cutaway,
+ * cut a span out of the cut, and reorder the A-roll's backbone scenes — each
+ * mapped to an already-deployed narrative endpoint, so the edit lands in the
+ * same project the web editor shows (and streams in live via realtime).
+ *
+ * All are hosted-only: they take a `job_id` (or VIRALSPIN_HOSTED_JOB_ID). There
+ * is no local-engine equivalent for these ops.
+ */
+const hosted_js_1 = require("../hosted.js");
+function fmt(sec) {
+    const m = Math.floor(sec / 60);
+    const s = Math.round(sec % 60);
+    return `${m}:${s.toString().padStart(2, "0")}`;
+}
+exports.trimClipTool = {
+    name: "trim_clip",
+    description: "Shorten (or restore) how long ONE B-roll cutaway stays on screen in a hosted Swap & Refine project, " +
+        "freeing that time back to the A-roll. Audio-safe — total video length is preserved. " +
+        "Get the segment id from suggest_clips. Instant timeline edit by default (no render); call render_project when done.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            segment_id: { type: "string", description: "The cutaway to trim (from suggest_clips)." },
+            duration_sec: { type: "number", description: "New on-screen duration in seconds (e.g. 1.5)." },
+            render: { type: "boolean", description: "Re-render now (costs credits). Default false = instant timeline-only edit." },
+        },
+        required: ["segment_id", "duration_sec"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "trim_clip is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        await (0, hosted_js_1.setClipDuration)(jobId, args.segment_id, args.duration_sec);
+        if (args.render) {
+            await (0, hosted_js_1.rerender)(jobId);
+            return `Trimmed segment ${args.segment_id} to ${args.duration_sec}s and started a re-render. ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        }
+        return (`Trimmed segment ${args.segment_id} to ${args.duration_sec}s (instant, no render). ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `Call render_project(job_id: "${jobId}") when the cut is final.`);
+    },
+};
+exports.removeSpanTool = {
+    name: "remove_span",
+    description: "Cut a span of time [from_sec, to_sec] out of a hosted Swap & Refine video — e.g. a duplicated opening " +
+        "sentence or a dead pause. The backbone A-roll is trimmed and the rest shifts up; reuses cached B-roll. " +
+        "Re-renders; streams into the editor.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            from_sec: { type: "number", description: "Start of the span to remove (seconds)." },
+            to_sec: { type: "number", description: "End of the span to remove (seconds)." },
+        },
+        required: ["from_sec", "to_sec"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "remove_span is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        if (!(args.to_sec > args.from_sec))
+            return "to_sec must be greater than from_sec.";
+        await (0, hosted_js_1.removeSpan)(jobId, args.from_sec, args.to_sec, true);
+        return (`Removing ${fmt(args.from_sec)}–${fmt(args.to_sec)} and re-rendering.\n` +
+            `Updating live: ${(0, hosted_js_1.editorUrl)(jobId)}`);
+    },
+};
+exports.reorderScenesTool = {
+    name: "reorder_scenes",
+    description: "See or reorder the A-roll's backbone scenes in a hosted Swap & Refine project. " +
+        "Call with no `order` to LIST the scenes (id + label + time) — the reorderable building blocks. " +
+        "Call with `order` (the scene ids in the new running order; omit ids to drop them) to apply it and re-render.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            order: {
+                type: "array",
+                items: { type: "string" },
+                description: "New running order as scene ids. Any scene id omitted here is removed from the cut. Omit `order` entirely to just list the scenes.",
+            },
+            render: { type: "boolean", description: "Re-render now (costs credits). Default false = instant timeline-only edit." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "reorder_scenes is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const { scenes } = await (0, hosted_js_1.detectScenes)(jobId);
+        if (!scenes.length)
+            return `No backbone scenes detected for project ${jobId} yet. Open it: ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        if (!args.order || !args.order.length) {
+            const lines = [...scenes]
+                .sort((a, b) => a.order - b.order)
+                .map((s) => `- ${s.id}${s.label ? ` — "${s.label}"` : ""}${s.src_start != null ? ` (${fmt(s.src_start)}${s.src_end != null ? `–${fmt(s.src_end)}` : ""})` : ""}`);
+            return [
+                `Backbone scenes in ${(0, hosted_js_1.editorUrl)(jobId)} :`,
+                ...lines,
+                ``,
+                `Reorder with: reorder_scenes(job_id: "${jobId}", order: ["${scenes[0].id}", …]). Omit a scene id to drop it.`,
+            ].join("\n");
+        }
+        const known = new Set(scenes.map((s) => s.id));
+        const wanted = args.order.filter((id) => known.has(id));
+        if (!wanted.length)
+            return "None of the given ids matched this project's scenes — call reorder_scenes with no `order` to list valid ids.";
+        const payload = scenes.map((s) => {
+            const idx = wanted.indexOf(s.id);
+            return { id: s.id, order: idx === -1 ? 9999 : idx, removed: idx === -1 };
+        });
+        await (0, hosted_js_1.saveSceneOrder)(jobId, payload);
+        const dropped = scenes.length - wanted.length;
+        if (args.render) {
+            await (0, hosted_js_1.rerender)(jobId);
+            return `Reordered to ${wanted.length} scene(s)${dropped ? ` (dropped ${dropped})` : ""} and started a re-render. ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        }
+        return (`Reordered to ${wanted.length} scene(s)${dropped ? ` (dropped ${dropped})` : ""} (instant, no render). ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `Call render_project(job_id: "${jobId}") when the cut is final.`);
+    },
+};
+exports.renderProjectTool = {
+    name: "render_project",
+    description: "Bake the current hosted Swap & Refine timeline into a final MP4 — the ONE cloud render after a batch of " +
+        "instant timeline edits (swap_clip / trim_clip / reorder_scenes). Captions, hook, overlays and motion are " +
+        "applied here. Costs a render/credits. Returns immediately; the finished preview lands on the project, then " +
+        "publish with publish_now or schedule_post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "render_project is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        await (0, hosted_js_1.rerender)(jobId);
+        return (`Rendering the final cut for project ${jobId}.\n` +
+            `Watch it in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `When it finishes, publish with publish_now or schedule_post.`);
+    },
+};
+exports.trimSilencesTool = {
+    name: "trim_silences",
+    description: "Edit out the dead air / empty pauses in a hosted Swap & Refine project. Reads the transcript word " +
+        "timings, finds the silent gaps between spoken words (plus a long lead-in / trailing pause), and removes " +
+        "them to tighten the cut. It re-cuts the A-roll once per gap, so it can take a couple of minutes on a " +
+        "long clip — it does the BIGGEST gaps first (capped by max_cuts). Needs a transcribed talking-head A-roll.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            min_gap_sec: { type: "number", description: "Smallest pause to treat as dead air (default 0.7s). Lower = tighter." },
+            max_cuts: { type: "number", description: "Safety cap on how many gaps to remove this pass (default 12, biggest first)." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "trim_silences is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const minGap = args.min_gap_sec ?? 0.7;
+        const maxCuts = args.max_cuts ?? 12;
+        const PAD = 0.1;
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const tl = job.timeline || {};
+        const words = Array.isArray(tl.words) ? tl.words : [];
+        if (words.length < 2) {
+            return "No transcript word-timings on this project, so I can't detect silences (needs a transcribed talking-head A-roll).";
+        }
+        const total = Number(tl.total_duration_sec) || Number(words[words.length - 1]?.end) || 0;
+        const gaps = [];
+        // long lead-in pause
+        const firstStart = Number(words[0]?.start) || 0;
+        if (firstStart >= minGap + PAD)
+            gaps.push({ from: PAD, to: +(firstStart - PAD).toFixed(2), len: firstStart });
+        // gaps between words
+        for (let i = 0; i < words.length - 1; i++) {
+            const a = Number(words[i]?.end), b = Number(words[i + 1]?.start);
+            if (!Number.isFinite(a) || !Number.isFinite(b))
+                continue;
+            const len = b - a;
+            if (len >= minGap)
+                gaps.push({ from: +(a + PAD).toFixed(2), to: +(b - PAD).toFixed(2), len });
+        }
+        // trailing pause
+        const lastEnd = Number(words[words.length - 1]?.end) || 0;
+        if (total - lastEnd >= minGap + PAD)
+            gaps.push({ from: +(lastEnd + PAD).toFixed(2), to: +total.toFixed(2), len: total - lastEnd });
+        const valid = gaps.filter((g) => g.to - g.from >= 0.2);
+        if (!valid.length)
+            return `No silences ≥ ${minGap}s found — the cut is already tight.`;
+        // biggest gaps first (within the cap), then remove latest→earliest so each
+        // removal doesn't invalidate the earlier gaps' timestamps.
+        const chosen = [...valid].sort((a, b) => b.len - a.len).slice(0, maxCuts).sort((a, b) => b.from - a.from);
+        let removed = 0;
+        let ok = 0;
+        for (const g of chosen) {
+            try {
+                await (0, hosted_js_1.removeSpan)(jobId, g.from, g.to, false);
+                removed += g.to - g.from;
+                ok++;
+            }
+            catch (e) {
+                process.stderr.write(`[trim_silences] span ${g.from}-${g.to} failed: ${e instanceof Error ? e.message : e}\n`);
+            }
+        }
+        if (!ok)
+            return "Couldn't trim the silences — the backend rejected the spans. The project may not allow span removal yet.";
+        await (0, hosted_js_1.rerender)(jobId);
+        const more = valid.length > chosen.length ? ` (${valid.length - chosen.length} smaller pause(s) left — run again or lower min_gap_sec)` : "";
+        return (`Trimmed ${ok} silent gap(s) — about ${removed.toFixed(1)}s of dead air${more} — and started a re-render.\n` +
+            `Watch it tighten in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}`);
+    },
+};
+exports.getTranscriptTool = {
+    name: "get_transcript",
+    description: "Get the timestamped transcript of a hosted Swap & Refine project so YOU (the agent) can spot what to cut " +
+        "— bad takes, restarts ('let me start over'), repeated sentences, filler — or which moments are worth " +
+        "highlighting in a long talking/narrated video. Returns spoken segments with start/end times. Then act: " +
+        "remove_spans to cut bad parts, or keep_windows to keep only the highlight moments.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "get_transcript is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const tl = job.timeline || {};
+        let segs = [];
+        if (Array.isArray(tl.transcript) && tl.transcript.length) {
+            segs = tl.transcript.map((s) => ({ a: Number(s.start_sec ?? s.start ?? 0), b: Number(s.end_sec ?? s.end ?? 0), text: String(s.text ?? "").trim() }));
+        }
+        else if (Array.isArray(tl.words) && tl.words.length) {
+            // group words into phrases on pauses > 0.5s
+            let cur = null;
+            for (const w of tl.words) {
+                const a = Number(w.start), b = Number(w.end), t = String(w.word ?? w.text ?? "");
+                if (!Number.isFinite(a))
+                    continue;
+                if (cur && a - cur.b > 0.5) {
+                    segs.push(cur);
+                    cur = null;
+                }
+                if (!cur)
+                    cur = { a, b, text: t };
+                else {
+                    cur.b = b;
+                    cur.text += (t.startsWith("'") ? "" : " ") + t;
+                }
+            }
+            if (cur)
+                segs.push(cur);
+        }
+        if (!segs.length)
+            return "No transcript on this project (needs a transcribed talking-head/narrated A-roll).";
+        const lines = segs.map((s) => `[${s.a.toFixed(1)}–${s.b.toFixed(1)}] ${s.text}`);
+        return [
+            `Transcript for ${jobId} (spot restarts / repeats / filler to cut, or highlight moments to keep):`,
+            ...lines,
+            ``,
+            `Cut bad spans: remove_spans(job_id: "${jobId}", spans: [{from_sec, to_sec}, …]).`,
+            `Keep only highlights: keep_windows(job_id: "${jobId}", windows: [{from_sec, to_sec}, …]).`,
+        ].join("\n");
+    },
+};
+/** Remove several spans (latest→earliest so earlier coords stay valid), one render. */
+async function removeMany(jobId, spans) {
+    const ordered = [...spans].filter((s) => s.to - s.from >= 0.15).sort((a, b) => b.from - a.from);
+    let ok = 0, removed = 0;
+    for (const s of ordered) {
+        try {
+            await (0, hosted_js_1.removeSpan)(jobId, +s.from.toFixed(2), +s.to.toFixed(2), false);
+            removed += s.to - s.from;
+            ok++;
+        }
+        catch (e) {
+            process.stderr.write(`[removeMany] ${s.from}-${s.to} failed: ${e instanceof Error ? e.message : e}\n`);
+        }
+    }
+    return { ok, removed };
+}
+exports.removeSpansTool = {
+    name: "remove_spans",
+    description: "Cut SEVERAL time spans out of a hosted project in one pass (e.g. bad takes / restarts you found via " +
+        "get_transcript), then re-render once. Spans are seconds of the current cut. Re-cuts the A-roll per span, " +
+        "so several takes a minute or two.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "Project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            spans: {
+                type: "array",
+                items: { type: "object", properties: { from_sec: { type: "number" }, to_sec: { type: "number" } }, required: ["from_sec", "to_sec"] },
+                description: "Spans to cut, each { from_sec, to_sec }.",
+            },
+        },
+        required: ["spans"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "remove_spans is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const spans = (args.spans || []).filter((s) => s && s.to_sec > s.from_sec).map((s) => ({ from: +s.from_sec, to: +s.to_sec }));
+        if (!spans.length)
+            return "No valid spans (each needs to_sec > from_sec).";
+        const { ok, removed } = await removeMany(jobId, spans);
+        if (!ok)
+            return "Couldn't remove the spans — the backend rejected them.";
+        await (0, hosted_js_1.rerender)(jobId);
+        return `Removed ${ok} span(s) — about ${removed.toFixed(1)}s — and started a re-render.\n${(0, hosted_js_1.editorUrl)(jobId)}`;
+    },
+};
+exports.keepWindowsTool = {
+    name: "keep_windows",
+    description: "Turn a long video into a highlight reel: KEEP only the given time windows and cut everything else, then " +
+        "re-render. Great for 'find the worth-highlighting moments in this 10-min recording' — get_transcript, " +
+        "pick the punchy windows, then keep_windows. Windows are seconds of the current cut.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "Project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            windows: {
+                type: "array",
+                items: { type: "object", properties: { from_sec: { type: "number" }, to_sec: { type: "number" } }, required: ["from_sec", "to_sec"] },
+                description: "The moments to KEEP, each { from_sec, to_sec }. Everything outside them is cut.",
+            },
+        },
+        required: ["windows"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "keep_windows is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const wins = (args.windows || []).filter((w) => w && w.to_sec > w.from_sec).map((w) => ({ from: +w.from_sec, to: +w.to_sec })).sort((a, b) => a.from - b.from);
+        if (!wins.length)
+            return "No valid windows to keep (each needs to_sec > from_sec).";
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const total = Number(job.timeline?.total_duration_sec) || wins[wins.length - 1].to;
+        // complement = everything outside the kept windows
+        const cuts = [];
+        if (wins[0].from > 0.15)
+            cuts.push({ from: 0, to: wins[0].from });
+        for (let i = 0; i < wins.length - 1; i++) {
+            if (wins[i + 1].from - wins[i].to > 0.15)
+                cuts.push({ from: wins[i].to, to: wins[i + 1].from });
+        }
+        if (total - wins[wins.length - 1].to > 0.15)
+            cuts.push({ from: wins[wins.length - 1].to, to: total });
+        if (!cuts.length)
+            return "The windows already cover the whole video — nothing to cut.";
+        const { ok, removed } = await removeMany(jobId, cuts);
+        if (!ok)
+            return "Couldn't trim to the windows — the backend rejected the spans.";
+        await (0, hosted_js_1.rerender)(jobId);
+        const kept = wins.reduce((s, w) => s + (w.to - w.from), 0);
+        return `Kept ${wins.length} highlight window(s) (~${kept.toFixed(1)}s), cut ~${removed.toFixed(1)}s, and started a re-render.\n${(0, hosted_js_1.editorUrl)(jobId)}`;
+    },
+};