@code-yeongyu/senpi 2026.9.9 → 2026.9.10

package/dist/core/extensions/builtin/imagegen/params.d.ts

@@ -0,0 +1,45 @@
+import { Type } from "typebox";
+export declare const DEFAULT_IMAGE_MODEL = "gpt-image-2.5-sunburst";
+export declare const IMAGE_MODEL_NAMES: {
+    readonly "gpt-image-2.5-sunburst": "GPT Image 2.5 Sunburst";
+    readonly "gpt-image-2.5-flare": "GPT Image 2.5 Flare";
+    readonly "gpt-image-2": "GPT Image 2";
+};
+export declare const Params: Type.TObject<{
+    prompt: Type.TString;
+    model: Type.TOptional<Type.TUnion<[Type.TLiteral<"gpt-image-2.5-sunburst">, Type.TLiteral<"gpt-image-2.5-flare">, Type.TLiteral<"gpt-image-2">]>>;
+    size: Type.TOptional<Type.TString>;
+    quality: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">, Type.TLiteral<"max">]>>;
+    reference_image_paths: Type.TOptional<Type.TArray<Type.TString>>;
+    mask_image_path: Type.TOptional<Type.TString>;
+    background: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"transparent">, Type.TLiteral<"opaque">]>>;
+    output_format: Type.TOptional<Type.TUnion<[Type.TLiteral<"png">, Type.TLiteral<"jpeg">, Type.TLiteral<"webp">]>>;
+    output_compression: Type.TOptional<Type.TInteger>;
+    moderation: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"low">]>>;
+    n: Type.TOptional<Type.TInteger>;
+    output_path: Type.TOptional<Type.TString>;
+}>;
+export interface GenerateImageDetails {
+    paths: string[];
+    model: string;
+    source: string;
+    size: string;
+    quality: string;
+    background: string;
+    outputFormat: string;
+    requested: number;
+    generated: number;
+    revisedPrompts: string[];
+    /** Provider-reported transparency of the saved images, when it reports one. */
+    transparentBackground?: boolean;
+    error?: string;
+    reason?: "missing_config" | "provider_native_bypass" | "invalid_params" | "write_failed" | "provider_error";
+}
+export declare function failure(message: string, reason: NonNullable<GenerateImageDetails["reason"]>, base: Pick<GenerateImageDetails, "model" | "size" | "quality" | "background" | "outputFormat" | "requested" | "source">): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: GenerateImageDetails;
+};
+//# sourceMappingURL=params.d.ts.map

package/dist/core/extensions/builtin/imagegen/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/params.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAC5D,eAAO,MAAM,iBAAiB;aAC7B,wBAAwB,EAAE,wBAAwB;aAClD,qBAAqB,EAAE,qBAAqB;aAC5C,aAAa,EAAE,aAAa;CACnB,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;;;;;EAoGlB,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+EAA+E;IAC/E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,GAAG,wBAAwB,GAAG,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,CAAC;CAC5G;AAED,wBAAgB,OAAO,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,EACnD,IAAI,EAAE,IAAI,CACT,oBAAoB,EACpB,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,QAAQ,CACrF;;cAU0B,MAAM;;;;EACjC"}

package/dist/core/extensions/builtin/imagegen/params.js

@@ -0,0 +1,81 @@
+import { Type } from "typebox";
+export const DEFAULT_IMAGE_MODEL = "gpt-image-2.5-sunburst";
+export const IMAGE_MODEL_NAMES = {
+    "gpt-image-2.5-sunburst": "GPT Image 2.5 Sunburst",
+    "gpt-image-2.5-flare": "GPT Image 2.5 Flare",
+    "gpt-image-2": "GPT Image 2",
+};
+export const Params = Type.Object({
+    prompt: Type.String({
+        minLength: 1,
+        maxLength: 32_000,
+        description: "Detailed description of the desired image, including the end state for edits.",
+    }),
+    model: Type.Optional(Type.Union([Type.Literal("gpt-image-2.5-sunburst"), Type.Literal("gpt-image-2.5-flare"), Type.Literal("gpt-image-2")], {
+        default: DEFAULT_IMAGE_MODEL,
+        description: "Sunburst (default) is the most capable: highest quality, precise edits, reference fidelity, best for final assets; Flare is the small model optimized for speed, with quality comparable to gpt-image-2; gpt-image-2 is the previous generation.",
+    })),
+    size: Type.Optional(Type.String({
+        default: "auto",
+        description: "auto, 1024x1024, 1536x1024, 1024x1536, or any WIDTHxHEIGHT with both divisible by 16, aspect between 1:3 and 3:1, max 3840x2160 (e.g. 2048x2048, 2048x1152, 3840x2160)",
+    })),
+    quality: Type.Optional(Type.Union([
+        Type.Literal("auto"),
+        Type.Literal("low"),
+        Type.Literal("medium"),
+        Type.Literal("high"),
+        Type.Literal("xhigh"),
+        Type.Literal("max"),
+    ], {
+        default: "auto",
+        description: "Rendering quality. Defaults to auto. xhigh/max are gpt-image-2.5 only, slower and costlier.",
+    })),
+    reference_image_paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+        minItems: 1,
+        maxItems: 5,
+        description: "Local PNG/JPEG/WEBP images to edit or use as references (1-5 files, each at most 50 MB). Paths may be absolute or relative to the working directory.",
+    })),
+    mask_image_path: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Inpainting mask (PNG with an alpha channel, same size as the first reference image): transparent areas are repainted. Requires reference_image_paths.",
+    })),
+    background: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("transparent"), Type.Literal("opaque")], {
+        default: "auto",
+        description: "Output background. transparent needs output_format png or webp and keeps the alpha channel; auto lets the model decide.",
+    })),
+    output_format: Type.Optional(Type.Union([Type.Literal("png"), Type.Literal("jpeg"), Type.Literal("webp")], {
+        default: "png",
+        description: "File format. png (default) is lossless and supports transparency; jpeg is fastest; webp is small and supports transparency.",
+    })),
+    output_compression: Type.Optional(Type.Integer({
+        minimum: 0,
+        maximum: 100,
+        description: "Compression level 0-100 for jpeg or webp output only (100 = best quality).",
+    })),
+    moderation: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("low")], {
+        default: "auto",
+        description: "Content filter strictness: auto (standard) or low (less restrictive).",
+    })),
+    n: Type.Optional(Type.Integer({
+        minimum: 1,
+        maximum: 10,
+        default: 1,
+        description: "How many variants of this one prompt to generate; distinct assets need distinct calls.",
+    })),
+    output_path: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Where to write the image, relative to the working directory. The extension must match output_format (.png, .jpg/.jpeg, .webp) or be omitted. Defaults to generated-images/.",
+    })),
+}, { additionalProperties: false });
+export function failure(message, reason, base) {
+    const details = {
+        ...base,
+        paths: [],
+        generated: 0,
+        revisedPrompts: [],
+        error: message,
+        reason,
+    };
+    return { content: [{ type: "text", text: message }], details };
+}
+//# sourceMappingURL=params.js.map

