@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/discovery/codex.ts

@@ -1,31 +1,25 @@
 /**
- * OpenAI code provider project provider.
+ * OpenAI Codex project/global skill layout adapter (import source).
  *
- * Supports project-local `.OpenAI code backend/` compatibility only. User-home OpenAI code backend
- * directories are intentionally ignored so `~/.OpenAI code backend` content is never injected
- * into GJC sessions.
+ * The `.codex/skills` layout is an explicit import source into the canonical
+ * `.gjc` skill locations — it is never loaded as an ordinary runtime authority.
+ * These helpers enumerate the layout for import/inspection consumers (#4291
+ * import UI, #4288 provenance diagnostics) and are deliberately NOT registered
+ * as capability providers: activating Codex's other surfaces (MCP servers,
+ * hooks, commands, tools, prompts, settings) is owned by sibling issues.
+ *
+ * User-home `~/.codex/skills` is enumerated as an explicit import candidate
+ * only; it is never loaded into sessions without an explicit import action.
  */
 import * as path from "node:path";
 import { logger, parseFrontmatter } from "@gajae-code/utils";
-import { registerProvider } from "../capability";
-import type { ContextFile } from "../capability/context-file";
-import { contextFileCapability } from "../capability/context-file";
-import { type ExtensionModule, extensionModuleCapability } from "../capability/extension-module";
+import type { ExtensionModule } from "../capability/extension-module";
 import { readFile } from "../capability/fs";
 import type { Hook } from "../capability/hook";
-import { hookCapability } from "../capability/hook";
 import type { MCPServer } from "../capability/mcp";
-import { mcpCapability } from "../capability/mcp";
-import type { Prompt } from "../capability/prompt";
-import { promptCapability } from "../capability/prompt";
-import type { Settings } from "../capability/settings";
-import { settingsCapability } from "../capability/settings";
 import type { Skill } from "../capability/skill";
-import { skillCapability } from "../capability/skill";
 import type { SlashCommand } from "../capability/slash-command";
-import { slashCommandCapability } from "../capability/slash-command";
 import type { CustomTool } from "../capability/tool";
-import { toolCapability } from "../capability/tool";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
 import {
 	buildExtensionModuleItems,
@@ -35,57 +29,53 @@ import {
 	scanSkillsFromDir,
 } from "./helpers";
 
-const PROVIDER_ID = "codex";
-const DISPLAY_NAME = "OpenAI Codex";
-const PRIORITY = 70;
+export const CODEX_PROVIDER_ID = "codex";
+export const CODEX_DISPLAY_NAME = "OpenAI Codex";
+export const CODEX_CONFIG_DIR = ".codex";
 
-function getProjectCodexDir(ctx: LoadContext): string {
-	return path.join(ctx.cwd, ".codex");
+/**
+ * Enumerate the project-local `.codex/skills` layout (cwd only), mirroring the
+ * OpenAI Codex project convention.
+ */
+export async function scanCodexProjectSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
+	return await scanSkillsFromDir(ctx, {
+		dir: path.join(ctx.cwd, CODEX_CONFIG_DIR, "skills"),
+		providerId: CODEX_PROVIDER_ID,
+		level: "project",
+		requireDescription: true,
+	});
 }
 
-async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
-	const items: ContextFile[] = [];
-	const agentsMd = path.join(getProjectCodexDir(ctx), "AGENTS.md");
-	const agentsContent = await readFile(agentsMd);
-	if (agentsContent) {
-		items.push({
-			path: agentsMd,
-			content: agentsContent,
-			level: "project",
-			depth: 0,
-			_source: createSourceMeta(PROVIDER_ID, agentsMd, "project"),
-		});
-	}
-	return { items, warnings: [] };
+/**
+ * Enumerate the user-global `~/.codex/skills` layout. This is an explicit
+ * import candidate only; GJC never loads it without an explicit import action.
+ */
+export async function scanCodexUserSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
+	return await scanSkillsFromDir(ctx, {
+		dir: path.join(ctx.home, CODEX_CONFIG_DIR, "skills"),
+		providerId: CODEX_PROVIDER_ID,
+		level: "user",
+		requireDescription: true,
+	});
 }
 
