@gajae-code/coding-agent 0.5.4 → 0.6.1

package/dist/types/web/search/providers/base.d.ts

@@ -32,6 +32,28 @@ export interface SearchParams {
     maxOutputTokens?: number;
     numSearchResults?: number;
     temperature?: number;
+    /** xAI-specific search surface. Defaults to web_search when omitted. */
+    xaiSearchMode?: "web" | "x" | "web_and_x";
+    /** xAI web_search domain allow-list (max 5). */
+    allowedDomains?: string[];
+    /** xAI web_search domain deny-list (max 5). */
+    excludedDomains?: string[];
+    /** xAI x_search handle allow-list (max 20). */
+    allowedXHandles?: string[];
+    /** xAI x_search handle deny-list (max 20). */
+    excludedXHandles?: string[];
+    /** xAI x_search lower date bound, ISO8601 date such as YYYY-MM-DD. */
+    fromDate?: string;
+    /** xAI x_search upper date bound, ISO8601 date such as YYYY-MM-DD. */
+    toDate?: string;
+    /** xAI web_search/x_search image understanding. */
+    enableImageUnderstanding?: boolean;
+    /** xAI web_search image search result embedding. */
+    enableImageSearch?: boolean;
+    /** xAI x_search video understanding. */
+    enableVideoUnderstanding?: boolean;
+    /** xAI Responses include=["no_inline_citations"]. */
+    noInlineCitations?: boolean;
     googleSearch?: Record<string, unknown>;
     codeExecution?: Record<string, unknown>;
     urlContext?: Record<string, unknown>;

package/dist/types/web/search/providers/xai.d.ts

@@ -0,0 +1,64 @@
+/**
+ * xAI Web/X Search Provider
+ *
+ * Uses xAI's Responses API with the built-in web_search and x_search tools.
+ * Endpoint: POST https://api.x.ai/v1/responses
+ */
+import type { AuthStorage } from "@gajae-code/ai";
+import type { SearchCitation, SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+declare const XAI_SEARCH_MODES: readonly ["web", "x", "web_and_x"];
+export type XaiSearchMode = (typeof XAI_SEARCH_MODES)[number];
+export interface XaiSearchParams {
+    query: string;
+    system_prompt?: string;
+    num_results?: number;
+    max_output_tokens?: number;
+    temperature?: number;
+    recency?: "day" | "week" | "month" | "year";
+    xai_search_mode?: XaiSearchMode;
+    allowed_domains?: string[];
+    excluded_domains?: string[];
+    allowed_x_handles?: string[];
+    excluded_x_handles?: string[];
+    from_date?: string;
+    to_date?: string;
+    enable_image_understanding?: boolean;
+    enable_image_search?: boolean;
+    enable_video_understanding?: boolean;
+    no_inline_citations?: boolean;
+    signal?: AbortSignal;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}
+export declare function buildXaiRequestBody(params: {
+    query: string;
+    systemPrompt: string;
+    model: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    recency?: XaiSearchParams["recency"];
+    xaiSearchMode?: XaiSearchMode;
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    allowedXHandles?: string[];
+    excludedXHandles?: string[];
+    fromDate?: string;
+    toDate?: string;
+    enableImageUnderstanding?: boolean;
+    enableImageSearch?: boolean;
+    enableVideoUnderstanding?: boolean;
+    noInlineCitations?: boolean;
+}): Record<string, unknown>;
+export declare function parseXaiCitations(json: any): SearchCitation[];
+/** Execute xAI web/X search through the Responses API search tools. */
+export declare function searchXai(params: XaiSearchParams): Promise<SearchResponse>;
+/** Search provider for xAI web and X search. */
+export declare class XaiProvider extends SearchProvider {
+    readonly id = "xai";
+    readonly label = "xAI";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/types.d.ts

@@ -4,7 +4,7 @@
  * Unified types for web search responses across supported providers.
  */
 /** Supported web search providers */
-export type SearchProviderId = "duckduckgo" | "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng" | "openai-compatible";
+export type SearchProviderId = "duckduckgo" | "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "xai" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng" | "openai-compatible";
 export type WebSearchMode = "on" | "off" | "auto";
 export interface ActiveSearchModelContext {
     provider: string;
@@ -15,7 +15,7 @@ export interface ActiveSearchModelContext {
     headers?: Record<string, string>;
     webSearch?: WebSearchMode;
 }
-export declare const CONFIGURABLE_SEARCH_PROVIDER_IDS: readonly ["duckduckgo", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "tavily", "parallel", "kagi", "synthetic", "searxng"];
+export declare const CONFIGURABLE_SEARCH_PROVIDER_IDS: readonly ["duckduckgo", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
 export declare function isSearchProviderId(value: string): value is SearchProviderId;
 export declare function isConfigurableSearchProviderId(value: string): value is (typeof CONFIGURABLE_SEARCH_PROVIDER_IDS)[number];
 export declare function isSearchProviderPreference(value: string): value is (typeof CONFIGURABLE_SEARCH_PROVIDER_IDS)[number] | "auto";
@@ -40,8 +40,16 @@ export interface SearchCitation {
 export interface SearchUsage {
     inputTokens?: number;
     outputTokens?: number;
-    /** Anthropic: number of web search requests made */
+    /** Number of web search requests made */
     searchRequests?: number;
+    /** Number of xAI X Search requests made */
+    xSearchRequests?: number;
+    /** Number of image search requests made */
+    imageSearchRequests?: number;
+    /** Number of image-understanding/view-image requests made */
+    imageUnderstandingRequests?: number;
+    /** Number of video-understanding requests made */
+    videoUnderstandingRequests?: number;
     /** Perplexity: combined token count */
     totalTokens?: number;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.5.4",
+	"version": "0.6.1",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.5.4",
-		"@gajae-code/agent-core": "0.5.4",
-		"@gajae-code/ai": "0.5.4",
-		"@gajae-code/natives": "0.5.4",
-		"@gajae-code/tui": "0.5.4",
-		"@gajae-code/utils": "0.5.4",
+		"@gajae-code/stats": "0.6.1",
+		"@gajae-code/agent-core": "0.6.1",
+		"@gajae-code/ai": "0.6.1",
+		"@gajae-code/natives": "0.6.1",
+		"@gajae-code/tui": "0.6.1",
+		"@gajae-code/utils": "0.6.1",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli/web-search-cli.ts

@@ -6,9 +6,15 @@
 
 import { APP_NAME } from "@gajae-code/utils";
 import chalk from "chalk";
+import { Settings } from "../config/settings";
 import { initTheme, theme } from "../modes/theme/theme";
-import { runSearchQuery, type SearchQueryParams } from "../web/search/index";
-import { SEARCH_PROVIDER_ORDER } from "../web/search/provider";
+import {
+	isConfigurableSearchProviderId,
+	isSearchProviderPreference,
+	runSearchQuery,
+	type SearchQueryParams,
+} from "../web/search/index";
+import { SEARCH_PROVIDER_ORDER, setPreferredSearchProvider, setSearchFallbackProviders } from "../web/search/provider";
 import { renderSearchResult } from "../web/search/render";
 import type { SearchProviderId } from "../web/search/types";
 
@@ -18,11 +24,45 @@ export interface SearchCommandArgs {
 	recency?: "day" | "week" | "month" | "year";
 	limit?: number;
 	expanded: boolean;
+	xaiSearchMode?: SearchQueryParams["xai_search_mode"];
+	allowedDomains?: string[];
+	excludedDomains?: string[];
+	allowedXHandles?: string[];
+	excludedXHandles?: string[];
+	fromDate?: string;
+	toDate?: string;
+	enableImageUnderstanding?: boolean;
+	enableImageSearch?: boolean;
+	enableVideoUnderstanding?: boolean;
+	noInlineCitations?: boolean;
 }
 
 const PROVIDERS: Array<SearchProviderId | "auto"> = ["auto", ...SEARCH_PROVIDER_ORDER];
 
 const RECENCY_OPTIONS: SearchCommandArgs["recency"][] = ["day", "week", "month", "year"];
+const XAI_SEARCH_MODES: Array<NonNullable<SearchCommandArgs["xaiSearchMode"]>> = ["web", "x", "web_and_x"];
+
+function appendCsv(existing: string[] | undefined, raw: string | undefined): string[] | undefined {
+	const values = raw
+		?.split(",")
+		.map(value => value.trim())
+		.filter(Boolean);
+	if (!values?.length) return existing;
+	return [...(existing ?? []), ...values];
+}
+
+function splitFlag(raw: string): { flag: string; inlineValue?: string } {
+	const equals = raw.indexOf("=");
+	if (raw.startsWith("-") && equals > 0) return { flag: raw.slice(0, equals), inlineValue: raw.slice(equals + 1) };
+	return { flag: raw };
+}
+
+function readValue(args: string[], index: number, flag: string, inlineValue: string | undefined): string {
+	if (inlineValue !== undefined) return inlineValue;
+	const value = args[index + 1];
+	if (!value) throw new Error(`${flag} requires a value`);
+	return value;
+}
 
 /**
  * Parse web search subcommand arguments.
@@ -41,17 +81,53 @@ export function parseSearchArgs(args: string[]): SearchCommandArgs | undefined {
 	const positional: string[] = [];
 
 	for (let i = 1; i < args.length; i++) {
-		const arg = args[i];
+		const { flag: arg, inlineValue } = splitFlag(args[i]);
+		const value = () => readValue(args, i, arg, inlineValue);
+		const consumeSeparateValue = () => {
+			if (inlineValue === undefined) i++;
+		};
 		if (arg === "--provider") {
-			result.provider = args[++i] as SearchCommandArgs["provider"];
+			result.provider = value() as SearchCommandArgs["provider"];
+			consumeSeparateValue();
 		} else if (arg === "--recency") {
-			result.recency = args[++i] as SearchCommandArgs["recency"];
+			result.recency = value() as SearchCommandArgs["recency"];
+			consumeSeparateValue();
 		} else if (arg === "--limit" || arg === "-l") {
-			result.limit = Number.parseInt(args[++i], 10);
+			result.limit = Number.parseInt(value(), 10);
+			consumeSeparateValue();
+		} else if (arg === "--xai-mode") {
+			result.xaiSearchMode = value() as SearchCommandArgs["xaiSearchMode"];
+			consumeSeparateValue();
+		} else if (arg === "--allowed-domain" || arg === "--allowed-domains") {
+			result.allowedDomains = appendCsv(result.allowedDomains, value());
+			consumeSeparateValue();
+		} else if (arg === "--excluded-domain" || arg === "--excluded-domains") {
+			result.excludedDomains = appendCsv(result.excludedDomains, value());
+			consumeSeparateValue();
+		} else if (arg === "--allowed-x-handle" || arg === "--allowed-x-handles") {
+			result.allowedXHandles = appendCsv(result.allowedXHandles, value());
+			consumeSeparateValue();
+		} else if (arg === "--excluded-x-handle" || arg === "--excluded-x-handles") {
+			result.excludedXHandles = appendCsv(result.excludedXHandles, value());
+			consumeSeparateValue();
+		} else if (arg === "--from-date") {
+			result.fromDate = value();
+			consumeSeparateValue();
+		} else if (arg === "--to-date") {
+			result.toDate = value();
+			consumeSeparateValue();
+		} else if (arg === "--image-understanding") {
+			result.enableImageUnderstanding = true;
+		} else if (arg === "--image-search") {
+			result.enableImageSearch = true;
+		} else if (arg === "--video-understanding") {
+			result.enableVideoUnderstanding = true;
+		} else if (arg === "--no-inline-citations") {
+			result.noInlineCitations = true;
 		} else if (arg === "--compact") {
 			result.expanded = false;
 		} else if (!arg.startsWith("-")) {
-			positional.push(arg);
+			positional.push(args[i]);
 		}
 	}
 
@@ -80,18 +156,46 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 		process.exit(1);
 	}
 
+	if (cmd.xaiSearchMode && !XAI_SEARCH_MODES.includes(cmd.xaiSearchMode)) {
+		process.stderr.write(`${chalk.red(`Error: Invalid xAI mode "${cmd.xaiSearchMode}"`)}\n`);
+		process.stderr.write(`${chalk.dim(`Valid xAI modes: ${XAI_SEARCH_MODES.join(", ")}`)}\n`);
+		process.exit(1);
+	}
+
 	if (cmd.limit !== undefined && Number.isNaN(cmd.limit)) {
 		process.stderr.write(`${chalk.red("Error: --limit must be a number")}\n`);
 		process.exit(1);
 	}
 
 	await initTheme();
+	const settings = await Settings.init();
+	const configuredProvider = settings.get("providers.webSearch");
+	if (typeof configuredProvider === "string" && isSearchProviderPreference(configuredProvider)) {
+		setPreferredSearchProvider(configuredProvider);
+	}
+	const configuredFallback = settings.get("web_search.fallback");
+	if (Array.isArray(configuredFallback)) {
+		setSearchFallbackProviders(
+			configuredFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
+		);
+	}
 
 	const params: SearchQueryParams = {
 		query: cmd.query,
 		provider: cmd.provider,
 		recency: cmd.recency,
 		limit: cmd.limit,
+		xai_search_mode: cmd.xaiSearchMode,
+		allowed_domains: cmd.allowedDomains,
+		excluded_domains: cmd.excludedDomains,
+		allowed_x_handles: cmd.allowedXHandles,
+		excluded_x_handles: cmd.excludedXHandles,
+		from_date: cmd.fromDate,
+		to_date: cmd.toDate,
+		enable_image_understanding: cmd.enableImageUnderstanding,
+		enable_image_search: cmd.enableImageSearch,
+		enable_video_understanding: cmd.enableVideoUnderstanding,
+		no_inline_citations: cmd.noInlineCitations,
 	};
 
 	const result = await runSearchQuery(params);
@@ -121,7 +225,18 @@ ${chalk.bold("Arguments:")}
 
 ${chalk.bold("Options:")}
   --provider <name>   Provider: ${PROVIDERS.join(", ")}
-  --recency <value>   Recency filter (Brave/Perplexity): ${RECENCY_OPTIONS.join(", ")}
+  --recency <value>   Recency filter: ${RECENCY_OPTIONS.join(", ")}
+  --xai-mode <mode>   xAI mode: web, x, web_and_x
+  --allowed-domain(s) d xAI web_search domain allow-list (comma-separated, repeatable)
+  --excluded-domain(s) d xAI web_search domain deny-list (comma-separated, repeatable)
+  --allowed-x-handle(s) h xAI x_search handle allow-list (comma-separated, repeatable)
+  --excluded-x-handle(s) h xAI x_search handle deny-list (comma-separated, repeatable)
+  --from-date <date>  xAI x_search start date (ISO8601)
+  --to-date <date>    xAI x_search end date (ISO8601)
+  --image-understanding Enable xAI image understanding
+  --image-search      Enable xAI web image search
+  --video-understanding Enable xAI X video understanding
+  --no-inline-citations Disable xAI inline citation markdown
   -l, --limit <n>     Max results to return
   --compact           Render condensed output
   -h, --help          Show this help

package/src/cli.ts

@@ -35,6 +35,7 @@ const commands: CommandEntry[] = [
 	{ name: "gc", load: () => import("./commands/gc").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "web-search", aliases: ["q"], load: () => import("./commands/web-search").then(m => m.default) },
 	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
 	{
 		name: "contribute-pr",
@@ -42,6 +43,7 @@ const commands: CommandEntry[] = [
 		load: () => import("./commands/contribution-prep").then(m => m.default),
 	},
 	{ name: "deep-interview", load: () => import("./commands/deep-interview").then(m => m.default) },
+	{ name: "rlm", load: () => import("./commands/rlm").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
 ];

package/src/commands/rlm.ts

@@ -0,0 +1,19 @@
+/**
+ * `gjc rlm` — opt-in Jupyter-style research session with a persistent Python kernel.
+ */
+import { Command } from "@gajae-code/utils/cli";
+import { runRlmCommand } from "../rlm";
+
+export default class Rlm extends Command {
+	static description = "Opt-in research session: persistent Python kernel, live notebook, synthesized report";
+	static strict = false;
+	static examples = [
+		"# Start an interactive research session\n  gjc rlm",
+		'# Seed the session with an initial question\n  gjc rlm "What drives the spike in the orders table?"',
+		"# Point the session at a data description\n  gjc rlm --data ./datasets/DATA.md",
+	];
+
+	async run(): Promise<void> {
+		await runRlmCommand(this.argv);
+	}
+}

package/src/commands/web-search.ts

@@ -9,6 +9,22 @@ const PROVIDERS: Array<string> = ["auto", ...SEARCH_PROVIDER_ORDER];
 
 const RECENCY: NonNullable<SearchCommandArgs["recency"]>[] = ["day", "week", "month", "year"];
 
+type ListFlagValue = string | string[] | undefined;
+
+function appendCsv(existing: string[] | undefined, raw: ListFlagValue): string[] | undefined {
+	const rawValues = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];
+	const values = rawValues
+		.flatMap(value => value.split(","))
+		.map(value => value.trim())
+		.filter(Boolean);
+	if (values.length === 0) return existing;
+	return [...(existing ?? []), ...values];
+}
+
+function combineCsv(...values: ListFlagValue[]): string[] | undefined {
+	return values.reduce<string[] | undefined>((acc, value) => appendCsv(acc, value), undefined);
+}
+
 export default class Search extends Command {
 	static description = "Test web search providers";
 
@@ -22,6 +38,45 @@ export default class Search extends Command {
 		provider: Flags.string({ description: "Search provider", options: PROVIDERS }),
 		recency: Flags.string({ description: "Recency filter", options: RECENCY }),
 		limit: Flags.integer({ char: "l", description: "Max results to return" }),
+		"xai-mode": Flags.string({ description: "xAI mode", options: ["web", "x", "web_and_x"] }),
+		"allowed-domain": Flags.string({
+			description: "xAI web_search allowed domains, comma-separated",
+			multiple: true,
+		}),
+		"allowed-domains": Flags.string({
+			description: "xAI web_search allowed domains, comma-separated",
+			multiple: true,
+		}),
+		"excluded-domain": Flags.string({
+			description: "xAI web_search excluded domains, comma-separated",
+			multiple: true,
+		}),
+		"excluded-domains": Flags.string({
+			description: "xAI web_search excluded domains, comma-separated",
+			multiple: true,
+		}),
+		"allowed-x-handle": Flags.string({
+			description: "xAI x_search allowed handles, comma-separated",
+			multiple: true,
+		}),
+		"allowed-x-handles": Flags.string({
+			description: "xAI x_search allowed handles, comma-separated",
+			multiple: true,
+		}),
+		"excluded-x-handle": Flags.string({
+			description: "xAI x_search excluded handles, comma-separated",
+			multiple: true,
+		}),
+		"excluded-x-handles": Flags.string({
+			description: "xAI x_search excluded handles, comma-separated",
+			multiple: true,
+		}),
+		"from-date": Flags.string({ description: "xAI x_search start date (ISO8601)" }),
+		"to-date": Flags.string({ description: "xAI x_search end date (ISO8601)" }),
+		"image-understanding": Flags.boolean({ description: "Enable xAI image understanding" }),
+		"image-search": Flags.boolean({ description: "Enable xAI web image search" }),
+		"video-understanding": Flags.boolean({ description: "Enable xAI X video understanding" }),
+		"no-inline-citations": Flags.boolean({ description: "Disable xAI inline citation markdown" }),
 		compact: Flags.boolean({ description: "Render condensed output" }),
 	};
 
@@ -35,6 +90,17 @@ export default class Search extends Command {
 			recency: flags.recency as SearchCommandArgs["recency"],
 			limit: flags.limit,
 			expanded: !flags.compact,
+			xaiSearchMode: flags["xai-mode"] as SearchCommandArgs["xaiSearchMode"],
+			allowedDomains: combineCsv(flags["allowed-domain"], flags["allowed-domains"]),
+			excludedDomains: combineCsv(flags["excluded-domain"], flags["excluded-domains"]),
+			allowedXHandles: combineCsv(flags["allowed-x-handle"], flags["allowed-x-handles"]),
+			excludedXHandles: combineCsv(flags["excluded-x-handle"], flags["excluded-x-handles"]),
+			fromDate: flags["from-date"],
+			toDate: flags["to-date"],
+			enableImageUnderstanding: flags["image-understanding"],
+			enableImageSearch: flags["image-search"],
+			enableVideoUnderstanding: flags["video-understanding"],
+			noInlineCitations: flags["no-inline-citations"],
 		};
 
 		await runSearchCommand(cmd);

package/src/config/keybindings.ts

@@ -27,8 +27,10 @@ interface AppKeybindings {
 	"app.model.select": true;
 	"app.model.selectTemporary": true;
 	"app.tools.expand": true;
+	"app.tool.backgroundFold": true;
 	"app.editor.external": true;
 	"app.message.followUp": true;
+	"app.message.queue": true;
 	"app.message.dequeue": true;
 	"app.clipboard.pasteImage": true;
 	"app.clipboard.copyLine": true;
@@ -106,6 +108,10 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+o",
 		description: "Expand tools",
 	},
+	"app.tool.backgroundFold": {
+		defaultKeys: "ctrl+b",
+		description: "Fold/background supported foreground tool",
+	},
 	"app.editor.external": {
 		defaultKeys: "ctrl+g",
 		description: "Open external editor",
@@ -114,6 +120,10 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+enter",
 		description: "Send follow-up message",
 	},
+	"app.message.queue": {
+		defaultKeys: "alt+enter",
+		description: "Queue message for next turn",
+	},
 	"app.message.dequeue": {
 		defaultKeys: "alt+up",
 		description: "Dequeue message",
@@ -217,6 +227,7 @@ const KEYBINDING_NAME_MIGRATIONS = {
 	toggleThinking: "app.thinking.toggle",
 	externalEditor: "app.editor.external",
 	followUp: "app.message.followUp",
+	queue: "app.message.queue",
 	dequeue: "app.message.dequeue",
 	pasteImage: "app.clipboard.pasteImage",
 	copyLine: "app.clipboard.copyLine",

package/src/config/model-profiles.ts

@@ -6,6 +6,7 @@ export type ModelProfileRole = GjcModelAssignmentTargetId;
 export interface ModelProfileDefinition {
 	name: string;
 	requiredProviders: string[];
+	displayName?: string;
 	/**
 	 * Optional groups of providers that are interchangeable fallbacks.
 	 * Each group is an array of provider ids where at least one must be
@@ -323,8 +324,14 @@ const PROFILE_RECOMMENDATIONS: Record<string, string> = {
 	"minimax-code": "minimax-medium",
 };
 
-export function getModelProfilePresentation(name: string): ModelProfilePresentation {
-	return PROFILE_PRESENTATION[name] ?? { displayName: name, providerGroup: "COMBOS" };
+export function getModelProfilePresentation(
+	profile: string | Pick<ModelProfileDefinition, "name" | "displayName">,
+): ModelProfilePresentation {
+	const name = typeof profile === "string" ? profile : profile.name;
+	const displayName = typeof profile === "string" ? undefined : profile.displayName;
+	const presentation = PROFILE_PRESENTATION[name];
+	if (presentation) return presentation;
+	return { displayName: displayName ?? name, providerGroup: "CUSTOM" };
 }
 
 export function groupModelProfilesForPresetLanding(
@@ -333,7 +340,7 @@ export function groupModelProfilesForPresetLanding(
 	const groups = new Map<string, ModelProfileDefinition[]>();
 	for (const group of PROFILE_GROUP_ORDER) groups.set(group, []);
 	for (const profile of profiles.values()) {
-		const group = getModelProfilePresentation(profile.name).providerGroup;
+		const group = getModelProfilePresentation(profile).providerGroup;
 		if (!groups.has(group)) groups.set(group, []);
 		groups.get(group)?.push(profile);
 	}
@@ -365,6 +372,7 @@ export function mergeModelProfiles(userProfiles?: ModelsConfig["profiles"]): Map
 		const modelMapping = { ...definition.model_mapping };
 		profiles.set(name, {
 			name,
+			displayName: definition.display_name,
 			requiredProviders: aggregateModelProfileRequiredProviders(definition.required_providers, { modelMapping }),
 			modelMapping,
 			source: "user",

package/src/config/model-registry.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
 	type Api,
@@ -45,11 +46,17 @@ import {
 	formatCanonicalVariantSelector,
 	type ModelEquivalenceConfig,
 } from "./model-equivalence";
-import { type ModelProfileDefinition, mergeModelProfiles } from "./model-profiles";
+import {
+	aggregateModelProfileRequiredProviders,
+	type ModelProfileDefinition,
+	mergeModelProfiles,
+} from "./model-profiles";
 import {
 	type ModelOverride,
+	type ModelProfileConfig,
 	type ModelsConfig,
 	ModelsConfigSchema,
+	ProfileDefinitionSchema,
 	type ProviderAuthMode,
 	type ProviderDiscovery,
 } from "./models-config-schema";
@@ -1489,6 +1496,53 @@ export class ModelRegistry {
 	getAvailableModelProfileNames(): string[] {
 		return [...this.#modelProfiles.keys()].sort((a, b) => a.localeCompare(b));
 	}
+
+	async saveCustomModelProfile(name: string, definition: ModelProfileConfig): Promise<ModelProfileDefinition> {
+		const normalizedName = name.trim();
+		if (!normalizedName) throw new Error("Profile name is required.");
+		const checkedDefinition = ProfileDefinitionSchema.safeParse(definition);
+		if (!checkedDefinition.success) {
+			const first = checkedDefinition.error.issues[0];
+			const where = first?.path.length ? `/${first.path.map(String).join("/")}` : "root";
+			throw new Error(`Custom model profile is invalid at ${where}: ${first?.message ?? "unknown schema error"}`);
+		}
+		const loaded = this.#modelsConfigFile.tryLoad();
+		if (loaded.status === "error") {
+			throw new Error(
+				`Cannot create custom model profile because ${this.#modelsConfigFile.path()} is invalid. Fix the existing config before saving a new preset.`,
+			);
+		}
+		const current = loaded.value ?? this.#modelsConfigFile.createDefault();
+		if (mergeModelProfiles(current.profiles).has(normalizedName)) {
+			throw new Error(`Custom model profile already exists: ${normalizedName}. Choose a unique preset id.`);
+		}
+		const next: ModelsConfig = {
+			...current,
+			profiles: {
+				...(current.profiles ?? {}),
+				[normalizedName]: definition,
+			},
+		};
+		const checkedConfig = ModelsConfigSchema.safeParse(next);
+		if (!checkedConfig.success) {
+			const first = checkedConfig.error.issues[0];
+			const where = first?.path.length ? `/${first.path.map(String).join("/")}` : "root";
+			throw new Error(`Generated models config is invalid at ${where}: ${first?.message ?? "unknown schema error"}`);
+		}
+		await fs.mkdir(path.dirname(this.#modelsConfigFile.path()), { recursive: true });
+		await Bun.write(this.#modelsConfigFile.path(), Bun.YAML.stringify(checkedConfig.data, null, 2));
+		this.#modelsConfigFile.invalidate();
+		this.#reloadStaticModels();
+		const modelMapping = { ...definition.model_mapping };
+		const profile: ModelProfileDefinition = {
+			name: normalizedName,
+			displayName: definition.display_name,
+			requiredProviders: aggregateModelProfileRequiredProviders(definition.required_providers, { modelMapping }),
+			modelMapping,
+			source: "user",
+		};
+		return profile;
+	}
 	applyConfiguredModelBindings(targetSettings: Settings): void {
 		this.#modelBindingsTargetSettings = targetSettings;
 		this.#applyConfiguredModelBindingsToTarget();

package/src/config/models-config-schema.ts

@@ -108,6 +108,7 @@ export const ProfileModelMappingSchema = z.partialRecord(ProfileRoleSchema, Prof
 export const ProfileDefinitionSchema = z
 	.object({
 		required_providers: z.array(z.string().min(1)).min(1),
+		display_name: z.string().min(1).optional(),
 		model_mapping: ProfileModelMappingSchema,
 	})
 	.strict();