@viralspin/mcp 0.1.0 → 0.2.2

package/dist/tools/engage.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteKeywordLinkTool = exports.listKeywordLinksTool = exports.setKeywordLinkTool = void 0;
+const client_js_1 = require("../client.js");
+function describe(k) {
+    const scope = k.media_id ? `post ${k.media_id}` : "all posts";
+    const platform = k.platform ?? "any platform";
+    const reply = k.reply_to_comment
+        ? (k.comment_reply_text ? `, replies "${k.comment_reply_text}"` : ", + comment reply")
+        : ", DM only";
+    const status = k.is_active ? "" : " (paused)";
+    return `"${k.keyword}" → ${k.link}  [${platform}, ${scope}, ${k.match_type}${reply}]${status}`;
+}
+exports.setKeywordLinkTool = {
+    name: "set_keyword_link",
+    description: "Map a keyword to a resource/destination link for DM automation. When a follower comments/DMs the keyword, " +
+        "the link is sent back (delivery activates once Instagram messaging access is approved). " +
+        "Re-running with the same keyword + scope updates the link instead of creating a duplicate. " +
+        "Omit media_id for a global rule (fires on any post); set media_id for a single post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            keyword: { type: "string", description: "The trigger word, e.g. 'guide' or 'link'. Case-insensitive." },
+            link: { type: "string", description: "The destination URL to send (e.g. a resource-hub article)." },
+            platform: {
+                type: "string",
+                enum: ["instagram", "tiktok", "youtube"],
+                description: "Platform this rule applies to. Omit for any connected platform. Only Instagram delivers today.",
+            },
+            media_id: {
+                type: "string",
+                description: "Optional. A specific post/media id to scope the rule to. Omit for a global rule across all posts.",
+            },
+            match_type: {
+                type: "string",
+                enum: ["exact", "contains", "word"],
+                description: "'word' (default, recommended) fires when the keyword appears as a whole word — 'the app.' matches, " +
+                    "'appreciate' does not. 'contains' fires on any substring, which misfires on short keywords. " +
+                    "'exact' requires the comment to be nothing but the keyword.",
+            },
+            reply_to_comment: {
+                type: "boolean",
+                description: "Also post a public reply to the comment (e.g. 'Check your DMs', wording varies). Defaults to true.",
+            },
+            comment_reply_text: {
+                type: "string",
+                description: "Custom wording for that public reply. Omit to rotate through the built-in phrases.",
+            },
+        },
+        required: ["keyword", "link"],
+    },
+    async execute(args) {
+        const created = await (0, client_js_1.post)("/v1/engage/keyword-links", {
+            keyword: args.keyword,
+            link: args.link,
+            platform: args.platform ?? null,
+            media_id: args.media_id ?? null,
+            match_type: args.match_type ?? "word",
+            reply_to_comment: args.reply_to_comment ?? true,
+            comment_reply_text: args.comment_reply_text ?? null,
+        });
+        return `Saved: ${describe(created)}`;
+    },
+};
+exports.listKeywordLinksTool = {
+    name: "list_keyword_links",
+    description: "List your keyword→link DM-automation rules.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+    async execute(_args) {
+        const rules = await (0, client_js_1.get)("/v1/engage/keyword-links");
+        if (!rules.length) {
+            return "No keyword→link rules yet. Use set_keyword_link to add one (e.g. map 'guide' to your resource link).";
+        }
+        return rules.map((r) => `• ${describe(r)}`).join("\n");
+    },
+};
+exports.deleteKeywordLinkTool = {
+    name: "delete_keyword_link",
+    description: "Delete a keyword→link rule by its keyword. If multiple rules share the keyword, all of them are removed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            keyword: { type: "string", description: "The keyword whose rule(s) should be deleted." },
+        },
+        required: ["keyword"],
+    },
+    async execute(args) {
+        const rules = await (0, client_js_1.get)("/v1/engage/keyword-links");
+        const matches = rules.filter((r) => r.keyword.toLowerCase() === args.keyword.trim().toLowerCase());
+        if (!matches.length)
+            return `No rule found for keyword "${args.keyword}".`;
+        for (const m of matches) {
+            await (0, client_js_1.del)(`/v1/engage/keyword-links/${m.id}`);
+        }
+        return `Deleted ${matches.length} rule(s) for "${args.keyword}".`;
+    },
+};

