@astrofoundry/pi-astro 0.5.1 → 0.6.1

package/extensions/gemini-image/index.ts

@@ -0,0 +1,375 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { GoogleGenAI } from "@google/genai";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "typebox";
+import { persistApiKey, resolveExistingApiKey } from "./credentials.ts";
+import {
+    ALL_MODELS,
+    DEFAULT_MODEL,
+    GEMINI_ASPECT_RATIOS,
+    GEMINI_IMAGE_SIZES,
+    IMAGEN_ASPECT_RATIOS,
+    IMAGEN_IMAGE_SIZES,
+    PERSON_GENERATION_VALUES,
+    isGeminiNative,
+    isImagen,
+    type ImageModel,
+} from "./models.ts";
+import { parseTweaks } from "./parseTweaks.ts";
+import { estimateCost, formatUsd, hasPricing } from "./pricing.ts";
+
+const DEFAULT_SAVE_SUBDIR = ".gemini-images";
+
+const params = Type.Object({
+    prompt: Type.String({ description: "Text prompt describing the image to generate." }),
+    model: Type.Optional(
+        StringEnum(ALL_MODELS as unknown as readonly [string, ...string[]], {
+            description: `Model. Default: ${DEFAULT_MODEL}.`,
+        }),
+    ),
+    aspect_ratio: Type.Optional(Type.String({ description: "Aspect ratio; validated per model family." })),
+    image_size: Type.Optional(
+        StringEnum(["1K", "2K", "4K"] as const, { description: "Output resolution. 4K is Gemini-native only." }),
+    ),
+    number_of_images: Type.Optional(
+        Type.Integer({ minimum: 1, maximum: 4, description: "Imagen only. 1-4." }),
+    ),
+    negative_prompt: Type.Optional(Type.String({ description: "Imagen only." })),
+    person_generation: Type.Optional(
+        StringEnum(PERSON_GENERATION_VALUES as unknown as readonly [string, ...string[]], {
+            description: "People policy: dont_allow | allow_adult | allow_all.",
+        }),
+    ),
+    seed: Type.Optional(Type.Integer({ description: "Imagen only. Reproducibility seed." })),
+    input_images: Type.Optional(
+        Type.Array(Type.String(), {
+            description: "Gemini native only. Absolute paths to images for editing.",
+        }),
+    ),
+    save_to: Type.Optional(
+        Type.String({ description: `Directory to save PNG(s). Default: <cwd>/${DEFAULT_SAVE_SUBDIR}/.` }),
+    ),
+    skip_confirm: Type.Optional(Type.Boolean({ description: "Skip the review/confirm prompt and call the API directly." })),
+});
+
+type Params = {
+    prompt: string;
+    model?: string;
+    aspect_ratio?: string;
+    image_size?: "1K" | "2K" | "4K";
+    number_of_images?: number;
+    negative_prompt?: string;
+    person_generation?: (typeof PERSON_GENERATION_VALUES)[number];
+    seed?: number;
+    input_images?: string[];
+    save_to?: string;
+    skip_confirm?: boolean;
+};
+
+async function ensureApiKey(ctx: ExtensionContext): Promise<string> {
+    const existing = resolveExistingApiKey();
+    if (existing) return existing;
+
+    if (!ctx.hasUI) {
+        throw new Error("Gemini API key is not configured and no interactive UI is available to ask for one.");
+    }
+
+    const pasted = await ctx.ui.input("Paste your Gemini API key:");
+    if (!pasted || !pasted.trim()) {
+        throw new Error("No API key provided.");
+    }
+    const key = pasted.trim();
+    persistApiKey(key);
+    ctx.ui.notify("Gemini API key saved.", "info");
+    return key;
+}
+
+function validateForModel(model: ImageModel, p: Params): void {
+    if (isImagen(model)) {
+        if (p.aspect_ratio && !(IMAGEN_ASPECT_RATIOS as readonly string[]).includes(p.aspect_ratio)) {
+            throw new Error(
+                `aspect_ratio "${p.aspect_ratio}" is not supported for Imagen. Valid: ${IMAGEN_ASPECT_RATIOS.join(", ")}.`,
+            );
+        }
+        if (p.image_size && !(IMAGEN_IMAGE_SIZES as readonly string[]).includes(p.image_size)) {
+            throw new Error(
+                `image_size "${p.image_size}" is not supported for Imagen. Valid: ${IMAGEN_IMAGE_SIZES.join(", ")}.`,
+            );
+        }
+        if (p.input_images && p.input_images.length > 0) {
+            throw new Error("Imagen does not support input_images (text-to-image only). Use a Gemini-native model.");
+        }
+    } else if (isGeminiNative(model)) {
+        if (p.aspect_ratio && !(GEMINI_ASPECT_RATIOS as readonly string[]).includes(p.aspect_ratio)) {
+            throw new Error(
+                `aspect_ratio "${p.aspect_ratio}" is not supported for Gemini native. Valid: ${GEMINI_ASPECT_RATIOS.join(", ")}.`,
+            );
+        }
+        if (p.image_size && !(GEMINI_IMAGE_SIZES as readonly string[]).includes(p.image_size)) {
+            throw new Error(
+                `image_size "${p.image_size}" is not supported for Gemini native. Valid: ${GEMINI_IMAGE_SIZES.join(", ")}.`,
+            );
+        }
+        if (p.number_of_images !== undefined && p.number_of_images !== 1) {
+            throw new Error("Gemini native produces a single image per call; number_of_images only applies to Imagen.");
+        }
+        if (p.negative_prompt) {
+            throw new Error("negative_prompt is Imagen-only.");
+        }
+        if (p.seed !== undefined) {
+            throw new Error("seed is Imagen-only.");
+        }
+    }
+}
+
+interface DecodedImage {
+    data: string;
+    mimeType: string;
+}
+
+async function callGeminiNative(
+    ai: GoogleGenAI,
+    model: string,
+    p: Params,
+    signal: AbortSignal | undefined,
+): Promise<DecodedImage[]> {
+    const imageConfig: Record<string, string> = {};
+    if (p.aspect_ratio) imageConfig.aspectRatio = p.aspect_ratio;
+    if (p.image_size) imageConfig.imageSize = p.image_size;
+    if (p.person_generation) imageConfig.personGeneration = p.person_generation;
+
+    const contents: Array<Record<string, unknown>> = [{ text: p.prompt }];
+    for (const path of p.input_images ?? []) {
+        const buffer = readFileSync(path);
+        const mimeType = path.toLowerCase().endsWith(".jpg") || path.toLowerCase().endsWith(".jpeg")
+            ? "image/jpeg"
+            : path.toLowerCase().endsWith(".webp")
+            ? "image/webp"
+            : "image/png";
+        contents.push({
+            inlineData: {
+                mimeType,
+                data: buffer.toString("base64"),
+            },
+        });
+    }
+
+    const response = await ai.models.generateContent({
+        model,
+        contents,
+        config: {
+            responseModalities: ["Text", "Image"],
+            ...(Object.keys(imageConfig).length > 0 ? { imageConfig } : {}),
+            ...(signal ? { abortSignal: signal } : {}),
+        },
+    });
+
+    const images: DecodedImage[] = [];
+    for (const candidate of response.candidates ?? []) {
+        for (const part of candidate.content?.parts ?? []) {
+            if (part.inlineData?.data && part.inlineData.mimeType) {
+                images.push({ data: part.inlineData.data, mimeType: part.inlineData.mimeType });
+            }
+        }
+    }
+    return images;
+}
+
+async function callImagen(
+    ai: GoogleGenAI,
+    model: string,
+    p: Params,
+    signal: AbortSignal | undefined,
+): Promise<DecodedImage[]> {
+    const config: Record<string, unknown> = {};
+    if (p.aspect_ratio) config.aspectRatio = p.aspect_ratio;
+    if (p.image_size) config.imageSize = p.image_size;
+    if (p.number_of_images !== undefined) config.numberOfImages = p.number_of_images;
+    if (p.negative_prompt) config.negativePrompt = p.negative_prompt;
+    if (p.person_generation) config.personGeneration = p.person_generation;
+    if (p.seed !== undefined) config.seed = p.seed;
+    if (signal) config.abortSignal = signal;
+
+    const response = await ai.models.generateImages({
+        model,
+        prompt: p.prompt,
+        ...(Object.keys(config).length > 0 ? { config } : {}),
+    });
+
+    const images: DecodedImage[] = [];
+    for (const generated of response.generatedImages ?? []) {
+        if (generated.image?.imageBytes) {
+            images.push({
+                data: generated.image.imageBytes,
+                mimeType: generated.image.mimeType ?? "image/png",
+            });
+        }
+    }
+    return images;
+}
+
+function saveImages(images: DecodedImage[], dir: string, prompt: string): string[] {
+    mkdirSync(dir, { recursive: true });
+    const slug =
+        prompt
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 40) || "image";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const paths: string[] = [];
+    for (let i = 0; i < images.length; i++) {
+        const ext = images[i].mimeType === "image/jpeg" ? "jpg" : "png";
+        const base = images.length > 1 ? `${slug}-${ts}-${i + 1}.${ext}` : `${slug}-${ts}.${ext}`;
+        const full = join(dir, base);
+        writeFileSync(full, Buffer.from(images[i].data, "base64"));
+        paths.push(full);
+    }
+    return paths;
+}
+
+function renderPreview(model: ImageModel, p: Params, estimate: { estimatedUsd: number; breakdown: string }): string {
+    const nImages = isImagen(model) ? p.number_of_images ?? 1 : 1;
+    const lines: string[] = [];
+    lines.push(`Model: ${model}`);
+    lines.push(`Prompt: "${p.prompt.length > 160 ? `${p.prompt.slice(0, 160)}…` : p.prompt}"`);
+    if (p.image_size) lines.push(`Size: ${p.image_size}`);
+    if (p.aspect_ratio) lines.push(`Aspect ratio: ${p.aspect_ratio}`);
+    lines.push(`Images: ${nImages}`);
+    if (p.negative_prompt) lines.push(`Negative: "${p.negative_prompt.slice(0, 80)}"`);
+    if (p.seed !== undefined) lines.push(`Seed: ${p.seed}`);
+    if (p.person_generation) lines.push(`People: ${p.person_generation}`);
+    lines.push(`Estimated: ~${formatUsd(estimate.estimatedUsd)} (${estimate.breakdown})`);
+    return lines.join(" | ");
+}
+
+async function reviewAndConfirm(
+    ctx: ExtensionContext,
+    p: Params,
+): Promise<Params> {
+    let current = { ...p };
+    while (true) {
+        const model = (current.model as ImageModel | undefined) ?? DEFAULT_MODEL;
+        const est = hasPricing(model)
+            ? estimateCost({
+                  model,
+                  prompt: current.prompt,
+                  numberOfImages: isImagen(model) ? current.number_of_images ?? 1 : 1,
+                  imageSize: current.image_size,
+              })
+            : { estimatedUsd: 0, breakdown: "unknown pricing" };
+
+        const preview = renderPreview(model, current, est);
+        const input = await ctx.ui.input(
+            "Review — Enter to confirm, type changes, or 'cancel'",
+            preview,
+        );
+        if (input === undefined) {
+            throw new Error("User cancelled image generation.");
+        }
+        const parsed = parseTweaks(input);
+        if (parsed.intent === "cancel") {
+            throw new Error("User cancelled image generation.");
+        }
+        if (parsed.intent === "confirm") {
+            return current;
+        }
+
+        // Apply patch. Re-validate before looping.
+        const next: Params = { ...current };
+        if (parsed.patch.prompt !== undefined) next.prompt = parsed.patch.prompt;
+        if (parsed.patch.model !== undefined) next.model = parsed.patch.model;
+        if (parsed.patch.aspect_ratio !== undefined) next.aspect_ratio = parsed.patch.aspect_ratio;
+        if (parsed.patch.image_size !== undefined) next.image_size = parsed.patch.image_size;
+        if (parsed.patch.number_of_images !== undefined) next.number_of_images = parsed.patch.number_of_images;
+        if (parsed.patch.negative_prompt !== undefined) next.negative_prompt = parsed.patch.negative_prompt;
+        if (parsed.patch.seed !== undefined) next.seed = parsed.patch.seed;
+        if (parsed.patch.person_generation !== undefined) next.person_generation = parsed.patch.person_generation;
+        if (parsed.patch.save_to !== undefined) next.save_to = parsed.patch.save_to;
+
+        try {
+            validateForModel((next.model as ImageModel | undefined) ?? DEFAULT_MODEL, next);
+            current = next;
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Change rejected: ${msg}`, "warning");
+        }
+
+        if (parsed.unrecognized.length > 0) {
+            ctx.ui.notify(
+                `Didn't understand: ${parsed.unrecognized.join(" ")}. Try keywords like 2K, 16:9, 'imagen ultra', 'prompt: ...'.`,
+                "warning",
+            );
+        }
+    }
+}
+
+export default function geminiImageExtension(pi: ExtensionAPI): void {
+    pi.registerTool({
+        name: "gemini_image",
+        label: "Gemini Image",
+        description:
+            "Generate or edit images via Google Gemini native and Imagen 4 models. Call this tool directly — it runs its own review/tweak/confirm gate before hitting the API, so there is no need to ask the user for a prompt or model in advance.",
+        promptGuidelines: [
+            "When the user asks to generate or edit an image, CALL THIS TOOL IMMEDIATELY. Do not ask them to confirm the prompt or model first — the tool shows a preview (prompt, model, size, estimated cost) and lets the user tweak or confirm inside its own UI.",
+            "By default, enhance the user's casual request into a stronger image-gen prompt (style, lighting, composition, detail qualifiers appropriate to what they asked for). The preview shows the final prompt so the user can catch unwanted enhancements and tweak before confirming.",
+            "If the user signals verbatim intent — wraps the prompt in backticks, or says 'as-is' / 'verbatim' / 'exactly' / 'don't change' / 'use my words' — pass the prompt UNCHANGED.",
+            "NEVER override explicit user parameters. If the user specifies model, resolution, aspect ratio, image count, negative prompt, seed, person-generation policy, or save path, pass those exact values through: 'use pro' → model=gemini-3-pro-image-preview; 'imagen ultra' → imagen-4.0-ultra-generate-001; '4K' → image_size=4K; '16:9' → aspect_ratio=16:9; 'give me 4' → number_of_images=4; 'save to <path>' → save_to=<path>.",
+            "Model selection when the user didn't specify one: gemini-2.5-flash-image for general use (default); gemini-3-pro-image-preview for studio-quality 4K, complex layouts, or precise text; imagen-4.0-*-generate-001 for batch (1-4 images per call), negative_prompt, or seeded reproducibility; image editing (input_images) is only supported by Gemini native models.",
+        ],
+        parameters: params,
+        async execute(_toolCallId, input, signal, _onUpdate, ctx) {
+            const requested = input as Params;
+            const model = (requested.model as ImageModel | undefined) ?? DEFAULT_MODEL;
+
+            if (!(ALL_MODELS as readonly string[]).includes(model)) {
+                throw new Error(`Unknown model "${model}". Valid: ${ALL_MODELS.join(", ")}.`);
+            }
+            validateForModel(model, requested);
+
+            const apiKey = await ensureApiKey(ctx);
+
+            const final = requested.skip_confirm || !ctx.hasUI
+                ? requested
+                : await reviewAndConfirm(ctx, requested);
+
+            const finalModel = (final.model as ImageModel | undefined) ?? DEFAULT_MODEL;
+
+            const ai = new GoogleGenAI({ apiKey });
+            const images = isImagen(finalModel)
+                ? await callImagen(ai, finalModel, final, signal)
+                : await callGeminiNative(ai, finalModel, final, signal);
+
+            if (images.length === 0) {
+                throw new Error("Model returned no images.");
+            }
+
+            const saveDir = final.save_to ? resolve(ctx.cwd, final.save_to) : join(ctx.cwd, DEFAULT_SAVE_SUBDIR);
+            const savedPaths = saveImages(images, saveDir, final.prompt);
+
+            const summaryLines = [
+                `Generated ${images.length} image${images.length > 1 ? "s" : ""} with ${finalModel}.`,
+                `Prompt: "${final.prompt}"`,
+            ];
+            if (final.aspect_ratio) summaryLines.push(`Aspect ratio: ${final.aspect_ratio}`);
+            if (final.image_size) summaryLines.push(`Size: ${final.image_size}`);
+            if (final.negative_prompt) summaryLines.push(`Negative: "${final.negative_prompt}"`);
+            if (final.person_generation) summaryLines.push(`People: ${final.person_generation}`);
+            if (final.seed !== undefined) summaryLines.push(`Seed: ${final.seed}`);
+            summaryLines.push(`Saved to:\n  ${savedPaths.join("\n  ")}`);
+
+            const content: AgentToolResult<unknown>["content"] = [
+                { type: "text", text: summaryLines.join("\n") },
+                ...images.map((img) => ({ type: "image" as const, data: img.data, mimeType: img.mimeType })),
+            ];
+
+            return {
+                content,
+                details: { model: finalModel, images: images.length, savedPaths },
+            };
+        },
+    });
+}