package/dist/core/extensions/builtin/imagegen/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/params.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC,wBAAwB,EAAE,wBAAwB;IAClD,qBAAqB,EAAE,qBAAqB;IAC5C,aAAa,EAAE,aAAa;CACnB,CAAC;AAEX,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAChC;IACC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;QACnB,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,MAAM;QACjB,WAAW,EAAE,+EAA+E;KAC5F,CAAC;IACF,KAAK,EAAE,IAAI,CAAC,QAAQ,CACnB,IAAI,CAAC,KAAK,CACT,CAAC,IAAI,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,EAC1G;QACC,OAAO,EAAE,mBAAmB;QAC5B,WAAW,EACV,kPAAkP;KACnP,CACD,CACD;IACD,IAAI,EAAE,IAAI,CAAC,QAAQ,CAClB,IAAI,CAAC,MAAM,CAAC;QACX,OAAO,EAAE,MAAM;QACf,WAAW,EACV,wKAAwK;KACzK,CAAC,CACF;IACD,OAAO,EAAE,IAAI,CAAC,QAAQ,CACrB,IAAI,CAAC,KAAK,CACT;QACC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;QACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;KACnB,EACD;QACC,OAAO,EAAE,MAAM;QACf,WAAW,EACV,6FAA6F;KAC9F,CACD,CACD;IACD,qBAAqB,EAAE,IAAI,CAAC,QAAQ,CACnC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE;QACzC,QAAQ,EAAE,CAAC;QACX,QAAQ,EAAE,CAAC;QACX,WAAW,EACV,sJAAsJ;KACvJ,CAAC,CACF;IACD,eAAe,EAAE,IAAI,CAAC,QAAQ,CAC7B,IAAI,CAAC,MAAM,CAAC;QACX,SAAS,EAAE,CAAC;QACZ,WAAW,EACV,uJAAuJ;KACxJ,CAAC,CACF;IACD,UAAU,EAAE,IAAI,CAAC,QAAQ,CACxB,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE;QACvF,OAAO,EAAE,MAAM;QACf,WAAW,EACV,yHAAyH;KAC1H,CAAC,CACF;IACD,aAAa,EAAE,IAAI,CAAC,QAAQ,CAC3B,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE;QAC7E,OAAO,EAAE,KAAK;QACd,WAAW,EACV,6HAA6H;KAC9H,CAAC,CACF;IACD,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAChC,IAAI,CAAC,OAAO,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,GAAG;QACZ,WAAW,EAAE,4EAA4E;KACzF,CAAC,CACF;IACD,UAAU,EAAE,IAAI,CAAC,QAAQ,CACxB,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE;QACvD,OAAO,EAAE,MAAM;QACf,WAAW,EAAE,uEAAuE;KACpF,CAAC,CACF;IACD,CAAC,EAAE,IAAI,CAAC,QAAQ,CACf,IAAI,CAAC,OAAO,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,wFAAwF;KACrG,CAAC,CACF;IACD,WAAW,EAAE,IAAI,CAAC,QAAQ,CACzB,IAAI,CAAC,MAAM,CAAC;QACX,SAAS,EAAE,CAAC;QACZ,WAAW,EACV,6KAA6K;KAC9K,CAAC,CACF;CACD,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAmBF,MAAM,UAAU,OAAO,CACtB,OAAe,EACf,MAAmD,EACnD,IAGC;IAED,MAAM,OAAO,GAAyB;QACrC,GAAG,IAAI;QACP,KAAK,EAAE,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,cAAc,EAAE,EAAE;QAClB,KAAK,EAAE,OAAO;QACd,MAAM;KACN,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;AACzE,CAAC","sourcesContent":["import { Type } from \"typebox\";\n\nexport const DEFAULT_IMAGE_MODEL = \"gpt-image-2.5-sunburst\";\nexport const IMAGE_MODEL_NAMES = {\n\t\"gpt-image-2.5-sunburst\": \"GPT Image 2.5 Sunburst\",\n\t\"gpt-image-2.5-flare\": \"GPT Image 2.5 Flare\",\n\t\"gpt-image-2\": \"GPT Image 2\",\n} as const;\n\nexport const Params = Type.Object(\n\t{\n\t\tprompt: Type.String({\n\t\t\tminLength: 1,\n\t\t\tmaxLength: 32_000,\n\t\t\tdescription: \"Detailed description of the desired image, including the end state for edits.\",\n\t\t}),\n\t\tmodel: Type.Optional(\n\t\t\tType.Union(\n\t\t\t\t[Type.Literal(\"gpt-image-2.5-sunburst\"), Type.Literal(\"gpt-image-2.5-flare\"), Type.Literal(\"gpt-image-2\")],\n\t\t\t\t{\n\t\t\t\t\tdefault: DEFAULT_IMAGE_MODEL,\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"Sunburst (default) is the most capable: highest quality, precise edits, reference fidelity, best for final assets; Flare is the small model optimized for speed, with quality comparable to gpt-image-2; gpt-image-2 is the previous generation.\",\n\t\t\t\t},\n\t\t\t),\n\t\t),\n\t\tsize: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdefault: \"auto\",\n\t\t\t\tdescription:\n\t\t\t\t\t\"auto, 1024x1024, 1536x1024, 1024x1536, or any WIDTHxHEIGHT with both divisible by 16, aspect between 1:3 and 3:1, max 3840x2160 (e.g. 2048x2048, 2048x1152, 3840x2160)\",\n\t\t\t}),\n\t\t),\n\t\tquality: Type.Optional(\n\t\t\tType.Union(\n\t\t\t\t[\n\t\t\t\t\tType.Literal(\"auto\"),\n\t\t\t\t\tType.Literal(\"low\"),\n\t\t\t\t\tType.Literal(\"medium\"),\n\t\t\t\t\tType.Literal(\"high\"),\n\t\t\t\t\tType.Literal(\"xhigh\"),\n\t\t\t\t\tType.Literal(\"max\"),\n\t\t\t\t],\n\t\t\t\t{\n\t\t\t\t\tdefault: \"auto\",\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"Rendering quality. Defaults to auto. xhigh/max are gpt-image-2.5 only, slower and costlier.\",\n\t\t\t\t},\n\t\t\t),\n\t\t),\n\t\treference_image_paths: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1 }), {\n\t\t\t\tminItems: 1,\n\t\t\t\tmaxItems: 5,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Local PNG/JPEG/WEBP images to edit or use as references (1-5 files, each at most 50 MB). Paths may be absolute or relative to the working directory.\",\n\t\t\t}),\n\t\t),\n\t\tmask_image_path: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tminLength: 1,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Inpainting mask (PNG with an alpha channel, same size as the first reference image): transparent areas are repainted. Requires reference_image_paths.\",\n\t\t\t}),\n\t\t),\n\t\tbackground: Type.Optional(\n\t\t\tType.Union([Type.Literal(\"auto\"), Type.Literal(\"transparent\"), Type.Literal(\"opaque\")], {\n\t\t\t\tdefault: \"auto\",\n\t\t\t\tdescription:\n\t\t\t\t\t\"Output background. transparent needs output_format png or webp and keeps the alpha channel; auto lets the model decide.\",\n\t\t\t}),\n\t\t),\n\t\toutput_format: Type.Optional(\n\t\t\tType.Union([Type.Literal(\"png\"), Type.Literal(\"jpeg\"), Type.Literal(\"webp\")], {\n\t\t\t\tdefault: \"png\",\n\t\t\t\tdescription:\n\t\t\t\t\t\"File format. png (default) is lossless and supports transparency; jpeg is fastest; webp is small and supports transparency.\",\n\t\t\t}),\n\t\t),\n\t\toutput_compression: Type.Optional(\n\t\t\tType.Integer({\n\t\t\t\tminimum: 0,\n\t\t\t\tmaximum: 100,\n\t\t\t\tdescription: \"Compression level 0-100 for jpeg or webp output only (100 = best quality).\",\n\t\t\t}),\n\t\t),\n\t\tmoderation: Type.Optional(\n\t\t\tType.Union([Type.Literal(\"auto\"), Type.Literal(\"low\")], {\n\t\t\t\tdefault: \"auto\",\n\t\t\t\tdescription: \"Content filter strictness: auto (standard) or low (less restrictive).\",\n\t\t\t}),\n\t\t),\n\t\tn: Type.Optional(\n\t\t\tType.Integer({\n\t\t\t\tminimum: 1,\n\t\t\t\tmaximum: 10,\n\t\t\t\tdefault: 1,\n\t\t\t\tdescription: \"How many variants of this one prompt to generate; distinct assets need distinct calls.\",\n\t\t\t}),\n\t\t),\n\t\toutput_path: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tminLength: 1,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Where to write the image, relative to the working directory. The extension must match output_format (.png, .jpg/.jpeg, .webp) or be omitted. Defaults to generated-images/.\",\n\t\t\t}),\n\t\t),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport interface GenerateImageDetails {\n\tpaths: string[];\n\tmodel: string;\n\tsource: string;\n\tsize: string;\n\tquality: string;\n\tbackground: string;\n\toutputFormat: string;\n\trequested: number;\n\tgenerated: number;\n\trevisedPrompts: string[];\n\t/** Provider-reported transparency of the saved images, when it reports one. */\n\ttransparentBackground?: boolean;\n\terror?: string;\n\treason?: \"missing_config\" | \"provider_native_bypass\" | \"invalid_params\" | \"write_failed\" | \"provider_error\";\n}\n\nexport function failure(\n\tmessage: string,\n\treason: NonNullable<GenerateImageDetails[\"reason\"]>,\n\tbase: Pick<\n\t\tGenerateImageDetails,\n\t\t\"model\" | \"size\" | \"quality\" | \"background\" | \"outputFormat\" | \"requested\" | \"source\"\n\t>,\n) {\n\tconst details: GenerateImageDetails = {\n\t\t...base,\n\t\tpaths: [],\n\t\tgenerated: 0,\n\t\trevisedPrompts: [],\n\t\terror: message,\n\t\treason,\n\t};\n\treturn { content: [{ type: \"text\" as const, text: message }], details };\n}\n"]}

