qlogicagent 2.13.5 → 2.13.7

package/dist/runtime/pet/petdex-forge-service.js

@@ -1,820 +0,0 @@
-/**
- * Petdex forge — drives the vendored OpenAI Codex Hatch-Pet Python pipeline
- * (Apache-2.0, under vendor/hatch-pet) to produce Codex-compatible animated pet
- * sprite atlases.
- *
- * The forge owns NO image-processing heuristics. Chroma-key background removal,
- * stable-slots frame extraction, atlas composition and validation are all done
- * by the deterministic vendored Python scripts — the same pipeline OpenAI ships
- * for Codex `/hatch`. This module only:
- *   1. spawns prepare_pet_run.py to lay out a run directory (prompts, layout
- *      guides, chroma-key selection, imagegen-jobs.json),
- *   2. fulfils each generation job by calling the provider-core media generator,
- *   3. spawns extract / inspect / compose / validate / contact-sheet / preview,
- *   4. reads the composed atlas back and packages it through pet-core.
- *
- * Prompts come exclusively from the Python prompt files (single source of
- * truth, chroma-hex + per-state frame counts baked in) — there is no TS prompt
- * builder path.
- */
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { createCanvas, loadImage } from "@napi-rs/canvas";
-import { createPetdexAssetFromSpritesheet, writePetdexAssetPackage, PETDEX_ATLAS_CONTRACT } from "./petdex-asset.js";
-import { isHatchPetAvailable, runHatchPetScript } from "./hatch-pet-runner.js";
-import { PETDEX_REFERENCE_IMAGE_SIZE, buildPetdexProductionRun, petdexSourceMode, accumulatePetdexUsage, } from "@xiaozhiclaw/pet-core";
-export { PETDEX_PRODUCTION_SCHEMA, } from "@xiaozhiclaw/pet-core";
-const CANONICAL_BASE_REL = "references/canonical-base.png";
-const BASE_STYLE = "single centered full-body desktop pet character on a flat chroma-key background, readable at pet size";
-const ROW_STYLE = "one horizontal animation row strip with evenly spaced full-body frames sharing a single consistent character identity";
-// Row strips are generated at a wide, provider-accepted resolution rather than
-// the (tiny) layout-guide dimensions: image providers like Volcengine Seedream
-// enforce a minimum pixel count (~1920x1920 = 3.69M px) that a 1536x208 guide
-// strip violates. extract_strip_frames slots by frame count, independent of the
-// generated resolution, so a 4096x1024 (4:1) strip extracts cleanly.
-const ROW_STRIP_SIZE = "4096x1024";
-// Image models do not honour the requested chroma-key hex exactly (e.g. Volcengine
-// Seedream renders a deep purple-magenta ~#9413A3 instead of pure #FF00FF), so
-// keying on the configured fallback leaves the real background behind. We detect
-// the actual flat background from the generated base and key extraction on that.
-const FALLBACK_CHROMA_HEX = "#FF00FF";
-const CHROMA_KEY_THRESHOLD = "110";
-// Component-based extraction with a shared viewport: finds the actual pose blobs
-// (merging detached bits — sweat drops, antenna balls — into the nearest pose by
-// x-position) so a drifting pose is never sliced across two cells, and crops every
-// pose to ONE shared viewport so the character keeps a stable scale across the row
-// (no size popping). This needs clean flat strips with no separator lines, which
-// the layout-guide-suppression + anti-frame guard now produce; pure equal-slot
-// "slots" was a stopgap for the separator era and could halve a misplaced pose.
-const EXTRACT_METHOD = "stable-slots";
-// inspect_frames' chroma-adjacent check must stay BELOW the extraction threshold:
-// extraction already removes everything within CHROMA_KEY_THRESHOLD of the key,
-// so anything still opaque is intentionally-kept character. The default (150) is
-// above our 110 and would flag the character's own edges as "chroma residue",
-// triggering an endless false-positive repair storm.
-const INSPECT_CHROMA_ADJ_THRESHOLD = "90";
-// Some image models (e.g. Volcengine Seedream) interpret "N frames in a row" as
-// a gallery of framed pictures — drawing white borders / mats / panels around
-// each pose. Those bright frames survive chroma keying and show as bars in the
-// atlas. The vendored Codex prompts (tuned for GPT-image) don't forbid this, so
-// we append an explicit anti-frame guard the orchestrator owns.
-const GENERATION_LAYOUT_GUARD = [
-    "STRICT BACKGROUND: render one single continuous flat background of the same solid color filling the entire image edge to edge.",
-    "Do NOT draw any picture frame, framed panel, border, mat, outline, box, gallery frame, white or light margin, or divider around or between the poses.",
-    "The poses sit directly on the one seamless flat background, evenly spaced, with nothing separating them.",
-    "IDENTITY LOCK: every frame is the EXACT same character — identical species, body shape, proportions, colors, palette, face, and markings. Do not redesign, restyle, recolor, or resize the character between frames; only its pose changes.",
-    "Each pose is ONE connected solid silhouette at a consistent size. No detached parts, sweat drops, tears, dust, puffs, sparkles, speed lines, motion blur, floating effects, or drop shadows.",
-].join(" ");
-const MIRROR_DECISION_NOTE = "Leftward gait is the framewise horizontal mirror of the approved rightward row, preserving frame order and timing semantics.";
-// Vision-QA loop (Codex method): generate up to N candidates per job and keep the
-// first that a vision model accepts; if none pass, fall through with the last (the
-// deterministic validate_atlas gate still protects the contract). Default 2.
-const DEFAULT_CANDIDATES = 2;
-const MAX_QA_PROMPTS = 2; // initial prompt, then the row's retry prompt
-// ── Public API ─────────────────────────────────────────────
-export async function forgePetdexAsset(input, generateImage, options = {}) {
-    if (!(await isHatchPetAvailable())) {
-        throw new Error("Petdex forge requires the vendored Hatch-Pet pipeline (Python with Pillow). Install Python + Pillow or set QLOGICAGENT_PYTHON to a python that can `import PIL`.");
-    }
-    const usage = { billingQuantity: 0, durationMs: 0 };
-    const productionJobs = [];
-    const combinedPrompts = [];
-    const sourceMode = petdexSourceMode(input);
-    const runDir = await createRunDir();
-    const stagedRefs = await stageReferenceFiles(input);
-    try {
-        // 1. Lay out the run directory: prompts, layout guides, chroma-key, jobs.
-        await runScript("prepare_pet_run.py", [
-            "--pet-name", input.name,
-            "--display-name", input.name,
-            "--description", input.description,
-            "--pet-notes", input.prompt?.trim() || input.description,
-            "--pet-id", asciiSlug(input.id ?? input.name),
-            "--output-dir", runDir,
-            "--chroma-key", "auto",
-            ...stagedRefs.flatMap((file) => ["--reference", file]),
-        ]);
-        const manifestPath = path.join(runDir, "imagegen-jobs.json");
-        const manifest = await readJson(manifestPath);
-        // 2. Fulfil each job in manifest order. The array is dependency-ordered
-        //    (base first; idle/running-right next, then the rest), so a plain
-        //    in-order walk satisfies depends_on and gives the Codex identity+gait
-        //    check for free: base → idle → running-right are vision-QA'd first.
-        const inspectImage = options.inspectImage;
-        const candidates = Math.max(1, options.candidates ?? DEFAULT_CANDIDATES);
-        const generatedRows = [];
-        let chromaHex = FALLBACK_CHROMA_HEX;
-        let baseDataUrl;
-        for (const job of manifest.jobs) {
-            // running-left is mirror-derivable. Without vision QA we mirror it (cheap,
-            // current behaviour). With vision QA we instead generate it as a normal
-            // grounded row so each frame is independently checked — Codex only mirrors
-            // a confirmed-safe running-right, and a drifting mirror yields empty cells.
-            const isDerived = !!(job.derivation_policy?.may_derive && job.derivation_policy.may_derive_from);
-            if (isDerived && !inspectImage) {
-                await deriveRow(runDir);
-                productionJobs.push({
-                    id: `row-${job.id}`,
-                    kind: "row-strip",
-                    status: "complete",
-                    animationId: job.id,
-                    prompt: `derived: framewise-horizontal-mirror of ${job.derivation_policy.may_derive_from}`,
-                    inputImages: [],
-                    outputUrl: job.output_path,
-                });
-                continue;
-            }
-            const prompt = await fs.readFile(path.join(runDir, job.prompt_file), "utf-8");
-            const retryPrompt = job.retry_prompt_file
-                ? await fs.readFile(path.join(runDir, job.retry_prompt_file), "utf-8").catch(() => undefined)
-                : undefined;
-            combinedPrompts.push(prompt);
-            const isBase = job.kind === "base-pet";
-            const { mediaUrl, inputImages } = await selectJobImage({
-                runDir, job, prompt, retryPrompt, generateImage, inspectImage, candidates, usage, upload: options.uploadReferenceImage, baseDataUrl,
-            });
-            // The canonical base is the identity reference every row reuses; it also
-            // reveals the actual flat background colour the model rendered (which we
-            // key extraction on) and is the image vision QA compares every row against.
-            if (isBase) {
-                await fs.copyFile(path.join(runDir, job.output_path), path.join(runDir, CANONICAL_BASE_REL));
-                chromaHex = await detectChromaHex(path.join(runDir, job.output_path));
-                baseDataUrl = await fileToDataUrl(path.join(runDir, CANONICAL_BASE_REL));
-            }
-            // The vendored mirror step gates on running-right being marked complete
-            // in the manifest, so persist job status as each generation lands.
-            job.status = "complete";
-            await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
-            productionJobs.push({
-                id: isBase ? "base-reference" : `row-${job.id}`,
-                kind: isBase ? "reference" : "row-strip",
-                status: "complete",
-                ...(isBase ? {} : { animationId: job.id }),
-                prompt,
-                inputImages,
-                outputUrl: mediaUrl,
-            });
-            if (!isBase)
-                generatedRows.push(job);
-        }
-        // 3. Deterministic pipeline: extract → QA-repair → compose → validate (+ artifacts).
-        const decodedDir = path.join(runDir, "decoded");
-        const framesDir = path.join(runDir, "frames");
-        const atlasPng = path.join(runDir, "atlas.png");
-        const atlasWebp = path.join(runDir, "atlas.webp");
-        await runScript("extract_strip_frames.py", ["--decoded-dir", decodedDir, "--output-dir", framesDir, "--chroma-key", chromaHex, "--key-threshold", CHROMA_KEY_THRESHOLD, "--method", EXTRACT_METHOD]);
-        // Codex deterministic repair: regenerate only the rows inspect flags
-        // (empty/sparse frames, wrong cell size, chroma bleed) with the retry
-        // prompt, re-extract that row, and re-inspect — bounded retries per row.
-        await repairFlaggedRows({
-            runDir, decodedDir, framesDir, generatedRows, chromaHex, generateImage,
-            inspectImage, candidates, baseDataUrl, usage, upload: options.uploadReferenceImage, productionJobs,
-        });
-        const contactSheet = path.join(runDir, "qa", "contact-sheet.png");
-        await composeAndValidate(runDir, framesDir, atlasPng, atlasWebp, contactSheet);
-        // Hybrid frame-level repair: the strip pass gives temporal continuity; here
-        // each extracted frame is scored DETERMINISTICALLY (non-transparent pixel
-        // count + mean brightness vs the row median) to catch dark silhouettes,
-        // off-brightness, empty, or fragment frames cheaply (no per-frame vision
-        // call). Each flagged frame is regenerated as ONE pose (img2img on the base,
-        // vision-QA'd when a vision model is present) and spliced back into its cell,
-        // then the atlas is recomposed + re-validated. One bounded round.
-        if (baseDataUrl) {
-            await repairBadFrames({
-                runDir, framesDir, atlasPng, atlasWebp, contactSheet, generatedRows,
-                generateImage, inspectImage, candidates, usage, upload: options.uploadReferenceImage, baseDataUrl,
-            });
-        }
-        await runScriptSoft("render_animation_previews.py", ["--frames-root", framesDir, "--output-dir", path.join(runDir, "qa", "previews")]);
-        // 4. Package through pet-core (re-encodes webp, builds the Codex-aligned manifest).
-        const spritesheet = await fs.readFile(atlasWebp);
-        const asset = await createPetdexAssetFromSpritesheet({
-            id: input.id,
-            name: input.name,
-            description: input.description,
-            prompt: input.prompt,
-            spritesheet,
-            sourceKind: "forge",
-        });
-        return {
-            ...asset,
-            prompt: combinedPrompts.join("\n\n---\n\n"),
-            productionRun: buildPetdexProductionRun(sourceMode, productionJobs),
-            model: usage.model,
-            size: usage.size,
-            durationMs: usage.durationMs || undefined,
-            ...(usage.provider ? {
-                mediaUsage: {
-                    provider: usage.provider,
-                    model: usage.model ?? "unknown",
-                    billingUnit: usage.billingUnit ?? "per_call",
-                    billingQuantity: usage.billingQuantity || 1,
-                },
-            } : {}),
-        };
-    }
-    finally {
-        await cleanupDir(stagedRefs.length ? path.dirname(stagedRefs[0]) : undefined);
-        if (!keepRuns())
-            await cleanupDir(runDir);
-    }
-}
-export async function forgePetdexAssetPackage(params) {
-    const forged = await forgePetdexAsset(params.input, params.generateImage, {
-        uploadReferenceImage: params.uploadReferenceImage,
-    });
-    const assetDir = path.join(params.outputDir, forged.asset.id);
-    await fs.mkdir(assetDir, { recursive: true });
-    const manifestPath = path.join(assetDir, "pet.json");
-    const spritesheetPath = path.join(assetDir, "spritesheet.webp");
-    const validationPath = path.join(assetDir, "validation.json");
-    const productionRunPath = path.join(assetDir, "production-run.json");
-    await fs.writeFile(manifestPath, JSON.stringify(forged.asset, null, 2), "utf-8");
-    await fs.writeFile(spritesheetPath, forged.spritesheet);
-    await fs.writeFile(validationPath, JSON.stringify(forged.validation, null, 2), "utf-8");
-    await fs.writeFile(productionRunPath, JSON.stringify(forged.productionRun, null, 2), "utf-8");
-    const packagePath = await writePetdexAssetPackage({
-        asset: forged.asset,
-        spritesheet: forged.spritesheet,
-        validation: forged.validation,
-        productionRun: forged.productionRun,
-        outputDir: params.outputDir,
-        fileName: `${forged.asset.id}.petdex`,
-    });
-    return {
-        ...forged,
-        packagePath,
-        assetDir,
-        manifestPath,
-        spritesheetPath,
-        validationPath,
-        productionRunPath,
-    };
-}
-export async function readGeneratedPetdexImage(mediaUrl) {
-    if (mediaUrl.startsWith("data:")) {
-        const match = mediaUrl.match(/^data:[^;]+;base64,(.+)$/);
-        if (!match)
-            throw new Error("Generated Petdex image data URL is not base64 encoded");
-        return Buffer.from(match[1], "base64");
-    }
-    if (/^https?:\/\//i.test(mediaUrl)) {
-        const response = await fetch(mediaUrl);
-        if (!response.ok)
-            throw new Error(`Generated Petdex image download failed: ${response.status} ${response.statusText}`);
-        return Buffer.from(await response.arrayBuffer());
-    }
-    if (mediaUrl.startsWith("file://")) {
-        return fs.readFile(new URL(mediaUrl));
-    }
-    return fs.readFile(mediaUrl);
-}
-// ── Internal helpers ───────────────────────────────────────
-async function deriveRow(runDir) {
-    await runScript("derive_running_left_from_running_right.py", [
-        "--run-dir", runDir,
-        "--confirm-appropriate-mirror",
-        "--decision-note", MIRROR_DECISION_NOTE,
-        "--force",
-    ]);
-}
-/** Generate one candidate image (base or row). Does NOT write to disk. */
-async function generateCandidate(runDir, job, promptText, generateImage, usage, upload) {
-    const inputImages = await resolveJobImages(runDir, job, upload);
-    const isBase = job.kind === "base-pet";
-    // Do NOT send the layout guide to the model: providers like Seedream copy its
-    // visible slot boxes / crosslines straight into the output. Frame spacing comes
-    // from the prompt ("N evenly-spaced frames") and the explicit ROW_STRIP_SIZE;
-    // extraction divides into equal slots regardless. The base pet grounds identity.
-    const sentImages = inputImages.filter((image) => image.role !== "layout-guide");
-    const identity = sentImages.find((image) => image.role === "canonical-reference") ?? sentImages[0];
-    const result = await generateImage({
-        prompt: `${promptText}\n\n${GENERATION_LAYOUT_GUARD}`,
-        purpose: isBase ? "petdex-reference" : "petdex-row-strip",
-        ...(isBase ? {} : { animationId: job.id }),
-        style: isBase ? BASE_STYLE : ROW_STYLE,
-        size: isBase ? PETDEX_REFERENCE_IMAGE_SIZE : ROW_STRIP_SIZE,
-        imageUrl: identity?.imageUrl,
-        referenceImages: sentImages,
-        n: 1,
-        quality: "auto",
-    });
-    accumulatePetdexUsage(usage, result);
-    const mediaUrl = result.mediaUrls[0];
-    if (!mediaUrl)
-        throw new Error(`Petdex generation returned no image for job ${job.id}`);
-    return { mediaUrl, inputImages: sentImages };
-}
-async function writeDecoded(runDir, job, mediaUrl) {
-    const outputPath = path.join(runDir, job.output_path);
-    await fs.mkdir(path.dirname(outputPath), { recursive: true });
-    await fs.writeFile(outputPath, await readGeneratedPetdexImage(mediaUrl));
-}
-/**
- * Generate a job image with the Codex vision-QA loop: up to `candidates` per
- * prompt (initial, then the row's retry prompt), keeping the first that vision QA
- * accepts. With no inspectImage, takes the first candidate. The chosen image is
- * written to the decoded output path. If nothing passes, the last candidate is
- * used — validate_atlas stays the hard contract gate.
- */
-async function selectJobImage(ctx) {
-    const prompts = [ctx.prompt, ...(ctx.retryPrompt ? [ctx.retryPrompt] : [])].slice(0, MAX_QA_PROMPTS);
-    let fallback = null;
-    for (const promptText of prompts) {
-        for (let attempt = 0; attempt < ctx.candidates; attempt++) {
-            const candidate = await generateCandidate(ctx.runDir, ctx.job, promptText, ctx.generateImage, ctx.usage, ctx.upload);
-            if (!ctx.inspectImage) {
-                await writeDecoded(ctx.runDir, ctx.job, candidate.mediaUrl);
-                return candidate;
-            }
-            const verdict = await qaJobImage(ctx.inspectImage, ctx.job, candidate.mediaUrl, ctx.baseDataUrl);
-            if (verdict.ok) {
-                await writeDecoded(ctx.runDir, ctx.job, candidate.mediaUrl);
-                return candidate;
-            }
-            fallback = candidate;
-        }
-    }
-    const chosen = fallback ?? await generateCandidate(ctx.runDir, ctx.job, ctx.prompt, ctx.generateImage, ctx.usage, ctx.upload);
-    await writeDecoded(ctx.runDir, ctx.job, chosen.mediaUrl);
-    return chosen;
-}
-// ── Vision QA (Codex method) ───────────────────────────────
-const FRAME_COUNTS = {
-    idle: 6, "running-right": 8, "running-left": 8, waving: 4, jumping: 5, failed: 8, waiting: 6, running: 6, review: 6,
-};
-/** Lenient parse: only an explicit FAIL blocks (ambiguous output never burns regenerations). */
-function parseVerdict(text) {
-    const value = (text ?? "").trim();
-    if (/\bfail\b/i.test(value) && !/\bpass\b/i.test(value.slice(0, 8))) {
-        const match = value.match(/fail[:\s-]*(.+)/i);
-        return { ok: false, reason: (match?.[1] ?? "").trim().slice(0, 200) };
-    }
-    return { ok: true, reason: "" };
-}
-async function qaJobImage(inspectImage, job, mediaUrl, baseDataUrl) {
-    try {
-        if (job.kind === "base-pet") {
-            return parseVerdict(await inspectImage({ prompt: BASE_QA_PROMPT, imageUrls: [mediaUrl] }));
-        }
-        const frames = FRAME_COUNTS[job.id] ?? 6;
-        const imageUrls = baseDataUrl ? [mediaUrl, baseDataUrl] : [mediaUrl];
-        return parseVerdict(await inspectImage({ prompt: rowQaPrompt(job.id, frames), imageUrls }));
-    }
-    catch {
-        return { ok: true, reason: "" }; // a QA-call failure must not block generation
-    }
-}
-const BASE_QA_PROMPT = [
-    "You are a strict desktop-pet sprite reviewer. The image is a single pet character reference.",
-    "Reply PASS only if ALL hold: one centered full-body cute pet; one flat solid background; no text, scenery, picture frames, borders, drop shadows, or detached effects.",
-    'Reply with exactly "PASS" or "FAIL: <one short reason>".',
-].join(" ");
-function rowQaPrompt(state, frames) {
-    return [
-        `You are a strict sprite-sheet reviewer. Image 1 is a horizontal strip of ${frames} animation frames for a desktop pet's "${state}" animation. Image 2 is the canonical reference of the SAME pet.`,
-        "Reply PASS only if ALL hold: (1) every frame is the SAME character as the reference — same species, colors, palette, face, proportions, markings; (2) one flat solid background with NO picture frames, borders, boxes, mats, panels, dividers, or copied guide lines; (3) each pose is a complete pet, fully inside its own area, not cut off or split between cells; (4) no detached effects — no drop shadows, sparkles, dust, tears, speed lines, or text.",
-        'Reply with exactly "PASS" or "FAIL: <one short reason>".',
-    ].join(" ");
-}
-async function fileToDataUrl(filePath) {
-    const buffer = await fs.readFile(filePath);
-    const mimeType = filePath.toLowerCase().endsWith(".webp") ? "image/webp" : "image/png";
-    return `data:${mimeType};base64,${buffer.toString("base64")}`;
-}
-const MAX_ROW_REPAIRS = 2;
-/**
- * Re-inspect extracted frames and regenerate only the rows that fail QA, using
- * each row's retry prompt and re-extracting just that row. Mirrors the Codex
- * "repair the smallest failing scope first" policy; bounded per row so a
- * persistently bad row falls through to the hard validate gate rather than
- * looping forever.
- */
-async function repairFlaggedRows(ctx) {
-    const reviewPath = path.join(ctx.runDir, "qa", "review.json");
-    const inspect = () => runScriptSoft("inspect_frames.py", ["--frames-root", ctx.framesDir, "--json-out", reviewPath, "--chroma-adjacent-threshold", INSPECT_CHROMA_ADJ_THRESHOLD]);
-    await inspect();
-    let review = await readReview(reviewPath);
-    for (const job of ctx.generatedRows) {
-        let attempts = 0;
-        while (review && rowFailed(review, job.id) && attempts < MAX_ROW_REPAIRS) {
-            attempts++;
-            await regenerateRow(ctx, job);
-            await reextractRows(ctx, await rowsToReextract(ctx, job));
-            await inspect();
-            review = await readReview(reviewPath);
-        }
-    }
-}
-/** Regenerate one row (vision-QA loop) and update its provenance + decoded output. */
-async function regenerateRow(ctx, job) {
-    // Repairs escalate to the row's stricter retry prompt as the primary prompt.
-    const prompt = await fs.readFile(path.join(ctx.runDir, job.prompt_file), "utf-8");
-    const retryPrompt = job.retry_prompt_file
-        ? await fs.readFile(path.join(ctx.runDir, job.retry_prompt_file), "utf-8").catch(() => undefined)
-        : undefined;
-    const repairPrompt = retryPrompt ?? prompt;
-    const { mediaUrl, inputImages } = await selectJobImage({
-        runDir: ctx.runDir, job, prompt: repairPrompt, generateImage: ctx.generateImage, inspectImage: ctx.inspectImage,
-        candidates: ctx.candidates, usage: ctx.usage, upload: ctx.upload, baseDataUrl: ctx.baseDataUrl,
-    });
-    const provenance = ctx.productionJobs.find((entry) => entry.id === `row-${job.id}`);
-    if (provenance) {
-        provenance.prompt = repairPrompt;
-        provenance.outputUrl = mediaUrl;
-        provenance.inputImages = inputImages;
-    }
-}
-/** When running-right is regenerated and running-left was mirror-derived, re-mirror it. */
-async function rowsToReextract(ctx, job) {
-    if (job.id !== "running-right")
-        return job.id;
-    // running-left was mirror-derived only when there is no vision QA.
-    const leftDerived = !ctx.inspectImage && await fileExists(path.join(ctx.decodedDir, "running-left.png"));
-    if (leftDerived) {
-        await deriveRow(ctx.runDir);
-        return "running-right,running-left";
-    }
-    return "running-right";
-}
-async function reextractRows(ctx, states) {
-    await runScript("extract_strip_frames.py", ["--decoded-dir", ctx.decodedDir, "--output-dir", ctx.framesDir, "--states", states, "--chroma-key", ctx.chromaHex, "--key-threshold", CHROMA_KEY_THRESHOLD, "--method", EXTRACT_METHOD]);
-}
-async function fileExists(filePath) {
-    return fs.access(filePath).then(() => true, () => false);
-}
-/** Compose the atlas, hard-validate it, and refresh the contact sheet. */
-async function composeAndValidate(runDir, framesDir, atlasPng, atlasWebp, contactSheet) {
-    await runScript("compose_atlas.py", ["--frames-root", framesDir, "--output", atlasPng, "--webp-output", atlasWebp]);
-    // Atlas validation is the hard gate: a contract-violating atlas is never packaged.
-    await runScript("validate_atlas.py", [atlasPng, "--json-out", path.join(runDir, "qa", "validation.json")]);
-    await runScriptSoft("make_contact_sheet.py", [atlasPng, "--output", contactSheet]);
-}
-const MAX_FRAME_REPAIRS_PER_ROW = 4; // cap single-frame regenerations per row
-const SINGLE_FRAME_STYLE = "one single centered full-body desktop pet pose on a flat chroma-key background";
-const FRAME_EXTRACT_THRESHOLD = 120; // chroma distance for single-frame background removal
-// Brief per-state pose hints for single-frame regeneration (the row prompt is for
-// a whole strip; one replacement frame just needs the state's gist + identity).
-const STATE_HINTS = {
-    idle: "a calm resting pose, breathing, standing still",
-    "running-right": "a mid-stride running pose facing and moving to the right",
-    "running-left": "a mid-stride running pose facing and moving to the left",
-    waving: "raising a paw/hand/limb in a friendly wave",
-    jumping: "a mid-air playful jump",
-    failed: "a sad, deflated, slumped reaction pose",
-    waiting: "an expectant waiting pose, looking up for input",
-    running: "a focused working/thinking pose, busy but not foot-running",
-    review: "a focused inspecting pose, leaning in to review",
-};
-const MIN_FRAME_PIXELS = 400; // matches inspect_frames --min-used-pixels
-const ABSOLUTE_DARK_LUM = 45; // mean luminance below which a frame is a dark silhouette
-/**
- * Frame-level repair (deterministic detection): score every extracted frame by
- * non-transparent pixel count + mean brightness against the row median. Frames
- * that are empty/fragment (too few pixels) or a dark silhouette / off-brightness
- * (much darker than the row) are regenerated as ONE pose (img2img on the base,
- * vision-QA'd when a vision model is present) and spliced back into the cell.
- * No per-frame vision call — the user's "black vs blue / wrong count" defects are
- * measurable directly, which also keeps the run fast enough for the RPC timeout.
- */
-async function repairBadFrames(ctx) {
-    let repaired = 0;
-    for (const job of ctx.generatedRows) {
-        const frames = FRAME_COUNTS[job.id] ?? 6;
-        const stats = [];
-        for (let index = 0; index < frames; index++) {
-            stats.push(await analyzeFrame(path.join(ctx.framesDir, job.id, `${String(index).padStart(2, "0")}.png`)));
-        }
-        const medianCount = median(stats.map((s) => s.count).filter((c) => c > 0));
-        const medianLum = median(stats.map((s) => s.lum).filter((l) => l > 0));
-        let rowRepairs = 0;
-        for (let index = 0; index < frames && rowRepairs < MAX_FRAME_REPAIRS_PER_ROW; index++) {
-            const stat = stats[index];
-            const sparse = stat.count < Math.max(MIN_FRAME_PIXELS, medianCount * 0.4);
-            const dark = stat.lum < ABSOLUTE_DARK_LUM || (medianLum > 0 && stat.lum < medianLum * 0.6);
-            if (!sparse && !dark)
-                continue;
-            const single = await generateSingleFrame(ctx, job, index, frames);
-            if (!single)
-                continue;
-            await extractFrameToCell(await readGeneratedPetdexImage(single), path.join(ctx.framesDir, job.id, `${String(index).padStart(2, "0")}.png`));
-            rowRepairs++;
-            repaired++;
-        }
-    }
-    if (repaired > 0) {
-        await composeAndValidate(ctx.runDir, ctx.framesDir, ctx.atlasPng, ctx.atlasWebp, ctx.contactSheet);
-    }
-}
-/** Non-transparent pixel count + mean luminance of those pixels for one frame. */
-async function analyzeFrame(framePath) {
-    try {
-        const image = await loadImage(await fs.readFile(framePath));
-        const width = Math.max(1, image.width);
-        const height = Math.max(1, image.height);
-        const canvas = createCanvas(width, height);
-        const ctx = canvas.getContext("2d");
-        ctx.drawImage(image, 0, 0);
-        const data = ctx.getImageData(0, 0, width, height).data;
-        let count = 0;
-        let lumSum = 0;
-        for (let i = 0; i < data.length; i += 4) {
-            if ((data[i + 3] ?? 0) > 40) {
-                count++;
-                lumSum += 0.299 * (data[i] ?? 0) + 0.587 * (data[i + 1] ?? 0) + 0.114 * (data[i + 2] ?? 0);
-            }
-        }
-        return { count, lum: count ? lumSum / count : 0 };
-    }
-    catch {
-        return { count: Number.MAX_SAFE_INTEGER, lum: 255 }; // unreadable → treat as ok
-    }
-}
-function median(values) {
-    if (values.length === 0)
-        return 0;
-    const sorted = [...values].sort((a, b) => a - b);
-    const mid = Math.floor(sorted.length / 2);
-    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-function frameQaPrompt(state) {
-    return [
-        `Image 1 is ONE animation frame of a desktop pet's "${state}" pose. Image 2 is the canonical reference of the SAME pet.`,
-        "Reply PASS only if image 1 shows ONE complete pet that clearly matches the reference — same species, colors, palette, BRIGHTNESS, proportions, markings; centered and fully visible.",
-        "Reply FAIL if it is a dark or black silhouette, off-colour, dimmer/brighter than the reference, cut off, empty, a fragment, or shows two pets.",
-        'Reply with exactly "PASS" or "FAIL: <one short reason>".',
-    ].join(" ");
-}
-/** Generate ONE replacement pose (img2img on the canonical base), vision-QA'd. */
-async function generateSingleFrame(ctx, job, index, frames) {
-    const prompt = [
-        `Create ONE single image of a desktop pet in the "${job.id}" animation, pose ${index + 1} of ${frames}.`,
-        "Output exactly ONE complete, centered, full-body pose of the SAME pet as the attached reference image — identical species, colors, palette, brightness, proportions, and markings.",
-        "This is a single sprite frame: NOT a strip, NOT a grid, NOT multiple poses, NOT a dark silhouette.",
-        `Pose: ${STATE_HINTS[job.id] ?? "a clear pose for this state"}.`,
-    ].join(" ");
-    let fallback = null;
-    for (let attempt = 0; attempt < ctx.candidates; attempt++) {
-        const result = await ctx.generateImage({
-            prompt: `${prompt}\n\n${GENERATION_LAYOUT_GUARD}`,
-            purpose: "petdex-reference",
-            style: SINGLE_FRAME_STYLE,
-            size: PETDEX_REFERENCE_IMAGE_SIZE,
-            imageUrl: ctx.baseDataUrl,
-            referenceImages: [{ role: "canonical-reference", imageUrl: ctx.baseDataUrl }],
-            n: 1,
-            quality: "auto",
-        });
-        accumulatePetdexUsage(ctx.usage, result);
-        const url = result.mediaUrls[0];
-        if (!url)
-            continue;
-        fallback = url;
-        if (!ctx.inspectImage)
-            return url;
-        try {
-            const verdict = parseVerdict(await ctx.inspectImage({ prompt: frameQaPrompt(job.id), imageUrls: [url, ctx.baseDataUrl] }));
-            if (verdict.ok)
-                return url;
-        }
-        catch {
-            return url; // vision-call failure → accept the candidate
-        }
-    }
-    return fallback;
-}
-/**
- * Extract a single generated pose into one transparent 192x208 cell: detect the
- * flat background colour from the image border, key it out, then crop-to-content
- * and fit centred. (Single clean pose only — not the flawed multi-pose slotting.)
- */
-async function extractFrameToCell(srcBuffer, outPath) {
-    const image = await loadImage(srcBuffer);
-    const width = Math.max(1, image.width);
-    const height = Math.max(1, image.height);
-    const canvas = createCanvas(width, height);
-    const ctx = canvas.getContext("2d");
-    ctx.drawImage(image, 0, 0);
-    const imageData = ctx.getImageData(0, 0, width, height);
-    const data = imageData.data;
-    const [kr, kg, kb] = dominantBorderColor(data, width, height);
-    for (let i = 0; i < data.length; i += 4) {
-        const dr = (data[i] ?? 0) - kr;
-        const dg = (data[i + 1] ?? 0) - kg;
-        const db = (data[i + 2] ?? 0) - kb;
-        if (Math.sqrt(dr * dr + dg * dg + db * db) <= FRAME_EXTRACT_THRESHOLD) {
-            data[i] = 0;
-            data[i + 1] = 0;
-            data[i + 2] = 0;
-            data[i + 3] = 0;
-        }
-    }
-    ctx.putImageData(imageData, 0, 0);
-    let minX = width, minY = height, maxX = -1, maxY = -1;
-    for (let y = 0; y < height; y++) {
-        for (let x = 0; x < width; x++) {
-            if ((data[(y * width + x) * 4 + 3] ?? 0) > 16) {
-                if (x < minX)
-                    minX = x;
-                if (x > maxX)
-                    maxX = x;
-                if (y < minY)
-                    minY = y;
-                if (y > maxY)
-                    maxY = y;
-            }
-        }
-    }
-    const cell = createCanvas(PETDEX_ATLAS_CONTRACT.cellWidth, PETDEX_ATLAS_CONTRACT.cellHeight);
-    const cellCtx = cell.getContext("2d");
-    if (maxX >= minX && maxY >= minY) {
-        const bw = maxX - minX + 1;
-        const bh = maxY - minY + 1;
-        const maxW = PETDEX_ATLAS_CONTRACT.cellWidth - 10;
-        const maxH = PETDEX_ATLAS_CONTRACT.cellHeight - 10;
-        const scale = Math.min(maxW / bw, maxH / bh, 1);
-        const dw = bw * scale;
-        const dh = bh * scale;
-        cellCtx.imageSmoothingEnabled = true;
-        cellCtx.imageSmoothingQuality = "high";
-        cellCtx.drawImage(canvas, minX, minY, bw, bh, (PETDEX_ATLAS_CONTRACT.cellWidth - dw) / 2, (PETDEX_ATLAS_CONTRACT.cellHeight - dh) / 2, dw, dh);
-    }
-    await fs.mkdir(path.dirname(outPath), { recursive: true });
-    await fs.writeFile(outPath, Buffer.from(cell.toBuffer("image/png")));
-}
-/** Dominant colour of an inset border ring (the flat chroma background). */
-function dominantBorderColor(data, width, height) {
-    const inset = Math.max(4, Math.floor(Math.min(width, height) * 0.02));
-    const step = Math.max(1, Math.floor(width / 200));
-    const buckets = new Map();
-    const sample = (x, y) => {
-        const idx = (y * width + x) * 4;
-        const r = data[idx] ?? 0, g = data[idx + 1] ?? 0, b = data[idx + 2] ?? 0;
-        if (r + g + b < 24)
-            return;
-        const key = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4);
-        const e = buckets.get(key) ?? { n: 0, r: 0, g: 0, b: 0 };
-        e.n++;
-        e.r += r;
-        e.g += g;
-        e.b += b;
-        buckets.set(key, e);
-    };
-    for (let x = inset; x < width - inset; x += step) {
-        sample(x, inset);
-        sample(x, height - 1 - inset);
-    }
-    for (let y = inset; y < height - inset; y += step) {
-        sample(inset, y);
-        sample(width - 1 - inset, y);
-    }
-    let best = null;
-    for (const e of buckets.values())
-        if (!best || e.n > best.n)
-            best = e;
-    if (!best || best.n === 0)
-        return [255, 0, 255];
-    return [Math.round(best.r / best.n), Math.round(best.g / best.n), Math.round(best.b / best.n)];
-}
-function rowFailed(review, state) {
-    const row = review.rows.find((entry) => entry.state === state);
-    return row ? row.ok === false : false;
-}
-async function readReview(reviewPath) {
-    return readJson(reviewPath).catch(() => null);
-}
-async function resolveJobImages(runDir, job, upload) {
-    const images = [];
-    for (const image of job.input_images) {
-        const absPath = path.join(runDir, image.path);
-        // canonical-base is produced after the base job; tolerate its absence on
-        // the base job itself (where it is not referenced anyway).
-        const buffer = await fs.readFile(absPath).catch(() => null);
-        if (!buffer)
-            continue;
-        const imageUrl = await toImageUrl(buffer, path.basename(absPath), upload);
-        images.push({ role: mapReferenceRole(image.role), imageUrl });
-    }
-    return images;
-}
-function mapReferenceRole(role) {
-    const lower = role.toLowerCase();
-    if (lower.includes("layout guide"))
-        return "layout-guide";
-    if (lower.includes("atlas"))
-        return "existing-atlas";
-    return "canonical-reference";
-}
-async function toImageUrl(buffer, filename, upload) {
-    const mimeType = filename.toLowerCase().endsWith(".webp") ? "image/webp" : "image/png";
-    if (upload)
-        return upload({ buffer, mimeType, filename });
-    return `data:${mimeType};base64,${buffer.toString("base64")}`;
-}
-async function stageReferenceFiles(input) {
-    const buffers = [];
-    if (input.referenceImageUrl)
-        buffers.push(await readGeneratedPetdexImage(input.referenceImageUrl));
-    // A refine run grounds identity on the existing atlas.
-    if (input.baseSpritesheet)
-        buffers.push(input.baseSpritesheet);
-    if (buffers.length === 0)
-        return [];
-    const stagingDir = await fs.mkdtemp(path.join(os.tmpdir(), "petdex-ref-"));
-    const files = [];
-    for (let index = 0; index < buffers.length; index++) {
-        const file = path.join(stagingDir, `reference-${String(index + 1).padStart(2, "0")}.png`);
-        await fs.writeFile(file, buffers[index]);
-        files.push(file);
-    }
-    return files;
-}
-async function createRunDir() {
-    const base = process.env.QLOGICAGENT_PETDEX_RUN_DIR?.trim() || os.tmpdir();
-    await fs.mkdir(base, { recursive: true });
-    return fs.mkdtemp(path.join(base, "petdex-run-"));
-}
-function keepRuns() {
-    const value = process.env.QLOGICAGENT_PETDEX_KEEP_RUNS?.trim().toLowerCase();
-    return value === "1" || value === "true";
-}
-async function cleanupDir(dir) {
-    if (!dir)
-        return;
-    await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
-}
-async function readJson(file) {
-    return JSON.parse(await fs.readFile(file, "utf-8"));
-}
-/**
- * Detect the flat background colour the model actually rendered, by taking the
- * dominant colour of an inset border ring of the base image. Image models do not
- * honour the requested chroma hex, so extraction must key on what was produced.
- */
-async function detectChromaHex(pngPath) {
-    try {
-        const image = await loadImage(await fs.readFile(pngPath));
-        const width = Math.max(1, image.width);
-        const height = Math.max(1, image.height);
-        const canvas = createCanvas(width, height);
-        const ctx = canvas.getContext("2d");
-        ctx.drawImage(image, 0, 0);
-        const data = ctx.getImageData(0, 0, width, height).data;
-        const inset = Math.max(8, Math.floor(Math.min(width, height) * 0.02));
-        const step = Math.max(1, Math.floor(width / 240));
-        const buckets = new Map();
-        const sample = (x, y) => {
-            const idx = (y * width + x) * 4;
-            const a = data[idx + 3] ?? 0;
-            const r = data[idx] ?? 0;
-            const g = data[idx + 1] ?? 0;
-            const b = data[idx + 2] ?? 0;
-            if (a < 200)
-                return;
-            if (r + g + b < 48)
-                return; // skip near-black borders/separator lines
-            const key = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4);
-            const e = buckets.get(key) ?? { n: 0, r: 0, g: 0, b: 0 };
-            e.n++;
-            e.r += r;
-            e.g += g;
-            e.b += b;
-            buckets.set(key, e);
-        };
-        for (let x = inset; x < width - inset; x += step) {
-            sample(x, inset);
-            sample(x, height - 1 - inset);
-        }
-        for (let y = inset; y < height - inset; y += step) {
-            sample(inset, y);
-            sample(width - 1 - inset, y);
-        }
-        let best = null;
-        for (const e of buckets.values())
-            if (!best || e.n > best.n)
-                best = e;
-        if (!best || best.n === 0)
-            return FALLBACK_CHROMA_HEX;
-        const r = Math.round(best.r / best.n);
-        const g = Math.round(best.g / best.n);
-        const b = Math.round(best.b / best.n);
-        return `#${[r, g, b].map((v) => v.toString(16).padStart(2, "0")).join("")}`.toUpperCase();
-    }
-    catch {
-        return FALLBACK_CHROMA_HEX;
-    }
-}
-function asciiSlug(value) {
-    const slug = value.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
-    return slug || "petdex";
-}
-async function runScript(script, args) {
-    const result = await runHatchPetScript(script, args, { timeoutMs: 180_000 });
-    if (!result.ok) {
-        throw new Error(`Petdex pipeline step ${script} failed (exit ${result.code ?? "?"}): ${result.stderr.trim() || result.stdout.trim()}`);
-    }
-}
-async function runScriptSoft(script, args) {
-    await runHatchPetScript(script, args, { timeoutMs: 180_000 }).catch(() => undefined);
-}