package/extensions/gemini-image/models.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import {
+    ALL_MODELS,
+    DEFAULT_MODEL,
+    GEMINI_ASPECT_RATIOS,
+    GEMINI_NATIVE_MODELS,
+    IMAGEN_ASPECT_RATIOS,
+    IMAGEN_MODELS,
+    isGeminiNative,
+    isImagen,
+} from "./models.ts";
+
+describe("models", () => {
+    it("has 3 Gemini native + 3 Imagen = 6 models", () => {
+        expect(GEMINI_NATIVE_MODELS).toHaveLength(3);
+        expect(IMAGEN_MODELS).toHaveLength(3);
+        expect(ALL_MODELS).toHaveLength(6);
+    });
+
+    it("default is gemini-2.5-flash-image", () => {
+        expect(DEFAULT_MODEL).toBe("gemini-2.5-flash-image");
+    });
+
+    it("Gemini aspect ratios include 4:5 and 5:4 (missing from the junior's impl)", () => {
+        expect(GEMINI_ASPECT_RATIOS).toContain("4:5");
+        expect(GEMINI_ASPECT_RATIOS).toContain("5:4");
+    });
+
+    it("Imagen has 5 aspect ratios (no 2:3 / 3:2 / 4:5 / 5:4 / 21:9)", () => {
+        expect(IMAGEN_ASPECT_RATIOS).toHaveLength(5);
+        expect(IMAGEN_ASPECT_RATIOS).not.toContain("2:3");
+    });
+
+    it("isGeminiNative narrows correctly", () => {
+        expect(isGeminiNative("gemini-2.5-flash-image")).toBe(true);
+        expect(isGeminiNative("imagen-4.0-generate-001")).toBe(false);
+        expect(isGeminiNative("unknown")).toBe(false);
+    });
+
+    it("isImagen narrows correctly", () => {
+        expect(isImagen("imagen-4.0-ultra-generate-001")).toBe(true);
+        expect(isImagen("gemini-3-pro-image-preview")).toBe(false);
+        expect(isImagen("unknown")).toBe(false);
+    });
+});

