@oh-my-pi/pi-coding-agent 17.0.1 → 17.0.2

package/src/tools/bash.ts

@@ -177,6 +177,8 @@ export interface BashToolDetails {
 	wallTimeMs?: number;
 	/** Exit code of a command that ran to completion but failed (non-zero). */
 	exitCode?: number;
+	/** True when the command was killed by its timeout deadline (not a failure). */
+	timedOut?: boolean;
 	terminalId?: string;
 	async?: {
 		state: "running" | "completed" | "failed";
@@ -208,10 +210,6 @@ function normalizeResultOutput(result: BashResult | BashInteractiveResult): stri
 	return result.output || "";
 }
 
-function isInteractiveResult(result: BashResult | BashInteractiveResult): result is BashInteractiveResult {
-	return "timedOut" in result;
-}
-
 function normalizeBashEnv(env: Record<string, string> | undefined): Record<string, string> | undefined {
 	if (!env || Object.keys(env).length === 0) return undefined;
 	const normalized: Record<string, string> = {};
@@ -439,12 +437,15 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 	}
 
 	/**
-	 * Throw for outcomes that are *not* a completed command: user/timeout
-	 * aborts and a missing exit status. The foreground and bridge callers plus
-	 * the async job manager rely on these throwing so cancellations surface as
-	 * aborts and jobs are recorded as failed. A definite non-zero exit is a
-	 * completed command that failed; #buildCompletedResult surfaces it as an
-	 * error *result* (carrying execution details) rather than a throw.
+	 * Throw for outcomes that are *not* a completed command: user aborts and a
+	 * missing exit status. Timeouts are handled separately by
+	 * #buildCompletedResult, which returns a non-throwing error result with
+	 * details.timedOut=true so the renderer can show a warning border. The
+	 * foreground and bridge callers plus the async job manager rely on these
+	 * throwing so cancellations surface as aborts and jobs are recorded as
+	 * failed. A definite non-zero exit is a completed command that failed;
+	 * #buildCompletedResult surfaces it as an error *result* (carrying
+	 * execution details) rather than a throw.
 	 */
 	#throwIfUnfinished(
 		result: BashResult | BashInteractiveResult,
@@ -452,13 +453,14 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		outputText: string,
 	): void {
 		if (result.cancelled) {
-			// executeBash output already carries a `[Command cancelled]` notice from
-			// the sink; PTY/bridge interactive output does not, so annotate it here.
+			// Local executor output already carries a leading `[Command cancelled]`
+			// notice from the sink; PTY/bridge output does not, so annotate only
+			// the latter.
 			const out = normalizeResultOutput(result);
-			const annotated = isInteractiveResult(result) && out ? `${out}\n\n[Command aborted]` : out;
+			const annotated = out.startsWith("[Command cancelled]") ? out : out ? `${out}\n\n[Command aborted]` : out;
 			throw new ToolError(annotated || "Command aborted");
 		}
-		if (isInteractiveResult(result) && result.timedOut) {
+		if (result.timedOut === true) {
 			const out = normalizeResultOutput(result);
 			const message =
 				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
@@ -496,8 +498,12 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (failedExit) outputLines.push("", formatExitCodeNotice(exitCode));
 		const outputText = outputLines.join("\n");
 
-		// Aborts / timeouts / missing-status still propagate as thrown errors.
-		this.#throwIfUnfinished(result, timeoutSec, outputText);
+		// Timeouts are not failures — the command ran its course. Return an error
+		// result (isError=true for the model) but flag timedOut so the renderer
+		// uses a warning border instead of error red. Both interactive and
+		// non-interactive results carry an explicit `timedOut` field from the
+		// executor/PTY layer.
+		const isTimeout = result.timedOut === true;
 
 		const details: BashToolDetails = {};
 		if (timeoutSec === undefined) {
@@ -517,6 +523,29 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (failedExit) {
 			details.exitCode = exitCode;
 		}
+
+		if (isTimeout) {
+			details.timedOut = true;
+			const message =
+				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
+			// executeBash has already emitted this leading sink notice. PTY output
+			// has not, so provide the LLM-facing annotation exactly once.
+			if (!normalizeResultOutput(result).startsWith(`[${message}]\n`)) {
+				outputLines.push("", `[${message}]`);
+			}
+			const timeoutOutputText = await enforceInlineByteCap(outputLines.join("\n"), {
+				saveArtifact: full => saveBashOriginalArtifact(this.session, full),
+			});
+			return toolResult(details)
+				.text(timeoutOutputText)
+				.truncationFromSummary(result, { direction: "tail" })
+				.error()
+				.done();
+		}
+
+		// Non-timeout cancellations and missing exit status still propagate as thrown errors.
+		this.#throwIfUnfinished(result, timeoutSec, outputText);
+
 		// Final defense at the tool-result boundary: no bash path (client bridge,
 		// head-retention spill, minimizer miss) may emit more than
 		// ~DEFAULT_MAX_BYTES inline. No-op for already-bounded output.
@@ -992,12 +1021,8 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 								outputLines: current.output.length > 0 ? current.output.split("\n").length : 0,
 								outputBytes: current.output.length,
 							};
-							return this.#buildCompletedResult(timedOutResult, timeoutSec, {
-								requestedTimeoutSec,
-								notices: pendingNotices,
-								terminalId: handle.terminalId,
-								wallTimeMs: performance.now() - bridgeWallTimeStart,
-							});
+							this.#throwIfUnfinished(timedOutResult, timeoutSec, this.#formatResultOutput(timedOutResult));
+							throw new ToolError("Command timed out");
 						}
 
 						if (raced.kind === "exit") {
@@ -1102,20 +1127,27 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 				});
 		const wallTimeMs = performance.now() - wallTimeStart;
 		if (result.cancelled) {
-			const out = normalizeResultOutput(result);
-			// PTY output carries no cancel/timeout notice of its own; annotate so
-			// the model can tell an abort from a plain failure.
-			const message = isInteractiveResult(result) && out ? `${out}\n\n[Command aborted]` : out || "Command aborted";
-			if (signal?.aborted) {
-				throw new ToolAbortError(message);
+			// A cancelled result is either a timeout (the command's deadline fired)
+			// or a user/system abort. Timeouts are handled by #buildCompletedResult
+			// which returns a non-throwing error result with details.timedOut=true
+			// so the renderer can show a warning border instead of error red.
+			// Both interactive and non-interactive results carry an explicit
+			// `timedOut` field from the executor/PTY layer.
+			const isTimeout = result.timedOut === true;
+			if (!isTimeout) {
+				const out = normalizeResultOutput(result);
+				// The local executor already prepends `[Command cancelled]`; PTY
+				// output does not, so preserve one cancellation notice in either case.
+				const message = out.startsWith("[Command cancelled]")
+					? out
+					: out
+						? `${out}\n\n[Command aborted]`
+						: "Command aborted";
+				if (signal?.aborted) {
+					throw new ToolAbortError(message);
+				}
+				throw new ToolError(message);
 			}
-			throw new ToolError(message);
-		}
-		if (isInteractiveResult(result) && result.timedOut) {
-			const out = normalizeResultOutput(result);
-			const message =
-				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
-			throw new ToolError(out ? `${out}\n\n[${message}]` : message);
 		}
 		return this.#buildCompletedResult(result, timeoutSec, {
 			requestedTimeoutSec,
@@ -1253,6 +1285,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 			const isError = result.isError === true;
 			const isPartial = options.isPartial === true;
 			const success = !isPartial && !isError;
+			const details = result.details;
+			const isTimeout = details?.timedOut === true;
 			const header =
 				config.showHeader === false
 					? undefined
@@ -1263,12 +1297,11 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 										title: config.resolveTitle(args, options),
 									}
 								: {
-										icon: isPartial ? "pending" : "error",
+										icon: isPartial ? "pending" : isTimeout ? "warning" : "error",
 										title: config.resolveTitle(args, options),
 									},
 							uiTheme,
 						);
