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

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;

package/src/tools/read.ts

@@ -1488,6 +1488,21 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (!this.session.settings.get("fetch.enabled")) {
 				throw new ToolError("URL reads are disabled by settings.");
 			}
+			if (parsedUrlTarget.ranges !== undefined) {
+				const cached = await loadReadUrlCacheEntry(
+					this.session,
+					{ path: parsedUrlTarget.path, raw: parsedUrlTarget.raw },
+					signal,
+					{ ensureArtifact: true, preferCached: true },
+				);
+				return this.#buildInMemoryMultiRangeResult(cached.output, parsedUrlTarget.ranges, {
+					details: { ...cached.details },
+					sourceUrl: cached.details.finalUrl,
+					entityLabel: "URL output",
+					raw: parsedUrlTarget.raw,
+					immutable: true,
+				});
+			}
 			if (parsedUrlTarget.offset !== undefined || parsedUrlTarget.limit !== undefined) {
 				const cached = await loadReadUrlCacheEntry(
 					this.session,
@@ -1502,6 +1517,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					details: { ...cached.details },
 					sourceUrl: cached.details.finalUrl,
 					entityLabel: "URL output",
+					raw: parsedUrlTarget.raw,
 					immutable: true,
 				});
 			}
@@ -1578,7 +1594,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			if (isMultiRange(parsed)) {
 				throw new ToolError("Multi-range line selectors are not supported for directory listings.");
 			}
-			const dirResult = await this.#readDirectory(absolutePath, selToOffsetLimit(parsed).limit, signal);
+			const { offset, limit } = selToOffsetLimit(parsed);
+			const dirResult = await this.#readDirectory(absolutePath, offset, limit, signal);
 			if (suffixResolution) {
 				dirResult.details ??= {};
 				dirResult.details.suffixResolution = suffixResolution;
@@ -2136,6 +2153,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	/** Read directory contents as a formatted listing */
 	async #readDirectory(
 		absolutePath: string,
+		offset: number | undefined,
 		limit: number | undefined,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<ReadToolDetails>> {
@@ -2149,7 +2167,9 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				maxDepth: READ_DIRECTORY_MAX_DEPTH,
 				perDirLimit: READ_DIRECTORY_CHILD_LIMIT,
 				rootLimit: null,
-				lineCap: limit ?? null,
+				// `lineCap` truncates the rendered tree itself, so apply it only when the caller
+				// did not request an offset — otherwise we'd cap the first N lines before slicing.
+				lineCap: offset === undefined && limit !== undefined ? limit : null,
 			});
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -2158,12 +2178,46 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		throwIfAborted(signal);
 
 		const output = tree.totalLines <= 1 ? "(empty directory)" : tree.rendered;
-		const truncation = truncateHead(output, { maxLines: Number.MAX_SAFE_INTEGER });
 		const details: ReadToolDetails = {
 			isDirectory: true,
 			resolvedPath: tree.rootPath,
 		};
 