package/extensions/gemini-image/models.ts

@@ -0,0 +1,50 @@
+export const GEMINI_NATIVE_MODELS = [
+    "gemini-2.5-flash-image",
+    "gemini-3.1-flash-image-preview",
+    "gemini-3-pro-image-preview",
+] as const;
+
+export const IMAGEN_MODELS = [
+    "imagen-4.0-fast-generate-001",
+    "imagen-4.0-generate-001",
+    "imagen-4.0-ultra-generate-001",
+] as const;
+
+export type GeminiNativeModel = (typeof GEMINI_NATIVE_MODELS)[number];
+export type ImagenModel = (typeof IMAGEN_MODELS)[number];
+export type ImageModel = GeminiNativeModel | ImagenModel;
+
+export const ALL_MODELS: readonly ImageModel[] = [
+    ...GEMINI_NATIVE_MODELS,
+    ...IMAGEN_MODELS,
+];
+
+export const DEFAULT_MODEL: ImageModel = "gemini-2.5-flash-image";
+
+export function isGeminiNative(model: string): model is GeminiNativeModel {
+    return (GEMINI_NATIVE_MODELS as readonly string[]).includes(model);
+}
+
+export function isImagen(model: string): model is ImagenModel {
+    return (IMAGEN_MODELS as readonly string[]).includes(model);
+}
+
+export const GEMINI_ASPECT_RATIOS = [
+    "1:1",
+    "2:3",
+    "3:2",
+    "3:4",
+    "4:3",
+    "4:5",
+    "5:4",
+    "9:16",
+    "16:9",
+    "21:9",
+] as const;
+
+export const IMAGEN_ASPECT_RATIOS = ["1:1", "3:4", "4:3", "9:16", "16:9"] as const;
+
+export const GEMINI_IMAGE_SIZES = ["1K", "2K", "4K"] as const;
+export const IMAGEN_IMAGE_SIZES = ["1K", "2K"] as const;
+
+export const PERSON_GENERATION_VALUES = ["dont_allow", "allow_adult", "allow_all"] as const;

