videobook 0.0.0-stage → 0.1.0

package/dist/tools/verify-x-mentions.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { toolError } from "./_shared.js";
+import { INTELLIGENCE_MODEL, buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+export const MENTION_VERIFICATION_MODEL = INTELLIGENCE_MODEL;
+const XAI_TIMEOUT_MS = 60_000;
+const MAX_MENTIONS = 10;
+const MAX_TEXT_CHARS = 1_000;
+/** Extract unique X handles from post text. X usernames are 1-15 chars of
+ *  [A-Za-z0-9_]; tokens followed by a hyphen (asset slugs like @vid-clip) and
+ *  email-style @s preceded by a word character are excluded. */
+export function extractXMentions(text) {
+    const handles = [];
+    const seen = new Set();
+    for (const match of text.matchAll(/(^|[^\w@])@([A-Za-z0-9_]{1,15})(?![\w-])/g)) {
+        const handle = match[2];
+        const key = handle.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        handles.push(handle);
+    }
+    return handles;
+}
+const VERDICTS_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        mentions: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    handle: { type: "string" },
+                    exists: { type: ["boolean", "null"] },
+                    display_name: { type: ["string", "null"] },
+                    summary: { type: ["string", "null"] },
+                },
+                required: ["handle", "exists", "display_name", "summary"],
+            },
+        },
+    },
+    required: ["mentions"],
+};
+const VERIFY_INSTRUCTIONS = [
+    "You verify X (Twitter) handles using web search.",
+    "For each handle, determine whether an account with EXACTLY that username exists on X.",
+    "Usernames are case-insensitive; ignore lookalike or similar usernames.",
+    "Set exists=true only when you confirm the exact username.",
+    "Set exists=false only when search results positively indicate the username is nonexistent, unclaimed, or suspended.",
+    "When you can neither confirm nor refute the exact profile (for example a small account you cannot load), set exists=null.",
+    "display_name is the account's current display name and summary is one short sentence about the account from its bio or posts; use null for either when unknown.",
+    "Never guess.",
+].join(" ");
+function responseText(response) {
+    const citations = [];
+    for (const item of response.output) {
+        if (item.type !== "message")
+            continue;
+        for (const content of item.content) {
+            if (content.type !== "output_text")
+                continue;
+            for (const annotation of content.annotations ?? []) {
+                if (annotation.type === "url_citation" && annotation.url && !citations.includes(annotation.url)) {
+                    citations.push(annotation.url);
+                }
+            }
+        }
+    }
+    return { text: firstResponseText(response), citations };
+}
+export async function verifyXMentionsWithOpenAi(responses, handles, signal) {
+    const response = await responses(intelligenceRequest({
+        input: [
+            { role: "user", content: `Verify these X handles: ${handles.map((handle) => `@${handle}`).join(", ")}` },
+        ],
+        instructions: VERIFY_INSTRUCTIONS,
+        tools: [{ type: "web_search_preview" }],
+        text: {
+            format: {
+                type: "json_schema",
+                name: "x_mention_verdicts",
+                schema: VERDICTS_JSON_SCHEMA,
+                strict: true,
+            },
+        },
+    }), signal);
+    const { text, citations } = responseText(response);
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed.mentions)) {
+        throw new Error("OpenAI verification response is missing the mentions array");
+    }
+    const byHandle = new Map(parsed.mentions.map((verdict) => [verdict.handle.replace(/^@/, "").toLowerCase(), verdict]));
+    const mentions = handles.map((handle) => {
+        const verdict = byHandle.get(handle.toLowerCase());
+        return {
+            handle,
+            exists: verdict?.exists ?? null,
+            display_name: verdict?.display_name ?? null,
+            summary: verdict?.summary ?? null,
+        };
+    });
+    return { mentions, citations, model: response.model };
+}
+export function verifyXMentionsDef() {
+    return {
+        name: "verify_x_mentions",
+        description: "Verify that @-mentions in post text are real X (Twitter) accounts using OpenAI web search. Returns per-handle verdicts (exists true/false/null) with display names and one-line summaries.",
+        schema: {
+            text: z.string().min(1).max(MAX_TEXT_CHARS).describe("Post text containing @handles to verify"),
+            book_id: z.string().describe("Book id"),
+        },
+        handler: async (args) => {
+            const { text } = args;
+            if (!process.env.OPENAI_API_KEY) {
+                return toolError("OPENAI_API_KEY environment variable is not set");
+            }
+            const handles = extractXMentions(text).slice(0, MAX_MENTIONS);
+            if (handles.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ mentions: [], citations: [], model: MENTION_VERIFICATION_MODEL }),
+                        }],
+                };
+            }
+            const responses = buildIntelligenceResponses(process.env.OPENAI_API_KEY, {
+                timeout: XAI_TIMEOUT_MS,
+            });
+            try {
+                const verification = await verifyXMentionsWithOpenAi(responses, handles);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(verification) }],
+                };
+            }
+            catch (error) {
+                return toolError(`Mention verification failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    };
+}

package/dist/tools/video-editing-command-contract.js

@@ -0,0 +1,291 @@
+export const COMMAND_ADAPTER_NAMES = [
+    "apply_cuts",
+    "apply_sfx",
+    "change_speed",
+    "duplicate",
+    "keywords",
+    "qr_outro",
+    "qrbtf",
+    "rewrite_script",
+    "sync_audio",
+    "timewarp",
+    "translate_subtitles",
+    "trim",
+];
+export const VIDEO_EDITING_COMMANDS = [
+    {
+        command: "/trim-video",
+        description: "Trim video clip",
+        example: "/trim-video @hero-intro 0:05 0:12",
+        category: "action",
+        icon: "Scissors",
+        size: "lg",
+        variant: "default",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Asset to trim" },
+            { name: "start", type: "string", required: false, description: "Start timestamp" },
+            { name: "end", type: "string", required: false, description: "End timestamp" },
+        ],
+        mcpTool: { tool: "trim_video", adapter: "trim", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: ["/trim"],
+    },
+    {
+        command: "/trim-audio",
+        description: "Trim audio clip",
+        example: "/trim-audio @aud-voiceover-main 0:00 0:30",
+        category: "action",
+        icon: "Scissors",
+        size: "default",
+        variant: "emerald",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Audio asset to trim (aud-*)" },
+            { name: "start", type: "string", required: false, description: "Start timestamp" },
+            { name: "end", type: "string", required: false, description: "End timestamp" },
+        ],
+        mcpTool: { tool: "trim_audio", adapter: "trim", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: [],
+    },
+    {
+        command: "/split-chunks",
+        description: "Split a video into targeted chunks plus a leftover while preserving the source",
+        example: "/split-chunks @vid-source 10 15",
+        category: "context_menu",
+        icon: "Scissors",
+        size: "default",
+        variant: "violet",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Video asset to split" },
+            { name: "target_secs", type: "string[]", required: false, description: "Ordered chunk lengths (default 7 seconds)" },
+        ],
+        mcpTool: { tool: "split_video_by_durations", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: ["/even-split"],
+    },
+    {
+        command: "/overlay",
+        description: "Place an on-screen graphic overlay on a video",
+        example: "/overlay @vid-yt-clip @img-logo",
+        category: "context_menu",
+        icon: "Tv",
+        size: "default",
+        variant: "default",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Video asset to overlay" },
+            { name: "image", type: "string", required: false, description: "Image asset to use as the overlay" },
+        ],
+        uiAction: "open_osg",
+        exposure: "ui",
+        aliases: ["/osg"],
+    },
+    {
+        command: "/apply-cuts",
+        description: "Apply trim cuts to a video clip in place",
+        example: "/apply-cuts @vid-clip 0-5 10-15",
+        category: "action",
+        icon: "Scissors",
+        size: "default",
+        variant: "violet",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Video asset ID" },
+            { name: "cuts", type: "string[]", required: true, description: "Cut ranges, e.g. 0-5 10-15" },
+        ],
+        mcpTool: { tool: "apply_cuts", adapter: "apply_cuts", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: [],
+    },
+    {
+        command: "/extract-frame",
+        description: "Extract a frame at a specific timestamp from a video as an image asset",
+        example: "/extract-frame @vid-clip 2.5",
+        category: "context_menu",
+        icon: "Image",
+        size: "default",
+        variant: "default",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Video asset to extract from" },
+            { name: "timestamp", type: "number", required: true, description: "Timestamp in seconds" },
+        ],
+        mcpTool: { tool: "extract_frame", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: [],
+    },
+    {
+        command: "/transcript",
+        description: "Read transcript of a video or audio asset",
+        example: "/transcript @vid-interview",
+        category: "action",
+        icon: "FileText",
+        size: "default",
+        variant: "violet",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Asset ID to read transcript for" },
+        ],
+        mcpTool: { tool: "read_transcript", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: [],
+    },
+    {
+        command: "/translate-subs",
+        description: "Translate video subtitles to a target language",
+        example: "/translate-subs @vid-clip es",
+        category: "action",
+        icon: "Languages",
+        size: "default",
+        variant: "violet",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Video asset ID" },
+            { name: "target_language", type: "string", required: true, description: "Two-letter target language code" },
+        ],
+        mcpTool: { tool: "translate_subtitles", adapter: "translate_subtitles", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: [],
+    },
+    {
+        command: "/final",
+        description: "Finalize and export the project timeline",
+        example: "/final portrait",
+        category: "action",
+        icon: "Clapperboard",
+        size: "default",
+        variant: "default",
+        chevron: "right",
+        params: [
+            { name: "orientation", type: "string", required: false, description: "landscape, portrait, or square (default: active tab)" },
+        ],
+        mcpTool: { tool: "render_timeline", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: [],
+    },
+    {
+        command: "/render-video",
+        description: "Render a video asset",
+        example: "/render-video @hero-intro portrait",
+        category: "action",
+        icon: "Film",
+        size: "lg",
+        variant: "violet",
+        chevron: "right",
+        params: [
+            { name: "asset_id", type: "string", required: true, description: "Video asset to render" },
+            { name: "orientation", type: "string", required: false, description: "landscape, portrait, or square (default: all)" },
+        ],
+        mcpTool: { tool: "render_video", autoInject: ["book_id"] },
+        exposure: "direct",
+        aliases: ["/render"],
+    },
+    {
+        command: "/audio-settings",
+        description: "Audio viewer settings for volume and fades",
+        example: "/audio-settings volume 80",
+        category: "viewer",
+        icon: "volume-2",
+        size: "sm",
+        variant: "default",
+        chevron: "right",
+        params: [
+            { name: "field", type: "string", required: true, description: "volume, fade-in, or fade-out" },
+            { name: "value", type: "string", required: false, description: "Numeric value" },
+        ],
+        uiAction: "settings_audio",
+        exposure: "ui",
+        aliases: ["/audio"],
+    },
+];
+export const VIDEO_EDITING_TOOL_CONTRACTS = [
+    { tool: "prepare_cold_open", exposure: "composite", command: "/edit-cold-open", purpose: "Select an AI highlight for review" },
+    { tool: "edit_cold_open", exposure: "composite", command: "/edit-cold-open", purpose: "Render a reviewed cold-open copy" },
+    { tool: "trim_video", exposure: "direct", command: "/trim-video", purpose: "Keep or remove a time range from video" },
+    { tool: "trim_audio", exposure: "direct", command: "/trim-audio", purpose: "Keep or remove a time range from audio" },
+    { tool: "split_video", exposure: "composite", command: "/split", purpose: "Create and run two notebook split branches" },
+    { tool: "split_video_by_durations", exposure: "direct", command: "/split-chunks", purpose: "Split video into target-duration chunks" },
+    { tool: "pad_video", exposure: "direct", command: "/pad", purpose: "Append black frames and silence" },
+    { tool: "crop_asset", exposure: "ui", command: "/crop", purpose: "Interactive image or video crop" },
+    { tool: "invert_image", exposure: "direct", command: "/invert", purpose: "Invert image colors" },
+    { tool: "set_video_overlay", exposure: "ui", command: "/overlay", purpose: "Configure an on-screen graphic" },
+    { tool: "animate_keywords", exposure: "direct", command: "/keywords", purpose: "Configure transcript-timed keyword graphics" },
+    { tool: "alive_captions", exposure: "ui", command: "/alive", purpose: "Analyze a video for stacked, frame-aware alive captions" },
+    { tool: "set_alive_captions", exposure: "ui", command: "/alive", purpose: "Save alive caption style, motion and placement" },
+    { tool: "detect_scenes", exposure: "direct", command: "/detect-scenes", purpose: "Detect visual scene boundaries" },
+    { tool: "suggest_cuts", exposure: "direct", command: "/suggest-cuts", purpose: "Suggest removable video ranges" },
+    { tool: "analyze_jokes", exposure: "direct", command: "/analyze-jokes", purpose: "Analyze edit points around jokes" },
+    { tool: "suggest_sfx", exposure: "direct", command: "/suggest-sfx", purpose: "Suggest sound-effect placements" },
+    { tool: "apply_cuts", exposure: "direct", command: "/apply-cuts", purpose: "Remove one or more video ranges" },
+    { tool: "apply_sfx", exposure: "direct", command: "/apply-sfx", purpose: "Generate and mix sound effects" },
+    { tool: "inject_first_frame", exposure: "direct", command: "/inject-first-frame", purpose: "Replace frame zero with an image" },
+    { tool: "extract_frame", exposure: "direct", command: "/extract-frame", purpose: "Extract the first, last or a timed video frame" },
+    { tool: "extract_notebook_frame", exposure: "internal", purpose: "Extract a frame from a video cell into a new image cell" },
+    { tool: "extract_notebook_audio", exposure: "internal", purpose: "Extract audio from a video cell into a new audio cell" },
+    { tool: "extract_video_clip", exposure: "internal", purpose: "Extract a notebook video clip" },
+    { tool: "extract_audio", exposure: "direct", command: "/extract-audio", purpose: "Extract a video soundtrack" },
+    { tool: "make_cover_song", exposure: "direct", command: "/make-cover-song", purpose: "Make an exact-duration instrumental cover from video or audio" },
+    { tool: "extend_audio_asset", exposure: "direct", command: "/extend-audio", purpose: "Extend an audio asset" },
+    { tool: "remove_sound", exposure: "direct", command: "/remove-sound", purpose: "Remove a described sound" },
+    { tool: "audio_boost", exposure: "direct", command: "/audio-boost", purpose: "Increase audio volume" },
+    { tool: "audio_mix", exposure: "direct", command: "/audio-mix", purpose: "Mix an audio layer into an asset" },
+    { tool: "replace_video_audio", exposure: "direct", command: "/replace-audio", purpose: "Replace a video soundtrack" },
+    { tool: "splice_video", exposure: "direct", command: "/splice", purpose: "Splice two or more videos" },
+    { tool: "smooth_scene_concat", exposure: "direct", command: "/scene-concat", purpose: "Join scenes with aligned audio" },
+    { tool: "reverse_video", exposure: "direct", command: "/reverse", purpose: "Reverse video playback" },
+    { tool: "change_video_speed", exposure: "direct", command: "/speed", purpose: "Change playback speed or duration" },
+    { tool: "timewarp_video", exposure: "direct", command: "/timewarp", purpose: "Retime a selected scene" },
+    { tool: "sync_video_to_audio", exposure: "direct", command: "/sync-audio", purpose: "Retime video to audio anchors" },
+    { tool: "transcribe", exposure: "direct", command: "/transcribe", purpose: "Transcribe an asset" },
+    { tool: "read_transcript", exposure: "direct", command: "/transcript", purpose: "Read an asset transcript" },
+    { tool: "analyze_video", exposure: "internal", purpose: "Describe a video from sampled frames and its transcript" },
+    { tool: "translate_subtitles", exposure: "direct", command: "/translate-subs", purpose: "Translate timed subtitles" },
+    { tool: "clean_video_audio", exposure: "direct", command: "/clean-audio", purpose: "Clean a video soundtrack" },
+    { tool: "isolate_vocals", exposure: "direct", command: "/vocals", purpose: "Isolate vocals" },
+    { tool: "render_video", exposure: "direct", command: "/render-video", purpose: "Render a video asset" },
+    { tool: "render_timeline", exposure: "direct", command: "/final", purpose: "Render the project timeline" },
+    { tool: "get_timeline", exposure: "internal", purpose: "Read raw timeline state" },
+    { tool: "set_timeline", exposure: "internal", purpose: "Replace raw timeline state" },
+    { tool: "assign_slot", exposure: "direct", command: "/assign", purpose: "Assign an asset to a timeline slot" },
+    { tool: "remove_timeline_slot", exposure: "direct", command: "/remove-slot", purpose: "Remove a timeline slot" },
+    { tool: "add_timeline_audio", exposure: "ui", command: "/audio-add", purpose: "Add timeline audio" },
+    { tool: "move_timeline_audio", exposure: "ui", command: "/audio-move", purpose: "Move timeline audio" },
+    { tool: "remove_timeline_audio", exposure: "ui", command: "/audio-remove", purpose: "Remove timeline audio" },
+    { tool: "update_timeline_audio", exposure: "ui", command: "/audio-set", purpose: "Update timeline audio settings" },
+    { tool: "get_render_settings", exposure: "ui", command: "/settings", purpose: "Read render settings" },
+    { tool: "create_watermark_card", exposure: "composite", command: "/watermark", purpose: "Create and apply a watermark card" },
+    { tool: "apply_watermark", exposure: "composite", command: "/watermark", purpose: "Preview and apply optional positioned QR and floating handle watermarks" },
+];
+function inferredExposure(command) {
+    if (command.exposure)
+        return command.exposure;
+    if (command.mcpTool)
+        return "direct";
+    return "ui";
+}
+export function canonicalizeCommands(commands) {
+    const names = new Set();
+    const canonicalCommands = [];
+    for (const command of commands) {
+        const aliases = command.aliases ?? [];
+        const canonical = {
+            ...command,
+            canonical: command.command,
+            aliases,
+            deprecated: false,
+            exposure: inferredExposure(command),
+        };
+        for (const name of [canonical.command, ...aliases]) {
+            if (!name.startsWith("/"))
+                throw new Error(`Invalid slash command name: ${name}`);
+            if (names.has(name))
+                throw new Error(`Duplicate slash command name or alias: ${name}`);
+            names.add(name);
+        }
+        canonicalCommands.push(canonical);
+    }
+    return canonicalCommands;
+}

package/dist/tools/video-source-reference.js

@@ -0,0 +1,30 @@
+import { normalizeNotebookReference } from "videobook-engine/notebook-mentions";
+import { resolveNotebookArtifactReference } from "../notebook-reference-resolver.js";
+function notebookCandidates(engine, notebookId) {
+    if (!notebookId)
+        return engine.notebooks.list();
+    const notebook = engine.notebooks.read(notebookId);
+    if (!notebook.ok)
+        throw new Error(notebook.error.message);
+    return [notebook.value];
+}
+export function resolveVideoAssetReference(engine, reference, notebookId) {
+    const normalized = normalizeNotebookReference(reference);
+    if (!normalized)
+        throw new Error("asset_id is required");
+    const notebooks = notebookCandidates(engine, notebookId);
+    const result = resolveNotebookArtifactReference({
+        engine,
+        documents: notebooks,
+        reference: normalized,
+    });
+    if (!("code" in result))
+        return result.artifactId;
+    if (result.code === "ambiguous") {
+        throw new Error(`Video source @${normalized} is ambiguous; include notebook_id`);
+    }
+    if (result.code === "no_output" || result.code === "not_media") {
+        throw new Error(`Video source @${normalized} has no media output yet`);
+    }
+    throw new Error(`Video source @${normalized} was not found`);
+}

package/dist/tools/video-time-input.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { parseTime } from "../time-parse.js";
+export const videoTimestampSchema = z.union([
+    z.number(),
+    z.string().min(1),
+]);
+export function parseVideoTimestamp(value, name) {
+    try {
+        const parsed = parseTime(value);
+        if (value !== undefined && parsed === undefined) {
+            throw new Error(`${name} is required`);
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error(`${name} must be seconds or a timestamp such as 15s or 1:30`);
+    }
+}