-async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
-	const warnings: string[] = [];
-	const projectConfigPath = path.join(getProjectCodexDir(ctx), "config.toml");
-	const projectConfig = await loadTomlConfig(projectConfigPath);
-	const items: MCPServer[] = [];
-	if (projectConfig) {
-		const servers = extractMCPServersFromToml(projectConfig);
-		for (const [name, config] of Object.entries(servers)) {
-			items.push({
-				name,
-				...config,
-				_source: createSourceMeta(PROVIDER_ID, projectConfigPath, "project"),
-			});
-		}
-	}
-	return { items, warnings };
+export function codexSkillSourceMeta(filePath: string, level: "user" | "project") {
+	return createSourceMeta(CODEX_PROVIDER_ID, filePath, level);
 }
 
-async function loadTomlConfig(filePath: string): Promise<Record<string, unknown> | null> {
-	const content = await readFile(filePath);
-	if (!content) return null;
-	try {
-		return Bun.TOML.parse(content) as Record<string, unknown>;
-	} catch (error) {
-		logger.warn("Failed to parse TOML config", { path: filePath, error: String(error) });
-		return null;
-	}
+// =============================================================================
+// Provenance inspection (#4288)
+//
+// The scans below enumerate the remaining `.codex/` project surfaces (MCP
+// servers, hooks, tools, extensions, commands) for the `gjc customize doctor`
+// provenance report. They reuse the shared discovery helpers but are
+// deliberately NOT registered as capability providers: none of these surfaces
+// are part of the session load path, and inspection must not change runtime
+// behavior.
+// =============================================================================
+
+function getProjectCodexDir(ctx: LoadContext): string {
+	return path.join(ctx.cwd, CODEX_CONFIG_DIR);
 }
 
 interface CodexMCPConfig {
@@ -104,6 +94,17 @@ interface CodexMCPConfig {
 	disabled_tools?: string[];
 }
 
+async function loadTomlConfig(filePath: string): Promise<Record<string, unknown> | null> {
+	const content = await readFile(filePath);
+	if (!content) return null;
+	try {
+		return Bun.TOML.parse(content) as Record<string, unknown>;
+	} catch (error) {
+		logger.warn("Failed to parse TOML config", { path: filePath, error: String(error) });
+		return null;
+	}
+}
+
 function extractMCPServersFromToml(toml: Record<string, unknown>): Record<string, Partial<MCPServer>> {
 	if (!toml.mcp_servers || typeof toml.mcp_servers !== "object") {
 		return {};
@@ -153,59 +154,25 @@ function extractMCPServersFromToml(toml: Record<string, unknown>): Record<string
 	return result;
 }
 
-async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
-	return await scanSkillsFromDir(ctx, {
-		dir: path.join(getProjectCodexDir(ctx), "skills"),
-		providerId: PROVIDER_ID,
-		level: "project",
-	});
-}
-
-async function loadExtensionModules(ctx: LoadContext): Promise<LoadResult<ExtensionModule>> {
-	const projectExtensionsDir = path.join(getProjectCodexDir(ctx), "extensions");
-	const projectPaths = await discoverExtensionModulePaths(ctx, projectExtensionsDir);
-	return { items: buildExtensionModuleItems(PROVIDER_ID, [], projectPaths), warnings: [] };
-}
-
-async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashCommand>> {
-	const projectCommandsDir = path.join(getProjectCodexDir(ctx), "commands");
-	const transformCommand = (name: string, content: string, filePath: string, source: SourceMeta) => {
-		const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
-		const commandName = frontmatter.name || name.replace(/\.md$/, "");
-		return {
-			name: String(commandName),
-			path: filePath,
-			content: body,
-			level: "project" as const,
-			_source: source,
-		};
-	};
-	return await loadFilesFromDir(ctx, projectCommandsDir, PROVIDER_ID, "project", {
-		extensions: ["md"],
-		transform: transformCommand,
-	});
-}
-
-async function loadPrompts(ctx: LoadContext): Promise<LoadResult<Prompt>> {
-	const projectPromptsDir = path.join(getProjectCodexDir(ctx), "prompts");
-	const transformPrompt = (name: string, content: string, filePath: string, source: SourceMeta) => {
-		const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
-		const promptName = frontmatter.name || name.replace(/\.md$/, "");
-		return {
-			name: String(promptName),
-			path: filePath,
-			content: body,
-			description: frontmatter.description ? String(frontmatter.description) : undefined,
-			_source: source,
-		};
-	};
-	return await loadFilesFromDir(ctx, projectPromptsDir, PROVIDER_ID, "project", {
-		extensions: ["md"],
-		transform: transformPrompt,
-	});
+async function inspectMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
+	const warnings: string[] = [];
+	const projectConfigPath = path.join(getProjectCodexDir(ctx), "config.toml");
+	const projectConfig = await loadTomlConfig(projectConfigPath);
+	const items: MCPServer[] = [];
+	if (projectConfig) {
+		const servers = extractMCPServersFromToml(projectConfig);
+		for (const [name, config] of Object.entries(servers)) {
+			items.push({
+				name,
+				...config,
+				_source: createSourceMeta(CODEX_PROVIDER_ID, projectConfigPath, "project"),
+			});
+		}
+	}
+	return { items, warnings };
 }
 
-async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
+async function inspectHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
 	const projectHooksDir = path.join(getProjectCodexDir(ctx), "hooks");
 	const transformHook = (name: string, _content: string, filePath: string, source: SourceMeta) => {
 		const baseName = name.replace(/\.(ts|js)$/, "");
@@ -220,13 +187,13 @@ async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
 			_source: source,
 		};
 	};
-	return await loadFilesFromDir(ctx, projectHooksDir, PROVIDER_ID, "project", {
+	return await loadFilesFromDir(ctx, projectHooksDir, CODEX_PROVIDER_ID, "project", {
 		extensions: ["ts", "js"],
 		transform: transformHook,
 	});
 }
 
-async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
+async function inspectTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 	const projectToolsDir = path.join(getProjectCodexDir(ctx), "tools");
 	const transformTool = (name: string, _content: string, filePath: string, source: SourceMeta) =>
 		({
@@ -235,96 +202,63 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 			level: "project" as const,
 			_source: source,
 		}) as CustomTool;
-	return await loadFilesFromDir(ctx, projectToolsDir, PROVIDER_ID, "project", {
+	return await loadFilesFromDir(ctx, projectToolsDir, CODEX_PROVIDER_ID, "project", {
 		extensions: ["ts", "js"],
 		transform: transformTool,
 	});
 }
 
-async function loadSettings(ctx: LoadContext): Promise<LoadResult<Settings>> {
-	const projectConfigPath = path.join(getProjectCodexDir(ctx), "config.toml");
-	const projectConfig = await loadTomlConfig(projectConfigPath);
-	return {
-		items: projectConfig
-			? [
-					{
-						...projectConfig,
-						_source: createSourceMeta(PROVIDER_ID, projectConfigPath, "project"),
-					} as Settings,
-				]
-			: [],
-		warnings: [],
-	};
+async function inspectExtensionModules(ctx: LoadContext): Promise<LoadResult<ExtensionModule>> {
+	const projectExtensionsDir = path.join(getProjectCodexDir(ctx), "extensions");
+	const projectPaths = await discoverExtensionModulePaths(ctx, projectExtensionsDir);
+	return { items: buildExtensionModuleItems(CODEX_PROVIDER_ID, [], projectPaths), warnings: [] };
 }
 
-registerProvider<ContextFile>(contextFileCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load context files from project .codex/AGENTS.md",
-	priority: PRIORITY,
-	load: loadContextFiles,
-});
-
-registerProvider<MCPServer>(mcpCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load MCP servers from project .codex/config.toml [mcp_servers.*] sections",
-	priority: PRIORITY,
-	load: loadMCPServers,
-});
-
-registerProvider<Skill>(skillCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load skills from project .codex/skills/",
-	priority: PRIORITY,
-	load: loadSkills,
-});
-
-registerProvider<ExtensionModule>(extensionModuleCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load extension modules from project .codex/extensions/",
-	priority: PRIORITY,
-	load: loadExtensionModules,
-});
-
-registerProvider<SlashCommand>(slashCommandCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load slash commands from project .codex/commands/",
-	priority: PRIORITY,
-	load: loadSlashCommands,
-});
-
-registerProvider<Prompt>(promptCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load prompts from project .codex/prompts/",
-	priority: PRIORITY,
-	load: loadPrompts,
-});
-
-registerProvider<Hook>(hookCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load hooks from project .codex/hooks/",
-	priority: PRIORITY,
-	load: loadHooks,
-});
+async function inspectSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashCommand>> {
+	const projectCommandsDir = path.join(getProjectCodexDir(ctx), "commands");
+	const transformCommand = (name: string, content: string, filePath: string, source: SourceMeta) => {
+		const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
+		const commandName = frontmatter.name || name.replace(/\.md$/, "");
+		return {
+			name: String(commandName),
+			path: filePath,
+			content: body,
+			level: "project" as const,
+			_source: source,
+		};
+	};
+	return await loadFilesFromDir(ctx, projectCommandsDir, CODEX_PROVIDER_ID, "project", {
+		extensions: ["md"],
+		transform: transformCommand,
+	});
+}
 
