videobook 0.0.0-stage → 0.2.0

package/dist/tools/media-library.js

@@ -0,0 +1,245 @@
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod";
+import { searchLibraryAssets, setNotebookMediaSlot, } from "../media-library.js";
+import { queue } from "../queue.js";
+import { searchReferenceStore } from "../search-reference-store.js";
+import { isLibraryBrowseStatus, LIBRARY_BROWSE_STATUSES } from "../library-browse.js";
+import { tagSelectorSchema } from "./asset-tags.js";
+const mediaKinds = ["audio", "image", "video"];
+function json(value) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(value),
+            }],
+    };
+}
+function failure(cause) {
+    return {
+        isError: true,
+        content: [{
+                type: "text",
+                text: cause instanceof Error ? cause.message : String(cause),
+            }],
+    };
+}
+export function mediaLibraryDefs(books) {
+    return [
+        {
+            name: "repair_library_search_indexes",
+            description: "Index ready visual media that is missing Similar-search coverage across books",
+            scope: "global",
+            schema: { kinds: z.array(z.enum(["image", "video"])).min(1).optional() },
+            handler: async (args) => {
+                await books.ready();
+                const kinds = [...new Set(args.kinds ?? ["image", "video"])].sort();
+                const summaries = books.list();
+                const jobs = await Promise.all(summaries.map(async (book) => {
+                    const job = await queue.enqueue(`repair-search:${book.bookId}:${kinds.join(",")}`, {
+                        type: "repair_search_indexes", bookId: book.bookId, kinds,
+                    });
+                    return { bookId: book.bookId, jobId: job.id };
+                }));
+                return json({ jobs });
+            },
+        },
+        {
+            name: "prepare_search_reference",
+            description: "Prepare an existing image or video asset for temporary reverse search",
+            scope: "global",
+            schema: {
+                source_book_id: z.string().uuid(),
+                source_artifact_id: z.string().uuid(),
+                kind: z.enum(["image", "video"]),
+                source_start_seconds: z.number().nonnegative().optional(),
+                source_duration_seconds: z.number().positive().optional(),
+            },
+            handler: async (args) => {
+                try {
+                    await books.ready();
+                    const sourceBookId = String(args.source_book_id);
+                    const source = books.get(sourceBookId);
+                    if (!source.ok)
+                        throw new Error(source.error.message);
+                    const artifact = source.value.engine.artifacts.get(String(args.source_artifact_id));
+                    if (!artifact.ok)
+                        throw new Error(artifact.error.message);
+                    const result = await queue.enqueueAndWait(`prepare-search-reference-${uuidv7()}`, {
+                        type: "prepare_search_reference",
+                        bookId: sourceBookId,
+                        mediaKind: String(args.kind),
+                        name: artifact.value.label ?? artifact.value.artifactId,
+                        assetId: artifact.value.artifactId,
+                        ...(typeof args.source_start_seconds === "number"
+                            ? { sourceStartMs: args.source_start_seconds * 1_000 }
+                            : {}),
+                        ...(typeof args.source_duration_seconds === "number"
+                            ? { sourceDurationMs: args.source_duration_seconds * 1_000 }
+                            : {}),
+                    }, 15 * 60_000);
+                    return json(result);
+                }
+                catch (cause) {
+                    return failure(cause);
+                }
+            },
+        },
+        {
+            name: "release_search_reference",
+            description: "Release a temporary reverse-search reference",
+            scope: "global",
+            schema: {
+                reference_id: z.string().uuid(),
+            },
+            handler: async (args) => json({
+                released: searchReferenceStore.release(String(args.reference_id)),
+            }),
+        },
+        {
+            name: "set_notebook_media_slot",
+            description: "Attach or clear a passive notebook media slot",
+            scope: "global",
+            schema: {
+                book_id: z.string().uuid(),
+                notebook_id: z.string().uuid(),
+                cell_id: z.string().uuid(),
+                artifact_ref: z.string().min(1).nullable(),
+                expected_revision: z.string().min(1).optional(),
+            },
+            handler: async (args) => {
+                try {
+                    await books.ready();
+                    const book = books.get(String(args.book_id));
+                    if (!book.ok)
+                        throw new Error(book.error.message);
+                    const result = await setNotebookMediaSlot(book.value.engine, {
+                        notebookId: String(args.notebook_id),
+                        cellId: String(args.cell_id),
+                        artifactRef: typeof args.artifact_ref === "string"
+                            ? args.artifact_ref
+                            : null,
+                        ...(typeof args.expected_revision === "string"
+                            ? { expectedRevision: args.expected_revision }
+                            : {}),
+                    });
+                    return json({
+                        cell_id: result.cellId,
+                        output_artifact_id: result.outputArtifactId,
+                        revision: result.revision,
+                    });
+                }
+                catch (cause) {
+                    return failure(cause);
+                }
+            },
+        },
+        {
+            name: "search_library_assets",
+            description: "Search ready audio, image, and video assets across all books",
+            scope: "global",
+            schema: {
+                query: z.string().optional(),
+                reference_id: z.string().uuid().optional(),
+                reference_range: z.object({
+                    start_seconds: z.number().nonnegative(),
+                    duration_seconds: z.number().positive().optional(),
+                }).optional(),
+                kinds: z.array(z.enum(mediaKinds)).min(1),
+                tags_all: z.array(tagSelectorSchema).optional()
+                    .describe("Only assets carrying every one of these tags"),
+                tags_any: z.array(tagSelectorSchema).optional()
+                    .describe("Only assets carrying at least one of these tags"),
+                browse_status: z.enum(LIBRARY_BROWSE_STATUSES).optional()
+                    .describe("Browse ready, processing, error, or all media when there is no text or reverse-search query. Semantic and reverse search stay ready-only."),
+                limit: z.number().int().positive().max(100).optional(),
+                offset: z.number().int().nonnegative().optional(),
+            },
+            handler: async (args) => {
+                try {
+                    const referenceRange = searchReferenceRange(args.reference_range);
+                    const tags = {
+                        ...(args.tags_all ? { all: args.tags_all } : {}),
+                        ...(args.tags_any ? { any: args.tags_any } : {}),
+                    };
+                    const browseStatus = isLibraryBrowseStatus(args.browse_status)
+                        ? args.browse_status
+                        : undefined;
+                    return json(await searchLibraryAssets(books, {
+                        ...(typeof args.query === "string" ? { query: args.query } : {}),
+                        ...(typeof args.reference_id === "string"
+                            ? { referenceId: args.reference_id }
+                            : {}),
+                        ...(referenceRange ? { referenceRange } : {}),
+                        kinds: args.kinds,
+                        tags,
+                        ...(browseStatus ? { browseStatus } : {}),
+                        ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+                        ...(typeof args.offset === "number" ? { offset: args.offset } : {}),
+                    }));
+                }
+                catch (cause) {
+                    return failure(cause);
+                }
+            },
+        },
+        {
+            name: "attach_library_asset",
+            description: "Copy a foreign Library asset into a book and attach it to a media slot",
+            scope: "global",
+            schema: {
+                source_book_id: z.string().uuid(),
+                source_artifact_id: z.string().uuid(),
+                target_book_id: z.string().uuid(),
+                notebook_id: z.string().uuid(),
+                cell_id: z.string().uuid(),
+                expected_output_artifact_id: z.string().uuid().nullable(),
+                new_name: z.string().min(1).optional(),
+            },
+            handler: async (args) => {
+                try {
+                    const jobId = `copy-library-asset-${uuidv7()}`;
+                    const result = await queue.enqueueAndWait(jobId, {
+                        type: "copy_library_asset",
+                        bookId: String(args.target_book_id),
+                        sourceBookId: String(args.source_book_id),
+                        sourceArtifactId: String(args.source_artifact_id),
+                        targetBookId: String(args.target_book_id),
+                        notebookId: String(args.notebook_id),
+                        cellId: String(args.cell_id),
+                        expectedOutputArtifactId: typeof args.expected_output_artifact_id === "string"
+                            ? args.expected_output_artifact_id
+                            : null,
+                        ...(typeof args.new_name === "string"
+                            ? { newName: args.new_name }
+                            : {}),
+                    }, 15 * 60_000);
+                    return json({
+                        source_book_id: result.sourceBookId,
+                        source_artifact_id: result.sourceArtifactId,
+                        target_book_id: result.targetBookId,
+                        target_artifact_id: result.targetArtifactId,
+                        notebook_id: result.notebookId,
+                        cell_id: result.cellId,
+                        revision: result.revision,
+                    });
+                }
+                catch (cause) {
+                    return failure(cause);
+                }
+            },
+        },
+    ];
+}
+function searchReferenceRange(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const range = value;
+    if (typeof range.start_seconds !== "number")
+        return undefined;
+    return {
+        startMs: range.start_seconds * 1_000,
+        ...(typeof range.duration_seconds === "number"
+            ? { durationMs: range.duration_seconds * 1_000 }
+            : {}),
+    };
+}