package/dist/tools/explainer-index.js

@@ -0,0 +1,307 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexExplainerSourcesTool = void 0;
+exports.searchAndExtract = searchAndExtract;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const TL_BASE = "https://api.twelvelabs.io/v1.3";
+const VIRALSPIN_HOME = node_path_1.default.join(node_os_1.default.homedir(), ".viralspin");
+const CACHE_FILE = node_path_1.default.join(VIRALSPIN_HOME, "explainer_cache.json");
+function readCache() {
+    try {
+        if (node_fs_1.default.existsSync(CACHE_FILE))
+            return JSON.parse(node_fs_1.default.readFileSync(CACHE_FILE, "utf8"));
+    }
+    catch { /* ignore */ }
+    return { indexes: {}, videos: {} };
+}
+function writeCache(c) {
+    node_fs_1.default.mkdirSync(VIRALSPIN_HOME, { recursive: true });
+    node_fs_1.default.writeFileSync(CACHE_FILE, JSON.stringify(c, null, 2));
+}
+function cacheKey(filePath) {
+    try {
+        const stat = node_fs_1.default.statSync(filePath);
+        return `${filePath}|${stat.size}`;
+    }
+    catch {
+        return filePath;
+    }
+}
+// ── Twelve Labs REST helpers ───────────────────────────────────────────────
+function tlFetch(method, urlPath, body, apiKey) {
+    return new Promise((resolve, reject) => {
+        const key = apiKey || process.env.TWELVE_LABS_API_KEY || "";
+        const bodyBuf = body ? Buffer.from(JSON.stringify(body)) : undefined;
+        const req = node_https_1.default.request(`${TL_BASE}${urlPath}`, {
+            method,
+            headers: {
+                "x-api-key": key,
+                "Content-Type": "application/json",
+                ...(bodyBuf ? { "Content-Length": bodyBuf.length } : {}),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                const text = Buffer.concat(chunks).toString();
+                try {
+                    resolve(JSON.parse(text));
+                }
+                catch {
+                    reject(new Error(`TL parse error: ${text.slice(0, 200)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        if (bodyBuf)
+            req.write(bodyBuf);
+        req.end();
+    });
+}
+async function tlUploadFile(filePath, indexId, apiKey) {
+    // Multipart upload using form-data
+    const { default: FormData } = await Promise.resolve(`${"form-data"}`).then(s => __importStar(require(s)));
+    const form = new FormData();
+    form.append("index_id", indexId);
+    form.append("language", "en");
+    form.append("video_file", node_fs_1.default.createReadStream(filePath), { filename: node_path_1.default.basename(filePath) });
+    return new Promise((resolve, reject) => {
+        const headers = { ...form.getHeaders(), "x-api-key": apiKey };
+        const req = node_https_1.default.request(`${TL_BASE}/tasks`, { method: "POST", headers }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                try {
+                    const d = JSON.parse(Buffer.concat(chunks).toString());
+                    resolve(d._id || d.id);
+                }
+                catch (e) {
+                    reject(new Error(`TL upload parse error: ${Buffer.concat(chunks).toString().slice(0, 200)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        form.pipe(req);
+    });
+}
+async function waitForTask(taskId, apiKey) {
+    const deadline = Date.now() + 30 * 60 * 1000; // 30-min max
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 8000));
+        const d = await tlFetch("GET", `/tasks/${taskId}`, undefined, apiKey);
+        if (d.status === "ready")
+            return d.video_id;
+        if (d.status === "failed")
+            throw new Error(`Twelve Labs indexing failed for task ${taskId}: ${d.error || ""}`);
+    }
+    throw new Error(`Twelve Labs indexing timed out for task ${taskId}`);
+}
+async function getOrCreateIndex(folderPath, indexName, apiKey) {
+    const cache = readCache();
+    if (cache.indexes[folderPath])
+        return cache.indexes[folderPath];
+    // Create a new index
+    const d = await tlFetch("POST", "/indexes", {
+        name: indexName,
+        engines: [{ name: "marengo2.6", options: ["visual", "conversation", "text_in_video"] }],
+    }, apiKey);
+    const indexId = d._id || d.id;
+    cache.indexes[folderPath] = indexId;
+    writeCache(cache);
+    return indexId;
+}
+// ── Folder walking ─────────────────────────────────────────────────────────
+const VIDEO_EXTS = new Set([".mp4", ".mkv", ".mov", ".avi", ".wmv", ".webm"]);
+function walkFolder(folder) {
+    const results = [];
+    try {
+        for (const entry of node_fs_1.default.readdirSync(folder, { withFileTypes: true })) {
+            const full = node_path_1.default.join(folder, entry.name);
+            if (entry.isDirectory())
+                results.push(...walkFolder(full));
+            else if (VIDEO_EXTS.has(node_path_1.default.extname(entry.name).toLowerCase()))
+                results.push(full);
+        }
+    }
+    catch { /* ignore permission errors */ }
+    return results;
+}
+exports.indexExplainerSourcesTool = {
+    name: "index_explainer_sources",
+    description: "Index a local folder of screen recordings and OBS videos with Twelve Labs so they can be searched semantically " +
+        "inside create_video_assembly. Call this once per folder — indexing is cached, so re-running skips already-indexed files. " +
+        "Returns an index_id to pass as explainer_index_id in create_video_assembly. " +
+        "Requires TWELVE_LABS_API_KEY in the MCP environment.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sources_folder: {
+                type: "string",
+                description: "Local folder containing your screen recordings / OBS videos (e.g. C:/obs-recordings).",
+            },
+            index_name: {
+                type: "string",
+                description: "Optional name for the Twelve Labs index (defaults to the folder's base name).",
+            },
+        },
+        required: ["sources_folder"],
+    },
+    async execute(args) {
+        // Credit gate: Twelve Labs indexing makes paid API calls that are not yet
+        // metered to a user's credit balance, so it is OFF by default for public
+        // MCP deployments. Internal/power users can enable it explicitly.
+        if (process.env.EXPLAINER_INDEX_ENABLED !== "true") {
+            return "Twelve Labs explainer indexing is disabled. This feature calls a paid API that is not yet billed to credits, so it is off by default. To enable it for internal use, set EXPLAINER_INDEX_ENABLED=true in the MCP environment.";
+        }
+        const apiKey = process.env.TWELVE_LABS_API_KEY;
+        if (!apiKey) {
+            return "Error: TWELVE_LABS_API_KEY is not set in the MCP environment. Add it to your ~/.claude.json MCP config under env.TWELVE_LABS_API_KEY.";
+        }
+        const folder = args.sources_folder;
+        if (!node_fs_1.default.existsSync(folder)) {
+            return `Error: folder not found: ${folder}`;
+        }
+        const indexName = args.index_name || node_path_1.default.basename(folder) || "viralspin-explainer";
+        process.stderr.write(`[explainer-index] Getting/creating Twelve Labs index for ${folder}…\n`);
+        const indexId = await getOrCreateIndex(folder, indexName, apiKey);
+        process.stderr.write(`[explainer-index] index_id=${indexId}\n`);
+        const videos = walkFolder(folder);
+        if (videos.length === 0) {
+            return `No video files found in ${folder}. Supported formats: ${[...VIDEO_EXTS].join(", ")}`;
+        }
+        const cache = readCache();
+        let indexed = 0;
+        let skipped = 0;
+        const errors = [];
+        for (const vpath of videos) {
+            const key = cacheKey(vpath);
+            if (cache.videos[key]) {
+                skipped++;
+                process.stderr.write(`[explainer-index] skip (cached): ${node_path_1.default.basename(vpath)}\n`);
+                continue;
+            }
+            process.stderr.write(`[explainer-index] uploading: ${node_path_1.default.basename(vpath)}…\n`);
+            try {
+                const taskId = await tlUploadFile(vpath, indexId, apiKey);
+                process.stderr.write(`[explainer-index] waiting for task ${taskId}…\n`);
+                const videoId = await waitForTask(taskId, apiKey);
+                cache.videos[key] = { video_id: videoId, index_id: indexId };
+                writeCache(cache);
+                indexed++;
+                process.stderr.write(`[explainer-index] indexed: ${node_path_1.default.basename(vpath)} → video_id=${videoId}\n`);
+            }
+            catch (e) {
+                errors.push(`${node_path_1.default.basename(vpath)}: ${e?.message || e}`);
+                process.stderr.write(`[explainer-index] ERROR: ${e?.message || e}\n`);
+            }
+        }
+        const parts = [
+            `Index ready: ${indexId}`,
+            `  Newly indexed: ${indexed} video${indexed !== 1 ? "s" : ""}`,
+            `  Already cached: ${skipped}`,
+            `  Total in folder: ${videos.length}`,
+            "",
+            `Pass this to create_video_assembly as:  explainer_index_id: "${indexId}"`,
+        ];
+        if (errors.length) {
+            parts.push("", `Errors (${errors.length}):`, ...errors.map((e) => `  • ${e}`));
+        }
+        return parts.join("\n");
+    },
+};
+// ── Clip retrieval (used by assemble.mjs via env forwarding) ───────────────
+// Exported so assemble.mjs can also call this logic if needed in future.
+async function searchAndExtract(searchQuery, indexId, outDir, clipIndex) {
+    const apiKey = process.env.TWELVE_LABS_API_KEY;
+    if (!apiKey)
+        return null;
+    try {
+        const result = await tlFetch("POST", "/search", {
+            query_text: searchQuery,
+            index_id: indexId,
+            search_options: ["visual", "conversation", "text_in_video"],
+            page_limit: 1,
+        }, apiKey);
+        const hit = result?.data?.[0];
+        if (!hit)
+            return null;
+        const videoId = hit.video_id;
+        const startSec = hit.start || 0;
+        const endSec = hit.end || startSec + 15;
+        const confidence = hit.score || 0;
+        // Look up local path from cache
+        const cache = readCache();
+        let localPath = null;
+        for (const entry of Object.values(cache.videos)) {
+            if (entry.video_id === videoId && entry.index_id === indexId) {
+                // Find the key (which is "filePath|size")
+                for (const [key, val] of Object.entries(cache.videos)) {
+                    if (val.video_id === videoId) {
+                        localPath = key.split("|")[0];
+                        break;
+                    }
+                }
+                break;
+            }
+        }
+        if (!localPath || !node_fs_1.default.existsSync(localPath))
+            return null;
+        const outPath = node_path_1.default.join(outDir, `explainer_clip_${clipIndex}.mp4`);
+        const duration = Math.min(endSec - startSec, 30);
+        const { spawn } = await Promise.resolve().then(() => __importStar(require("child_process")));
+        await new Promise((resolve, reject) => {
+            const ff = spawn("ffmpeg", [
+                "-y", "-ss", String(startSec), "-t", String(duration),
+                "-i", localPath,
+                "-c:v", "libx264", "-crf", "26", "-c:a", "aac", "-movflags", "+faststart",
+                outPath,
+            ]);
+            ff.on("close", (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg exit ${code}`)));
+            ff.on("error", reject);
+        });
+        return { clip_path: outPath, confidence, start_sec: startSec };
+    }
+    catch (e) {
+        process.stderr.write(`[explainer-index] searchAndExtract error: ${e?.message || e}\n`);
+        return null;
+    }
+}

package/dist/tools/find-moments.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findMomentsTool = void 0;
+/**
+ * find_moments — surface highlight windows inside a long/silent local video so
+ * the agent can build a reel without the user pre-splitting it. Shells out to the
+ * engine's moments.mjs (ffmpeg frame sampling + vision scoring via the configured
+ * model — local Ollama when VIRALSPIN_VLM is set, else cloud Gemini).
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+function runMoments(args, script = "moments.mjs") {
+    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, script), ...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(-400) || `moments engine exited ${code}`));
+        });
+    });
+}
+exports.findMomentsTool = {
+    name: "find_moments",
+    description: "Find the highlight-worthy moments INSIDE a long or silent LOCAL video (e.g. a screen recording or B-roll " +
+        "reel) — no need to split it first. Samples frames and scores them with the configured vision model " +
+        "(free + private local Ollama when local mode is on, else cloud), and returns 0.6–3s windows with " +
+        "descriptions. Pass `query` to bias toward a theme. Set `extract: true` to ALSO cut each highlight into " +
+        "its own small clip LOCALLY — then you upload only those snippets (not the long source). Build a reel from " +
+        "them with create_video_assembly: destination:'hosted' uploads ONLY the snippets + opens the web editor; " +
+        "destination:'local' keeps everything on-device (no upload). Same analysis, two destinations.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to the long video to scan." },
+            query: { type: "string", description: "Optional theme to bias toward (e.g. 'surprise reveal', 'on-screen editing')." },
+            threshold: { type: "number", description: "Score cutoff 0..1 for a 'highlight' (default 0.55; lower = more windows)." },
+            extract: { type: "boolean", description: "Also cut each highlight into its own small clip locally (so you upload only the snippets). Default false = just list the windows." },
+            mode: { type: "string", enum: ["highlight", "screen"], description: "'highlight' (default) = VLM-scored striking moments for any footage. 'screen' = SCREEN-RECORDING mode: frame-diff finds where the on-screen ACTION is and returns a focal point (x,y) + suggested punch-in zoom per snippet, so the reel can auto-zoom to exactly where things happen (cursor, typing, output). Use for app/product demos." },
+        },
+        required: ["video_path"],
+    },
+    async execute(args) {
+        if (args.mode === "screen")
+            return runScreenMode(args);
+        if (!(0, engine_js_1.engineAvailable)("moments.mjs")) {
+            return "find_moments needs the local engine (it runs ffmpeg + the vision model). It's unavailable in this install — set VIRALSPIN_ASSEMBLY_DIR, or use the hosted transcript path (get_transcript + keep_windows) for talking/narrated video instead.";
+        }
+        const cli = [args.video_path];
+        if (args.query)
+            cli.push("--query", args.query);
+        if (args.threshold != null)
+            cli.push("--threshold", String(args.threshold));
+        if (args.extract)
+            cli.push("--extract");
+        let json;
+        try {
+            json = JSON.parse(await runMoments(cli));
+        }
+        catch (e) {
+            return `Couldn't scan the video: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        if (!json.windows?.length) {
+            return `Scanned ${json.sampled} frames over ${Math.round(json.duration)}s but found no standout moments — lower the threshold or add a query.`;
+        }
+        const head = `Found ${json.windows.length} highlight window(s) in ${path_1.default.basename(args.video_path)} (${Math.round(json.duration)}s, ${json.sampled} frames sampled, analyzed locally if local mode is on):`;
+        if (json.clips?.length) {
+            const lines = json.clips.map((c, i) => `${i + 1}. ${c.path}  (${c.from_sec.toFixed(1)}–${c.to_sec.toFixed(1)}s)${c.desc ? ` — ${c.desc}` : ""}`);
+            return [
+                head,
+                `Extracted ${json.clips.length} clip(s) → ${json.out_dir}`,
+                ...lines,
+                ``,
+                `Build a reel from these snippets with create_video_assembly:`,
+                `  • destination:"hosted" → uploads ONLY these snippets (not the long source) + opens the web editor.`,
+                `  • destination:"local"  → keeps everything on-device, no upload (fully private).`,
+            ].join("\n");
+        }
+        const lines = json.windows.map((w, i) => `${i + 1}. ${w.from_sec.toFixed(1)}–${w.to_sec.toFixed(1)}s (score ${w.score})${w.desc ? ` — ${w.desc}` : ""}`);
+        return [
+            head,
+            ...lines,
+            ``,
+            `Re-run with extract:true to cut these into clips (then upload only those), or run keep_windows on a hosted project to cut to just these moments.`,
+        ].join("\n");
+    },
+};
+// SCREEN mode — shells to screen-moments.mjs (frame-diff focal + zoom, VLM label).
+// Returns snippets that carry focal_x/focal_y + zoom so the assembly can punch-in to
+// exactly where the on-screen action is. Each screen recording is a B-roll SOURCE;
+// call once per recording and let the story arc stitch the snippets together.
+async function runScreenMode(args) {
+    if (!(0, engine_js_1.engineAvailable)("screen-moments.mjs")) {
+        return "Screen mode needs the local engine (ffmpeg + Python opencv). It's unavailable in this install — set VIRALSPIN_ASSEMBLY_DIR and `pip install opencv-python numpy`.";
+    }
+    const cli = [args.video_path];
+    if (args.threshold != null)
+        cli.push("--threshold", String(args.threshold));
+    if (args.extract)
+        cli.push("--extract");
+    let json;
+    try {
+        json = JSON.parse(await runMoments(cli, "screen-moments.mjs"));
+    }
+    catch (e) {
+        return `Couldn't scan the screen recording: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    if (!json.snippets?.length) {
+        return `Scanned ${json.sampled} frames over ${Math.round(json.duration)}s of ${path_1.default.basename(args.video_path)} but found no clear on-screen action — the recording may be mostly static.`;
+    }
+    const head = `Found ${json.snippets.length} on-screen action moment(s) in ${path_1.default.basename(args.video_path)} (${json.width}×${json.height}, ${Math.round(json.duration)}s). Each carries a focal point + punch-in zoom so the reel can zoom to exactly where the action is:`;
+    const fmt = (s, i) => `${i + 1}. ${s.from_sec.toFixed(1)}–${s.to_sec.toFixed(1)}s — focal (${s.focal_x.toFixed(2)}, ${s.focal_y.toFixed(2)}), zoom ${s.zoom}×${s.label ? ` — “${s.label}”` : ""}`;
+    if (json.clips?.length) {
+        return [
+            head,
+            ...json.snippets.map(fmt),
+            ``,
+            `Extracted ${json.clips.length} snippet clip(s) → ${json.out_dir}`,
+            `These are B-roll candidates: build a screen-demo reel with create_video_assembly (they stitch together with other B-roll; the focal+zoom drive the auto punch-in).`,
+        ].join("\n");
+    }
+    return [
+        head,
+        ...json.snippets.map(fmt),
+        ``,
+        `Re-run with extract:true to cut these into snippet clips, then assemble a screen-demo reel from them (each snippet's focal+zoom drives the punch-in).`,
+    ].join("\n");
+}

package/dist/tools/folder-preview.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewFolderTool = void 0;
+/**
+ * preview_folder — a pre-flight cost gate for assembling a local folder.
+ *
+ * create_video_assembly analyzes every clip (Gemini tags) and charges credits on
+ * create. For a big folder that adds up, so the agent should call this FIRST and
+ * confirm with the user before assembling. Counting is local (reads the disk),
+ * so it's instant and free; the exact credit charge is finalized server-side in
+ * the create response. An optional per-asset rate (env) gives a rough estimate.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+const VIDEO_EXT = new Set([".mp4", ".mov", ".webm", ".m4v"]);
+exports.previewFolderTool = {
+    name: "preview_folder",
+    description: "Before assembling from a LOCAL folder, count its media so you can warn the user about cost. Each clip is " +
+        "analyzed (tagged for matching) and credits are charged when create_video_assembly runs — so for a big " +
+        "folder, call this first and CONFIRM before proceeding. Counting is instant + free; the exact charge is " +
+        "finalized in the create response. Returns video/image counts (+ a rough credit estimate if a per-asset " +
+        "rate is configured via VIRALSPIN_ANALYZE_CREDITS_PER_ASSET).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            folder: { type: "string", description: "Local folder path to inspect." },
+        },
+        required: ["folder"],
+    },
+    async execute(args) {
+        const folder = args.folder;
+        if (!fs_1.default.existsSync(folder))
+            return `Folder not found: ${folder}`;
+        let names;
+        try {
+            const st = fs_1.default.statSync(folder);
+            if (!st.isDirectory())
+                return `${folder} is a file, not a folder.`;
+            names = fs_1.default.readdirSync(folder);
+        }
+        catch (e) {
+            return `Can't read folder: ${e instanceof Error ? e.message : e}`;
+        }
+        let images = 0;
+        let videos = 0;
+        for (const n of names) {
+            const ext = path_1.default.extname(n).toLowerCase();
+            if (VIDEO_EXT.has(ext))
+                videos++;
+            else if (IMAGE_EXT.has(ext))
+                images++;
+        }
+        const total = images + videos;
+        if (!total)
+            return `No images or videos found in ${folder}.`;
+        const rate = Number(process.env.VIRALSPIN_ANALYZE_CREDITS_PER_ASSET || "");
+        const est = Number.isFinite(rate) && rate > 0 ? ` Rough estimate: ~${Math.round(total * rate)} credits (${rate}/clip).` : "";
+        const warnAt = Number(process.env.VIRALSPIN_FOLDER_WARN || "40");
+        const big = total > warnAt;
+        return (`${folder}\n` +
+            `${total} media file(s): ${videos} video(s), ${images} image(s).\n` +
+            `Each is analyzed when you assemble; credits are charged on create_video_assembly and finalized in its response.${est}\n` +
+            (big
+                ? `⚠️ Large folder — CONFIRM with the user before assembling (it will cost credits). Consider a sub-folder or only the best clips.`
+                : `Small enough to assemble directly.`));
+    },
+};