package/extensions/gemini-image/parseTweaks.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { parseTweaks } from "./parseTweaks.ts";
+
+describe("parseTweaks intent", () => {
+    it("empty string = confirm", () => {
+        expect(parseTweaks("").intent).toBe("confirm");
+        expect(parseTweaks("   ").intent).toBe("confirm");
+    });
+
+    it("'yes' / 'y' / 'go' / 'ok' / 'proceed' / 'confirm' = confirm", () => {
+        for (const word of ["yes", "y", "go", "ok", "proceed", "confirm", "YES"]) {
+            expect(parseTweaks(word).intent).toBe("confirm");
+        }
+    });
+
+    it("'cancel' / 'abort' / 'no' / 'n' / 'quit' = cancel", () => {
+        for (const word of ["cancel", "abort", "no", "n", "quit", "CANCEL"]) {
+            expect(parseTweaks(word).intent).toBe("cancel");
+        }
+    });
+});
+
+describe("parseTweaks patches", () => {
+    it("recognizes image sizes 1K / 2K / 4K", () => {
+        expect(parseTweaks("2K").patch.image_size).toBe("2K");
+        expect(parseTweaks("4K").patch.image_size).toBe("4K");
+        expect(parseTweaks("use 1K please").patch.image_size).toBe("1K");
+    });
+
+    it("recognizes aspect ratios", () => {
+        expect(parseTweaks("16:9").patch.aspect_ratio).toBe("16:9");
+        expect(parseTweaks("4:3").patch.aspect_ratio).toBe("4:3");
+    });
+
+    it("recognizes full model ids", () => {
+        expect(parseTweaks("gemini-3-pro-image-preview").patch.model).toBe("gemini-3-pro-image-preview");
+        expect(parseTweaks("imagen-4.0-ultra-generate-001").patch.model).toBe("imagen-4.0-ultra-generate-001");
+    });
+
+    it("recognizes model aliases", () => {
+        expect(parseTweaks("use pro").patch.model).toBe("gemini-3-pro-image-preview");
+        expect(parseTweaks("imagen ultra").patch.model).toBe("imagen-4.0-ultra-generate-001");
+        expect(parseTweaks("flash").patch.model).toBe("gemini-2.5-flash-image");
+        expect(parseTweaks("imagen fast").patch.model).toBe("imagen-4.0-fast-generate-001");
+    });
+
+    it("longer aliases win over shorter (e.g. 'nano banana pro' over 'pro')", () => {
+        expect(parseTweaks("nano banana pro").patch.model).toBe("gemini-3-pro-image-preview");
+    });
+
+    it("recognizes image counts", () => {
+        expect(parseTweaks("3 images").patch.number_of_images).toBe(3);
+        expect(parseTweaks("give me 4").patch.number_of_images).toBe(4);
+        expect(parseTweaks("n=2").patch.number_of_images).toBe(2);
+    });
+
+    it("clamps number_of_images to 1-4", () => {
+        expect(parseTweaks("10 images").patch.number_of_images).toBe(4);
+        expect(parseTweaks("0 images").patch.number_of_images).toBe(1);
+    });
+
+    it("recognizes prompt: form", () => {
+        expect(parseTweaks("prompt: a purple squirrel").patch.prompt).toBe("a purple squirrel");
+    });
+
+    it("recognizes 'use prompt ...' form", () => {
+        expect(parseTweaks("use prompt a purple squirrel").patch.prompt).toBe("a purple squirrel");
+    });
+
+    it("strips quotes around prompt", () => {
+        expect(parseTweaks(`prompt: "a cat"`).patch.prompt).toBe("a cat");
+        expect(parseTweaks(`prompt: 'a cat'`).patch.prompt).toBe("a cat");
+    });
+
+    it("recognizes negative_prompt", () => {
+        expect(parseTweaks("negative: blurry").patch.negative_prompt).toBe("blurry");
+        expect(parseTweaks("negative_prompt: ugly, blurry").patch.negative_prompt).toBe("ugly, blurry");
+    });
+
+    it("recognizes seed", () => {
+        expect(parseTweaks("seed: 42").patch.seed).toBe(42);
+        expect(parseTweaks("seed 1337").patch.seed).toBe(1337);
+    });
+
+    it("recognizes save to <path>", () => {
+        expect(parseTweaks("save to ./out").patch.save_to).toBe("./out");
+    });
+
+    it("recognizes verbatim / as-is / raw", () => {
+        expect(parseTweaks("verbatim").patch.verbatim).toBe(true);
+        expect(parseTweaks("as-is").patch.verbatim).toBe(true);
+        expect(parseTweaks("raw").patch.verbatim).toBe(true);
+    });
+
+    it("recognizes person_generation tokens", () => {
+        expect(parseTweaks("allow_adult").patch.person_generation).toBe("allow_adult");
+        expect(parseTweaks("dont_allow").patch.person_generation).toBe("dont_allow");
+    });
+
+    it("combines multiple changes in one utterance", () => {
+        const p = parseTweaks("use imagen ultra 16:9 3 images");
+        expect(p.patch.model).toBe("imagen-4.0-ultra-generate-001");
+        expect(p.patch.aspect_ratio).toBe("16:9");
+        expect(p.patch.number_of_images).toBe(3);
+    });
+
+    it("unrecognized tokens are returned", () => {
+        const p = parseTweaks("frobnicate plz");
+        expect(p.unrecognized.length).toBeGreaterThan(0);
+    });
+
+    it("filler words 'use', 'and', 'with' don't count as unrecognized", () => {
+        const p = parseTweaks("use 2K and 16:9 with allow_adult");
+        expect(p.unrecognized).toEqual([]);
+        expect(p.patch.image_size).toBe("2K");
+        expect(p.patch.aspect_ratio).toBe("16:9");
+        expect(p.patch.person_generation).toBe("allow_adult");
+    });
+});