@viralspin/mcp 0.2.0 → 0.4.0

package/dist/local-render/startup.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultEnv = void 0;
+exports.startupCommand = startupCommand;
+exports.plistFor = plistFor;
+exports.installStartup = installStartup;
+exports.uninstallStartup = uninstallStartup;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Start the connector when this person signs in to their computer (`viralspin-mcp watch --install`), so "Render on my computer" just works.
+ * Windows: a Run key under HKEY_CURRENT_USER (no admin). macOS: a LaunchAgent plist (written, not loaded: it starts at the next sign-in, like
+ * the Windows key, so a second copy never collides with one already running). Other systems: said plainly, nothing is changed.
+ */
+const NAME = "ViralSpinConnector";
+const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+const defaultEnv = () => ({ platform: process.platform, node: process.execPath, script: process.argv[1] ?? "", home: os_1.default.homedir() });
+exports.defaultEnv = defaultEnv;
+/** The command line the system runs at sign-in. Pure so it is tested. */
+function startupCommand(e) {
+    return `"${e.node}" "${e.script}" watch`;
+}
+function plistFor(e) {
+    const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>ai.viralspin.connector</string>
+<key>ProgramArguments</key><array><string>${esc(e.node)}</string><string>${esc(e.script)}</string><string>watch</string></array>
+<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
+<key>StandardOutPath</key><string>${esc(path_1.default.join(e.home, ".viralspin", "watch.log"))}</string>
+<key>StandardErrorPath</key><string>${esc(path_1.default.join(e.home, ".viralspin", "watch.log"))}</string>
+</dict></plist>
+`;
+}
+const plistPath = (e) => path_1.default.join(e.home, "Library", "LaunchAgents", "ai.viralspin.connector.plist");
+function installStartup(e = (0, exports.defaultEnv)(), run = child_process_1.execFileSync) {
+    if (!e.script)
+        return "Could not tell where this program is installed, so nothing was changed. Install it with: npm i -g @viralspin/mcp";
+    if (e.platform === "win32") {
+        run("reg", ["add", RUN_KEY, "/v", NAME, "/t", "REG_SZ", "/d", startupCommand(e), "/f"], { stdio: "ignore" });
+        return "The connector will start when you sign in to this computer. Start it now with: viralspin-mcp watch";
+    }
+    if (e.platform === "darwin") {
+        const p = plistPath(e);
+        fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+        fs_1.default.mkdirSync(path_1.default.join(e.home, ".viralspin"), { recursive: true });
+        fs_1.default.writeFileSync(p, plistFor(e));
+        return `The connector will start at your next sign-in (${p}). Start it now with: viralspin-mcp watch`;
+    }
+    return "Start-at-sign-in is set up for Windows and macOS only. On this system, run: viralspin-mcp watch";
+}
+function uninstallStartup(e = (0, exports.defaultEnv)(), run = child_process_1.execFileSync) {
+    if (e.platform === "win32") {
+        try {
+            run("reg", ["delete", RUN_KEY, "/v", NAME, "/f"], { stdio: "ignore" });
+        }
+        catch { /* it was not there */ }
+        return "The connector will no longer start when you sign in.";
+    }
+    if (e.platform === "darwin") {
+        try {
+            fs_1.default.unlinkSync(plistPath(e));
+        }
+        catch { /* it was not there */ }
+        return "The connector will no longer start when you sign in.";
+    }
+    return "Nothing to remove on this system.";
+}

package/dist/local-render/tokens.js

@@ -0,0 +1,201 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenManager = exports.RefreshRefused = void 0;
+exports.jwtExpiry = jwtExpiry;
+exports.saveTokens = saveTokens;
+exports.defaultTokenFile = defaultTokenFile;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function jwtExpiry(token) {
+    try {
+        const part = token.split(".")[1];
+        if (!part)
+            return null;
+        const json = JSON.parse(Buffer.from(part.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+        return typeof json.exp === "number" ? json.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the token file owner-only (dir 0700, file 0600), atomically. chmod even if the file existed with looser bits. */
+function saveTokens(file, data) {
+    const dir = path_1.default.dirname(file);
+    fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch { /* not ours to chmod (a shared home on Windows) */ }
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs_1.default.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+    try {
+        fs_1.default.chmodSync(tmp, 0o600);
+    }
+    catch { /* Windows */ }
+    fs_1.default.renameSync(tmp, file);
+}
+function defaultTokenFile() {
+    return path_1.default.join(os_1.default.homedir(), ".viralspin", "oauth.json");
+}
+/** The server said the refresh token is no good (expired, revoked): a new sign-in is the only way forward. */
+class RefreshRefused extends Error {
+}
+exports.RefreshRefused = RefreshRefused;
+class TokenManager {
+    constructor(opts) {
+        this.opts = opts;
+        this.mem = null;
+        this.refreshCount = 0;
+        this.signing = null;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.file = opts.file ?? defaultTokenFile();
+        this.env = opts.env ?? process.env;
+        this.now = opts.now ?? Date.now;
+        this.skew = opts.skewSec ?? 120;
+    }
+    readFile() {
+        try {
+            const j = JSON.parse(fs_1.default.readFileSync(this.file, "utf8"));
+            return j && typeof j.access_token === "string" ? j : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    fromEnv() {
+        const a = this.env.VIRALSPIN_OAUTH_TOKEN;
+        if (!a && !this.env.VIRALSPIN_OAUTH_REFRESH_TOKEN)
+            return null;
+        return {
+            access_token: a || "",
+            refresh_token: this.env.VIRALSPIN_OAUTH_REFRESH_TOKEN || undefined,
+            client_id: this.env.VIRALSPIN_OAUTH_CLIENT_ID || undefined,
+        };
+    }
+    expiry(p) {
+        if (!p.access_token)
+            return 0;
+        return jwtExpiry(p.access_token) ?? Number.POSITIVE_INFINITY; // not a JWT with exp: trust until the server says 401
+    }
+    /** The candidate with the latest expiry (re-read from the file every call). */
+    best() {
+        const all = [this.mem, this.readFile(), this.fromEnv()].filter(Boolean);
+        if (!all.length)
+            return null;
+        return all.sort((a, b) => this.expiry(b) - this.expiry(a))[0];
+    }
+    refreshToken() {
+        for (const p of [this.mem, this.readFile(), this.fromEnv()]) {
+            if (p?.refresh_token)
+                return { rt: p.refresh_token, client_id: p.client_id };
+        }
+        return null;
+    }
+    /** Run the browser sign-in, one at a time, and forget anything stale held in memory. */
+    async signInNow() {
+        if (!this.opts.signIn)
+            return false;
+        this.signing ?? (this.signing = this.opts.signIn().finally(() => { this.signing = null; }));
+        await this.signing;
+        this.mem = null;
+        return true;
+    }
+    async getAccessToken() {
+        let cur = this.best();
+        if (!cur && (await this.signInNow()))
+            cur = this.best();
+        if (!cur) {
+            throw new Error("Not signed in to ViralSpin on this computer. Run `npx -y @viralspin/mcp login` once (it opens your browser), " +
+                "or set VIRALSPIN_OAUTH_TOKEN (+ VIRALSPIN_OAUTH_REFRESH_TOKEN) in the MCP server's env.");
+        }
+        const nowSec = this.now() / 1000;
+        if (cur.access_token && this.expiry(cur) - nowSec > this.skew)
+            return cur.access_token;
+        if (this.refreshToken()) {
+            try {
+                return await this.refresh();
+            }
+            catch (e) {
+                // the 30-day refresh token ran out (or was revoked): sign in again in the browser, if we can
+                if (!(e instanceof RefreshRefused) || !(await this.signInNow()))
+                    throw e;
+                const fresh = this.best();
+                if (fresh?.access_token)
+                    return fresh.access_token;
+                throw e;
+            }
+        }
+        if (cur.access_token)
+            return cur.access_token; // nothing to refresh with: let the server judge it
+        throw new Error("The ViralSpin sign-in has expired and there is no refresh token. Sign in again.");
+    }
+    async refresh() {
+        const r = this.refreshToken();
+        if (!r)
+            throw new Error("The ViralSpin sign-in expired and there is no refresh token (VIRALSPIN_OAUTH_REFRESH_TOKEN). Sign in again.");
+        const form = new URLSearchParams({ grant_type: "refresh_token", refresh_token: r.rt });
+        if (r.client_id)
+            form.set("client_id", r.client_id);
+        const resp = await this.fetchImpl(`${this.opts.apiBase}/v1/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: form.toString(),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            const msg = `Could not renew the ViralSpin sign-in (${resp.status}). The refresh token lasts 30 days; sign in again. ${text.slice(0, 160)}`;
+            throw resp.status === 400 || resp.status === 401 ? new RefreshRefused(msg) : new Error(msg);
+        }
+        const j = (await resp.json());
+        if (!j.access_token)
+            throw new Error("The token endpoint answered without an access_token.");
+        this.mem = { access_token: j.access_token, refresh_token: j.refresh_token || r.rt, client_id: r.client_id };
+        this.refreshCount++;
+        try {
+            saveTokens(this.file, { ...this.mem });
+        }
+        catch {
+            /* the file is a convenience; memory is enough for this process */
+        }
+        return j.access_token;
+    }
+    /** Authenticated JSON request; one retry after a refresh when the server says 401. */
+    async request(method, url, body) {
+        const go = async (token) => this.fetchImpl(url, {
+            method,
+            headers: { Authorization: `Bearer ${token}`, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        let resp = await go(await this.getAccessToken());
+        if (resp.status === 401 && (this.refreshToken() || this.opts.signIn)) {
+            let fresh;
+            try {
+                fresh = this.refreshToken() ? await this.refresh() : (await this.signInNow(), await this.getAccessToken());
+            }
+            catch (e) {
+                if (!(e instanceof RefreshRefused) || !(await this.signInNow()))
+                    throw e;
+                fresh = await this.getAccessToken();
+            }
+            resp = await go(fresh);
+        }
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            let detail = text;
+            try {
+                const d = JSON.parse(text).detail;
+                detail = typeof d === "string" ? d : JSON.stringify(d ?? text);
+            }
+            catch {
+                /* keep text */
+            }
+            throw new Error(`API error ${resp.status} on ${method} ${url.replace(this.opts.apiBase, "")}: ${detail.slice(0, 400)}`);
+        }
+        return (await resp.json());
+    }
+}
+exports.TokenManager = TokenManager;

package/dist/local-render/watch.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newWatchState = exports.POLL_MS = exports.PING_EVERY_MS = void 0;
+exports.watchTick = watchTick;
+exports.nextDelay = nextDelay;
+exports.watchLoop = watchLoop;
+const render_js_1 = require("./render.js");
+exports.PING_EVERY_MS = 15000;
+exports.POLL_MS = 4000;
+const MAX_BACKOFF_MS = 60000;
+const newWatchState = () => ({ lastPing: 0, failed: new Set(), errors: 0, pingWarned: false });
+exports.newWatchState = newWatchState;
+async function watchTick(d, st) {
+    if (d.now() - st.lastPing >= exports.PING_EVERY_MS) {
+        st.lastPing = d.now();
+        try {
+            await d.ping();
+            st.pingWarned = false;
+        }
+        catch (e) {
+            if (!st.pingWarned) {
+                d.log(`[watch] could not tell ViralSpin this computer is online (${e.message}); will keep trying`);
+                st.pingWarned = true;
+            }
+        }
+    }
+    let jobs;
+    try {
+        jobs = await d.list();
+        st.errors = 0;
+    }
+    catch (e) {
+        st.errors++;
+        d.log(`[watch] could not ask ViralSpin for jobs (${e.message})`);
+        return { did: "error" };
+    }
+    const { job } = (0, render_js_1.pickJob)(jobs.filter((j) => !st.failed.has(j.job_id)));
+    // a job ViralSpin is still preparing is waited for by the render itself (it polls); starting it now only means this computer holds it from here
+    if (!job)
+        return { did: "idle" };
+    const name = job.title ? `"${job.title}"` : job.job_id.slice(0, 8);
+    d.log(`[watch] drawing ${name}${job.duration_sec ? ` (${Math.round(Number(job.duration_sec))} s)` : ""}`);
+    try {
+        await d.render(job.job_id);
+        d.log(`[watch] finished ${name}`);
+        return { did: "rendered", jobId: job.job_id };
+    }
+    catch (e) {
+        st.failed.add(job.job_id);
+        d.log(`[watch] ${name} failed on this computer: ${e.message}`);
+        return { did: "failed", jobId: job.job_id };
+    }
+}
+/** Wait before the next pass: soon after work, a little longer when idle, much longer while ViralSpin is unreachable. */
+function nextDelay(r, st) {
+    if (r.did === "rendered" || r.did === "failed")
+        return 500;
+    if (r.did === "error")
+        return Math.min(MAX_BACKOFF_MS, exports.POLL_MS * 2 ** Math.min(st.errors, 4));
+    return exports.POLL_MS;
+}
+async function watchLoop(d, o = {}) {
+    const st = (0, exports.newWatchState)();
+    d.log("[watch] ViralSpin connector is running. Send a reel to your computer from the app and it draws here. Ctrl+C to stop.");
+    while (!o.signal?.aborted) {
+        const r = await watchTick(d, st);
+        await d.sleep(nextDelay(r, st));
+    }
+}

package/dist/sanitize.js

@@ -0,0 +1,22 @@
+"use strict";
+// Strips unpaired UTF-16 surrogates from strings so MCP responses can be
+// safely JSON-serialized and written to the stdio transport. Lone surrogates
+// (e.g. an emoji's surrogate pair cut in half by a fixed-length .slice) cause
+// the transport's UTF-8 encoder to throw "no low surrogate in string".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeSurrogates = sanitizeSurrogates;
+exports.sanitizeObject = sanitizeObject;
+const UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+function sanitizeSurrogates(str) {
+    return str.replace(UNPAIRED_SURROGATE, "");
+}
+function sanitizeObject(obj) {
+    if (typeof obj === "string")
+        return sanitizeSurrogates(obj);
+    if (Array.isArray(obj))
+        return obj.map(sanitizeObject);
+    if (obj && typeof obj === "object") {
+        return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, sanitizeObject(v)]));
+    }
+    return obj;
+}