package/dist/core/extensions/builtin/imagegen/paths.d.ts

@@ -1,4 +1,5 @@
 export declare const GENERATED_IMAGE_DIRECTORY = "generated-images";
+export type OutputFormat = "png" | "jpeg" | "webp";
 export type TargetPaths = {
     ok: true;
     paths: string[];
@@ -16,11 +17,16 @@ export declare function sanitizeImageStem(identifier: string): string;
  * Resolves the absolute destination paths for a generation call.
  *
  * A relative output_path resolves against the working directory. An omitted path
- * falls back to generated-images/<sanitized tool call id>.png. An extensionless
- * path gains .png; any other extension is rejected. With more than one image a
- * zero-padded index is inserted before the extension.
+ * falls back to generated-images/<sanitized tool call id> with the format's
+ * extension. An extensionless path gains that extension; an extension that does
+ * not belong to the format is rejected (.jpg and .jpeg both serve jpeg). With more
+ * than one image a zero-padded index is inserted before the extension.
  */
-export declare function resolveTargets(cwd: string, toolCallId: string, count: number, outputPath: string | undefined): TargetPaths;
+export declare function resolveTargets(cwd: string, toolCallId: string, count: number, outputPath: string | undefined, outputFormat?: OutputFormat): TargetPaths;
+/** The output format a returned MIME type denotes, or undefined for anything outside the supported three. */
+export declare function outputFormatOf(mimeType: string): OutputFormat | undefined;
+/** Swaps a target's extension so the file name matches the bytes a provider actually returned. */
+export declare function withFormatExtension(path: string, outputFormat: OutputFormat): string;
 /** Prefers a path relative to the working directory, falling back to absolute. */
 export declare function displayPath(cwd: string, absolute: string): string;
 //# sourceMappingURL=paths.d.ts.map

package/dist/core/extensions/builtin/imagegen/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/paths.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAI5D,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG5D;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GAAG,SAAS,GAC5B,WAAW,CAmBb;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjE"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/paths.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAI5D,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAOnD,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG5D;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,GAAE,YAAoB,GAChC,WAAW,CA2Bb;AAED,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAKzE;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAMpF;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjE"}

package/dist/core/extensions/builtin/imagegen/paths.js

@@ -2,6 +2,11 @@ import { isAbsolute, relative, resolve } from "node:path";
 export const GENERATED_IMAGE_DIRECTORY = "generated-images";
 const DEFAULT_DIRECTORY = GENERATED_IMAGE_DIRECTORY;
 const MAX_TOOL_CALL_ID_CHARS = 64;
+const EXTENSIONS = {
+    png: [".png"],
+    jpeg: [".jpg", ".jpeg"],
+    webp: [".webp"],
+};
 /**
  * Reduces a provider-supplied identifier to a safe file stem: path separators and
  * any other unexpected character collapse to `_`, the result is length-capped, and
@@ -18,32 +23,60 @@ function sanitizeToolCallId(toolCallId) {
  * Resolves the absolute destination paths for a generation call.
  *
  * A relative output_path resolves against the working directory. An omitted path
- * falls back to generated-images/<sanitized tool call id>.png. An extensionless
- * path gains .png; any other extension is rejected. With more than one image a
- * zero-padded index is inserted before the extension.
+ * falls back to generated-images/<sanitized tool call id> with the format's
+ * extension. An extensionless path gains that extension; an extension that does
+ * not belong to the format is rejected (.jpg and .jpeg both serve jpeg). With more
+ * than one image a zero-padded index is inserted before the extension.
  */