package/dist/tools/move-timeline-audio.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { readTimeline, timelineFailure, timelineInput, timelinePayload, writeTimeline, } from "../timeline-helpers.js";
+export function moveTimelineAudioDef(engine) {
+    return {
+        name: "move_timeline_audio",
+        description: "Move an audio overlay to a frame offset",
+        schema: {
+            book_id: z.string().uuid(),
+            audio_id: z.string().uuid(),
+            start_frame: z.number().int().min(0),
+        },
+        handler: async (args) => {
+            const timeline = readTimeline(engine);
+            const audioId = String(args.audio_id);
+            if (!timeline.audio.some((clip) => clip.id === audioId)) {
+                return timelineFailure(`Timeline audio clip not found: ${audioId}`);
+            }
+            const result = await writeTimeline(engine, {
+                ...timelineInput(timeline),
+                audio: timeline.audio.map((clip) => ({
+                    id: clip.id,
+                    artifactId: clip.artifactId,
+                    startFrame: clip.id === audioId ? args.start_frame : clip.startFrame,
+                    durationFrames: clip.durationFrames,
+                    ...(clip.volume === undefined ? {} : { volume: clip.volume }),
+                    ...(clip.fadeIn === undefined ? {} : { fadeIn: clip.fadeIn }),
+                    ...(clip.fadeOut === undefined ? {} : { fadeOut: clip.fadeOut }),
+                })),
+            });
+            return result.ok ? {
+                content: [{ type: "text", text: JSON.stringify(timelinePayload(result.value)) }],
+            } : timelineFailure(result.error.message);
+        },
+    };
+}

