videobook 0.0.0-stage → 0.2.0

package/dist/tools/sequence-rhythm.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { rhythmSettingsSchema } from "../rhythm/model.js";
+import { readSequenceRhythm, updateSequenceRhythm } from "../rhythm/sequence-rhythm.js";
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+export function sequenceRhythmDefs(engine) {
+    const schema = { book_id: z.string().uuid(), sequence_id: z.string().uuid() };
+    return [
+        {
+            name: "get_sequence_rhythm", description: "Read the selected master soundtrack and editable beat map with its revision and undo state",
+            scope: "book", schema,
+            handler: async (args) => {
+                try {
+                    return json(await readSequenceRhythm(engine, String(args.sequence_id)));
+                }
+                catch (error) {
+                    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+                }
+            },
+        },
+        {
+            name: "update_sequence_rhythm", description: "Save or undo a soundtrack choice or corrected source-timed beat map without changing the audio",
+            scope: "book", schema: {
+                ...schema, expected_revision: z.string().min(1),
+                operation: z.enum(["set", "undo", "redo"]), settings: rhythmSettingsSchema.optional(),
+            },
+            handler: async (args) => {
+                try {
+                    const update = args.operation === "undo" || args.operation === "redo" ? args.operation : rhythmSettingsSchema.parse(args.settings);
+                    const state = await updateSequenceRhythm(engine, String(args.sequence_id), String(args.expected_revision), update);
+                    const sequence = engine.sequences.get(String(args.sequence_id));
+                    if (!sequence.ok)
+                        throw new Error(sequence.error.message);
+                    return json({ state, sequence: sequence.value });
+                }
+                catch (error) {
+                    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+                }
+            },
+        },
+    ];
+}