-export function resolveTargets(cwd, toolCallId, count, outputPath) {
+export function resolveTargets(cwd, toolCallId, count, outputPath, outputFormat = "png") {
+    const allowed = EXTENSIONS[outputFormat];
+    const defaultExtension = allowed[0] ?? ".png";
     const requested = outputPath?.trim();
     let base;
+    let extension;
     if (requested === undefined || requested.length === 0) {
-        base = resolve(cwd, DEFAULT_DIRECTORY, `${sanitizeToolCallId(toolCallId)}.png`);
+        base = resolve(cwd, DEFAULT_DIRECTORY, `${sanitizeToolCallId(toolCallId)}${defaultExtension}`);
+        extension = defaultExtension;
     }
     else {
         const absolute = isAbsolute(requested) ? requested : resolve(cwd, requested);
         const extensionMatch = /\.[^./\\]+$/.exec(absolute);
-        if (extensionMatch && extensionMatch[0].toLowerCase() !== ".png") {
-            return { ok: false, error: `Error: output_path must end in .png (got "${requested}").` };
+        if (extensionMatch && !allowed.includes(extensionMatch[0].toLowerCase())) {
+            return {
+                ok: false,
+                error: `Error: output_path must end in ${allowed.join(" or ")} for output_format ${outputFormat} (got "${requested}").`,
+            };
         }
-        base = extensionMatch ? absolute : `${absolute}.png`;
+        extension = extensionMatch ? extensionMatch[0] : defaultExtension;
+        base = extensionMatch ? absolute : `${absolute}${defaultExtension}`;
     }
     if (count === 1)
         return { ok: true, paths: [base] };
-    const stem = base.slice(0, -".png".length);
+    const stem = base.slice(0, -extension.length);
     return {
         ok: true,
-        paths: Array.from({ length: count }, (_, index) => `${stem}-${String(index + 1).padStart(2, "0")}.png`),
+        paths: Array.from({ length: count }, (_, index) => `${stem}-${String(index + 1).padStart(2, "0")}${extension}`),
     };
 }
+/** The output format a returned MIME type denotes, or undefined for anything outside the supported three. */
+export function outputFormatOf(mimeType) {
+    if (mimeType === "image/png")
+        return "png";
+    if (mimeType === "image/jpeg")
+        return "jpeg";
+    if (mimeType === "image/webp")
+        return "webp";
+    return undefined;
+}
+/** Swaps a target's extension so the file name matches the bytes a provider actually returned. */
+export function withFormatExtension(path, outputFormat) {
+    const extension = EXTENSIONS[outputFormat][0] ?? ".png";
+    const extensionMatch = /\.[^./\\]+$/.exec(path);
+    const current = extensionMatch?.[0].toLowerCase();
+    if (current !== undefined && EXTENSIONS[outputFormat].includes(current))
+        return path;
+    return extensionMatch ? `${path.slice(0, -extensionMatch[0].length)}${extension}` : `${path}${extension}`;
+}
 /** Prefers a path relative to the working directory, falling back to absolute. */
 export function displayPath(cwd, absolute) {
     const relativePath = relative(cwd, absolute);

package/dist/core/extensions/builtin/imagegen/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,CAAC,MAAM,yBAAyB,GAAG,kBAAkB,CAAC;AAC5D,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AACpD,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAIlC;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IACnD,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;IAC9F,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACnD,CAAC;AAED,SAAS,kBAAkB,CAAC,UAAkB;IAC7C,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC7B,GAAW,EACX,UAAkB,EAClB,KAAa,EACb,UAA8B;IAE9B,MAAM,SAAS,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IACrC,IAAI,IAAY,CAAC;IACjB,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,iBAAiB,EAAE,GAAG,kBAAkB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjF,CAAC;SAAM,CAAC;QACP,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC7E,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,cAAc,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6CAA6C,SAAS,KAAK,EAAE,CAAC;QAC1F,CAAC;QACD,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,MAAM,CAAC;IACtD,CAAC;IACD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO;QACN,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC;KACvG,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,QAAgB;IACxD,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC7C,OAAO,YAAY,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC9G,CAAC","sourcesContent":["import { isAbsolute, relative, resolve } from \"node:path\";\n\nexport const GENERATED_IMAGE_DIRECTORY = \"generated-images\";\nconst DEFAULT_DIRECTORY = GENERATED_IMAGE_DIRECTORY;\nconst MAX_TOOL_CALL_ID_CHARS = 64;\n\nexport type TargetPaths = { ok: true; paths: string[] } | { ok: false; error: string };\n\n/**\n * Reduces a provider-supplied identifier to a safe file stem: path separators and\n * any other unexpected character collapse to `_`, the result is length-capped, and\n * an identifier that sanitizes to nothing falls back to `image`.\n */\nexport function sanitizeImageStem(identifier: string): string {\n\tconst sanitized = identifier.replace(/[^A-Za-z0-9_-]/g, \"_\").slice(0, MAX_TOOL_CALL_ID_CHARS);\n\treturn sanitized.length > 0 ? sanitized : \"image\";\n}\n\nfunction sanitizeToolCallId(toolCallId: string): string {\n\treturn sanitizeImageStem(toolCallId);\n}\n\n/**\n * Resolves the absolute destination paths for a generation call.\n *\n * A relative output_path resolves against the working directory. An omitted path\n * falls back to generated-images/<sanitized tool call id>.png. An extensionless\n * path gains .png; any other extension is rejected. With more than one image a\n * zero-padded index is inserted before the extension.\n */\nexport function resolveTargets(\n\tcwd: string,\n\ttoolCallId: string,\n\tcount: number,\n\toutputPath: string | undefined,\n): TargetPaths {\n\tconst requested = outputPath?.trim();\n\tlet base: string;\n\tif (requested === undefined || requested.length === 0) {\n\t\tbase = resolve(cwd, DEFAULT_DIRECTORY, `${sanitizeToolCallId(toolCallId)}.png`);\n\t} else {\n\t\tconst absolute = isAbsolute(requested) ? requested : resolve(cwd, requested);\n\t\tconst extensionMatch = /\\.[^./\\\\]+$/.exec(absolute);\n\t\tif (extensionMatch && extensionMatch[0].toLowerCase() !== \".png\") {\n\t\t\treturn { ok: false, error: `Error: output_path must end in .png (got \"${requested}\").` };\n\t\t}\n\t\tbase = extensionMatch ? absolute : `${absolute}.png`;\n\t}\n\tif (count === 1) return { ok: true, paths: [base] };\n\tconst stem = base.slice(0, -\".png\".length);\n\treturn {\n\t\tok: true,\n\t\tpaths: Array.from({ length: count }, (_, index) => `${stem}-${String(index + 1).padStart(2, \"0\")}.png`),\n\t};\n}\n\n/** Prefers a path relative to the working directory, falling back to absolute. */\nexport function displayPath(cwd: string, absolute: string): string {\n\tconst relativePath = relative(cwd, absolute);\n\treturn relativePath && !relativePath.startsWith(\"..\") && !isAbsolute(relativePath) ? relativePath : absolute;\n}\n"]}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/paths.ts"],"names":[],"mappings":"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","sourcesContent":["import { isAbsolute, relative, resolve } from \"node:path\";\n\nexport const GENERATED_IMAGE_DIRECTORY = \"generated-images\";\nconst DEFAULT_DIRECTORY = GENERATED_IMAGE_DIRECTORY;\nconst MAX_TOOL_CALL_ID_CHARS = 64;\n\nexport type OutputFormat = \"png\" | \"jpeg\" | \"webp\";\nconst EXTENSIONS: Record<OutputFormat, readonly string[]> = {\n\tpng: [\".png\"],\n\tjpeg: [\".jpg\", \".jpeg\"],\n\twebp: [\".webp\"],\n};\n\nexport type TargetPaths = { ok: true; paths: string[] } | { ok: false; error: string };\n\n/**\n * Reduces a provider-supplied identifier to a safe file stem: path separators and\n * any other unexpected character collapse to `_`, the result is length-capped, and\n * an identifier that sanitizes to nothing falls back to `image`.\n */\nexport function sanitizeImageStem(identifier: string): string {\n\tconst sanitized = identifier.replace(/[^A-Za-z0-9_-]/g, \"_\").slice(0, MAX_TOOL_CALL_ID_CHARS);\n\treturn sanitized.length > 0 ? sanitized : \"image\";\n}\n\nfunction sanitizeToolCallId(toolCallId: string): string {\n\treturn sanitizeImageStem(toolCallId);\n}\n\n/**\n * Resolves the absolute destination paths for a generation call.\n *\n * A relative output_path resolves against the working directory. An omitted path\n * falls back to generated-images/<sanitized tool call id> with the format's\n * extension. An extensionless path gains that extension; an extension that does\n * not belong to the format is rejected (.jpg and .jpeg both serve jpeg). With more\n * than one image a zero-padded index is inserted before the extension.\n */\nexport function resolveTargets(\n\tcwd: string,\n\ttoolCallId: string,\n\tcount: number,\n\toutputPath: string | undefined,\n\toutputFormat: OutputFormat = \"png\",\n): TargetPaths {\n\tconst allowed = EXTENSIONS[outputFormat];\n\tconst defaultExtension = allowed[0] ?? \".png\";\n\tconst requested = outputPath?.trim();\n\tlet base: string;\n\tlet extension: string;\n\tif (requested === undefined || requested.length === 0) {\n\t\tbase = resolve(cwd, DEFAULT_DIRECTORY, `${sanitizeToolCallId(toolCallId)}${defaultExtension}`);\n\t\textension = defaultExtension;\n\t} else {\n\t\tconst absolute = isAbsolute(requested) ? requested : resolve(cwd, requested);\n\t\tconst extensionMatch = /\\.[^./\\\\]+$/.exec(absolute);\n\t\tif (extensionMatch && !allowed.includes(extensionMatch[0].toLowerCase())) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: `Error: output_path must end in ${allowed.join(\" or \")} for output_format ${outputFormat} (got \"${requested}\").`,\n\t\t\t};\n\t\t}\n\t\textension = extensionMatch ? extensionMatch[0] : defaultExtension;\n\t\tbase = extensionMatch ? absolute : `${absolute}${defaultExtension}`;\n\t}\n\tif (count === 1) return { ok: true, paths: [base] };\n\tconst stem = base.slice(0, -extension.length);\n\treturn {\n\t\tok: true,\n\t\tpaths: Array.from({ length: count }, (_, index) => `${stem}-${String(index + 1).padStart(2, \"0\")}${extension}`),\n\t};\n}\n\n/** The output format a returned MIME type denotes, or undefined for anything outside the supported three. */\nexport function outputFormatOf(mimeType: string): OutputFormat | undefined {\n\tif (mimeType === \"image/png\") return \"png\";\n\tif (mimeType === \"image/jpeg\") return \"jpeg\";\n\tif (mimeType === \"image/webp\") return \"webp\";\n\treturn undefined;\n}\n\n/** Swaps a target's extension so the file name matches the bytes a provider actually returned. */\nexport function withFormatExtension(path: string, outputFormat: OutputFormat): string {\n\tconst extension = EXTENSIONS[outputFormat][0] ?? \".png\";\n\tconst extensionMatch = /\\.[^./\\\\]+$/.exec(path);\n\tconst current = extensionMatch?.[0].toLowerCase();\n\tif (current !== undefined && EXTENSIONS[outputFormat].includes(current)) return path;\n\treturn extensionMatch ? `${path.slice(0, -extensionMatch[0].length)}${extension}` : `${path}${extension}`;\n}\n\n/** Prefers a path relative to the working directory, falling back to absolute. */\nexport function displayPath(cwd: string, absolute: string): string {\n\tconst relativePath = relative(cwd, absolute);\n\treturn relativePath && !relativePath.startsWith(\"..\") && !isAbsolute(relativePath) ? relativePath : absolute;\n}\n"]}

