videobook 0.0.0-stage → 0.2.0

package/dist/tools/archive-clip.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { queue } from "../queue.js";
+import { getApiKey } from "../api-key.js";
+function normalizeUrl(url) {
+    return /^https?:\/\//i.test(url) ? url : `https://${url}`;
+}
+export function archiveClipDef(engine) {
+    return {
+        name: "archive_clip",
+        description: "Save a URL or a video or audio asset to the global clip archive (B2 when configured, otherwise local), deduplicated by content and transcribed; restore it with restore_archive_clips.",
+        schema: {
+            url: z.string().optional().describe("Source URL to download in full"),
+            asset_id: z.string().optional().describe("Existing video/audio asset ID to archive"),
+            book_id: z.string().uuid().describe("Book UUID"),
+            title: z.string().optional().describe("Optional archive title"),
+            topics: z.array(z.string()).optional().default([]).describe("Search topics to attach to this clip"),
+            people: z.array(z.string()).optional().default([]).describe("Named people to attach to this clip"),
+            language_code: z.string().optional().describe("Language code (e.g. 'en'). Auto-detected if omitted."),
+            tag_audio_events: z.boolean().optional().default(true).describe("Tag audio events like laughter, music, etc."),
+            diarize: z.boolean().optional().default(true).describe("Enable speaker diarization"),
+        },
+        handler: async (args) => {
+            const { url, asset_id, book_id, title, topics, people, language_code, tag_audio_events, diarize, } = args;
+            if ((url ? 1 : 0) + (asset_id ? 1 : 0) !== 1) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "archive_clip requires exactly one of url or asset_id" }],
+                };
+            }
+            if (!getApiKey("ELEVENLABS_API_KEY")) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "ELEVENLABS_API_KEY environment variable is not set or is a placeholder" }],
+                };
+            }
+            if (asset_id) {
+                const manifest = await engine.files.manifest(asset_id);
+                if (!manifest.ok) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: manifest.error.message }],
+                    };
+                }
+            }
+            const ingestId = randomUUID();
+            const jobId = `archive-clip-${ingestId}`;
+            await queue.enqueue(jobId, {
+                type: "archive_clip",
+                bookId: book_id,
+                ...(asset_id ? { assetId: asset_id } : {}),
+                ...(url ? { url: normalizeUrl(url) } : {}),
+                ...(title ? { title } : {}),
+                topics,
+                people,
+                tagAudioEvents: tag_audio_events,
+                diarize,
+                ingestId,
+                ...(language_code ? { languageCode: language_code } : {}),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "enqueued",
+                            job_id: jobId,
+                            ingest_id: ingestId,
+                            archive_id: null,
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/asset-history.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+async function enrichCommitsWithRewrite(engine, commits, artifact) {
+    if (artifact.kind !== "script")
+        return commits;
+    return Promise.all(commits.map(async (commit) => {
+        const result = await engine.metadata.artifacts.readAtRevision(artifact.artifactId, "original", commit.hash);
+        if (!result.ok || result.value.origin !== "describe_image") {
+            return commit;
+        }
+        const metadata = result.value;
+        return {
+            ...commit,
+            rewrite: {
+                model: metadata.model ?? "gpt-5.6-sol",
+                variant: metadata.variant ?? "full",
+                ...(metadata.platform ? { platform: metadata.platform } : {}),
+                ...(metadata.customPrompt
+                    ? { customPrompt: metadata.customPrompt }
+                    : {}),
+                ...(metadata.processed_at
+                    ? { processedAt: metadata.processed_at }
+                    : {}),
+            },
+        };
+    }));
+}
+export function assetHistoryDef(engine) {
+    return {
+        name: "asset_history",
+        description: "Get immutable Dolt revision history for an asset",
+        schema: {
+            asset_id: z.string().describe("Artifact UUID"),
+            book_id: z.string().describe("Book id"),
+            limit: z.number().optional().describe("Maximum revisions (default 20)"),
+        },
+        handler: async (args) => {
+            const { asset_id, limit } = args;
+            try {
+                const artifact = engine.artifacts.get(asset_id);
+                if (!artifact.ok)
+                    throw new Error(artifact.error.message);
+                const commits = engine.history.artifact(artifact.value.artifactId, limit);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(await enrichCommitsWithRewrite(engine, commits, artifact.value)),
+                        }],
+                };
+            }
+            catch (error) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: error instanceof Error ? error.message : String(error),
+                        }],
+                };
+            }
+        },
+    };
+}