package/dist/tools/set-character-metadata.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { requireArtifactKind } from "./_shared.js";
+/**
+ * Normalize the metadata arg into a plain object.
+ * - Objects pass through (agents often send structured JSON, not a string).
+ * - Valid JSON object strings parse as expected.
+ * - Free-form notes (no leading `{`/`[`) are stored as `{ notes: "..." }`.
+ */
+function parseCharacterMetadata(input) {
+    if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+        return { ok: true, value: input };
+    }
+    if (typeof input !== "string") {
+        return { ok: false, error: "Metadata must be a JSON object or string" };
+    }
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return { ok: true, value: {} };
+    }
+    // Plain notes / prose — not JSON. Keep them without forcing users to quote keys.
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+        return { ok: true, value: { notes: trimmed } };
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { ok: false, error: "Metadata must be a JSON object" };
+        }
+        return { ok: true, value: parsed };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: `Invalid JSON metadata: ${message}. ` +
+                `Use double-quoted keys (e.g. {"display_name":"Ada"}) or free-form notes without braces.`,
+        };
+    }
+}
+export function setCharacterMetadataDef(engine) {
+    return {
+        name: "set_character_metadata",
+        description: "Write free-form native metadata for a character. " +
+            "Accepts a JSON object, a JSON-stringified object, or plain-text notes " +
+            "(stored as { notes: \"...\" }).",
+        schema: {
+            book_id: z.string().describe("Book id"),
+            char_asset_id: z.string().describe("Character artifact id"),
+            metadata: z
+                .union([z.string(), z.record(z.string(), z.unknown())])
+                .describe("JSON object (or stringified object) of character metadata, or free-form notes"),
+        },
+        handler: async (args) => {
+            const { book_id: _book_id, char_asset_id, metadata } = args;
+            const parsed = parseCharacterMetadata(metadata);
+            if (!parsed.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: parsed.error }],
+                };
+            }
+            const id = char_asset_id.replace(/^@/, "").trim();
+            const kindGate = await requireArtifactKind(engine, id, ["character"], "set_character_metadata");
+            if (kindGate)
+                return kindGate;
+            const writeResult = await engine.metadata.artifacts.write(id, "character", parsed.value);
+            if (!writeResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Failed to write character metadata: ${writeResult.error.message}` }],
+                };
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            asset_id: id,
+                            message: "Metadata successfully written",
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/set-env-secret.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { MANAGED_ENV_KEYS, getDefaultSecretStore, isSecretEnvKey, maskEnvValue, } from "../env-secrets.js";
+/**
+ * Writes a managed key into the repo-root .env file. Runs inline (no job
+ * queue): it is sub-millisecond local file I/O, like rename_project.
+ *
+ * This tool intentionally has no book_id argument, so withLogging never
+ * persists its args into git-versioned project activity logs — the secret
+ * value must not leak there, and success/error results never echo it either.
+ */
+export function setEnvSecretDef(store = getDefaultSecretStore()) {
+    return {
+        name: "set_env_secret",
+        description: "Write a secret into the server's .env file and live environment. Rejects keys managed by 1Password (edit those in the vault). Never returns the secret value.",
+        schema: {
+            key: z.enum(MANAGED_ENV_KEYS).describe("Environment variable name to set"),
+            value: z.string().min(1).describe("New value; stored in .env, never echoed back"),
+        },
+        handler: async (args) => {
+            const { key, value } = args;
+            try {
+                await store.setEnvSecret(key, value);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: message }],
+                };
+            }
+            const stored = store.getValue(key) ?? value;
+            const maskedKey = isSecretEnvKey(key) ? maskEnvValue(stored) : stored;
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ key, source: "env", maskedKey }) },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/set-osg.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { writeOsgSettings } from "../osg-settings.js";
+import { resolveOsgImagePath } from "../osg-assets.js";
+import { requireArtifactKind, toolError } from "./_shared.js";
+const OSG_POSITIONS = [
+    "top-left", "top-center", "top-right",
+    "middle-left", "middle-center", "middle-right",
+    "bottom-left", "bottom-center", "bottom-right",
+];
+const positionEnum = z.enum(OSG_POSITIONS);
+/**
+ * Persist OSG (on-screen graphic) overlay settings for a video asset WITHOUT
+ * triggering a render. The render path later reads these fields from the
+ * asset's `.render` metadata. We merge into every orientation's metadata so
+ * the badge + render stay consistent regardless of which orientation is
+ * rendered; `osg_positions` lets frame-aware callers store a different anchor
+ * per orientation.
+ */
+export function setVideoOverlayDef(engine) {
+    return {
+        name: "set_video_overlay",
+        description: "Set or clear the on-screen graphic overlay on a video asset. Persists to the asset's render metadata for all orientations without rendering. Pass osg_asset_id=null to clear.",
+        schema: {
+            asset_id: z.string().describe("Video asset ID (e.g. vid-my-clip)"),
+            book_id: z.string().describe("Book id"),
+            osg_asset_id: z
+                .string()
+                .nullable()
+                .describe("Image asset ID (img- prefix) for the overlay, or null to clear the OSG"),
+            osg_position: positionEnum.describe("Anchor position (default top-right)"),
+            osg_positions: z
+                .object({
+                landscape: positionEnum.optional(),
+                portrait: positionEnum.optional(),
+                square: positionEnum.optional(),
+            })
+                .optional()
+                .describe("Per-orientation anchor overrides; unlisted orientations use osg_position"),
+            osg_size: z.enum(["small", "medium", "large"]).describe("Size preset"),
+            osg_scale: z
+                .number()
+                .min(0.1)
+                .max(2)
+                .optional()
+                .describe("Size multiplier applied on top of osg_size (default 1)"),
+            osg_opacity: z
+                .number()
+                .min(0.05)
+                .max(1)
+                .optional()
+                .describe("Overlay opacity 0.05-1; the floating watermark uses 0.5 (default 1)"),
+            osg_start_seconds: z
+                .number()
+                .min(0)
+                .nullable()
+                .optional()
+                .describe("Absolute window start in seconds; null ⇒ from clip start. Omit to leave unchanged"),
+            osg_end_seconds: z
+                .number()
+                .min(0)
+                .nullable()
+                .optional()
+                .describe("Absolute window end in seconds; null ⇒ to clip end. Omit to leave unchanged"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id: _book_id, osg_asset_id, osg_position, osg_positions, osg_size, osg_scale, osg_opacity, osg_start_seconds, osg_end_seconds, } = args;
+            const clearing = osg_asset_id == null;
+            const targetGate = await requireArtifactKind(engine, asset_id, ["video"], "set_video_overlay");
+            if (targetGate)
+                return targetGate;
+            if (!clearing) {
+                const imageGate = await requireArtifactKind(engine, osg_asset_id, ["image"], "osg_asset_id");
+                if (imageGate)
+                    return imageGate;
+                const image = await resolveOsgImagePath(engine, osg_asset_id);
+                if (!image.ok)
+                    return toolError(image.error);
+            }
+            const written = await writeOsgSettings(engine, asset_id, (orientation, base) => {
+                const merged = {
+                    // osgAssetId is canonical; null out the legacy osgImagePath so a stale
+                    // path can't override a cleared/changed asset id at render time.
+                    osgImagePath: null,
+                    osgAssetId: clearing ? null : osg_asset_id,
+                    osgPosition: osg_positions?.[orientation] ?? osg_position,
+                    osgSize: osg_size,
+                    osgScale: osg_scale ?? (typeof base.osgScale === "number" ? base.osgScale : 1),
+                    osgOpacity: clearing
+                        ? 1
+                        : osg_opacity ?? (typeof base.osgOpacity === "number" ? base.osgOpacity : 1),
+                };
+                if (osg_start_seconds !== undefined) {
+                    merged.osgStartSeconds = clearing ? null : osg_start_seconds;
+                }
+                else if (clearing) {
+                    merged.osgStartSeconds = null;
+                }
+                if (osg_end_seconds !== undefined) {
+                    merged.osgEndSeconds = clearing ? null : osg_end_seconds;
+                }
+                else if (clearing) {
+                    merged.osgEndSeconds = null;
+                }
+                // An absolute window supersedes the legacy duration-relative tail.
+                const windowProvided = osg_start_seconds !== undefined || osg_end_seconds !== undefined;
+                if (clearing || windowProvided)
+                    merged.osgTailSeconds = null;
+                const resolved = { ...base, ...merged };
+                const start = typeof resolved.osgStartSeconds === "number" ? resolved.osgStartSeconds : 0;
+                if (!clearing && typeof resolved.osgEndSeconds === "number" && resolved.osgEndSeconds <= start) {
+                    throw new Error(`osg_end_seconds must be greater than osg_start_seconds for ${orientation}`);
+                }
+                return merged;
+            });
+            if (!written.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: written.error }],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            asset_id,
+                            osg: clearing
+                                ? null
+                                : {
+                                    assetId: osg_asset_id,
+                                    position: osg_position,
+                                    positions: osg_positions ?? null,
+                                    size: osg_size,
+                                    scale: written.settings.landscape.osgScale,
+                                    opacity: written.settings.landscape.osgOpacity,
+                                },
+                        }),
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/show-folder.js

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+import { z } from "zod";
+export function showFolderDef(engine) {
+    return {
+        name: "show_folder",
+        description: "Reveal an asset's folder in Finder",
+        schema: {
+            asset_id: z.string().describe("Asset ID (e.g. img-cute-cat)"),
+            book_id: z.string().describe("Book id"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id: _book_id } = args;
+            const result = await engine.workspaces.resolveArtifact(asset_id);
+            if (!result.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: result.error.message }],
+                };
+            }
+            return new Promise((resolve) => {
+                execFile("open", ["-R", result.value], (error) => {
+                    if (error) {
+                        resolve({
+                            isError: true,
+                            content: [{ type: "text", text: `Failed to open folder: ${error.message}` }],
+                        });
+                    }
+                    else {
+                        resolve({
+                            content: [{ type: "text", text: JSON.stringify({ status: "opened", path: result.value }) }],
+                        });
+                    }
+                });
+            });
+        },
+    };
+}

package/dist/tools/smooth-scene-concat.js

@@ -0,0 +1,122 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { findVideoFile } from "videobook-engine";
+import { probeVideo } from "../ffmpeg.js";
+import { queue } from "../queue.js";
+import { derivedLabel } from "../artifact-label.js";
+import { fixedTransitionSeconds } from "../scene-transition.js";
+function error(text) {
+    return {
+        isError: true,
+        content: [{ type: "text", text }],
+    };
+}
+function sourceName(artifact) {
+    return artifact.label?.trim() || artifact.artifactId;
+}
+function concatName(first, second) {
+    return derivedLabel("scene concat", `${sourceName(first)} + ${sourceName(second)}`);
+}
+function validVideoProbe(probe) {
+    return probe.width > 0 && probe.height > 0 && probe.fps > 0 && probe.videoDuration > 0;
+}
+export function smoothSceneConcatDef(engine) {
+    return {
+        name: "smooth_scene_concat",
+        description: "Join two video scenes into a new video, aligning overlapping boundary audio to avoid repeated speech and dissolving across it, otherwise crossfading briefly.",
+        schema: {
+            first_asset_id: z.string().describe("First video artifact id in playback order"),
+            second_asset_id: z.string().describe("Second video artifact id in playback order"),
+            transition_seconds: z.number().min(0.05).max(5).optional().describe("Optional fixed crossfade duration in seconds. Omit to auto-align shared boundary audio, falling back to 0.35 seconds."),
+            book_id: z.string().describe("Book UUID"),
+        },
+        handler: async (args) => {
+            const { first_asset_id, second_asset_id, transition_seconds, book_id, } = args;
+            const firstArtifact = engine.artifacts.get(first_asset_id);
+            if (!firstArtifact.ok)
+                return error(`First asset: ${firstArtifact.error.message}`);
+            const secondArtifact = engine.artifacts.get(second_asset_id);
+            if (!secondArtifact.ok)
+                return error(`Second asset: ${secondArtifact.error.message}`);
+            if (firstArtifact.value.kind !== "video" || secondArtifact.value.kind !== "video") {
+                return error("smooth_scene_concat requires two video artifacts");
+            }
+            if (first_asset_id === second_asset_id) {
+                return error("first_asset_id and second_asset_id must differ");
+            }
+            const [firstManifestResult, secondManifestResult] = await Promise.all([
+                engine.files.manifest(first_asset_id),
+                engine.files.manifest(second_asset_id),
+            ]);
+            if (!firstManifestResult.ok) {
+                return error(`First asset: ${firstManifestResult.error.message}`);
+            }
+            if (!secondManifestResult.ok) {
+                return error(`Second asset: ${secondManifestResult.error.message}`);
+            }
+            const firstVideo = findVideoFile(firstManifestResult.value.files);
+            const secondVideo = findVideoFile(secondManifestResult.value.files);
+            if (!firstVideo)
+                return error(`No video file in asset ${first_asset_id}`);
+            if (!secondVideo)
+                return error(`No video file in asset ${second_asset_id}`);
+            const firstPath = join(firstManifestResult.value.path, firstVideo.name);
+            const secondPath = join(secondManifestResult.value.path, secondVideo.name);
+            let firstProbe;
+            let secondProbe;
+            try {
+                [firstProbe, secondProbe] = await Promise.all([
+                    probeVideo(firstPath),
+                    probeVideo(secondPath),
+                ]);
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                return error(`Failed to probe input videos: ${message}`);
+            }
+            if (!validVideoProbe(firstProbe))
+                return error(`Invalid video in asset ${first_asset_id}`);
+            if (!validVideoProbe(secondProbe))
+                return error(`Invalid video in asset ${second_asset_id}`);
+            try {
+                fixedTransitionSeconds(firstProbe.videoDuration, secondProbe.videoDuration, transition_seconds);
+            }
+            catch (cause) {
+                return error(cause instanceof Error ? cause.message : String(cause));
+            }
+            const assetResult = await engine.artifacts.create("video", concatName(firstArtifact.value, secondArtifact.value));
+            if (!assetResult.ok) {
+                return error(`Failed to create scene concat asset: ${assetResult.error.message}`);
+            }
+            const { artifactId: assetId, path: assetDir } = assetResult.value;
+            const outputPath = join(assetDir, "original.mp4");
+            const jobId = `scene-concat-${assetId}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "smooth_scene_concat",
+                firstPath,
+                secondPath,
+                outputPath,
+                firstAssetId: first_asset_id,
+                secondAssetId: second_asset_id,
+                assetId,
+                assetDir,
+                bookId: book_id,
+                transitionSeconds: transition_seconds,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            asset_id: assetId,
+                            first_asset_id,
+                            second_asset_id,
+                            transition_seconds: transition_seconds ?? null,
+                            alignment_mode: transition_seconds === undefined ? "auto" : "fixed",
+                            job_id: jobId,
+                            status: "enqueued",
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/splice-video.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { join } from "node:path";
+import { queue } from "../queue.js";
+import { probeVideo } from "../ffmpeg.js";
+import { findVideoFile } from "videobook-engine";
+function deriveSpliceName(assetIds) {
+    if (assetIds.length <= 2)
+        return `splice-${assetIds[0]}-${assetIds[1]}`;
+    return `splice-${assetIds[0]}-x${assetIds.length - 1}`;
+}
+function error(text) {
+    return {
+        isError: true,
+        content: [{ type: "text", text }],
+    };
+}
+function uniqueAssetIds(ids) {
+    const seen = new Set();
+    const unique = [];
+    for (const id of ids) {
+        const trimmed = id.trim();
+        if (!trimmed)
+            return { error: "splice asset ids must be non-empty" };
+        if (seen.has(trimmed)) {
+            return { error: "splice asset ids must be unique" };
+        }
+        seen.add(trimmed);
+        unique.push(trimmed);
+    }
+    return unique;
+}
+async function resolveSpliceClip(engine, assetId) {
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        return { ok: false, error: artifact.error.message };
+    if (artifact.value.kind !== "video") {
+        return { ok: false, error: `Asset ${assetId} is not a video` };
+    }
+    const manifest = await engine.files.manifest(assetId);
+    if (!manifest.ok) {
+        return { ok: false, error: `${assetId}: ${manifest.error.message}` };
+    }
+    const video = findVideoFile(manifest.value.files);
+    if (!video)
+        return { ok: false, error: `No video file in asset ${assetId}` };
+    const path = join(manifest.value.path, video.name);
+    try {
+        const probe = await probeVideo(path);
+        return {
+            ok: true,
+            clip: { assetId, filename: video.name, path, probe },
+        };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { ok: false, error: `Failed to probe ${assetId}: ${message}` };
+    }
+}
+export function spliceVideoDef(engine) {
+    return {
+        name: "splice_video",
+        description: "Join two or more videos in playback order into a new video. overlap 0 concatenates whole clips; a positive overlap cuts each boundary at the best-matching frame within that many seconds.",
+        schema: {
+            first_asset_id: z.string().describe("First video artifact id in playback order. The match point is searched within this video."),
+            second_asset_id: z.string().describe("Second video artifact id in playback order. Its first frame is the search target against the preceding clip."),
+            additional_asset_ids: z.array(z.string()).max(18).optional()
+                .describe("Further video artifact ids in playback order after the second clip."),
+            overlap: z.number().min(0).default(0)
+                .describe("Possible overlap in seconds at each consecutive boundary. Use 0 to concatenate complete clips without trimming."),
+            book_id: z.string().describe("Book UUID"),
+        },
+        handler: async (args) => {
+            const { first_asset_id, second_asset_id, additional_asset_ids, overlap, book_id, } = args;
+            const additional = Array.isArray(additional_asset_ids)
+                ? additional_asset_ids
+                : [];
+            const ids = uniqueAssetIds([
+                first_asset_id,
+                second_asset_id,
+                ...additional,
+            ]);
+            if (!Array.isArray(ids))
+                return error(ids.error);
+            const resolved = await Promise.all(ids.map((assetId) => resolveSpliceClip(engine, assetId)));
+            const failed = resolved.find((result) => !result.ok);
+            if (failed && !failed.ok)
+                return error(failed.error);
+            const clips = resolved.flatMap((result) => result.ok ? [result.clip] : []);
+            const first = clips[0];
+            if (!first)
+                return error("splice_video requires at least two videos");
+            const resolvedOverlap = typeof overlap === "number" ? overlap : 0;
+            const spliceName = deriveSpliceName(ids);
+            const assetResult = await engine.artifacts.create("video", spliceName);
+            if (!assetResult.ok) {
+                return error(`Failed to create splice asset: ${assetResult.error.message}`);
+            }
+            const { artifactId: assetId, path: assetDir } = assetResult.value;
+            const outputPath = join(assetDir, "original.mp4");
+            const jobId = `splice-${assetId}-${Date.now()}`;
+            const second = clips[1];
+            await queue.enqueue(jobId, {
+                type: "splice_video",
+                firstPath: first.path,
+                secondPath: second.path,
+                firstFilename: first.filename,
+                secondFilename: second.filename,
+                outputPath,
+                firstAssetId: first.assetId,
+                secondAssetId: second.assetId,
+                assetId,
+                assetDir,
+                bookId: book_id,
+                targetWidth: first.probe.width,
+                targetHeight: first.probe.height,
+                firstFps: first.probe.fps,
+                firstDuration: first.probe.videoDuration,
+                secondDuration: second.probe.videoDuration,
+                firstHasAudio: first.probe.hasAudio,
+                secondHasAudio: second.probe.hasAudio,
+                overlap: resolvedOverlap,
+                clips: clips.map((clip) => ({
+                    assetId: clip.assetId,
+                    filename: clip.filename,
+                    duration: clip.probe.videoDuration,
+                    hasAudio: clip.probe.hasAudio,
+                })),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            asset_id: assetId,
+                            first: first.assetId,
+                            second: second.assetId,
+                            first_asset_id: first.assetId,
+                            second_asset_id: second.assetId,
+                            ...(clips.length > 2
+                                ? { additional_asset_ids: clips.slice(2).map((clip) => clip.assetId) }
+                                : {}),
+                            overlap: resolvedOverlap,
+                            job_id: jobId,
+                            status: "enqueued",
+                        }),
+                    }],
+            };
+        },
+    };
+}