package/dist/core/extensions/builtin/imagegen/reference-images.d.ts

@@ -0,0 +1,20 @@
+import type { ImageContent } from "@earendil-works/pi-ai/compat";
+type ReferenceImages = {
+    ok: true;
+    images: ImageContent[];
+} | {
+    ok: false;
+    error: string;
+};
+type LoadedImage = {
+    ok: true;
+    image: ImageContent;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function loadReferenceImages(cwd: string, paths: string[] | undefined): Promise<ReferenceImages>;
+/** The inpainting mask is one more local image, bound to the first reference by the API. */
+export declare function loadMaskImage(cwd: string, path: string | undefined, referenceCount: number): Promise<LoadedImage | undefined>;
+export {};
+//# sourceMappingURL=reference-images.d.ts.map

package/dist/core/extensions/builtin/imagegen/reference-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-images.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/reference-images.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAQjE,KAAK,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3F,KAAK,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiCpF,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAY5G;AAED,4FAA4F;AAC5F,wBAAsB,aAAa,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,cAAc,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAMlC"}

package/dist/core/extensions/builtin/imagegen/reference-images.js

@@ -0,0 +1,70 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+const MAX_REFERENCE_BYTES = 50 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]);
+const RIFF_SIGNATURE = Buffer.from("RIFF");
+const WEBP_SIGNATURE = Buffer.from("WEBP");
+function imageMimeType(bytes) {
+    if (bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+        return "image/png";
+    if (bytes.subarray(0, 3).equals(JPEG_SIGNATURE))
+        return "image/jpeg";
+    if (bytes.subarray(0, 4).equals(RIFF_SIGNATURE) && bytes.subarray(8, 12).equals(WEBP_SIGNATURE)) {
+        return "image/webp";
+    }
+    return undefined;
+}
+async function loadImageFile(cwd, path, label) {
+    try {
+        // Nonblocking open lets us reject FIFOs without waiting for a writer.
+        const file = await open(resolve(cwd, path), constants.O_RDONLY | constants.O_NONBLOCK);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile())
+                throw new Error("must be a regular file");
+            if (stat.size > MAX_REFERENCE_BYTES)
+                throw new Error("must be at most 50 MB");
+            const bytes = await file.readFile();
+            if (bytes.length > MAX_REFERENCE_BYTES)
+                throw new Error("must be at most 50 MB");
+            const mimeType = imageMimeType(bytes);
+            if (mimeType === undefined)
+                throw new Error("must be a PNG, JPEG, or WEBP image (invalid magic bytes)");
+            return { ok: true, image: { type: "image", data: bytes.toString("base64"), mimeType } };
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Error: ${label} "${path}": ${reason}` };
+    }
+}
+export async function loadReferenceImages(cwd, paths) {
+    if (paths === undefined)
+        return { ok: true, images: [] };
+    if (paths.length < 1 || paths.length > 5) {
+        return { ok: false, error: `Error: reference_image_paths must contain 1 to 5 paths (got ${paths.length}).` };
+    }
+    const images = [];
+    for (const path of paths) {
+        const loaded = await loadImageFile(cwd, path, "reference image");
+        if (!loaded.ok)
+            return loaded;
+        images.push(loaded.image);
+    }
+    return { ok: true, images };
+}
+/** The inpainting mask is one more local image, bound to the first reference by the API. */
+export async function loadMaskImage(cwd, path, referenceCount) {
+    if (path === undefined)
+        return undefined;
+    if (referenceCount === 0) {
+        return { ok: false, error: "Error: mask_image_path requires at least one reference_image_paths entry to edit." };
+    }
+    return loadImageFile(cwd, path, "mask image");
+}
+//# sourceMappingURL=reference-images.js.map

package/dist/core/extensions/builtin/imagegen/reference-images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-images.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/reference-images.ts"],"names":[],"mappings":"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","sourcesContent":["import { constants } from \"node:fs\";\nimport { open } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport type { ImageContent } from \"@earendil-works/pi-ai/compat\";\n\nconst MAX_REFERENCE_BYTES = 50 * 1024 * 1024;\nconst PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);\nconst JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]);\nconst RIFF_SIGNATURE = Buffer.from(\"RIFF\");\nconst WEBP_SIGNATURE = Buffer.from(\"WEBP\");\n\ntype ReferenceImages = { ok: true; images: ImageContent[] } | { ok: false; error: string };\ntype LoadedImage = { ok: true; image: ImageContent } | { ok: false; error: string };\n\nfunction imageMimeType(bytes: Buffer): string | undefined {\n\tif (bytes.subarray(0, 8).equals(PNG_SIGNATURE)) return \"image/png\";\n\tif (bytes.subarray(0, 3).equals(JPEG_SIGNATURE)) return \"image/jpeg\";\n\tif (bytes.subarray(0, 4).equals(RIFF_SIGNATURE) && bytes.subarray(8, 12).equals(WEBP_SIGNATURE)) {\n\t\treturn \"image/webp\";\n\t}\n\treturn undefined;\n}\n\nasync function loadImageFile(cwd: string, path: string, label: string): Promise<LoadedImage> {\n\ttry {\n\t\t// Nonblocking open lets us reject FIFOs without waiting for a writer.\n\t\tconst file = await open(resolve(cwd, path), constants.O_RDONLY | constants.O_NONBLOCK);\n\t\ttry {\n\t\t\tconst stat = await file.stat();\n\t\t\tif (!stat.isFile()) throw new Error(\"must be a regular file\");\n\t\t\tif (stat.size > MAX_REFERENCE_BYTES) throw new Error(\"must be at most 50 MB\");\n\t\t\tconst bytes = await file.readFile();\n\t\t\tif (bytes.length > MAX_REFERENCE_BYTES) throw new Error(\"must be at most 50 MB\");\n\t\t\tconst mimeType = imageMimeType(bytes);\n\t\t\tif (mimeType === undefined) throw new Error(\"must be a PNG, JPEG, or WEBP image (invalid magic bytes)\");\n\t\t\treturn { ok: true, image: { type: \"image\", data: bytes.toString(\"base64\"), mimeType } };\n\t\t} finally {\n\t\t\tawait file.close();\n\t\t}\n\t} catch (error) {\n\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\treturn { ok: false, error: `Error: ${label} \"${path}\": ${reason}` };\n\t}\n}\n\nexport async function loadReferenceImages(cwd: string, paths: string[] | undefined): Promise<ReferenceImages> {\n\tif (paths === undefined) return { ok: true, images: [] };\n\tif (paths.length < 1 || paths.length > 5) {\n\t\treturn { ok: false, error: `Error: reference_image_paths must contain 1 to 5 paths (got ${paths.length}).` };\n\t}\n\tconst images: ImageContent[] = [];\n\tfor (const path of paths) {\n\t\tconst loaded = await loadImageFile(cwd, path, \"reference image\");\n\t\tif (!loaded.ok) return loaded;\n\t\timages.push(loaded.image);\n\t}\n\treturn { ok: true, images };\n}\n\n/** The inpainting mask is one more local image, bound to the first reference by the API. */\nexport async function loadMaskImage(\n\tcwd: string,\n\tpath: string | undefined,\n\treferenceCount: number,\n): Promise<LoadedImage | undefined> {\n\tif (path === undefined) return undefined;\n\tif (referenceCount === 0) {\n\t\treturn { ok: false, error: \"Error: mask_image_path requires at least one reference_image_paths entry to edit.\" };\n\t}\n\treturn loadImageFile(cwd, path, \"mask image\");\n}\n"]}