+		// Slice the rendered listing when the caller passed an offset/limit. We do this
+		// instead of passing the selector down to `buildDirectoryTree` because the tree
+		// builder lays out entries hierarchically (per-dir caps, recent-then-elided
+		// summaries); line-based slicing operates on the formatted text and matches what
+		// users expect from `:N-M` on long listings.
+		const wantsSlice = offset !== undefined || limit !== undefined;
+		if (wantsSlice) {
+			const allLines = output.split("\n");
+			const start = offset ? Math.max(0, offset - 1) : 0;
+			if (start >= allLines.length) {
+				const suggestion =
+					allLines.length === 0
+						? "The listing is empty."
+						: `Use :1 to read from the start, or :${allLines.length} to read the last line.`;
+				return toolResult(details)
+					.text(`Line ${start + 1} is beyond end of listing (${allLines.length} lines total). ${suggestion}`)
+					.sourcePath(tree.rootPath)
+					.done();
+			}
+			const end = limit !== undefined ? Math.min(start + limit, allLines.length) : allLines.length;
+			const sliced = allLines.slice(start, end).join("\n");
+			const resultBuilder = toolResult(details).sourcePath(tree.rootPath);
+			let text = sliced;
+			if (end < allLines.length) {
+				const remaining = allLines.length - end;
+				text += `\n\n[${remaining} more lines in listing. Use :${end + 1} to continue]`;
+			}
+			resultBuilder.text(text);
+			if (tree.truncated) {
+				resultBuilder.limits({ resultLimit: 1 });
+			}
+			return resultBuilder.done();
+		}
+
+		const truncation = truncateHead(output, { maxLines: Number.MAX_SAFE_INTEGER });
 		const resultBuilder = toolResult(details).text(truncation.content).sourcePath(tree.rootPath);
 		if (tree.truncated) {
 			resultBuilder.limits({ resultLimit: 1 });

package/src/tools/search.ts

@@ -478,8 +478,8 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 						);
 					}
 				} catch (err) {
-					if (err instanceof Error && err.message.startsWith("regex parse error")) {
-						throw new ToolError(err.message);
+					if (err instanceof Error && /^regex(?: parse)? error/i.test(err.message)) {
+						throw new ToolError(err.message.replace(/^regex(?: parse)? error:?\s*/i, "Invalid regex: "));
 					}
 					throw err;
 				}

package/src/tools/tts.ts

@@ -0,0 +1,133 @@
+// Ported from NousResearch/hermes-agent (MIT) — tools/tts_tool.py L167-171, L896-959.
+
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import * as z from "zod/v4";
+import type { CustomTool, CustomToolContext } from "../extensibility/custom-tools/types";
+import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
+import { formatPathRelativeToCwd, resolveToCwd } from "./path-utils";
+
+// Hermes tts_tool.py L167-171
+const DEFAULT_XAI_VOICE_ID = "eve" as const;
+const DEFAULT_XAI_LANGUAGE = "en" as const;
+const DEFAULT_XAI_SAMPLE_RATE = 24_000;
+const DEFAULT_XAI_BIT_RATE = 128_000;
+const XAI_MAX_TEXT_LENGTH = 15_000;
+
+// Built-in voices per xAI Tier-1 docs (2026-05-16). xAI also accepts custom voice IDs,
+// so the schema does NOT enum-restrict voice_id; this constant only drives the description.
+const XAI_BUILTIN_VOICES = ["ara", "eve", "leo", "rex", "sal"] as const;
+
+const formatVoiceList = (): string =>
+	XAI_BUILTIN_VOICES.map(v => (v === DEFAULT_XAI_VOICE_ID ? `${v} (default)` : v)).join(", ");
+
+type TtsCodec = "mp3" | "wav";
+
+const ttsSchema = z.object({
+	text: z.string().min(1).max(XAI_MAX_TEXT_LENGTH),
+	voice_id: z.string().default(DEFAULT_XAI_VOICE_ID),
+	language: z.string().default(DEFAULT_XAI_LANGUAGE),
+	output_path: z.string(),
+	sample_rate: z.number().int().optional(),
+	bit_rate: z.number().int().optional(),
+});
+
+interface TtsToolDetails {
+	bytes: number;
+	voiceId: string;
+	codec: TtsCodec;
+}
+
+export const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails> = {
+	name: "tts",
+	label: "TextToSpeech",
+	strict: false,
+	approval: "write",
+	description:
+		`Synthesize speech from text using xAI Grok Voice. Built-in voices: ${formatVoiceList()}. ` +
+		"Custom voice IDs also accepted. Output codec inferred from output_path suffix (.wav → wav, else mp3). " +
+		`Max ${XAI_MAX_TEXT_LENGTH.toLocaleString("en-US")} characters.`,
+	parameters: ttsSchema,
+	async execute(
+		_toolCallId: string,
+		params: z.infer<typeof ttsSchema>,
+		_onUpdate,
+		ctx: CustomToolContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
+		const creds = await resolveXAIHttpCredentials(ctx.modelRegistry);
+		if (!creds) {
+			return {
+				isError: true,
+				content: [
+					{
+						type: "text",
+						text: "No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
+					},
+				],
+			};
+		}
+
+		const cwd = ctx.sessionManager.getCwd();
+		const outputPath = resolveToCwd(params.output_path, cwd);
+		const displayPath = formatPathRelativeToCwd(outputPath, cwd);
+		const codec: TtsCodec = outputPath.toLowerCase().endsWith(".wav") ? "wav" : "mp3";
+		const voiceId = params.voice_id;
+		const language = params.language;
+		const sampleRate = params.sample_rate ?? DEFAULT_XAI_SAMPLE_RATE;
+		const bitRate = params.bit_rate ?? DEFAULT_XAI_BIT_RATE;
+
+		const payload: Record<string, unknown> = {
+			text: params.text,
+			voice_id: voiceId,
+			language,
+		};
+		// Hermes tts_tool.py L926-940 — only send output_format when caller overrides a default.
+		const codecOverridden = codec !== "mp3";
+		const sampleRateOverridden = sampleRate !== DEFAULT_XAI_SAMPLE_RATE;
+		const bitRateOverridden = codec === "mp3" && bitRate !== DEFAULT_XAI_BIT_RATE;
+		if (codecOverridden || sampleRateOverridden || bitRateOverridden) {
+			const fmt: Record<string, unknown> = { codec };
+			if (sampleRate) fmt.sample_rate = sampleRate;
+			if (codec === "mp3" && bitRate) fmt.bit_rate = bitRate;
+			payload.output_format = fmt;
+		}
+
+		// Compose the caller signal with a 60 s timeout fence.
+		const timeoutSignal = AbortSignal.timeout(60_000);
+		const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+		const response = await fetch(`${creds.baseURL}/tts`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${creds.apiKey}`,
+				"Content-Type": "application/json",
+				"User-Agent": ohMyPiXAIUserAgent(),
+			},
+			body: JSON.stringify(payload),
+			signal: combinedSignal,
+		});
+		if (!response.ok) {
+			const detail = await response.text();
+			return {
+				isError: true,
+				content: [
+					{
+						type: "text",
+						text: `xAI TTS failed (${response.status}): ${detail.slice(0, 300)}`,
+					},
+				],
+			};
+		}
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		await Bun.write(outputPath, bytes);
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Saved ${bytes.length} bytes to ${displayPath} (voice=${voiceId}, codec=${codec}).`,
+				},
+			],
+			details: { bytes: bytes.length, voiceId, codec },
+		};
+	},
+};