neoctl 0.2.40 → 0.2.42

package/dist/tools/builtins/image-capabilities.d.ts

@@ -0,0 +1,21 @@
+import type { JsonSchema } from "../tool.js";
+export declare const IMAGE_MODELS: readonly ["gpt-image-2.5-sunburst", "gpt-image-2.5-flare", "gpt-image-2"];
+export type OpenAIImageModel = typeof IMAGE_MODELS[number];
+export declare const DEFAULT_OPENAI_IMAGE_MODEL: OpenAIImageModel;
+export declare const IMAGE_QUALITIES: readonly ["auto", "low", "medium", "high", "xhigh", "max"];
+export declare const IMAGE_SIZE_RULES = "auto or WIDTHxHEIGHT: both edges multiples of 16, each <=3840, aspect ratio <=3:1, total pixels 655360..8294400";
+export declare const IMAGE_SELECTION_GUIDE = "Prefer the GPT Image 2.5 family. Default to gpt-image-2.5-sunburst with quality=auto for final artwork, precise edits, subject/identity preservation, typography, and demanding layouts. Use gpt-image-2.5-flare when the task explicitly prioritizes speed/interactive iteration. Keep quality=auto unless a controlled tier is appropriate or requested: low for explicitly rough fast drafts, medium for iterative composition previews, high for controlled final production, xhigh for demanding text/layout/detail, max for an explicit maximum-tier request. These are selection heuristics, not guarantees that higher tiers improve every prompt. Respect explicit user tier choices. Cost is not a selection criterion. Use gpt-image-2 only when explicitly requested or necessary for confirmed compatibility; never silently switch models or lower quality. Select size for the intended layout, PNG for lossless art/transparency, JPEG for opaque photos, WebP for web assets. Review warnings and actual output metadata: a compatible gateway may accept but ignore parameters. Quality echo differences are informational: they do not prove an internal downgrade. Distinguish requested settings, upstream-reported settings, and byte-verified properties. Output images report hasAlphaChannel separately from hasTransparentPixels: an alpha channel may be fully opaque; PNG palette/color-key transparency may exist without a separate alpha channel. Missing hasTransparentPixels means unknown, not false.";
+export interface ImageWarning {
+    code: string;
+    field: string;
+    message: string;
+    requested?: unknown;
+    actual?: unknown;
+    remedy?: string;
+}
+export declare const IMAGE_INPUT_SCHEMA: JsonSchema;
+export declare function imageValidationError(model: string, field: string, reason: string): string;
+export declare function validImageSize(value: unknown): boolean;
+/** Validate unknown values before any trim, coercion, network request or file write. */
+export declare function normalizeImageInput(value: unknown, configuredModel?: string): Record<string, unknown>;
+export declare function imageInputWarnings(input: Record<string, unknown>): ImageWarning[];

package/dist/tools/builtins/image-capabilities.js