package/dist/core/extensions/builtin/imagegen/skill/SKILL.md

@@ -1,67 +1,92 @@
 ---
 name: gpt-image-gen
-description: MUST read before generating images. Detailed prompt-crafting guide for gpt-image models, covering tool routing (native image_generation server tool vs the generate_image tool), prompt structure from subject to background, verbatim text rendering, anti-patterns, and the revised_prompt feedback loop for iteration.
+description: MUST read before generating images. Prompt-crafting guide for gpt-image-2.5 covering tool routing (native image_generation server tool vs the generate_image tool), model and quality selection, prompt structure, exact text rendering, reference-image editing, transparent assets, output formats, and multi-turn refinement.
 ---
 
 # GPT Image Generation
 
-How to write image prompts that come back right the first time, and how to fix them fast when they don't. Read this before your first generation call.
+How to get the image right the first time, and how to fix it fast when it is not. Read this before your first generation call.
 
 ## Which tool
 
 When image generation tooling is present in your tool set, pick the surface that actually exists right now:
 
 - If a native `image_generation` server tool is available, use it. The provider runs generation server-side and returns the image in the response stream.
-- Otherwise, call the `generate_image` tool. It sends your prompt to the configured OpenAI-compatible endpoint and saves the result to a file.
+- Otherwise, call the `generate_image` tool. It sends your prompt and optional reference images to the configured OpenAI-compatible endpoint and saves the result as a png, jpeg, or webp file. The model, quality, size, background, and format controls below apply to `generate_image`, not to the native server tool.
 