package/dist/tools/assembly-adjust.js

@@ -6,13 +6,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.swapCaptionStyleTool = exports.swapClipTool = exports.suggestClipsTool = void 0;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
-// Adjustment tools operate on the most recent create_video_assembly project (the engine keeps the
-// timeline + analyzed candidate pool + staged clips on disk), so suggesting is instant and swapping
-// just re-renders. Same engine dir as create_video_assembly.
-const ENGINE_DIR = process.env.VIRALSPIN_ASSEMBLY_DIR || "E:/AI test/carissa bot/assembly-engine";
+const hosted_js_1 = require("../hosted.js");
+const engine_js_1 = require("../engine.js");
+// Adjustment tools operate on the most recent create_video_assembly project. By
+// default that's the LOCAL engine project (the engine keeps the timeline +
+// analyzed candidate pool + staged clips on disk), so suggesting is instant and
+// swapping just re-renders locally. When a hosted project is targeted instead —
+// a `job_id` arg, or the VIRALSPIN_HOSTED_JOB_ID env set by a hosted
+// create_video_assembly — the same verbs drive the web Swap & Refine project via
+// the deployed narrative endpoints, so the edit shows up in the browser editor.
+// Shown when a local action is requested but no engine is bundled (the public
+// npm package) and no hosted project is targeted.
+const NO_LOCAL_ENGINE = "This local action needs the ViralSpin engine, which isn't bundled in this install.\n" +
+    "Target a hosted Swap & Refine project instead — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID) — " +
+    "or set VIRALSPIN_ASSEMBLY_DIR to a local engine checkout.";
 function runEngine(args) {
     return new Promise((resolve, reject) => {
-        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(ENGINE_DIR, "assemble.mjs"), ...args], { cwd: ENGINE_DIR, env: { ...process.env } });
+        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(engine_js_1.ENGINE_DIR, "assemble.mjs"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
         let stdout = "";
         child.stdout.on("data", (d) => { stdout += d.toString(); });
         child.stderr.on("data", (d) => process.stderr.write(d));
@@ -22,17 +32,56 @@ function runEngine(args) {
 }
 exports.suggestClipsTool = {
     name: "suggest_clips",
-    description: "Get ranked alternative B-roll for one cutaway in the most recently assembled video (from create_video_assembly). " +
-        "Returns options ranked by how well they fit that moment's transcript, each with a thumbnail image path you can open. " +
-        "Then call swap_clip to apply a choice. Instant — reuses the cached analysis, no re-render.",
+    description: "See a project's cutaways and find better B-roll for one of them. " +
+        "LOCAL project (default): pass `cut` (0-based) to get ranked alternatives for that cutaway, each with a thumbnail. " +
+        "HOSTED Swap & Refine project (pass `job_id`, or set VIRALSPIN_HOSTED_JOB_ID): " +
+        "call with no `query` to list the timeline's cutaways (segment id + the beat each covers + current clip); " +
+        "call with `query` (e.g. \"newborn in hospital\") to search the user's B-roll library — each result includes the " +
+        "library tags it matched on, which is the 'why this clip fits' to show the user. " +
+        "Then call swap_clip to apply a choice.",
     inputSchema: {
         type: "object",
         properties: {
-            cut: { type: "number", description: "Index of the cutaway to replace (0-based; from the cut list create_video_assembly returns)." },
+            cut: { type: "number", description: "LOCAL only: index of the cutaway to replace (0-based; from the cut list create_video_assembly returns)." },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project (narrative job) to inspect. Omit to use VIRALSPIN_HOSTED_JOB_ID, or the local project." },
+            query: { type: "string", description: "HOSTED: theme to search the B-roll library for (the moment's subject). Omit to list the timeline's cutaways instead." },
         },
-        required: ["cut"],
     },
     async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            // Hosted project: either list the timeline's cutaways, or search the
+            // library for alternatives (with the matched tags = the "why").
+            if (args.query) {
+                const r = await (0, hosted_js_1.searchLibrary)(args.query);
+                if (!r.items.length)
+                    return `No library B-roll matched "${args.query}". Try a broader term.`;
+                const lines = r.items.map((it, i) => `${i + 1}. ${it.url}\n   ${it.kind}${it.album ? ` · from "${it.album}"` : ""} — matched on: "${args.query}"`);
+                return [
+                    `B-roll matching "${args.query}" (best fit first):`,
+                    ...lines,
+                    ``,
+                    `Apply one with: swap_clip(job_id: "${jobId}", segment_id: "<from the cutaway list>", asset_url: "<url above>").`,
+                ].join("\n");
+            }
+            const job = await (0, hosted_js_1.getJob)(jobId);
+            const segs = (0, hosted_js_1.listSegments)(job.timeline);
+            if (!segs.length) {
+                return `Project ${jobId} has no listable cutaways yet (status: ${job.status}). Open it: ${(0, hosted_js_1.editorUrl)(jobId)}`;
+            }
+            const lines = segs.map((s, i) => `${i + 1}. segment ${s.id}${s.beat ? ` — "${s.beat}"` : ""}${s.asset_url ? `\n   current: ${s.asset_url}` : ""}`);
+            return [
+                `Cutaways in ${(0, hosted_js_1.editorUrl)(jobId)} :`,
+                ...lines,
+                ``,
+                `Find alternatives for one: suggest_clips(job_id: "${jobId}", query: "<what that moment is about>").`,
+            ].join("\n");
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        if (args.cut === undefined) {
+            return "For a local project, pass `cut` (the 0-based cutaway index). For a hosted Swap & Refine project, pass `job_id`.";
+        }
         const out = await runEngine(["--suggest", String(args.cut)]);
         const m = out.match(/SUGGEST:(.+)/);
         if (!m)
@@ -50,17 +99,49 @@ exports.suggestClipsTool = {
 };
 exports.swapClipTool = {
     name: "swap_clip",
-    description: "Replace one cutaway in the most recently assembled video with a chosen B-roll asset (from suggest_clips), then re-render. " +
-        "Returns the path to the updated MP4.",
+    description: "Replace one cutaway with a chosen B-roll asset (from suggest_clips), then re-render. " +
+        "LOCAL project (default): pass `cut` (0-based) + `asset` (filename) → re-renders locally, returns the MP4 path. " +
+        "HOSTED Swap & Refine project (pass `job_id`, or set VIRALSPIN_HOSTED_JOB_ID): pass `segment_id` + `asset_url` → " +
+        "patches the same timeline the browser editor shows and kicks off a cloud re-render; the change appears live in " +
+        "Swap & Refine. Returns immediately — the new preview lands on the project shortly.",
     inputSchema: {
         type: "object",
         properties: {
-            cut: { type: "number", description: "Index of the cutaway to replace (0-based)." },
-            asset: { type: "string", description: "Asset filename from suggest_clips (e.g. \"v03.mp4\" or \"07.jpg\")." },
+            cut: { type: "number", description: "LOCAL: index of the cutaway to replace (0-based)." },
+            asset: { type: "string", description: "LOCAL: asset filename from suggest_clips (e.g. \"v03.mp4\" or \"07.jpg\")." },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            segment_id: { type: "string", description: "HOSTED: the cutaway's segment id (from suggest_clips)." },
+            asset_url: { type: "string", description: "HOSTED: public URL of the replacement B-roll (from suggest_clips)." },
+            asset_kind: { type: "string", enum: ["broll_video", "broll_photo"], description: "HOSTED: optional — kind of the replacement asset." },
+            reason: { type: "string", description: "HOSTED: optional one-line rationale for WHY this clip fits here (e.g. \"the line says 'the day she arrived'\"). Stored as provenance + shown on the timeline." },
+            render: { type: "boolean", description: "HOSTED: re-render now (costs a render/credits). Default false = instant timeline-only edit; iterate freely, then call render_project once to bake & publish." },
         },
-        required: ["cut", "asset"],
     },
     async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            if (!args.segment_id || !args.asset_url) {
+                return "For a hosted project, pass `segment_id` and `asset_url` (both from suggest_clips).";
+            }
+            let kind = args.asset_kind;
+            if (!kind)
+                kind = /\.(mp4|mov|webm|m4v)(\?|$)/i.test(args.asset_url) ? "broll_video" : "broll_photo";
+            await (0, hosted_js_1.swapSegment)(jobId, args.segment_id, args.asset_url, kind, args.reason);
+            if (args.render) {
+                await (0, hosted_js_1.rerender)(jobId);
+                return (`Swapped segment ${args.segment_id} → ${args.asset_url}${args.reason ? ` (${args.reason})` : ""} and started a cloud re-render.\n` +
+                    `Updating live in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+                    `Publish it with publish_now or schedule_post once it finishes.`);
+            }
+            return (`Swapped segment ${args.segment_id} → ${args.asset_url}${args.reason ? ` (${args.reason})` : ""} (instant, no render).\n` +
+                `Keep editing freely — it's all on the timeline. Open: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+                `When the cut is right, call render_project(job_id: "${jobId}") to bake captions/overlays and get the final MP4.`);
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
+        if (args.cut === undefined || !args.asset) {
+            return "For a local project, pass `cut` and `asset`. For a hosted Swap & Refine project, pass `job_id`, `segment_id`, and `asset_url`.";
+        }
         const out = await runEngine(["--swap", String(args.cut), args.asset]);
         const m = out.match(/RESULT:(.+)/);
         if (!m)
@@ -87,10 +168,21 @@ exports.swapCaptionStyleTool = {
                     "minimalist = lowercase thin font fade-in (calm, educational). " +
                     "whiteboard = text revealed left-to-right (explainers, tutorials).",
             },
+            job_id: { type: "string", description: "HOSTED: the Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID or the local project." },
         },
         required: ["caption_style"],
     },
     async execute(args) {
+        // Hosted projects set caption style via the editor's render options; there's
+        // no standalone caption-swap endpoint to drive from here yet. Be explicit
+        // rather than hit a guessed route.
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (jobId) {
+            return (`Caption style isn't swappable from here for hosted Swap & Refine projects yet — ` +
+                `set it in the editor: ${(0, hosted_js_1.editorUrl)(jobId)} (this is the next slice to wire up).`);
+        }
+        if (!(0, engine_js_1.engineAvailable)())
+            return NO_LOCAL_ENGINE;
         const out = await runEngine(["--caption-style", args.caption_style, "--swap-caption-style"]);
         const m = out.match(/RESULT:(.+)/);
         if (!m)

package/dist/tools/carousel-video.js

@@ -71,6 +71,12 @@ exports.publishCarouselAsVideoTool = {
                 items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
                 description: "Platforms to publish to. Must be connected. For mode='draft', Instagram is not allowed (no IG drafts API).",
             },
+            account_ids: {
+                type: "array",
+                items: { type: "string" },
+                description: "Specific connection IDs (from list_connections) to target. REQUIRED when you have multiple accounts on a platform — " +
+                    "without it the post fans out to EVERY connected account on the platform (e.g. a draft landing on the wrong handle).",
+            },
             caption: { type: "string", description: "Post caption." },
             hashtags: {
                 type: "array",
@@ -158,6 +164,7 @@ exports.publishCarouselAsVideoTool = {
                 media_urls: upload.urls,
                 media_type: "video",
                 platforms: args.platforms,
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
                 caption: args.caption,
                 hashtags: args.hashtags ?? [],
                 publish_now: true,

package/dist/tools/color-grade.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorGradeTool = void 0;
+/**
+ * color_grade — free, instant cinematic LUT looks (ffmpeg, no AI, no cost). The
+ * cheap counterpart to relight_clip: it regrades color/contrast but can't change
+ * the background or add 3D relighting. Great for the A-roll or any clip.
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+const LOOKS = ["teal-orange", "noir", "warm-golden", "cool-cinematic", "vintage", "vibrant", "moody-blue"];
+function runGrade(args) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(engine_js_1.ENGINE_DIR, "grade.mjs"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let out = "";
+        child.stdout.on("data", (d) => { out += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const m = out.match(/RESULT:([\s\S]+)/);
+            if (code === 0 && m)
+                resolve(m[1].trim());
+            else
+                reject(new Error(out.slice(-300) || `grade exited ${code}`));
+        });
+    });
+}
+exports.colorGradeTool = {
+    name: "color_grade",
+    description: "Apply a FREE, instant cinematic color grade / LUT look to a LOCAL video (no AI, no cost) — teal-orange, " +
+        "noir, warm-golden, cool-cinematic, vintage, vibrant, or moody-blue. Great for the A-roll or any clip; it's " +
+        "a toggle-able look (keep the original or the graded file). For true relighting / background change, that's " +
+        "the paid relight_clip instead. Omit `look` to list the available looks.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to the video to grade." },
+            look: { type: "string", enum: LOOKS, description: "The look to apply. Omit to list all looks." },
+        },
+        required: ["video_path"],
+    },
+    async execute(args) {
+        if (!(0, engine_js_1.engineAvailable)("grade.mjs")) {
+            return "color_grade needs the local engine (ffmpeg). It's unavailable in this install.";
+        }
+        if (!args.look) {
+            const r = JSON.parse(await runGrade(["--list"]));
+            const lines = r.looks.map((l) => `  • ${l.key} — ${l.label}`);
+            return ["Free cinematic looks (no cost):", ...lines, "", `Apply one: color_grade(video_path: "${args.video_path}", look: "teal-orange").`].join("\n");
+        }
+        let r;
+        try {
+            r = JSON.parse(await runGrade([args.video_path, args.look]));
+        }
+        catch (e) {
+            return `Couldn't grade the video: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        return `Applied the "${r.look}" grade → ${r.out}\nFree + instant (ffmpeg). Swap it in, or try another look.`;
+    },
+};