videobook 0.0.0-stage → 0.2.0

package/dist/jobs/complete-provider-task.js

@@ -0,0 +1,185 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { writeFile, unlink, readFile as readFsFile } from "node:fs/promises";
+import { logger } from "../logger.js";
+import { registerJobHandler } from "../queue.js";
+import { runFfmpeg } from "../ffmpeg.js";
+import { completeMediaGeneration, providerResultUrls } from "../media/complete.js";
+import { MEDIA_TASK_TYPES } from "../media/adapters/types.js";
+import { legacyMediaForTaskType, legacyMediaMeta } from "../media/legacy-task-types.js";
+const LOCK_DURATION_MS = 300_000;
+const TASK_TYPES_BY_COMPLETION_FAMILY = {
+    isolateVocals: ["isolate_vocals"],
+    media: Object.values(MEDIA_TASK_TYPES),
+};
+const COMPLETION_FAMILY_BY_TASK_TYPE = new Map(Object.entries(TASK_TYPES_BY_COMPLETION_FAMILY).flatMap(([family, taskTypes]) => taskTypes.map((taskType) => [taskType, family])));
+export function completionFamilyForTaskType(taskType) {
+    return COMPLETION_FAMILY_BY_TASK_TYPE.get(taskType)
+        ?? (legacyMediaForTaskType(taskType) ? "media" : undefined);
+}
+async function reclaimFailedCompletion(engine, task, ctx) {
+    const { assetId, taskId, taskType, meta } = task;
+    const failure = engine.jobs.failures.read(assetId);
+    if (!failure.ok || !failure.value)
+        return null;
+    const pending = engine.jobs.pending.read(assetId);
+    if (!pending.ok || pending.value)
+        return null;
+    const cleared = await engine.jobs.failures.clear(assetId);
+    if (!cleared.ok || !cleared.value)
+        return null;
+    const lease = engine.jobs.artifactWork.begin(assetId, {
+        kind: "generate",
+        ownerKind: "job",
+        durationMs: LOCK_DURATION_MS,
+    });
+    if (!lease)
+        throw new Error(`Could not re-claim ${assetId} to retry its completion`);
+    ctx.setLease({ kind: "owner", ownerId: lease.ownerId });
+    const written = await engine.jobs.pending.write({ artifactId: assetId, taskId, taskType, meta }, lease.ownerId);
+    if (!written.ok) {
+        throw new Error(`Failed to re-register provider task ${taskId} for ${assetId}: ${written.error.message}`);
+    }
+    if (written.value === null) {
+        throw new Error(`Lost the lease on ${assetId} while re-registering provider task ${taskId}`);
+    }
+    return lease.ownerId;
+}
+export function registerCompleteProviderTaskJob(engine) {
+    registerJobHandler("complete_kie_task", async (payload, ctx) => {
+        const { taskId, taskType, assetId, bookId, meta, resultUrls, resultObject, } = payload;
+        // Pattern C: inherit the provider lease via getOwner, abort if the row
+        // already terminated, and register the lease so the wrapper's catch path
+        // CAS-fails by task_id (unaffected by a fresh retry on the same asset).
+        // A row that was failed by an earlier completion attempt is re-claimed
+        // instead, so retrying the job after the cause is fixed finishes the
+        // asset rather than silently skipping it.
+        const ownerId = engine.jobs.pending.getOwner(assetId, taskId)
+            ?? await reclaimFailedCompletion(engine, { assetId, taskId, taskType, meta }, ctx);
+        if (!ownerId) {
+            // The row was already removed by a delete or a stale duplicate
+            // dispatch. Either way the task is no longer ours to complete.
+            return { success: true, skipped: true };
+        }
+        ctx.setLease({ kind: "task", taskId });
+        const completionFamily = completionFamilyForTaskType(taskType);
+        if (!completionFamily) {
+            throw new Error(`Unhandled provider task type: ${taskType}`);
+        }
+        // Resolve the asset directory at runtime so renames don't break completion.
+        const assetDirResult = await engine.workspaces.resolveArtifact(assetId);
+        if (!assetDirResult.ok) {
+            await engine.jobs.pending.delete(assetId, taskId);
+            return { success: true, skipped: true };
+        }
+        const assetDir = assetDirResult.value;
+        const lockState = taskType === "isolate_vocals" ? "isolating" : "generating";
+        const lockResult = await engine.jobs.locks.acquire(assetDir, { durationMs: LOCK_DURATION_MS, data: { state: lockState } });
+        if (!lockResult.ok) {
+            // LOCKED means another completion job for this same asset is already
+            // running (sync can enqueue duplicates between polls because
+            // the provider task remains pending until the completion job finishes).
+            // Treat as a no-op — the other job will finish the work.
+            if (lockResult.error.code === "LOCKED") {
+                return { success: true, skipped: true };
+            }
+            throw new Error(`Asset is locked: ${lockResult.error.message}`);
+        }
+        // Renew the provider lease while we work — covers downloads + processing.
+        const heartbeat = setInterval(() => {
+            try {
+                engine.jobs.artifactWork.renew(assetId, ownerId, 60_000);
+            }
+            catch (error) {
+                logger.warn("heartbeat-failed", { assetId, error });
+            }
+        }, 20_000);
+        const urls = completionFamily === "media"
+            ? providerResultUrls(resultUrls, resultObject)
+            : resultUrls;
+        try {
+            switch (completionFamily) {
+                case "isolateVocals":
+                    await completeIsolateVocals(engine, assetId, meta, urls);
+                    break;
+                case "media":
+                    await completeMediaGeneration({
+                        engine,
+                        assetId,
+                        assetDir,
+                        bookId,
+                        meta: legacyMediaMeta(taskType, meta),
+                        outputs: urls.map((url) => ({ url })),
+                    });
+                    break;
+                default: {
+                    const unhandledFamily = completionFamily;
+                    throw new Error(`Unhandled provider completion family: ${unhandledFamily}`);
+                }
+            }
+            await engine.jobs.pending.delete(assetId, taskId);
+            return { success: true };
+        }
+        finally {
+            clearInterval(heartbeat);
+            await engine.jobs.locks.release(assetDir);
+        }
+    });
+}
+async function completeIsolateVocals(engine, assetId, meta, resultUrls) {
+    const vocalsUrl = resultUrls[0];
+    if (!vocalsUrl)
+        throw new Error("No vocals URL in result");
+    const response = await fetch(vocalsUrl);
+    if (!response.ok)
+        throw new Error(`Failed to download vocals: ${response.status} ${response.statusText}`);
+    let vocalsBuffer = Buffer.from(await response.arrayBuffer());
+    // Trim back to original duration if audio was padded before upload
+    const originalDuration = meta.originalDuration;
+    if (originalDuration !== undefined) {
+        const tmpIn = join(tmpdir(), `isolate-trim-in-${Date.now()}.mp3`);
+        const tmpOut = join(tmpdir(), `isolate-trim-out-${Date.now()}.mp3`);
+        try {
+            await writeFile(tmpIn, vocalsBuffer);
+            await runFfmpeg(["-y", "-i", tmpIn, "-t", String(originalDuration), tmpOut]);
+            vocalsBuffer = await readFsFile(tmpOut);
+        }
+        finally {
+            await unlink(tmpIn).catch(() => { });
+            await unlink(tmpOut).catch(() => { });
+        }
+    }
+    const isAudioAsset = meta.isAudioAsset;
+    if (isAudioAsset) {
+        // Audio assets: write mix.mp3 and .mix.json
+        await engine.files.write(assetId, "mix.mp3", vocalsBuffer);
+        const mixSettings = { volume: 100, fadeIn: 0, fadeOut: 0 };
+        await engine.files.write(assetId, ".mix.json", JSON.stringify(mixSettings, null, 2));
+    }
+    else {
+        // Video assets: write audio_vocals.mp3
+        await engine.files.write(assetId, "audio_vocals.mp3", vocalsBuffer);
+        // Optionally write background audio if a second URL exists
+        if (resultUrls[1]) {
+            const bgResponse = await fetch(resultUrls[1]);
+            if (bgResponse.ok) {
+                let bgBuffer = Buffer.from(await bgResponse.arrayBuffer());
+                if (originalDuration !== undefined) {
+                    const tmpBgIn = join(tmpdir(), `isolate-bg-in-${Date.now()}.mp3`);
+                    const tmpBgOut = join(tmpdir(), `isolate-bg-out-${Date.now()}.mp3`);
+                    try {
+                        await writeFile(tmpBgIn, bgBuffer);
+                        await runFfmpeg(["-y", "-i", tmpBgIn, "-t", String(originalDuration), tmpBgOut]);
+                        bgBuffer = await readFsFile(tmpBgOut);
+                    }
+                    finally {
+                        await unlink(tmpBgIn).catch(() => { });
+                        await unlink(tmpBgOut).catch(() => { });
+                    }
+                }
+                await engine.files.write(assetId, "audio_background.mp3", bgBuffer);
+            }
+        }
+    }
+    await engine.history.recordOperation("isolate_vocals", assetId, { mode: "cloud" });
+}