-registerProvider<CustomTool>(toolCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load custom tools from project .codex/tools/",
-	priority: PRIORITY,
-	load: loadTools,
-});
+export interface CodexConventionInspection {
+	mcps: LoadResult<MCPServer>;
+	skills: LoadResult<Skill>;
+	hooks: LoadResult<Hook>;
+	tools: LoadResult<CustomTool>;
+	extensions: LoadResult<ExtensionModule>;
+	commands: LoadResult<SlashCommand>;
+}
 
-registerProvider<Settings>(settingsCapability.id, {
-	id: PROVIDER_ID,
-	displayName: DISPLAY_NAME,
-	description: "Load settings from project .codex/config.toml",
-	priority: PRIORITY,
-	load: loadSettings,
-});
+/**
+ * Inspect what the Codex project convention (.codex/) would surface.
+ *
+ * Reuses the shared discovery scan helpers without registering any provider,
+ * so diagnostics can report the convention's files while keeping the runtime
+ * load path exactly as configured (none of these surfaces are registered for
+ * session loading; hooks are covered by the separate registered codex-hooks
+ * provider).
+ */
+export async function inspectCodexConvention(ctx: LoadContext): Promise<CodexConventionInspection> {
+	const [mcps, skills, hooks, tools, extensions, commands] = await Promise.all([
+		inspectMCPServers(ctx),
+		scanCodexProjectSkills(ctx),
+		inspectHooks(ctx),
+		inspectTools(ctx),
+		inspectExtensionModules(ctx),
+		inspectSlashCommands(ctx),
+	]);
+	return { mcps, skills, hooks, tools, extensions, commands };
+}

