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

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [15.5.7] - 2026-05-27
+### Added
+- `providers.openrouterVariant` setting (Settings → Providers → "OpenRouter Routing") to default OpenRouter requests to a routing-variant suffix (`:nitro`, `:floor`, `:online`, `:exacto`). Selectors that already name a variant (e.g. `openrouter/anthropic/claude-haiku:nitro`) keep precedence.
+
+- `generate_image` supports xAI Grok Imagine via `providers.image=xai`. Supports `grok-imagine-image` (default) and `grok-imagine-image-quality` at aspect ratios `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`. Uses the xAI Grok OAuth credential when available, otherwise `XAI_API_KEY`.
+- New `tts` tool synthesises speech via xAI Grok Voice behind the disabled-by-default `tts.enabled` setting. Built-in voices `ara`, `eve` (default), `leo`, `rex`, `sal`; custom voice IDs also accepted. Output codec inferred from the `output_path` suffix (`.wav` → `wav`, else `mp3`). Up to 15,000 characters per request.
+
+### Fixed
+
+- Fixed plan-mode re-entry after approval reopening a fresh `local://PLAN.md` instead of the approved titled plan artifact, which could duplicate plan content and fail approval on an existing destination.
+- Fixed `read` URL reader mode aborting after a stalled Jina request instead of falling back to trafilatura/lynx/native: Jina (and Parallel extract) now have their own per-attempt sub-budget capped at 10s, the catch handler honours only real user cancellation, and the in-process native renderer is always attempted on already-loaded HTML ([#1449](https://github.com/can1357/oh-my-pi/issues/1449))
+
 ## [15.5.6] - 2026-05-27
 ### Added
 
@@ -57,6 +69,10 @@
 
 - Fixed `omp` startup and `/changelog` reading the host project's `CHANGELOG.md` as omp's — `getPackageDir()` no longer falls back to the user's `cwd` when no owning `package.json` is locatable, preventing spurious `lastChangelogVersion` writes ([#1423](https://github.com/can1357/oh-my-pi/issues/1423))
 
+### Fixed
+
+- Fixed hashline session-chain replay silently overwriting in-session edits when the model re-targeted a previously rewritten line with a stale file hash; replay now refuses unless every edit's anchor line content matches between the snapshot and the current file ([#1422](https://github.com/can1357/oh-my-pi/pull/1422))
+
 ## [15.5.3] - 2026-05-27
 ### Breaking Changes
 
@@ -66,6 +82,10 @@
 
 - Warned when legacy inline `LINE:TEXT` lines are accepted as payload continuations only when inside a pending multi-line `A-B:` replacement
 
+### Fixed
+
+- Fixed runtime model registry refresh and cache loading so providers with authoritative dynamic catalogs, including Synthetic, do not re-add deprecated bundled model IDs after discovery ([#1417](https://github.com/can1357/oh-my-pi/issues/1417)).
+
 ## [15.5.2] - 2026-05-26
 ### Breaking Changes
 
@@ -8867,4 +8887,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
+- HTML export with syntax highlighting and collapsible sections

package/dist/types/config/settings-schema.d.ts

@@ -2393,6 +2393,15 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Enable the calculator tool for basic calculations";
         };
     };
+    readonly "tts.enabled": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly ui: {
+            readonly tab: "tools";
+            readonly label: "Text-to-Speech";
+            readonly description: "Enable the tts tool for xAI Grok Voice speech synthesis";
+        };
+    };
     readonly "recipe.enabled": {
         readonly type: "boolean";
         readonly default: true;
@@ -3118,7 +3127,7 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "providers.image": {
         readonly type: "enum";
-        readonly values: readonly ["auto", "openai", "gemini", "openrouter"];
+        readonly values: readonly ["auto", "openai", "antigravity", "xai", "gemini", "openrouter"];
         readonly default: "auto";
         readonly ui: {
             readonly tab: "providers";
@@ -3127,11 +3136,19 @@ export declare const SETTINGS_SCHEMA: {
             readonly options: readonly [{
                 readonly value: "auto";
                 readonly label: "Auto";
-                readonly description: "Priority: GPT model image tool > Antigravity > OpenRouter > Gemini";
+                readonly description: "Priority: GPT model image tool > Antigravity > xAI > OpenRouter > Gemini";
             }, {
                 readonly value: "openai";
                 readonly label: "OpenAI";
                 readonly description: "Uses the active GPT Responses/Codex model";
+            }, {
+                readonly value: "antigravity";
+                readonly label: "Antigravity";
+                readonly description: "Requires google-antigravity OAuth";
+            }, {
+                readonly value: "xai";
+                readonly label: "xAI Grok Imagine";
+                readonly description: "Requires xAI Grok OAuth or XAI_API_KEY";
             }, {
                 readonly value: "gemini";
                 readonly label: "Gemini";
@@ -3185,6 +3202,37 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "providers.openrouterVariant": {
+        readonly type: "enum";
+        readonly values: readonly ["default", "nitro", "floor", "online", "exacto"];
+        readonly default: "default";
+        readonly ui: {
+            readonly tab: "providers";
+            readonly label: "OpenRouter Routing";
+            readonly description: "Default routing-variant suffix appended to OpenRouter model IDs (overridden when the selector already names a variant)";
+            readonly options: readonly [{
+                readonly value: "default";
+                readonly label: "Default";
+                readonly description: "No suffix; use OpenRouter's default routing";
+            }, {
+                readonly value: "nitro";
+                readonly label: ":nitro";
+                readonly description: "Prioritize throughput / lowest latency";
+            }, {
+                readonly value: "floor";
+                readonly label: ":floor";
+                readonly description: "Prioritize cheapest available provider";
+            }, {
+                readonly value: "online";
+                readonly label: ":online";
+                readonly description: "Enable OpenRouter's web-search plugin";
+            }, {
+                readonly value: "exacto";
+                readonly label: ":exacto";
+                readonly description: "Cherry-picked high-quality providers (only defined for select models)";
+            }];
+        };
+    };
     readonly "providers.parallelFetch": {
         readonly type: "boolean";
         readonly default: true;

package/dist/types/lib/xai-http.d.ts

@@ -0,0 +1,40 @@
+import type { ModelRegistry } from "../config/model-registry";
+interface XAICredentials {
+    provider: "xai-oauth" | "xai";
+    apiKey: string;
+    baseURL: string;
+}
+export declare function ohMyPiXAIUserAgent(): string;
+/**
+ * Resolve xAI credentials for HTTP tool calls.
+ *
+ * Credential priority:
+ *   1. xai-oauth — only when a *dedicated* xai-oauth source exists. Composed
+ *      of two checks against the registry layer:
+ *        a. `authStorage.hasNonEnvCredential("xai-oauth")` covers stored
+ *           credentials (OAuth or api_key), runtime overrides (CLI
+ *           `--api-key` for xai-oauth), config overrides (models.yml
+ *           `providers.xai-oauth.apiKey`), and fallback resolvers.
+ *        b. `$env.XAI_OAUTH_TOKEN` covers the xai-oauth-specific env var.
+ *      `XAI_API_KEY` is intentionally NOT a signal here, even though the
+ *      env-fallback map (`stream.ts: "xai-oauth"`) lets xai-oauth borrow it
+ *      as a back-compat convenience: the borrow lets API-key-only setups
+ *      satisfy the xai-oauth branch and then resolve baseUrl under
+ *      xai-oauth instead of xai, silently bypassing `providers.xai.baseUrl`
+ *      overrides for image/TTS traffic. The gate routes the borrow case to
+ *      step 2 while preserving every dedicated xai-oauth path.
+ *   2. xai (plain API key). Delegates to ModelRegistry.getApiKeyForProvider
+ *      which runs AuthStorage.getApiKey's full cascade: runtime override →
+ *      models.yml config override → stored api_key credential → OAuth
+ *      resolution → XAI_API_KEY env var → custom fallback resolver.
+ *
+ * baseURL: see `resolveXAIBaseURL` above. Resolved AFTER the credential
+ * decision so the scoped (provider, id) lookup is unambiguous. `modelId`
+ * is optional; probes / tool-availability checks pass `undefined` and fall
+ * through to env/default.
+ *
+ * Returns null when neither credential is available. Caller is responsible
+ * for surfacing an actionable error message in that case.
+ */
+export declare function resolveXAIHttpCredentials(modelRegistry: ModelRegistry, modelId?: string): Promise<XAICredentials | null>;
+export {};

package/dist/types/session/agent-session.d.ts

@@ -454,6 +454,7 @@ export declare class AgentSession {
     get goalRuntime(): GoalRuntime;
     markPlanReferenceSent(): void;
     setPlanReferencePath(path: string): void;
+    getPlanReferencePath(): string;
     get clientBridge(): ClientBridge | undefined;
     setClientBridge(bridge: ClientBridge | undefined): void;
     getCheckpointState(): CheckpointState | undefined;

package/dist/types/tools/fetch.d.ts

@@ -1,8 +1,10 @@
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { type Component } from "@oh-my-pi/pi-tui";
+import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
+import type { AgentStorage } from "../session/agent-storage";
 import { type OutputMeta } from "./output-meta";
 import { type LineRange } from "./path-utils";
 export declare function isReadableUrlPath(value: string): boolean;
@@ -15,6 +17,20 @@ export interface ParsedReadUrlTarget {
     ranges?: readonly LineRange[];
 }
 export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+/**
+ * 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 declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null): Promise<{
+    content: string;
+    ok: boolean;
+    method: string;
+}>;
 interface FetchImagePayload {
     data: string;
     mimeType: string;

package/dist/types/tools/image-gen.d.ts

@@ -2,7 +2,8 @@ import { type Model } from "@oh-my-pi/pi-ai";
 import * as z from "zod/v4";
 import { type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
-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";
 declare const responseModalitySchema: z.ZodEnum<{
     IMAGE: "IMAGE";
     TEXT: "TEXT";
@@ -19,6 +20,8 @@ export declare const imageGenSchema: z.ZodObject<{
     aspect_ratio: z.ZodOptional<z.ZodEnum<{
         "16:9": "16:9";
         "1:1": "1:1";
+        "2:3": "2:3";
+        "3:2": "3:2";
         "3:4": "3:4";
         "4:3": "4:3";
         "9:16": "9:16";
@@ -70,8 +73,9 @@ interface InlineImageData {
     data: string;
     mimeType: string;
 }
+export declare function isImageProviderPreference(value: unknown): value is ImageProviderPreference;
 /** Set the preferred image provider from settings */
-export declare function setPreferredImageProvider(provider: ImageProvider | "auto"): void;
+export declare function setPreferredImageProvider(provider: ImageProviderPreference): void;
 export declare const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails>;
 export declare function getImageGenTools(modelRegistry?: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
 export declare function getImageGenToolsWithRegistry(modelRegistry: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;

package/dist/types/tools/index.d.ts

@@ -54,6 +54,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";
 /** Tool type (AgentTool from pi-ai) */

package/dist/types/tools/plan-mode-guard.d.ts

@@ -2,12 +2,11 @@ import type { ToolSession } from ".";
 /**
  * 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.
  */

package/dist/types/tools/tts.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod/v4";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+type TtsCodec = "mp3" | "wav";
+declare const ttsSchema: z.ZodObject<{
+    text: z.ZodString;
+    voice_id: z.ZodDefault<z.ZodString>;
+    language: z.ZodDefault<z.ZodString>;
+    output_path: z.ZodString;
+    sample_rate: z.ZodOptional<z.ZodNumber>;
+    bit_rate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+interface TtsToolDetails {
+    bytes: number;
+    voiceId: string;
+    codec: TtsCodec;
+}
+export declare const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.5.6",
+	"version": "15.5.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,13 +47,13 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "15.5.6",
-		"@oh-my-pi/omp-stats": "15.5.6",
-		"@oh-my-pi/pi-agent-core": "15.5.6",
-		"@oh-my-pi/pi-ai": "15.5.6",
-		"@oh-my-pi/pi-natives": "15.5.6",
-		"@oh-my-pi/pi-tui": "15.5.6",
-		"@oh-my-pi/pi-utils": "15.5.6",
+		"@oh-my-pi/hashline": "15.5.7",
+		"@oh-my-pi/omp-stats": "15.5.7",
+		"@oh-my-pi/pi-agent-core": "15.5.7",
+		"@oh-my-pi/pi-ai": "15.5.7",
+		"@oh-my-pi/pi-natives": "15.5.7",
+		"@oh-my-pi/pi-tui": "15.5.7",
+		"@oh-my-pi/pi-utils": "15.5.7",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/config/model-registry.ts

@@ -291,6 +291,12 @@ export function mergeDiscoveredModel<TApi extends Api>(
 	return model;
 }
 
+const AUTHORITATIVE_RUNTIME_CATALOG_PROVIDERS = new Set<string>(
+	PROVIDER_DESCRIPTORS.filter(descriptor => descriptor.dynamicModelsAuthoritative).map(
+		descriptor => descriptor.providerId,
+	),
+);
+
 function isAuthoritativeProjectCatalogModel(model: Model<Api>): boolean {
 	return (
 		model.provider === "google-vertex" &&
@@ -323,6 +329,11 @@ interface DiscoveryProviderConfig {
 	optional?: boolean;
 }
 
+interface BuiltInDiscoveryResult {
+	models: Model<Api>[];
+	authoritativeProviders: Set<string>;
+}
+
 export type ProviderDiscoveryStatus = "idle" | "ok" | "empty" | "cached" | "unavailable" | "unauthenticated";
 
 export interface ProviderDiscoveryState {
@@ -914,6 +925,11 @@ export class ModelRegistry {
 				cachedAuthoritativeProviders.add(provider);
 			}
 		}
+		for (const provider of cachedStandardResult.authoritativeFreshProviders) {
+			if (AUTHORITATIVE_RUNTIME_CATALOG_PROVIDERS.has(provider)) {
+				cachedAuthoritativeProviders.add(provider);
+			}
+		}
 		if (cachedAuthoritativeProviders.size > 0) {
 			builtInModels = dropProviderModels(builtInModels, cachedAuthoritativeProviders);
 		}
@@ -1253,12 +1269,12 @@ export class ModelRegistry {
 				: Promise.all(
 						selectedDiscoverableProviders.map(provider => this.#discoverProviderModels(provider, strategy)),
 					).then(results => results.flat());
-		const [configuredDiscovered, builtInDiscovered] = await Promise.all([
+		const [configuredDiscovered, builtInDiscovery] = await Promise.all([
 			configuredDiscoveriesPromise,
 			this.#discoverBuiltInProviderModels(strategy, providerFilter),
 		]);
-		const discovered = [...configuredDiscovered, ...builtInDiscovered];
-		if (discovered.length === 0) {
+		const discovered = [...configuredDiscovered, ...builtInDiscovery.models];
+		if (discovered.length === 0 && builtInDiscovery.authoritativeProviders.size === 0) {
 			return;
 		}
 		const discoveredModels = this.#applyHardcodedModelPolicies(
@@ -1271,6 +1287,9 @@ export class ModelRegistry {
 			),
 		);
 		const authoritativeProviders = providersWithAuthoritativeProjectCatalog(discoveredModels);
+		for (const provider of builtInDiscovery.authoritativeProviders) {
+			authoritativeProviders.add(provider);
+		}
 		const baseModels =
 			authoritativeProviders.size > 0 ? dropProviderModels(this.#models, authoritativeProviders) : this.#models;
 		const resolved = this.#mergeResolvedModels(baseModels, discoveredModels);
@@ -1385,7 +1404,7 @@ export class ModelRegistry {
 	async #discoverBuiltInProviderModels(
 		strategy: ModelRefreshStrategy,
 		providerFilter?: ReadonlySet<string>,
-	): Promise<Model<Api>[]> {
+	): Promise<BuiltInDiscoveryResult> {
 		// Skip providers already handled by configured discovery (e.g. user-configured ollama with discovery.type)
 		const configuredDiscoveryProviders = new Set(this.#discoverableProviders.map(p => p.provider));
 		const managerOptions = (await this.#collectBuiltInModelManagerOptions()).filter(opts => {
@@ -1395,12 +1414,20 @@ export class ModelRegistry {
 			return providerFilter ? providerFilter.has(opts.providerId) : true;
 		});
 		if (managerOptions.length === 0) {
-			return [];
+			return { models: [], authoritativeProviders: new Set() };
 		}
 		const discoveries = await Promise.all(
 			managerOptions.map(options => this.#discoverWithModelManager(options, strategy)),
 		);
-		return discoveries.flat();
+		const authoritativeProviders = new Set<string>();
+		const models: Model<Api>[] = [];
+		for (const discovery of discoveries) {
+			models.push(...discovery.models);
+			for (const provider of discovery.authoritativeProviders) {
+				authoritativeProviders.add(provider);
+			}
+		}
+		return { models, authoritativeProviders };
 	}
 
 	async #collectBuiltInModelManagerOptions(): Promise<ModelManagerOptions<Api>[]> {
@@ -1482,19 +1509,24 @@ export class ModelRegistry {
 	async #discoverWithModelManager(
 		options: ModelManagerOptions<Api>,
 		strategy: ModelRefreshStrategy,
-	): Promise<Model<Api>[]> {
+	): Promise<BuiltInDiscoveryResult> {
 		try {
 			const manager = createModelManager({ ...options, cacheDbPath: this.#cacheDbPath });
 			const result = await manager.refresh(strategy);
-			return result.models.map(model =>
+			const models = result.models.map(model =>
 				model.provider === options.providerId ? model : { ...model, provider: options.providerId },
 			);
+			const authoritativeProviders = new Set<string>();
+			if (options.dynamicModelsAuthoritative && !result.stale) {
+				authoritativeProviders.add(options.providerId);
+			}
+			return { models, authoritativeProviders };
 		} catch (error) {
 			logger.warn("model discovery failed for provider", {
 				provider: options.providerId,
 				error: error instanceof Error ? error.message : String(error),
 			});
-			return [];
+			return { models: [], authoritativeProviders: new Set() };
 		}
 	}
 

package/src/config/settings-schema.ts

@@ -2036,6 +2036,15 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"tts.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tools",
+			label: "Text-to-Speech",
+			description: "Enable the tts tool for xAI Grok Voice speech synthesis",
+		},
+	},
 	"recipe.enabled": {
 		type: "boolean",
 		default: true,
@@ -2698,7 +2707,7 @@ export const SETTINGS_SCHEMA = {
 	},
 	"providers.image": {
 		type: "enum",
-		values: ["auto", "openai", "gemini", "openrouter"] as const,
+		values: ["auto", "openai", "antigravity", "xai", "gemini", "openrouter"] as const,
 		default: "auto",
 		ui: {
 			tab: "providers",
@@ -2708,9 +2717,19 @@ export const SETTINGS_SCHEMA = {
 				{
 					value: "auto",
 					label: "Auto",
-					description: "Priority: GPT model image tool > Antigravity > OpenRouter > Gemini",
+					description: "Priority: GPT model image tool > Antigravity > xAI > OpenRouter > Gemini",
 				},
 				{ value: "openai", label: "OpenAI", description: "Uses the active GPT Responses/Codex model" },
+				{
+					value: "antigravity",
+					label: "Antigravity",
+					description: "Requires google-antigravity OAuth",
+				},
+				{
+					value: "xai",
+					label: "xAI Grok Imagine",
+					description: "Requires xAI Grok OAuth or XAI_API_KEY",
+				},
 				{ value: "gemini", label: "Gemini", description: "Requires GEMINI_API_KEY" },
 				{ value: "openrouter", label: "OpenRouter", description: "Requires OPENROUTER_API_KEY" },
 			],
@@ -2748,6 +2767,28 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"providers.openrouterVariant": {
+		type: "enum",
+		values: ["default", "nitro", "floor", "online", "exacto"] as const,
+		default: "default",
+		ui: {
+			tab: "providers",
+			label: "OpenRouter Routing",
+			description:
+				"Default routing-variant suffix appended to OpenRouter model IDs (overridden when the selector already names a variant)",
+			options: [
+				{ value: "default", label: "Default", description: "No suffix; use OpenRouter's default routing" },
+				{ value: "nitro", label: ":nitro", description: "Prioritize throughput / lowest latency" },
+				{ value: "floor", label: ":floor", description: "Prioritize cheapest available provider" },
+				{ value: "online", label: ":online", description: "Enable OpenRouter's web-search plugin" },
+				{
+					value: "exacto",
+					label: ":exacto",
+					description: "Cherry-picked high-quality providers (only defined for select models)",
+				},
+			],
+		},
+	},
 	"providers.parallelFetch": {
 		type: "boolean",
 		default: true,

package/src/lib/xai-http.ts

@@ -0,0 +1,124 @@
+// Ported from NousResearch/hermes-agent (MIT) — tools/xai_http.py.
+
+import { getBundledModels } from "@oh-my-pi/pi-ai";
+import { $env } from "@oh-my-pi/pi-utils";
+import type { ModelRegistry } from "../config/model-registry";
+
+const DEFAULT_BASE_URL = "https://api.x.ai/v1";
+
+interface XAICredentials {
+	provider: "xai-oauth" | "xai";
+	apiKey: string;
+	baseURL: string;
+}
+
+export function ohMyPiXAIUserAgent(): string {
+	return "oh-my-pi/xai";
+}
+
+type XAIProvider = "xai-oauth" | "xai";
+
+/**
+ * Resolve the HTTP base URL for an xAI tool call.
+ *
+ * Precedence:
+ *   1. `model.baseUrl` from the registry IF the user pinned a per-model
+ *      override — i.e. `merged.baseUrl` differs from the seeded/bundled
+ *      default for the (provider, id) pair. Mirrors the chat path's per-model
+ *      contract (`openai-responses.ts: model.baseUrl`).
+ *   2. `ModelRegistry.getProviderBaseUrl(provider)` — provider-level override
+ *      (e.g. `providers.xai-oauth.baseUrl` from models.yml). Reached when the
+ *      modelId does not appear in the registry under this provider, which
+ *      happens for tool-only ids like `grok-imagine-image` that
+ *      `applyXAIOAuthCuration` filters out via `XAI_NON_CHAT_PREFIXES`.
+ *      Without this leg, a registry-configured proxy is silently bypassed for
+ *      image/TTS traffic.
+ *   3. `XAI_BASE_URL` env var (legacy global override, preserved).
+ *   4. `DEFAULT_BASE_URL = "https://api.x.ai/v1"`.
+ *
+ * The override gate at step 1 uses `bundled?.baseUrl ?? DEFAULT_BASE_URL` as
+ * the canonical default sentinel. For xai (which has bundled entries) this
+ * compares against the bundled value; for xai-oauth (no bundled entries —
+ * models.json carries no xai-oauth records when the seed is absent, the
+ * picker is seeded statically from `xaiOAuthModelManagerOptions` with
+ * `baseUrl: DEFAULT_BASE_URL`) the sentinel falls back to DEFAULT_BASE_URL
+ * so the env leg remains reachable. Without that fallback, every xai-oauth
+ * model id forces `!bundled === true` and short-circuits XAI_BASE_URL
+ * silently. Lookup is scoped to (provider, id); matching by id alone would
+ * let xai-oauth entries hijack a xai tool call (or vice versa) when the
+ * same model id ships under both descriptors.
+ */
+function resolveXAIBaseURL(modelRegistry: ModelRegistry, provider: XAIProvider, modelId: string | undefined): string {
+	if (modelId) {
+		const merged = modelRegistry.getAll().find(m => m.id === modelId && m.provider === provider);
+		if (merged?.baseUrl) {
+			const bundled = getBundledModels(provider as Parameters<typeof getBundledModels>[0]).find(
+				m => m.id === modelId,
+			);
+			const providerDefault = bundled?.baseUrl ?? DEFAULT_BASE_URL;
+			if (merged.baseUrl !== providerDefault) {
+				return merged.baseUrl.replace(/\/$/, "");
+			}
+		}
+	}
+	const providerBaseUrl = modelRegistry.getProviderBaseUrl(provider);
+	if (providerBaseUrl) {
+		const normalized = providerBaseUrl.replace(/\/$/, "");
+		if (normalized !== DEFAULT_BASE_URL) return normalized;
+	}
+	return ($env.XAI_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+
+/**
+ * Resolve xAI credentials for HTTP tool calls.
+ *
+ * Credential priority:
+ *   1. xai-oauth — only when a *dedicated* xai-oauth source exists. Composed
+ *      of two checks against the registry layer:
+ *        a. `authStorage.hasNonEnvCredential("xai-oauth")` covers stored
+ *           credentials (OAuth or api_key), runtime overrides (CLI
+ *           `--api-key` for xai-oauth), config overrides (models.yml
+ *           `providers.xai-oauth.apiKey`), and fallback resolvers.
+ *        b. `$env.XAI_OAUTH_TOKEN` covers the xai-oauth-specific env var.
+ *      `XAI_API_KEY` is intentionally NOT a signal here, even though the
+ *      env-fallback map (`stream.ts: "xai-oauth"`) lets xai-oauth borrow it
+ *      as a back-compat convenience: the borrow lets API-key-only setups
+ *      satisfy the xai-oauth branch and then resolve baseUrl under
+ *      xai-oauth instead of xai, silently bypassing `providers.xai.baseUrl`
+ *      overrides for image/TTS traffic. The gate routes the borrow case to
+ *      step 2 while preserving every dedicated xai-oauth path.
+ *   2. xai (plain API key). Delegates to ModelRegistry.getApiKeyForProvider
+ *      which runs AuthStorage.getApiKey's full cascade: runtime override →
+ *      models.yml config override → stored api_key credential → OAuth
+ *      resolution → XAI_API_KEY env var → custom fallback resolver.
+ *
+ * baseURL: see `resolveXAIBaseURL` above. Resolved AFTER the credential
+ * decision so the scoped (provider, id) lookup is unambiguous. `modelId`
+ * is optional; probes / tool-availability checks pass `undefined` and fall
+ * through to env/default.
+ *
+ * Returns null when neither credential is available. Caller is responsible
+ * for surfacing an actionable error message in that case.
+ */
+export async function resolveXAIHttpCredentials(
+	modelRegistry: ModelRegistry,
+	modelId?: string,
+): Promise<XAICredentials | null> {
+	const hasDedicatedXaiOAuth =
+		modelRegistry.authStorage.hasNonEnvCredential("xai-oauth") || Boolean($env.XAI_OAUTH_TOKEN);
+	if (hasDedicatedXaiOAuth) {
+		const oauthKey = await modelRegistry.getApiKeyForProvider("xai-oauth");
+		if (oauthKey) {
+			const baseURL = resolveXAIBaseURL(modelRegistry, "xai-oauth", modelId);
+			return { provider: "xai-oauth", apiKey: oauthKey, baseURL };
+		}
+	}
+
+	const apiKey = await modelRegistry.getApiKeyForProvider("xai");
+	if (apiKey) {
+		const baseURL = resolveXAIBaseURL(modelRegistry, "xai", modelId);
+		return { provider: "xai", apiKey, baseURL };
+	}
+
+	return null;
+}