johns-harness 2026.9.13 → 2026.9.14

package/README.md

@@ -55,7 +55,10 @@ Expired ChatGPT credentials trigger an owner notice with the `/login` recovery c
 
 <!-- JOHNNESS_PATCH_DEFAULTS_61 -->
 ### Batteries included
-The harness ships the current model catalog and the short aliases `opus`, `sonnet`, `fable`, `astra`, `sol`, `luna`, `terra`, and `gpt`, so `/model opus` works on a fresh install with no `models.providers` block. Channels you configure load without a `plugins.allow` list; only an explicit `enabled: false` or `plugins.deny` turns one off. Updating the harness updates the catalog and aliases for every agent.
+The harness ships the current model catalog and the short aliases `opus`, `sonnet`, `fable`, `astra`, `sol`, `luna`, `terra`, and `gpt`, so `/model opus` works on a fresh install with no `models.providers` block. Channels you configure load without a `plugins.allow` list; only an explicit `enabled: false` or `plugins.deny` turns one off. Updating the harness updates the catalog and aliases for every agent. Image generation and editing use GPT Image 2 through the `image_generate` tool: `openai-codex/gpt-image-2` on the ChatGPT subscription first, `openai/gpt-image-2` on the API key second (`agents.defaults.imageGenerationModel`).
+
+### Updating from chat
+Send `/update` to install the newest `johns-harness` on the machine the gateway runs on and restart into it; `/update 2026.9.14` pins an exact version. Owner only. The reply names the current and target versions, a second `/update` while one is running is refused, and the first message after the restart confirms the running version. On a writable host the package is reinstalled into the existing global prefix. On an immutable image with a persistent volume (Fly), it is installed into `$JOHNNESS_STATE_DIR/runtime/johnness` and the entrypoint prefers that runtime when it is newer than the image: `exec node "$(node /opt/johnness/lib/node_modules/johns-harness/dist/runtime-path.js)" gateway run`. `JOHNNESS_UPDATE_PREFIX` overrides the target. On failure the reply carries the last lines of npm output and the one command that fixes it.
 
 ### From source
 
@@ -68,8 +71,8 @@ node johnness.mjs --help
 ### Verify
 
 ```bash
-npm test                        # 701 tests against the installed dependency tree
-bash scripts/verify-patches.sh  # 258 checks across every patch family
+npm test                        # 767 tests against the installed dependency tree
+bash scripts/verify-patches.sh  # 360 checks across every patch family
 ```
 
 ## Launch a swarm with one command
@@ -115,7 +118,7 @@ Coding agents today run as isolated processes. Two agents on the same repository
 - **Memory built for production.** Tiered recall that traces from consolidated reflections down to the verbatim record, surviving compaction and shared across the swarm. Installed and enabled by default.
 - **Production authority per commit.** Promotion is granted to an exact SHA, never to a branch name, so one worker's authorization never covers another worker's commits.
 - **An append-only action log.** Agents record every consequential action to `ACTION_LOG.md` and read it before acting.
-- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 59 patch families, each with a regression test and a rollback path.
+- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 62 patch families, each with a regression test and a rollback path.
 - **Reliability with a definition.** Bounded retries, explicit failure states, exact-once continuation, context-pressure recovery, durable delivery, and supervised gateway recovery.
 - **Coding first, phone optional.** Direct the work at a high level from a chat channel while agents plan, implement, test, coordinate, and stage releases unattended.
 - **Local voice.** Optional native Whisper transcription of inbound audio, entirely on your machine. Off by default. [Setup](docs/NATIVE-WHISPER-MUSE.md).
@@ -182,7 +185,7 @@ The log is a [`RULES.md`](RULES.md) workspace convention enforced through the ac
 
 ## Patch families
 
-The runtime carries 59 patch families. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 258 checks against the package tree and installed dependencies, and 701 tests run against the installed dependency tree.
+The runtime carries 62 patch families. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 360 checks against the package tree and installed dependencies, and 767 tests run against the installed dependency tree.
 
 Every family follows the same six steps: reproduce the failure, trace the exact runtime path, make the smallest source-level change that restores the invariant, add a regression test and a patch marker, run the verifier, and retain rollback artifacts. The full index: [`docs/PATCHES.md`](docs/PATCHES.md).
 
@@ -199,7 +202,7 @@ Every family follows the same six steps: reproduce the failure, trace the exact
 ## Documentation
 
 - [`docs/index.md`](docs/index.md): runtime docs, from gateway and channels to plugins, nodes, and CLI reference.
-- [`docs/PATCHES.md`](docs/PATCHES.md): the 59 patch families, one record each.
+- [`docs/PATCHES.md`](docs/PATCHES.md): the 62 patch families, one record each.
 - [`docs/NATIVE-WHISPER-MUSE.md`](docs/NATIVE-WHISPER-MUSE.md): local Whisper transcription setup.
 - [`RULES.md`](RULES.md): the default operating rules, including Rule Zero on production authorization.
 

