@oh-my-pi/pi-coding-agent 15.5.6 → 15.5.7

package/src/modes/controllers/selector-controller.ts

@@ -29,7 +29,12 @@ import {
 import type { InteractiveModeContext } from "../../modes/types";
 import { type SessionInfo, SessionManager } from "../../session/session-manager";
 import { FileSessionStorage } from "../../session/session-storage";
-import { isSearchProviderPreference, setPreferredImageProvider, setPreferredSearchProvider } from "../../tools";
+import {
+	isImageProviderPreference,
+	isSearchProviderPreference,
+	setPreferredImageProvider,
+	setPreferredSearchProvider,
+} from "../../tools";
 import { setSessionTerminalTitle } from "../../utils/title-generator";
 import { AgentDashboard } from "../components/agent-dashboard";
 import { AssistantMessageComponent } from "../components/assistant-message";
@@ -374,7 +379,7 @@ export class SelectorController {
 				}
 				break;
 			case "providers.image":
-				if (value === "auto" || value === "openai" || value === "gemini" || value === "openrouter") {
+				if (isImageProviderPreference(value)) {
 					setPreferredImageProvider(value);
 				}
 				break;

package/src/modes/interactive-mode.ts

@@ -1012,7 +1012,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	async #getPlanFilePath(): Promise<string> {
-		return "local://PLAN.md";
+		return this.session.getPlanReferencePath() || "local://PLAN.md";
 	}
 
 	#resolvePlanFilePath(planFilePath: string): string {

package/src/sdk.ts

@@ -129,6 +129,7 @@ import {
 	FindTool,
 	getSearchTools,
 	HIDDEN_TOOLS,
+	isImageProviderPreference,
 	isSearchProviderPreference,
 	type LspStartupServerInfo,
 	loadSshTool,
@@ -148,6 +149,7 @@ import { ToolContextStore } from "./tools/context";
 import { getImageGenTools } from "./tools/image-gen";
 import { wrapToolWithMetaNotice } from "./tools/output-meta";
 import { queueResolveHandler } from "./tools/resolve";
+import { ttsTool } from "./tools/tts";
 import { EventBus } from "./utils/event-bus";
 import { buildNamedToolChoice } from "./utils/tool-choice";
 import { buildWorkspaceTree, type WorkspaceTree } from "./workspace-tree";
@@ -893,12 +895,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	}
 
 	const imageProvider = settings.get("providers.image");
-	if (
-		imageProvider === "auto" ||
-		imageProvider === "openai" ||
-		imageProvider === "gemini" ||
-		imageProvider === "openrouter"
-	) {
+	if (isImageProviderPreference(imageProvider)) {
 		setPreferredImageProvider(imageProvider);
 	}
 
@@ -1319,6 +1316,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			customTools.push(...(imageGenTools as unknown as CustomTool[]));
 		}
 
+		if (settings.get("tts.enabled")) {
+			customTools.push(ttsTool as unknown as CustomTool);
+		}
+
 		// Add web search tools
 		if (options.toolNames?.includes("web_search")) {
 			customTools.push(...getSearchTools());
@@ -1876,9 +1877,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				}
 				return key;
 			},
