oira666_pi-image-generation 0.0.4 → 0.1.0

package/README.md

@@ -1,12 +1,27 @@
 # pi-image-generation
 
-Tested against Pi 1.4.0.
+Tested against Pi 1.5.0.
 
 ```sh
 pi install npm:oira666_pi-image-generation
 ```
 
-Generate and edit PNG images with the `image_gen` tool. Without settings, the extension uses the stored `openai-codex` subscription login, as before.
+Generate and edit PNG images with GPT Image 2.6 using the `image_gen` tool. Without settings, the extension uses the stored `openai-codex` subscription login, as before.
+
+## Model selection
+
+Sunburst (`gpt-image-2.6-sunburst`) is the default for better quality. Flare (`gpt-image-2.6-flare`) is faster but lower quality. The agent should use Flare only when you explicitly ask for Flare or faster generation, never as an automatic fallback.
+
+The optional `model` argument applies to both generation and reference-image editing:
+
+```json
+{
+  "prompt": "A blue ceramic vase on a white background",
+  "model": "gpt-image-2.6-flare"
+}
+```
+
+Omit `model` to use Sunburst. The extension sends the full model ID instead of relying on the unspecified `gpt-image-2.6` alias.
 
 ## Credentials
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-image-generation",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "Image generation and reference-image editing for pi.",
   "type": "module",
   "license": "MIT",