@@ -0,0 +1,97 @@
+import { validateJsonSchema } from "../schema.js";
+export const IMAGE_MODELS = ["gpt-image-2.5-sunburst", "gpt-image-2.5-flare", "gpt-image-2"];
+export const DEFAULT_OPENAI_IMAGE_MODEL = "gpt-image-2.5-sunburst";
+export const IMAGE_QUALITIES = ["auto", "low", "medium", "high", "xhigh", "max"];
+export const IMAGE_SIZE_RULES = "auto or WIDTHxHEIGHT: both edges multiples of 16, each <=3840, aspect ratio <=3:1, total pixels 655360..8294400";
+export const IMAGE_SELECTION_GUIDE = "Prefer the GPT Image 2.5 family. Default to gpt-image-2.5-sunburst with quality=auto for final artwork, precise edits, subject/identity preservation, typography, and demanding layouts. Use gpt-image-2.5-flare when the task explicitly prioritizes speed/interactive iteration. Keep quality=auto unless a controlled tier is appropriate or requested: low for explicitly rough fast drafts, medium for iterative composition previews, high for controlled final production, xhigh for demanding text/layout/detail, max for an explicit maximum-tier request. These are selection heuristics, not guarantees that higher tiers improve every prompt. Respect explicit user tier choices. Cost is not a selection criterion. Use gpt-image-2 only when explicitly requested or necessary for confirmed compatibility; never silently switch models or lower quality. Select size for the intended layout, PNG for lossless art/transparency, JPEG for opaque photos, WebP for web assets. Review warnings and actual output metadata: a compatible gateway may accept but ignore parameters. Quality echo differences are informational: they do not prove an internal downgrade. Distinguish requested settings, upstream-reported settings, and byte-verified properties. Output images report hasAlphaChannel separately from hasTransparentPixels: an alpha channel may be fully opaque; PNG palette/color-key transparency may exist without a separate alpha channel. Missing hasTransparentPixels means unknown, not false.";
+const sourceSchema = {
+    type: "object", additionalProperties: false,
+    properties: Object.fromEntries(["base64", "data", "dataUrl", "mimeType", "name", "label"].map(key => [key, { type: "string" }])),
+};
+export const IMAGE_INPUT_SCHEMA = {
+    type: "object", additionalProperties: false, required: ["semanticName", "prompt"],
+    properties: {
+        mode: { type: "string", enum: ["generate", "edit"], description: "generate (default) creates a new image; edit modifies source images." },
+        semanticName: { type: "string", description: "Required meaningful Chinese/English image name used for the label and filename. Do not use generic image, 图片, output, result, gen, or img." },
+        prompt: { type: "string", description: "Detailed scene/layout/text requirements. In edit mode specify exactly what must change and what must remain unchanged." },
+        model: { type: "string", enum: [...IMAGE_MODELS], description: `Defaults to configured OPENAI_IMAGE_MODEL or ${DEFAULT_OPENAI_IMAGE_MODEL}. ${IMAGE_SELECTION_GUIDE}` },
+        quality: { type: "string", enum: [...IMAGE_QUALITIES], description: "2.5: auto, low, medium, high, xhigh, max. Default auto on all models. Explicit legacy gpt-image-2 rejects xhigh/max. Do not lower quality to save money. auto lets the upstream choose and is not guaranteed to mean max." },
+        size: { type: "string", description: `${IMAGE_SIZE_RULES}. Defaults to auto. Examples: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160, 2160x3840. Gateways may resize: inspect actual dimensions and warnings.` },
+        outputFormat: { type: "string", enum: ["png", "jpeg", "webp"], description: "Default png. PNG for lossless artwork/transparent assets; JPEG for opaque photography; WebP for web delivery/transparency. Actual bytes are inspected, not assumed from this request." },
+        background: { type: "string", enum: ["auto", "opaque", "transparent"], description: "Default auto. transparent requires png or webp. Also explicitly request an isolated subject and true transparency in prompt. Gateway support is verified from output where possible." },
+        moderation: { type: "string", enum: ["auto", "low"], description: "Default auto. low is the upstream less-restrictive moderation preset, not a safety bypass. Acceptance does not prove that a gateway applied this setting." },
+        n: { type: "integer", minimum: 1, maximum: 4, description: "Number of requested images, 1..4; default 1. Returned count is verified and mismatches produce warnings." },
+        image: { ...sourceSchema, description: "One explicit edit source. Exactly one of base64/data/dataUrl. PNG/JPEG/WebP; raw base64 requires matching mimeType. Maximum 50 MiB per image." },
+        images: { type: "array", minItems: 1, maxItems: 16, items: sourceSchema, description: "Explicit edit sources, maximum 16 total including image and imageRefs." },
+        imageRefs: { type: "array", minItems: 1, maxItems: 16, items: { type: "string" }, description: "Prior conversation image IDs/labels/numeric refs. Prefer stable image IDs. Unknown/ambiguous references are errors, never silently use a different image." },
+        useLatestImage: { type: "boolean", description: "Default true: in edit mode, use latest available conversation image only when no explicit source or refs are given." },
+        outputDir: { type: "string", description: "Optional output directory; defaults to session image directory." },
+        outputPath: { type: "string", description: "Optional single-image filename hint; final name derives from semanticName and actual image format. n must be 1. If outputDir is also set, outputPath takes precedence with a warning." },
+    },
+};
+export function imageValidationError(model, field, reason) {
+    return `image_create validation failed for model ${model}: ${field} ${reason}.`;
+}
+export function validImageSize(value) {
+    if (value === "auto")
+        return true;
+    if (typeof value !== "string" || !/^\d{3,4}x\d{3,4}$/u.test(value))
+        return false;
+    const [w, h] = value.split("x").map(Number);
+    return w > 0 && h > 0 && w <= 3840 && h <= 3840 && w % 16 === 0 && h % 16 === 0
+        && Math.max(w, h) / Math.min(w, h) <= 3 && w * h >= 655360 && w * h <= 8294400;
+}
+/** Validate unknown values before any trim, coercion, network request or file write. */
+export function normalizeImageInput(value, configuredModel) {
+    const record = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const model = typeof record.model === "string" ? record.model.trim() : configuredModel?.trim() || DEFAULT_OPENAI_IMAGE_MODEL;
+    const fail = (field, reason) => { throw new Error(imageValidationError(model, field, reason)); };
+    const clean = value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(record).filter(([, v]) => v !== undefined)) : value;
+    const validation = validateJsonSchema(clean, IMAGE_INPUT_SCHEMA);
+    if (!validation.ok)
+        fail("input", validation.message);
+    if (!IMAGE_MODELS.includes(model))
+        fail("model", `must be one of ${IMAGE_MODELS.join(", ")}; update OPENAI_IMAGE_MODEL if configured incorrectly`);
+    const input = { mode: "generate", size: "auto", quality: "auto", outputFormat: "png", background: "auto", moderation: "auto", n: 1, useLatestImage: true, ...clean, model };
+    if (typeof input.prompt !== "string" || !input.prompt.trim())
+        fail("prompt", "must be a non-empty string");
+    if ([...input.prompt].length > 32000)
+        fail("prompt", "must not exceed 32000 characters");
+    if (!validImageSize(input.size))
+        fail("size", `must be ${IMAGE_SIZE_RULES}; received ${JSON.stringify(input.size)}`);
+    if (model === "gpt-image-2" && ["max", "xhigh"].includes(String(input.quality)))
+        fail("quality", `${input.quality} is only available for 2.5 models; select gpt-image-2.5-sunburst or use high with gpt-image-2`);
+    if (input.background === "transparent" && input.outputFormat === "jpeg")
+        fail("outputFormat", "jpeg cannot store transparency; use png or webp with background=transparent, or request background=opaque");
+    if (!Number.isInteger(input.n) || Number(input.n) < 1 || Number(input.n) > 4)
+        fail("n", "must be an integer between 1 and 4");
+    if (record.useLatestImage !== undefined && typeof record.useLatestImage !== "boolean")
+        fail("useLatestImage", "must be boolean");
+    for (const key of ["outputDir", "outputPath"]) {
+        const v = record[key];
+        if (v !== undefined && (typeof v !== "string" || !v.trim() || /[\u0000-\u001f]/u.test(v)))
+            fail(key, "must be a non-empty path without control characters");
+    }
+    if (record.outputPath !== undefined && input.n !== 1)
+        fail("outputPath", "requires n=1; use outputDir for multiple images");
+    for (const key of ["images", "imageRefs"]) {
+        const v = record[key];
+        if (v !== undefined && (!Array.isArray(v) || v.length < 1 || v.length > 16))
+            fail(key, "must contain 1..16 entries");
+    }
+    if (Array.isArray(record.imageRefs) && record.imageRefs.some(ref => typeof ref !== "string" || !ref.trim()))
+        fail("imageRefs", "must contain non-empty strings");
+    const count = (record.image ? 1 : 0) + (Array.isArray(record.images) ? record.images.length : 0) + (Array.isArray(record.imageRefs) ? record.imageRefs.length : 0);
+    if (count > 16)
+        fail("images", "maximum 16 total source images including image, images and imageRefs");
+    return input;
+}
+export function imageInputWarnings(input) {
+    const warnings = [];
+    if (input.mode === "generate" && (input.image || input.images || input.imageRefs))
+        warnings.push({ code: "UNUSED_EDIT_SOURCES", field: "mode", message: "Sources were provided in generate mode and will not be sent. This is a new image, not an edit.", remedy: "Use mode=edit to preserve or modify source images." });
+    if (input.outputDir && input.outputPath)
+        warnings.push({ code: "OUTPUT_PATH_PRECEDENCE", field: "outputDir", message: "Both outputDir and outputPath were supplied; outputPath takes precedence." });
+    return warnings;
+}
+//# sourceMappingURL=image-capabilities.js.map