package/src/discovery/helpers.ts

@@ -416,11 +416,18 @@ export async function scanSkillsFromDir(
 					warnings.push(
 						`Skill frontmatter exceeded ${SKILL_FRONTMATTER_SCAN_TOTAL_BYTES} byte scan cap: ${skillPath}`,
 					);
+				} else {
+					warnings.push(
+						`Skill file has no parseable frontmatter (expected a leading \`---\` YAML block with name/description): ${skillPath}`,
+					);
 				}
 				return;
 			}
 			if (frontmatter.enabled === false) return;
-			if (requireDescription && !frontmatter.description) return;
+			if (requireDescription && !frontmatter.description) {
+				warnings.push(`Skill is missing a description in frontmatter: ${skillPath}`);
+				return;
+			}
 			const skillDirName = path.basename(path.dirname(skillPath));
 			const rawName = frontmatter.name;
 			const name = typeof rawName === "string" ? rawName.trim() || skillDirName : skillDirName;

package/src/discovery/index.ts

@@ -22,10 +22,12 @@ import "../capability/tool";
 // Import providers (each registers itself on import)
 import "./agents-md";
 import "./builtin";
+import "./claude-hooks";
 import "./claude-plugins";
 import "./cline";
 import "./agents";
 import "./cursor";
+import "./codex-hooks";
 import "./gemini";
 import "./opencode";
 import "./github";

package/src/discovery/mcp-compat.ts