@@ -29,14 +29,14 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=1.4.0",
+    "@earendil-works/pi-coding-agent": ">=1.5.0",
     "typebox": "*"
   },
   "dependencies": {
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
     "@types/node": "^22.0.0",
     "@types/pngjs": "^6.0.5",
     "tsx": "^4.20.0",

package/resources/imagegen/SKILL.md

@@ -17,6 +17,7 @@ Use `image_gen` for new raster artwork, image edits, and variations. The tool is
 
 ## Tool arguments
 
+- `model`: optional, either `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare`. Sunburst is the default for better quality. Flare is faster but lower quality. Use Flare only when the user explicitly asks for Flare or faster generation. Do not choose it automatically for drafts, simple images, retries, or edits, and never switch models after an error without permission.
 - `prompt`: a complete brief, up to 16,000 characters. Include exact text, reference roles, required details, and exclusions.
 - `referenced_image_paths`: one to five local PNG, JPEG, or WebP paths, in the same order used by the prompt. Relative paths use the project directory. These are uploaded to the image service for the requested edit.
 - `num_last_images_to_include`: one to five recent images from the current conversation branch. The selected images are supplied oldest first. This includes user attachments, images read by tools, and generated images. Unrelated recent images can enter this window, so explicit paths are safer for long workflows.
@@ -24,7 +25,7 @@ Use `image_gen` for new raster artwork, image edits, and variations. The tool is
 
 Choose either `referenced_image_paths` or `num_last_images_to_include`, never both. Do not pass an empty reference list. References must be at most 32 MiB each and 50 MiB combined. The tool accepts local paths, not arbitrary remote URLs.
 
-There are no separate model, size, quality, seed, mask, or batch arguments. Put framing, proportions, detail, and transparency requirements in the prompt. Do not promise exact dimensions, reproducible seeds, or pixel-perfect preservation. The backend decides the output dimensions and quality.
+There are no separate size, quality, seed, mask, or batch arguments. Put framing, proportions, detail, and transparency requirements in the prompt. Do not promise exact dimensions, reproducible seeds, or pixel-perfect preservation. The backend decides the output dimensions and quality.
 
 ## Workflow
 

package/src/backend.ts

@@ -2,7 +2,15 @@ import { randomUUID } from "node:crypto";
 import { PNG } from "pngjs";
 import type { ImageAuth } from "./auth.ts";
 
-export const IMAGE_MODEL = "gpt-image-2";
+export const IMAGE_MODELS = ["gpt-image-2.6-sunburst", "gpt-image-2.6-flare"] as const;
+export type ImageModel = typeof IMAGE_MODELS[number];
+export const DEFAULT_IMAGE_MODEL = IMAGE_MODELS[0];
+
+export function resolveImageModel(value: unknown): ImageModel {
+  if (value === undefined) return DEFAULT_IMAGE_MODEL;
+  if (value === IMAGE_MODELS[0] || value === IMAGE_MODELS[1]) return value;
+  throw new Error("Image model must be gpt-image-2.6-sunburst or gpt-image-2.6-flare.");
+}
 const BASE_URL = "https://chatgpt.com/backend-api/codex";
 const API_BASE_URL = "https://api.openai.com/v1";
 export const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
@@ -10,6 +18,7 @@ const MAX_RESPONSE_BYTES = 48 * 1024 * 1024;
 
 export interface ImageRequest {
   prompt: string;
+  model?: ImageModel;
   images?: string[];
 }
 
@@ -98,7 +107,7 @@ export async function requestImage(
   const editing = !!request.images?.length;
   const apiKeyAuth = "apiKey" in auth;
   const fields = {
-    model: IMAGE_MODEL,
+    model: resolveImageModel(request.model),
     prompt: request.prompt,
     background: "auto",
     quality: "auto",

package/src/index.ts

@@ -3,10 +3,14 @@ import { Type } from "typebox";
 import { resizeImage, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { hasImageAuth, offWarning, resolveImageAuth } from "./auth.ts";
 import { loadImageSettings } from "./settings.ts";
-import { IMAGE_MODEL, requestImage } from "./backend.ts";
+import { DEFAULT_IMAGE_MODEL, IMAGE_MODELS, requestImage, resolveImageModel } from "./backend.ts";
 import { loadReferences, prepareOutput, saveImage } from "./images.ts";
 
 const parameters = Type.Object({
+  model: Type.Optional(Type.Union([Type.Literal(IMAGE_MODELS[0]), Type.Literal(IMAGE_MODELS[1])], {
+    default: DEFAULT_IMAGE_MODEL,
+    description: "Sunburst is the default for better quality. Flare is faster but lower quality; use it only when the user explicitly asks for Flare or faster generation.",
+  })),
   prompt: Type.String({ minLength: 1, maxLength: 16000, description: "Complete image brief, including reference-image roles and details that must not change." }),
   referenced_image_paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
     minItems: 1, maxItems: 5, description: "Local PNG/JPEG/WebP references, in prompt order. Relative paths resolve against the project. Do not combine with num_last_images_to_include.",
@@ -67,11 +71,12 @@ export default function imageGeneration(pi: ExtensionAPI): void {
   const tool: ToolDefinition<typeof parameters> = {
     name: "image_gen",
     label: "Generate image",
-    description: "Generate or edit one raster image using the configured OpenAI provider or API key. Accepts up to five local or recent-conversation reference images for consistent edits and variants. Saves a new PNG and returns a preview when possible. Uses openai-codex by default; credentials can be overridden in pi-image-generation-settings.json. Reference limits: 32 MiB each, 50 MiB combined; 4-minute request timeout. Load the imagegen skill first.",
+    description: "Generate or edit one raster image using the configured OpenAI provider or API key. Accepts up to five local or recent-conversation reference images for consistent edits and variants. Saves a new PNG and returns a preview when possible. Defaults to GPT Image 2.6 Sunburst; Flare is faster but lower quality and only for explicit user requests. Uses openai-codex by default; credentials can be overridden in pi-image-generation-settings.json. Reference limits: 32 MiB each, 50 MiB combined; 4-minute request timeout. Load the imagegen skill first.",
     promptSnippet: "Generate images or edit them using local or recent image references",
     promptGuidelines: [
       "Before using image_gen, read the imagegen skill. Reuse reference images and state what must remain unchanged for consistent edits.",
       "Use image_gen for requested raster artwork, not SVG placeholders. Prefer native code edits for existing vector assets.",
+      "Default to Sunburst. Use Flare only when the user explicitly requests Flare or faster generation; it trades quality for speed. Never switch models automatically after an error.",
     ],
     parameters,
     async execute(_toolCallId, args, signal, onUpdate, ctx) {
@@ -79,6 +84,7 @@ export default function imageGeneration(pi: ExtensionAPI): void {
       const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
       requestSignal.throwIfAborted();
       if (!args.prompt.trim()) throw new Error("The image prompt must not be blank.");
+      const model = resolveImageModel(args.model);
       const settings = await settingsFor(ctx);
       if (!hasImageAuth(settings, ctx.modelRegistry)) throw new Error(offWarning(settings) + " Check your image generation settings and login, then /reload.");
       const path = await prepareOutput(ctx.cwd, args.output_path);
@@ -89,7 +95,7 @@ export default function imageGeneration(pi: ExtensionAPI): void {
 
       let result;
       try {
-        result = await requestImage(auth, { prompt: args.prompt, images }, requestSignal);
+        result = await requestImage(auth, { prompt: args.prompt, images, model }, requestSignal);
       } catch (error) {
         if (timeout.aborted && !signal?.aborted) {
           throw new Error("Image generation timed out after four minutes. It may still have consumed image allowance; no automatic retry was made.");
@@ -121,7 +127,7 @@ export default function imageGeneration(pi: ExtensionAPI): void {
         details: {
           savedPath,
           prompt: args.prompt,
-          model: IMAGE_MODEL,
+          model,
           operation: images.length ? "edit" : "generate",
           referenceCount: images.length,
         },