package/dist/tools/music-analysis.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { cachedMusicAnalysis, musicSource, readMusicAnalysis, readSectionLabels, sectionLabelsCurrent } from "../rhythm/music-analysis.js";
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+export function musicAnalysisDefs(engine) {
+    const schema = { book_id: z.string().uuid(), asset_id: z.string().uuid(), stream_id: z.string().uuid().optional() };
+    return [
+        {
+            name: "analyze_music",
+            description: "Analyze an audio source's beats and waveform locally in a background job, reusing results for unchanged audio. sections adds an energy curve and suggested section boundaries and labels, which may use a paid model.",
+            scope: "book",
+            schema: { ...schema, force: z.boolean().optional(), sections: z.boolean().optional() },
+            handler: async (args) => {
+                try {
+                    const source = await musicSource(engine, String(args.asset_id), args.stream_id);
+                    if (!args.force && await cachedMusicAnalysis(engine, source)) {
+                        if (args.sections === true && !await labelsReadyOrPending(engine, source)) {
+                            await queue.enqueue(`music-sections-${source.artifactId}-${source.analysisId}`, {
+                                type: "label_music_sections", bookId: String(args.book_id), artifactId: source.artifactId,
+                                analysisId: source.analysisId, streamId: source.streamId,
+                            });
+                        }
+                        return json(await readMusicAnalysis(engine, source.artifactId, source.streamId));
+                    }
+                    await queue.enqueue(`music-${source.artifactId}-${source.analysisId}`, {
+                        type: "analyze_music", bookId: String(args.book_id), musicArtifactId: source.artifactId,
+                        analysisId: source.analysisId, streamId: source.streamId, sections: args.sections === true,
+                    });
+                    return json(await readMusicAnalysis(engine, source.artifactId, source.streamId));
+                }
+                catch (error) {
+                    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+                }
+            },
+        },
+        {
+            name: "get_music_analysis",
+            description: "Read cached music beats, waveform, analysis job status and optional section energy/label suggestions for the current source audio",
+            scope: "book", schema,
+            handler: async (args) => {
+                try {
+                    return json(await readMusicAnalysis(engine, String(args.asset_id), args.stream_id));
+                }
+                catch (error) {
+                    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+                }
+            },
+        },
+    ];
+}
+async function labelsReadyOrPending(engine, source) {
+    const analysis = await cachedMusicAnalysis(engine, source);
+    const stored = analysis ? await readSectionLabels(engine, source.artifactId, source.analysisId) : null;
+    if (stored && analysis && sectionLabelsCurrent(stored, analysis))
+        return true;
+    const jobs = engine.jobs.queue.list({ type: "label_music_sections", limit: 500 });
+    return jobs.some((item) => item.payload.analysisId === source.analysisId && ["queued", "running", "completing"].includes(item.state));
+}

