videobook 0.0.0-stage → 0.2.0

package/dist/tools/rewrite-prompt.js

@@ -0,0 +1,388 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { textPart, imageUrlPart } from "@apicity/openai";
+import { modelEntry } from "../media/catalog.js";
+import { platformGuidance } from "../platform-guidance.js";
+import { expandTimelineSlotRefs, timelineSlotArtifactIds } from "../timeline-helpers.js";
+import { resolveArtifactRefs } from "../artifact-refs.js";
+import { buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GUIDES_DIR = join(__dirname, "../guides");
+const GUIDE_FILES = {
+    nano_banana: "nano_banana_pro_prompting_guide.md",
+    gpt_image: "gpt_image_2_5_prompting_guide.md",
+    kling30: "kling_3_0_prompting_guide.md",
+    grok_imagine: "grok_imagine_prompting_guide.md",
+    grok_image: "grok_imagine_prompting_guide.md",
+    seedance2: "seedance_2_prompting_guide.md",
+    seedance25: "seedance_2_prompting_guide.md",
+};
+const SUPPORTED_MODELS = Object.keys(GUIDE_FILES).sort();
+// --- Pure helpers ---
+export function loadGuide(model) {
+    const filename = GUIDE_FILES[model];
+    if (!filename) {
+        throw new Error(`No prompting guide available for model: ${model}. Supported models: ${SUPPORTED_MODELS.join(", ")}`);
+    }
+    return readFile(join(GUIDES_DIR, filename), "utf-8");
+}
+function guideFilename(model) {
+    return GUIDE_FILES[model] ?? "";
+}
+const IMAGE_CLEANUP_DIRECTIVE = "IMAGE CLEANUP: The reference image(s) may contain AI-generation artifacts " +
+    "(plasticky skin, oversharpened or haloed edges, waxy textures, mushy background detail) " +
+    "or low-resolution noise (blocking, chroma banding, jpeg ringing). Describe the intended " +
+    "subject/scene rather than replicating these artifacts. Produce a prompt that guides the " +
+    "target model to render the scene cleanly at full fidelity, honoring the platform aesthetic above.";
+function previousErrorSection(error) {
+    const failCodeLine = error.failCode
+        ? `Provider fail code: ${error.failCode}\n`
+        : "";
+    return ("\n--- PREVIOUS GENERATION ERROR ---\n" +
+        "A previous generation attempt with this exact prompt FAILED with the provider error below.\n" +
+        failCodeLine +
+        `Error message: ${error.message}\n` +
+        "Rework the prompt so it will not trigger this failure again, while preserving the creative intent:\n" +
+        "- Infer which element of the prompt (or its references) most plausibly triggered the error and rewrite or generalize that element (e.g. a PROMINENT_PEOPLE / celebrity-likeness filter -> describe a generic fictional person; a sensitive-content filter -> reframe or tone down the flagged concept)\n" +
+        "- Keep every part of the prompt unrelated to the failure intact in spirit\n" +
+        "- Do NOT mention the error, the filter, the provider, or these instructions in the rewritten prompt text\n" +
+        "--- END PREVIOUS GENERATION ERROR ---\n");
+}
+export function buildRewritePromptText(guide, prompt, extras = {}) {
+    const { maxChars, platform, customPrompt, hasImages, previousError } = extras;
+    let charLimitRule = "";
+    if (maxChars) {
+        charLimitRule =
+            `- HARD LIMIT: The rewritten prompt MUST be under ${maxChars} characters (API max is 500)\n` +
+                "- Be concise and visually specific — cut filler words, focus on key actions and details\n";
+    }
+    const platformSection = platform
+        ? `\n--- PLATFORM STYLE ---\n${platformGuidance(platform)}\n--- END PLATFORM STYLE ---\n` +
+            (hasImages ? `\n${IMAGE_CLEANUP_DIRECTIVE}\n` : "")
+        : "";
+    const instructionSection = customPrompt
+        ? `\nADDITIONAL INSTRUCTION: ${customPrompt}\n`
+        : "";
+    const errorSection = previousError ? previousErrorSection(previousError) : "";
+    const userPromptBlock = prompt
+        ? `USER PROMPT TO REWRITE:\n${prompt}`
+        : "USER PROMPT TO REWRITE: (none — describe the reference image(s) directly, applying the guide above)";
+    return ("You are a prompt engineering expert. Using the model-specific prompting guide below, " +
+        "rewrite the user's prompt to follow best practices for this model.\n\n" +
+        "RULES:\n" +
+        "- Output ONLY the rewritten prompt text, nothing else\n" +
+        "- Do not include explanations, labels, or commentary\n" +
+        charLimitRule +
+        "- Preserve the user's creative intent while improving structure and detail\n" +
+        "- Apply the guide's recommended prompt structure and techniques\n" +
+        "- If images are provided, incorporate visual details you observe into the prompt\n\n" +
+        `--- PROMPTING GUIDE ---\n${guide}\n--- END GUIDE ---\n` +
+        platformSection +
+        instructionSection +
+        errorSection +
+        `\n${userPromptBlock}`);
+}
+export function buildRewriteMessages(guide, prompt, extras = {}) {
+    return [{ role: "user", content: buildRewritePromptText(guide, prompt, extras) }];
+}
+export function buildVisionMessages(guide, prompt, imageDataUris, extras = {}) {
+    const content = imageDataUris.map((uri) => imageUrlPart(uri));
+    content.push(textPart(buildRewritePromptText(guide, prompt, { ...extras, hasImages: true })));
+    return [{ role: "user", content }];
+}
+export function buildResult(model, originalPrompt, rewrittenPrompt, guideFile, previousError) {
+    const result = {
+        model,
+        original_prompt: originalPrompt,
+        rewritten_prompt: rewrittenPrompt,
+        guide_used: guideFile,
+    };
+    if (previousError) {
+        result.previous_error = {
+            message: previousError.message,
+            ...(previousError.failCode ? { fail_code: previousError.failCode } : {}),
+        };
+    }
+    return result;
+}
+export function normalizePromptForMatch(p) {
+    return p.replace(/\s+/g, " ").trim();
+}
+const ERROR_RECENCY_MS = 7 * 24 * 60 * 60 * 1000;
+export async function findPreviousErrorForPrompt(engine, prompt) {
+    const result = await engine.jobs.failures.findAll();
+    if (!result.ok)
+        return null;
+    const normalized = normalizePromptForMatch(prompt);
+    const cutoff = Date.now() - ERROR_RECENCY_MS;
+    const matching = result.value.filter((e) => typeof e.prompt === "string" &&
+        normalizePromptForMatch(e.prompt) === normalized &&
+        e.failedAt > cutoff);
+    if (matching.length === 0)
+        return null;
+    return matching.reduce((latest, current) => current.failedAt > latest.failedAt ? current : latest);
+}
+function requestOptions(request) {
+    return request.options ?? {};
+}
+function sceneElements(options) {
+    const elements = Array.isArray(options.elements) ? options.elements : [];
+    return elements.map((element) => ({ name: String(element.name ?? ""), desc: String(element.description ?? "") }));
+}
+export function extractSceneContext(request) {
+    const options = requestOptions(request);
+    const multiPrompt = Array.isArray(options.multi_prompt) ? options.multi_prompt : [];
+    const scenes = multiPrompt.length > 0
+        ? multiPrompt
+        : [{ prompt: typeof request.prompt === "string" ? request.prompt : "", duration: Number(options.duration ?? 5) }];
+    return { scenes, elements: sceneElements(options) };
+}
+export function validateSceneRewrite(request, sceneIndex) {
+    const model = typeof request.model === "string" ? request.model : undefined;
+    if (model === undefined || modelEntry(model)?.guide !== "kling30") {
+        throw new Error(`Scene rewrite requires a Kling 3.0 asset, got model: ${model}`);
+    }
+    const nScenes = extractSceneContext(request).scenes.length;
+    if (sceneIndex < 0 || sceneIndex >= nScenes) {
+        throw new Error(`scene_index ${sceneIndex} out of range (0-${nScenes - 1})`);
+    }
+}
+export function buildSceneRewriteText(guide, scenes, elements, sceneIndex, instruction) {
+    const lines = [
+        "You are a prompt engineering expert specializing in multi-shot video generation. " +
+            "Using the model-specific prompting guide below, rewrite the TARGET scene prompt " +
+            "to follow best practices.\n",
+        "RULES:",
+        "- Output ONLY the rewritten scene prompt text, nothing else",
+        "- Do not include explanations, labels, scene numbers, or commentary",
+        "- HARD LIMIT: The rewritten prompt MUST be under 400 characters (API max is 500)",
+        "- Be concise and visually specific — cut filler words, focus on key actions and details",
+        "- Preserve @element_name references exactly as they appear",
+        "- Maintain narrative continuity with the other scenes",
+        "- Preserve the user's creative intent while improving structure and detail",
+        "- Apply the guide's recommended prompt structure and techniques",
+        "- If images are provided, incorporate visual details you observe into the prompt\n",
+        `--- PROMPTING GUIDE ---\n${guide}\n--- END GUIDE ---\n`,
+    ];
+    lines.push("--- ALL SCENES ---");
+    for (let i = 0; i < scenes.length; i++) {
+        const marker = i === sceneIndex ? " <<<< TARGET — REWRITE THIS SCENE" : "";
+        lines.push(`Scene ${i} (${scenes[i].duration ?? "?"}s): ${scenes[i].prompt}${marker}`);
+    }
+    lines.push("--- END SCENES ---\n");
+    if (elements.length > 0) {
+        lines.push("--- ELEMENTS ---");
+        for (const elem of elements) {
+            lines.push(`@${elem.name}: ${elem.desc}`);
+        }
+        lines.push("--- END ELEMENTS ---\n");
+    }
+    if (instruction) {
+        lines.push(`ADDITIONAL INSTRUCTION: ${instruction}\n`);
+    }
+    return lines.join("\n");
+}
+function buildSceneResult(sceneIndex, originalScenePrompt, rewritten, guideFile, scenes) {
+    const updatedMultiPrompt = scenes.map((scene, i) => i === sceneIndex ? { ...scene, prompt: rewritten } : { ...scene });
+    return {
+        model: "kling30",
+        scene_index: sceneIndex,
+        original_scene_prompt: originalScenePrompt,
+        rewritten_prompt: rewritten,
+        guide_used: guideFile,
+        updated_multi_prompt: updatedMultiPrompt,
+    };
+}
+async function resolveImageDataUris(imageRefs, engine) {
+    const { resolved } = await resolveArtifactRefs(engine, imageRefs);
+    const dataUris = [];
+    for (const asset of resolved) {
+        if (!asset.filePath)
+            continue;
+        const readResult = await engine.files.read(asset.artifactId, asset.filePath.split("/").pop());
+        if (!readResult.ok)
+            continue;
+        const buf = Buffer.from(readResult.value);
+        const ext = asset.filePath.split(".").pop()?.toLowerCase() ?? "png";
+        const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : ext === "webp" ? "image/webp" : "image/png";
+        dataUris.push(`data:${mime};base64,${buf.toString("base64")}`);
+    }
+    return dataUris;
+}
+// --- Tool definition ---
+export function rewritePromptDef(engine) {
+    return {
+        name: "rewrite_prompt",
+        description: "Rewrite a generation prompt using model-specific best practices. " +
+            "Supports standard mode (rewrite any prompt) and scene mode (rewrite a " +
+            "specific scene in a Kling 3.0 multi-shot asset).",
+        schema: {
+            prompt: z.string().optional().describe("Prompt to rewrite. In scene mode, serves as optional creative direction."),
+            model: z
+                .enum(["nano_banana", "gpt_image", "kling30", "grok_imagine", "grok_image", "seedance2", "seedance25"])
+                .default("kling30")
+                .describe("Target model for prompt optimization"),
+            image_refs: z
+                .array(z.string())
+                .optional()
+                .describe("Optional image artifact ids for visual context"),
+            book_id: z.string().describe("Book id"),
+            asset_ref: z.string().optional().describe("Artifact id for scene-context rewrite (requires scene_index)"),
+            scene_index: z.number().int().optional().describe("0-based scene index to rewrite (requires asset_ref)"),
+            platform: z
+                .enum(["ig", "tiktok", "youtube"])
+                .optional()
+                .describe("Optional platform aesthetic preset (Instagram/TikTok/YouTube)"),
+            custom_prompt: z
+                .string()
+                .max(500)
+                .optional()
+                .describe("Optional free-form additional instruction (max 500 chars)"),
+            previous_error: z
+                .string()
+                .max(2000)
+                .min(1)
+                .optional()
+                .describe("Explicit error message to adapt the rewritten prompt around. When omitted, " +
+                "the tool auto-looks up the latest matching generation error by prompt text."),
+        },
+        handler: async (args) => {
+            const { prompt, model, image_refs, asset_ref, scene_index, platform, custom_prompt, previous_error, } = args;
+            const apiKey = process.env.OPENAI_API_KEY;
+            if (!apiKey) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "OPENAI_API_KEY environment variable is not set" }],
+                };
+            }
+            // Scene rewrite mode
+            if (asset_ref !== undefined && scene_index !== undefined) {
+                return handleSceneRewrite(engine, apiKey, asset_ref, scene_index, prompt);
+            }
+            // Standard rewrite mode — require prompt OR reference images
+            const hasImages = !!image_refs && image_refs.length > 0;
+            if (!prompt && !hasImages) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: "Provide a prompt, or reference image_refs (for vision-based description), or both.",
+                        }],
+                };
+            }
+            // Auto-lookup previous error BEFORE @s01 slot expansion (stored failed
+            // prompts are pre-expansion). Skipped when previous_error was passed
+            // explicitly.
+            let previousError;
+            if (previous_error) {
+                previousError = { message: previous_error };
+            }
+            else if (prompt) {
+                const found = await findPreviousErrorForPrompt(engine, prompt);
+                if (found) {
+                    previousError = {
+                        message: found.message,
+                        ...(found.failCode ? { failCode: found.failCode } : {}),
+                    };
+                }
+            }
+            // Expand @s01 slot refs → @<artifact-id> tokens
+            let expandedPrompt = prompt ?? "";
+            if (expandedPrompt) {
+                expandedPrompt = expandTimelineSlotRefs(expandedPrompt, timelineSlotArtifactIds(engine));
+            }
+            return handleStandardRewrite(engine, apiKey, expandedPrompt, model, image_refs, platform, custom_prompt, previousError);
+        },
+    };
+}
+async function handleStandardRewrite(engine, apiKey, prompt, model, imageRefs, platform, customPrompt, previousError) {
+    let guide;
+    let guideFile;
+    try {
+        guide = await loadGuide(model);
+        guideFile = guideFilename(model);
+    }
+    catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: e.message }],
+        };
+    }
+    const maxChars = model === "kling30" ? 400 : undefined;
+    const responses = buildIntelligenceResponses(apiKey, { timeout: 60_000 });
+    const extras = { maxChars, platform, customPrompt, previousError };
+    let messages;
+    if (imageRefs && imageRefs.length > 0) {
+        const dataUris = await resolveImageDataUris(imageRefs, engine);
+        if (dataUris.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "Could not resolve any image files from provided refs" }],
+            };
+        }
+        messages = buildVisionMessages(guide, prompt, dataUris, extras);
+    }
+    else {
+        messages = buildRewriteMessages(guide, prompt, extras);
+    }
+    const result = await responses(intelligenceRequest({
+        input: responseInputFromMessages(messages),
+        text: { format: { type: "text" } },
+        max_output_tokens: 1024,
+    }));
+    const rewritten = firstResponseText(result);
+    const output = buildResult(model, prompt, rewritten, guideFile, previousError);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output) }],
+    };
+}
+async function handleSceneRewrite(engine, apiKey, assetRef, sceneIndex, instruction) {
+    const assetId = assetRef.replace(/^@/, "");
+    const metaResult = await engine.metadata.artifacts.read(assetId, "generation-request");
+    if (!metaResult.ok || metaResult.value === null) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `No generation-request found for ${assetRef}; scene rewrite needs a video made with generate_video` }],
+        };
+    }
+    const request = metaResult.value;
+    try {
+        validateSceneRewrite(request, sceneIndex);
+    }
+    catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: e.message }],
+        };
+    }
+    const { scenes, elements } = extractSceneContext(request);
+    const guide = await loadGuide("kling30");
+    const text = buildSceneRewriteText(guide, scenes, elements, sceneIndex, instruction);
+    const responses = buildIntelligenceResponses(apiKey, { timeout: 60_000 });
+    const result = await responses(intelligenceRequest({
+        input: [{ role: "user", content: text }],
+        text: { format: { type: "text" } },
+        max_output_tokens: 1024,
+    }));
+    const rewritten = firstResponseText(result);
+    const output = buildSceneResult(sceneIndex, scenes[sceneIndex].prompt, rewritten, guideFilename("kling30"), scenes);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output) }],
+    };
+}
+function responseInputFromMessages(messages) {
+    return messages.map((message) => ({
+        role: message.role,
+        content: typeof message.content === "string"
+            ? message.content
+            : message.content.map((part) => part.type === "text"
+                ? { type: "input_text", text: part.text }
+                : {
+                    type: "input_image",
+                    image_url: part.image_url.url,
+                    detail: part.image_url.detail ?? "auto",
+                }),
+    }));
+}