package/dist/tools/asset-manifest.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export function assetManifestDef(engine) {
+    return {
+        name: "asset_manifest",
+        description: "List all files in an asset directory",
+        schema: {
+            asset_id: z.string().describe("Asset ID (e.g. img-cute-cat, vid-running-dog)"),
+            book_id: z.string().describe("Book id"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id: _book_id } = args;
+            const result = await engine.files.manifest(asset_id);
+            if (!result.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: result.error.message }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.value) }],
+            };
+        },
+    };
+}

package/dist/tools/asset-tags.js

@@ -0,0 +1,151 @@
+/**
+ * Manual tag editing and tag discovery over MCP.
+ *
+ * Every operation is book-scoped: the handler runs against the engine bound
+ * to `book_id`, so a Library edit made from another book still lands in the
+ * book that owns the asset. Manual intent is all these tools can express —
+ * the automatic set belongs to the tagging jobs, and nothing here can add to
+ * it, relabel it, or clear a dismissal that a user meant to keep.
+ */
+import { TAG_FACETS, tagCanonicalKey } from "videobook-engine";
+import { z } from "zod";
+import { assetTagSummary, readAssetTagSummaries, tagFacetCounts } from "../asset-tags.js";
+import { matchesTagPrefix, resolveTagInput } from "../tag-vocabulary.js";
+const facetSchema = z.enum(TAG_FACETS).describe("Optional category; inferred from the label when omitted. Use custom for a free-form tag with a separate identity");
+const labelSchema = z.string().min(1).describe("Display label; the engine normalizes it into the canonical identity");
+/** One tag filter term: a label, optionally pinned to a single facet. */
+export const tagSelectorSchema = z.object({
+    facet: facetSchema.optional(),
+    label: labelSchema,
+});
+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),
+            }],
+    };
+}
+/**
+ * Tag operations address artifacts, and the Library also lists synthetic
+ * notebook rows whose id is a notebook id. Resolving through the artifact
+ * catalog first turns that into a clear error instead of a foreign-key
+ * failure from the write.
+ */
+function resolveArtifact(engine, assetId) {
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    return artifact.value;
+}
+function tagState(engine, assetId) {
+    const state = engine.tags.read(assetId);
+    if (!state.ok)
+        throw new Error(state.error.message);
+    return assetTagSummary(state.value);
+}
+function matchingIdentities(engine, assetId, input) {
+    const state = engine.tags.read(assetId);
+    if (!state.ok)
+        throw new Error(state.error.message);
+    const existing = [...state.value.manual, ...state.value.automatic, ...state.value.dismissed];
+    const tag = resolveTagInput(input, existing);
+    const key = tagCanonicalKey(tag.label);
+    const aliases = existing.filter((entry) => entry.facet === tag.facet
+        && tagCanonicalKey(resolveTagInput(entry).label) === key);
+    const identities = [...new Map([tag, ...aliases].map((entry) => [`${entry.facet}/${tagCanonicalKey(entry.label)}`, { facet: entry.facet, label: entry.label }])).values()];
+    return { tag, identities };
+}
+async function applyToIdentities(engine, assetId, identities, op) {
+    for (const identity of identities) {
+        const result = op === "remove"
+            ? await engine.tags.remove(assetId, identity)
+            : await engine.tags.restore(assetId, identity);
+        if (!result.ok)
+            throw new Error(result.error.message);
+    }
+}
+async function editAssetTag(engine, edit) {
+    if (edit.entity_id && edit.op !== "add")
+        throw new Error("entity_id applies only to op add");
+    const artifact = resolveArtifact(engine, edit.asset_id);
+    const assetId = artifact.artifactId;
+    const { tag, identities } = matchingIdentities(engine, assetId, edit);
+    if (edit.op === "add") {
+        const added = await engine.tags.add(assetId, { ...tag, ...(edit.entity_id ? { entityId: edit.entity_id } : {}) });
+        if (!added.ok)
+            throw new Error(added.error.message);
+    }
+    await applyToIdentities(engine, assetId, identities, edit.op === "remove" ? "remove" : "restore");
+    return json({ asset_id: assetId, tags: tagState(engine, assetId) });
+}
+export function assetTagDefs(engine) {
+    return [
+        {
+            name: "edit_asset_tag",
+            description: "Add, remove or restore one tag on an asset. add makes a manual tag that survives re-analysis; removing an automatic tag records a dismissal so re-analysis cannot bring it back; restore clears that dismissal.",
+            annotations: { idempotentHint: true },
+            schema: {
+                book_id: z.string().describe("Book that owns the asset"),
+                asset_id: z.string().describe("Artifact id to edit"),
+                op: z.enum(["add", "remove", "restore"]),
+                facet: facetSchema.optional(),
+                label: labelSchema,
+                entity_id: z.string().optional().describe("With op add: an already-confirmed entity to reference; never invent one"),
+            },
+            handler: async (args) => {
+                try {
+                    return await editAssetTag(engine, args);
+                }
+                catch (cause) {
+                    return failure(cause);
+                }
+            },
+        },
+        {
+            name: "suggest_asset_tags",
+            description: "List the tags in use in a book with the number of assets carrying each, optionally narrowed by prefix or facet. Use it for autocomplete and to discover the groups available for filtering.",
+            annotations: { readOnlyHint: true },
+            schema: {
+                book_id: z.string().describe("Book to inspect"),
+                prefix: z.string().optional().describe("Match tags starting with this text; omit for the most used tags"),
+                facet: facetSchema.optional(),
+                kinds: z.array(z.enum(["audio", "image", "video", "final"])).optional()
+                    .describe("Restrict counting to these artifact kinds"),
+                limit: z.number().int().positive().max(200).optional(),
+                asset_id: z.string().optional().describe("Return this asset's own tag state alongside the suggestions"),
+            },
+            handler: async (args) => {
+                const { prefix, facet, kinds, limit, asset_id } = args;
+                try {
+                    const ids = engine.artifacts.list().filter((artifact) => !kinds
+                        || kinds.some((kind) => kind === artifact.kind)).map((artifact) => artifact.artifactId);
+                    const summaries = [...readAssetTagSummaries(engine, ids).values()];
+                    const suggestions = tagFacetCounts(summaries.map((tags) => ({ tags })), Infinity)
+                        .filter((tag) => (!facet || tag.facet === facet) && matchesTagPrefix(tag, prefix ?? ""))
+                        .slice(0, limit ?? 50);
+                    const asset = asset_id
+                        ? tagState(engine, resolveArtifact(engine, asset_id).artifactId)
+                        : null;
+                    return json({
+                        facets: TAG_FACETS,
+                        suggestions: suggestions.map((row) => ({
+                            facet: row.facet,
+                            key: row.key,
+                            label: row.label,
+                            assets: row.assets,
+                        })),
+                        ...(asset ? { asset_id, tags: asset } : {}),
+                    });
+                }
+                catch (cause) {
+                    return failure(cause);
+                }
+            },
+        },
+    ];
+}