package/dist/tools/music-draft.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { musicDraftOptionsSchema } from "../rhythm/draft-model.js";
+import { planMusicVideo, commitMusicVideo } from "../rhythm/music-draft.js";
+const schema = z.object({ book_id: z.string().uuid(), expected_revision: z.string().min(1), rhythm_revision: z.string().min(1),
+    actor: z.string().default("videobook-user"), source_surface: z.enum(["ui", "slash", "chat", "system"]).default("ui"), options: musicDraftOptionsSchema });
+export function musicDraftDefs(engine) {
+    return [{ name: "plan_music_video", description: "Draft a beat-aligned music video from selected sources without saving it. Review the returned sequence, then apply it with commit_music_video using the returned intent, preview hash and revisions.", scope: "book", schema: schema.shape,
+            annotations: { readOnlyHint: true }, handler: async (input) => {
+                try {
+                    const args = schema.parse(input);
+                    return { content: [{ type: "text", text: JSON.stringify(await planMusicVideo(engine, args.options, args.expected_revision, args.rhythm_revision, args.actor, args.source_surface)) }] };
+                }
+                catch (error) {
+                    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+                }
+            } }, {
+            name: "commit_music_video", description: "Apply a reviewed music-video draft once, checking its timeline, source and beat-map revisions. Returns the previous action on a retry.", scope: "book",
+            schema: { book_id: z.string().uuid(), intent: z.record(z.string(), z.unknown()), preview_hash: z.string().min(1), rhythm_revision: z.string().min(1), sequence_content_revision: z.string().min(1) },
+            annotations: { idempotentHint: true }, handler: async (args) => {
+                try {
+                    const result = await commitMusicVideo(engine, args.intent, String(args.preview_hash), String(args.rhythm_revision), String(args.sequence_content_revision));
+                    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+                }
+                catch (error) {
+                    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+                }
+            },
+        }];
+}