package/dist/jobs/copy-library-asset.js

@@ -0,0 +1,33 @@
+import { copyAndAttachLibraryAsset, copyLibraryAsset, } from "../media-library.js";
+import { registerJobHandler } from "../queue.js";
+function requiredString(payload, key) {
+    const value = payload[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`copy_library_asset requires ${key}`);
+    }
+    return value;
+}
+export function registerCopyLibraryAssetJob(books) {
+    registerJobHandler("copy_library_asset", async (payload) => {
+        const input = {
+            sourceBookId: requiredString(payload, "sourceBookId"),
+            sourceArtifactId: requiredString(payload, "sourceArtifactId"),
+            targetBookId: requiredString(payload, "targetBookId"),
+            ...(typeof payload.newName === "string"
+                ? { newName: payload.newName }
+                : {}),
+        };
+        if (typeof payload.notebookId !== "string"
+            || typeof payload.cellId !== "string") {
+            return await copyLibraryAsset(books, input);
+        }
+        return await copyAndAttachLibraryAsset(books, {
+            ...input,
+            notebookId: payload.notebookId,
+            cellId: payload.cellId,
+            expectedOutputArtifactId: typeof payload.expectedOutputArtifactId === "string"
+                ? payload.expectedOutputArtifactId
+                : null,
+        });
+    });
+}