package/dist/tools/builtins/image-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-capabilities.js","sourceRoot":"","sources":["../../../src/tools/builtins/image-capabilities.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtins/image-generation-tool.d.ts

@@ -1,11 +1,14 @@
 import type { Tool } from "../tool.js";
-export type ImageGenerationSize = "auto" | "1024x1024" | "1536x1024" | "1024x1536";
-export type ImageGenerationQuality = "auto" | "low" | "medium" | "high";
+import { type ImageWarning } from "./image-capabilities.js";
+import { type ImageByteMetadata } from "./image-output-verification.js";
+export { DEFAULT_OPENAI_IMAGE_MODEL } from "./image-capabilities.js";
+export type { OpenAIImageModel } from "./image-capabilities.js";
+export type ImageGenerationSize = "auto" | `${number}x${number}`;
+export type ImageGenerationQuality = "auto" | "low" | "medium" | "high" | "xhigh" | "max";
 export type ImageGenerationFormat = "png" | "jpeg" | "webp";
 export type OpenAIImageGenerationResponseFormat = ImageGenerationFormat | "jpg";
 export type ImageGenerationBackground = "auto" | "transparent" | "opaque";
 export type ImageGenerationModeration = "auto" | "low";
-export type OpenAIImageModel = "gpt-image-2";
 export type ImageToolMode = "generate" | "edit";
 export interface ImageEditInputImage {
     /** Base64 image bytes, either raw or a data URL. */
@@ -44,12 +47,11 @@ export interface ImageGenerationToolInput {
     useLatestImage?: boolean;
     /** Directory where generated image files should be saved. Defaults to a session/agent image directory. */
     outputDir?: string;
-    /** Exact file path for a single generated image. For multiple images, outputDir is used instead. */
+    /** Single-image path hint; semanticName and verified format determine the filename. Requires n=1. */
     outputPath?: string;
 }
-export interface ImageGenerationResult {
+export interface ImageGenerationResult extends ImageByteMetadata {
     index: number;
-    mimeType: string;
     base64: string;
     dataUrl: string;
     revisedPrompt?: string;
@@ -91,6 +93,11 @@ export interface ImageGenerationToolOutput extends ImageGenerationToolTiming {
     sourceImages?: number;
     imageRefs?: string[];
     images: ImageGenerationResult[];
+    /** Explicit request, never confused with actual image properties. */
+    requested: Record<string, unknown>;
+    /** Upstream report, not independent proof of model/compute. */
+    actual: Record<string, unknown>;
+    warnings: ImageWarning[];
     raw?: unknown;
 }
 export interface CreateOpenAIImageGenerationToolOptions {
@@ -99,7 +106,6 @@ export interface CreateOpenAIImageGenerationToolOptions {
     model?: string;
     timeoutMs?: number;
 }
-export declare const DEFAULT_OPENAI_IMAGE_MODEL: OpenAIImageModel;
 export declare const DEFAULT_IMAGE_TIMEOUT_MS = 360000;
 /**
  * OpenAI-only image generation tool backed by the Images API.
@@ -110,3 +116,4 @@ export declare const DEFAULT_IMAGE_TIMEOUT_MS = 360000;
  */
 export declare function createOpenAIImageGenerationTool(options?: CreateOpenAIImageGenerationToolOptions): Tool<ImageGenerationToolInput>;
 export declare const openAIImageGenerationTool: Tool<ImageGenerationToolInput>;
+export declare function normalizeImageBaseUrl(value: string): string;