package/dist/auth-profiles-5CHn7vq1.js

@@ -6443,6 +6443,17 @@ function applyLegacyAudioTranscriptionModel(params) {
 	params.changes.push(params.alreadySetMessage);
 }
 const LEGACY_CONFIG_MIGRATIONS_PART_2 = [
+	{
+		id: "agent.image-generation-model-v1",
+		describe: "Migrate agents.defaults.imageGenerationModel string to primary/fallbacks",
+		apply: (raw, changes) => {
+			const defaults = getRecord(getRecord(raw.agents)?.defaults);
+			if (!defaults || typeof defaults.imageGenerationModel !== "string") return;
+			const primary = defaults.imageGenerationModel.trim();
+			defaults.imageGenerationModel = primary ? { primary, fallbacks: [] } : void 0;
+			changes.push("Migrated agents.defaults.imageGenerationModel string to primary/fallbacks");
+		}
+	}, // JOHNNESS_PATCH_GPT_IMAGE_62
 	{
 		id: "agent.model-config-v2",
 		describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
@@ -10876,6 +10887,7 @@ function isValidNonNegativeByteSizeString(value) {
 const AgentDefaultsSchema = z.object({
 	model: AgentModelSchema.optional(),
 	imageModel: AgentModelSchema.optional(),
+	imageGenerationModel: AgentModelSchema.optional(), // JOHNNESS_PATCH_GPT_IMAGE_62
 	pdfModel: AgentModelSchema.optional(),
 	pdfMaxBytesMb: z.number().positive().optional(),
 	pdfMaxPages: z.number().int().positive().optional(),

package/dist/commands-registry-C78-tPS3.js

@@ -1,3 +1,4 @@
+// JOHNNESS_PATCH_UPDATE_COMMAND_62
 // JOHNNESS_PATCH_DEVICE_LOGIN_60
 // JOHNNESS_PATCH_DEVICE_LOGIN_60B
 import { l as escapeRegExp } from "./utils-DC4zYvW0.js";
@@ -181,6 +182,19 @@ function buildChatCommands() {
 				captureRemaining: true
 			}]
 		}),
+		defineChatCommand({
+			key: "update",
+			nativeName: "update",
+			description: "Install the newest johns-harness and restart (owner only).",
+			textAlias: "/update",
+			category: "management",
+			args: [{
+				name: "version",
+				description: "Exact version to install (default latest)",
+				type: "string",
+				required: false
+			}]
+		}),
 		defineChatCommand({
 			key: "login",
 			nativeName: "login",

package/dist/commands-registry-D0Jkz-Sn.js

@@ -1,3 +1,4 @@
+// JOHNNESS_PATCH_UPDATE_COMMAND_62
 // JOHNNESS_PATCH_DEVICE_LOGIN_60
 // JOHNNESS_PATCH_DEVICE_LOGIN_60B
 import { D as isPlainObject, u as escapeRegExp } from "./logger-Bj0Xl6pn.js";
@@ -218,6 +219,19 @@ function buildChatCommands() {
 				captureRemaining: true
 			}]
 		}),
+		defineChatCommand({
+			key: "update",
+			nativeName: "update",
+			description: "Install the newest johns-harness and restart (owner only).",
+			textAlias: "/update",
+			category: "management",
+			args: [{
+				name: "version",
+				description: "Exact version to install (default latest)",
+				type: "string",
+				required: false
+			}]
+		}),
 		defineChatCommand({
 			key: "login",
 			nativeName: "login",

package/dist/commands-registry-DJWLO-6B.js

@@ -1,3 +1,4 @@
+// JOHNNESS_PATCH_UPDATE_COMMAND_62
 // JOHNNESS_PATCH_DEVICE_LOGIN_60
 // JOHNNESS_PATCH_DEVICE_LOGIN_60B
 import { D as isPlainObject, u as escapeRegExp } from "./logger-BW8uLq6f.js";
@@ -218,6 +219,19 @@ function buildChatCommands() {
 				captureRemaining: true
 			}]
 		}),
+		defineChatCommand({
+			key: "update",
+			nativeName: "update",
+			description: "Install the newest johns-harness and restart (owner only).",
+			textAlias: "/update",
+			category: "management",
+			args: [{
+				name: "version",
+				description: "Exact version to install (default latest)",
+				type: "string",
+				required: false
+			}]
+		}),
 		defineChatCommand({
 			key: "login",
 			nativeName: "login",

package/dist/commands-registry-l51VuG0m.js

@@ -1,3 +1,4 @@
+// JOHNNESS_PATCH_UPDATE_COMMAND_62
 // JOHNNESS_PATCH_DEVICE_LOGIN_60
 // JOHNNESS_PATCH_DEVICE_LOGIN_60B
 import { Bi as DEFAULT_PROVIDER, Or as resolveConfiguredModelRef, zi as DEFAULT_MODEL } from "./auth-profiles-5CHn7vq1.js";
@@ -181,6 +182,19 @@ function buildChatCommands() {
 				captureRemaining: true
 			}]
 		}),