-			const details = result.details;
 			const outputBlock = new CachedOutputBlock();
 
 			// Per-instance cache for the expensive inner lines computation. Mirrors
@@ -1408,7 +1441,7 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					const framed = outputBlock.render(
 						{
 							header,
-							state: isPartial ? "pending" : isError ? "error" : "success",
+							state: isPartial ? "pending" : isError ? (isTimeout ? "warning" : "error") : "success",
 							sections: [
 								{
 									// Viewport-sized tail window in every state — streaming and final

package/src/tools/essential-tools.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical set of built-in tools that must stay top-level.
+ *
+ * These are the coding essentials the model always needs directly in its
+ * callable schema. `read`/`write` are additionally the `xd://` transport
+ * (`read xd://` lists devices, `write xd://<tool>` executes them), so demoting
+ * them under xdev makes every mounted device unreachable.
+ *
+ * Adapter boundaries (extension `registerTool`, SDK custom tools, RPC host
+ * tools) default an omitted `loadMode` to `"discoverable"`. A UI-only
+ * re-register of a built-in — e.g. wrapping `read`/`write`/`bash`/`edit`/`glob`
+ * to customize rendering — would then silently demote it to `discoverable` and,
+ * with `tools.xdev` on, unmount it from the top-level schema (issue #5764).
+ * {@link defaultLoadModeForToolName} pins these names to `"essential"` when the
+ * definition omits `loadMode`, so re-registering a built-in never demotes it.
+ */
+import type { ToolLoadMode } from "@oh-my-pi/pi-agent-core";
+
+/**
+ * Built-in tool names whose classes declare `loadMode = "essential"`. Kept in
+ * sync with the tool classes by `essential-tools.test.ts` (drift guard).
+ */
+export const ESSENTIAL_BUILTIN_TOOL_NAMES: Record<string, true> = {
+	read: true,
+	write: true,
+	bash: true,
+	edit: true,
+	glob: true,
+	eval: true,
+	task: true,
+	hub: true,
+	learn: true,
+	manage_skill: true,
+};
+
+/**
+ * Resolve a tool's presentation mode at an adapter boundary. An explicit
+ * `declared` mode always wins. When omitted, known essential built-in names
+ * default to `"essential"` (so a re-register never demotes them); everything
+ * else defaults to `"discoverable"`.
+ */
+export function defaultLoadModeForToolName(name: string, declared?: ToolLoadMode): ToolLoadMode {
+	if (declared) return declared;
+	return name in ESSENTIAL_BUILTIN_TOOL_NAMES ? "essential" : "discoverable";
+}

package/src/tools/gh.ts

@@ -10,7 +10,7 @@ import type {
 	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
 
-import { getWorktreeDir, hashPath, isEnoent, prompt, untilAborted } from "@oh-my-pi/pi-utils";
+import { getWorktreeDir, hashPath, isEnoent, logger, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import type { Settings } from "../config/settings";
 import githubDescription from "../prompts/tools/github.md" with { type: "text" };
@@ -239,6 +239,8 @@ const RUN_WATCH_TAIL_DEFAULT = 15;
 const RUN_WATCH_TAIL_MAX = 200;
 const REVIEW_COMMENTS_PAGE_SIZE = 100;
 const RUN_JOBS_PAGE_SIZE = 100;
+const PR_DIFF_FILES_PAGE_SIZE = 100;
+const PR_DIFF_FILES_MAX = 3000;
 const PR_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)(?:\/.*)?$/;
 const ISSUE_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)(?:\/.*)?$/;
 const RUN_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/(\d+)(?:\/.*)?$/;
@@ -2931,6 +2933,160 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 	return file;
 }
 
+/**
+ * A single entry from `GET /repos/{owner}/{repo}/pulls/{n}/files`. `patch` is
+ * absent for binary files and for individual file diffs GitHub deems too large
+ * to render.
+ */
+interface GhPrFileApi {
+	filename?: string;
+	previous_filename?: string;
+	status?: string;
+	additions?: number;
+	deletions?: number;
+	patch?: string;
+}
+
+interface GhPrApi {
+	changed_files?: number;
+}
+
+/**
+ * GitHub rejects the aggregate PR diff endpoint with HTTP 406 once the diff
+ * exceeds 20,000 lines. Detect that specific failure so the caller can fall
+ * back to the per-file endpoint instead of aborting the whole review.
+ */
+function isPrDiffTooLargeError(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : String(err);
+	return (
+		/\bHTTP 406\b/.test(message) ||
+		/exceeded the maximum number of lines/i.test(message) ||
+		/\btoo_large\b/.test(message)
+	);
+}
+
+function formatSyntheticDiffPath(prefix: "a/" | "b/", path: string): string {
+	const prefixedPath = `${prefix}${path}`;
+	if (!/[\u0000-\u001F\s"\\]/.test(prefixedPath)) return prefixedPath;
+
+	let escaped = "";
+	for (const char of prefixedPath) {
+		switch (char) {
+			case "\\":
+				escaped += "\\\\";
+				break;
+			case '"':
+				escaped += '\\"';
+				break;
+			case "\n":
+				escaped += "\\n";
+				break;
+			case "\r":
+				escaped += "\\r";
+				break;
+			case "\t":
+				escaped += "\\t";
+				break;
+			default: {
+				const code = char.charCodeAt(0);
+				escaped += code < 32 ? `\\${code.toString(8).padStart(3, "0")}` : char;
+			}
+		}
+	}
+	return `"${escaped}"`;
+}
+
+/**
+ * Reconstruct a `diff --git` section from a single files-API entry. The API's
+ * `patch` field carries only the hunk body, so the `diff --git`/`---`/`+++`
+ * headers are synthesized to match `gh pr diff` output — this keeps
+ * {@link parsePrUnifiedDiff} and the review parser producing identical section
+ * boundaries and byte offsets. Files whose `patch` is omitted (binary or
+ * too-large) stay visible with an explicit marker rather than being dropped.
+ */
+function buildSyntheticDiffSection(file: GhPrFileApi): string | undefined {
+	const newPath = file.filename;
+	if (!newPath) return undefined;
+	const status = file.status ?? "modified";
+	const oldPath = file.previous_filename ?? newPath;
+	const oldDiffPath = formatSyntheticDiffPath("a/", oldPath);
+	const newDiffPath = formatSyntheticDiffPath("b/", newPath);
+	const lines: string[] = [`diff --git ${oldDiffPath} ${newDiffPath}`];
+	if (status === "added") {
+		lines.push("new file mode 100644");
+	} else if (status === "removed") {
+		lines.push("deleted file mode 100644");
+	} else if (status === "renamed" || file.previous_filename) {
+		lines.push(`rename from ${oldPath}`, `rename to ${newPath}`);
+	}
+	if (typeof file.patch === "string" && file.patch.length > 0) {
+		lines.push(status === "added" ? "--- /dev/null" : `--- ${oldDiffPath}`);
+		lines.push(status === "removed" ? "+++ /dev/null" : `+++ ${newDiffPath}`);
+		lines.push(file.patch);
+	} else {
+		lines.push(
+			`* patch unavailable (binary or too large); additions ${file.additions ?? 0}, deletions ${file.deletions ?? 0}`,
+		);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Fallback PR diff retrieval via the paginated per-file endpoint, used when the
+ * aggregate `gh pr diff` is rejected for exceeding GitHub's 20,000-line limit.
+ * The per-file patches are not subject to that aggregate cap, so even very
+ * large PRs can be reassembled into a synthetic unified diff.
+ */
+async function fetchPrDiffViaFilesApi(
+	cwd: string,
+	repo: string,
+	number: number,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	const pull = await git.github.json<GhPrApi>(
+		cwd,
+		["api", "--method", "GET", `/repos/${repo}/pulls/${number}`],
+		signal,
+		{ repoProvided: true },
+	);
+	if ((pull.changed_files ?? 0) > PR_DIFF_FILES_MAX) {
+		throw new ToolError(
+			`Pull request changes ${pull.changed_files} files, exceeding GitHub's ${PR_DIFF_FILES_MAX}-file limit for the per-file diff API.`,
+		);
+	}
+
+	const sections: string[] = [];
+	let page = 1;
+	while (true) {
+		const response = await git.github.json<GhPrFileApi[]>(
+			cwd,
+			[
+				"api",
+				"--method",
+				"GET",
+				`/repos/${repo}/pulls/${number}/files`,
+				"-F",
+				`per_page=${PR_DIFF_FILES_PAGE_SIZE}`,
+				"-F",
+				`page=${page}`,
+			],
+			signal,
+			{ repoProvided: true },
+		);
+		for (const file of response) {
+			const section = buildSyntheticDiffSection(file);
+			if (section) sections.push(section);
+		}
+		if (response.length < PR_DIFF_FILES_PAGE_SIZE) {
+			break;
+		}
+		page += 1;
+	}
+	// Trailing newline mirrors `gh pr diff` so downstream parsers splitting on
+	// `^diff --git ` see identical boundaries.
+	return sections.length > 0 ? `${sections.join("\n")}\n` : "";
+}
+
 async function fetchPrDiffFresh(
 	cwd: string,
 	repo: string,
@@ -2939,7 +3095,18 @@ async function fetchPrDiffFresh(
 ): Promise<{ rendered: string; sourceUrl: string | undefined; payload: PrDiffPayload }> {
 	const args = ["pr", "diff", String(number), "--color", "never"];
 	appendRepoFlag(args, repo, String(number));
-	const text = await git.github.text(cwd, args, signal, { repoProvided: true, trimOutput: false });
+	let text: string;
+	try {
+		text = await git.github.text(cwd, args, signal, { repoProvided: true, trimOutput: false });
+	} catch (err) {
+		if (!isPrDiffTooLargeError(err)) throw err;
+		logger.debug("gh pr diff exceeded GitHub's aggregate line limit; falling back to per-file API", {
+			repo,
+			number,
+			err: String(err),
+		});
+		text = await fetchPrDiffViaFilesApi(cwd, repo, number, signal);
+	}
 	const payload = parsePrUnifiedDiff(text);
 	// `rendered` already carries the verbatim diff; blank the payload copy so
 	// the cache row stores a potentially huge diff once instead of twice.

package/src/tools/image-gen.ts

@@ -45,7 +45,7 @@ const IMAGE_SYSTEM_INSTRUCTION =
 	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
 
 export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
-export type ImageProviderPreference = Exclude<ImageProvider, "openai-codex"> | "auto";
+export type ImageProviderPreference = ImageProvider | "auto";
 
 interface ImageApiKey {
 	provider: ImageProvider;
@@ -57,8 +57,17 @@ interface ImageApiKey {
 const COMMON_IMAGE_ASPECT_RATIOS = ["1:1", "3:4", "4:3", "9:16", "16:9"] as const;
 const XAI_IMAGE_ASPECT_RATIOS = [...COMMON_IMAGE_ASPECT_RATIOS, "3:2", "2:3"] as const;
 const COMMON_IMAGE_ASPECT_RATIO_SET = new Set<string>(COMMON_IMAGE_ASPECT_RATIOS);
-const IMAGE_PROVIDER_PREFERENCES = new Set<string>(["auto", "antigravity", "gemini", "openai", "openrouter", "xai"]);
-const AUTO_IMAGE_PROVIDER_ORDER = ["openai", "antigravity", "xai", "openrouter", "gemini"] as const;
+const IMAGE_PROVIDER_CHOICES = [
+	"auto",
+	"antigravity",
+	"gemini",
+	"openai",
+	"openai-codex",
+	"openrouter",
+	"xai",
+] as const;
+const IMAGE_PROVIDER_PREFERENCES = new Set<string>(IMAGE_PROVIDER_CHOICES);
+const AUTO_IMAGE_PROVIDER_ORDER = ["openai", "openai-codex", "antigravity", "xai", "openrouter", "gemini"] as const;
 
 const responseModalitySchema = type('"IMAGE" | "TEXT"');
 
@@ -71,6 +80,10 @@ const inputImageSchema = type({
 	"mime_type?": type("string").describe("mime type"),
 });
 
+const imageProviderSchema = type
+	.enumerated(...IMAGE_PROVIDER_CHOICES)
+	.describe("image provider for this request; overrides the providers.image setting (default: use the setting)");
+
 export const imageGenSchema = type({
 	subject: type("string").describe("main subject"),
 	"action?": type("string").describe("what subject is doing"),
@@ -83,6 +96,7 @@ export const imageGenSchema = type({
 	"aspect_ratio?": aspectRatioSchema,
 	"image_size?": imageSizeSchema,
 	"input?": inputImageSchema.array().describe("input images"),
+	"provider?": imageProviderSchema,
 });
 export type ImageGenParams = typeof imageGenSchema.infer;
 export type GeminiResponseModality = typeof responseModalitySchema.infer;
@@ -548,6 +562,49 @@ async function findOpenAIHostedImageCredentials(
 	};
 }
 
+// Codex (ChatGPT subscription) chat models that carry OpenAI's hosted
+// `image_generation` tool. Priority: newest general model first, then Codex
+// variants; any available openai-codex hosted-image model is the last resort.
+const CODEX_IMAGE_MODEL_PRIORITY = ["gpt-5.5", "gpt-5.4", "gpt-5.1", "gpt-5", "gpt-5-codex"] as const;
+
+function resolveDefaultCodexImageModel(modelRegistry: ModelRegistry): Model | undefined {
+	for (const id of CODEX_IMAGE_MODEL_PRIORITY) {
+		const model = modelRegistry.find("openai-codex", id);
+		if (model && isOpenAIHostedImageModel(model)) return model;
+	}
+	return modelRegistry.getAll().find(model => model.provider === "openai-codex" && isOpenAIHostedImageModel(model));
+}
+
+/**
+ * Codex subscription (ChatGPT OAuth) image credentials — engages OpenAI's hosted
+ * `image_generation` tool through a CONNECTED Codex account, independent of the
+ * active chat model. This is what lets image generation run on a ChatGPT
+ * subscription (no metered OPENAI_API_KEY) even when the active model is, e.g.,
+ * Claude. The active-model-is-codex case is already served by
+ * {@link findOpenAIHostedImageCredentials}, so it is skipped here to avoid a
+ * duplicate resolution.
+ */
+async function findCodexSubscriptionImageCredentials(
+	modelRegistry: ModelRegistry | undefined,
+	activeModel: Model | undefined,
+	sessionId?: string,
+): Promise<ImageApiKey | null> {
+	if (!modelRegistry) return null;
+	if (isOpenAIHostedImageModel(activeModel) && getOpenAIHostedImageProvider(activeModel) === "openai-codex") {
+		return null;
+	}
+	// A Codex subscription credential is an OAuth JWT with an account claim. API
+	// keys stored under this provider cannot use the ChatGPT backend and must not
+	// prevent fallback providers from being selected.
+	const token = await modelRegistry.getApiKeyForProvider("openai-codex", sessionId);
+	if (!token || !getCodexAccountId(token)) return null;
+	const model = resolveDefaultCodexImageModel(modelRegistry);
+	if (!model) return null;
+	const apiKey = await modelRegistry.getApiKey(model, sessionId);
+	if (!isAuthenticated(apiKey) || !getCodexAccountId(apiKey)) return null;
+	return { provider: "openai-codex", apiKey, model };
+}
+
 function activeImageProvider(model: Model | undefined): Exclude<ImageProviderPreference, "auto"> | null {
 	switch (model?.provider) {
 		case "openai":
@@ -567,7 +624,10 @@ function activeImageProvider(model: Model | undefined): Exclude<ImageProviderPre
 	}
 }
 
-function imageProviderOrder(activeModel: Model | undefined): Array<Exclude<ImageProviderPreference, "auto">> {
+function imageProviderOrder(
+	activeModel: Model | undefined,
+	preference: ImageProviderPreference = preferredImageProvider,
+): Array<Exclude<ImageProviderPreference, "auto">> {
 	const providers: Array<Exclude<ImageProviderPreference, "auto">> = [];
 	const added = new Set<Exclude<ImageProviderPreference, "auto">>();
 	const add = (provider: Exclude<ImageProviderPreference, "auto"> | null): void => {
@@ -576,7 +636,7 @@ function imageProviderOrder(activeModel: Model | undefined): Array<Exclude<Image
 		providers.push(provider);
 	};
 
-	if (preferredImageProvider !== "auto") add(preferredImageProvider);
+	if (preference !== "auto") add(preference);
 	add(activeImageProvider(activeModel));
 	for (const provider of AUTO_IMAGE_PROVIDER_ORDER) add(provider);
 	return providers;
@@ -591,6 +651,8 @@ async function findImageApiKey(
 	switch (provider) {
 		case "openai":
 			return findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
+		case "openai-codex":
+			return findCodexSubscriptionImageCredentials(modelRegistry, activeModel, sessionId);
 		case "antigravity":
 			return modelRegistry ? findAntigravityCredentials(modelRegistry, sessionId) : null;
 		case "xai":
@@ -1047,7 +1109,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 	async execute(_toolCallId, params, _onUpdate, ctx, signal) {
 		return untilAborted(signal, async () => {
 			const sessionId = ctx.sessionManager.getSessionId();
-			const providerOrder = imageProviderOrder(ctx.model);
+			const providerOrder = imageProviderOrder(ctx.model, params.provider ?? preferredImageProvider);
 			const cwd = ctx.sessionManager.getCwd();
 			const requestSignal = ptree.combineSignals(signal, IMAGE_TIMEOUT);
 			const fetchImpl = ctx.fetch ?? fetch;
@@ -1604,7 +1666,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 
 			if (!foundCredentials) {
 				throw new Error(
-					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity or xAI Grok OAuth, or set XAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
+					"No image API credentials found. Connect a Codex (ChatGPT) subscription, use a GPT Responses/Codex model with OpenAI credentials, log in with google-antigravity or xAI Grok OAuth, or set OPENAI_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
 				);
 			}
 

package/src/tools/index.ts

@@ -74,6 +74,7 @@ export * from "./bash";
 export * from "./browser";
 export * from "./checkpoint";
 export * from "./debug";
+export * from "./essential-tools";
 export * from "./eval";
 export * from "./eval-backends";
 export * from "./gh";
@@ -568,15 +569,16 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	);
 	let tools = baseResults.filter((r): r is Tool => r !== null);
 
-	// xd:// mounting: unmount discoverable built-ins from the tools array and
-	// expose them as virtual device URLs driven through read/write. Active for
-	// default tool sets when `tools.xdev` is enabled.
-	const xdevEnabled = requestedTools === undefined && session.settings.get("tools.xdev");
+	// Always create the xd:// registry when enabled so SDK assembly can mount
+	// discoverable custom/MCP tools later. Explicitly requested built-ins keep
+	// their top-level presentation; default tool sets mount discoverable built-ins.
+	const xdevEnabled = session.settings.get("tools.xdev");
+	const mountBuiltinTools = requestedTools === undefined;
 	if (xdevEnabled) {
 		const mounted: Tool[] = [];
 		const kept: Tool[] = [];
 		for (const tool of tools) {
-			const mountable = isMountableUnderXdev(tool) && tool.name in BUILTIN_TOOLS;
+			const mountable = mountBuiltinTools && isMountableUnderXdev(tool) && tool.name in BUILTIN_TOOLS;
 			(mountable ? mounted : kept).push(tool);
 		}
 		session.xdevRegistry = new XdevRegistry(mounted);