qlogicagent 2.13.3 → 2.13.5

package/dist/cli/handlers/pet-handler.test.js

@@ -0,0 +1,620 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createCanvas } from "@napi-rs/canvas";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PetProfileService } from "../../runtime/pet/pet-profile-service.js";
+import { createDefaultPetdexAnimations } from "@xiaozhiclaw/pet-core";
+import { PETDEX_ATLAS_CONTRACT, createPetdexAssetFromSpritesheet } from "../../runtime/pet/petdex-asset.js";
+import { PetSoulService } from "../../runtime/pet/pet-soul-service.js";
+import { handlePetCustomDelete, handlePetInteract, handlePetJourneyGet, handlePetJourneyList, handlePetJourneySnapshot, handlePetForge, handlePetPreferencesUpdate, handlePetStatus, } from "./pet-handler.js";
+const tmpDirs = [];
+function makeWorkspace() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pet-handler-"));
+    tmpDirs.push(dir);
+    return dir;
+}
+async function createTestPetdexAsset(params = {}) {
+    const canvas = createCanvas(PETDEX_ATLAS_CONTRACT.width, PETDEX_ATLAS_CONTRACT.height);
+    const ctx = canvas.getContext("2d");
+    ctx.clearRect(0, 0, PETDEX_ATLAS_CONTRACT.width, PETDEX_ATLAS_CONTRACT.height);
+    for (let frame = 0; frame < PETDEX_ATLAS_CONTRACT.frameCount; frame++) {
+        const col = frame % PETDEX_ATLAS_CONTRACT.columns;
+        const row = Math.floor(frame / PETDEX_ATLAS_CONTRACT.columns);
+        const x = col * PETDEX_ATLAS_CONTRACT.cellWidth + 64 + (frame % 2) * 6;
+        const y = row * PETDEX_ATLAS_CONTRACT.cellHeight + 64 + (frame % 3) * 4;
+        ctx.fillStyle = row === 5 ? "#ef4444" : "#2563eb";
+        ctx.beginPath();
+        ctx.ellipse(x + 34, y + 40, 32, 42, 0, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.fillStyle = "#111827";
+        ctx.beginPath();
+        ctx.arc(x + 23, y + 29, 4, 0, Math.PI * 2);
+        ctx.arc(x + 45, y + 29, 4, 0, Math.PI * 2);
+        ctx.fill();
+    }
+    const spritesheet = Buffer.from(await canvas.encode("webp"));
+    return createPetdexAssetFromSpritesheet({
+        id: params.id,
+        name: params.name ?? "Test Pet",
+        description: params.description ?? "Test Petdex asset",
+        prompt: params.prompt ?? "test petdex asset",
+        spritesheet,
+        now: "2026-06-03T00:00:00.000Z",
+        sourceKind: params.sourceKind ?? "forge",
+    });
+}
+async function installTestBuiltinPetdexAsset() {
+    const root = path.join(makeWorkspace(), "builtin-petdex");
+    const builtin = await createTestPetdexAsset({
+        id: "builtin-anime-horse-girl",
+        name: "Builtin Pet",
+        description: "Published builtin Petdex asset",
+        prompt: "published builtin petdex asset",
+        sourceKind: "builtin",
+    });
+    const dir = path.join(root, builtin.asset.id);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "pet.json"), JSON.stringify(builtin.asset, null, 2), "utf-8");
+    fs.writeFileSync(path.join(dir, "spritesheet.webp"), builtin.spritesheet);
+    fs.writeFileSync(path.join(dir, "validation.json"), JSON.stringify(builtin.validation, null, 2), "utf-8");
+    vi.stubEnv("QLOGICAGENT_BUILTIN_PETDEX_DIR", root);
+}
+function petdexAsset(overrides = {}) {
+    return {
+        schema: "qlogic.petdex.asset.v1",
+        id: "petdex-1",
+        assetKind: "petdex",
+        name: "Spark",
+        description: "Generated",
+        createdAt: "2026-06-03T00:00:00.000Z",
+        updatedAt: "2026-06-03T00:00:00.000Z",
+        source: { kind: "forge", prompt: "round desk companion" },
+        atlas: {
+            image: "spritesheet.webp",
+            format: "webp",
+            columns: 8,
+            rows: 9,
+            frameCount: 72,
+            cellWidth: 192,
+            cellHeight: 208,
+            width: 1536,
+            height: 1872,
+            sha256: "sha256-petdex-1",
+        },
+        animations: createDefaultPetdexAnimations(),
+        thumbnail: { frame: 0 },
+        ...overrides,
+    };
+}
+afterEach(() => {
+    vi.unstubAllEnvs();
+    for (const dir of tmpDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("pet interaction boundary", () => {
+    it("ensures a shared owner soul from pet status without a separate activation RPC", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const statsByOwner = new Map();
+        function makeHost(ownerUserId) {
+            return {
+                deviceId: "same-device",
+                ownerUserId,
+                getActiveProjectRoot: () => workspace,
+                sendNotification: () => undefined,
+                sendResponse: () => undefined,
+                petRuntime: {
+                    createPetSoulGenerator: () => async (_rarity, stats) => {
+                        statsByOwner.set(ownerUserId, stats);
+                        return {
+                            name: `pet-${stats.grip}-${stats.patience}-${stats.curiosity}`,
+                            personality: "calm",
+                            catchphrase: "ready",
+                        };
+                    },
+                    createSmallLLMCall: () => undefined,
+                    forgeAnalyzeImage: async () => "",
+                },
+            };
+        }
+        await handlePetStatus.call(makeHost("user/alice"), { id: "status-a", method: "pet.status", params: {} });
+        await handlePetStatus.call(makeHost("user/bob"), { id: "status-b", method: "pet.status", params: {} });
+        expect(fs.existsSync(path.join(home, "profiles", "user%2Falice", "pet", "profile.json"))).toBe(true);
+        expect(fs.existsSync(path.join(home, "profiles", "user%2Fbob", "pet", "profile.json"))).toBe(true);
+        expect(statsByOwner.get("user/alice")).not.toEqual(statsByOwner.get("user/bob"));
+    });
+    it("returns presentation-only reactions without agent action shortcuts", async () => {
+        const workspace = makeWorkspace();
+        const notifications = [];
+        const responses = [];
+        const host = {
+            getActiveProjectRoot: () => workspace,
+            sendNotification: (method, params) => notifications.push({ method, params }),
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        await handlePetInteract.call(host, {
+            id: "pet-1",
+            method: "pet.interact",
+            params: { action: "click" },
+        });
+        const response = responses[0]?.result;
+        expect(responses[0]?.error).toBeUndefined();
+        expect(response?.reaction?.actions).toBeUndefined();
+        for (const item of notifications.filter((n) => n.method === "pet.reaction")) {
+            expect(item.params.actions).toBeUndefined();
+        }
+    });
+    it("reports pet growth as display traits without agent ability fields", async () => {
+        const workspace = makeWorkspace();
+        await installTestBuiltinPetdexAsset();
+        const service = new PetSoulService(workspace);
+        const soul = await service.ensureSoul("user-test");
+        service.updateSoul({
+            ...soul,
+            level: 15,
+            experience: 0,
+        });
+        const notifications = [];
+        const responses = [];
+        const host = {
+            getActiveProjectRoot: () => workspace,
+            sendNotification: (method, params) => notifications.push({ method, params }),
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        await handlePetStatus.call(host, {
+            id: "pet-status",
+            method: "pet.status",
+            params: {},
+        });
+        const result = responses[0]?.result;
+        const growthNotification = notifications.find((item) => item.method === "pet.growth")?.params ?? {};
+        for (const payload of [result?.growth ?? {}, growthNotification]) {
+            const displayTraits = payload.displayTraits;
+            expect(displayTraits.length).toBeGreaterThan(0);
+            for (const trait of displayTraits) {
+                expect(Object.keys(trait).sort()).toEqual(["id", "level"]);
+            }
+            if (payload.nextDisplayTrait) {
+                expect(Object.keys(payload.nextDisplayTrait).sort()).toEqual(["id", "level"]);
+            }
+            expect(payload.abilities).toBeUndefined();
+            expect(payload.nextAbility).toBeUndefined();
+            expect(payload.newAbility).toBeUndefined();
+        }
+    });
+    it("returns Petdex custom pet summaries on pet status without SVG maps", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        await installTestBuiltinPetdexAsset();
+        new PetProfileService("user/alice").upsertCustomPet(petdexAsset());
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        await handlePetStatus.call(host, { id: "pet-status", method: "pet.status", params: {} });
+        const removedSvgMapKey = "svg" + "s";
+        const result = responses[0]?.result;
+        expect(result.customPets?.[0]).toMatchObject({
+            id: "petdex-1",
+            assetKind: "petdex",
+            sourceKind: "forge",
+            name: "Spark",
+            description: "Generated",
+            createdAt: "2026-06-03T00:00:00.000Z",
+            updatedAt: "2026-06-03T00:00:00.000Z",
+            atlas: {
+                format: "webp",
+                columns: 8,
+                rows: 9,
+                frameCount: 72,
+                cellWidth: 192,
+                cellHeight: 208,
+                width: 1536,
+                height: 1872,
+                sha256: "sha256-petdex-1",
+            },
+        });
+        expect(result.customPets?.[0]?.animations).toBeDefined();
+        expect(result.profile?.customPets).toEqual(result.customPets);
+        expect(result.customPets?.[0]?.[removedSvgMapKey]).toBeUndefined();
+    });
+    it("returns builtin and custom pets through one Petdex asset list on pet status", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        await installTestBuiltinPetdexAsset();
+        new PetProfileService("user/alice").upsertCustomPet(petdexAsset());
+        new PetProfileService("user/alice").updatePreferences({ selectedPetAssetId: "builtin-anime-horse-girl" });
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        await handlePetStatus.call(host, { id: "pet-status", method: "pet.status", params: {} });
+        const result = responses[0]?.result;
+        expect(result.profile?.preferences?.selectedPetAssetId).toBe("builtin-anime-horse-girl");
+        expect(result.petAssets?.map((pet) => pet.id)).toEqual(["builtin-anime-horse-girl", "petdex-1"]);
+        for (const asset of result.petAssets ?? []) {
+            expect(asset.assetKind).toBe("petdex");
+            if (asset.sourceKind === "builtin")
+                expect(asset.atlas?.imageUrl).toMatch(/^data:image\/webp;base64,/);
+        }
+        expect(result.petAssets?.filter((pet) => pet.sourceKind === "builtin")).toHaveLength(1);
+    });
+    it("persists pet preferences through the backend pet profile", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        await handlePetPreferencesUpdate.call(host, {
+            id: "prefs",
+            method: "pet.preferences.update",
+            params: { enabled: false, selectedPetAssetId: "builtin-anime-horse-girl" },
+        });
+        const result = responses[0]?.result;
+        expect(result.profile?.preferences).toEqual({
+            enabled: false,
+            selectedPetAssetId: "builtin-anime-horse-girl",
+        });
+        expect(new PetProfileService("user/alice").loadProfile().preferences.selectedPetAssetId).toBe("builtin-anime-horse-girl");
+    });
+    it("persists and reads journey snapshots through the backend pet profile", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        const snapshot = {
+            date: "2026-06-03",
+            day: 2,
+            petName: "Blue",
+            stateLabel: "idle",
+            entries: [{ kind: "done", title: "State", detail: "Idle" }],
+        };
+        await handlePetJourneySnapshot.call(host, { id: "snap", method: "pet.journey.snapshot", params: snapshot });
+        await handlePetJourneyList.call(host, { id: "list", method: "pet.journey.list", params: {} });
+        await handlePetJourneyGet.call(host, { id: "get", method: "pet.journey.get", params: { date: "2026-06-03" } });
+        expect((responses[1]?.result).dates).toEqual(["2026-06-03"]);
+        expect((responses[2]?.result).snapshot).toEqual(snapshot);
+    });
+    it("deletes custom pets from the backend profile and clears selected custom pet", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const pet = petdexAsset();
+        new PetProfileService("user/alice").upsertCustomPet(pet);
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+            },
+        };
+        await handlePetCustomDelete.call(host, { id: "delete", method: "pet.custom.delete", params: { id: "petdex-1" } });
+        const profile = (responses[0]?.result).profile;
+        expect(profile?.customPets).toEqual([]);
+        expect(profile?.preferences?.selectedPetAssetId).toBe("builtin-anime-horse-girl");
+        expect(fs.existsSync(path.join(home, "profiles", "user%2Falice", "pet", "assets", "petdex-1"))).toBe(false);
+    });
+    it("forges a Petdex asset update without returning SVG state maps", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const responses = [];
+        const notifications = [];
+        const forgeInputs = [];
+        const mediaSetupCalls = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: (method, params) => notifications.push({ method, params }),
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            configureTurnMedia: (config, turnId) => mediaSetupCalls.push({ config, turnId }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+                forgeGeneratePetdexAtlas: async (input) => {
+                    forgeInputs.push(input);
+                    const generated = await createTestPetdexAsset({
+                        id: input.id,
+                        name: input.name,
+                        description: input.description,
+                        prompt: input.prompt,
+                        sourceKind: "forge",
+                    });
+                    return {
+                        ...generated,
+                        productionRun: {
+                            schema: "qlogic.petdex.production.v1",
+                            status: "complete",
+                            sourceMode: "text",
+                            contract: PETDEX_ATLAS_CONTRACT,
+                            jobs: [],
+                            qa: {
+                                contactSheet: { rows: 9, columns: 8, frameCount: 72 },
+                                rowReports: [],
+                            },
+                        },
+                        mediaUsage: {
+                            provider: "volcengine",
+                            model: "doubao-seedream-4-5",
+                            billingUnit: "per_call",
+                            billingQuantity: 1,
+                        },
+                    };
+                },
+            },
+        };
+        await handlePetForge.call(host, {
+            id: "forge",
+            method: "pet.forge",
+            params: { description: "round yellow desk companion" },
+        });
+        const removedSvgMapKey = "svg" + "s";
+        const result = responses[0]?.result;
+        const assetUpdate = notifications.find((item) => item.method === "pet.asset.updated");
+        const mediaUsage = notifications.find((item) => item.method === "turn.media_usage");
+        expect(mediaSetupCalls).toEqual([{ config: undefined, turnId: "pet-forge-forge" }]);
+        expect(forgeInputs).toEqual([{
+                id: undefined,
+                name: "round yell",
+                description: "round yellow desk companion",
+                prompt: "round yellow desk companion",
+            }]);
+        expect(assetUpdate?.params).toMatchObject({
+            asset: {
+                assetKind: "petdex",
+                name: "round yell",
+                atlas: {
+                    format: "webp",
+                    columns: 8,
+                    rows: 9,
+                    frameCount: 72,
+                    cellWidth: 192,
+                    cellHeight: 208,
+                },
+            },
+        });
+        expect(mediaUsage?.params).toEqual({
+            usageId: "pet-forge-forge:media:1",
+            turnId: "pet-forge-forge",
+            mediaType: "image",
+            provider: "volcengine",
+            model: "doubao-seedream-4-5",
+            billingUnit: "per_call",
+            billingQuantity: 1,
+        });
+        expect(result.asset).toMatchObject({ assetKind: "petdex", name: "round yell" });
+        expect(result.productionRun).toMatchObject({ schema: "qlogic.petdex.production.v1", status: "complete" });
+        expect(result.customPet).toBeUndefined();
+        expect(result[removedSvgMapKey]).toBeUndefined();
+        expect(result.manifest?.states).toBeUndefined();
+    });
+    it("passes uploaded images directly as image-generation references without image understanding", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const forgeInputs = [];
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => {
+                    throw new Error("image understanding must not be called");
+                },
+                forgeGeneratePetdexAtlas: async (input) => {
+                    forgeInputs.push(input);
+                    return createTestPetdexAsset({
+                        id: input.id,
+                        name: input.name,
+                        description: input.description,
+                        prompt: input.prompt,
+                        sourceKind: "forge",
+                    });
+                },
+            },
+        };
+        await handlePetForge.call(host, {
+            id: "forge-ref",
+            method: "pet.forge",
+            params: {
+                description: "Pika",
+                imageBase64: Buffer.from("uploaded-image").toString("base64"),
+                imageMimeType: "image/png",
+                imageFileName: "pikachu.png",
+            },
+        });
+        expect(responses[0]?.error).toBeUndefined();
+        expect(forgeInputs).toEqual([expect.objectContaining({
+                description: "Pika",
+                prompt: "Pika",
+                referenceImageUrl: `data:image/png;base64,${Buffer.from("uploaded-image").toString("base64")}`,
+                referenceMode: "identity",
+            })]);
+    });
+    it("returns the concrete Petdex forge failure reason", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const notifications = [];
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: (method, params) => notifications.push({ method, params }),
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+                forgeGeneratePetdexAtlas: async () => {
+                    throw new Error("Petdex row idle is visually inert");
+                },
+            },
+        };
+        await handlePetForge.call(host, {
+            id: "forge-error",
+            method: "pet.forge",
+            params: { description: "static mascot" },
+        });
+        expect(responses[0]?.error).toMatchObject({
+            message: "Petdex row idle is visually inert",
+        });
+        expect(notifications.find((item) => item.method === "pet.reaction")?.params).toMatchObject({
+            text: "Generating a Petdex 8x9 atlas...",
+            style: "thinking",
+        });
+        expect(notifications.filter((item) => item.method === "pet.reaction").at(-1)?.params).toMatchObject({
+            text: "Forge failed: Petdex row idle is visually inert",
+            style: "normal",
+        });
+    });
+    it("fails fast with setup guidance when Petdex image generation capability is unavailable", async () => {
+        const workspace = makeWorkspace();
+        const responses = [];
+        let forgeCalled = false;
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => "",
+                isImageGenerationAvailable: () => true,
+                isPetdexForgeAvailable: () => false,
+                forgeGeneratePetdexAtlas: async () => {
+                    forgeCalled = true;
+                    throw new Error("must not call forge");
+                },
+            },
+        };
+        await handlePetForge.call(host, {
+            id: "forge-no-image-model",
+            method: "pet.forge",
+            params: { description: "Bulbasaur" },
+        });
+        expect(forgeCalled).toBe(false);
+        expect(responses[0]?.error?.message).toContain("Petdex image generation is not configured");
+        expect(responses[0]?.error?.message).toContain("image-generation model");
+        expect(responses[0]?.error?.message).toContain("img2img");
+        expect(responses[0]?.error?.message).toContain("API Key");
+    });
+    it("refines an existing Petdex asset with the current spritesheet as the image reference", async () => {
+        const home = makeWorkspace();
+        const workspace = makeWorkspace();
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        const profileService = new PetProfileService("user/alice");
+        const existing = await createTestPetdexAsset({
+            id: "petdex-existing",
+            name: "Spark",
+            description: "Existing spark pet",
+            prompt: "existing spark",
+        });
+        profileService.writeCustomPetAssetFiles(existing.asset, existing.spritesheet, existing.validation);
+        const forgeInputs = [];
+        const responses = [];
+        const host = {
+            ownerUserId: "user/alice",
+            getActiveProjectRoot: () => workspace,
+            sendNotification: () => undefined,
+            sendResponse: (id, result, error) => responses.push({ id, result, error }),
+            petRuntime: {
+                createPetSoulGenerator: () => undefined,
+                createSmallLLMCall: () => undefined,
+                forgeAnalyzeImage: async () => {
+                    throw new Error("image understanding must not be called");
+                },
+                forgeGeneratePetdexAtlas: async (input) => {
+                    forgeInputs.push(input);
+                    return createTestPetdexAsset({
+                        id: input.id,
+                        name: input.name,
+                        description: input.description,
+                        prompt: input.prompt,
+                        sourceKind: "forge",
+                    });
+                },
+            },
+        };
+        await handlePetForge.call(host, {
+            id: "forge-refine",
+            method: "pet.forge",
+            params: {
+                mode: "refine",
+                basePetId: "petdex-existing",
+                description: "smaller eyes and shorter ears",
+            },
+        });
+        expect(responses[0]?.error).toBeUndefined();
+        expect(forgeInputs).toEqual([expect.objectContaining({
+                id: "petdex-existing",
+                name: "Spark",
+                prompt: "smaller eyes and shorter ears",
+                referenceImageUrl: `data:image/webp;base64,${existing.spritesheet.toString("base64")}`,
+                referenceMode: "refine",
+            })]);
+    });
+});