@@ -0,0 +1,234 @@
+/**
+ * Bounded Claude Code / Codex MCP import-source adapters.
+ *
+ * These functions normalize foreign MCP formats to GJC's internal MCP contract
+ * (`MCPServer`). They are EXPLICIT import sources: a caller (for example the
+ * `/extensions` import transaction) reads a Claude `.mcp.json` or Codex
+ * `config.toml` file and writes the normalized definitions into GJC's native
+ * `.gjc` config. They are never registered as runtime discovery providers, so
+ * foreign files are never implicit competing runtime authorities, and user-home
+ * (`~/.claude`, `~/.codex`) configuration is never scanned.
+ */
+import { tryParseJson } from "@gajae-code/utils";
+import { type MCPServer, mcpCapability } from "../capability/mcp";
+import type { LoadResult, SourceMeta } from "../capability/types";
+import { createSourceMeta, expandEnvVarsDeep } from "./helpers";
+
+const PROVIDER_IDS = {
+	claude: "claude",
+	codex: "codex",
+} as const;
+
+const PROTOTYPE_SENSITIVE_SERVER_NAMES = new Set(["__proto__", "prototype", "constructor"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return isRecord(value) && Object.values(value).every(item => typeof item === "string");
+}
+
+/** Result of normalizing a foreign MCP config into the internal contract. */
+export interface MCPCompatNormalizeResult extends LoadResult<MCPServer> {
+	/** Normalization diagnostics (always present, possibly empty). */
+	warnings: string[];
+	/** Path the definitions were normalized from (for provenance). */
+	sourcePath: string;
+}
+
+function compatSource(providerId: string, sourcePath: string, level: "project" | "user"): SourceMeta {
+	return createSourceMeta(providerId, sourcePath, level);
+}
+
+/**
+ * Normalize a Claude Code `.mcp.json` file body into the internal MCP contract.
+ *
+ * The Claude project format uses the same `{ "mcpServers": { name: {...} } }`
+ * JSON shape as GJC's config; `enabled`/`autoload` are preserved so a caller
+ * can decide startup behavior after import. Bounded to the supplied content:
+ * no filesystem scanning, no user-home reads.
+ */
+export function normalizeClaudeMcpJson(
+	content: string,
+	sourcePath: string,
+	level: "project" | "user" = "project",
+): MCPCompatNormalizeResult {
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
+	const json = tryParseJson<Record<string, unknown>>(content);
+	const mcpServers = json?.mcpServers;
+	if (!json || !isRecord(mcpServers)) {
+		warnings.push(`Failed to parse MCP servers in ${sourcePath}`);
+		return { items, warnings, sourcePath };
+	}
+
+	// Check prototype-sensitive names on the RAW record first: env expansion
+	// rebuilds the object via plain assignment, which silently drops a
+	// `__proto__` own-property into the result's prototype — the check must
+	// run before that transformation or it would never fire.
+	const unsafeNames = Object.keys(mcpServers).filter(name => PROTOTYPE_SENSITIVE_SERVER_NAMES.has(name));
+	for (const name of unsafeNames) {
+		warnings.push(`Skipped unsafe MCP server name in ${sourcePath}: ${name}`);
+	}
+	const expanded = expandEnvVarsDeep(mcpServers);
+	for (const [name, config] of Object.entries(expanded)) {
+		if (PROTOTYPE_SENSITIVE_SERVER_NAMES.has(name)) {
+			continue;
+		}
+		const serverConfig = isRecord(config) ? config : {};
+		const server: MCPServer = {
+			name,
+			enabled: typeof serverConfig.enabled === "boolean" ? serverConfig.enabled : undefined,
+			autoload: typeof serverConfig.autoload === "boolean" ? serverConfig.autoload : undefined,
+			sharing:
+				serverConfig.sharing === "per-session" || serverConfig.sharing === "shared"
+					? serverConfig.sharing
+					: undefined,
+			timeout: typeof serverConfig.timeout === "number" ? serverConfig.timeout : undefined,
+			command: typeof serverConfig.command === "string" ? serverConfig.command : undefined,
+			args: Array.isArray(serverConfig.args)
+				? serverConfig.args.filter((arg): arg is string => typeof arg === "string")
+				: undefined,
+			env: isStringRecord(serverConfig.env) ? serverConfig.env : undefined,
+			noInheritEnv: typeof serverConfig.noInheritEnv === "boolean" ? serverConfig.noInheritEnv : undefined,
+			cwd: typeof serverConfig.cwd === "string" ? serverConfig.cwd : undefined,
+			url: typeof serverConfig.url === "string" ? serverConfig.url : undefined,
+			headers: isStringRecord(serverConfig.headers) ? serverConfig.headers : undefined,
+			transport:
+				serverConfig.type === "http" || serverConfig.type === "sse" || serverConfig.type === "stdio"
+					? serverConfig.type
+					: undefined,
+			_source: compatSource(PROVIDER_IDS.claude, sourcePath, level),
+		};
+		items.push(server);
+	}
+	return { items, warnings, sourcePath };
+}
+
+interface CodexMcpServerConfig {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	env_vars?: string[];
+	url?: string;
+	http_headers?: Record<string, string>;
+	env_http_headers?: Record<string, string>;
+	bearer_token_env_var?: string;
+	cwd?: string;
+	startup_timeout_sec?: number;
+	tool_timeout_sec?: number;
+}
+
+/**
+ * Extract normalized MCP servers from a Codex `config.toml` `[mcp_servers.*]`
+ * section. Codex's config does not carry an `enabled` concept; imported servers
+ * default to autoload (startup) behavior after import. Bounded to the supplied
+ * content: no filesystem scanning, no user-home reads.
+ */
+function extractCodexMcpServers(toml: Record<string, unknown>): Record<string, Partial<MCPServer>> {
+	if (!toml.mcp_servers || !isRecord(toml.mcp_servers)) return {};
+
+	const codexServers = toml.mcp_servers as Record<string, CodexMcpServerConfig>;
+	const result: Record<string, Partial<MCPServer>> = {};
+	for (const [name, config] of Object.entries(codexServers)) {
+		// `result[name] = ...` below is a plain assignment: a prototype-sensitive
+		// name would mutate the result's prototype instead of becoming an item.
+		if (PROTOTYPE_SENSITIVE_SERVER_NAMES.has(name)) continue;
+		const serverConfig = isRecord(config) ? config : {};
+		const server: Partial<MCPServer> = {
+			command: typeof serverConfig.command === "string" ? serverConfig.command : undefined,
+			args: Array.isArray(serverConfig.args)
+				? serverConfig.args.filter((arg): arg is string => typeof arg === "string")
+				: undefined,
+			url: typeof serverConfig.url === "string" ? serverConfig.url : undefined,
+			cwd: typeof serverConfig.cwd === "string" ? serverConfig.cwd : undefined,
+		};
+
+		const env: Record<string, string> = { ...(isStringRecord(serverConfig.env) ? serverConfig.env : {}) };
+		if (Array.isArray(serverConfig.env_vars)) {
+			for (const varName of serverConfig.env_vars) {
+				if (typeof varName !== "string") continue;
+				const value = Bun.env[varName];
+				if (value !== undefined) env[varName] = value;
+			}
+		}
+		if (Object.keys(env).length > 0) server.env = env;
+
+		const headers: Record<string, string> = {
+			...(isStringRecord(serverConfig.http_headers) ? serverConfig.http_headers : {}),
+		};
+		if (isRecord(serverConfig.env_http_headers)) {
+			for (const [headerName, envVarName] of Object.entries(serverConfig.env_http_headers)) {
+				if (typeof envVarName !== "string") continue;
+				const value = Bun.env[envVarName];
+				if (value !== undefined) headers[headerName] = value;
+			}
+		}
+		if (typeof serverConfig.bearer_token_env_var === "string") {
+			const token = Bun.env[serverConfig.bearer_token_env_var];
+			if (token) headers.Authorization = `Bearer ${token}`;
+		}
+		if (Object.keys(headers).length > 0) server.headers = headers;
+
+		if (server.url) {
+			server.transport = "http";
+		} else if (server.command) {
+			server.transport = "stdio";
+		}
+		if (typeof serverConfig.tool_timeout_sec === "number" && serverConfig.tool_timeout_sec > 0) {
+			server.timeout = serverConfig.tool_timeout_sec * 1000;
+		}
+		result[name] = server;
+	}
+	return result;
+}
+
+/**
+ * Normalize a Codex `config.toml` file body into the internal MCP contract.
+ * Only the `[mcp_servers.*]` sections are read; everything else is ignored.
+ */
+export function normalizeCodexMcpToml(
+	content: string,
+	sourcePath: string,
+	level: "project" | "user" = "project",
+): MCPCompatNormalizeResult {
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = Bun.TOML.parse(content) as Record<string, unknown>;
+	} catch {
+		warnings.push(`Failed to parse TOML in ${sourcePath}`);
+		return { items, warnings, sourcePath };
+	}
+
+	// Mirror the Claude path: warn on prototype-sensitive names dropped by the
+	// extractor's plain-assignment result construction.
+	if (isRecord(parsed.mcp_servers)) {
+		for (const name of Object.keys(parsed.mcp_servers)) {
+			if (PROTOTYPE_SENSITIVE_SERVER_NAMES.has(name)) {
+				warnings.push(`Skipped unsafe MCP server name in ${sourcePath}: ${name}`);
+			}
+		}
+	}
+	const servers = extractCodexMcpServers(parsed);
+	for (const [name, config] of Object.entries(servers)) {
+		items.push({
+			name,
+			...config,
+			_source: compatSource(PROVIDER_IDS.codex, sourcePath, level),
+		} as MCPServer);
+	}
+	return { items, warnings, sourcePath };
+}
+
+/**
+ * Validate a normalized server against the internal MCP contract. Returns an
+ * error message, or undefined when the definition is importable. Callers use
+ * this to fail closed before writing a malformed/untrusted definition into
+ * `.gjc` (mcpCapability.validate is reused so import and runtime share one rule).
+ */
+export function validateMCPCompatServer(server: MCPServer): string | undefined {
+	return mcpCapability.validate?.(server);
+}