pi-openai-toolkit 0.21.1 → 0.22.1

package/src/image-generation/extension.ts

@@ -1,189 +1,189 @@
-import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadToolkitConfig, resolveToolkitConfig } from "../config";
-import { notifyConfigIssues } from "../config/notifications";
-import { registerPhysicalModelObserver } from "../runtime";
-import { executeImageGeneration } from "./service";
-import { isImageGenerationEnabledForModel } from "./eligibility";
-import { renderImageGenerationResult } from "./render";
-import {
-	IMAGE_GENERATION_QUALITIES,
-	IMAGE_GENERATION_SIZES,
-	IMAGE_GENERATION_TOOL_NAME,
-	MAX_IMAGE_BATCH_SIZE,
-	MAX_IMAGE_MODEL_ID_CHARS,
-	MAX_IMAGE_PATH_CHARS,
-	MAX_IMAGE_PROMPT_CHARS,
-	MAX_REFERENCE_IMAGE_COUNT,
-	ImageGenerationError,
-	sanitizeImageDiagnostic,
-	type ImageGenerationToolDetails,
-} from "./types";
-
-const registeredApis = new WeakSet<object>();
-
-const GenerateImageParameters = Type.Object(
-	{
-		prompt: Type.String({
-			minLength: 1,
-			maxLength: MAX_IMAGE_PROMPT_CHARS,
-			description: "Image generation or edit prompt. Preserve the user's requested subject and constraints.",
-		}),
-		referenceImagePaths: Type.Optional(
-			Type.Union(
-				[
-					Type.Null(),
-					Type.Array(Type.String({ minLength: 1, maxLength: MAX_IMAGE_PATH_CHARS }), {
-						minItems: 1,
-						maxItems: MAX_REFERENCE_IMAGE_COUNT,
-					}),
-				],
-				{
-					description:
-						"Use null when the user did not explicitly identify reference images; otherwise provide one to five user-identified local image paths.",
-				},
-			),
-		),
-		outputPath: Type.Optional(
-			Type.Union(
-				[
-					Type.Null(),
-					Type.String({
-						minLength: 1,
-						maxLength: MAX_IMAGE_PATH_CHARS,
-					}),
-				],
-				{
-					description:
-						"Use null when the user did not explicitly request a destination; otherwise provide an explicit .png, .jpg, .jpeg, or .webp file path matching the provider output format.",
-				},
-			),
-		),
-		size: Type.Optional(
-			StringEnum(IMAGE_GENERATION_SIZES, {
-				description: "Requested raster-image dimensions, or auto.",
-			}),
-		),
-		quality: Type.Optional(
-			StringEnum(IMAGE_GENERATION_QUALITIES, {
-				description: "Requested image quality, or auto.",
-			}),
-		),
-		model: Type.Optional(
-			Type.Union(
-				[
-					Type.Null(),
-					Type.String({
-						minLength: 1,
-						maxLength: MAX_IMAGE_MODEL_ID_CHARS,
-					}),
-				],
-				{
-					description:
-						"Use null to accept the default image model, configured by imageGeneration.defaultModel; otherwise provide another model id exactly as it appears in that configured list.",
-				},
-			),
-		),
-		batchSize: Type.Optional(
-			Type.Union(
-				[
-					Type.Null(),
-					Type.Integer({ minimum: 1, maximum: MAX_IMAGE_BATCH_SIZE }),
-				],
-				{
-					description:
-						"Run this many independent image requests concurrently (1-10). Batch requests use generated artifacts and cannot set outputPath.",
-				},
-			),
-		),
-	},
-	{ additionalProperties: false },
-);
-
-type GenerateImageToolParams = Static<typeof GenerateImageParameters>;
-
-function syncImageGenerationTool(
-	pi: ExtensionAPI,
-	model: Parameters<typeof isImageGenerationEnabledForModel>[0],
-	config: Parameters<typeof isImageGenerationEnabledForModel>[1],
-): void {
-	const eligible = isImageGenerationEnabledForModel(model, config);
-	const activeTools = pi.getActiveTools();
-	const active = activeTools.includes(IMAGE_GENERATION_TOOL_NAME);
-	if (eligible && !active) {
-		pi.setActiveTools([...activeTools, IMAGE_GENERATION_TOOL_NAME]);
-	} else if (!eligible && active) {
-		pi.setActiveTools(activeTools.filter((name) => name !== IMAGE_GENERATION_TOOL_NAME));
-	}
-}
-
-export function registerImageGenerationExtension(
-	pi: ExtensionAPI,
-	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
-	executeImage: typeof executeImageGeneration = executeImageGeneration,
-): void {
-	if (registeredApis.has(pi)) return;
-	registeredApis.add(pi);
-	registerPhysicalModelObserver(pi);
-
-	pi.registerTool<typeof GenerateImageParameters, ImageGenerationToolDetails, Record<string, never>>({
-		name: IMAGE_GENERATION_TOOL_NAME,
-		label: "OpenAI Generate Image",
-		description:
-			"Generate raster images, or edit from one to five user-approved local reference images, through an independent Images API request using a configured image model. PNG, JPEG, and WebP responses are validated and saved in their actual format. This is a paid provider operation; batchSize runs independent requests concurrently.",
-		promptSnippet: "Generate or edit raster images through an independent Images API request and a configured imageGeneration.allowedModels entry.",
-		promptGuidelines: [
-			"Use openai_generate_image when the user explicitly asks to create, draw, render, or edit a raster image and the active model speaks a Responses API.",
-			"Do not call openai_generate_image speculatively: it consumes the user's provider or gateway image quota.",
-			"Keep the image prompt faithful to the user's requested subject and constraints; do not invent unrequested style details.",
-			"Set referenceImagePaths to null unless the user explicitly identified local files; never invent paths or placeholder strings, and remember upload requires user approval.",
-			"Set outputPath to null unless the user explicitly asks for a destination; never invent a destination or placeholder string, and otherwise use the default Pi agent artifact.",
-			"Set model to null unless the user named an image model configured in imageGeneration.allowedModels; never invent or guess a model id, and remember an unlisted model fails before the paid request.",
-			"Use batchSize only when the user asks for multiple variants; each batch item is an independent paid request, and batchSize cannot be combined with outputPath.",
-			"Do not substitute Python, browser automation, shell scripts, or unrelated image tools for an eligible image request.",
-		],
-		parameters: GenerateImageParameters,
-		executionMode: "sequential",
-		async execute(toolCallId, params: GenerateImageToolParams, signal, _onUpdate, ctx) {
-			try {
-				const result = await executeImage({
-					params,
-					toolCallId,
-					signal,
-					ctx,
-				});
-				return {
-					content: [{ type: "text", text: result.text }],
-					details: result.details,
-				};
-			} catch (error) {
-				if (error instanceof ImageGenerationError) {
-					throw new Error(error.message);
-				}
-				throw new Error(
-					sanitizeImageDiagnostic(error instanceof Error ? error.message : error, "Image generation failed."),
-				);
-			}
-		},
-		renderResult: renderImageGenerationResult,
-	});
-
-	const synchronize = (ctx: Parameters<typeof executeImageGeneration>[0]["ctx"], model = ctx.model) => {
-		const resolved = resolveToolkitConfig(loadConfig(), model);
-		notifyConfigIssues(ctx, resolved);
-		const valid = !resolved.invalidFeatures.some((feature) => feature === "imageGeneration" || feature === "compatibility");
-		syncImageGenerationTool(pi, model, { ...resolved.config.imageGeneration, enabled: valid && resolved.policy.imageGeneration.enabled });
-	};
-	pi.on("session_start", (_event, ctx) => synchronize(ctx));
-	pi.on("model_select", (event, ctx) => synchronize(ctx, event.model));
-	pi.on("before_agent_start", (_event, ctx) => synchronize(ctx));
-}
-
-export default function imageGenerationExtension(pi: ExtensionAPI): void {
-	registerImageGenerationExtension(pi);
-}
-
-export const _extensionTest = {
-	GenerateImageParameters,
-	syncImageGenerationTool,
-};
+import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadToolkitConfig, resolveToolkitConfig } from "../config";
+import { notifyConfigIssues } from "../config/notifications";
+import { registerPhysicalModelObserver } from "../runtime";
+import { executeImageGeneration } from "./service";
+import { isImageGenerationEnabledForModel } from "./eligibility";
+import { renderImageGenerationResult } from "./render";
+import {
+	IMAGE_GENERATION_QUALITIES,
+	IMAGE_GENERATION_SIZES,
+	IMAGE_GENERATION_TOOL_NAME,
+	MAX_IMAGE_BATCH_SIZE,
+	MAX_IMAGE_MODEL_ID_CHARS,
+	MAX_IMAGE_PATH_CHARS,
+	MAX_IMAGE_PROMPT_CHARS,
+	MAX_REFERENCE_IMAGE_COUNT,
+	ImageGenerationError,
+	sanitizeImageDiagnostic,
+	type ImageGenerationToolDetails,
+} from "./types";
+
+const registeredApis = new WeakSet<object>();
+
+const GenerateImageParameters = Type.Object(
+	{
+		prompt: Type.String({
+			minLength: 1,
+			maxLength: MAX_IMAGE_PROMPT_CHARS,
+			description: "Image generation or edit prompt. Preserve the user's requested subject and constraints.",
+		}),
+		referenceImagePaths: Type.Optional(
+			Type.Union(
+				[
+					Type.Null(),
+					Type.Array(Type.String({ minLength: 1, maxLength: MAX_IMAGE_PATH_CHARS }), {
+						minItems: 1,
+						maxItems: MAX_REFERENCE_IMAGE_COUNT,
+					}),
+				],
+				{
+					description:
+						"Use null when the user did not explicitly identify reference images; otherwise provide one to five user-identified local image paths.",
+				},
+			),
+		),
+		outputPath: Type.Optional(
+			Type.Union(
+				[
+					Type.Null(),
+					Type.String({
+						minLength: 1,
+						maxLength: MAX_IMAGE_PATH_CHARS,
+					}),
+				],
+				{
+					description:
+						"Use null when the user did not explicitly request a destination; otherwise provide an explicit .png, .jpg, .jpeg, or .webp file path matching the provider output format.",
+				},
+			),
+		),
+		size: Type.Optional(
+			StringEnum(IMAGE_GENERATION_SIZES, {
+				description: "Requested raster-image dimensions, or auto.",
+			}),
+		),
+		quality: Type.Optional(
+			StringEnum(IMAGE_GENERATION_QUALITIES, {
+				description: "Requested image quality, or auto.",
+			}),
+		),
+		model: Type.Optional(
+			Type.Union(
+				[
+					Type.Null(),
+					Type.String({
+						minLength: 1,
+						maxLength: MAX_IMAGE_MODEL_ID_CHARS,
+					}),
+				],
+				{
+					description:
+						"Use null to accept the default image model, configured by imageGeneration.defaultModel; otherwise provide another model id exactly as it appears in that configured list.",
+				},
+			),
+		),
+		batchSize: Type.Optional(
+			Type.Union(
+				[
+					Type.Null(),
+					Type.Integer({ minimum: 1, maximum: MAX_IMAGE_BATCH_SIZE }),
+				],
+				{
+					description:
+						"Run this many independent image requests concurrently (1-10). Batch requests use generated artifacts and cannot set outputPath.",
+				},
+			),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+type GenerateImageToolParams = Static<typeof GenerateImageParameters>;
+
+function syncImageGenerationTool(
+	pi: ExtensionAPI,
+	model: Parameters<typeof isImageGenerationEnabledForModel>[0],
+	config: Parameters<typeof isImageGenerationEnabledForModel>[1],
+): void {
+	const eligible = isImageGenerationEnabledForModel(model, config);
+	const activeTools = pi.getActiveTools();
+	const active = activeTools.includes(IMAGE_GENERATION_TOOL_NAME);
+	if (eligible && !active) {
+		pi.setActiveTools([...activeTools, IMAGE_GENERATION_TOOL_NAME]);
+	} else if (!eligible && active) {
+		pi.setActiveTools(activeTools.filter((name) => name !== IMAGE_GENERATION_TOOL_NAME));
+	}
+}
+
+export function registerImageGenerationExtension(
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
+	executeImage: typeof executeImageGeneration = executeImageGeneration,
+): void {
+	if (registeredApis.has(pi)) return;
+	registeredApis.add(pi);
+	registerPhysicalModelObserver(pi);
+
+	pi.registerTool<typeof GenerateImageParameters, ImageGenerationToolDetails, Record<string, never>>({
+		name: IMAGE_GENERATION_TOOL_NAME,
+		label: "OpenAI Generate Image",
+		description:
+			"Generate raster images, or edit from one to five user-approved local reference images, through an independent Images API request using a configured image model. PNG, JPEG, and WebP responses are validated and saved in their actual format. This is a paid provider operation; batchSize runs independent requests concurrently.",
+		promptSnippet: "Generate or edit raster images through an independent Images API request and a configured imageGeneration.allowedModels entry.",
+		promptGuidelines: [
+			"Use openai_generate_image when the user explicitly asks to create, draw, render, or edit a raster image and the active model speaks a Responses API.",
+			"Do not call openai_generate_image speculatively: it consumes the user's provider or gateway image quota.",
+			"Keep the image prompt faithful to the user's requested subject and constraints; do not invent unrequested style details.",
+			"Set referenceImagePaths to null unless the user explicitly identified local files; never invent paths or placeholder strings, and remember upload requires user approval.",
+			"Set outputPath to null unless the user explicitly asks for a destination; never invent a destination or placeholder string, and otherwise use the default Pi agent artifact.",
+			"Set model to null unless the user named an image model configured in imageGeneration.allowedModels; never invent or guess a model id, and remember an unlisted model fails before the paid request.",
+			"Use batchSize only when the user asks for multiple variants; each batch item is an independent paid request, and batchSize cannot be combined with outputPath.",
+			"Do not substitute Python, browser automation, shell scripts, or unrelated image tools for an eligible image request.",
+		],
+		parameters: GenerateImageParameters,
+		executionMode: "sequential",
+		async execute(toolCallId, params: GenerateImageToolParams, signal, _onUpdate, ctx) {
+			try {
+				const result = await executeImage({
+					params,
+					toolCallId,
+					signal,
+					ctx,
+				});
+				return {
+					content: [{ type: "text", text: result.text }],
+					details: result.details,
+				};
+			} catch (error) {
+				if (error instanceof ImageGenerationError) {
+					throw new Error(error.message);
+				}
+				throw new Error(
+					sanitizeImageDiagnostic(error instanceof Error ? error.message : error, "Image generation failed."),
+				);
+			}
+		},
+		renderResult: renderImageGenerationResult,
+	});
+
+	const synchronize = (ctx: Parameters<typeof executeImageGeneration>[0]["ctx"], model = ctx.model) => {
+		const resolved = resolveToolkitConfig(loadConfig(), model);
+		notifyConfigIssues(ctx, resolved);
+		const valid = !resolved.invalidFeatures.some((feature) => feature === "imageGeneration" || feature === "compatibility");
+		syncImageGenerationTool(pi, model, { ...resolved.config.imageGeneration, enabled: valid && resolved.policy.imageGeneration.enabled });
+	};
+	pi.on("session_start", (_event, ctx) => synchronize(ctx));
+	pi.on("model_select", (event, ctx) => synchronize(ctx, event.model));
+	pi.on("before_agent_start", (_event, ctx) => synchronize(ctx));
+}
+
+export default function imageGenerationExtension(pi: ExtensionAPI): void {
+	registerImageGenerationExtension(pi);
+}
+
+export const _extensionTest = {
+	GenerateImageParameters,
+	syncImageGenerationTool,
+};