@eddyskywalker/dsh-chatgpt-subscription 0.58.0 → 0.59.0

package/lib/index.js

@@ -9,7 +9,7 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 import { z } from "zod";
 import z$1 from "@deepseek-ai/schemastery";
 import fs, { chmod, lstat, mkdir, open, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
-import path, { basename, dirname, join, relative, resolve } from "node:path";
+import path, { basename, dirname, extname, join, relative, resolve } from "node:path";
 import os, { homedir, platform, userInfo } from "node:os";
 import { constants, createCipheriv, createDecipheriv, createHash, createHmac, publicEncrypt, randomBytes, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
@@ -807,11 +807,20 @@ const ROUTE_PREFIX$5 = "/api/dsh-chatgpt-subscription";
 * `test/responses-client.test.ts` asserts the two agree, so a release that
 * forgets this constant fails the suite instead of shipping quietly.
 */
-const PLUGIN_VERSION = "0.58.0";
+const PLUGIN_VERSION = "0.59.0";
 const CODEX_CHATGPT_PROVIDER_ID = "codex-chatgpt";
 const CODEX_API_BASE = "https://chatgpt.com/backend-api/codex";
 const CODEX_RESPONSES_URL = `${CODEX_API_BASE}/responses`;
 const CODEX_IMAGE_GENERATION_URL = `${CODEX_API_BASE}/images/generations`;
+/**
+* The edit route: the same image surface, addressed for reference-image input.
+*
+* A generation has nothing to modify and goes to `/images/generations`; a
+* request that names reference images is an EDIT and goes here, with those
+* images carried inline in a JSON `images` array. It is a separate route, not a
+* flag on the generation body, so the two are stated as two constants.
+*/
+const CODEX_IMAGE_EDIT_URL = `${CODEX_API_BASE}/images/edits`;
 const CODEX_SEARCH_URL = `${CODEX_API_BASE}/alpha/search`;
 const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
 /**
@@ -6099,6 +6108,33 @@ function normalizeGenerateOptions(options) {
 }
 //#endregion
 //#region src/host/codex-images.ts
+/**
+* Output canvases the Codex image endpoint accepts in `size`.
+*
+* These are the official client's own three canvases plus the default `auto`,
+* which lets the service pick. A size outside this set is not negotiated: the
+* backend answers it with a 400, so the tool refuses it before the request.
+*/
+const CODEX_IMAGE_SIZES = [
+	"auto",
+	"1024x1024",
+	"1536x1024",
+	"1024x1536"
+];
+/** Render effort the endpoint accepts in `quality`; `auto` is the service's own default. */
+const CODEX_IMAGE_QUALITIES = [
+	"auto",
+	"low",
+	"medium",
+	"high"
+];
+/** Frame budget of an animated GIF the endpoint accepts. */
+const GIF_MIN_FRAMES = 2;
+const GIF_MAX_FRAMES = 16;
+const GIF_MIN_FRAME_MS = 20;
+const GIF_MAX_FRAME_MS = 2e3;
+/** How much of an upstream error body is quoted back to the caller. */
+const MAX_UPSTREAM_EXCERPT_CHARS = 300;
 const PNG_SIGNATURE = [
 	137,
 	80,
@@ -6109,16 +6145,78 @@ const PNG_SIGNATURE = [
 	26,
 	10
 ];
+/**
+* Magic-byte checks per media type.
+*
+* An extension is a claim about a file's name; the bytes are the claim the file
+* itself makes. Both are checked, because sending a file whose declared type the
+* service cannot decode returns a plain upstream error rather than an image.
+*/
+const SIGNATURES$1 = {
+	"image/png": (bytes) => bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71,
+	"image/jpeg": (bytes) => bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255,
+	"image/webp": (bytes) => bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80,
+	"image/gif": (bytes) => bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70
+};
+/**
+* Extensions a reference image may carry.
+*
+* Deliberately narrower than {@link SIGNATURES}: an edit accepts stills only.
+* Animated GIF input is not part of the edit wire contract, so it is refused
+* here instead of being sent to an endpoint that does not take it.
+*/
+const REFERENCE_EXTENSIONS = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp"
+};
 function createCodexImageTool(oauth, attachments, options = {}) {
 	const fetchFn = options.fetchFn ?? fetch;
 	return defineTool({
 		name: CODEX_IMAGE_TOOL_NAME,
-		description: "Generate a PNG image using the signed-in ChatGPT subscription-backed Codex image endpoint.",
-		parameters: { prompt: {
-			type: "string",
-			required: true,
-			description: "A detailed image generation prompt."
-		} },
+		description: "Generate or edit a PNG or GIF image with the signed-in ChatGPT subscription-backed Codex image endpoint. Describe the subject, style, composition and any text to render in the prompt; pass referenceImagePaths to edit local PNG/JPEG/WebP images, and gif to animate the result. Scheduling: call this tool yourself for a single generation, an edit, or a retry - never create a subagent just to generate one image. Delegate only when the creative task needs several candidate images or is large enough to be a multi-step task of its own.",
+		parameters: {
+			prompt: {
+				type: "string",
+				required: true,
+				description: "A detailed image generation prompt."
+			},
+			size: {
+				type: "string",
+				enum: CODEX_IMAGE_SIZES,
+				description: "Output canvas. Omit or pass auto to let the service choose. 1024x1024 is square, 1536x1024 landscape and 1024x1536 portrait."
+			},
+			quality: {
+				type: "string",
+				enum: CODEX_IMAGE_QUALITIES,
+				description: "Render effort. Omit or pass auto for the service default; low is fastest and high is most detailed."
+			},
+			transparentBackground: {
+				type: "boolean",
+				description: "true for a transparent background (PNG or GIF alpha), false for an explicitly opaque one. Omit it to leave the background decision to the service."
+			},
+			referenceImagePaths: {
+				type: "array",
+				items: { type: "string" },
+				description: "Up to 5 local PNG, JPEG or WebP files to edit. Absolute paths recommended. The request becomes an edit against those images; nothing else on disk is read."
+			},
+			gif: {
+				type: "object",
+				additionalProperties: false,
+				description: "Ask for an animated GIF. An empty object is allowed and lets the service choose the frames.",
+				properties: {
+					frameCount: {
+						type: "integer",
+						description: "Number of frames, 2 to 16."
+					},
+					frameDurationMs: {
+						type: "integer",
+						description: "Milliseconds each frame is shown, 20 to 2000."
+					}
+				}
+			}
+		},
 		output: {
 			schema: {
 				type: "object",
@@ -6143,7 +6241,7 @@ function createCodexImageTool(oauth, attachments, options = {}) {
 							},
 							mediaType: {
 								type: "string",
-								enum: ["image/png"],
+								enum: ["image/png", "image/gif"],
 								required: true
 							},
 							bytes: {
@@ -6190,34 +6288,52 @@ function createCodexImageTool(oauth, attachments, options = {}) {
 		async execute(args, exec) {
 			const prompt = args.prompt.trim();
 			if (prompt === "") throw new HarnessError("Image prompt cannot be empty.", "CODEX_IMAGE_INVALID_PROMPT");
-			if (!attachments.imageLimits.mediaTypes.includes("image/png")) throw new HarnessError("PNG image attachments are not enabled in this DSH environment.", "CODEX_IMAGE_ATTACHMENT_UNSUPPORTED");
+			const gif = readGifOptions(args.gif);
+			const references = await readReferenceImages(args.referenceImagePaths ?? [], attachments);
+			assertOutputTypeSupported(attachments, gif === void 0 ? "image/png" : "image/gif");
+			const body = buildImageBody({
+				prompt,
+				size: args.size ?? "auto",
+				quality: args.quality ?? "auto",
+				...args.transparentBackground !== void 0 ? { transparentBackground: args.transparentBackground } : {},
+				...gif !== void 0 ? { gif } : {},
+				references
+			});
+			const url = references.length > 0 ? CODEX_IMAGE_EDIT_URL : CODEX_IMAGE_GENERATION_URL;
+			const turnId = String(exec.callId);
 			let credentials = await imageCredentials(oauth);
-			let response = await requestImage$1(fetchFn, credentials, prompt, String(exec.callId), exec.signal);
+			let response = await requestImage$1(fetchFn, credentials, url, body, turnId, exec.signal);
 			if (response.status === 401) {
 				await response.body?.cancel().catch(() => void 0);
 				credentials = await imageCredentials(oauth, true);
-				response = await requestImage$1(fetchFn, credentials, prompt, String(exec.callId), exec.signal);
+				response = await requestImage$1(fetchFn, credentials, url, body, turnId, exec.signal);
 			}
 			if (response.status === 429) {
-				await response.body?.cancel().catch(() => void 0);
-				throw new HarnessError("Codex image generation was rate limited.", "CODEX_IMAGE_RATE_LIMITED");
+				const detail = upstreamExcerpt(await response.text().catch(() => ""));
+				throw new HarnessError(`Codex image generation was rate limited (429).${detail === "" ? "" : ` ${detail}`}`, "CODEX_IMAGE_RATE_LIMITED");
+			}
+			if (response.status === 400) {
+				const detail = upstreamExcerpt(await response.text().catch(() => ""));
+				throw new HarnessError(`Codex rejected the image request (400). The parameters this call stated were: ${statedParameterSummary(args, gif, references.length)}. One of them is not accepted as given, and no field was dropped to retry.` + (detail === "" ? "" : ` Upstream said: ${detail}`), "CODEX_IMAGE_REQUEST_REJECTED");
 			}
 			if (!response.ok) {
-				await response.body?.cancel().catch(() => void 0);
-				throw new HarnessError(`Codex image generation failed (${response.status}).`, "CODEX_IMAGE_FAILED");
+				const detail = upstreamExcerpt(await response.text().catch(() => ""));
+				throw new HarnessError(`Codex image generation failed (${response.status}).${detail === "" ? "" : ` ${detail}`}`, "CODEX_IMAGE_FAILED");
 			}
-			const bytes = decodeImageBytes(readBase64Image(await response.json()), maxGeneratedImageBytes(attachments));
+			const decoded = decodeImageBytes(readBase64Image(await response.json()), maxGeneratedImageBytes(attachments));
+			if (gif !== void 0 && decoded.mediaType !== "image/gif") throw new HarnessError(`Codex was asked for an animated GIF but returned ${decoded.mediaType}. Nothing was saved: the answer is not the animation that was requested. Omit the gif parameter to accept a still image.`, "CODEX_IMAGE_RESPONSE_INVALID");
+			if (!attachments.imageLimits.mediaTypes.includes(decoded.mediaType)) throw new HarnessError(`Codex returned ${decoded.mediaType} but this DSH environment does not accept that attachment type.`, "CODEX_IMAGE_ATTACHMENT_UNSUPPORTED");
 			const image = await attachments.saveImage({
-				data: bytes,
-				mediaType: "image/png",
-				name: "codex-generated-image.png"
+				data: decoded.data,
+				mediaType: decoded.mediaType,
+				name: `codex-generated-image.${decoded.mediaType === "image/gif" ? "gif" : "png"}`
 			});
 			const output = {
 				prompt,
 				model: CODEX_IMAGE_MODEL,
 				image: {
 					attachmentId: image.attachmentId,
-					mediaType: "image/png",
+					mediaType: decoded.mediaType,
 					bytes: image.bytes,
 					width: image.width,
 					height: image.height,
@@ -6239,6 +6355,124 @@ function createCodexImageTool(oauth, attachments, options = {}) {
 		}
 	});
 }
+/**
+* Validate the frame options of a GIF request.
+*
+* An empty object is legal: it asks for an animation and leaves both numbers to
+* the service. A stated number is checked here rather than by the parameter
+* schema because the schema DSL carries no numeric bounds, and because
+* `execute` is reachable directly.
+*/
+function readGifOptions(gif) {
+	if (gif === void 0) return void 0;
+	const result = {};
+	const frameCount = gif.frameCount;
+	if (frameCount !== void 0) {
+		if (!Number.isInteger(frameCount) || frameCount < GIF_MIN_FRAMES || frameCount > GIF_MAX_FRAMES) throw new HarnessError(`gif.frameCount must be a whole number from ${GIF_MIN_FRAMES} to ${GIF_MAX_FRAMES} (got ${String(frameCount)}).`, "CODEX_IMAGE_GIF_INVALID");
+		result.frameCount = frameCount;
+	}
+	const frameDurationMs = gif.frameDurationMs;
+	if (frameDurationMs !== void 0) {
+		if (!Number.isInteger(frameDurationMs) || frameDurationMs < GIF_MIN_FRAME_MS || frameDurationMs > GIF_MAX_FRAME_MS) throw new HarnessError(`gif.frameDurationMs must be a whole number of milliseconds from ${GIF_MIN_FRAME_MS} to ${GIF_MAX_FRAME_MS} (got ${String(frameDurationMs)}).`, "CODEX_IMAGE_GIF_INVALID");
+		result.frameDurationMs = frameDurationMs;
+	}
+	return result;
+}
+/** Refuse an output type this deployment cannot store, before anything is requested. */
+function assertOutputTypeSupported(attachments, outputType) {
+	if (attachments.imageLimits.mediaTypes.includes(outputType)) return;
+	throw new HarnessError(outputType === "image/gif" ? "GIF output was requested, but this DSH environment does not accept GIF attachments, so nothing was requested. Omit the gif parameter to generate a PNG instead." : "PNG image attachments are not enabled in this DSH environment.", "CODEX_IMAGE_ATTACHMENT_UNSUPPORTED");
+}
+/**
+* Build the wire body of one request.
+*
+* Field order and the defaults are deliberate: a call with no new options
+* produces exactly `prompt/background auto/model/quality auto/size auto`, which
+* is the body this tool has always sent. Every new field appears only when the
+* caller stated it, so an old call site keeps its old bytes on the wire.
+*/
+function buildImageBody(request) {
+	const body = {
+		prompt: request.prompt,
+		background: request.transparentBackground === true ? "transparent" : request.transparentBackground === false ? "opaque" : "auto",
+		model: CODEX_IMAGE_MODEL,
+		quality: request.quality,
+		size: request.size
+	};
+	if (request.gif !== void 0) {
+		body.output_format = "gif";
+		if (request.gif.frameCount !== void 0) body.frame_count = request.gif.frameCount;
+		if (request.gif.frameDurationMs !== void 0) body.frame_duration_ms = request.gif.frameDurationMs;
+	}
+	if (request.references.length > 0) body.images = request.references.map((image) => ({ image_url: `data:${image.mediaType};base64,${Buffer.from(image.data).toString("base64")}` }));
+	return body;
+}
+/**
+* The optional parameters one request actually stated, in words.
+*
+* A 400 says only that the request was invalid, which is useless on a tool with
+* seven parameters: the caller has to be told WHICH ones it sent, or it has no
+* way to know what to change. Only stated options are named - a default that the
+* tool has always sent cannot be the field to fix - and each GIF sub-field is
+* named separately, because `gif: {}` is a legal call that stated neither number.
+*/
+function statedParameterSummary(args, gif, referenceCount) {
+	const stated = [];
+	if (args.size !== void 0) stated.push(`size=${args.size}`);
+	if (args.quality !== void 0) stated.push(`quality=${args.quality}`);
+	if (args.transparentBackground !== void 0) stated.push(`transparentBackground=${String(args.transparentBackground)}`);
+	if (referenceCount > 0) stated.push(`referenceImagePaths (${referenceCount} image${referenceCount === 1 ? "" : "s"})`);
+	if (gif !== void 0) {
+		const frames = [];
+		if (gif.frameCount !== void 0) frames.push(`frameCount=${String(gif.frameCount)}`);
+		if (gif.frameDurationMs !== void 0) frames.push(`frameDurationMs=${String(gif.frameDurationMs)}`);
+		stated.push(frames.length === 0 ? "gif (frame numbers left to the service)" : `gif (${frames.join(", ")})`);
+	}
+	return stated.length === 0 ? "no optional parameter was stated" : stated.join(", ");
+}
+/**
+* Read and validate the reference images one edit request names.
+*
+* Every named file is checked as a local still image: the path must not be a
+* URL, the extension must be PNG/JPEG/WebP, the file must be a regular non-empty
+* file inside the attachment byte limits, and its leading bytes must match the
+* declared type. Nothing else on disk is read, and the returned bytes are the
+* ONLY image data that reaches the request.
+*/
+async function readReferenceImages(files, attachments) {
+	if (files.length === 0) return [];
+	const limit = Math.min(5, attachments.imageLimits.maxImagesPerMessage);
+	if (files.length > limit) throw new HarnessError(`At most ${limit} reference images are accepted; ${files.length} were given.`, "CODEX_IMAGE_REFERENCE_LIMIT");
+	const perImageBytes = attachments.imageLimits.maxImageBytes;
+	const totalBytes = attachments.imageLimits.maxMessageImageBytes;
+	const images = [];
+	let sentBytes = 0;
+	for (const [index, raw] of files.entries()) {
+		const label = `referenceImagePaths[${index}]`;
+		const value = raw.trim();
+		if (value === "") throw new HarnessError(`${label} is empty; every reference image must name a local file.`, "CODEX_IMAGE_REFERENCE_INVALID_PATH");
+		if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value) || /^data:/i.test(value)) throw new HarnessError(`${label} is a URL (${value}). Reference images must be local PNG, JPEG or WebP files; nothing is fetched.`, "CODEX_IMAGE_REFERENCE_INVALID_PATH");
+		const extension = extname(value).toLowerCase();
+		const mediaType = REFERENCE_EXTENSIONS[extension];
+		if (mediaType === void 0) throw new HarnessError(extension === ".gif" ? `${label} (${value}) is a GIF. Reference images must be still PNG, JPEG or WebP files; animated input is not part of the edit request.` : `${label} (${value}) is not a PNG, JPEG or WebP file (extension ${extension === "" ? "(none)" : `"${extension}"`}).`, "CODEX_IMAGE_REFERENCE_UNSUPPORTED");
+		if (!attachments.imageLimits.mediaTypes.includes(mediaType)) throw new HarnessError(`${label} is ${mediaType}, which this DSH environment does not accept as an attachment.`, "CODEX_IMAGE_ATTACHMENT_UNSUPPORTED");
+		const absolute = resolve(value);
+		const stats = await stat(absolute).catch(() => void 0);
+		if (stats === void 0) throw new HarnessError(`${label} (${value}) does not exist or cannot be read.`, "CODEX_IMAGE_REFERENCE_NOT_FOUND");
+		if (!stats.isFile()) throw new HarnessError(`${label} (${value}) is not a regular file; pass a path to one PNG, JPEG or WebP file.`, "CODEX_IMAGE_REFERENCE_NOT_A_FILE");
+		if (stats.size === 0) throw new HarnessError(`${label} (${value}) is empty.`, "CODEX_IMAGE_REFERENCE_EMPTY");
+		if (stats.size > perImageBytes) throw new HarnessError(`${label} (${value}) is ${stats.size} bytes, above the ${perImageBytes} byte limit for one attachment.`, "CODEX_IMAGE_REFERENCE_TOO_LARGE");
+		const data = new Uint8Array(await readFile(absolute));
+		if (!SIGNATURES$1[mediaType](data)) throw new HarnessError(`${label} (${value}) does not start like a ${mediaType} file, so its bytes contradict its extension.`, "CODEX_IMAGE_REFERENCE_INVALID_CONTENT");
+		sentBytes += data.byteLength;
+		if (sentBytes > totalBytes) throw new HarnessError(`The reference images total ${sentBytes} bytes, above the ${totalBytes} byte limit for one message.`, "CODEX_IMAGE_REFERENCE_TOO_LARGE");
+		images.push({
+			mediaType,
+			data
+		});
+	}
+	return images;
+}
 async function imageCredentials(oauth, force = false) {
 	try {
 		return await oauth.credentials(force, { purpose: "tool" });
@@ -6246,8 +6480,8 @@ async function imageCredentials(oauth, force = false) {
 		throw new HarnessError(`ChatGPT subscription credentials are required for Codex image generation.${error instanceof Error && error.message !== "" ? ` (${error.message})` : ""}`, "CODEX_IMAGE_CREDENTIAL_MISSING", { cause: error });
 	}
 }
-function requestImage$1(fetchFn, credentials, prompt, turnId, signal) {
-	return fetchFn(CODEX_IMAGE_GENERATION_URL, {
+function requestImage$1(fetchFn, credentials, url, body, turnId, signal) {
+	return fetchFn(url, {
 		method: "POST",
 		headers: {
 			...codexHeaders(credentials),
@@ -6255,16 +6489,19 @@ function requestImage$1(fetchFn, credentials, prompt, turnId, signal) {
 			"content-type": "application/json",
 			"x-codex-image-turn-id": turnId
 		},
-		body: JSON.stringify({
-			prompt,
-			background: "auto",
-			model: CODEX_IMAGE_MODEL,
-			quality: "auto",
-			size: "auto"
-		}),
+		body: JSON.stringify(body),
 		signal
 	});
 }
+/**
+* The upstream error body, short enough to read in a message and stripped of
+* anything that must never be echoed: bearer credentials, base64 image payloads
+* and any long base64-shaped run.
+*/
+function upstreamExcerpt(text) {
+	const collapsed = text.replace(/data:[a-z0-9.+-]+\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]*/gi, "data:<redacted>").replace(/Bearer\s+[A-Za-z0-9._~+/=-]{6,}/gi, "Bearer <redacted>").replace(/[A-Za-z0-9+/]{200,}={0,2}/g, "<redacted>").replace(/\s+/g, " ").trim();
+	return collapsed.length > MAX_UPSTREAM_EXCERPT_CHARS ? `${collapsed.slice(0, MAX_UPSTREAM_EXCERPT_CHARS)}…` : collapsed;
+}
 function readBase64Image(value) {
 	const root = record$7(value);
 	const data = Array.isArray(root?.data) ? root.data[0] : null;
@@ -6272,12 +6509,27 @@ function readBase64Image(value) {
 	if (image === null) throw new HarnessError("Codex image response did not include image data.", "CODEX_IMAGE_RESPONSE_INVALID");
 	return image;
 }
+/**
+* Decode one returned image and identify it by its own magic bytes.
+*
+* The endpoint answers a requested GIF with GIF bytes in the same `b64_json`
+* field it uses for PNG, and states nothing about which one it produced, so the
+* bytes are the only reliable source for the media type – and storing a GIF
+* under `image/png` would fail at save time or, worse, mislabel the file.
+*/
 function decodeImageBytes(base64, maxBytes) {
 	if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64) || base64.length % 4 !== 0) throw new HarnessError("Codex image response was not valid base64.", "CODEX_IMAGE_RESPONSE_INVALID");
 	const buffer = Buffer.from(base64, "base64");
 	if (buffer.length > maxBytes) throw new HarnessError("Generated image exceeds the configured attachment size limit.", "CODEX_IMAGE_TOO_LARGE");
-	for (const [index, byte] of PNG_SIGNATURE.entries()) if (buffer[index] !== byte) throw new HarnessError("Codex image response was not a PNG image.", "CODEX_IMAGE_RESPONSE_INVALID");
-	return buffer;
+	if (SIGNATURES$1["image/gif"](buffer)) return {
+		mediaType: "image/gif",
+		data: buffer
+	};
+	for (const [index, byte] of PNG_SIGNATURE.entries()) if (buffer[index] !== byte) throw new HarnessError("Codex image response was neither PNG nor GIF image data.", "CODEX_IMAGE_RESPONSE_INVALID");
+	return {
+		mediaType: "image/png",
+		data: buffer
+	};
 }
 function maxGeneratedImageBytes(attachments) {
 	return Math.min(attachments.imageLimits.maxImageBytes, attachments.imageLimits.maxMessageImageBytes);
@@ -10451,6 +10703,9 @@ var AntigravityAdapter = class extends LlmAdapter {
 /**
 * Aspect ratios Gemini image models accept in `imageConfig.aspectRatio`.
 * Omitted, the model picks one itself, which is what the request then does.
+*
+* The last four are the extreme strips: a wider or taller frame than the square
+* family covers, useful for banners, headers and phone wallpapers.
 */
 const ANTIGRAVITY_IMAGE_ASPECT_RATIOS = [
 	"1:1",
@@ -10462,7 +10717,21 @@ const ANTIGRAVITY_IMAGE_ASPECT_RATIOS = [
 	"5:4",
 	"9:16",
 	"16:9",
-	"21:9"
+	"21:9",
+	"1:4",
+	"4:1",
+	"1:8",
+	"8:1"
+];
+/**
+* Image sizes Gemini image models accept in `imageConfig.imageSize`.
+* Omitted, the model picks one itself, which is what the request then does.
+*/
+const ANTIGRAVITY_IMAGE_SIZES = [
+	"0.5K",
+	"1K",
+	"2K",
+	"4K"
 ];
 /** Images one call keeps; the model normally returns one. */
 const MAX_IMAGES_PER_CALL = 4;
@@ -10476,7 +10745,11 @@ const MAX_IMAGES_PER_CALL = 4;
 * Antigravity clients send for image runtimes; it has not been captured from
 * the official client.
 */
-function buildImageRequest(prompt, projectId, aspectRatio) {
+function buildImageRequest(prompt, projectId, aspectRatio, imageSize) {
+	const imageConfig = {
+		...aspectRatio ? { aspectRatio } : {},
+		...imageSize ? { imageSize } : {}
+	};
 	return {
 		project: projectId,
 		model: ANTIGRAVITY_IMAGE_MODEL,
@@ -10487,7 +10760,7 @@ function buildImageRequest(prompt, projectId, aspectRatio) {
 			}],
 			generationConfig: {
 				responseModalities: ["TEXT", "IMAGE"],
-				...aspectRatio ? { imageConfig: { aspectRatio } } : {}
+				...Object.keys(imageConfig).length > 0 ? { imageConfig } : {}
 			}
 		},
 		requestType: "image_gen",
@@ -10599,7 +10872,7 @@ function createAntigravityImageTool(accountPool, store, attachments, options = {
 	const fetchFn = options.fetchFn ?? fetch;
 	return defineTool({
 		name: ANTIGRAVITY_IMAGE_TOOL_NAME,
-		description: "Generate an image with Gemini image generation through the signed-in Antigravity account. Describe the subject, style, composition and any text to render in the prompt.",
+		description: "Generate an image with Gemini image generation through the signed-in Antigravity account. Describe the subject, style, composition and any text to render in the prompt. Scheduling: a single generation, a change to an image already generated, and a retry of a failed attempt are direct calls from the agent that needs the image — do not create a subagent just to generate one image. Delegate only a task that genuinely needs several alternative directions or complex creative planning, and pass the prompt that comes back to this tool.",
 		parameters: {
 			prompt: {
 				type: "string",
@@ -10609,7 +10882,12 @@ function createAntigravityImageTool(accountPool, store, attachments, options = {
 			aspectRatio: {
 				type: "string",
 				enum: ANTIGRAVITY_IMAGE_ASPECT_RATIOS,
-				description: "Optional aspect ratio. Omit it to let the model choose."
+				description: "Optional aspect ratio, one of the listed values. Omit it to let the model choose. If the upstream rejects the value, re-issue the call with another value from the list rather than the same one."
+			},
+			imageSize: {
+				type: "string",
+				enum: ANTIGRAVITY_IMAGE_SIZES,
+				description: "Optional output size, one of 0.5K, 1K, 2K or 4K. Omit it to let the model choose. It is sent only when given, so it never overrides an aspect ratio the caller did not set."
 			}
 		},
 		output: {
@@ -10693,7 +10971,7 @@ function createAntigravityImageTool(accountPool, store, attachments, options = {
 			const prompt = args.prompt.trim();
 			if (prompt === "") throw new HarnessError("Image prompt cannot be empty.", "ANTIGRAVITY_IMAGE_INVALID_PROMPT");
 			if (options.isEnabled?.() === false) throw new HarnessError("The Antigravity line is switched off; enable it in Settings → Antigravity to generate images.", "ANTIGRAVITY_IMAGE_DISABLED");
-			const response = await requestImage(accountPool, store, fetchFn, prompt, args.aspectRatio, exec.signal);
+			const response = await requestImage(accountPool, store, fetchFn, prompt, args.aspectRatio, args.imageSize, exec.signal);
 			if (response.images.length === 0) throw new HarnessError(noImageMessage(response), "ANTIGRAVITY_IMAGE_EMPTY");
 			const keep = Math.min(MAX_IMAGES_PER_CALL, attachments.imageLimits.maxImagesPerMessage, response.images.length);
 			const saved = [];
@@ -10752,12 +11030,37 @@ async function acquireAccount(accountPool, store, tried, fetchFn) {
 		}
 	}
 }
-async function requestImage(accountPool, store, fetchFn, prompt, aspectRatio, signal) {
+/**
+* Whether a status means the upstream refused the SHAPE of the request rather
+* than the account, the allowance or the transient state of the service.
+*/
+const PARAMETER_REJECTION_STATUSES = /* @__PURE__ */ new Set([400, 422]);
+/**
+* What a failed image request reports: the status, a bounded excerpt of what
+* the upstream said, and — when the refusal was about the request — which
+* optional fields were sent.
+*
+* A parameter rejection is never retried without the field it names. Dropping
+* `aspectRatio` or `imageSize` would answer with an image that silently has a
+* shape nobody asked for, so the caller is told which fields to change and
+* makes that call itself.
+*/
+function imageFailureMessage(status, errorText, sent) {
+	const parts = [`Antigravity image generation failed (${status ?? "no response"}).`];
+	if (status !== void 0 && PARAMETER_REJECTION_STATUSES.has(status)) {
+		const fields = [sent.aspectRatio === void 0 ? void 0 : `aspectRatio "${sent.aspectRatio}"`, sent.imageSize === void 0 ? void 0 : `imageSize "${sent.imageSize}"`].filter((field) => field !== void 0);
+		parts.push(fields.length > 0 ? `The request itself was refused, and these optional fields were what it carried: ${fields.join(", ")}. It is not retried without them: re-issue the call with a different candidate value, or omit the field, because the upstream refused this request shape.` : "The request itself was refused while no aspectRatio or imageSize was set, so a different value for either cannot fix it; change the prompt or check the account before retrying.");
+	}
+	const excerpt = upstreamBodyExcerpt(errorText);
+	if (excerpt !== "") parts.push(`Upstream said: ${excerpt}`);
+	return parts.join(" ");
+}
+async function requestImage(accountPool, store, fetchFn, prompt, aspectRatio, imageSize, signal) {
 	const tried = /* @__PURE__ */ new Set();
 	while (true) {
 		const { account, token, projectId } = await acquireAccount(accountPool, store, tried, fetchFn);
 		tried.add(account.id);
-		const body = JSON.stringify(buildImageRequest(prompt, projectId || "antigravity-default", aspectRatio));
+		const body = JSON.stringify(buildImageRequest(prompt, projectId || "antigravity-default", aspectRatio, imageSize));
 		let response;
 		let firstResponse;
 		for (const endpoint of endpointCandidates()) try {
@@ -10789,7 +11092,10 @@ async function requestImage(accountPool, store, fetchFn, prompt, aspectRatio, si
 			}
 			throw new HarnessError(`Antigravity image generation was rate limited (429) without a stated reset time, so it is handled as a transient rate limit rather than a spent quota. ${upstreamBodyExcerpt(errorText)}`.trim(), "ANTIGRAVITY_IMAGE_RATE_LIMITED");
 		}
-		throw new HarnessError(`Antigravity image generation failed (${status ?? "no response"}).${errorText ? ` ${errorText}` : ""}`, "ANTIGRAVITY_IMAGE_FAILED");
+		throw new HarnessError(imageFailureMessage(status, errorText, {
+			aspectRatio,
+			imageSize
+		}), "ANTIGRAVITY_IMAGE_FAILED");
 	}
 }
 //#endregion
@@ -27971,6 +28277,25 @@ const TOOL_SOURCE = /(?:^|[-_/])(?:read|view|cat|open|edit|write|patch|apply_pat
 /** 独立开关覆盖的检索工具；只有明确导航任务才允许进入新投影。 */
 const TOOL_RETRIEVAL = /^(?:read|web_fetch|grep|glob)$/;
 /**
+* PTC 家族的**程序传输**工具名（一个集合，两个名字）。
+*
+* 「模型写一段程序、工具调用发生在程序内部」是同一种传输，只是不同预设给主工具起
+* 了不同名字：PTC 预设叫 `run_code`，Code Mode 预设叫 `code_run`。凡是按工具名判断
+* 「这条结果来自程序传输」的地方都必须认这**整个集合**——名字只写一个，预设一换，
+* 大结果的 `ref://` 预览与精确补读就会静默失效。
+*/
+const CACHE_WARMUP_PTC_TRANSPORT_TOOLS = /* @__PURE__ */ new Set(["run_code", "code_run"]);
+/**
+* 这个名字是否属于 PTC 家族的程序传输工具。
+*
+* 只做**精确**匹配：`code_runner` 之类的近似名不算，宁可少投影也不能误伤。
+* @param name - 工具名。
+* @returns 属于 {@link CACHE_WARMUP_PTC_TRANSPORT_TOOLS} 时为 true。
+*/
+function isPtcTransportName(name) {
+	return CACHE_WARMUP_PTC_TRANSPORT_TOOLS.has(name);
+}
+/**
 * 多节/多读输出进入新投影的最小长度门槛（字符）。
 *
 * 短于这个长度、又没有 spill 的普通源码与契约读一律逐字保留：
@@ -29266,7 +29591,7 @@ function planProjection(text, toolName, navigation, retrievalOnly, spilled = fal
 		kind: "verbatim",
 		strategy: "verbatim-contract"
 	};
-	if (toolName === "run_code" && navigation === true) {
+	if (isPtcTransportName(toolName) && navigation === true) {
 		const outline = planRetrievalOutline(text, "read");
 		if (outline !== void 0) return outline;
 		if (retrievalOnly === true) return {
@@ -92527,6 +92852,20 @@ const PRESET_REGISTRY_PACKAGE = "@deepseek-ai/dsh-agent-preset";
 const WORKING_DIRECTORY_PACKAGE = "@deepseek-ai/dsh-working-directory";
 /** The standalone PTC executor introduced when tool presentation split into executor plugins. */
 const PTC_EXECUTOR_PACKAGE = "@deepseek-ai/dsh-tool-executor-ptc";
+/**
+* The native executor this package delegates Code Mode execution to.
+*
+* A program sub-call must run through the harness's own policy, approval, and
+* post-execute pipeline; re-implementing that pipeline is how a plugin silently
+* drops policy. A profile plugin cannot resolve the host's kernel packages, so
+* this package carries the executor as a real dependency and drives the host
+* registry with it.
+*/
+const NATIVE_EXECUTOR_PACKAGE = "@deepseek-ai/dsh-tool-executor-native";
+/** This package's Code Mode row: the preset's own tools stay native, the rest is program-only. */
+const CODEMODE_PACKAGE = "@eddyskywalker/dsh-chatgpt-subscription/codemode";
+/** The deprecated presentation row generations without a native executor keep. */
+const AGENT_TOOL_PRESENTATION_PACKAGE = "@deepseek-ai/dsh-agent-tool-presentation";
 /** The id the `dispatch` preset is selectable under. */
 const DISPATCH_PRESET_ID = "dispatch";
 /**
@@ -92542,7 +92881,7 @@ const DISPATCH_PRESET_ID = "dispatch";
 const DISPATCH_PRESET = {
 	id: DISPATCH_PRESET_ID,
 	name: "调度模式",
-	description: "基于 PTC 模式的调度 Agent：先分诊任务复杂度，L2 任务在规划前先做澄清访谈，再由主代理规划、派发子代理（显式选择子代理模型）、审查与验收。",
+	description: "基于 Code Mode 的调度 Agent：先分诊任务复杂度，L2 任务在规划前先做澄清访谈，再由主代理规划、派发子代理（显式选择子代理模型）、审查与验收。",
 	order: 5,
 	plugins: [
 		{
@@ -92589,6 +92928,7 @@ L0/L1: execute directly (or 1 subagent for L1). L2: R-G, R9, and R6 are mandator
 - Lead-Core: tightly coupled cross-module/contract changes or sequential chains where splitting duplicates reads or causes hand_back loops. -> Implement directly in continuous steps (track in todo_write, no self-briefs) and run R6 verification.
 - Hybrid: unsettled shared contracts/seams plus orthogonal downstream work. -> Implement & freeze core seams yourself first, then delegate orthogonal adapters/tests/noisy exploration per R2/R5 (or subagent_fork for warm-context isolation).
 - Fan-out: >=3 orthogonal subtasks with disjoint files, settled interfaces, and clear parallel/routing gain. -> Coordinate (plan, R2/R5 dispatch, R6 review/acceptance, docs, non-delegable or disjoint parallel modules); never edit an active child's Boundary.
+- [Media generation] Generate/revise/retry images directly; delegate complex creative work, never a bare call.
 
 ## R2 · Model Routing (Check Availability First, Then Decide How to Dispatch)
 Check whether list_subagent_models exists (in PTC mode: tools.list_subagent_models). The tool row and provider/model/reasoning_effort parameters are mounted statically, so they are present even in a session that authorized no route at all. Read that fact instead of inferring it from the tool's output:
@@ -92833,9 +93173,8 @@ Fallback is a task-scoped, non-session-wide exception for delegated briefs: it c
 			}
 		},
 		{
-			id: "tool-presentation",
-			name: "@deepseek-ai/dsh-agent-tool-presentation",
-			config: { mode: "ptc" }
+			id: "code-mode",
+			name: CODEMODE_PACKAGE
 		},
 		{
 			id: "present",
@@ -92859,8 +93198,16 @@ Fallback is a task-scoped, non-session-wide exception for delegated briefs: it c
 * the export is absent; older harnesses keep it because their main entry does not
 * register the tool.
 *
-* When the standalone PTC executor exists, it replaces the deprecated
-* agent-tool-presentation compatibility row and its `{ mode: 'ptc' }` config.
+* Code Mode needs the native tool executor (it is the pipeline the program's
+* sub-calls are delegated to), so that package's presence decides the
+* presentation rows:
+*
+* - resolvable: the `code-mode` row mounts as-is and no PTC executor row exists
+*   beside it (one executor per scope);
+* - absent: the row falls back to the deprecated agent-tool-presentation row and,
+*   when the standalone PTC executor exists, to that executor instead — the
+*   behaviour of every generation before Code Mode.
+*
 * @param resolves - whether a bare specifier resolves in this installation.
 * @returns the preset definition for the running harness generation.
 */
@@ -92868,7 +93215,8 @@ function resolveDispatchPreset(resolves = resolvesFromHere) {
 	const hasWorkingDirectory = resolves(WORKING_DIRECTORY_PACKAGE);
 	const hasLegacyListAgents = resolves("@deepseek-ai/dsh-tool-subagent-control/list-agents");
 	const hasPtcExecutor = resolves(PTC_EXECUTOR_PACKAGE);
-	if (!hasWorkingDirectory && hasLegacyListAgents && !hasPtcExecutor) return DISPATCH_PRESET;
+	const hasNativeExecutor = resolves(NATIVE_EXECUTOR_PACKAGE);
+	if (!hasWorkingDirectory && hasLegacyListAgents && !hasPtcExecutor && hasNativeExecutor) return DISPATCH_PRESET;
 	return {
 		...DISPATCH_PRESET,
 		plugins: DISPATCH_PRESET.plugins.map((row) => {
@@ -92876,14 +93224,14 @@ function resolveDispatchPreset(resolves = resolvesFromHere) {
 				...row,
 				config: row.config.filter((nested) => nested.id !== "tool-subagent-list-agents")
 			};
-			if (row.id === "tool-presentation" && hasPtcExecutor) {
-				const { config: _omitted, ...rest } = row;
-				return {
-					...rest,
-					id: "tool-executor-ptc",
-					name: PTC_EXECUTOR_PACKAGE
-				};
-			}
+			if (row.id === "code-mode" && !hasNativeExecutor) return hasPtcExecutor ? {
+				id: "tool-executor-ptc",
+				name: PTC_EXECUTOR_PACKAGE
+			} : {
+				id: "tool-presentation",
+				name: AGENT_TOOL_PRESENTATION_PACKAGE,
+				config: { mode: "ptc" }
+			};
 			if (row.id !== "persona" || !hasWorkingDirectory || typeof row.config !== "object" || row.config === null) return row;
 			const { suffix: _omitted, ...rest } = row.config;
 			return {
@@ -94760,12 +95108,13 @@ const CACHE_WARMUP_PROVIDER = "kimi-code";
 /**
 * 允许进入结果投影的工具集合。
 *
-* 除了 PTC 的 `run_code`，宿主的独立 Shell 与后台任务输出工具（`win_bash`、
-* `bash`、`pwsh`、`job_output`）同样经常吐出整屏测试/构建日志。源码读取/编辑类
-* 工具（`read`、`edit`、`grep`、`glob`、CodeGraph 等）不在此列，保持 100% 原样。
+* 除了 PTC 家族的程序传输（`run_code` 与 Code Mode 的 `code_run`），宿主的独立
+* Shell 与后台任务输出工具（`win_bash`、`bash`、`pwsh`、`job_output`）同样经常
+* 吐出整屏测试/构建日志。源码读取/编辑类工具（`read`、`edit`、`grep`、`glob`、
+* CodeGraph 等）不在此列，保持 100% 原样。
 */
 const CACHE_WARMUP_SOURCE_TOOLS = /* @__PURE__ */ new Set([
-	"run_code",
+	...CACHE_WARMUP_PTC_TRANSPORT_TOOLS,
 	"win_bash",
 	"bash",
 	"pwsh",
@@ -94782,7 +95131,7 @@ const CACHE_WARMUP_SECTION_NAME = "plugin:cache-warmup";
 const CACHE_WARMUP_GUIDANCE = [
 	"## Result previews",
 	"",
-	"On large `run_code` results this line may replace the output with a preview: a short description plus one or more `ref://<session>/<sha256>` handles.",
+	"On large `run_code`/`code_run` results this line may replace the output with a preview: a short description plus one or more `ref://<session>/<sha256>` handles.",
 	"",
 	"- A preview is **not** the full result. It states `complete`, `omitted` and `nextOffset` explicitly; treat an incomplete preview as incomplete data, not as the whole output.",
 	"- To read the original, call `cache_warmup_result` with `action: \"page\"` and that `refId`, then follow `nextOffset` until `complete` is true.",
@@ -95001,7 +95350,8 @@ function installCacheWarmup(ctx, options) {
 	*
 	* 决策取舍写在代码里，因为它全是「什么时候**不动**」：
 	* - 不是 `accept`（`block` 的 feedback 是别人的东西）；
-	* - 工具名不是 `run_code`、线路不是本线、会话拿不到；
+	* - 工具名不在源工具集合里（`run_code`/`code_run`/Shell/`job_output`）、线路不是
+	*   本线、会话拿不到；
 	* - 没有存储、内容为空。
 	* 上面任何一条成立就原样返回同一个决策对象。
 	*
@@ -95019,7 +95369,7 @@ function installCacheWarmup(ctx, options) {
 		const retrievalTool = CACHE_WARMUP_RETRIEVAL_TOOLS.has(exec.name);
 		if (!sourceTool && !retrievalTool) return decision;
 		const settings = options.settings();
-		const ptcRetrieval = exec.name === "run_code" && settings.retrievalEnabled === true;
+		const ptcRetrieval = isPtcTransportName(exec.name) && settings.retrievalEnabled === true;
 		if (sourceTool && !settings.enabled && !ptcRetrieval) return decision;
 		if (retrievalTool && settings.retrievalEnabled !== true) return decision;
 		const navigation = retrievalTool || ptcRetrieval ? cacheWarmupNavigationIntentOf(exec.agent) : void 0;