-Check your current tool set before choosing. Skill visibility refreshes on reload, but tool state can change mid-session (model switch, credential change), so trust the tools you can see over what this page said at startup. If both surfaces ever appear, prefer the native server tool.
+Check your current tool set before choosing. Tool state can change mid-session (model switch, credential change), so trust the tools you can see over what this page said at startup. If both surfaces ever appear, prefer the native server tool. When the request is clear, generate directly instead of asking for confirmation; ask only when a required reference image is missing.
+
+## Model selection
+
+- `gpt-image-2.5-sunburst` (default): the base model, optimized for quality, above gpt-image-2. Use it for precise edits, fidelity to reference subjects and products, dense text or diagrams, and final production assets.
+- `gpt-image-2.5-flare`: the small model, optimized for speed, with quality comparable to gpt-image-2. Reach for it when latency or volume matters more than the last increment of quality.
+- `gpt-image-2`: previous generation; quality tiers stop at `high`, transparency is preview-level.
+
+The default is the better model on purpose. When a workflow turns out to be latency-sensitive, run the same prompt and inputs on Flare and switch only if the result still meets the bar.
 
 ## Prompt crafting
 
-This section is the core of the skill. gpt-image models reward detail, and the single most common failure mode is a one-line prompt.
+Start from the deliverable, then describe what is visible. Match the prompt's specificity to the user's request:
 
-Build each prompt from six parts, in this order:
+- A specific request (exact text, a named layout, a product photo brief) is normalized, not padded. Keep every stated requirement; do not add objects, people, brands, slogans, or story beats the user did not ask for.
+- A generic request ("a logo for a bakery") gets tasteful concreteness: medium, composition, lighting, palette, materials. Stay within what the request implies.
 
-1. Subject. Who or what, with concrete physical detail. "A middle-aged baker with flour on her forearms and a gray-streaked braid" beats "a baker".
-2. Medium and style. One style, stated plainly: "35mm film photograph", "watercolor illustration", "flat vector poster". Pick one lane.
-3. Composition and camera. Framing, angle, focal length or its visual equivalent. "Eye-level medium close-up, shallow depth of field, subject left of center".
-4. Lighting and color. Direction, quality, palette. "Soft window light from the left, warm amber tones against deep shadow".
-5. Mood. The emotional register: quiet, tense, celebratory, clinical.
-6. Background. What sits behind the subject, and how much of it is in focus.
+Cover these when they matter: the deliverable and its use (poster, product shot, UI mockup, diagram, icon); the subject with concrete physical detail; one medium or style, stated plainly; composition and camera (framing, angle, focal length or its visual equivalent); lighting and color; mood; background and how much of it is in focus. For people, describe body framing, gaze, and interaction ("full body visible, feet included", "looking down at the open book").
 
-A good prompt reads as a short paragraph, not a list and not a lone sentence. If your prompt fits on one line, it is under-specified, and the model will fill the gaps with whatever it likes.
+A short specific prompt is fine. For complex requests, organize the prompt into labeled sections (scene, subject, details, constraints); a descriptive paragraph and a labeled spec express the same intent, so choose whichever is easier to read and update. Request "photorealistic" or "real photograph" explicitly when that is the goal; camera specifications are cues for appearance, not a guarantee of exact optics.
 
 ### Rendering text in the image
 
-When the image must contain readable text (a sign, a label, a headline), put the exact string in double quotes and state the font style and placement:
+Put the exact string in double quotes, say how many times it appears, and describe its position and typography: `A weathered wooden sign above the door reads "OPEN TIL LATE" once, in hand-painted white serif letters, centered, slightly faded.` Spell unusual words or brand names letter by letter when they matter. Add "no other text" so the model does not invent captions. Keep on-image text short; long passages smear. Use `quality` `medium` or `high` for small text, dense labels, or multiple fonts, then check spelling and legibility in the result.
 
-A weathered wooden sign above the door reads "OPEN TIL LATE" in hand-painted white serif letters, centered, slightly faded.
+### Anti-patterns
 
-Keep on-image text short. Long passages smear. If the layout matters, say where each string sits.
+- Contradictory instructions. "Photorealistic watercolor" or "minimalist scene packed with detail" averages two opposing goals, and you get neither.
+- Element overcrowding. Past roughly five or six distinct elements, small ones get dropped or mangled. Cut before you add.
+- Style-list collisions. "In the style of anime, oil painting, and pixel art" is three prompts. Choose one style per image and generate variants separately.
+- Invented content. Extra characters, logos, watermarks, or slogans the user never asked for. State exclusions when the model tends to add them ("no watermark, no logo").
 