package/dist/tools/rewrite-script.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { requireArtifactKind } from "./_shared.js";
+const CUSTOM_PROMPT_MAX = 500;
+function error(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export function rewriteScriptDef(engine) {
+    return {
+        name: "rewrite_script",
+        description: "Rewrite a script asset's markdown in place without re-reading the source image: variant full (reproduction prompt and breakdown) or tldr (one or two sentences), with an optional platform preset and custom_prompt instruction. Asynchronous; earlier versions stay in history.",
+        schema: {
+            asset_id: z.string().describe("Script artifact id"),
+            variant: z.enum(["full", "tldr"]).describe("Rewrite style"),
+            platform: z.enum(["ig", "tiktok", "youtube"]).optional()
+                .describe("Platform preset — tunes authentic-capture cues for the target feed"),
+            custom_prompt: z.string().max(CUSTOM_PROMPT_MAX).optional()
+                .describe("Optional transformation instruction, e.g. 'replace the pig with a man in a blue suit'"),
+            book_id: z.string().describe("Book id"),
+        },
+        handler: async (args) => {
+            const { asset_id, variant, platform, custom_prompt, book_id } = args;
+            const kindGate = await requireArtifactKind(engine, asset_id, ["script"], "rewrite_script");
+            if (kindGate)
+                return kindGate;
+            const originalResult = await engine.metadata.artifacts.read(asset_id, "original");
+            if (!originalResult.ok) {
+                return error(`Script ${asset_id} has no native original metadata — cannot determine origin`);
+            }
+            const { origin, sourceAssetId } = originalResult.value;
+            if (origin !== "describe_image" || !sourceAssetId) {
+                return error(`rewrite_script currently supports scripts created by describe_image. Got origin=${origin ?? "unknown"}`);
+            }
+            if (!process.env.OPENAI_API_KEY) {
+                return error("OPENAI_API_KEY is not set");
+            }
+            const scriptManifest = await engine.files.manifest(asset_id);
+            if (!scriptManifest.ok) {
+                return error(scriptManifest.error.message);
+            }
+            const jobId = `rewrite-script-${variant}-${asset_id}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "rewrite_script",
+                assetId: asset_id,
+                sourceAssetId,
+                bookId: book_id,
+                tldr: variant === "tldr",
+                platform: platform ?? null,
+                customPrompt: custom_prompt ?? null,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            source_asset_id: sourceAssetId,
+                            script_asset_id: asset_id,
+                            job_id: jobId,
+                            status: "enqueued",
+                            variant,
+                            ...(platform ? { platform } : {}),
+                            ...(custom_prompt ? { custom_prompt } : {}),
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/schema-from-apicity.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { readSlotConstraints, zodEnumOptionsOrNull, zodFiniteNumberOptions, zodIsBoolean, zodNumberRange, zodStringMaxLength, zodStringMinLength, zodUnionEnumOptions, } from "../zod-slots.js";
+function buildCore(schema) {
+    const enumOpts = zodEnumOptionsOrNull(schema);
+    if (enumOpts)
+        return z.enum(enumOpts);
+    if (zodIsBoolean(schema))
+        return z.boolean();
+    const finiteNumbers = zodFiniteNumberOptions(schema);
+    if (finiteNumbers) {
+        const literals = z.literal(finiteNumbers);
+        return z.preprocess((value) => typeof value === "string" && value.trim() !== "" ? Number(value) : value, literals);
+    }
+    const range = zodNumberRange(schema);
+    if (range) {
+        let n = z.coerce.number();
+        if (range.int)
+            n = n.int();
+        if (range.min !== undefined)
+            n = range.exclusiveMin ? n.gt(range.min) : n.min(range.min);
+        if (range.max !== undefined)
+            n = range.exclusiveMax ? n.lt(range.max) : n.max(range.max);
+        return n;
+    }
+    let s = z.string();
+    const min = zodStringMinLength(schema);
+    if (min !== undefined)
+        s = s.min(min);
+    const max = zodStringMaxLength(schema);
+    if (max !== undefined)
+        s = s.max(max);
+    return s;
+}
+export function apicityField(schema, describe, opts) {
+    const core = buildCore(schema);
+    const described = describe ? core.describe(describe) : core;
+    return opts?.required ? described : described.optional();
+}
+export function apicityStringNumberField(schema, describe, opts) {
+    const values = zodFiniteNumberOptions(schema);
+    if (!values)
+        throw new Error("apicityStringNumberField: schema is not a finite numeric domain");
+    const core = z.enum(values.map(String));
+    const described = describe ? core.describe(describe) : core;
+    return opts?.required ? described : described.optional();
+}
+export function apicityStringArrayField(schema, describe, opts) {
+    const slots = readSlotConstraints(schema, { whenPresent: true });
+    if (!slots)
+        throw new Error("apicityStringArrayField: schema is not an array");
+    let core = z.array(z.string());
+    if (slots.min > 0)
+        core = core.min(slots.min);
+    if (slots.max !== null)
+        core = core.max(slots.max);
+    const described = describe ? core.describe(describe) : core;
+    return opts?.required ? described : described.optional();
+}
+export function apicityUnionEnumField(schema, describe, opts) {
+    const options = zodUnionEnumOptions(schema);
+    if (!options)
+        throw new Error("apicityUnionEnumField: schema has no enum union branch");
+    const core = z.enum(options);
+    const described = describe ? core.describe(describe) : core;
+    return opts?.required ? described : described.optional();
+}

package/dist/tools/search-archive.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { archiveKey, archiveTags, indexKey, } from "../archive-b2.js";
+import { getArchiveStore } from "../archive-store.js";
+function markerShaFromKey(key) {
+    const match = /\/([a-f0-9]{64})-[^/]+\.json$/i.exec(key);
+    return match?.[1]?.toLowerCase() ?? null;
+}
+function includesQuery(index, transcript, query) {
+    const q = query?.trim().toLowerCase();
+    if (!q)
+        return true;
+    const haystack = [
+        index.title ?? "",
+        ...index.topics.map((topic) => topic.label),
+        ...index.people.map((person) => person.label),
+        transcript ?? "",
+    ].join("\n").toLowerCase();
+    return haystack.includes(q);
+}
+function excerptFor(transcript, query) {
+    if (!transcript)
+        return null;
+    const clean = transcript.replace(/\s+/g, " ").trim();
+    if (!clean)
+        return null;
+    const q = query?.trim().toLowerCase();
+    if (!q)
+        return clean.slice(0, 280);
+    const idx = clean.toLowerCase().indexOf(q);
+    if (idx < 0)
+        return clean.slice(0, 280);
+    const start = Math.max(0, idx - 100);
+    return clean.slice(start, start + 320);
+}
+async function loadMarkerSeeds(args) {
+    const seeds = [];
+    for (const key of args.keys) {
+        const objects = await args.store.list(archiveKey(args.store, `${args.kind}/${key}/`));
+        for (const object of objects) {
+            const marker = await args.store.getJson(object.key);
+            const sha256 = marker?.sha256 ?? markerShaFromKey(object.key);
+            if (!sha256)
+                continue;
+            seeds.push({
+                sha256,
+                indexKey: marker?.index_key ?? indexKey(args.store, sha256),
+            });
+        }
+    }
+    return seeds;
+}
+async function loadAllIndexSeeds(args) {
+    const objects = await args.store.list(archiveKey(args.store, "clips/"));
+    return objects
+        .filter((object) => /\/archive\.json$/.test(object.key))
+        .map((object) => {
+        const match = /(?:^|\/)clips\/([a-f0-9]{64})\/archive\.json$/i.exec(object.key);
+        return match?.[1]
+            ? { sha256: match[1].toLowerCase(), indexKey: object.key }
+            : null;
+    })
+        .filter((seed) => seed !== null);
+}
+export function searchArchiveDef() {
+    return {
+        name: "search_archive",
+        description: "Search the global clip archive (B2 if configured, otherwise the local archive folder) by topics, named people, or text query.",
+        schema: {
+            topics: z.array(z.string()).optional().default([]).describe("Topics to match; multiple values use match-any semantics"),
+            people: z.array(z.string()).optional().default([]).describe("Named people to match; multiple values use match-any semantics"),
+            query: z.string().optional().describe("Optional case-insensitive title/topic/person/transcript substring search"),
+            limit: z.number().int().positive().max(100).optional().default(20),
+            offset: z.number().int().min(0).optional().default(0),
+            sort: z.enum(["newest", "oldest"]).optional().default("newest").describe("Sort archived clips by archive updated time"),
+            include_transcript: z.boolean().optional().default(false).describe("Include full transcript text in results"),
+            presign_media: z.boolean().optional().default(true).describe("Return a playable media URL (temporary B2 URL or local server path)"),
+        },
+        handler: async (args) => {
+            const { topics, people, query, limit, offset, sort, include_transcript, presign_media, } = args;
+            const store = getArchiveStore();
+            const topicKeys = archiveTags(topics, "manual").map((topic) => topic.key);
+            const personKeys = archiveTags(people, "manual").map((person) => person.key);
+            const seeds = topicKeys.length > 0 || personKeys.length > 0
+                ? [
+                    ...await loadMarkerSeeds({ kind: "topics", keys: topicKeys, store }),
+                    ...await loadMarkerSeeds({ kind: "people", keys: personKeys, store }),
+                ]
+                : await loadAllIndexSeeds({ store });
+            const byHash = new Map();
+            for (const seed of seeds) {
+                if (!byHash.has(seed.sha256))
+                    byHash.set(seed.sha256, seed);
+            }
+            const hits = [];
+            for (const seed of byHash.values()) {
+                const index = await store.getJson(seed.indexKey);
+                if (!index)
+                    continue;
+                const transcript = (query || include_transcript) && index.transcript
+                    ? await store.getText(index.transcript.text_key)
+                    : null;
+                if (!includesQuery(index, transcript, query))
+                    continue;
+                hits.push({
+                    sortAt: index.updated_at || index.created_at,
+                    result: {
+                        archive_id: index.archive_id,
+                        sha256: index.sha256,
+                        title: index.title,
+                        topics: index.topics,
+                        people: index.people,
+                        sources: index.sources,
+                        duration: index.duration,
+                        media: {
+                            key: index.media.key,
+                            content_type: index.media.content_type,
+                            size_bytes: index.media.size_bytes,
+                            url: null,
+                            expires_at: null,
+                        },
+                        transcript_excerpt: excerptFor(transcript, query),
+                        ...(include_transcript ? { transcript } : {}),
+                    },
+                });
+            }
+            hits.sort((a, b) => sort === "newest" ? b.sortAt.localeCompare(a.sortAt) : a.sortAt.localeCompare(b.sortAt));
+            const paged = hits.slice(offset, offset + limit).map((hit) => hit.result);
+            if (presign_media) {
+                for (const result of paged) {
+                    const media = result.media;
+                    const signed = store.presignGet(media.key, 3600);
+                    media.url = signed?.url ?? null;
+                    media.expires_at = signed?.expiresAt ?? null;
+                }
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            results: paged,
+                            total: hits.length,
+                            offset,
+                            limit,
+                            has_more: offset + paged.length < hits.length,
+                        }),
+                    }],
+            };
+        },
+    };
+}