package/dist/jobs/cost-estimate-assessment.js

@@ -0,0 +1,113 @@
+import { computeEstimate } from "@apicity/cost";
+import { logger } from "../logger.js";
+import { appendDiagnostic, diagnosticRecord } from "../diagnostics.js";
+import { estimateCostDef } from "../tools/estimate-cost.js";
+function toUpstreamCostHints(hints) {
+    return {
+        ...(typeof hints.duration === "number" && hints.duration > 0 ? { durationSeconds: hints.duration } : {}),
+        ...(typeof hints.inputDuration === "number" && hints.inputDuration > 0 ? { inputDurationSeconds: hints.inputDuration } : {}),
+    };
+}
+function assessComputedEstimate(estimate) {
+    const warnings = estimate.warnings.filter((warning) => typeof warning === "string" && warning.length > 0);
+    if (estimate.usd > 0) {
+        return { available: true, usd: estimate.usd, warnings };
+    }
+    if (warnings.length === 0 && estimate.usd === 0) {
+        return { available: true, usd: 0, warnings };
+    }
+    return {
+        available: false,
+        usd: estimate.usd,
+        warnings,
+        reason: classifyUnavailable(warnings, estimate.usd),
+    };
+}
+export function assessBestEffortEstimate(compute) {
+    try {
+        return assessComputedEstimate(compute());
+    }
+    catch {
+        return {
+            available: false,
+            warnings: [],
+            reason: "estimator-threw",
+        };
+    }
+}
+export function assessKieRequestEstimate(request, costHints = {}) {
+    return assessBestEffortEstimate(() => computeEstimate({
+        provider: "kie",
+        payload: request,
+        costHints: toUpstreamCostHints(costHints),
+    }));
+}
+export async function assessToolCallEstimate(engine, tool, input) {
+    try {
+        const result = await estimateCostDef(engine).handler({
+            calls: [{ tool_name: tool, input }],
+        });
+        if (result.isError) {
+            return {
+                available: false,
+                warnings: [],
+                reason: "estimate-error",
+            };
+        }
+        const text = result.content.find((item) => item.type === "text")?.text;
+        const parsed = text
+            ? JSON.parse(text)
+            : {};
+        const warnings = Array.isArray(parsed.estimate?.warnings)
+            ? parsed.estimate.warnings.filter((warning) => typeof warning === "string")
+            : [];
+        const usd = typeof parsed.estimate?.usd === "number"
+            ? parsed.estimate.usd
+            : undefined;
+        if (usd === undefined) {
+            return {
+                available: false,
+                warnings,
+                reason: classifyUnavailable(warnings, usd),
+            };
+        }
+        return assessComputedEstimate({ usd, warnings });
+    }
+    catch {
+        return {
+            available: false,
+            warnings: [],
+            reason: "estimator-threw",
+        };
+    }
+}
+export function sanitizedCostEstimateLog(input) {
+    return diagnosticRecord("generation-cost-estimate", {
+        ...input.correlation,
+        available: input.assessment.available,
+        ...(input.assessment.available ? {} : { reason: input.assessment.reason }),
+        warningCount: input.assessment.warnings.length,
+    });
+}
+export async function logUnavailableCostEstimate(input) {
+    if (input.assessment.available)
+        return;
+    const line = sanitizedCostEstimateLog(input);
+    logger.warn("generation-cost-estimate", line);
+    if (!input.engine)
+        return;
+    await appendDiagnostic(input.engine, "generation-cost-estimate", line).catch(() => undefined);
+}
+function classifyUnavailable(warnings, usd) {
+    const text = warnings.join(" ").toLowerCase();
+    if (/no cost adapter/.test(text))
+        return "missing-adapter";
+    if (/not found in pricing table/.test(text) || /model '.+' not found/.test(text)) {
+        return "missing-rates";
+    }
+    if (/selector|variant '/.test(text))
+        return "missing-selector";
+    if (usd === 0)
+        return "zero";
+    return "unbounded";
+}

package/dist/jobs/crop-image.js

@@ -0,0 +1,47 @@
+import { registerJobHandler, queue } from "../queue.js";
+import { cropRegion, probeImage } from "../image.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { cropGeometry } from "../crop-geometry.js";
+const LOCK_DURATION_MS = 300_000;
+export function registerCropImageJob(engine) {
+    registerJobHandler("crop_image", async (payload, ctx) => {
+        const { inputFilename, ratio, rect, assetId, assetDir, bookId, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "crop", { durationMs: LOCK_DURATION_MS, data: { state: "cropping", ratio } }, async () => {
+            const readResult = await engine.files.read(assetId, inputFilename);
+            if (!readResult.ok) {
+                throw new Error(`Failed to read ${inputFilename}: ${readResult.error.message}`);
+            }
+            const buffer = Buffer.isBuffer(readResult.value)
+                ? readResult.value
+                : Buffer.from(readResult.value);
+            const src = await probeImage(buffer);
+            if (!src.width || !src.height) {
+                throw new Error(`Could not probe source dimensions for ${inputFilename}`);
+            }
+            const { outW, outH } = cropGeometry(rect, src.width, src.height, ratio, 1);
+            const cropped = await cropRegion(buffer, rect, outW, outH);
+            const out = await probeImage(cropped);
+            if (out.width !== outW || out.height !== outH) {
+                throw new Error(`Crop output dimensions ${out.width}x${out.height} do not match canonical ${outW}x${outH}`);
+            }
+            const finalFilename = "original.jpg";
+            const writeResult = await engine.files.write(assetId, finalFilename, cropped);
+            if (!writeResult.ok) {
+                throw new Error(`Failed to write cropped image: ${writeResult.error.message}`);
+            }
+            // Drop the previous original when it was a different filename (e.g. original.png).
+            if (inputFilename !== finalFilename) {
+                await engine.files.delete(assetId, inputFilename);
+            }
+            return { extension: ".jpg" };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        await queue.enqueueAndWait(`process-image-${assetId}-${Date.now()}`, {
+            type: "process_image",
+            assetId,
+            bookId,
+            extension: result.extension,
+            provenance: { origin: "crop", ratio, cropped_at: new Date().toISOString() },
+        });
+        return { success: true };
+    });
+}

package/dist/jobs/crop-video.js

@@ -0,0 +1,71 @@
+import { rm } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { registerJobHandler, queue } from "../queue.js";
+import { runFfmpeg, probeVideo, H264_MEDIUM, AUDIO_OPTS } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+import { cropGeometry } from "../crop-geometry.js";
+const LOCK_DURATION_MS = 300_000;
+export function registerCropVideoJob(engine) {
+    registerJobHandler("crop_video", async (payload, ctx) => {
+        const { inputPath, outputPath, ratio, rect, assetId, assetDir, bookId, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "crop", { durationMs: LOCK_DURATION_MS, data: { state: "cropping", ratio } }, async () => {
+            const src = await probeVideo(inputPath);
+            if (!src.width || !src.height) {
+                throw new Error(`Could not probe source dimensions for ${inputPath}`);
+            }
+            const { cropX, cropY, cropW, cropH, outW, outH } = cropGeometry(rect, src.width, src.height, ratio, 2);
+            const vf = `crop=${cropW}:${cropH}:${cropX}:${cropY},` +
+                `scale=${outW}:${outH}:flags=lanczos,setsar=1`;
+            const args = [
+                "-y", "-i", inputPath,
+                "-vf", vf,
+                ...H264_MEDIUM,
+                ...(src.hasAudio ? AUDIO_OPTS : ["-an"]),
+                "-movflags", "+faststart",
+                outputPath,
+            ];
+            try {
+                await runFfmpeg(args);
+            }
+            catch (err) {
+                await rm(outputPath, { force: true });
+                throw err;
+            }
+            try {
+                const out = await probeVideo(outputPath);
+                if (out.width !== outW || out.height !== outH) {
+                    throw new Error(`Crop output dimensions ${out.width}x${out.height} do not match canonical ${outW}x${outH}`);
+                }
+                if (!(out.duration > 0)) {
+                    throw new Error(`Crop output has zero duration`);
+                }
+            }
+            catch (err) {
+                await rm(outputPath, { force: true });
+                throw err;
+            }
+            const inputFilename = basename(inputPath);
+            await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+            for (const stale of [
+                ".original.analysis.json",
+                ".analysis.gpt4otrans.json",
+                "elevenlabs.json",
+            ]) {
+                await engine.files.delete(assetId, stale);
+            }
+            const videoPath = join(assetDir, inputFilename);
+            return { videoPath };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        await queue.enqueue(`process-video-${assetId}-${Date.now()}`, {
+            type: "process_video",
+            videoPath: result.videoPath,
+            assetId,
+            assetDir,
+            bookId,
+            provenance: { origin: "crop", ratio, cropped_at: new Date().toISOString() },
+            force: true,
+        });
+        return { success: true };
+    });
+}

package/dist/jobs/describe-image.js

@@ -0,0 +1,181 @@
+import { join, dirname, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+import { logger } from "../logger.js";
+import { registerJobHandler } from "../queue.js";
+import { MAX_AUTOMATIC_TAGS, frameVocabularyFor } from "../tag-vocabulary.js";
+import { requireApiKey } from "../api-key.js";
+import { withLocalLease } from "./_lease.js";
+import { enqueueAssetTagging } from "./tag-asset.js";
+import { INTELLIGENCE_MODEL, buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GUIDE_PATH = join(__dirname, "../guides/image_reproduction_guide.md");
+export const SCRIPT_FILENAME = "original.md";
+export const ANALYSIS_FILENAME = ".original.analysis.json";
+const VISION_MODEL = INTELLIGENCE_MODEL;
+export const PROMPT_CHAR_LIMIT = 1900;
+const DESCRIBE_IMAGE_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        prompt: { type: "string", maxLength: PROMPT_CHAR_LIMIT },
+        shot: { type: "string" },
+        pose: { type: "string" },
+        tags: {
+            type: "array",
+            maxItems: MAX_AUTOMATIC_TAGS,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    facet: { type: "string", enum: ["people", "places", "editing"] },
+                    label: { type: "string" },
+                },
+                required: ["facet", "label"],
+            },
+        },
+    },
+    required: ["prompt", "shot", "pose", "tags"],
+};
+/**
+ * The tagging half of the instructions. The prompt half describes how to
+ * reproduce the image; this half describes how to file it. Offering the
+ * vocabulary inline is what makes separate clips converge on one spelling —
+ * anything outside it is discarded on the way in, so asking for invented
+ * terms would only waste tokens.
+ */
+function buildTaggingPrompt() {
+    return ("\n\nTAGS: also return a \"tags\" array of {facet, label} records that help an editor "
+        + "find and group this image with related footage. Emit a tag only when the image itself "
+        + "supports it, prefer few precise tags over many, and return an empty array when nothing "
+        + "is worth grouping by. Never tag how good or how moody the image looks, and never name a "
+        + "real person or a real place.\n"
+        + `- facet "people" — one of: ${frameVocabularyFor("people").join(", ")}.\n`
+        + `- facet "places" — the setting, plus interior/exterior and day/night when visible. `
+        + `Common settings: ${frameVocabularyFor("places").join(", ")}. A concrete unlisted setting is fine.\n`
+        + `- facet "editing" — framing and coverage only: ${frameVocabularyFor("editing").join(", ")}. `
+        + "A still image cannot show camera movement, so never claim pan, tilt, tracking or handheld.");
+}
+function mimeForFilename(filename) {
+    const ext = extname(filename).replace(/^\./, "").toLowerCase();
+    if (ext === "png")
+        return "image/png";
+    if (ext === "webp")
+        return "image/webp";
+    return "image/jpeg";
+}
+function buildSystemPrompt(guide) {
+    return ("You are an expert image-to-prompt analyst. You look at an image and emit a reproduction-ready prompt " +
+        "for an image generator. Follow the guide below exactly. Return ONLY a JSON object matching the schema " +
+        "described in the guide. Do not wrap it in prose or markdown fences.\n\n" +
+        `HARD LIMIT: the "prompt" field MUST be ${PROMPT_CHAR_LIMIT} characters or fewer. Trim detail to fit; never exceed.\n\n` +
+        "REGISTER: If the image reads as a casual phone/social snapshot (candid framing, available light, " +
+        "unretouched skin, compression artifacts), use the Authentic-photo register from the guide. Do not " +
+        "inject editorial film-stock, 'cinematic', 'masterpiece', or pro-film vocabulary into snapshots. " +
+        "Default to authentic phone capture when in doubt.\n\n" +
+        `--- REPRODUCTION GUIDE ---\n${guide}\n--- END GUIDE ---`
+        + buildTaggingPrompt());
+}
+export function formatMarkdown(r) {
+    const lines = [];
+    lines.push(r.prompt.trim(), "");
+    const rows = [
+        ["Shot", r.shot],
+        ["Pose", r.pose],
+    ];
+    for (const [label, value] of rows) {
+        if (value && value.trim()) {
+            lines.push(`${label}: ${value.trim()}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function mimeForImageFilename(filename) {
+    return mimeForFilename(filename);
+}
+function buildResponses(apiKey) {
+    return buildIntelligenceResponses(apiKey);
+}
+export async function describeImageBytes(bytes, mime, responses) {
+    const fn = responses ?? buildResponses(requireApiKey("OPENAI_API_KEY"));
+    const guide = await readFile(GUIDE_PATH, "utf-8");
+    const dataUrl = `data:${mime};base64,${bytes.toString("base64")}`;
+    const response = await fn(intelligenceRequest({
+        instructions: buildSystemPrompt(guide),
+        input: [{
+                role: "user",
+                content: [
+                    { type: "input_image", image_url: dataUrl, detail: "high" },
+                    { type: "input_text", text: "Analyze this image and produce the reproduction prompt as a JSON object matching the schema in the guide." },
+                ],
+            }],
+        text: {
+            format: {
+                type: "json_schema",
+                name: "image_reproduction",
+                schema: DESCRIBE_IMAGE_SCHEMA,
+                strict: true,
+            },
+        },
+        max_output_tokens: 2048,
+    }));
+    const content = firstResponseText(response);
+    if (!content) {
+        throw new Error(`Vision provider returned no content (status=${response.status})`);
+    }
+    const parsed = JSON.parse(content);
+    if (!parsed.prompt || typeof parsed.prompt !== "string") {
+        throw new Error(`Vision model returned no prompt field. Got keys: ${Object.keys(parsed).join(",")}`);
+    }
+    if (parsed.prompt.length > PROMPT_CHAR_LIMIT) {
+        logger.warn("description-truncated", { count: parsed.prompt.length, limit: PROMPT_CHAR_LIMIT });
+        parsed.prompt = parsed.prompt.slice(0, PROMPT_CHAR_LIMIT).trimEnd();
+    }
+    return parsed;
+}
+export function registerDescribeImageJob(engine) {
+    registerJobHandler("describe_image", async (payload, ctx) => {
+        const { sourceAssetId, sourceImageFilename, assetId: scriptAssetId, } = payload;
+        // When scriptAssetId is set, the queue wrote a pending row on it; claim
+        // the lease so the wrapper finalizes it (ready/error). Analysis-only
+        // mode runs on the source asset, which already exists at status='ready'.
+        const targetAssetId = scriptAssetId ?? sourceAssetId;
+        return withLocalLease(engine, targetAssetId, ctx, "describe", async () => {
+            const responses = buildResponses(requireApiKey("OPENAI_API_KEY"));
+            const readResult = await engine.files.read(sourceAssetId, sourceImageFilename);
+            if (!readResult.ok) {
+                throw new Error(`Failed to read image ${sourceImageFilename} for ${sourceAssetId}: ${readResult.error.message}`);
+            }
+            const buffer = Buffer.from(readResult.value);
+            const mime = mimeForFilename(sourceImageFilename);
+            const parsed = await describeImageBytes(buffer, mime, responses);
+            const analysisJson = JSON.stringify(parsed, null, 2);
+            const cacheResult = await engine.files.write(sourceAssetId, ANALYSIS_FILENAME, analysisJson);
+            if (!cacheResult.ok) {
+                if (cacheResult.error.code === "NOT_FOUND") {
+                    return { success: false, sourceAssetId, scriptAssetId, reason: "source_deleted" };
+                }
+                logger.warn("description-cache-failed", { assetId: sourceAssetId, error: cacheResult.error });
+            }
+            // The structured tags rode along with the prompt, so tagging is now a
+            // read of what this request already returned.
+            await enqueueAssetTagging(engine, sourceAssetId);
+            if (scriptAssetId) {
+                const markdown = formatMarkdown(parsed);
+                const writeResult = await engine.files.write(scriptAssetId, SCRIPT_FILENAME, markdown);
+                if (!writeResult.ok) {
+                    throw new Error(`Failed to write ${SCRIPT_FILENAME} to ${scriptAssetId}: ${writeResult.error.message}`);
+                }
+                await engine.metadata.artifacts.write(scriptAssetId, "original", {
+                    origin: "describe_image",
+                    sourceAssetId,
+                    model: VISION_MODEL,
+                    processed_at: new Date().toISOString(),
+                    variant: "full",
+                });
+            }
+            return { success: true, sourceAssetId, scriptAssetId, prompt: parsed.prompt };
+        });
+    });
+}

package/dist/jobs/detect-scenes.js

@@ -0,0 +1,33 @@
+import { findVideoFile } from "videobook-engine";
+import { join } from "node:path";
+import { registerJobHandler } from "../queue.js";
+import { withLocalLease } from "./_lease.js";
+import { detectSceneCandidates } from "../scene-detect.js";
+export function registerDetectScenesJob(engine) {
+    registerJobHandler("detect_scenes", async (payload, ctx) => {
+        const { assetId } = payload;
+        return withLocalLease(engine, assetId, ctx, "analyze", async () => {
+            const manifestResult = await engine.files.manifest(assetId);
+            if (!manifestResult.ok)
+                throw new Error(manifestResult.error.message);
+            const videoFile = findVideoFile(manifestResult.value.files);
+            if (!videoFile)
+                throw new Error(`No video file found in asset ${assetId}`);
+            const candidates = await detectSceneCandidates(join(manifestResult.value.path, videoFile.name));
+            const shots = candidates.filter((c) => c.kind === "shot").length;
+            const settles = candidates.filter((c) => c.kind === "settle").length;
+            const final = {
+                asset_id: assetId,
+                count: candidates.length,
+                shots,
+                settles,
+                candidates,
+            };
+            const writeResult = await engine.files.write(assetId, ".detect-scenes.json", JSON.stringify(final, null, 2));
+            if (!writeResult.ok) {
+                throw new Error(`Scenes detected but failed to persist: ${writeResult.error.message}`);
+            }
+            return { success: true, count: candidates.length, shots, settles };
+        });
+    });
+}