package/dist/tools/assign-slot.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { enqueueLazyTimelineRender } from "../lazy-render.js";
+import { readTimeline, resolveArtifact, slotIndex, timelineFailure, timelineInput, timelinePayload, writeTimeline, } from "../timeline-helpers.js";
+async function enqueueLazyAnalysis(engine, asset, bookId) {
+    if (!process.env.OPENAI_API_KEY)
+        return null;
+    if (asset.kind !== "video" && asset.kind !== "image")
+        return null;
+    const manifest = await engine.files.manifest(asset.artifactId);
+    if (!manifest.ok)
+        return null;
+    if ((await engine.files.read(asset.artifactId, ".original.analysis.json")).ok)
+        return null;
+    if (asset.kind === "video") {
+        const transcription = await engine.files.read(asset.artifactId, ".analysis.gpt4otrans.json");
+        const jobId = `auto-analyze-${asset.artifactId}`;
+        await queue.enqueue(jobId, {
+            type: "analyze_video",
+            bookId,
+            assetId: asset.artifactId,
+            assetDir: manifest.value.path,
+            hasTranscription: transcription.ok,
+        });
+        return { jobId, kind: "analyze_video" };
+    }
+    const original = manifest.value.files.find((file) => /^original\.(jpe?g|png|webp)$/i.test(file.name));
+    if (!original)
+        return null;
+    const jobId = `auto-describe-${asset.artifactId}`;
+    await queue.enqueue(jobId, {
+        type: "describe_image",
+        bookId,
+        sourceAssetId: asset.artifactId,
+        sourceImageFilename: original.name,
+    });
+    return { jobId, kind: "describe_image" };
+}
+export function assignSlotDef(engine) {
+    return {
+        name: "assign_slot",
+        description: "Assign an artifact to a typed timeline slot",
+        schema: {
+            book_id: z.string().uuid(),
+            asset_id: z.string(),
+            slot: z.string(),
+        },
+        handler: async (args) => {
+            const index = slotIndex(String(args.slot));
+            if (index === null)
+                return timelineFailure("Slot must use the form s01, s02, and so on");
+            const asset = resolveArtifact(engine, String(args.asset_id));
+            if (!asset)
+                return timelineFailure(`Artifact not found: ${String(args.asset_id)}`);
+            const timeline = readTimeline(engine);
+            if (index > timeline.slots.length) {
+                return timelineFailure("Typed timelines cannot contain empty gaps; assign the next available slot first");
+            }
+            const slots = timeline.slots.map((slot) => ({
+                id: slot.id,
+                artifactId: slot.artifactId,
+                ...(slot.volume === undefined ? {} : { volume: slot.volume }),
+                ...(slot.audioFadeIn === undefined ? {} : { audioFadeIn: slot.audioFadeIn }),
+                ...(slot.audioFadeOut === undefined ? {} : { audioFadeOut: slot.audioFadeOut }),
+            }));
+            const replacement = index < slots.length
+                ? { ...slots[index], artifactId: asset.artifactId }
+                : { artifactId: asset.artifactId };
+            if (index < slots.length)
+                slots[index] = replacement;
+            else
+                slots.push(replacement);
+            const result = await writeTimeline(engine, { ...timelineInput(timeline), slots });
+            if (!result.ok)
+                return timelineFailure(result.error.message);
+            const response = timelinePayload(result.value);
+            const bookId = String(args.book_id);
+            try {
+                const analysis = await enqueueLazyAnalysis(engine, asset, bookId);
+                if (analysis)
+                    response.auto_analyze = analysis;
+            }
+            catch {
+                delete response.auto_analyze;
+            }
+            try {
+                const render = await enqueueLazyTimelineRender(engine, bookId, asset.artifactId, asset);
+                if (render)
+                    response.auto_render = render;
+            }
+            catch {
+                delete response.auto_render;
+            }
+            return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        },
+    };
+}