-### Anti-patterns
+## Quality, size, and format
+
+`quality` accepts `low`, `medium`, `high`, `xhigh`, `max`, or `auto` (default). Explore with `auto` or a lower tier; raise it for the final image only while it fixes an unmet requirement, since a higher tier does not guarantee a better image and costs more latency. `xhigh` and `max` exist only on GPT Image 2.5; the API rejects them on `gpt-image-2`.
+
+`size` defaults to `auto`. Presets: `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait). Custom `WIDTHxHEIGHT` works when both edges are multiples of 16, the aspect ratio stays within 1:3 to 3:1, neither edge exceeds 3840, and the total pixel count is between 655,360 and 8,294,400 (4K is `3840x2160` or `2160x3840`, not `3840x3840`). Outputs above `2560x1440` are experimental; square images are usually fastest.
+
+`output_format`: `png` (default) is lossless and keeps alpha; `jpeg` is the fastest and smallest for photos with no transparency; `webp` is small and keeps alpha. `output_compression` (0-100) applies to jpeg and webp only. The `output_path` extension must match the format or be omitted.
+
+### Transparent assets
+
+For logos, stickers, cutouts, and UI icons set `background: "transparent"` with `output_format` `png` or `webp`, and also ask for an isolated subject in the prompt ("isolated on a transparent background, no drop shadow"). A drawn checkerboard is not transparency: after saving, confirm the file has an alpha channel (the result reports `Background: transparent` when the provider confirms it) and inspect edges, hair, glass, and shadows. Repeat the transparent requirement on every later edit of that asset. On `gpt-image-2` transparency is a preview feature; prefer a 2.5 model and verify the alpha channel either way.
+
+## Editing with reference images
 
-- Contradictory instructions. "Photorealistic watercolor" or "minimalist scene packed with detail" forces the model to average two opposing goals, and you get neither.
-- Element overcrowding. Every named object competes for pixels and attention. Past roughly five or six distinct elements, small ones get dropped or mangled. Cut before you add.
-- Style-list collisions. "In the style of anime, oil painting, and pixel art" is three prompts in a trench coat. Choose one style per image and generate variants separately.
+Pass `reference_image_paths` to edit an existing image or to use images as references: 1-5 local png, jpeg, or webp files, each at most 50 MB, absolute or relative to the working directory. With references the tool sends an image-edit request; without them it generates from text. Assign each input a role by position ("image 1 is the product to keep unchanged; image 2 is the style reference") and say how they combine.
 
-### The revised_prompt loop
+Separate the change from the constraints. Say "change only X" and list what must stay fixed: identity, geometry, layout, lighting, labels, colors, surrounding objects. Describe the desired END STATE, not only the delta.
 
-Both surfaces can return a `revised_prompt`: the prompt the model actually used after its own rewrite. Always read it.
+For a local repaint, add `mask_image_path`: a png with an alpha channel the same size as the first reference, where transparent pixels mark the area to repaint. Masking is prompt-guided, so restate the edit and the preserved regions in words too.
 
-1. Diff it against your intent. Note what the model added, dropped, or reinterpreted.
-2. Fold the delta into your next prompt explicitly. If the rewrite dropped "overcast sky", put "overcast sky, no direct sunlight" back with more weight. If it added something you dislike, name the exclusion ("no lens flare").
-3. Regenerate. Treat each round as a conversation with the rewriter, not a fresh roll of the dice.
+```json
+{
+  "prompt": "The same red fox from image 1, now wearing a knitted blue scarf, in an eye-level wildlife photograph. Change only the scarf. Preserve its face, fur markings, pose, and forest background; soft overcast light, muted woodland colors, shallow depth of field.",
+  "model": "gpt-image-2.5-sunburst",
+  "reference_image_paths": ["art/fox.png"],
+  "quality": "high",
+  "size": "2048x1152",
+  "output_path": "art/fox-with-scarf.png"
+}
+```
 
-## Editing and masks
+Use a new `output_path` so the source stays intact. Only the native server tool returns a `revised_prompt` (the mainline model's rewrite); the client tool reports one in `details.revisedPrompts` only when the provider sends it, so judge the saved image against your request rather than waiting for a rewrite.
 
-v1 has no editing surface. The `generate_image` tool is text-only: it accepts a prompt and returns new images. There is no image input, no mask, no inpainting, no variation mode. The native `image_generation` server tool may perform provider-side edits on its own (action=auto), but no edit controls are exposed here.
+## Multi-turn refinement
 
-Don't build workflows around editing. If the user asks to change an existing image, say that v1 generates from text only, then offer the closest text-only path: describe the desired end state as a full new prompt. Editing, masks, and image input are planned for a future version.
+- Generate one image first and inspect it against every clause of the request before spending more.
+- Refine one thing per turn: pass the previous output as the next `reference_image_paths` entry, request the single change, and restate the constraints that must survive. "Same style as before" carries context, but restate critical details if the result drifts.
+- For a recurring character or product, establish one reference image and reuse it in every scene, repeating its defining details.
+- `n` produces variants of one prompt; distinct assets need distinct calls. Use `n` only after the prompt is proven.
+- Keep the full prompt text in the conversation as the reproducibility record.
 
-## Iteration workflow
+## Check the result
 
-- Generate one image first. Inspect the result against every clause of your prompt before spending more.
-- Correct deviations by editing the prompt, not by hoping. Name what was wrong and what stays fixed.
-- Batch with `n` only after the prompt is proven. `n` variants of a bad prompt is `n` bad images.
-- Keep the full prompt text in the conversation. It is your reproducibility record: anyone can re-run the exact call later, and you can diff prompt versions when results drift.
+Before handing the image over: required text is spelled correctly and legible; identities, product shapes, and labels survived; the edit changed only what was requested; a transparent asset has real alpha rather than a painted background; diagram labels and relationships are correct. Fix a miss by editing the prompt or masking the region, not by regenerating blindly.

package/dist/core/extensions/builtin/imagegen/tool.d.ts

@@ -1,22 +1,18 @@
-import { Type } from "typebox";
-export interface GenerateImageDetails {
-    paths: string[];
-    model: string;
-    source: string;
-    size: string;
-    quality: string;
-    requested: number;
-    generated: number;
-    revisedPrompts: string[];
-    error?: string;
-    reason?: "missing_config" | "provider_native_bypass" | "invalid_params" | "write_failed" | "provider_error";
-}
+import { type GenerateImageDetails } from "./params.ts";
+export type { GenerateImageDetails } from "./params.ts";
 export declare const GENERATE_IMAGE_TOOL_NAME = "generate_image";
-export declare const generateImageTool: import("../../types.ts").ToolDefinition<Type.TObject<{
-    prompt: Type.TString;
-    size: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"1024x1024">, Type.TLiteral<"1024x1536">, Type.TLiteral<"1536x1024">]>>;
-    quality: Type.TOptional<Type.TUnion<[Type.TLiteral<"auto">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>>;
-    n: Type.TOptional<Type.TInteger>;
-    output_path: Type.TOptional<Type.TString>;
+export declare const generateImageTool: import("../../types.ts").ToolDefinition<import("typebox").TObject<{
+    prompt: import("typebox").TString;
+    model: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TLiteral<"gpt-image-2.5-sunburst">, import("typebox").TLiteral<"gpt-image-2.5-flare">, import("typebox").TLiteral<"gpt-image-2">]>>;
+    size: import("typebox").TOptional<import("typebox").TString>;
+    quality: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TLiteral<"auto">, import("typebox").TLiteral<"low">, import("typebox").TLiteral<"medium">, import("typebox").TLiteral<"high">, import("typebox").TLiteral<"xhigh">, import("typebox").TLiteral<"max">]>>;
+    reference_image_paths: import("typebox").TOptional<import("typebox").TArray<import("typebox").TString>>;
+    mask_image_path: import("typebox").TOptional<import("typebox").TString>;
+    background: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TLiteral<"auto">, import("typebox").TLiteral<"transparent">, import("typebox").TLiteral<"opaque">]>>;
+    output_format: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TLiteral<"png">, import("typebox").TLiteral<"jpeg">, import("typebox").TLiteral<"webp">]>>;
+    output_compression: import("typebox").TOptional<import("typebox").TInteger>;
+    moderation: import("typebox").TOptional<import("typebox").TUnion<[import("typebox").TLiteral<"auto">, import("typebox").TLiteral<"low">]>>;
+    n: import("typebox").TOptional<import("typebox").TInteger>;
+    output_path: import("typebox").TOptional<import("typebox").TString>;
 }>, GenerateImageDetails, any> & import("../../types.ts").ToolDefinition<any, any, any>;
 //# sourceMappingURL=tool.d.ts.map

package/dist/core/extensions/builtin/imagegen/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/tool.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAyC/B,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,GAAG,wBAAwB,GAAG,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,CAAC;CAC5G;AAiFD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,eAAO,MAAM,iBAAiB;;;;;;uFA4F5B,CAAC"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/imagegen/tool.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgC,KAAK,oBAAoB,EAA6B,MAAM,aAAa,CAAC;AAKjH,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAoExD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;uFAoJ5B,CAAC"}