package/dist/cli/handlers/product-handler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Product mode handlers.
+ * Handles: product.plan/confirm/message/create/resume/pause/checkpoint/status/list/delete/cancel/rollback.
+ */
+import { type AgentRpcError, type AgentRpcRequest } from "../../protocol/wire/index.js";
+import { type ProductCoordinatorHost } from "../product-coordinator.js";
+export type { ProductCoordinatorHost } from "../product-coordinator.js";
+export interface ProductHandlerHost extends ProductCoordinatorHost {
+    getActiveProjectRoot(): string;
+    sendResponse(id: string | number, result?: unknown, error?: AgentRpcError): void;
+}
+export { productProjectMap, writeProductTerminalPlanStatus } from "../product-coordinator.js";
+export declare function ensureProductOrchestrator(this: ProductCoordinatorHost): import("../../orchestration/agent-instance.js").ProductOrchestrator;
+export declare function ensureProductPlanner(this: ProductCoordinatorHost): import("../../orchestration/product-planner.js").ProductPlanner;
+/** `product.plan` - Start interactive planning with leader agent. */
+export declare function handleProductPlan(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.confirm` - User confirms the plan, transition to execution. */
+export declare function handleProductConfirm(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.message` - User sends message to leader (multi-turn planning or execution intervention). */
+export declare function handleProductMessage(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.create` - Create a new Product Mode session. */
+export declare function handleProductCreate(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.resume` - Resume a paused product. */
+export declare function handleProductResume(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.pause` - Pause a running product. */
+export declare function handleProductPause(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.checkpoint` - Manual checkpoint. */
+export declare function handleProductCheckpoint(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.status` - Query product status. */
+export declare function handleProductStatus(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.list` - List all products. */
+export declare function handleProductList(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+export declare function handleProductDelete(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.cancel` - Cancel a running product. */
+export declare function handleProductCancel(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** `product.rollback` - Rollback a product to a checkpoint. */
+export declare function handleProductRollback(this: ProductHandlerHost, msg: AgentRpcRequest): Promise<void>;