package/dist/tools/audio-boost.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { extname, join } from "node:path";
+import { queue } from "../queue.js";
+import { findAudioFile, findVideoFile } from "videobook-engine";
+import { probeVideo } from "../ffmpeg.js";
+import { audioOnlyOutputOptions, videoAudioOutputOptions } from "../audio-encoding.js";
+const BOOST_MIN = 1.0;
+const BOOST_MAX = 4.0;
+function validateBoost(boost) {
+    if (boost === 1.0)
+        return "Boost 1.0 is a no-op — nothing to change";
+    if (boost < BOOST_MIN || boost > BOOST_MAX)
+        return `Boost must be between ${BOOST_MIN} and ${BOOST_MAX}, got ${boost}`;
+    return null;
+}
+export function audioBoostDef(engine) {
+    return {
+        name: "audio_boost",
+        description: "Boost audio volume of a video or audio asset using a linear multiplier (1.0–4.0). Operates in-place with git versioning.",
+        schema: {
+            asset_id: z.string().describe("Video or audio artifact id"),
+            book_id: z.string().describe("Book UUID"),
+            boost: z.number().describe("Volume multiplier (1.0–4.0). >1 = louder."),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id, boost } = args;
+            const boostError = validateBoost(boost);
+            if (boostError) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: boostError }],
+                };
+            }
+            const artifactResult = engine.artifacts.get(asset_id);
+            if (!artifactResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: artifactResult.error.message }],
+                };
+            }
+            const isVideo = artifactResult.value.kind === "video";
+            const isAudio = artifactResult.value.kind === "audio";
+            if (!isVideo && !isAudio) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `audio_boost only supports video or audio artifacts, got ${artifactResult.value.kind} artifact ${asset_id}`,
+                        }],
+                };
+            }
+            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 file = isVideo
+                ? findVideoFile(manifest.files)
+                : findAudioFile(manifest.files, artifactResult.value.kind);
+            if (!file) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `No ${isVideo ? "video" : "audio"} file found in asset ${asset_id}`,
+                        }],
+                };
+            }
+            const assetDir = manifest.path;
+            const inputPath = join(assetDir, file.name);
+            try {
+                const source = await probeVideo(inputPath);
+                if (!source.hasAudio)
+                    throw new Error("Source has no playable audio stream");
+                if (isVideo)
+                    videoAudioOutputOptions(inputPath);
+                else
+                    audioOnlyOutputOptions(inputPath);
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+            }
+            const ext = extname(file.name) || (isVideo ? ".mp4" : ".mp3");
+            const tempPath = join(assetDir, `boost_pending${ext}`);
+            const jobId = `boost-${asset_id}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "audio_boost",
+                inputPath,
+                outputPath: tempPath,
+                boost,
+                isVideo,
+                assetId: asset_id,
+                assetDir,
+                bookId: book_id,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ asset_id, job_id: jobId, status: "enqueued" }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/audio-mix.js

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { findAudioFile, findVideoFile, } from "videobook-engine";
+import { z } from "zod";
+import { audioOnlyOutputOptions, videoAudioOutputOptions } from "../audio-encoding.js";
+import { probeVideo } from "../ffmpeg.js";
+import { queue } from "../queue.js";
+function toolError(message) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+    };
+}
+function normalizeAssetId(assetId) {
+    return assetId.trim().replace(/^@/, "");
+}
+function findMediaFile(files, kind) {
+    return kind === "video"
+        ? findVideoFile(files)
+        : findAudioFile(files, kind);
+}
+export async function resolveAudioMixAsset(engine, assetIdInput) {
+    const assetId = normalizeAssetId(assetIdInput);
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    if (artifact.value.kind !== "video" && artifact.value.kind !== "audio") {
+        throw new Error(`Audio mix artifacts must be video or audio, got ${artifact.value.kind} artifact ${assetId}`);
+    }
+    const kind = artifact.value.kind;
+    const manifestResult = await engine.files.manifest(assetId);
+    if (!manifestResult.ok)
+        throw new Error(manifestResult.error.message);
+    const file = findMediaFile(manifestResult.value.files, kind);
+    if (!file) {
+        throw new Error(`No ${kind} file found in artifact ${assetId}`);
+    }
+    return {
+        assetId,
+        kind,
+        assetDir: manifestResult.value.path,
+        filename: file.name,
+        path: join(manifestResult.value.path, file.name),
+    };
+}
+export function audioMixDef(engine) {
+    return {
+        name: "audio_mix",
+        description: "Mix a video or audio layer asset into a target video or audio asset in place, starting at 0 seconds at volume 0-100; the target keeps its duration and picture.",
+        schema: {
+            target_asset_id: z.string().describe("Artifact id to edit in-place (video or audio)"),
+            layer_asset_id: z.string().describe("Artifact whose audio is layered onto the target (video or audio artifact id)"),
+            volume: z.number().min(0).max(100).describe("Layer volume percentage from 0 to 100"),
+            book_id: z.string().describe("Book UUID"),
+        },
+        handler: async (args) => {
+            const { target_asset_id, layer_asset_id, volume, book_id } = args;
+            let target;
+            let layer;
+            try {
+                [target, layer] = await Promise.all([
+                    resolveAudioMixAsset(engine, target_asset_id),
+                    resolveAudioMixAsset(engine, layer_asset_id),
+                ]);
+                const [targetProbe, layerProbe] = await Promise.all([
+                    probeVideo(target.path),
+                    probeVideo(layer.path),
+                ]);
+                if (!layerProbe.hasAudio || (layerProbe.audioDuration ?? layerProbe.duration) <= 0) {
+                    throw new Error("Layer asset has no playable audio stream");
+                }
+                if (target.kind === "video") {
+                    if (!targetProbe.videoStream || targetProbe.videoDuration <= 0) {
+                        throw new Error("Video target has no playable video stream");
+                    }
+                    videoAudioOutputOptions(target.filename);
+                }
+                else {
+                    if (!targetProbe.hasAudio || (targetProbe.audioDuration ?? targetProbe.duration) <= 0) {
+                        throw new Error("Audio target has no playable audio stream");
+                    }
+                    audioOnlyOutputOptions(target.filename);
+                }
+            }
+            catch (error) {
+                return toolError(error instanceof Error ? error.message : String(error));
+            }
+            const token = randomUUID();
+            const jobId = `audio-mix-${target.assetId}-${token}`;
+            try {
+                await queue.enqueueAndWait(jobId, {
+                    type: "audio_mix",
+                    targetPath: target.path,
+                    targetFilename: target.filename,
+                    targetKind: target.kind,
+                    layerPath: layer.path,
+                    layerAssetId: layer.assetId,
+                    volume,
+                    assetId: target.assetId,
+                    assetDir: target.assetDir,
+                    bookId: book_id,
+                }, 1_800_000);
+            }
+            catch (error) {
+                return toolError(`Audio mix failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            target_asset_id: target.assetId,
+                            layer_asset_id: layer.assetId,
+                            volume,
+                            job_id: jobId,
+                            status: "completed",
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/book-usage.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { settleFinishedUsage, usageIncomplete } from "../provider-usage.js";
+export function bookUsageDef(engine) {
+    return {
+        name: "get_book_usage",
+        description: "Read recorded provider tokens and USD cost for this book, with estimated and unavailable prices, activity/model breakdowns, and the latest 20 requests. Tracking starts when usage recording is enabled for this book.",
+        schema: { book_id: z.string().uuid() },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        handler: async () => {
+            await settleFinishedUsage(engine);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ...engine.usage.summary(), recent: engine.usage.recent(), incomplete: usageIncomplete(engine) }) }],
+            };
+        },
+    };
+}