+		defineChatCommand({
+			key: "update",
+			nativeName: "update",
+			description: "Install the newest johns-harness and restart (owner only).",
+			textAlias: "/update",
+			category: "management",
+			args: [{
+				name: "version",
+				description: "Exact version to install (default latest)",
+				type: "string",
+				required: false
+			}]
+		}),
 		defineChatCommand({
 			key: "login",
 			nativeName: "login",

package/dist/compact-B247y5Qt.js

@@ -1,3 +1,5 @@
+import { createImageGenerateTool } from "./image-generate.js";
+import { handleUpdateCommand } from "./update-command.js";
 // JOHNNESS_PATCH_DEVICE_LOGIN_60
 // JOHNNESS_PATCH_DEVICE_LOGIN_60B
 import { handleDeviceLoginCommand } from "./codex-oauth-device.js";
@@ -11283,6 +11285,7 @@ const TRUSTED_TOOL_RESULT_MEDIA = new Set([
 	"exec",
 	"gateway",
 	"image",
+	"image_generate",
 	"memory_get",
 	"memory_search",
 	"message",
@@ -15583,7 +15586,8 @@ function buildAgentSystemPrompt(params) {
 		sessions_spawn: acpSpawnRuntimeEnabled ? "Spawn an isolated sub-agent or ACP coding session (runtime=\"acp\" requires `agentId` unless `acp.defaultAgent` is configured; ACP harness ids follow acp.allowedAgents, not agents_list)" : "Spawn an isolated sub-agent session",
 		subagents: "List, steer, or kill sub-agent runs for this requester session",
 		session_status: "Show a /status-equivalent status card (usage + time + Reasoning/Verbose/Elevated); use for model-use questions (📊 session_status); optional per-session model override",
-		image: "Analyze an image with the configured image model"
+		image: "Analyze an image with the configured image model",
+		image_generate: "Generate or edit images with GPT Image 2 (subscription first, API key second)"
 	};
 	const toolOrder = [
 		"read",
@@ -15610,7 +15614,8 @@ function buildAgentSystemPrompt(params) {
 		"sessions_send",
 		"subagents",
 		"session_status",
-		"image"
+		"image",
+		"image_generate"
 	];
 	const canonicalToolNames = (params.toolNames ?? []).map((tool) => tool.trim()).filter(Boolean);
 	const canonicalByNormalized = /* @__PURE__ */ new Map();
@@ -40979,6 +40984,8 @@ function resolveSessionEntryForHookSessionKey(sessionStore, sessionKey) {
 async function handleCommands(params) {
 	const deviceLoginReply = await handleDeviceLoginCommand(params, shouldHandleTextCommands({ cfg: params.cfg, surface: params.command.surface, commandSource: params.ctx.CommandSource }), { routeReply, callGateway });
 	if (deviceLoginReply) return deviceLoginReply;
+	const updateReply = await handleUpdateCommand(params, shouldHandleTextCommands({ cfg: params.cfg, surface: params.command.surface, commandSource: params.ctx.CommandSource }), { routeReply, callGateway, writeRestartSentinel, extractDeliveryInfo, restart: () => scheduleGatewaySigusr1Restart({ reason: "/update" }) }); // JOHNNESS_PATCH_UPDATE_COMMAND_62
+	if (updateReply) return updateReply;
 	if (HANDLERS === null) HANDLERS = [
 		handlePluginCommand,
 		handleBashCommand,
@@ -55646,6 +55653,16 @@ function createJohnnessTools(options) {
 		fsPolicy: options?.fsPolicy,
 		modelHasVision: options?.modelHasVision
 	}) : null;
+	const imageGenerateTool = options?.agentDir?.trim() ? createImageGenerateTool({
+		config: options?.config,
+		agentDir: options.agentDir,
+		workspaceDir,
+		sandbox: options?.sandboxRoot && options?.sandboxFsBridge ? { root: options.sandboxRoot, bridge: options.sandboxFsBridge } : void 0
+	}, {
+		resolveApiKeyForProvider,
+		loadWebMedia,
+		localRoots: resolveMediaToolLocalRoots(workspaceDir, { workspaceOnly: options?.fsPolicy?.workspaceOnly === true })
+	}) : null; // JOHNNESS_PATCH_GPT_IMAGE_62
 	const pdfTool = options?.agentDir?.trim() ? createPdfTool({
 		config: options?.config,
 		agentDir: options.agentDir,
@@ -55765,6 +55782,7 @@ function createJohnnessTools(options) {
 		...webSearchTool ? [webSearchTool] : [],
 		...webFetchTool ? [webFetchTool] : [],
 		...imageTool ? [imageTool] : [],
+		...imageGenerateTool ? [imageGenerateTool] : [],
 		...pdfTool ? [pdfTool] : []
 	];
 	const pluginTools = resolvePluginTools({

package/dist/config-koj5M_EO.js

@@ -3132,6 +3132,17 @@ function applyLegacyAudioTranscriptionModel(params) {
 	params.changes.push(params.alreadySetMessage);
 }
 const LEGACY_CONFIG_MIGRATIONS_PART_2 = [
+	{
+		id: "agent.image-generation-model-v1",
+		describe: "Migrate agents.defaults.imageGenerationModel string to primary/fallbacks",
+		apply: (raw, changes) => {
+			const defaults = getRecord(getRecord(raw.agents)?.defaults);
+			if (!defaults || typeof defaults.imageGenerationModel !== "string") return;
+			const primary = defaults.imageGenerationModel.trim();
+			defaults.imageGenerationModel = primary ? { primary, fallbacks: [] } : void 0;
+			changes.push("Migrated agents.defaults.imageGenerationModel string to primary/fallbacks");
+		}
+	}, // JOHNNESS_PATCH_GPT_IMAGE_62
 	{
 		id: "agent.model-config-v2",
 		describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
@@ -6762,6 +6773,7 @@ function isValidNonNegativeByteSizeString(value) {
 const AgentDefaultsSchema = z.object({
 	model: AgentModelSchema.optional(),
 	imageModel: AgentModelSchema.optional(),
+	imageGenerationModel: AgentModelSchema.optional(), // JOHNNESS_PATCH_GPT_IMAGE_62
 	pdfModel: AgentModelSchema.optional(),
 	pdfMaxBytesMb: z.number().positive().optional(),
 	pdfMaxPages: z.number().int().positive().optional(),

package/dist/daemon-cli.js

@@ -6112,6 +6112,17 @@ function applyLegacyAudioTranscriptionModel(params) {
 	params.changes.push(params.alreadySetMessage);
 }
 const LEGACY_CONFIG_MIGRATIONS_PART_2 = [
+	{
+		id: "agent.image-generation-model-v1",
+		describe: "Migrate agents.defaults.imageGenerationModel string to primary/fallbacks",
+		apply: (raw, changes) => {
+			const defaults = getRecord(getRecord(raw.agents)?.defaults);
+			if (!defaults || typeof defaults.imageGenerationModel !== "string") return;
+			const primary = defaults.imageGenerationModel.trim();
+			defaults.imageGenerationModel = primary ? { primary, fallbacks: [] } : void 0;
+			changes.push("Migrated agents.defaults.imageGenerationModel string to primary/fallbacks");
+		}
+	}, // JOHNNESS_PATCH_GPT_IMAGE_62
 	{
 		id: "agent.model-config-v2",
 		describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
@@ -9694,6 +9705,7 @@ function isValidNonNegativeByteSizeString(value) {
 const AgentDefaultsSchema = z.object({
 	model: AgentModelSchema.optional(),
 	imageModel: AgentModelSchema.optional(),
+	imageGenerationModel: AgentModelSchema.optional(), // JOHNNESS_PATCH_GPT_IMAGE_62
 	pdfModel: AgentModelSchema.optional(),
 	pdfMaxBytesMb: z.number().positive().optional(),
 	pdfMaxPages: z.number().int().positive().optional(),

package/dist/image-generate.js

@@ -0,0 +1,269 @@
+// JOHNNESS_PATCH_GPT_IMAGE_62
+// First-class `image_generate` agent tool: OpenAI Images API (generations when no input
+// image, edits when one is given) with the model from `agents.defaults.imageGenerationModel`.
+// Default order: `openai-codex/gpt-image-2` (ChatGPT subscription, Family 58 OAuth token)
+// then `openai/gpt-image-2` (OPENAI_API_KEY or the configured openai provider key).
+// A provider that rejects the request as unsupported (404/405/501, 429 usage limit, or no
+// credentials) yields to the next entry; the result names the provider that served it.
+// Output is written as PNG under <workspace>/media/generated and the path is returned so the
+// agent can send it with the `message` tool. Path safety mirrors createImageTool: inputs load
+// through loadWebMedia with the same local roots, outputs never escape the workspace.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Type } from "@sinclair/typebox";
+
+export const DEFAULT_IMAGE_GENERATION_MODEL = Object.freeze({
+  primary: "openai-codex/gpt-image-2",
+  fallbacks: Object.freeze(["openai/gpt-image-2"]),
+});
+export const IMAGE_GENERATION_MODEL_ID = "gpt-image-2";
+const OPENAI_BASE = "https://api.openai.com/v1";
+const CODEX_BASE = "https://chatgpt.com/backend-api/codex";
+const SIZES = new Set(["1024x1024", "1536x1024", "1024x1536", "auto"]);
+const DEFAULT_MAX_INPUT_BYTES = 20 * 1024 * 1024;
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+
+export function coerceImageGenerationModelConfig(cfg) {
+  const raw = cfg?.agents?.defaults?.imageGenerationModel;
+  if (typeof raw === "string" && raw.trim()) return { primary: raw.trim(), fallbacks: [] };
+  if (raw && typeof raw === "object") {
+    const primary = typeof raw.primary === "string" && raw.primary.trim() ? raw.primary.trim() : void 0;
+    const fallbacks = Array.isArray(raw.fallbacks) ? raw.fallbacks.filter((v) => typeof v === "string" && v.trim()).map((v) => v.trim()) : [];
+    if (primary || fallbacks.length > 0) return { primary: primary ?? fallbacks.shift(), fallbacks };
+  }
+  return { primary: DEFAULT_IMAGE_GENERATION_MODEL.primary, fallbacks: [...DEFAULT_IMAGE_GENERATION_MODEL.fallbacks] };
+}
+
+export function listImageGenerationCandidates(cfg) {
+  const { primary, fallbacks } = coerceImageGenerationModelConfig(cfg);
+  const out = [];
+  for (const ref of [primary, ...fallbacks]) {
+    if (!ref || out.some((c) => c.ref === ref)) continue;
+    const slash = ref.indexOf("/");
+    if (slash <= 0) continue;
+    out.push({ ref, provider: ref.slice(0, slash), model: ref.slice(slash + 1) });
+  }
+  return out;
+}
+
+export function codexAccountIdFromToken(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(String(token).split(".")[1], "base64url").toString("utf8"));
+    const id = payload?.[JWT_CLAIM_PATH]?.chatgpt_account_id;
+    if (typeof id === "string" && id) return id;
+  } catch {}
+  return null;
+}
+
+/** Endpoint + headers for one provider. Same OAuth transport shape as openai-codex-responses. */
+export function buildProviderRequest({ provider, apiKey, edit, userAgent = "johnness" }) {
+  if (provider === "openai-codex") {
+    const accountId = codexAccountIdFromToken(apiKey);
+    if (!accountId) throw new ProviderUnsupported("codex token has no chatgpt_account_id");
+    return {
+      url: `${CODEX_BASE}/images/${edit ? "edits" : "generations"}`,
+      headers: { Authorization: `Bearer ${apiKey}`, "chatgpt-account-id": accountId, originator: "pi", "User-Agent": userAgent },
+    };
+  }
+  return { url: `${OPENAI_BASE}/images/${edit ? "edits" : "generations"}`, headers: { Authorization: `Bearer ${apiKey}` } };
+}
+
+export class ProviderUnsupported extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "ProviderUnsupported";
+    this.status = status;
+  }
+}
+
+export function isUnsupportedStatus(status, bodyText = "") {
+  if (status === 404 || status === 405 || status === 501) return true;
+  if (status === 429 && /usage_limit|usage limit/i.test(bodyText)) return true;
+  if (status === 401 || status === 403) return true;
+  return false;
+}
+
+function redact(text) {
+  return String(text ?? "").replace(/[A-Za-z0-9_-]{40,}/g, "<redacted>").slice(0, 400);
+}
+
+function sanitizeName(input, fallback) {
+  const base = String(input ?? "").trim().replace(/\.[a-z0-9]+$/i, "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return base || fallback;
+}
+
+export function resolveOutputPath({ workspaceDir, output, index = 0, count = 1 }) {
+  const root = path.resolve(workspaceDir);
+  const mediaDir = path.join(root, "media", "generated");
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  let target;
+  if (output && String(output).trim()) {
+    const raw = String(output).trim();
+    if (/^[a-z][a-z0-9+.-]*:/i.test(raw) && !/^[a-zA-Z]:[\\/]/.test(raw)) throw new Error(`output must be a workspace path, got ${raw}`);
+    const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw);
+    const rel = path.relative(root, resolved);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`output must stay inside the workspace: ${raw}`);
+    target = count > 1 ? path.join(path.dirname(resolved), `${sanitizeName(path.basename(resolved), "image")}-${index + 1}.png`) : resolved.replace(/\.[a-z0-9]+$/i, "") + ".png";
+  } else {
+    target = path.join(mediaDir, `gpt-image-${stamp}${count > 1 ? `-${index + 1}` : ""}.png`);
+  }
+  return target;
+}
+
+export function validateParams(args) {
+  const record = args && typeof args === "object" ? args : {};
+  const prompt = typeof record.prompt === "string" ? record.prompt.trim() : "";
+  if (!prompt) throw new Error("prompt required");
+  const inputs = [];
+  if (typeof record.image === "string" && record.image.trim()) inputs.push(record.image.trim());
+  if (Array.isArray(record.images)) for (const v of record.images) if (typeof v === "string" && v.trim()) inputs.push(v.trim());
+  if (inputs.length > 4) throw new Error("at most 4 input images");
+  const mask = typeof record.mask === "string" && record.mask.trim() ? record.mask.trim() : void 0;
+  if (mask && inputs.length === 0) throw new Error("mask requires an input image");
+  const size = typeof record.size === "string" && record.size.trim() ? record.size.trim() : "auto";
+  if (!SIZES.has(size)) throw new Error(`size must be one of ${[...SIZES].join(", ")}`);
+  const countRaw = typeof record.count === "number" ? Math.floor(record.count) : 1;
+  if (!Number.isFinite(countRaw) || countRaw < 1 || countRaw > 4) throw new Error("count must be 1..4");
+  const quality = typeof record.quality === "string" && ["low", "medium", "high", "auto"].includes(record.quality) ? record.quality : void 0;
+  return { prompt, inputs, mask, size, count: countRaw, quality, output: typeof record.output === "string" ? record.output : void 0, model: typeof record.model === "string" && record.model.trim() ? record.model.trim() : void 0 };
+}
+
+async function callProvider({ candidate, apiKey, params, images, mask, fetchImpl, userAgent }) {
+  const edit = images.length > 0;
+  const { url, headers } = buildProviderRequest({ provider: candidate.provider, apiKey, edit, userAgent });
+  let body;
+  if (edit) {
+    body = new FormData();
+    body.set("model", candidate.model);
+    body.set("prompt", params.prompt);
+    body.set("n", String(params.count));
+    if (params.size !== "auto") body.set("size", params.size);
+    if (params.quality) body.set("quality", params.quality);
+    images.forEach((img, i) => body.append("image[]", new Blob([img.buffer], { type: img.mimeType }), `input-${i + 1}.${img.mimeType.includes("jpeg") ? "jpg" : "png"}`));
+    if (mask) body.set("mask", new Blob([mask.buffer], { type: mask.mimeType }), "mask.png");
+  } else {
+    headers["content-type"] = "application/json";
+    body = JSON.stringify({ model: candidate.model, prompt: params.prompt, n: params.count, ...(params.size !== "auto" ? { size: params.size } : {}), ...(params.quality ? { quality: params.quality } : {}) });
+  }
+  const res = await fetchImpl(url, { method: "POST", headers, body });
+  const text = await res.text();
+  if (!res.ok) {
+    if (isUnsupportedStatus(res.status, text)) throw new ProviderUnsupported(`${candidate.provider} ${res.status}: ${redact(text)}`, res.status);
+    throw new Error(`${candidate.provider} ${res.status}: ${redact(text)}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(`${candidate.provider}: non-JSON response`);
+  }
+  const data = Array.isArray(json?.data) ? json.data : [];
+  const buffers = [];
+  for (const item of data) {
+    if (typeof item?.b64_json === "string") buffers.push(Buffer.from(item.b64_json, "base64"));
+    else if (typeof item?.url === "string") {
+      const r = await fetchImpl(item.url);
+      if (!r.ok) throw new Error(`${candidate.provider}: image download HTTP ${r.status}`);
+      buffers.push(Buffer.from(await r.arrayBuffer()));
+    }
+  }
+  if (buffers.length === 0) throw new Error(`${candidate.provider}: response carried no image data`);
+  return { buffers, usage: json?.usage ?? null, mode: edit ? "edit" : "generate" };
+}
+
+/**
+ * Try each candidate in order. Returns { provider, model, buffers, usage, mode, attempts }.
+ * `resolveAuth({ provider })` -> { apiKey } or throws; a throw counts as unsupported for that provider.
+ */
+export async function generateWithFallback({ cfg, params, images, mask, resolveAuth, fetchImpl = fetch, userAgent }) {
+  const candidates = params.model ? [{ ref: params.model, provider: params.model.split("/")[0], model: params.model.split("/").slice(1).join("/") || IMAGE_GENERATION_MODEL_ID }] : listImageGenerationCandidates(cfg);
+  if (candidates.length === 0) throw new Error("No image generation model configured. Set agents.defaults.imageGenerationModel.primary.");
+  const attempts = [];
+  for (const candidate of candidates) {
+    let apiKey;
+    try {
+      apiKey = (await resolveAuth({ provider: candidate.provider }))?.apiKey;
+      if (!apiKey) throw new Error("no credentials");
+    } catch (error) {
+      attempts.push({ provider: candidate.provider, skipped: `auth: ${redact(error?.message ?? error)}` });
+      continue;
+    }
+    try {
+      const result = await callProvider({ candidate, apiKey, params, images, mask, fetchImpl, userAgent });
+      return { provider: candidate.provider, model: candidate.model, ...result, attempts };
+    } catch (error) {
+      if (error instanceof ProviderUnsupported) {
+        attempts.push({ provider: candidate.provider, skipped: error.message });
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error(`No image provider could serve the request. ${attempts.map((a) => `${a.provider}: ${a.skipped}`).join(" | ")}`);
+}
+
+/**
+ * Tool factory. `deps` are supplied by the bundle so this module owns no second auth path:
+ *   resolveApiKeyForProvider({ provider, cfg, agentDir }) from auth-profiles (Family 58 owner refresh)
+ *   loadWebMedia(pathOrUrl, { maxBytes, localRoots }) with the same roots createImageTool uses
+ */
+export function createImageGenerateTool(options, deps) {
+  const agentDir = options?.agentDir?.trim();
+  const workspaceDir = options?.workspaceDir?.trim();
+  if (!agentDir || !workspaceDir) return null;
+  if (options?.sandbox?.root?.trim()) return null;
+  const localRoots = deps.localRoots ?? [workspaceDir];
+  const fetchImpl = deps.fetch ?? fetch;
+  return {
+    label: "Image Generate",
+    name: "image_generate",
+    description: "Generate or edit images with GPT Image 2 (default openai-codex/gpt-image-2, then openai/gpt-image-2). Give a prompt; add image (or images, up to 4) to edit, and an optional mask PNG. Writes PNG files under the workspace media/generated folder and returns their paths; send them with the message tool.",
+    parameters: Type.Object({
+      prompt: Type.String({ description: "What to draw or how to change the input image." }),
+      image: Type.Optional(Type.String({ description: "Input image path to edit (workspace or allowed local root)." })),
+      images: Type.Optional(Type.Array(Type.String(), { description: "Multiple input images to edit together (max 4)." })),
+      mask: Type.Optional(Type.String({ description: "PNG mask path; transparent areas are edited." })),
+      size: Type.Optional(Type.String({ description: "1024x1024, 1536x1024, 1024x1536, or auto (default)." })),
+      count: Type.Optional(Type.Number({ description: "Number of images, 1..4 (default 1)." })),
+      quality: Type.Optional(Type.String({ description: "low, medium, high, or auto." })),
+      output: Type.Optional(Type.String({ description: "Output path inside the workspace (default media/generated/gpt-image-<timestamp>.png)." })),
+      model: Type.Optional(Type.String({ description: "Override provider/model, for example openai/gpt-image-2." })),
+    }),
+    execute: async (_toolCallId, args) => {
+      const params = validateParams(args);
+      const maxBytes = deps.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES;
+      const load = async (ref) => {
+        const raw = ref.startsWith("@") ? ref.slice(1).trim() : ref;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(raw) && !/^[a-zA-Z]:[\\/]/.test(raw) && !/^file:/i.test(raw)) throw new Error(`input must be a local file path: ${ref}`);
+        const media = await deps.loadWebMedia(raw.startsWith("file://") ? raw.slice(7) : raw, { maxBytes, localRoots });
+        if (media.kind !== "image") throw new Error(`Unsupported media type: ${media.kind}`);
+        return { buffer: media.buffer, mimeType: ("contentType" in media && media.contentType) || ("mimeType" in media && media.mimeType) || "image/png" };
+      };
+      const images = [];
+      for (const ref of params.inputs) images.push(await load(ref));
+      const mask = params.mask ? await load(params.mask) : void 0;
+      const outputs = Array.from({ length: params.count }, (_, i) => resolveOutputPath({ workspaceDir, output: params.output, index: i, count: params.count }));
+      const result = await generateWithFallback({
+        cfg: options?.config,
+        params,
+        images,
+        mask,
+        fetchImpl,
+        userAgent: deps.userAgent,
+        resolveAuth: ({ provider }) => deps.resolveApiKeyForProvider({ provider, cfg: options?.config, agentDir }),
+      });
+      const written = [];
+      for (let i = 0; i < result.buffers.length && i < outputs.length; i++) {
+        await fs.mkdir(path.dirname(outputs[i]), { recursive: true });
+        await fs.writeFile(outputs[i], result.buffers[i]);
+        written.push(outputs[i]);
+      }
+      const served = `${result.provider}/${result.model}`;
+      const text = [`${result.mode === "edit" ? "Edited" : "Generated"} ${written.length} image${written.length === 1 ? "" : "s"} with ${served}.`, ...written.map((p) => `MEDIA:${p}`)].join("\n");
+      return {
+        content: [{ type: "text", text }],
+        details: { provider: result.provider, model: result.model, mode: result.mode, paths: written, usage: result.usage, attempts: result.attempts },
+      };
+    },
+  };
+}

package/dist/model-selection-BGlGpPgM.js

@@ -3027,6 +3027,17 @@ function applyLegacyAudioTranscriptionModel(params) {
 	params.changes.push(params.alreadySetMessage);
 }
 const LEGACY_CONFIG_MIGRATIONS_PART_2 = [
+	{
+		id: "agent.image-generation-model-v1",
+		describe: "Migrate agents.defaults.imageGenerationModel string to primary/fallbacks",
+		apply: (raw, changes) => {
+			const defaults = getRecord(getRecord(raw.agents)?.defaults);
+			if (!defaults || typeof defaults.imageGenerationModel !== "string") return;
+			const primary = defaults.imageGenerationModel.trim();
+			defaults.imageGenerationModel = primary ? { primary, fallbacks: [] } : void 0;
+			changes.push("Migrated agents.defaults.imageGenerationModel string to primary/fallbacks");
+		}
+	}, // JOHNNESS_PATCH_GPT_IMAGE_62
 	{
 		id: "agent.model-config-v2",
 		describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
@@ -9298,6 +9309,7 @@ function isValidNonNegativeByteSizeString(value) {
 const AgentDefaultsSchema = z.object({
 	model: AgentModelSchema.optional(),
 	imageModel: AgentModelSchema.optional(),
+	imageGenerationModel: AgentModelSchema.optional(), // JOHNNESS_PATCH_GPT_IMAGE_62
 	pdfModel: AgentModelSchema.optional(),
 	pdfMaxBytesMb: z.number().positive().optional(),
 	pdfMaxPages: z.number().int().positive().optional(),

package/dist/model-selection-BU6wl1le.js

@@ -3002,6 +3002,17 @@ function applyLegacyAudioTranscriptionModel(params) {
 	params.changes.push(params.alreadySetMessage);
 }
 const LEGACY_CONFIG_MIGRATIONS_PART_2 = [
+	{
+		id: "agent.image-generation-model-v1",
+		describe: "Migrate agents.defaults.imageGenerationModel string to primary/fallbacks",
+		apply: (raw, changes) => {
+			const defaults = getRecord(getRecord(raw.agents)?.defaults);
+			if (!defaults || typeof defaults.imageGenerationModel !== "string") return;
+			const primary = defaults.imageGenerationModel.trim();
+			defaults.imageGenerationModel = primary ? { primary, fallbacks: [] } : void 0;
+			changes.push("Migrated agents.defaults.imageGenerationModel string to primary/fallbacks");
+		}
+	}, // JOHNNESS_PATCH_GPT_IMAGE_62
 	{
 		id: "agent.model-config-v2",
 		describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
@@ -9187,6 +9198,7 @@ function isValidNonNegativeByteSizeString(value) {
 const AgentDefaultsSchema = z.object({
 	model: AgentModelSchema.optional(),
 	imageModel: AgentModelSchema.optional(),
+	imageGenerationModel: AgentModelSchema.optional(), // JOHNNESS_PATCH_GPT_IMAGE_62
 	pdfModel: AgentModelSchema.optional(),
 	pdfMaxBytesMb: z.number().positive().optional(),
 	pdfMaxPages: z.number().int().positive().optional(),

package/dist/model-selection-L7RMwsG-.js

@@ -2914,6 +2914,17 @@ function applyLegacyAudioTranscriptionModel(params) {
 	params.changes.push(params.alreadySetMessage);
 }
 const LEGACY_CONFIG_MIGRATIONS_PART_2 = [
+	{
+		id: "agent.image-generation-model-v1",
+		describe: "Migrate agents.defaults.imageGenerationModel string to primary/fallbacks",
+		apply: (raw, changes) => {
+			const defaults = getRecord(getRecord(raw.agents)?.defaults);
+			if (!defaults || typeof defaults.imageGenerationModel !== "string") return;
+			const primary = defaults.imageGenerationModel.trim();
+			defaults.imageGenerationModel = primary ? { primary, fallbacks: [] } : void 0;
+			changes.push("Migrated agents.defaults.imageGenerationModel string to primary/fallbacks");
+		}
+	}, // JOHNNESS_PATCH_GPT_IMAGE_62
 	{
 		id: "agent.model-config-v2",
 		describe: "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists",
@@ -7347,6 +7358,7 @@ function isValidNonNegativeByteSizeString(value) {
 const AgentDefaultsSchema = z.object({
 	model: AgentModelSchema.optional(),
 	imageModel: AgentModelSchema.optional(),
+	imageGenerationModel: AgentModelSchema.optional(), // JOHNNESS_PATCH_GPT_IMAGE_62
 	pdfModel: AgentModelSchema.optional(),
 	pdfMaxBytesMb: z.number().positive().optional(),
 	pdfMaxPages: z.number().int().positive().optional(),