package/dist/tools/pad-video.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { join } from "node:path";
+import { queue } from "../queue.js";
+import { findVideoFile } from "videobook-engine";
+import { probeVideo } from "../ffmpeg.js";
+import { parseTime } from "../time-parse.js";
+export function padVideoDef(engine) {
+    return {
+        name: "pad_video",
+        description: "Append black video frames at the end to make a whole-second video tail. Retains original audio and makes the appended tail silent.",
+        schema: {
+            asset_id: z.string().describe("Source video asset ID"),
+            book_id: z.string().describe("Book id"),
+            padding: z.string().describe("Padding duration (e.g. 2s)"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id, padding } = args;
+            const paddingSecs = parseTime(padding);
+            if (paddingSecs === undefined || paddingSecs <= 0) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Invalid padding duration: ${padding}` }],
+                };
+            }
+            const manifestResult = await engine.files.manifest(asset_id);
+            if (!manifestResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: manifestResult.error.message }],
+                };
+            }
+            const manifest = manifestResult.value;
+            const videoFile = findVideoFile(manifest.files);
+            if (!videoFile) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `No video file found in asset ${asset_id}` }],
+                };
+            }
+            const sourcePath = join(manifest.path, videoFile.name);
+            let sourceDurationSec;
+            let hasAudio;
+            try {
+                const probe = await probeVideo(sourcePath);
+                if (!probe.videoStream || probe.videoDuration <= 0)
+                    throw new Error("Source has no playable video stream");
+                sourceDurationSec = probe.videoDuration;
+                hasAudio = probe.hasAudio;
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `Failed to probe source duration: ${err instanceof Error ? err.message : String(err)}`,
+                        }],
+                };
+            }
+            const unroundedTarget = sourceDurationSec + paddingSecs;
+            const EPSILON = 1e-4;
+            const targetSecs = Math.ceil(unroundedTarget - EPSILON);
+            const jobId = `pad-video-${asset_id}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "pad_video",
+                sourcePath,
+                assetDir: manifest.path,
+                sourceAssetId: asset_id,
+                bookId: book_id,
+                targetSecs,
+                hasAudio,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            source_asset_id: asset_id,
+                            source_duration_sec: sourceDurationSec,
+                            padding_sec: paddingSecs,
+                            target_sec: targetSecs,
+                            job_id: jobId,
+                            status: "enqueued",
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/post-record.js

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { getPost, listPosts, migrateLegacyPosts } from "../posts/post-store.js";
+import { POST_METRIC_NAMES, POST_PLATFORMS } from "../posts/post-contract.js";
+import { recordPostMetrics } from "../posts/post-metrics.js";
+import { postIcloudSyncStatus } from "../posts/icloud-drive.js";
+import { postAnalysisTarget } from "../posts/post-copy.js";
+import { freshPostLanguage } from "../lightning-defaults.js";
+import { POST_COPY_LANGUAGES } from "../posts/post-copy-format.js";
+import { getApiKey } from "../api-key.js";
+import { analyzeVideoJobPayload } from "./analyze-video.js";
+const book = { book_id: z.string() };
+const target = { ...book, post_cell_id: z.string().uuid() };
+const fields = { platform: z.enum(POST_PLATFORMS).optional(), account: z.string().max(200).optional(), caption: z.string().max(25_000).optional(), credits: z.string().max(10_000).optional(), notes: z.string().max(20_000).optional() };
+function define(name, description, schema, handler, scope = "book") {
+    return { name, description, schema, scope, handler: async (args) => {
+            try {
+                return { content: [{ type: "text", text: JSON.stringify(await handler(args)) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+            }
+        } };
+}
+async function draftPostCopyTool(engine, args) {
+    if (!getApiKey("OPENAI_API_KEY"))
+        throw new Error("OPENAI_API_KEY is not set");
+    const bookId = String(args.book_id);
+    const postCellId = String(args.post_cell_id);
+    const post = getPost(engine, postCellId);
+    if (!post.definition.source)
+        throw new Error(`${post.address} has no saved source clip. Choose one in the Post panel.`);
+    const target = await postAnalysisTarget(engine, post);
+    if (target?.analyzable && !target.analyzed) {
+        await queue.enqueueAndWait(`post-copy-analysis-${target.assetId}-${randomUUID()}`, await analyzeVideoJobPayload(engine, target.assetId, bookId, "tagging"));
+    }
+    const platform = args.platform ?? post.definition.platform;
+    const suppliedTags = Array.isArray(args.tags)
+        ? args.tags.filter((tag) => typeof tag === "string")
+        : undefined;
+    const request = {
+        platform,
+        language: freshPostLanguage(platform, args.language),
+        instruction: typeof args.instruction === "string" ? args.instruction : undefined,
+        caption: typeof args.caption === "string" ? args.caption : undefined,
+        tags: suppliedTags,
+    };
+    return queue.enqueueAndWait(`post-copy-${postCellId}-${randomUUID()}`, { type: "post_copy", bookId, postCellId, request });
+}
+export function postRecordDefs(engine) {
+    return [
+        define("create_post", "Create a Post cell to track one publication. Freezes the selected source clip and its upstream idea/prompt lineage; place the cell beside the source.", { ...book, notebook_id: z.string().uuid(), source_cell_id: z.string().uuid().optional(), ...fields }, async (args) => queue.enqueueAndWait(`post-create-${randomUUID()}`, { type: "post_create", bookId: String(args.book_id), args: { notebookId: String(args.notebook_id), sourceCellId: args.source_cell_id, platform: args.platform, caption: args.caption, credits: args.credits, account: args.account, notes: args.notes } })),
+        define("update_post", "Edit a Post draft or its notes. Delivered media, caption and source versions are immutable; create another Post for a repost.", { ...target, ...fields, source_cell_id: z.string().uuid().optional() }, async (args) => {
+            const patch = {};
+            for (const name of ["account", "caption", "credits", "notes"])
+                if (typeof args[name] === "string")
+                    patch[name] = args[name];
+            if (args.platform)
+                patch.platform = args.platform;
+            if (args.source_cell_id)
+                patch.sourceCellId = String(args.source_cell_id);
+            return queue.enqueueAndWait(`post-update-${args.post_cell_id}-${randomUUID()}`, { type: "post_update", bookId: String(args.book_id), postCellId: String(args.post_cell_id), patch });
+        }),
+        define("get_post", "Read a Post with its frozen source, lineage, publication receipt and timestamped results.", target, async (args) => { await migrateLegacyPosts(engine); return getPost(engine, String(args.post_cell_id)); }),
+        define("list_posts", "List this book's publications and performance observations for comparison.", book, async () => { await migrateLegacyPosts(engine); return { posts: listPosts(engine) }; }),
+        define("link_post", "Attach the actual URL and publication time after manually posting. Freezes media and caption; duplicate publication URLs are rejected.", { ...target, url: z.string().url(), posted_at: z.string().datetime() }, async (args) => {
+            const post = await queue.enqueueAndWait(`post-link-${args.post_cell_id}-${randomUUID()}`, { type: "post_link", bookId: String(args.book_id), postCellId: String(args.post_cell_id), url: String(args.url), postedAt: String(args.posted_at) });
+            if (post.definition.platform === "x")
+                await queue.enqueue(`post-metrics-${post.id}-${randomUUID()}`, { type: "post_metrics", bookId: String(args.book_id), postCellId: post.id });
+            return post;
+        }),
+        define("upload_post_to_dropbox", "Upload the frozen Post media and caption.txt to a private Dropbox folder. A caption saves to the Post first and freezes with the first delivery. Interrupted uploads resume without replacing unrelated files.", { ...target, folder: z.string().optional(), caption: fields.caption }, async (args) => queue.enqueueAndWait(`post-dropbox-${args.post_cell_id}-${randomUUID()}`, { type: "post_dropbox", bookId: String(args.book_id), postCellId: String(args.post_cell_id), folder: args.folder, caption: args.caption })),
+        define("save_post_to_icloud", "Deliver a Post's frozen media and caption.txt to the shared iCloud Drive Videobook folder (folder is relative to it) so they appear in Files on the phones. A caption saves to the Post first. Repeats are no-ops and never replace different files.", { ...target, folder: z.string().max(500).optional(), caption: fields.caption }, async (args) => queue.enqueueAndWait(`post-icloud-${args.post_cell_id}-${randomUUID()}`, { type: "post_icloud", bookId: String(args.book_id), postCellId: String(args.post_cell_id), folder: args.folder, caption: args.caption })),
+        define("draft_post_copy", "Draft a Post's caption and hashtags from its clip's analysis, transcript and prompts (analyzing the clip first when needed) without saving. language defaults to Thai for TikTok and English otherwise; instruction, caption and tags rewrite an existing draft.", { ...target, language: z.enum(POST_COPY_LANGUAGES).optional(), platform: z.enum(POST_PLATFORMS).optional(), instruction: z.string().max(1000).optional(), caption: fields.caption, tags: z.array(z.string().max(100)).max(50).optional() }, async (args) => draftPostCopyTool(engine, args)),
+        define("refresh_post_metrics", "Fetch a current X metrics observation. Non-X publications use record_post_metrics. Unknown values remain unknown.", target, async (args) => queue.enqueueAndWait(`post-metrics-${args.post_cell_id}-${randomUUID()}`, { type: "post_metrics", bookId: String(args.book_id), postCellId: String(args.post_cell_id) })),
+        define("record_post_metrics", "Append a manual performance observation with its actual timestamp. Omit unavailable metrics; zero means an observed zero.", { ...target, observed_at: z.string().datetime(), values: z.partialRecord(z.enum(POST_METRIC_NAMES), z.number().int().nonnegative().nullable()).refine((value) => Object.keys(value).length > 0), note: z.string().optional() }, async (args) => {
+            recordPostMetrics(engine, String(args.post_cell_id), { source: "manual", observedAt: String(args.observed_at), values: args.values, note: args.note });
+            return getPost(engine, String(args.post_cell_id));
+        }),
+        define("post_icloud_sync_status", "Read whether a saved Post's clip and caption.txt have finished uploading to iCloud. A folder outside iCloud Drive reports that it is not an iCloud folder.", target, async (args) => postIcloudSyncStatus(engine, String(args.post_cell_id))),
+    ];
+}