-			streamFn: (streamModel, context, streamOptions) =>
-				streamSimple(streamModel, context, {
+			streamFn: (streamModel, context, streamOptions) => {
+				const openrouterRoutingPreset = settings.get("providers.openrouterVariant");
+				const openrouterVariant =
+					openrouterRoutingPreset && openrouterRoutingPreset !== "default" ? openrouterRoutingPreset : undefined;
+				return streamSimple(streamModel, context, {
 					...streamOptions,
+					openrouterVariant: streamOptions?.openrouterVariant ?? openrouterVariant,
 					onAuthError: async (provider, oldKey, error) => {
 						await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, {
 							signal: streamOptions?.signal,
@@ -1890,7 +1895,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						});
 						return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
 					},
-				}),
+				});
+			},
 			cursorExecHandlers,
 			transformToolCallArguments: (args, _toolName) => {
 				let result = args;

package/src/session/agent-session.ts

@@ -3631,9 +3631,17 @@ export class AgentSession {
 		const sessionOnResponse = this.#onResponse;
 		const sessionMetadata = this.agent.metadataForProvider(provider);
 		const sessionOnSseEvent = this.#onSseEvent;
-		if (!sessionOnPayload && !sessionOnResponse && !sessionMetadata && !sessionOnSseEvent) return options;
-
-		const preparedOptions: SimpleStreamOptions = { ...options };
+		const openrouterRoutingPreset =
+			provider === "openrouter" ? this.settings.get("providers.openrouterVariant") : "default";
+		const openrouterVariant =
+			openrouterRoutingPreset !== "default" && options.openrouterVariant === undefined
+				? openrouterRoutingPreset
+				: undefined;
+		if (!sessionOnPayload && !sessionOnResponse && !sessionMetadata && !sessionOnSseEvent && !openrouterVariant)
+			return options;
+
+		const preparedOptions: SimpleStreamOptions =
+			openrouterVariant === undefined ? { ...options } : { ...options, openrouterVariant };
 
 		// Stamp session metadata (e.g. user_id={session_id}) onto direct-call requests so
 		// they share the same session bucket as Agent.prompt-routed requests on Anthropic
@@ -3758,6 +3766,10 @@ export class AgentSession {
 		this.#planReferencePath = path;
 	}
 
+	getPlanReferencePath(): string {
+		return this.#planReferencePath;
+	}
+
 	get clientBridge(): ClientBridge | undefined {
 		return this.#clientBridge;
 	}
@@ -5575,6 +5587,11 @@ export class AgentSession {
 					initiatorOverride: "agent",
 					metadata: this.agent.metadataForProvider(model.provider),
 					telemetry: resolveTelemetry(this.agent.telemetry, this.sessionId),
+					// Honor the user's /model thinking selection on the handoff
+					// path. Clamped per-model inside generateHandoff via
+					// resolveCompactionEffort so unsupported-effort models don't
+					// trip requireSupportedEffort.
+					thinkingLevel: this.thinkingLevel,
 				},
 				handoffSignal,
 			);
@@ -6345,6 +6362,11 @@ export class AgentSession {
 					metadata: this.agent.metadataForProvider(candidate.provider),
 					convertToLlm,
 					telemetry,
+					// Honor the user's /model thinking selection (incl. `off`) on
+					// the manual `/compact` path. Clamped per-model inside compact()
+					// via resolveCompactionEffort so unsupported-effort models
+					// (xai-oauth/grok-build) don't trip requireSupportedEffort.
+					thinkingLevel: this.thinkingLevel,
 				});
 			} catch (error) {
 				if (!this.#isCompactionAuthFailure(error)) {
@@ -6617,6 +6639,11 @@ export class AgentSession {
 								initiatorOverride: "agent",
 								convertToLlm,
 								telemetry,
+								// Honor the user's /model thinking selection on the
+								// auto-compaction path — the most-fired compaction
+								// site. Clamped per-model inside compact() via
+								// resolveCompactionEffort.
+								thinkingLevel: this.thinkingLevel,
 							});
 							break;
 						} catch (error) {

package/src/tools/fetch.ts

@@ -562,9 +562,22 @@ function parseFeedToMarkdown(content: string, maxItems = 10): string {
 }
 
 /**
- * Render HTML to markdown using Parallel, jina, trafilatura, lynx (in order of preference)
+ * Cap on any single remote reader-mode request (Parallel, Jina) so a stalled
+ * remote endpoint cannot consume the whole reader-mode budget and starve the
+ * local fallback renderers (trafilatura, lynx, native). See #1449.
  */
-async function renderHtmlToText(
+const REMOTE_READER_MAX_MS = 10_000;
+
+/**
+ * Render HTML to markdown using Parallel, jina, trafilatura, lynx, then the
+ * in-process native converter. The overall `timeout` budget bounds the call,
+ * but remote reader requests are additionally capped at `REMOTE_READER_MAX_MS`
+ * so that a hung remote endpoint cannot prevent local fallbacks from running.
+ * Only a real `userSignal` cancellation aborts the chain — remote per-attempt
+ * timeouts and the overall reader-mode timeout still allow later renderers
+ * (especially the purely-local native converter) to be tried.
+ */
+export async function renderHtmlToText(
 	url: string,
 	html: string,
 	timeout: number,
@@ -572,14 +585,15 @@ async function renderHtmlToText(
 	userSignal: AbortSignal | undefined,
 	storage: AgentStorage | null,
 ): Promise<{ content: string; ok: boolean; method: string }> {
-	const signal = ptree.combineSignals(userSignal, timeout * 1000);
+	const overallSignal = ptree.combineSignals(userSignal, timeout * 1000);
 	const execOptions = {
 		mode: "group" as const,
 		allowNonZero: true,
 		allowAbort: true,
 		stderr: "full" as const,
-		signal,
+		signal: overallSignal,
 	};
+	const remoteBudgetMs = Math.min(timeout * 1000, REMOTE_READER_MAX_MS);
 
 	// Try Parallel extract first when credentials are configured
 	if (settings.get("providers.parallelFetch") && findParallelApiKey(storage)) {
@@ -590,7 +604,7 @@ async function renderHtmlToText(
 					objective: "Extract the main content",
 					excerpts: true,
 					fullContent: false,
-					signal,
+					signal: ptree.combineSignals(userSignal, remoteBudgetMs),
 				},
 				storage,
 			);
@@ -602,17 +616,18 @@ async function renderHtmlToText(
 				}
 			}
 		} catch {
-			// Parallel extract failed, continue to next method
-			signal?.throwIfAborted();
+			// Parallel extract failed or stalled; honour real cancellation only.
+			userSignal?.throwIfAborted();
 		}
 	}
 
-	// Try jina first (reader API)
+	// Try jina reader API with its own sub-budget so a stall cannot starve
+	// later fallbacks (#1449).
 	try {
 		const jinaUrl = `https://r.jina.ai/${url}`;
 		const response = await fetch(jinaUrl, {
 			headers: { Accept: "text/markdown" },
-			signal,
+			signal: ptree.combineSignals(userSignal, remoteBudgetMs),
 		});
 		if (response.ok) {
 			const content = await response.text();
@@ -621,37 +636,50 @@ async function renderHtmlToText(
 			}
 		}
 	} catch {
-		// Jina failed, continue to next method
-		signal?.throwIfAborted();
+		// Jina failed or stalled; honour real cancellation only.
+		userSignal?.throwIfAborted();
 	}
 
 	// Try trafilatura (auto-install via uv/pip)
-	const trafilatura = await ensureTool("trafilatura", { signal, silent: true });
-	if (trafilatura) {
-		const result = await ptree.exec([trafilatura, "-u", url, "--output-format", "markdown"], execOptions);
-		if (result.ok && result.stdout.trim().length > 100) {
-			return { content: result.stdout, ok: true, method: "trafilatura" };
+	try {
+		const trafilatura = await ensureTool("trafilatura", { signal: overallSignal, silent: true });
+		if (trafilatura) {
+			const result = await ptree.exec([trafilatura, "-u", url, "--output-format", "markdown"], execOptions);
+			if (result.ok && result.stdout.trim().length > 100) {
+				return { content: result.stdout, ok: true, method: "trafilatura" };
+			}
 		}
+	} catch {
+		// trafilatura unavailable or stalled; continue to next method.
+		userSignal?.throwIfAborted();
 	}
 
 	// Try lynx (can't auto-install, system package)
-	const lynx = hasCommand("lynx");
-	if (lynx) {
-		const result = await ptree.exec(["lynx", "-dump", "-nolist", "-width", "250", url], execOptions);
-		if (result.ok) {
-			return { content: result.stdout, ok: true, method: "lynx" };
+	try {
+		const lynx = hasCommand("lynx");
+		if (lynx) {
+			const result = await ptree.exec(["lynx", "-dump", "-nolist", "-width", "250", url], execOptions);
+			if (result.ok) {
+				return { content: result.stdout, ok: true, method: "lynx" };
+			}
 		}
+	} catch {
+		// lynx failed or stalled; continue to native converter.
+		userSignal?.throwIfAborted();
 	}
 
-	// Fall back to native converter (fastest, no network/subprocess)
+	// Fall back to native converter (purely local, no network/subprocess).
+	// Always attempted: even if remote renderers and subprocesses were aborted
+	// by the overall reader-mode timeout, this still works on already-loaded
+	// HTML (#1449).
 	try {
 		const content = await htmlToMarkdown(html, { cleanContent: true });
 		if (content.trim().length > 100 && !isLowQualityOutput(content)) {
 			return { content, ok: true, method: "native" };
 		}
 	} catch {
-		// Native converter failed, continue to next method
-		signal?.throwIfAborted();
+		// Native converter failed; nothing else to try.
+		userSignal?.throwIfAborted();
 	}
 	return { content: "", ok: false, method: "none" };
 }

package/src/tools/image-gen.ts

@@ -22,12 +22,14 @@ import * as z from "zod/v4";
 import packageJson from "../../package.json" with { type: "json" };
 import { isAuthenticated, type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
+import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
 import imageGenDescription from "../prompts/tools/image-gen.md" with { type: "text" };
 import { resolveReadPath } from "./path-utils";
 
 const DEFAULT_MODEL = "gemini-3-pro-image-preview";
 const DEFAULT_OPENROUTER_MODEL = "google/gemini-3-pro-image-preview";
 const DEFAULT_ANTIGRAVITY_MODEL = "gemini-3-pro-image";
+const DEFAULT_XAI_IMAGE_MODEL = "grok-imagine-image";
 const IMAGE_TIMEOUT = 3 * 60 * 1000; // 3 minutes
 const MAX_IMAGE_SIZE = 35 * 1024 * 1024;
 const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
@@ -38,7 +40,9 @@ const ANTIGRAVITY_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com"
 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.";
 
-type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
+export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+export type ImageProviderPreference = Exclude<ImageProvider, "openai-codex"> | "auto";
+
 interface ImageApiKey {
 	provider: ImageProvider;
 	apiKey: string;
@@ -46,8 +50,13 @@ interface ImageApiKey {
 	model?: Model;
 }
 
+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 responseModalitySchema = z.enum(["IMAGE", "TEXT"] as const);
-const aspectRatioSchema = z.enum(["1:1", "3:4", "4:3", "9:16", "16:9"] as const).describe("aspect ratio");
+const aspectRatioSchema = z.enum(XAI_IMAGE_ASPECT_RATIOS).describe("aspect ratio");
 const imageSizeSchema = z.enum(["1024x1024", "1536x1024", "1024x1536"] as const).describe("image size");
 
 const inputImageSchema = z
@@ -274,6 +283,36 @@ interface AntigravityRequest {
 	requestId?: string;
 }
 
+interface XAIImageReference {
+	// OpenAI-compat discriminator. Every code example at
+	// docs.x.ai/developers/rest-api-reference/inference/images sends this
+	// alongside `url`; the schema text doesn't strictly require it, but
+	// matching the documented wire format avoids relying on schema-vs-example.
+	readonly type: "image_url";
+	readonly url: string;
+}
+
+interface XAIImageRequestBase {
+	readonly model: string;
+	readonly prompt: string;
+	readonly aspect_ratio: string;
+	readonly resolution: "1k" | "2k";
+	readonly n: number;
+	readonly response_format: "b64_json" | "url";
+}
+
+// xAI image request body. Three shapes:
+//   1. text-only generation                  → POST /v1/images/generations
+//   2. single-source edit (image field)      → POST /v1/images/edits
+//   3. multi-reference edit (images field)   → POST /v1/images/edits
+// `image` and `images` are mutually exclusive per docs.x.ai; the discriminated
+// union enforces that statically. The runtime cap (XAI_MAX_EDIT_IMAGES) bounds
+// the array length, which TypeScript cannot encode without lossy tuple unions.
+type XAIImageRequestBody =
+	| (XAIImageRequestBase & { readonly image?: never; readonly images?: never })
+	| (XAIImageRequestBase & { readonly image: XAIImageReference; readonly images?: never })
+	| (XAIImageRequestBase & { readonly images: readonly XAIImageReference[]; readonly image?: never });
+
 interface AntigravityResponseChunk {
 	response?: {
 		candidates?: Array<{
@@ -391,12 +430,24 @@ function extractOpenRouterImageUrls(message: OpenRouterMessage | undefined): str
 }
 
 /** Preferred provider set via settings (default: auto) */
-let preferredImageProvider: ImageProvider | "auto" = "auto";
+let preferredImageProvider: ImageProviderPreference = "auto";
+
+export function isImageProviderPreference(value: unknown): value is ImageProviderPreference {
+	return typeof value === "string" && IMAGE_PROVIDER_PREFERENCES.has(value);
+}
 
 /** Set the preferred image provider from settings */
-export function setPreferredImageProvider(provider: ImageProvider | "auto"): void {
+export function setPreferredImageProvider(provider: ImageProviderPreference): void {
 	preferredImageProvider = provider;
 }
+function assertImageAspectRatioSupported(provider: ImageProvider, aspectRatio: ImageGenParams["aspect_ratio"]): void {
+	if (!aspectRatio || provider === "xai" || COMMON_IMAGE_ASPECT_RATIO_SET.has(aspectRatio)) {
+		return;
+	}
+	throw new Error(
+		`Aspect ratio ${aspectRatio} is only supported by xAI image generation. Set providers.image to xai or use one of ${COMMON_IMAGE_ASPECT_RATIOS.join(", ")}.`,
+	);
+}
 
 interface ParsedAntigravityCredentials {
 	accessToken: string;
@@ -429,6 +480,17 @@ async function findAntigravityCredentials(modelRegistry: ModelRegistry): Promise
 	};
 }
 
+async function findXAIImageCredentials(modelRegistry?: ModelRegistry): Promise<ImageApiKey | null> {
+	if (modelRegistry) {
+		const creds = await resolveXAIHttpCredentials(modelRegistry);
+		if (creds) return { provider: "xai", apiKey: creds.apiKey };
+		return null;
+	}
+	const apiKey = $env.XAI_API_KEY;
+	if (apiKey) return { provider: "xai", apiKey };
+	return null;
+}
+
 async function findOpenAIHostedImageCredentials(
 	modelRegistry: ModelRegistry | undefined,
 	activeModel: Model | undefined,
@@ -468,9 +530,13 @@ async function findImageApiKey(
 		const openRouterKey = getEnvApiKey("openrouter");
 		if (openRouterKey) return { provider: "openrouter", apiKey: openRouterKey };
 		// Fall through to auto-detect if preferred provider key not found.
+	} else if (preferredImageProvider === "xai") {
+		const xai = await findXAIImageCredentials(modelRegistry);
+		if (xai) return xai;
+		// Fall through to auto-detect if preferred provider key not found.
 	}
 
-	// Auto-detect: GPT hosted image generation, then Antigravity, OpenRouter, Gemini.
+	// Auto-detect: GPT hosted image generation, then Antigravity, xAI, OpenRouter, Gemini.
 	const openAI = await findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
 	if (openAI) return openAI;
 
@@ -479,6 +545,9 @@ async function findImageApiKey(
 		if (antigravity) return antigravity;
 	}
 
+	const xai = await findXAIImageCredentials(modelRegistry);
+	if (xai) return xai;
+
 	const openRouterKey = getEnvApiKey("openrouter");
 	if (openRouterKey) return { provider: "openrouter", apiKey: openRouterKey };
 
@@ -857,6 +926,31 @@ function buildAntigravityRequest(
 	};
 }
 
+// xAI image-edit cap per docs.x.ai (POST /v1/images/edits supports up to 3
+// source images for multi-reference editing).
+const XAI_MAX_EDIT_IMAGES = 3;
+
+// Map the OpenAI-style pixel-size enum (image_size) to xAI's discrete tier.
+// "1024x1024" → "1k"; anything wider (1536x... or ...x1536) → "2k". Absent
+// image_size defaults to "1k", matching hermes-agent's DEFAULT_RESOLUTION
+// (plugins/image_gen/xai/__init__.py:71).
+function resolveXAIResolution(imageSize: string | undefined): "1k" | "2k" {
+	if (!imageSize || imageSize === "1024x1024") return "1k";
+	return "2k";
+}
+
+// Build the discriminated edit body. Caller must ensure images.length is in
+// [1, XAI_MAX_EDIT_IMAGES]; the bound check fires earlier in execute().
+function buildXAIEditPayload(base: XAIImageRequestBase, images: readonly InlineImageData[]): XAIImageRequestBody {
+	const refs: readonly XAIImageReference[] = images.map(img => ({
+		type: "image_url",
+		url: toDataUrl(img),
+	}));
+	const [first, ...rest] = refs;
+	if (first === undefined) return base; // unreachable: caller checked images.length > 0
+	return rest.length === 0 ? { ...base, image: first } : { ...base, images: refs };
+}
+
 interface AntigravitySseResult {
 	images: InlineImageData[];
 	text: string[];
@@ -910,7 +1004,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 			const apiKey = await findImageApiKey(ctx.modelRegistry, ctx.model, sessionId);
 			if (!apiKey) {
 				throw new Error(
-					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity, or set OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
+					"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.",
 				);
 			}
 
@@ -922,8 +1016,11 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 						? DEFAULT_ANTIGRAVITY_MODEL
 						: provider === "openrouter"
 							? DEFAULT_OPENROUTER_MODEL
-							: DEFAULT_MODEL;
+							: provider === "xai"
+								? DEFAULT_XAI_IMAGE_MODEL
+								: DEFAULT_MODEL;
 			const resolvedModel = provider === "openrouter" ? resolveOpenRouterModel(model) : model;
+			assertImageAspectRatioSupported(provider, params.aspect_ratio);
 			const cwd = ctx.sessionManager.getCwd();
 
 			const resolvedImages: InlineImageData[] = [];
@@ -1059,6 +1156,107 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 				};
 			}
 
+			if (provider === "xai") {
+				if (!ctx.modelRegistry) {
+					throw new Error("Missing modelRegistry for xAI image generation");
+				}
+				const xaiCreds = await resolveXAIHttpCredentials(ctx.modelRegistry, resolvedModel);
+				if (!xaiCreds) {
+					throw new Error(
+						"No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
+					);
+				}
+
+				const prompt = assemblePrompt(params);
+				const aspectRatio = params.aspect_ratio ?? "1:1";
+				const xaiResolution = resolveXAIResolution(params.image_size);
+
+				const isEdit = resolvedImages.length > 0;
+				if (isEdit && resolvedImages.length > XAI_MAX_EDIT_IMAGES) {
+					throw new Error(
+						`xAI image edits accept up to ${XAI_MAX_EDIT_IMAGES} reference images; got ${resolvedImages.length}.`,
+					);
+				}
+
+				const xaiBaseBody: XAIImageRequestBase = {
+					model: resolvedModel,
+					prompt,
+					aspect_ratio: aspectRatio,
+					resolution: xaiResolution,
+					n: 1,
+					response_format: "b64_json",
+				};
+				const xaiBody: XAIImageRequestBody = isEdit
+					? buildXAIEditPayload(xaiBaseBody, resolvedImages)
+					: xaiBaseBody;
+				const xaiEndpoint = isEdit ? "/images/edits" : "/images/generations";
+
+				const xaiResponse = await fetch(`${xaiCreds.baseURL}${xaiEndpoint}`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${xaiCreds.apiKey}`,
+						"Content-Type": "application/json",
+						"User-Agent": ohMyPiXAIUserAgent(),
+					},
+					body: JSON.stringify(xaiBody),
+					signal: requestSignal,
+				});
+
+				const xaiRawText = await xaiResponse.text();
+				if (!xaiResponse.ok) {
+					let message = xaiRawText;
+					try {
+						const parsedErr = JSON.parse(xaiRawText) as { error?: { message?: string } };
+						message = parsedErr.error?.message ?? message;
+					} catch {
+						// Keep raw text.
+					}
+					throw new Error(`xAI image request failed (${xaiResponse.status}): ${message}`);
+				}
+
+				const xaiData = JSON.parse(xaiRawText) as {
+					data?: Array<{ b64_json?: string; url?: string }>;
+				};
+				const xaiInlineImages: InlineImageData[] = [];
+				for (const entry of xaiData.data ?? []) {
+					if (entry.b64_json) {
+						const bytes = Buffer.from(entry.b64_json, "base64");
+						const mimeType = parseImageMetadata(bytes)?.mimeType ?? "image/png";
+						xaiInlineImages.push({ data: entry.b64_json, mimeType });
+					} else if (entry.url) {
+						xaiInlineImages.push(await loadImageFromUrl(entry.url, requestSignal));
+					}
+				}
+
+				if (xaiInlineImages.length === 0) {
+					return {
+						content: [{ type: "text", text: "No image data returned." }],
+						details: {
+							provider,
+							model: resolvedModel,
+							imageCount: 0,
+							imagePaths: [],
+							images: [],
+						},
+					};
+				}
+
+				const xaiImagePaths = await saveImagesToTemp(xaiInlineImages);
+
+				return {
+					content: [
+						{ type: "text", text: buildResponseSummary(provider, resolvedModel, xaiImagePaths, undefined) },
+					],
+					details: {
+						provider,
+						model: resolvedModel,
+						imageCount: xaiInlineImages.length,
+						imagePaths: xaiImagePaths,
+						images: xaiInlineImages,
+					},
+				};
+			}
+
 			if (provider === "openrouter") {
 				const prompt = assemblePrompt(params);
 				const contentParts: OpenRouterContentPart[] = [{ type: "text", text: prompt }];

package/src/tools/index.ts

@@ -92,6 +92,7 @@ export * from "./search";
 export * from "./search-tool-bm25";
 export * from "./ssh";
 export * from "./todo-write";
+export * from "./tts";
 export * from "./write";
 export * from "./yield";
 

package/src/tools/plan-mode-guard.ts

@@ -5,6 +5,8 @@ import { normalizeLocalScheme, resolveToCwd } from "./path-utils";
 import { ToolError } from "./tool-errors";
 
 const LOCAL_SCHEME_PREFIX = "local:";
+const PLAN_ALIAS_FILE = "PLAN.md";
+const LOCAL_PLAN_ALIAS = "local://PLAN.md";
 
 function resolveRawPath(session: ToolSession, targetPath: string): string {
 	const normalized = normalizeLocalScheme(targetPath);
@@ -18,15 +20,20 @@ function resolveRawPath(session: ToolSession, targetPath: string): string {
 	return resolveToCwd(normalized, session.cwd);
 }
 
+function isPlanAliasTarget(session: ToolSession, targetPath: string, resolved: string): boolean {
+	const normalized = normalizeLocalScheme(targetPath);
+	if (normalized === LOCAL_PLAN_ALIAS) return true;
+	return resolved === resolveToCwd(PLAN_ALIAS_FILE, session.cwd);
+}
+
 /**
  * Resolve a write/edit target to its absolute filesystem path.
  *
- * In plan mode, transparently redirects targets whose basename matches the
- * plan file's basename (e.g. a bare `PLAN.md` or `./PLAN.md`) to the canonical
- * plan file location at `state.planFilePath`. This lets `write` and `edit`
- * accept the unqualified plan filename and have the change land at the
- * session-scoped `local://PLAN.md` artifact instead of a stray cwd-relative
- * file the plan-mode guard would otherwise reject.
+ * In plan mode, transparently redirects `PLAN.md` aliases and targets whose
+ * basename matches the plan file's basename to the canonical plan file
+ * location at `state.planFilePath`. This lets `write` and `edit` accept the
+ * habitual plan filename after approval even when the active artifact has a
+ * titled path such as `local://APPROVED.md`.
  *
  * Outside plan mode (or when the basename does not match) this is a no-op.
  */
@@ -38,6 +45,7 @@ export function resolvePlanPath(session: ToolSession, targetPath: string): strin
 
 	const planResolved = resolveRawPath(session, state.planFilePath);
 	if (resolved === planResolved) return resolved;
+	if (isPlanAliasTarget(session, targetPath, resolved)) return planResolved;
 	if (path.basename(resolved) !== path.basename(planResolved)) return resolved;
 
 	return planResolved;