From 30d9bd806eaed50240b2b503392c9896731fc1fe Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sat, 21 Nov 2026 23:29:19 +0200 Subject: [PATCH 1/4] scient: load installed Codex plugins' skills and MCP servers Scient Agent reads the plugins Codex has installed and enabled ($CODEX_HOME/config.toml, the version Codex runs from plugins/cache) and loads their skills and MCP servers through the existing skill reader and Codex MCP mapping. The source is `codex-plugins`, opt-in through SCIENT_AGENT_ENABLE_SOURCES or enabledProviders, and --runtime-info lists it under enableSources so a host can check before enabling it. Plugins that need OpenAI's host (browser, chrome, computer-use, unified-computer-use, codex-app-tools), servers launched by computer-use-client-launcher or with auth "chatgpt", app references and hooks are left out. Scient-Divergence: SA-CODEX-PLUGINS --- SCIENT.md | 3 +- docs/environment-variables.md | 2 +- packages/coding-agent/CHANGELOG.md | 6 + packages/coding-agent/src/capability/index.ts | 3 + packages/coding-agent/src/discovery/codex.ts | 3 + packages/coding-agent/src/discovery/index.ts | 3 + .../coding-agent/src/scient/codex-plugins.ts | 261 ++++++++++++++++++ .../coding-agent/src/scient/runtime-info.ts | 6 + .../test/scient/codex-plugins.test.ts | 169 ++++++++++++ .../test/scient/runtime-info.test.ts | 1 + scripts/scient/divergences.json | 19 +- 11 files changed, 473 insertions(+), 3 deletions(-) create mode 100644 packages/coding-agent/src/scient/codex-plugins.ts create mode 100644 packages/coding-agent/test/scient/codex-plugins.test.ts diff --git a/SCIENT.md b/SCIENT.md index ebaeeac3cf..07299dd176 100644 --- a/SCIENT.md +++ b/SCIENT.md @@ -14,7 +14,8 @@ Everything else is upstream's code and behavior. | Wording | The agent calls itself Scient Agent, and its command `scient-agent`, wherever a person or a model reads its words: messages, help, sign-in instructions, prompts, the built-in documentation, window and notification titles. The prompts also address researchers: the model's role is a research and coding assistant, and each personality matches its explanations to the reader's expertise instead of assuming a technical reader. `scripts/scient/rename-wording.ts` generates this. | | State | The config root is `~/.scient-agent` (project folder `.scient-agent/`), or the absolute directory a host sets in `SCIENT_AGENT_ROOT`. User config lookups, the native addon cache, browser storage state and crash logs follow it. A host's root is authoritative: `SCIENT_AGENT_DIR` is ignored under it, and a `.env` in the project or the home directory cannot set any `SCIENT_AGENT_*` variable (a `.env` inside the root can). The root is taken only from the launch environment, never from a `.env`. Standalone use keeps upstream's `.env` overrides. | | Variables | The variables that choose where state lives have `SCIENT_AGENT_*` names: `CONFIG_DIR`, `CONFIG_FILES`, `DIR`, `PROFILE`, `SESSION_DIR`, `WORKTREE_DIR`, `AUTH_BROKER_*`, `NATIVES_DIR`, the cache database overrides, the directory, TCP address and re-exec hand-over of Oh My Pi's per-user daemon, and the configuration the agent hands its own workers. OMP's names for them are ignored. Tuning variables (`PI_*`) are unchanged. | -| Discovery | A host can add foreign user-level sources with `SCIENT_AGENT_ENABLE_SOURCES` (provider ids separated by commas or whitespace). These are unioned with `enabledProviders` for discovery without changing or persisting that setting; `disabledProviders` still wins. The same aliases apply, including `claude` enabling `claude-plugins`. Under a host root, project and home `.env` files cannot add sources. | +| Discovery | A host can add foreign user-level sources with `SCIENT_AGENT_ENABLE_SOURCES` (provider ids separated by commas or whitespace). These are unioned with `enabledProviders` for discovery without changing or persisting that setting; `disabledProviders` still wins. The same aliases apply, including `claude` enabling `claude-plugins`. Under a host root, project and home `.env` files cannot add sources. `--runtime-info` lists the plugin sources a host may add (`enableSources`). | +| Codex plugins | The opt-in source `codex-plugins` loads the skills and MCP servers of the Codex plugins a person installed and enabled (`[plugins."@"]` in `$CODEX_HOME/config.toml`, default `~/.codex`), from the version Codex runs in its plugin cache. MCP fields map as the Codex `config.toml` reader maps them, with relative commands and working folders inside the package. Plugins and servers that run only inside OpenAI's apps (browser, Chrome, computer use, the Codex app's tools, the Computer Use client launcher, Codex's ChatGPT session) are left out, and so are app references, which the ChatGPT apps cover. `codex` does not enable it. | | Native addon cache | A compiled binary extracts its addons into a directory named for their content, so two builds on one upstream version never load each other's, and it loads only from that directory. A modern addon that fails to load falls back to the same build's baseline addon; an addon found beside the executable is not a fallback. | | Symbol | The sign-in page every browser sign-in ends on and the `stats` dashboard show Scient Agent's symbol (`packages/utils/src/scient/scient-agent-symbol.svg.txt`, the file Scient Desktop shows for the agent; copy it over when the symbol changes) in Scient's colors. | | Shared workers | The tiny model worker, the embedding server and word prediction run in Oh My Pi's per-user daemon. The daemon's build carries Scient Agent's release, not the upstream package version, so a new Scient Agent release has an older release's daemon re-exec into it, which replaces its workers. | diff --git a/docs/environment-variables.md b/docs/environment-variables.md index cf89a88a4f..1cb7d747c8 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -11,7 +11,7 @@ It documents only active behavior. ## Host discovery sources -`SCIENT_AGENT_ENABLE_SOURCES` adds foreign user-level discovery sources to the effective `enabledProviders` set without replacing or persisting that setting. Set it in the launch environment, for example `SCIENT_AGENT_ENABLE_SOURCES=claude-plugins` to load Claude Code's installed plugins under `~/.claude/plugins`. Separate multiple provider ids with commas or whitespace; empty and malformed entries are ignored. Ids use lowercase letters, digits and hyphens, starting with a letter; `*` and `all` are also accepted. The normal opt-in semantics apply, including `claude` enabling `claude-plugins`. `disabledProviders` takes precedence. +`SCIENT_AGENT_ENABLE_SOURCES` adds foreign user-level discovery sources to the effective `enabledProviders` set without replacing or persisting that setting. Set it in the launch environment, for example `SCIENT_AGENT_ENABLE_SOURCES=claude-plugins` to load Claude Code's installed plugins under `~/.claude/plugins`, or `codex-plugins` to load the skills and MCP servers of the Codex plugins installed and enabled in `$CODEX_HOME/config.toml` (default `~/.codex`) from Codex's plugin cache. Separate multiple provider ids with commas or whitespace; empty and malformed entries are ignored. Ids use lowercase letters, digits and hyphens, starting with a letter; `*` and `all` are also accepted. The normal opt-in semantics apply, including `claude` enabling `claude-plugins`. `disabledProviders` takes precedence. `--runtime-info` lists the plugin sources the executable can load in `enableSources`. This uses the same environment loading rules as other `SCIENT_AGENT_*` variables: when a host sets `SCIENT_AGENT_ROOT`, project and home `.env` files cannot set it (a `.env` inside the host root can). Standalone use retains the normal `.env` loading rules below. The additions affect discovery only; `getEnabledProviders()`, settings UI values, and source enable/disable writes remain based on settings alone. diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index 7420decb64..6a9c7f0a6d 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -2,6 +2,12 @@ ## [Unreleased] + +### Added + +- The skills and MCP servers of the Codex plugins you installed and enabled load when the `codex-plugins` source is on (`enabledProviders`, or a host's `SCIENT_AGENT_ENABLE_SOURCES`). Plugins that only work inside OpenAI's apps are left out. + + ## [19.0.1] - 2026-11-19 ### Added diff --git a/packages/coding-agent/src/capability/index.ts b/packages/coding-agent/src/capability/index.ts index 69c14e3f1c..00a621230f 100644 --- a/packages/coding-agent/src/capability/index.ts +++ b/packages/coding-agent/src/capability/index.ts @@ -56,6 +56,9 @@ const FOREIGN_USER_PROVIDERS: Record = { codex: true, claude: true, "claude-plugins": true, + // scient(SA-CODEX-PLUGINS): begin - Installed Codex plugins are opt-in like Claude's. + "codex-plugins": true, + // scient(SA-CODEX-PLUGINS): end gemini: true, opencode: true, windsurf: true, diff --git a/packages/coding-agent/src/discovery/codex.ts b/packages/coding-agent/src/discovery/codex.ts index 646c5863b2..0ff1cf51ef 100644 --- a/packages/coding-agent/src/discovery/codex.ts +++ b/packages/coding-agent/src/discovery/codex.ts @@ -256,6 +256,9 @@ function extractMCPServersFromToml( return result; } +// scient(SA-CODEX-PLUGINS): begin - Installed Codex plugins map their MCP servers as Codex's config.toml does. +export { extractMCPServersFromToml }; +// scient(SA-CODEX-PLUGINS): end // ============================================================================= // Skills (skills/) diff --git a/packages/coding-agent/src/discovery/index.ts b/packages/coding-agent/src/discovery/index.ts index ff58c99216..46b3d033b8 100644 --- a/packages/coding-agent/src/discovery/index.ts +++ b/packages/coding-agent/src/discovery/index.ts @@ -42,6 +42,9 @@ import "./ssh"; import "./ssh-config"; import "./vscode"; import "./windsurf"; +// scient(SA-CODEX-PLUGINS): begin - Installed, enabled Codex plugins. +import "../scient/codex-plugins"; +// scient(SA-CODEX-PLUGINS): end // Re-export the main API from capability registry export { diff --git a/packages/coding-agent/src/scient/codex-plugins.ts b/packages/coding-agent/src/scient/codex-plugins.ts new file mode 100644 index 0000000000..e60e46f748 --- /dev/null +++ b/packages/coding-agent/src/scient/codex-plugins.ts @@ -0,0 +1,261 @@ +/** + * Installed Codex plugins (SA-CODEX-PLUGINS). + * + * Codex lists plugins in `$CODEX_HOME/config.toml` (default `~/.codex`) as + * `[plugins."@"]`, enabled unless the table says `enabled = false`, and runs + * each from the active version of `$CODEX_HOME/plugins/cache////`, + * described by `.codex-plugin/plugin.json`. Their skills and MCP servers load here, MCP fields + * mapped as the Codex config.toml reader maps them. App references (`.app.json`) do not: a + * person's ChatGPT apps reach the agent through the ChatGPT sign-in (SA-CHATGPT-APPS). Plugins + * and servers that run only inside OpenAI's own apps are left out. + */ +import * as path from "node:path"; +import { $env, isRecord, logger } from "@oh-my-pi/pi-utils"; +import { isUserSourceEnabled, registerProvider } from "../capability"; +import { readDirEntries, readFile } from "../capability/fs"; +import { type MCPServer, mcpCapability } from "../capability/mcp"; +import { type Skill, skillCapability } from "../capability/skill"; +import type { LoadContext, LoadResult } from "../capability/types"; +import { extractMCPServersFromToml } from "../discovery/codex"; +import { createSourceMeta, scanSkillsFromDir } from "../discovery/helpers"; + +const PROVIDER_ID = "codex-plugins"; +const DISPLAY_NAME = "Codex Plugins"; +/** Below the `codex` provider (70), so a person's own `~/.codex` skills and servers win. */ +const PRIORITY = 65; + +/** The folder of a plugin Codex links from its source while it is developed; it wins over versions. */ +const LOCAL_VERSION = "local"; + +/** + * Bundled plugins that drive OpenAI's apps (the in-app browser, the Chrome extension host, + * computer use, the Codex app's own threads) through services only those apps provide. Their + * skills drive those services too. + */ +const HOST_PLUGINS: Record = { + "browser@openai-bundled": true, + "chrome@openai-bundled": true, + "codex-app-tools@openai-bundled": true, + "computer-use@openai-bundled": true, + "unified-computer-use@openai-bundled": true, +}; + +/** OpenAI's launcher for its signed Computer Use client, which serves only Codex (the Messages plugin). */ +const HOST_LAUNCHER = "computer-use-client-launcher"; + +const SEMVER = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/; + +interface CodexPlugin { + /** `@`, the plugin's key in config.toml. */ + id: string; + /** Plugin name: skill namespace and MCP server prefix. */ + name: string; + /** The active version's folder; package-relative paths resolve against it. */ + root: string; + manifestPath: string; + manifest: Record; + /** The plugin's `[plugins.""]` table. */ + config: Record; +} + +/** Codex's rule for a cache path segment (plugin, marketplace or version name). */ +function isPathSegment(value: string): boolean { + return value !== "." && value !== ".." && /^[A-Za-z0-9._+-]+$/.test(value); +} + +/** Codex's version order: semantic versions by precedence, anything else by its characters. */ +function compareVersions(a: string, b: string): number { + if (SEMVER.test(a) && SEMVER.test(b)) { + const order = Bun.semver.order(a, b); + if (order !== 0) return order; + } + return a < b ? -1 : a > b ? 1 : 0; +} + +/** The version folder Codex runs: `local` while present, else the highest version; null when not installed. */ +async function activeVersion(base: string): Promise { + const versions = (await readDirEntries(base)) + .filter(entry => entry.isDirectory() && isPathSegment(entry.name)) + .map(entry => entry.name); + if (versions.includes(LOCAL_VERSION)) return LOCAL_VERSION; + return versions.sort(compareVersions).at(-1) ?? null; +} + +async function readPlugin( + home: string, + id: string, + config: Record, + warnings: string[], +): Promise { + const at = id.lastIndexOf("@"); + const name = id.slice(0, at); + const marketplace = id.slice(at + 1); + if (at <= 0 || !isPathSegment(name) || !isPathSegment(marketplace)) { + warnings.push(`[codex-plugins] Ignoring invalid plugin id: ${id}`); + return null; + } + const base = path.join(home, "plugins", "cache", marketplace, name); + const version = await activeVersion(base); + // Listed but not installed (or removed since): Codex skips it as well. + if (version === null) return null; + const root = path.join(base, version); + const manifestPath = path.join(root, ".codex-plugin", "plugin.json"); + const raw = await readFile(manifestPath); + let manifest: unknown = null; + try { + manifest = raw === null ? null : JSON.parse(raw); + } catch {} + if (!isRecord(manifest)) { + warnings.push(`[codex-plugins] Missing or invalid plugin.json for ${id}: ${manifestPath}`); + return null; + } + return { id, name, root, manifestPath, manifest, config }; +} + +/** Installed, enabled Codex plugins outside {@link HOST_PLUGINS}. */ +async function listCodexPlugins(ctx: LoadContext): Promise<{ plugins: CodexPlugin[]; warnings: string[] }> { + const warnings: string[] = []; + // Codex's home: `CODEX_HOME`, else `~/.codex`. + const home = $env.CODEX_HOME?.trim() || path.join(ctx.home, ".codex"); + const configPath = path.join(home, "config.toml"); + const raw = await readFile(configPath); + if (raw === null) return { plugins: [], warnings }; + let toml: unknown; + try { + toml = Bun.TOML.parse(raw); + } catch (error) { + warnings.push(`[codex-plugins] Invalid TOML in ${configPath}: ${String(error)}`); + return { plugins: [], warnings }; + } + const table = isRecord(toml) && isRecord(toml.plugins) ? toml.plugins : {}; + const plugins = await Promise.all( + Object.entries(table).map(([id, config]) => { + if (!isRecord(config) || config.enabled === false || HOST_PLUGINS[id] === true) return null; + return readPlugin(home, id, config, warnings); + }), + ); + return { plugins: plugins.filter(plugin => plugin !== null), warnings }; +} + +/** A manifest path inside the package, or null (with a warning when it points outside). */ +function packagePath(plugin: CodexPlugin, value: unknown, key: string, warnings: string[]): string | null { + if (typeof value !== "string" || !value.trim()) return null; + const resolved = path.resolve(plugin.root, value.trim()); + const relative = path.relative(plugin.root, resolved); + if (relative.startsWith("..") || path.isAbsolute(relative)) { + warnings.push(`[codex-plugins] Ignoring ${key} path outside ${plugin.id}: ${value}`); + return null; + } + return resolved; +} + +async function loadSkills(ctx: LoadContext): Promise> { + if (!isUserSourceEnabled(PROVIDER_ID, ctx)) return { items: [] }; + const { plugins, warnings } = await listCodexPlugins(ctx); + const scans = plugins.flatMap(plugin => { + const declared = plugin.manifest.skills; + const entries = declared == null ? ["skills"] : Array.isArray(declared) ? declared : [declared]; + const dirs = new Set(); + for (const entry of entries) { + const dir = packagePath(plugin, entry, "skills", warnings); + if (dir !== null) dirs.add(dir); + } + return [...dirs].map(dir => + scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user", pluginName: plugin.name }), + ); + }); + const items: Skill[] = []; + for (const result of await Promise.all(scans)) { + items.push(...result.items); + if (result.warnings) warnings.push(...result.warnings); + } + return { items, warnings }; +} + +/** Why an MCP server runs only inside OpenAI's apps, or undefined when it runs anywhere. */ +function hostOnlyReason(server: Record): string | undefined { + if (typeof server.command === "string" && path.basename(server.command) === HOST_LAUNCHER) { + return "it launches OpenAI's Computer Use client"; + } + if (server.auth === "chatgpt") return "it signs in with Codex's own ChatGPT session"; + return undefined; +} + +/** The plugin's server map: the manifest's inline map, its named file, or the package's `.mcp.json`. */ +async function readServerMap( + plugin: CodexPlugin, + warnings: string[], +): Promise<{ servers: Record; sourcePath: string } | null> { + const declared = plugin.manifest.mcpServers; + let parsed: unknown = declared; + let sourcePath = plugin.manifestPath; + if (!isRecord(declared)) { + const file = + declared == null ? path.join(plugin.root, ".mcp.json") : packagePath(plugin, declared, "mcpServers", warnings); + if (file === null) return null; + const raw = await readFile(file); + if (raw === null) { + if (declared != null) + warnings.push(`[codex-plugins] Missing mcpServers file declared by ${plugin.id}: ${file}`); + return null; + } + try { + parsed = JSON.parse(raw); + } catch { + warnings.push(`[codex-plugins] Invalid JSON in ${file}`); + return null; + } + sourcePath = file; + } + if (!isRecord(parsed)) return null; + // Codex accepts `{ "mcpServers": { ... } }` and the bare server map. + const servers = "mcpServers" in parsed ? parsed.mcpServers : parsed; + return isRecord(servers) ? { servers, sourcePath } : null; +} + +async function loadMCPServers(ctx: LoadContext): Promise> { + if (!isUserSourceEnabled(PROVIDER_ID, ctx)) return { items: [] }; + const { plugins, warnings } = await listCodexPlugins(ctx); + const items: MCPServer[] = []; + for (const plugin of plugins) { + const map = await readServerMap(plugin, warnings); + if (map === null) continue; + const policies = isRecord(plugin.config.mcp_servers) ? plugin.config.mcp_servers : {}; + for (const [serverName, server] of Object.entries(map.servers)) { + if (!isRecord(server)) continue; + const reason = hostOnlyReason(server); + if (reason !== undefined) { + logger.debug(`[codex-plugins] Skipping MCP server "${serverName}" of ${plugin.id}: ${reason}`); + continue; + } + // Codex resolves a relative cwd, and a relative command from that cwd, against the package. + const mapped = extractMCPServersFromToml({ mcp_servers: { [serverName]: server } }, plugin.root)[serverName]; + const policy = policies[serverName]; + items.push({ + name: `${plugin.name}:${serverName}`, + ...mapped, + // `[plugins."".mcp_servers.] enabled = false` turns the server off in Codex. + ...(isRecord(policy) && policy.enabled === false && { enabled: false }), + _source: createSourceMeta(PROVIDER_ID, map.sourcePath, "user", undefined, plugin.name), + }); + } + } + return { items, warnings }; +} + +registerProvider(skillCapability.id, { + id: PROVIDER_ID, + displayName: DISPLAY_NAME, + description: "Load skills from installed, enabled Codex plugins ($CODEX_HOME/plugins/cache)", + priority: PRIORITY, + load: loadSkills, +}); + +registerProvider(mcpCapability.id, { + id: PROVIDER_ID, + displayName: DISPLAY_NAME, + description: "Load MCP servers from installed, enabled Codex plugins ($CODEX_HOME/plugins/cache)", + priority: PRIORITY, + load: loadMCPServers, +}); diff --git a/packages/coding-agent/src/scient/runtime-info.ts b/packages/coding-agent/src/scient/runtime-info.ts index aa50b84928..efd99f8bb6 100644 --- a/packages/coding-agent/src/scient/runtime-info.ts +++ b/packages/coding-agent/src/scient/runtime-info.ts @@ -24,6 +24,11 @@ export interface RuntimeInfo { * prompt, so a host checks this list instead of guessing from the version. */ hostCommands: string[]; + /** + * Plugin discovery sources a host may name in `SCIENT_AGENT_ENABLE_SOURCES`. An executable + * that does not list a source has no reader for it, so a host checks this list before it offers it. + */ + enableSources: string[]; } export function formatRuntimeInfo(): string { @@ -34,6 +39,7 @@ export function formatRuntimeInfo(): string { rpcProtocolVersions: [1, 2], buildId: BUILD_ID, hostCommands: ["apps", "dictate"], + enableSources: ["claude-plugins", "codex-plugins"], }; return `${JSON.stringify(info)}\n`; } diff --git a/packages/coding-agent/test/scient/codex-plugins.test.ts b/packages/coding-agent/test/scient/codex-plugins.test.ts new file mode 100644 index 0000000000..b557013e17 --- /dev/null +++ b/packages/coding-agent/test/scient/codex-plugins.test.ts @@ -0,0 +1,169 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test"; +import * as fs from "node:fs/promises"; +import * as os from "node:os"; +import * as path from "node:path"; +import { initializeWithSettings, loadCapability } from "@oh-my-pi/pi-coding-agent/capability"; +import { clearCache as clearFsCache } from "@oh-my-pi/pi-coding-agent/capability/fs"; +import type { MCPServer } from "@oh-my-pi/pi-coding-agent/capability/mcp"; +import type { Skill } from "@oh-my-pi/pi-coding-agent/capability/skill"; +import { cfgEnabledProviders } from "@oh-my-pi/pi-coding-agent/config/model-settings"; +import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings"; +import { TempDir } from "@oh-my-pi/pi-utils"; +import { restoreEnvValue } from "../helpers/settings-test-state"; +import "@oh-my-pi/pi-coding-agent/discovery"; + +const ENV_KEYS = ["SCIENT_AGENT_ENABLE_SOURCES", "CODEX_HOME", "CODEX_PLUGIN_TEST_TOKEN", "CODEX_PLUGIN_TEST_PAT"]; + +async function writeSkill(root: string, name: string): Promise { + const skillPath = path.join(root, "skills", name, "SKILL.md"); + await Bun.write(skillPath, `---\nname: ${name}\ndescription: ${name} skill\n---\nUse ${name}.\n`); + return skillPath; +} + +async function writeManifest(root: string, manifest: Record): Promise { + await Bun.write(path.join(root, ".codex-plugin", "plugin.json"), JSON.stringify(manifest)); +} + +describe("installed Codex plugins", () => { + let temp: TempDir; + let settings: Settings; + let release: () => void; + let saved: Record; + let cwd: string; + let agentDir: string; + let researchRoot: string; + let researchSkill: string; + + beforeEach(async () => { + saved = Object.fromEntries(ENV_KEYS.map(key => [key, process.env[key]])); + for (const key of ENV_KEYS) restoreEnvValue(key, undefined); + settings = Settings.isolated(); + release = initializeWithSettings(settings); + temp = TempDir.createSync("@scient-codex-plugins-"); + const home = temp.join("home"); + const codexHome = temp.join("codex-home"); + cwd = temp.join("project"); + agentDir = temp.join("agent"); + await fs.mkdir(cwd, { recursive: true }); + vi.spyOn(os, "homedir").mockReturnValue(home); + restoreEnvValue("CODEX_HOME", codexHome); + restoreEnvValue("CODEX_PLUGIN_TEST_TOKEN", "forwarded-value"); + restoreEnvValue("CODEX_PLUGIN_TEST_PAT", "pat-value"); + + await Bun.write( + path.join(codexHome, "config.toml"), + [ + '[plugins."research@market"]', + "enabled = true", + '[plugins."research@market".mcp_servers.quiet]', + "enabled = false", + '[plugins."paused@market"]', + "enabled = false", + '[plugins."browser@openai-bundled"]', + "enabled = true", + "", + ].join("\n"), + ); + const cache = path.join(codexHome, "plugins", "cache"); + const research = path.join(cache, "market", "research"); + researchRoot = path.join(research, "1.10.0"); + const olderRoot = path.join(research, "1.2.0"); + for (const root of [researchRoot, olderRoot]) { + await writeManifest(root, { + name: "research", + skills: "./skills/", + mcpServers: "./.mcp.json", + apps: "./.app.json", + interface: { displayName: "Research" }, + }); + } + researchSkill = await writeSkill(researchRoot, "lit-review"); + await writeSkill(olderRoot, "stale-review"); + // Codex ignores links in the cache (bundled plugins ship a `latest` link to a version). + await fs.symlink(olderRoot, path.join(research, "latest"), "dir"); + await Bun.write( + path.join(researchRoot, ".mcp.json"), + JSON.stringify({ + mcpServers: { + papers: { + command: "./bin/papers", + args: ["--stdio"], + cwd: ".", + env_vars: ["CODEX_PLUGIN_TEST_TOKEN"], + tool_timeout_sec: 30, + }, + tracker: { + type: "http", + url: "https://mcp.example.test/mcp", + bearer_token_env_var: "CODEX_PLUGIN_TEST_PAT", + }, + quiet: { command: "node", args: ["./quiet.mjs"] }, + messages: { command: "./bin/computer-use-client-launcher", args: ["messages", "mcp"], cwd: "." }, + }, + }), + ); + await Bun.write( + path.join(researchRoot, ".app.json"), + JSON.stringify({ apps: { research: { id: "asdk_app_x" } } }), + ); + + const paused = path.join(cache, "market", "paused", "1.0.0"); + await writeManifest(paused, { name: "paused", skills: "./skills/" }); + await writeSkill(paused, "paused-skill"); + + const browser = path.join(cache, "openai-bundled", "browser", "26.1117.41037"); + await writeManifest(browser, { name: "browser", skills: "./skills/" }); + await writeSkill(browser, "control-in-app-browser"); + clearFsCache(); + }); + + afterEach(() => { + release(); + for (const key of ENV_KEYS) restoreEnvValue(key, saved[key]); + vi.restoreAllMocks(); + clearFsCache(); + temp.removeSync(); + }); + + const skills = async () => + (await loadCapability("skills", { cwd, agentDir })).items.filter( + skill => skill._source.provider === "codex-plugins", + ); + const servers = async () => + (await loadCapability("mcps", { cwd, agentDir })).items.filter( + server => server._source.provider === "codex-plugins", + ); + + it("loads nothing until the host or settings enable codex-plugins", async () => { + cfgEnabledProviders.set(settings, ["codex", "claude"]); + expect(await skills()).toEqual([]); + expect(await servers()).toEqual([]); + }); + + it("loads the active version's skills and MCP servers with package-relative paths", async () => { + restoreEnvValue("SCIENT_AGENT_ENABLE_SOURCES", "codex-plugins"); + + // Only the enabled, installed plugin's highest version: not the disabled plugin, the + // host-only browser plugin, the older version or the `latest` link to it. + expect((await skills()).map(skill => [skill.name, skill.path])).toEqual([["lit-review", researchSkill]]); + + const byName = new Map((await servers()).map(server => [server.name, server])); + // The Computer Use client launcher runs only inside Codex. + expect([...byName.keys()].sort()).toEqual(["research:papers", "research:quiet", "research:tracker"]); + expect(byName.get("research:papers")).toMatchObject({ + command: path.join(researchRoot, "bin", "papers"), + args: ["--stdio"], + cwd: researchRoot, + env: { CODEX_PLUGIN_TEST_TOKEN: "forwarded-value" }, + timeout: 30_000, + transport: "stdio", + }); + expect(byName.get("research:tracker")).toMatchObject({ + url: "https://mcp.example.test/mcp", + headers: { Authorization: "Bearer pat-value" }, + transport: "http", + }); + // The plugin's config table turns this server off, as Codex does. + expect(byName.get("research:quiet")?.enabled).toBe(false); + }); +}); diff --git a/packages/coding-agent/test/scient/runtime-info.test.ts b/packages/coding-agent/test/scient/runtime-info.test.ts index 8a1c6eed9f..112bf4fabc 100644 --- a/packages/coding-agent/test/scient/runtime-info.test.ts +++ b/packages/coding-agent/test/scient/runtime-info.test.ts @@ -16,6 +16,7 @@ describe("--runtime-info", () => { rpcProtocolVersions: [1, 2], buildId: BUILD_ID, hostCommands: ["apps", "dictate"], + enableSources: ["claude-plugins", "codex-plugins"], }); }); }); diff --git a/scripts/scient/divergences.json b/scripts/scient/divergences.json index 49188463ad..1aa35282b7 100644 --- a/scripts/scient/divergences.json +++ b/scripts/scient/divergences.json @@ -69,7 +69,7 @@ }, "SA-PRODUCT": { "status": "active", - "contract": "Scient Agent reports its own release: scient.json names the product, its version and the exact Oh My Pi release; --version, the startup screen, completions and the User-Agent report the version, and --runtime-info reports all of it with the build id Scient's workflow stamps and the Scient commands a host may run (hostCommands).", + "contract": "Scient Agent reports its own release: scient.json names the product, its version and the exact Oh My Pi release; --version, the startup screen, completions and the User-Agent report the version, and --runtime-info reports all of it with the build id Scient's workflow stamps, the Scient commands a host may run (hostCommands) and the plugin sources a host may add with SCIENT_AGENT_ENABLE_SOURCES (enableSources).", "owned": [ "scient.json", "scripts/scient/stamp-build-id.ts", @@ -517,6 +517,23 @@ "verification": [ "bun test packages/coding-agent/test/scient/xdev-catalog.test.ts packages/coding-agent/test/scient/eval-docs.test.ts" ] + }, + "SA-CODEX-PLUGINS": { + "status": "active", + "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex), from the version Codex runs in $CODEX_HOME/plugins/cache/// and its .codex-plugin/plugin.json. MCP fields map as the codex provider maps config.toml (env_vars, bearer_token_env_var, tool_timeout_sec), relative command and cwd resolve inside the package, servers are named :, and a plugin's mcp_servers..enabled = false disables one. OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded.", + "owned": [ + "packages/coding-agent/src/scient/codex-plugins.ts", + "packages/coding-agent/test/scient/codex-plugins.test.ts" + ], + "upstream": [ + "packages/coding-agent/src/capability/index.ts", + "packages/coding-agent/src/discovery/codex.ts", + "packages/coding-agent/src/discovery/index.ts", + "packages/coding-agent/CHANGELOG.md" + ], + "verification": [ + "bun --cwd=packages/coding-agent test test/scient/codex-plugins.test.ts" + ] } } } From 0af9eab8099399b0589b7bf1b487f12020f058a4 Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sun, 22 Nov 2026 02:01:13 +0200 Subject: [PATCH 2/4] fix(codex-plugins): never widen a plugin server's tools; one bad server skips alone - A server whose plugin entry or config.toml policy sets enabled_tools (or a non-empty disabled_tools) is skipped with a warning: Scient Agent cannot enforce Codex's tool filters. - Fields the mapper iterates are validated per server; a malformed server is skipped with a warning and its siblings still load. --- SCIENT.md | 2 +- packages/coding-agent/CHANGELOG.md | 2 +- .../coding-agent/src/scient/codex-plugins.ts | 55 ++++++++++++++-- .../test/scient/codex-plugins.test.ts | 66 +++++++++++++++++++ scripts/scient/divergences.json | 2 +- 5 files changed, 119 insertions(+), 8 deletions(-) diff --git a/SCIENT.md b/SCIENT.md index 07299dd176..fdfb5817b5 100644 --- a/SCIENT.md +++ b/SCIENT.md @@ -15,7 +15,7 @@ Everything else is upstream's code and behavior. | State | The config root is `~/.scient-agent` (project folder `.scient-agent/`), or the absolute directory a host sets in `SCIENT_AGENT_ROOT`. User config lookups, the native addon cache, browser storage state and crash logs follow it. A host's root is authoritative: `SCIENT_AGENT_DIR` is ignored under it, and a `.env` in the project or the home directory cannot set any `SCIENT_AGENT_*` variable (a `.env` inside the root can). The root is taken only from the launch environment, never from a `.env`. Standalone use keeps upstream's `.env` overrides. | | Variables | The variables that choose where state lives have `SCIENT_AGENT_*` names: `CONFIG_DIR`, `CONFIG_FILES`, `DIR`, `PROFILE`, `SESSION_DIR`, `WORKTREE_DIR`, `AUTH_BROKER_*`, `NATIVES_DIR`, the cache database overrides, the directory, TCP address and re-exec hand-over of Oh My Pi's per-user daemon, and the configuration the agent hands its own workers. OMP's names for them are ignored. Tuning variables (`PI_*`) are unchanged. | | Discovery | A host can add foreign user-level sources with `SCIENT_AGENT_ENABLE_SOURCES` (provider ids separated by commas or whitespace). These are unioned with `enabledProviders` for discovery without changing or persisting that setting; `disabledProviders` still wins. The same aliases apply, including `claude` enabling `claude-plugins`. Under a host root, project and home `.env` files cannot add sources. `--runtime-info` lists the plugin sources a host may add (`enableSources`). | -| Codex plugins | The opt-in source `codex-plugins` loads the skills and MCP servers of the Codex plugins a person installed and enabled (`[plugins."@"]` in `$CODEX_HOME/config.toml`, default `~/.codex`), from the version Codex runs in its plugin cache. MCP fields map as the Codex `config.toml` reader maps them, with relative commands and working folders inside the package. Plugins and servers that run only inside OpenAI's apps (browser, Chrome, computer use, the Codex app's tools, the Computer Use client launcher, Codex's ChatGPT session) are left out, and so are app references, which the ChatGPT apps cover. `codex` does not enable it. | +| Codex plugins | The opt-in source `codex-plugins` loads the skills and MCP servers of the Codex plugins a person installed and enabled (`[plugins."@"]` in `$CODEX_HOME/config.toml`, default `~/.codex`), from the version Codex runs in its plugin cache. MCP fields map as the Codex `config.toml` reader maps them, with relative commands and working folders inside the package. A server whose tools Codex narrows (`enabled_tools`, or a non-empty `disabled_tools`, in the plugin or in its `[plugins."".mcp_servers.]` table) is skipped with a warning, because Scient Agent cannot enforce the filter; so is a server with malformed fields, while its siblings load. Plugins and servers that run only inside OpenAI's apps (browser, Chrome, computer use, the Codex app's tools, the Computer Use client launcher, Codex's ChatGPT session) are left out, and so are app references, which the ChatGPT apps cover. `codex` does not enable it. | | Native addon cache | A compiled binary extracts its addons into a directory named for their content, so two builds on one upstream version never load each other's, and it loads only from that directory. A modern addon that fails to load falls back to the same build's baseline addon; an addon found beside the executable is not a fallback. | | Symbol | The sign-in page every browser sign-in ends on and the `stats` dashboard show Scient Agent's symbol (`packages/utils/src/scient/scient-agent-symbol.svg.txt`, the file Scient Desktop shows for the agent; copy it over when the symbol changes) in Scient's colors. | | Shared workers | The tiny model worker, the embedding server and word prediction run in Oh My Pi's per-user daemon. The daemon's build carries Scient Agent's release, not the upstream package version, so a new Scient Agent release has an older release's daemon re-exec into it, which replaces its workers. | diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index 6a9c7f0a6d..0853a714be 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -5,7 +5,7 @@ ### Added -- The skills and MCP servers of the Codex plugins you installed and enabled load when the `codex-plugins` source is on (`enabledProviders`, or a host's `SCIENT_AGENT_ENABLE_SOURCES`). Plugins that only work inside OpenAI's apps are left out. +- The skills and MCP servers of the Codex plugins you installed and enabled load when the `codex-plugins` source is on (`enabledProviders`, or a host's `SCIENT_AGENT_ENABLE_SOURCES`). Plugins that only work inside OpenAI's apps are left out, and so, with a warning, are servers whose tools Codex narrows (`enabled_tools` or `disabled_tools`) and servers with malformed fields. ## [19.0.1] - 2026-11-19 diff --git a/packages/coding-agent/src/scient/codex-plugins.ts b/packages/coding-agent/src/scient/codex-plugins.ts index e60e46f748..8a612cf4d1 100644 --- a/packages/coding-agent/src/scient/codex-plugins.ts +++ b/packages/coding-agent/src/scient/codex-plugins.ts @@ -182,6 +182,33 @@ function hostOnlyReason(server: Record): string | undefined { return undefined; } +/** + * The Codex key that narrows a server's tools, or undefined when it exposes them all. Scient + * Agent's MCP servers carry no tool filter, so such a server would run with more tools than Codex + * allows. An empty denylist narrows nothing. + */ +function toolFilterKey(table: Record): string | undefined { + if (table.enabled_tools != null) return "enabled_tools"; + const denied = table.disabled_tools; + if (denied != null && !(Array.isArray(denied) && denied.length === 0)) return "disabled_tools"; + return undefined; +} + +/** The first field the config.toml mapper would misread, or undefined when its shapes are sound. */ +function malformedField(server: Record): string | undefined { + for (const key of ["args", "env_vars"]) { + const value = server[key]; + if (value != null && !(Array.isArray(value) && value.every(item => typeof item === "string"))) return key; + } + for (const key of ["env", "http_headers", "env_http_headers"]) { + const value = server[key]; + if (value != null && !(isRecord(value) && Object.values(value).every(item => typeof item === "string"))) { + return key; + } + } + return undefined; +} + /** The plugin's server map: the manifest's inline map, its named file, or the package's `.mcp.json`. */ async function readServerMap( plugin: CodexPlugin, @@ -224,19 +251,37 @@ async function loadMCPServers(ctx: LoadContext): Promise> const policies = isRecord(plugin.config.mcp_servers) ? plugin.config.mcp_servers : {}; for (const [serverName, server] of Object.entries(map.servers)) { if (!isRecord(server)) continue; + const skip = `[codex-plugins] Skipping MCP server "${serverName}" of ${plugin.id}`; const reason = hostOnlyReason(server); if (reason !== undefined) { - logger.debug(`[codex-plugins] Skipping MCP server "${serverName}" of ${plugin.id}: ${reason}`); + logger.debug(`${skip}: ${reason}`); + continue; + } + const declaredPolicy = policies[serverName]; + const policy: Record = isRecord(declaredPolicy) ? declaredPolicy : {}; + const filter = toolFilterKey(server) ?? toolFilterKey(policy); + if (filter !== undefined) { + warnings.push(`${skip}: Codex restricts its tools (${filter}), which Scient Agent cannot enforce`); + continue; + } + const malformed = malformedField(server); + if (malformed !== undefined) { + warnings.push(`${skip}: invalid ${malformed} in ${map.sourcePath}`); + continue; + } + let mapped: Partial | undefined; + try { + // Codex resolves a relative cwd, and a relative command from that cwd, against the package. + mapped = extractMCPServersFromToml({ mcp_servers: { [serverName]: server } }, plugin.root)[serverName]; + } catch (error) { + warnings.push(`${skip}: ${String(error)}`); continue; } - // Codex resolves a relative cwd, and a relative command from that cwd, against the package. - const mapped = extractMCPServersFromToml({ mcp_servers: { [serverName]: server } }, plugin.root)[serverName]; - const policy = policies[serverName]; items.push({ name: `${plugin.name}:${serverName}`, ...mapped, // `[plugins."".mcp_servers.] enabled = false` turns the server off in Codex. - ...(isRecord(policy) && policy.enabled === false && { enabled: false }), + ...(policy.enabled === false && { enabled: false }), _source: createSourceMeta(PROVIDER_ID, map.sourcePath, "user", undefined, plugin.name), }); } diff --git a/packages/coding-agent/test/scient/codex-plugins.test.ts b/packages/coding-agent/test/scient/codex-plugins.test.ts index b557013e17..629f2d164d 100644 --- a/packages/coding-agent/test/scient/codex-plugins.test.ts +++ b/packages/coding-agent/test/scient/codex-plugins.test.ts @@ -166,4 +166,70 @@ describe("installed Codex plugins", () => { // The plugin's config table turns this server off, as Codex does. expect(byName.get("research:quiet")?.enabled).toBe(false); }); + + /** + * Installs and enables `limits@market` with these servers and config.toml lines after its table; + * returns its `.mcp.json`. + */ + async function installLimits(mcpServers: Record, policy: string[] = []): Promise { + const codexHome = temp.join("codex-home"); + const configPath = path.join(codexHome, "config.toml"); + const config = await Bun.file(configPath).text(); + await Bun.write(configPath, [config, '[plugins."limits@market"]', "enabled = true", ...policy, ""].join("\n")); + const root = path.join(codexHome, "plugins", "cache", "market", "limits", "1.0.0"); + await writeManifest(root, { name: "limits" }); + const mcpPath = path.join(root, ".mcp.json"); + await Bun.write(mcpPath, JSON.stringify({ mcpServers })); + clearFsCache(); + restoreEnvValue("SCIENT_AGENT_ENABLE_SOURCES", "codex-plugins"); + return mcpPath; + } + const limits = async () => { + const result = await loadCapability("mcps", { cwd, agentDir }); + return { + names: result.items.filter(server => server.name.startsWith("limits:")).map(server => server.name), + warnings: result.warnings.filter(warning => warning.includes("of limits@market")), + }; + }; + + it("skips a plugin's server whose tools Codex narrows with enabled_tools", async () => { + await installLimits({ + narrow: { command: "node", args: ["narrow.mjs"], enabled_tools: ["search"] }, + open: { command: "node", args: ["open.mjs"], disabled_tools: [] }, + }); + expect(await limits()).toEqual({ + names: ["limits:open"], + warnings: [ + '[Codex Plugins] [codex-plugins] Skipping MCP server "narrow" of limits@market: Codex restricts its tools (enabled_tools), which Scient Agent cannot enforce', + ], + }); + }); + + it("skips a server whose config.toml policy narrows its tools with disabled_tools", async () => { + await installLimits( + { denied: { command: "node", args: ["denied.mjs"] }, open: { command: "node", args: ["open.mjs"] } }, + ['[plugins."limits@market".mcp_servers.denied]', 'disabled_tools = ["delete"]'], + ); + expect(await limits()).toEqual({ + names: ["limits:open"], + warnings: [ + '[Codex Plugins] [codex-plugins] Skipping MCP server "denied" of limits@market: Codex restricts its tools (disabled_tools), which Scient Agent cannot enforce', + ], + }); + }); + + it("skips a malformed server and keeps its siblings", async () => { + const mcpPath = await installLimits({ + bad: { command: "node", env_vars: "CODEX_PLUGIN_TEST_TOKEN" }, + headers: { url: "https://mcp.example.test/mcp", http_headers: ["X-Bad"] }, + open: { command: "node", args: ["open.mjs"] }, + }); + expect(await limits()).toEqual({ + names: ["limits:open"], + warnings: [ + `[Codex Plugins] [codex-plugins] Skipping MCP server "bad" of limits@market: invalid env_vars in ${mcpPath}`, + `[Codex Plugins] [codex-plugins] Skipping MCP server "headers" of limits@market: invalid http_headers in ${mcpPath}`, + ], + }); + }); }); diff --git a/scripts/scient/divergences.json b/scripts/scient/divergences.json index 1aa35282b7..c03e17c514 100644 --- a/scripts/scient/divergences.json +++ b/scripts/scient/divergences.json @@ -520,7 +520,7 @@ }, "SA-CODEX-PLUGINS": { "status": "active", - "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex), from the version Codex runs in $CODEX_HOME/plugins/cache/// and its .codex-plugin/plugin.json. MCP fields map as the codex provider maps config.toml (env_vars, bearer_token_env_var, tool_timeout_sec), relative command and cwd resolve inside the package, servers are named :, and a plugin's mcp_servers..enabled = false disables one. OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded.", + "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex), from the version Codex runs in $CODEX_HOME/plugins/cache/// and its .codex-plugin/plugin.json. MCP fields map as the codex provider maps config.toml (env_vars, bearer_token_env_var, tool_timeout_sec), relative command and cwd resolve inside the package, servers are named :, and a plugin's mcp_servers..enabled = false disables one. A server whose plugin definition or mcp_servers. policy sets enabled_tools or a non-empty disabled_tools is skipped with a warning, since Scient Agent's MCP servers carry no tool filter, and a server with a malformed args, env_vars, env, http_headers or env_http_headers is skipped with a warning while its siblings load. OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded.", "owned": [ "packages/coding-agent/src/scient/codex-plugins.ts", "packages/coding-agent/test/scient/codex-plugins.test.ts" From 4d90a4861420a2fbe7d723b765a5059b799d114e Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sun, 22 Nov 2026 09:52:27 +0200 Subject: [PATCH 3/4] fix(codex-plugins): load Codex plugins under Codex's own trust rules Codex review of 0af9eab809: - CODEX_HOME and header credentials come from the launch environment, never a project's .env. - Stdio servers inherit only Codex's variable list plus their env_vars (MCPServer.envInherit), not the agent's whole environment; env values are literal, headers literal and origin-locked. - [plugins._default] and /etc/codex/config.toml apply; nothing loads under an organization policy. - Package files, cwd and relative commands must stay inside the symlink-resolved package. - One transport per server with only its Codex fields; OAuth client settings, scopes and oauth_resource map; http_headers_helper and auth other than oauth are skipped. - Same-named plugins from two marketplaces are named .. - Codex's manifest precedence: root Agent Plugins plugin.json, then .codex-, .claude-, .cursor-plugin. - The plugin mapper no longer borrows the codex provider's config.toml mapper. --- SCIENT.md | 2 +- packages/coding-agent/CHANGELOG.md | 2 +- packages/coding-agent/src/capability/mcp.ts | 7 + packages/coding-agent/src/discovery/codex.ts | 3 - packages/coding-agent/src/mcp/config.ts | 3 + .../coding-agent/src/mcp/transports/stdio.ts | 7 +- packages/coding-agent/src/mcp/types.ts | 4 + .../coding-agent/src/scient/codex-plugins.ts | 513 ++++++++++++++---- .../test/scient/codex-plugins.test.ts | 237 +++++++- scripts/scient/divergences.json | 7 +- 10 files changed, 679 insertions(+), 106 deletions(-) diff --git a/SCIENT.md b/SCIENT.md index fdfb5817b5..f19dd7a614 100644 --- a/SCIENT.md +++ b/SCIENT.md @@ -15,7 +15,7 @@ Everything else is upstream's code and behavior. | State | The config root is `~/.scient-agent` (project folder `.scient-agent/`), or the absolute directory a host sets in `SCIENT_AGENT_ROOT`. User config lookups, the native addon cache, browser storage state and crash logs follow it. A host's root is authoritative: `SCIENT_AGENT_DIR` is ignored under it, and a `.env` in the project or the home directory cannot set any `SCIENT_AGENT_*` variable (a `.env` inside the root can). The root is taken only from the launch environment, never from a `.env`. Standalone use keeps upstream's `.env` overrides. | | Variables | The variables that choose where state lives have `SCIENT_AGENT_*` names: `CONFIG_DIR`, `CONFIG_FILES`, `DIR`, `PROFILE`, `SESSION_DIR`, `WORKTREE_DIR`, `AUTH_BROKER_*`, `NATIVES_DIR`, the cache database overrides, the directory, TCP address and re-exec hand-over of Oh My Pi's per-user daemon, and the configuration the agent hands its own workers. OMP's names for them are ignored. Tuning variables (`PI_*`) are unchanged. | | Discovery | A host can add foreign user-level sources with `SCIENT_AGENT_ENABLE_SOURCES` (provider ids separated by commas or whitespace). These are unioned with `enabledProviders` for discovery without changing or persisting that setting; `disabledProviders` still wins. The same aliases apply, including `claude` enabling `claude-plugins`. Under a host root, project and home `.env` files cannot add sources. `--runtime-info` lists the plugin sources a host may add (`enableSources`). | -| Codex plugins | The opt-in source `codex-plugins` loads the skills and MCP servers of the Codex plugins a person installed and enabled (`[plugins."@"]` in `$CODEX_HOME/config.toml`, default `~/.codex`), from the version Codex runs in its plugin cache. MCP fields map as the Codex `config.toml` reader maps them, with relative commands and working folders inside the package. A server whose tools Codex narrows (`enabled_tools`, or a non-empty `disabled_tools`, in the plugin or in its `[plugins."".mcp_servers.]` table) is skipped with a warning, because Scient Agent cannot enforce the filter; so is a server with malformed fields, while its siblings load. Plugins and servers that run only inside OpenAI's apps (browser, Chrome, computer use, the Codex app's tools, the Computer Use client launcher, Codex's ChatGPT session) are left out, and so are app references, which the ChatGPT apps cover. `codex` does not enable it. | +| Codex plugins | The opt-in source `codex-plugins` loads the skills and MCP servers of the Codex plugins a person installed and enabled (`[plugins."@"]` in `$CODEX_HOME/config.toml`, default `~/.codex`, or `[plugins._default]`), from the version Codex runs in its plugin cache, under Codex's own rules: its manifest precedence (a root Agent Plugins `plugin.json`, then `.codex-plugin`, `.claude-plugin`, `.cursor-plugin`), one transport per server with only that transport's fields, package files and launch paths inside the package, a stdio server inheriting only the variables Codex passes (`HOME`, `PATH` and the like, plus its `env_vars`), and plugin values taken literally. `CODEX_HOME` and header credentials come from the launch environment, never a project's `.env`. A server whose tools Codex narrows (`enabled_tools`, or a non-empty `disabled_tools`) is skipped with a warning, because Scient Agent cannot enforce the filter; so is a server with malformed or unsupported fields, while its siblings load. Nothing loads while an organization policy manages Codex. Plugins and servers that run only inside OpenAI's apps (browser, Chrome, computer use, the Codex app's tools, the Computer Use client launcher, Codex's ChatGPT session) are left out, and so are app references, which the ChatGPT apps cover. `codex` does not enable it. | | Native addon cache | A compiled binary extracts its addons into a directory named for their content, so two builds on one upstream version never load each other's, and it loads only from that directory. A modern addon that fails to load falls back to the same build's baseline addon; an addon found beside the executable is not a fallback. | | Symbol | The sign-in page every browser sign-in ends on and the `stats` dashboard show Scient Agent's symbol (`packages/utils/src/scient/scient-agent-symbol.svg.txt`, the file Scient Desktop shows for the agent; copy it over when the symbol changes) in Scient's colors. | | Shared workers | The tiny model worker, the embedding server and word prediction run in Oh My Pi's per-user daemon. The daemon's build carries Scient Agent's release, not the upstream package version, so a new Scient Agent release has an older release's daemon re-exec into it, which replaces its workers. | diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index 0853a714be..a621a19345 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -5,7 +5,7 @@ ### Added -- The skills and MCP servers of the Codex plugins you installed and enabled load when the `codex-plugins` source is on (`enabledProviders`, or a host's `SCIENT_AGENT_ENABLE_SOURCES`). Plugins that only work inside OpenAI's apps are left out, and so, with a warning, are servers whose tools Codex narrows (`enabled_tools` or `disabled_tools`) and servers with malformed fields. +- The skills and MCP servers of the Codex plugins you installed and enabled load when the `codex-plugins` source is on (`enabledProviders`, or a host's `SCIENT_AGENT_ENABLE_SOURCES`), under Codex's own rules: only the plugins Codex would run (`[plugins._default]` and its manifest formats included), servers that inherit only the variables Codex would pass them, plugin values taken literally, and package paths kept inside the package. Plugins that only work inside OpenAI's apps are left out, and so, with a warning, are servers whose tools Codex narrows (`enabled_tools` or `disabled_tools`) and servers with malformed or unsupported fields. Nothing loads while an organization policy manages Codex. ## [19.0.1] - 2026-11-19 diff --git a/packages/coding-agent/src/capability/mcp.ts b/packages/coding-agent/src/capability/mcp.ts index 4b12e9293a..2a0528860a 100644 --- a/packages/coding-agent/src/capability/mcp.ts +++ b/packages/coding-agent/src/capability/mcp.ts @@ -36,6 +36,10 @@ export interface MCPServer { envPolicy?: "literal"; /** Env keys whose values are final package data (expanded by the provider). */ envLiteralKeys?: string[]; + // scient(SA-CODEX-PLUGINS): begin - A Codex plugin's server inherits only what Codex passes it. + /** When set, the stdio server inherits only these variables from the agent's environment, plus its own `env`. */ + envInherit?: string[]; + // scient(SA-CODEX-PLUGINS): end /** Working directory for stdio transport */ cwd?: string; /** URL (for HTTP/SSE transport) */ @@ -98,6 +102,9 @@ export function isSameMCPConnection(left: MCPServer, right: MCPServer): boolean Bun.deepEquals(left.args, right.args) && Bun.deepEquals(left.env, right.env) && Bun.deepEquals(literalKeysOf(left), literalKeysOf(right)) && + // scient(SA-CODEX-PLUGINS): begin - Inheritance decides what the process sees. + Bun.deepEquals(left.envInherit, right.envInherit) && + // scient(SA-CODEX-PLUGINS): end left.cwd === right.cwd ); } diff --git a/packages/coding-agent/src/discovery/codex.ts b/packages/coding-agent/src/discovery/codex.ts index 0ff1cf51ef..646c5863b2 100644 --- a/packages/coding-agent/src/discovery/codex.ts +++ b/packages/coding-agent/src/discovery/codex.ts @@ -256,9 +256,6 @@ function extractMCPServersFromToml( return result; } -// scient(SA-CODEX-PLUGINS): begin - Installed Codex plugins map their MCP servers as Codex's config.toml does. -export { extractMCPServersFromToml }; -// scient(SA-CODEX-PLUGINS): end // ============================================================================= // Skills (skills/) diff --git a/packages/coding-agent/src/mcp/config.ts b/packages/coding-agent/src/mcp/config.ts index f8224fe4c7..fe82b2d84d 100644 --- a/packages/coding-agent/src/mcp/config.ts +++ b/packages/coding-agent/src/mcp/config.ts @@ -67,6 +67,9 @@ function convertToLegacyConfig(server: MCPServer): MCPServerConfig { if (server.env) config.env = server.env; if (server.envPolicy) config.envPolicy = server.envPolicy; if (server.envLiteralKeys) config.envLiteralKeys = server.envLiteralKeys; + // scient(SA-CODEX-PLUGINS): begin - A Codex plugin's server inherits only what Codex passes it. + if (server.envInherit) config.envInherit = server.envInherit; + // scient(SA-CODEX-PLUGINS): end if (server.cwd) config.cwd = server.cwd; return config; } diff --git a/packages/coding-agent/src/mcp/transports/stdio.ts b/packages/coding-agent/src/mcp/transports/stdio.ts index b96a905696..7c06fe7686 100644 --- a/packages/coding-agent/src/mcp/transports/stdio.ts +++ b/packages/coding-agent/src/mcp/transports/stdio.ts @@ -592,10 +592,15 @@ export class StdioTransport implements MCPTransport { signal?.throwIfAborted(); if (this.#connected) return; + // scient(SA-CODEX-PLUGINS): begin - A Codex plugin's server inherits only what Codex passes it. + const inherited: Record = this.config.envInherit + ? Object.fromEntries(this.config.envInherit.map(name => [name, Bun.env[name]]).filter(([, value]) => value)) + : Bun.env; const env = { - ...Bun.env, + ...inherited, ...this.config.env, }; + // scient(SA-CODEX-PLUGINS): end const cwd = this.config.cwd ?? getProjectDir(); const spawnCommand = await resolveStdioSpawnCommand(this.config, { cwd, diff --git a/packages/coding-agent/src/mcp/types.ts b/packages/coding-agent/src/mcp/types.ts index 8252c3a9f3..ab2825fae3 100644 --- a/packages/coding-agent/src/mcp/types.ts +++ b/packages/coding-agent/src/mcp/types.ts @@ -124,6 +124,10 @@ export interface MCPStdioServerConfig extends MCPServerConfigBase { envPolicy?: "literal"; /** Env keys whose values are final package data; auth resolution keeps them verbatim. */ envLiteralKeys?: string[]; + // scient(SA-CODEX-PLUGINS): begin - A Codex plugin's server inherits only what Codex passes it. + /** When set, only these variables are inherited from the agent's environment; `env` still applies on top. */ + envInherit?: string[]; + // scient(SA-CODEX-PLUGINS): end cwd?: string; } diff --git a/packages/coding-agent/src/scient/codex-plugins.ts b/packages/coding-agent/src/scient/codex-plugins.ts index 8a612cf4d1..3cb6e2fa74 100644 --- a/packages/coding-agent/src/scient/codex-plugins.ts +++ b/packages/coding-agent/src/scient/codex-plugins.ts @@ -2,21 +2,27 @@ * Installed Codex plugins (SA-CODEX-PLUGINS). * * Codex lists plugins in `$CODEX_HOME/config.toml` (default `~/.codex`) as - * `[plugins."@"]`, enabled unless the table says `enabled = false`, and runs - * each from the active version of `$CODEX_HOME/plugins/cache////`, - * described by `.codex-plugin/plugin.json`. Their skills and MCP servers load here, MCP fields - * mapped as the Codex config.toml reader maps them. App references (`.app.json`) do not: a - * person's ChatGPT apps reach the agent through the ChatGPT sign-in (SA-CHATGPT-APPS). Plugins - * and servers that run only inside OpenAI's own apps are left out. + * `[plugins."@"]`, enabled unless the table, or else `[plugins._default]`, + * says `enabled = false`, and runs each from the active version of + * `$CODEX_HOME/plugins/cache////`. Their skills and MCP servers load + * here under Codex's own rules: its manifest precedence, its MCP field validation, and the + * environment and header handling it gives a plugin's servers. App references (`.app.json`) do + * not: a person's ChatGPT apps reach the agent through the ChatGPT sign-in (SA-CHATGPT-APPS). + * Plugins and servers that run only inside OpenAI's own apps are left out, and so is everything + * when an organization manages Codex, since its policy cannot be read here. */ +import type { Dirent, Stats } from "node:fs"; +import * as fs from "node:fs/promises"; +import * as os from "node:os"; import * as path from "node:path"; -import { $env, isRecord, logger } from "@oh-my-pi/pi-utils"; +import { filterChildShellEnv, getPluginsDir, isRecord, logger } from "@oh-my-pi/pi-utils"; import { isUserSourceEnabled, registerProvider } from "../capability"; import { readDirEntries, readFile } from "../capability/fs"; import { type MCPServer, mcpCapability } from "../capability/mcp"; import { type Skill, skillCapability } from "../capability/skill"; import type { LoadContext, LoadResult } from "../capability/types"; -import { extractMCPServersFromToml } from "../discovery/codex"; +import { classifyAgentPluginRoot, parseAgentPluginMcp } from "../discovery/agent-plugin-format"; +import { isContainedResolved, realpathIfExists, resolveContainedPath } from "../discovery/contained-path"; import { createSourceMeta, scanSkillsFromDir } from "../discovery/helpers"; const PROVIDER_ID = "codex-plugins"; @@ -27,6 +33,12 @@ const PRIORITY = 65; /** The folder of a plugin Codex links from its source while it is developed; it wins over versions. */ const LOCAL_VERSION = "local"; +/** + * Codex's legacy manifests, in its order of precedence after a root Agent Plugins `plugin.json`. + * The first one present decides; a link or non-file there stops the search, as in Codex. + */ +const LEGACY_MANIFESTS = [".codex-plugin/plugin.json", ".claude-plugin/plugin.json", ".cursor-plugin/plugin.json"]; + /** * Bundled plugins that drive OpenAI's apps (the in-app browser, the Chrome extension host, * computer use, the Codex app's own threads) through services only those apps provide. Their @@ -43,22 +55,107 @@ const HOST_PLUGINS: Record = { /** OpenAI's launcher for its signed Computer Use client, which serves only Codex (the Messages plugin). */ const HOST_LAUNCHER = "computer-use-client-launcher"; +/** + * The variables Codex passes a plugin's local stdio server from its own environment, besides + * those the server names in `env_vars` (codex-rs/rmcp-client `DEFAULT_ENV_VARS`, and + * `WINDOWS_CORE_ENV_VARS` on Windows), plus the certificate-bundle variables it always keeps + * (`CUSTOM_CA_ENV_KEYS`). Nothing else, API keys included, reaches the server. + */ +const INHERITED_ENV = + process.platform === "win32" + ? [ + "PATH", + "PATHEXT", + "SHELL", + "COMSPEC", + "SYSTEMROOT", + "WINDIR", + "SYSTEMDRIVE", + "USERNAME", + "USERDOMAIN", + "USERPROFILE", + "HOMEDRIVE", + "HOMEPATH", + "PROGRAMFILES", + "PROGRAMFILES(X86)", + "PROGRAMW6432", + "PROGRAMDATA", + "LOCALAPPDATA", + "APPDATA", + "TEMP", + "TMP", + "TMPDIR", + "POWERSHELL", + "PWSH", + ] + : [ + "HOME", + "LOGNAME", + "PATH", + "SHELL", + "USER", + "__CF_USER_TEXT_ENCODING", + "LANG", + "LC_ALL", + "TERM", + "TMPDIR", + "TZ", + ]; +const CA_BUNDLE_ENV = [ + "CODEX_CA_CERTIFICATE", + "SSL_CERT_FILE", + "REQUESTS_CA_BUNDLE", + "CURL_CA_BUNDLE", + "NODE_EXTRA_CA_CERTS", + "GIT_SSL_CAINFO", + "CARGO_HTTP_CAINFO", + "PIP_CERT", + "BUNDLE_SSL_CA_CERT", + "npm_config_cafile", + "NPM_CONFIG_CAFILE", +]; + +/** Fields Codex rejects on a stdio server, and on a streamable HTTP server. */ +const NOT_STDIO = [ + "url", + "bearer_token_env_var", + "bearer_token", + "http_headers_helper", + "http_headers", + "env_http_headers", + "oauth", + "oauth_resource", + "auth", +]; +const NOT_HTTP = ["args", "env", "env_vars", "cwd", "bearer_token"]; + const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/; interface CodexPlugin { /** `@`, the plugin's key in config.toml. */ id: string; - /** Plugin name: skill namespace and MCP server prefix. */ name: string; - /** The active version's folder; package-relative paths resolve against it. */ + marketplace: string; + /** Skill namespace and MCP server prefix: the name, or `.` when two enabled plugins share it. */ + label: string; + /** The active version's folder, symlinks resolved; every package path stays inside it. */ root: string; + /** `standard`: a root Agent Plugins `plugin.json`, read under that standard; `legacy`: a Codex-style manifest. */ + format: "standard" | "legacy"; manifestPath: string; manifest: Record; /** The plugin's `[plugins.""]` table. */ config: Record; } +interface PluginList { + plugins: CodexPlugin[]; + warnings: string[]; + /** Scient Agent's launch environment, without a project's `.env` values. */ + env: Record; +} + /** Codex's rule for a cache path segment (plugin, marketplace or version name). */ function isPathSegment(value: string): boolean { return value !== "." && value !== ".." && /^[A-Za-z0-9._+-]+$/.test(value); @@ -76,18 +173,54 @@ function compareVersions(a: string, b: string): number { /** The version folder Codex runs: `local` while present, else the highest version; null when not installed. */ async function activeVersion(base: string): Promise { const versions = (await readDirEntries(base)) - .filter(entry => entry.isDirectory() && isPathSegment(entry.name)) + .filter((entry: Dirent) => entry.isDirectory() && isPathSegment(entry.name)) .map(entry => entry.name); if (versions.includes(LOCAL_VERSION)) return LOCAL_VERSION; return versions.sort(compareVersions).at(-1) ?? null; } +async function lstatOrNull(file: string): Promise { + try { + return await fs.lstat(file); + } catch { + return null; + } +} + +/** The first legacy manifest present, read; null (with a warning) when none is usable. */ +async function readLegacyManifest( + root: string, + id: string, + warnings: string[], +): Promise<{ manifestPath: string; manifest: Record } | null> { + for (const relative of LEGACY_MANIFESTS) { + const manifestPath = path.join(root, relative); + const stat = await lstatOrNull(manifestPath); + if (stat === null) continue; + if (!stat.isFile()) { + warnings.push(`[codex-plugins] Ignoring ${id}: ${relative} is not a regular file`); + return null; + } + let manifest: unknown = null; + try { + manifest = JSON.parse((await readFile(manifestPath)) ?? ""); + } catch {} + if (!isRecord(manifest)) { + warnings.push(`[codex-plugins] Invalid plugin.json for ${id}: ${manifestPath}`); + return null; + } + return { manifestPath, manifest }; + } + warnings.push(`[codex-plugins] No plugin.json for ${id} in ${root}`); + return null; +} + async function readPlugin( home: string, id: string, config: Record, warnings: string[], -): Promise { +): Promise | null> { const at = id.lastIndexOf("@"); const name = id.slice(0, at); const marketplace = id.slice(at + 1); @@ -99,72 +232,145 @@ async function readPlugin( const version = await activeVersion(base); // Listed but not installed (or removed since): Codex skips it as well. if (version === null) return null; - const root = path.join(base, version); - const manifestPath = path.join(root, ".codex-plugin", "plugin.json"); - const raw = await readFile(manifestPath); - let manifest: unknown = null; + const root = await realpathIfExists(path.join(base, version)); + if (root === null) return null; + // A root `plugin.json` that targets Agent Plugins wins; one that does not leaves the legacy manifests. + const rootManifest = path.join(root, "plugin.json"); + const rootStat = await lstatOrNull(rootManifest); + if (rootStat !== null && !rootStat.isFile()) { + warnings.push(`[codex-plugins] Ignoring ${id}: plugin.json is not a regular file`); + return null; + } + const standard = await classifyAgentPluginRoot(root); + if (standard.kind === "invalid") { + warnings.push(`[codex-plugins] Ignoring ${id}: ${standard.reason}`); + return null; + } + if (standard.kind === "standard") { + warnings.push(...standard.warnings.map(warning => `[codex-plugins] ${id}: ${warning}`)); + return { + id, + name, + marketplace, + root, + format: "standard", + manifestPath: rootManifest, + manifest: { ...standard.manifest }, + config, + }; + } + const legacy = await readLegacyManifest(root, id, warnings); + if (legacy === null) return null; + return { id, name, marketplace, root, format: "legacy", ...legacy, config }; +} + +async function readToml(file: string, warnings: string[]): Promise | null> { + const raw = await readFile(file); + if (raw === null) return null; try { - manifest = raw === null ? null : JSON.parse(raw); - } catch {} - if (!isRecord(manifest)) { - warnings.push(`[codex-plugins] Missing or invalid plugin.json for ${id}: ${manifestPath}`); + const parsed = Bun.TOML.parse(raw); + return isRecord(parsed) ? parsed : null; + } catch (error) { + warnings.push(`[codex-plugins] Invalid TOML in ${file}: ${String(error)}`); return null; } - return { id, name, root, manifestPath, manifest, config }; +} + +/** + * Where an organization's Codex policy lives (requirements, managed config, macOS managed + * preferences). Codex enforces them over the user's config; Scient Agent cannot, so it loads no + * plugins while one is present. + */ +function managedPolicyFiles(): string[] { + if (process.platform === "win32") { + const programData = process.env.ProgramData || "C:\\ProgramData"; + return [path.join(programData, "OpenAI", "Codex", "requirements.toml")]; + } + const files = ["/etc/codex/requirements.toml", "/etc/codex/managed_config.toml"]; + if (process.platform === "darwin") { + const managed = "/Library/Managed Preferences"; + files.push( + path.join(managed, "com.openai.codex.plist"), + path.join(managed, os.userInfo().username, "com.openai.codex.plist"), + ); + } + return files; } /** Installed, enabled Codex plugins outside {@link HOST_PLUGINS}. */ -async function listCodexPlugins(ctx: LoadContext): Promise<{ plugins: CodexPlugin[]; warnings: string[] }> { +async function listCodexPlugins(ctx: LoadContext): Promise { const warnings: string[] = []; - // Codex's home: `CODEX_HOME`, else `~/.codex`. - const home = $env.CODEX_HOME?.trim() || path.join(ctx.home, ".codex"); - const configPath = path.join(home, "config.toml"); - const raw = await readFile(configPath); - if (raw === null) return { plugins: [], warnings }; - let toml: unknown; - try { - toml = Bun.TOML.parse(raw); - } catch (error) { - warnings.push(`[codex-plugins] Invalid TOML in ${configPath}: ${String(error)}`); - return { plugins: [], warnings }; + // The environment Scient Agent was launched with: a project's `.env` never chooses Codex's + // home or the credentials sent to a plugin's server. + const env = filterChildShellEnv(Bun.env); + for (const file of managedPolicyFiles()) { + if ((await lstatOrNull(file)) === null) continue; + warnings.push( + `[codex-plugins] Codex is managed by an organization policy (${file}), which Scient Agent cannot apply; no Codex plugins load`, + ); + return { plugins: [], warnings, env }; } - const table = isRecord(toml) && isRecord(toml.plugins) ? toml.plugins : {}; - const plugins = await Promise.all( + // Codex's home: `CODEX_HOME`, else `~/.codex`. + const home = env.CODEX_HOME?.trim() || path.join(ctx.home, ".codex"); + const user = await readToml(path.join(home, "config.toml"), warnings); + if (user === null) return { plugins: [], warnings, env }; + // The system layer sits under the user's; per-plugin tables and `_default` merge by key. + const system = process.platform === "win32" ? null : await readToml("/etc/codex/config.toml", warnings); + const table: Record = { + ...(isRecord(system?.plugins) ? system.plugins : {}), + ...(isRecord(user.plugins) ? user.plugins : {}), + }; + const defaults = isRecord(table._default) ? table._default : {}; + const enabledByDefault = defaults.enabled !== false; + const read = await Promise.all( Object.entries(table).map(([id, config]) => { - if (!isRecord(config) || config.enabled === false || HOST_PLUGINS[id] === true) return null; - return readPlugin(home, id, config, warnings); + if (id === "_default" || !isRecord(config) || HOST_PLUGINS[id] === true) return null; + const enabled = typeof config.enabled === "boolean" ? config.enabled : enabledByDefault; + return enabled ? readPlugin(home, id, config, warnings) : null; }), ); - return { plugins: plugins.filter(plugin => plugin !== null), warnings }; + const found = read.filter(plugin => plugin !== null); + const sharedNames = new Set( + found.filter((plugin, index) => found.findIndex(other => other.name === plugin.name) !== index).map(p => p.name), + ); + const plugins = found.map(plugin => ({ + ...plugin, + label: sharedNames.has(plugin.name) ? `${plugin.name}.${plugin.marketplace}` : plugin.name, + })); + return { plugins, warnings, env }; } -/** A manifest path inside the package, or null (with a warning when it points outside). */ -function packagePath(plugin: CodexPlugin, value: unknown, key: string, warnings: string[]): string | null { +/** A manifest path inside the package, symlinks resolved; null (with a warning when it points outside). */ +async function packagePath(plugin: CodexPlugin, value: unknown, key: string, warnings: string[]) { if (typeof value !== "string" || !value.trim()) return null; - const resolved = path.resolve(plugin.root, value.trim()); - const relative = path.relative(plugin.root, resolved); - if (relative.startsWith("..") || path.isAbsolute(relative)) { + const resolved = await resolveContainedPath(plugin.root, path.resolve(plugin.root, value.trim())); + if (resolved.status === "outside") { warnings.push(`[codex-plugins] Ignoring ${key} path outside ${plugin.id}: ${value}`); return null; } - return resolved; + return resolved.status === "ok" ? resolved.realPath : null; } async function loadSkills(ctx: LoadContext): Promise> { if (!isUserSourceEnabled(PROVIDER_ID, ctx)) return { items: [] }; const { plugins, warnings } = await listCodexPlugins(ctx); - const scans = plugins.flatMap(plugin => { - const declared = plugin.manifest.skills; - const entries = declared == null ? ["skills"] : Array.isArray(declared) ? declared : [declared]; - const dirs = new Set(); - for (const entry of entries) { - const dir = packagePath(plugin, entry, "skills", warnings); - if (dir !== null) dirs.add(dir); - } - return [...dirs].map(dir => - scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user", pluginName: plugin.name }), - ); - }); + const dirsByPlugin = await Promise.all( + plugins.map(async plugin => { + const declared = plugin.format === "standard" ? undefined : plugin.manifest.skills; + const entries = declared == null ? ["skills"] : Array.isArray(declared) ? declared : [declared]; + const dirs = new Set(); + for (const entry of entries) { + const dir = await packagePath(plugin, entry, "skills", warnings); + if (dir !== null) dirs.add(dir); + } + return { plugin, dirs: [...dirs] }; + }), + ); + const scans = dirsByPlugin.flatMap(({ plugin, dirs }) => + dirs.map(dir => + scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user", pluginName: plugin.label }), + ), + ); const items: Skill[] = []; for (const result of await Promise.all(scans)) { items.push(...result.items); @@ -194,23 +400,119 @@ function toolFilterKey(table: Record): string | undefined { return undefined; } -/** The first field the config.toml mapper would misread, or undefined when its shapes are sound. */ -function malformedField(server: Record): string | undefined { - for (const key of ["args", "env_vars"]) { - const value = server[key]; - if (value != null && !(Array.isArray(value) && value.every(item => typeof item === "string"))) return key; - } - for (const key of ["env", "http_headers", "env_http_headers"]) { - const value = server[key]; - if (value != null && !(isRecord(value) && Object.values(value).every(item => typeof item === "string"))) { - return key; +const isStringList = (value: unknown): value is string[] => + Array.isArray(value) && value.every(item => typeof item === "string"); +const isStringMap = (value: unknown): value is Record => + isRecord(value) && Object.values(value).every(item => typeof item === "string"); + +/** Codex's `env_vars` entry: a name, or `{ name, source = "local" }`. */ +function envVarName(entry: unknown): string | undefined { + if (typeof entry === "string") return entry; + if (isRecord(entry) && typeof entry.name === "string" && (entry.source ?? "local") === "local") return entry.name; + return undefined; +} + +type Mapped = { server: Partial } | { error: string }; + +/** + * A legacy plugin's server as Codex reads it: exactly one transport with its own fields, package + * paths kept inside the package, values taken literally, and only Codex's variables inherited. + */ +async function mapLegacyServer( + plugin: CodexPlugin, + server: Record, + env: Record, +): Promise { + const isStdio = typeof server.command === "string"; + if (!isStdio && typeof server.url !== "string") return { error: "it declares neither command nor url" }; + const wrong = (isStdio ? NOT_STDIO : NOT_HTTP).find(key => server[key] != null); + if (wrong !== undefined) return { error: `${wrong} is not supported for ${isStdio ? "stdio" : "streamable HTTP"}` }; + const timeout = + typeof server.tool_timeout_sec === "number" && server.tool_timeout_sec > 0 + ? { timeout: server.tool_timeout_sec * 1000 } + : {}; + + if (isStdio) { + const command = (server.command as string).trim(); + if (!command) return { error: "command is empty" }; + if (server.args != null && !isStringList(server.args)) return { error: "invalid args" }; + if (server.env != null && !isStringMap(server.env)) return { error: "invalid env" }; + if (server.env_vars != null && !Array.isArray(server.env_vars)) return { error: "invalid env_vars" }; + const forwarded = ((server.env_vars as unknown[] | undefined) ?? []).map(envVarName); + if (forwarded.some(name => name === undefined)) return { error: "invalid env_vars" }; + // Codex runs a server from the package unless it names a folder inside it. + const cwd = typeof server.cwd === "string" ? path.resolve(plugin.root, server.cwd) : plugin.root; + if (!(await isContainedResolved(plugin.root, cwd))) return { error: `cwd ${server.cwd} leaves the package` }; + // A bare name runs from PATH and an absolute path as given; a relative path runs from the package. + const relative = !path.isAbsolute(command) && /[\\/]/.test(command); + const resolvedCommand = relative ? path.resolve(cwd, command) : command; + if (relative && !(await isContainedResolved(plugin.root, resolvedCommand))) { + return { error: `command ${command} leaves the package` }; } + return { + server: { + transport: "stdio", + command: resolvedCommand, + ...(server.args != null && { args: server.args as string[] }), + ...(server.env != null && { env: server.env as Record }), + envPolicy: "literal", + envInherit: [...new Set([...INHERITED_ENV, ...CA_BUNDLE_ENV, ...(forwarded as string[])])], + cwd, + ...timeout, + }, + }; } - return undefined; + + if (server.http_headers_helper != null) return { error: "it computes its headers with a helper command" }; + if (server.auth != null && server.auth !== "oauth") return { error: `auth ${String(server.auth)} is not supported` }; + if (server.http_headers != null && !isStringMap(server.http_headers)) return { error: "invalid http_headers" }; + if (server.env_http_headers != null && !isStringMap(server.env_http_headers)) { + return { error: "invalid env_http_headers" }; + } + if (server.bearer_token_env_var != null && typeof server.bearer_token_env_var !== "string") { + return { error: "invalid bearer_token_env_var" }; + } + if (server.oauth != null && !isRecord(server.oauth)) return { error: "invalid oauth" }; + const url = server.url as string; + if (!URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol)) return { error: `invalid url ${url}` }; + // Static headers are data; the others name variables of the launch environment, as in Codex. + const headers: Record = { ...(server.http_headers as Record | undefined) }; + for (const [header, name] of Object.entries((server.env_http_headers ?? {}) as Record)) { + const value = env[name]?.trim(); + if (value) headers[header] = value; + } + const bearer = server.bearer_token_env_var ? env[server.bearer_token_env_var as string]?.trim() : undefined; + if (bearer) headers.Authorization = `Bearer ${bearer}`; + // Codex's OAuth client settings, snake_case or the camelCase plugins may use. + const oauthTable = (server.oauth ?? {}) as Record; + const oauth: NonNullable = {}; + for (const [snake, camel, target] of [ + ["client_id", "clientId", "clientId"], + ["client_secret", "clientSecret", "clientSecret"], + ["callback_url", "callbackUrl", "redirectUri"], + ] as const) { + const value = oauthTable[snake] ?? oauthTable[camel]; + if (typeof value === "string" && value) oauth[target] = value; + } + const port = oauthTable.callback_port ?? oauthTable.callbackPort; + if (Number.isInteger(port) && Number(port) > 0) oauth.callbackPort = Number(port); + if (isStringList(server.scopes) && server.scopes.length > 0) oauth.scope = server.scopes.join(" "); + const resource = typeof server.oauth_resource === "string" && server.oauth_resource ? server.oauth_resource : null; + return { + server: { + transport: "http", + url, + ...(Object.keys(headers).length > 0 && { headers }), + headerPolicy: "origin-locked", + ...(Object.keys(oauth).length > 0 && { oauth }), + ...(resource !== null && { auth: { type: "oauth" as const, resource } }), + ...timeout, + }, + }; } /** The plugin's server map: the manifest's inline map, its named file, or the package's `.mcp.json`. */ -async function readServerMap( +async function readLegacyServerMap( plugin: CodexPlugin, warnings: string[], ): Promise<{ servers: Record; sourcePath: string } | null> { @@ -218,17 +520,13 @@ async function readServerMap( let parsed: unknown = declared; let sourcePath = plugin.manifestPath; if (!isRecord(declared)) { - const file = - declared == null ? path.join(plugin.root, ".mcp.json") : packagePath(plugin, declared, "mcpServers", warnings); - if (file === null) return null; - const raw = await readFile(file); - if (raw === null) { - if (declared != null) - warnings.push(`[codex-plugins] Missing mcpServers file declared by ${plugin.id}: ${file}`); + const file = await packagePath(plugin, declared ?? ".mcp.json", "mcpServers", warnings); + if (file === null) { + if (declared != null) warnings.push(`[codex-plugins] Missing mcpServers file declared by ${plugin.id}`); return null; } try { - parsed = JSON.parse(raw); + parsed = JSON.parse((await readFile(file)) ?? ""); } catch { warnings.push(`[codex-plugins] Invalid JSON in ${file}`); return null; @@ -241,15 +539,49 @@ async function readServerMap( return isRecord(servers) ? { servers, sourcePath } : null; } +/** An Agent Plugins package's `mcp.json`, read under that standard, keyed by server name. */ +async function readStandardServers( + ctx: LoadContext, + plugin: CodexPlugin, + warnings: string[], +): Promise<{ servers: Record>; sourcePath: string } | null> { + const resolved = await resolveContainedPath(plugin.root, path.join(plugin.root, "mcp.json")); + if (resolved.status !== "ok") { + if (resolved.status === "outside") warnings.push(`[codex-plugins] ${plugin.id}: mcp.json leaves the package`); + return null; + } + const raw = await readFile(resolved.realPath); + if (raw === null) return null; + const digest = new Bun.CryptoHasher("sha256").update(`codex:${plugin.id}`).digest("hex").slice(0, 16); + const pluginData = path.join(getPluginsDir(ctx.home), "data", `codex-${plugin.name}-${digest}`); + const result = await parseAgentPluginMcp(raw, { pluginRoot: plugin.root, pluginData }); + if (result.status === "disabled") { + warnings.push(`[codex-plugins] ${plugin.id}: MCP disabled: ${result.reason}`); + return null; + } + warnings.push(...result.warnings.map(warning => `[codex-plugins] ${plugin.id}: ${warning}`)); + if (result.servers.some(server => server.transport === "stdio")) await fs.mkdir(pluginData, { recursive: true }); + const servers: Record> = {}; + for (const { name, ...server } of result.servers) { + servers[name] = + server.transport === "stdio" + ? { ...server, envPolicy: "literal", envInherit: [...INHERITED_ENV, ...CA_BUNDLE_ENV] } + : { ...server, headerPolicy: "origin-locked" }; + } + return { servers, sourcePath: resolved.realPath }; +} + async function loadMCPServers(ctx: LoadContext): Promise> { if (!isUserSourceEnabled(PROVIDER_ID, ctx)) return { items: [] }; - const { plugins, warnings } = await listCodexPlugins(ctx); + const { plugins, warnings, env } = await listCodexPlugins(ctx); const items: MCPServer[] = []; for (const plugin of plugins) { - const map = await readServerMap(plugin, warnings); - if (map === null) continue; const policies = isRecord(plugin.config.mcp_servers) ? plugin.config.mcp_servers : {}; - for (const [serverName, server] of Object.entries(map.servers)) { + const standard = plugin.format === "standard" ? await readStandardServers(ctx, plugin, warnings) : null; + const legacy = plugin.format === "legacy" ? await readLegacyServerMap(plugin, warnings) : null; + const declared: Record = standard?.servers ?? legacy?.servers ?? {}; + const sourcePath = standard?.sourcePath ?? legacy?.sourcePath ?? plugin.manifestPath; + for (const [serverName, server] of Object.entries(declared)) { if (!isRecord(server)) continue; const skip = `[codex-plugins] Skipping MCP server "${serverName}" of ${plugin.id}`; const reason = hostOnlyReason(server); @@ -264,25 +596,22 @@ async function loadMCPServers(ctx: LoadContext): Promise> warnings.push(`${skip}: Codex restricts its tools (${filter}), which Scient Agent cannot enforce`); continue; } - const malformed = malformedField(server); - if (malformed !== undefined) { - warnings.push(`${skip}: invalid ${malformed} in ${map.sourcePath}`); - continue; - } - let mapped: Partial | undefined; + let mapped: Mapped; try { - // Codex resolves a relative cwd, and a relative command from that cwd, against the package. - mapped = extractMCPServersFromToml({ mcp_servers: { [serverName]: server } }, plugin.root)[serverName]; + mapped = standard !== null ? { server } : await mapLegacyServer(plugin, server, env); } catch (error) { - warnings.push(`${skip}: ${String(error)}`); + mapped = { error: String(error) }; + } + if ("error" in mapped) { + warnings.push(`${skip}: ${mapped.error} (${sourcePath})`); continue; } items.push({ - name: `${plugin.name}:${serverName}`, - ...mapped, + name: `${plugin.label}:${serverName}`, + ...mapped.server, // `[plugins."".mcp_servers.] enabled = false` turns the server off in Codex. ...(policy.enabled === false && { enabled: false }), - _source: createSourceMeta(PROVIDER_ID, map.sourcePath, "user", undefined, plugin.name), + _source: createSourceMeta(PROVIDER_ID, sourcePath, "user", undefined, plugin.label), }); } } diff --git a/packages/coding-agent/test/scient/codex-plugins.test.ts b/packages/coding-agent/test/scient/codex-plugins.test.ts index 629f2d164d..880d9e0b9d 100644 --- a/packages/coding-agent/test/scient/codex-plugins.test.ts +++ b/packages/coding-agent/test/scient/codex-plugins.test.ts @@ -8,11 +8,18 @@ import type { MCPServer } from "@oh-my-pi/pi-coding-agent/capability/mcp"; import type { Skill } from "@oh-my-pi/pi-coding-agent/capability/skill"; import { cfgEnabledProviders } from "@oh-my-pi/pi-coding-agent/config/model-settings"; import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings"; -import { TempDir } from "@oh-my-pi/pi-utils"; +import { StdioTransport } from "@oh-my-pi/pi-coding-agent/mcp/transports/stdio"; +import { getProjectDir, setProjectDir, TempDir } from "@oh-my-pi/pi-utils"; import { restoreEnvValue } from "../helpers/settings-test-state"; import "@oh-my-pi/pi-coding-agent/discovery"; -const ENV_KEYS = ["SCIENT_AGENT_ENABLE_SOURCES", "CODEX_HOME", "CODEX_PLUGIN_TEST_TOKEN", "CODEX_PLUGIN_TEST_PAT"]; +const ENV_KEYS = [ + "SCIENT_AGENT_ENABLE_SOURCES", + "CODEX_HOME", + "CODEX_PLUGIN_TEST_TOKEN", + "CODEX_PLUGIN_TEST_PAT", + "CODEX_PLUGIN_TEST_SECRET", +]; async function writeSkill(root: string, name: string): Promise { const skillPath = path.join(root, "skills", name, "SKILL.md"); @@ -114,6 +121,9 @@ describe("installed Codex plugins", () => { const browser = path.join(cache, "openai-bundled", "browser", "26.1117.41037"); await writeManifest(browser, { name: "browser", skills: "./skills/" }); await writeSkill(browser, "control-in-app-browser"); + // The loader reports symlink-resolved paths (macOS temp folders live under /private). + researchRoot = await fs.realpath(researchRoot); + researchSkill = await fs.realpath(researchSkill); clearFsCache(); }); @@ -154,13 +164,19 @@ describe("installed Codex plugins", () => { command: path.join(researchRoot, "bin", "papers"), args: ["--stdio"], cwd: researchRoot, - env: { CODEX_PLUGIN_TEST_TOKEN: "forwarded-value" }, + envPolicy: "literal", timeout: 30_000, transport: "stdio", }); + // Codex passes its own short list plus the server's env_vars, never the whole environment. + expect(byName.get("research:papers")?.env).toBeUndefined(); + expect(byName.get("research:papers")?.envInherit).toEqual( + expect.arrayContaining(["PATH", "HOME", "CODEX_PLUGIN_TEST_TOKEN"]), + ); expect(byName.get("research:tracker")).toMatchObject({ url: "https://mcp.example.test/mcp", headers: { Authorization: "Bearer pat-value" }, + headerPolicy: "origin-locked", transport: "http", }); // The plugin's config table turns this server off, as Codex does. @@ -182,7 +198,7 @@ describe("installed Codex plugins", () => { await Bun.write(mcpPath, JSON.stringify({ mcpServers })); clearFsCache(); restoreEnvValue("SCIENT_AGENT_ENABLE_SOURCES", "codex-plugins"); - return mcpPath; + return fs.realpath(mcpPath); } const limits = async () => { const result = await loadCapability("mcps", { cwd, agentDir }); @@ -227,9 +243,218 @@ describe("installed Codex plugins", () => { expect(await limits()).toEqual({ names: ["limits:open"], warnings: [ - `[Codex Plugins] [codex-plugins] Skipping MCP server "bad" of limits@market: invalid env_vars in ${mcpPath}`, - `[Codex Plugins] [codex-plugins] Skipping MCP server "headers" of limits@market: invalid http_headers in ${mcpPath}`, + `[Codex Plugins] [codex-plugins] Skipping MCP server "bad" of limits@market: invalid env_vars (${mcpPath})`, + `[Codex Plugins] [codex-plugins] Skipping MCP server "headers" of limits@market: invalid http_headers (${mcpPath})`, ], }); }); + + /** Installs `@` with this manifest file and extra files; returns its real root. */ + async function install( + id: string, + files: Record, + configLines: string[] = ["enabled = true"], + ): Promise { + const [name, marketplace] = id.split("@"); + const codexHome = temp.join("codex-home"); + const configPath = path.join(codexHome, "config.toml"); + const config = await Bun.file(configPath).text(); + await Bun.write(configPath, [config, `[plugins."${id}"]`, ...configLines, ""].join("\n")); + const root = path.join(codexHome, "plugins", "cache", marketplace!, name!, "1.0.0"); + for (const [file, content] of Object.entries(files)) { + await Bun.write(path.join(root, file), typeof content === "string" ? content : JSON.stringify(content)); + } + clearFsCache(); + restoreEnvValue("SCIENT_AGENT_ENABLE_SOURCES", "codex-plugins"); + return fs.realpath(root); + } + const load = async () => { + const result = await loadCapability("mcps", { cwd, agentDir }); + return { + byName: new Map( + result.items.filter(server => server._source.provider === "codex-plugins").map(s => [s.name, s]), + ), + warnings: result.warnings, + }; + }; + + it("follows [plugins._default]: a table without enabled inherits it", async () => { + const server = { mcpServers: { one: { command: "node" } } }; + await install("inherits@market", { ".codex-plugin/plugin.json": { name: "inherits" }, ".mcp.json": server }); + await install("opted@market", { ".codex-plugin/plugin.json": { name: "opted" }, ".mcp.json": server }); + await Bun.write( + path.join(temp.join("codex-home"), "config.toml"), + [ + "[plugins._default]", + "enabled = false", + // A table with only a server policy and no `enabled` takes the default. + '[plugins."inherits@market".mcp_servers.one]', + "enabled = true", + '[plugins."opted@market"]', + "enabled = true", + "", + ].join("\n"), + ); + clearFsCache(); + expect([...(await load()).byName.keys()]).toEqual(["opted:one"]); + }); + + it("rejects servers Codex would reject and maps OAuth client settings", async () => { + await install("strict@market", { + ".codex-plugin/plugin.json": { name: "strict" }, + ".mcp.json": { + mcpServers: { + both: { command: "node", url: "https://mcp.example.test/mcp" }, + argsOnHttp: { url: "https://mcp.example.test/mcp", args: ["x"] }, + helper: { url: "https://mcp.example.test/mcp", http_headers_helper: "./headers.sh" }, + ema: { url: "https://mcp.example.test/mcp", auth: "ema_auth" }, + signin: { + type: "http", + url: "https://mcp.example.test/mcp", + oauth_resource: "https://mcp.example.test/mcp", + scopes: ["read", "write"], + oauth: { clientId: "client-1", callback_port: 4567 }, + note: "unknown fields are ignored, as in Codex", + }, + }, + }, + }); + const { byName, warnings } = await load(); + expect([...byName.keys()].filter(name => name.startsWith("strict:"))).toEqual(["strict:signin"]); + expect(byName.get("strict:signin")).toMatchObject({ + oauth: { clientId: "client-1", callbackPort: 4567, scope: "read write" }, + auth: { type: "oauth", resource: "https://mcp.example.test/mcp" }, + }); + expect(warnings.filter(w => w.includes("of strict@market"))).toEqual([ + expect.stringContaining('"both" of strict@market: url is not supported for stdio'), + expect.stringContaining('"argsOnHttp" of strict@market: args is not supported for streamable HTTP'), + expect.stringContaining('"helper" of strict@market: it computes its headers with a helper command'), + expect.stringContaining('"ema" of strict@market: auth ema_auth is not supported'), + ]); + }); + + it("takes plugin values literally and keeps launch paths inside the package", async () => { + const root = await install("paths@market", { + ".codex-plugin/plugin.json": { name: "paths" }, + ".mcp.json": { + mcpServers: { + literal: { url: "https://mcp.example.test/mcp", http_headers: { "X-Run": "!touch /tmp/pwned" } }, + upCwd: { command: "node", cwd: "../.." }, + upCommand: { command: "../../../other/bin/server" }, + fromPath: { command: "node", env: { MODE: "CODEX_PLUGIN_TEST_PAT" } }, + }, + }, + }); + const { byName, warnings } = await load(); + expect([...byName.keys()].filter(name => name.startsWith("paths:")).sort()).toEqual([ + "paths:fromPath", + "paths:literal", + ]); + // Origin-locked headers and literal env are never resolved as variables or `!commands`. + expect(byName.get("paths:literal")).toMatchObject({ + headers: { "X-Run": "!touch /tmp/pwned" }, + headerPolicy: "origin-locked", + }); + expect(byName.get("paths:fromPath")).toMatchObject({ + command: "node", + cwd: root, + env: { MODE: "CODEX_PLUGIN_TEST_PAT" }, + envPolicy: "literal", + }); + const reasons = warnings.filter(w => w.includes("of paths@market")); + expect(reasons).toEqual([ + expect.stringContaining('"upCwd" of paths@market: cwd ../.. leaves the package'), + expect.stringContaining('"upCommand" of paths@market: command ../../../other/bin/server leaves the package'), + ]); + }); + + it("does not follow a skills or MCP file link out of the package", async () => { + const outside = temp.join("outside"); + await writeSkill(outside, "leaked"); + await Bun.write(path.join(outside, "servers.json"), JSON.stringify({ mcpServers: { x: { command: "node" } } })); + const root = await install("linked@market", { + ".codex-plugin/plugin.json": { name: "linked", mcpServers: "./servers.json" }, + }); + await fs.symlink(path.join(outside, "skills"), path.join(root, "skills"), "dir"); + await fs.symlink(path.join(outside, "servers.json"), path.join(root, "servers.json")); + clearFsCache(); + expect((await skills()).map(skill => skill.name)).toEqual(["lit-review"]); + const { byName, warnings } = await load(); + expect([...byName.keys()].some(name => name.startsWith("linked:"))).toBe(false); + expect(warnings).toContainEqual(expect.stringContaining("Ignoring mcpServers path outside linked@market")); + }); + + it("keeps two marketplaces' same-named plugins apart", async () => { + const server = { mcpServers: { api: { command: "node" } } }; + await install("twin@alpha", { ".codex-plugin/plugin.json": { name: "twin" }, ".mcp.json": server }); + await install("twin@beta", { ".codex-plugin/plugin.json": { name: "twin" }, ".mcp.json": server }); + expect([...(await load()).byName.keys()].filter(name => name.startsWith("twin")).sort()).toEqual([ + "twin.alpha:api", + "twin.beta:api", + ]); + }); + + it("reads Codex's manifest precedence: a root Agent Plugins manifest, then the legacy folders", async () => { + await install("portable@market", { + "plugin.json": { $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", name: "portable" }, + ".codex-plugin/plugin.json": { name: "portable", mcpServers: { legacy: { command: "node" } } }, + "mcp.json": { + $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + mcpServers: { remote: { type: "streamable-http", url: "https://mcp.example.test/mcp" } }, + }, + }); + await install("clauded@market", { + ".claude-plugin/plugin.json": { name: "clauded" }, + ".mcp.json": { mcpServers: { tool: { command: "node" } } }, + }); + const { byName } = await load(); + expect(byName.get("portable:remote")).toMatchObject({ transport: "http", headerPolicy: "origin-locked" }); + expect(byName.has("portable:legacy")).toBe(false); + expect(byName.has("clauded:tool")).toBe(true); + }); + + it("ignores a CODEX_HOME that only a project's .env sets", async () => { + const previous = getProjectDir(); + const decoy = temp.join("decoy-home"); + await Bun.write(path.join(cwd, ".env"), `CODEX_HOME=${decoy}\n`); + await install("decoy@market", { ".codex-plugin/plugin.json": { name: "decoy" } }); + await fs.cp(temp.join("codex-home"), decoy, { recursive: true }); + // As if the agent had loaded the project's .env into its environment. + restoreEnvValue("CODEX_HOME", decoy); + setProjectDir(cwd); + try { + clearFsCache(); + const decoyServers = (await load()).warnings.filter(w => w.includes(decoy)); + expect(decoyServers).toEqual([]); + expect((await skills()).map(skill => skill.path).some(p => p.includes("decoy-home"))).toBe(false); + } finally { + setProjectDir(previous); + } + }); + + it("starts a stdio server with only the variables Codex would pass", async () => { + restoreEnvValue("CODEX_PLUGIN_TEST_SECRET", "must-not-leak"); + const out = temp.join("env.json"); + const transport = new StdioTransport({ + type: "stdio", + command: process.execPath, + args: ["-e", `require("fs").writeFileSync(${JSON.stringify(out)}, JSON.stringify(process.env))`], + env: { MODE: "set" }, + envInherit: ["PATH", "CODEX_PLUGIN_TEST_TOKEN"], + }); + // The script writes its environment and exits; the transport reports the exit. + const exited = Promise.withResolvers(); + transport.onClose = () => exited.resolve(); + try { + await transport.connect(); + await exited.promise; + } finally { + await transport.close(); + } + const seen = JSON.parse(await Bun.file(out).text()) as Record; + expect(seen.CODEX_PLUGIN_TEST_TOKEN).toBe("forwarded-value"); + expect(seen.MODE).toBe("set"); + expect(seen.CODEX_PLUGIN_TEST_SECRET).toBeUndefined(); + expect(seen.CODEX_PLUGIN_TEST_PAT).toBeUndefined(); + }); }); diff --git a/scripts/scient/divergences.json b/scripts/scient/divergences.json index c03e17c514..3d21582963 100644 --- a/scripts/scient/divergences.json +++ b/scripts/scient/divergences.json @@ -520,15 +520,18 @@ }, "SA-CODEX-PLUGINS": { "status": "active", - "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex), from the version Codex runs in $CODEX_HOME/plugins/cache/// and its .codex-plugin/plugin.json. MCP fields map as the codex provider maps config.toml (env_vars, bearer_token_env_var, tool_timeout_sec), relative command and cwd resolve inside the package, servers are named :, and a plugin's mcp_servers..enabled = false disables one. A server whose plugin definition or mcp_servers. policy sets enabled_tools or a non-empty disabled_tools is skipped with a warning, since Scient Agent's MCP servers carry no tool filter, and a server with a malformed args, env_vars, env, http_headers or env_http_headers is skipped with a warning while its siblings load. OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded.", + "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of the Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex; CODEX_HOME from the launch environment, never a project's .env), layered over /etc/codex/config.toml, a table without enabled taking [plugins._default]. It reads the version Codex runs in $CODEX_HOME/plugins/cache/// with Codex's manifest precedence: a root Agent Plugins plugin.json (its skills/ and mcp.json, read under that standard), else .codex-plugin, .claude-plugin or .cursor-plugin/plugin.json, a link or non-file there rejecting the plugin. A server must declare exactly one transport with only that transport's Codex fields; package files, cwd and relative commands must stay inside the symlink-resolved package. Stdio servers inherit only Codex's variable list (HOME, PATH and the like, certificate-bundle variables, and the server's env_vars: MCPServer.envInherit), with literal env values; HTTP servers carry literal, origin-locked headers, bearer_token_env_var and env_http_headers read from the launch environment, and their OAuth client settings, scopes and oauth_resource. Servers are named :, or .: when two enabled plugins share a name; a plugin's mcp_servers..enabled = false disables one. Skipped with a warning while siblings load: servers whose tools Codex narrows (enabled_tools, or a non-empty disabled_tools), which Scient Agent cannot enforce, and servers with malformed or unsupported fields (http_headers_helper, auth other than oauth). OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded, and nothing loads while an organization policy manages Codex (/etc/codex/requirements.toml or managed_config.toml, macOS managed preferences for com.openai.codex, %ProgramData%\\OpenAI\\Codex\\requirements.toml). Not applied: Codex profiles, project .codex/config.toml layers and cloud-delivered config.", "owned": [ "packages/coding-agent/src/scient/codex-plugins.ts", "packages/coding-agent/test/scient/codex-plugins.test.ts" ], "upstream": [ "packages/coding-agent/src/capability/index.ts", - "packages/coding-agent/src/discovery/codex.ts", + "packages/coding-agent/src/capability/mcp.ts", "packages/coding-agent/src/discovery/index.ts", + "packages/coding-agent/src/mcp/config.ts", + "packages/coding-agent/src/mcp/transports/stdio.ts", + "packages/coding-agent/src/mcp/types.ts", "packages/coding-agent/CHANGELOG.md" ], "verification": [ From e53bde7b83596e3ff6910d6f4acee7994de849d0 Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sun, 22 Nov 2026 10:38:12 +0200 Subject: [PATCH 4/4] fix(codex-plugins): match Codex on launch env, policy layers, containment and server rules Second Codex review of 4d90a48614: - getLaunchEnv() (utils env.ts) is the exec environment when known (procfs, --no-env-file), else the environment without the values of the launch folder's Bun-autoloaded dotenv files and the agent's own .env files, whichever folder the agent works in now. CODEX_HOME, header credentials and servers' variables come from it. - A stdio server's env is built as Codex builds it (variable list, absolute CA bundles, env_vars, literal env, minus Codex's non-inheritable names) and it inherits nothing else. - System config merges at every depth; Windows system config and Group Policy RequirementsPath. - Each skill and each legacy manifest's folder must stay in the package; a linked folder rejects. - A declaration's enabled = false and a policy's auth = "ema_auth" disable a server. - Mistyped command/url rejected; Agent Plugins mcp.json must be a regular file, sse is left out, and the legacy declaration's env_vars overlay applies. - Same-named plugins are qualified :, which no plugin name can collide with. --- .../coding-agent/src/scient/codex-plugins.ts | 359 ++++++++++++------ .../test/scient/codex-plugins.test.ts | 128 ++++++- packages/utils/src/env.ts | 24 ++ scripts/scient/divergences.json | 5 +- 4 files changed, 389 insertions(+), 127 deletions(-) diff --git a/packages/coding-agent/src/scient/codex-plugins.ts b/packages/coding-agent/src/scient/codex-plugins.ts index 3cb6e2fa74..8241154ad0 100644 --- a/packages/coding-agent/src/scient/codex-plugins.ts +++ b/packages/coding-agent/src/scient/codex-plugins.ts @@ -15,7 +15,7 @@ import type { Dirent, Stats } from "node:fs"; import * as fs from "node:fs/promises"; import * as os from "node:os"; import * as path from "node:path"; -import { filterChildShellEnv, getPluginsDir, isRecord, logger } from "@oh-my-pi/pi-utils"; +import { filterChildShellEnv, getLaunchEnv, getPluginsDir, isRecord, logger } from "@oh-my-pi/pi-utils"; import { isUserSourceEnabled, registerProvider } from "../capability"; import { readDirEntries, readFile } from "../capability/fs"; import { type MCPServer, mcpCapability } from "../capability/mcp"; @@ -35,7 +35,8 @@ const LOCAL_VERSION = "local"; /** * Codex's legacy manifests, in its order of precedence after a root Agent Plugins `plugin.json`. - * The first one present decides; a link or non-file there stops the search, as in Codex. + * The first one present decides; a link or non-file there, or a linked folder holding it, stops + * the search, as in Codex. */ const LEGACY_MANIFESTS = [".codex-plugin/plugin.json", ".claude-plugin/plugin.json", ".cursor-plugin/plugin.json"]; @@ -55,52 +56,41 @@ const HOST_PLUGINS: Record = { /** OpenAI's launcher for its signed Computer Use client, which serves only Codex (the Messages plugin). */ const HOST_LAUNCHER = "computer-use-client-launcher"; +const IS_WINDOWS = process.platform === "win32"; + /** * The variables Codex passes a plugin's local stdio server from its own environment, besides * those the server names in `env_vars` (codex-rs/rmcp-client `DEFAULT_ENV_VARS`, and - * `WINDOWS_CORE_ENV_VARS` on Windows), plus the certificate-bundle variables it always keeps - * (`CUSTOM_CA_ENV_KEYS`). Nothing else, API keys included, reaches the server. + * `WINDOWS_CORE_ENV_VARS` on Windows). Nothing else, API keys included, reaches the server. */ -const INHERITED_ENV = - process.platform === "win32" - ? [ - "PATH", - "PATHEXT", - "SHELL", - "COMSPEC", - "SYSTEMROOT", - "WINDIR", - "SYSTEMDRIVE", - "USERNAME", - "USERDOMAIN", - "USERPROFILE", - "HOMEDRIVE", - "HOMEPATH", - "PROGRAMFILES", - "PROGRAMFILES(X86)", - "PROGRAMW6432", - "PROGRAMDATA", - "LOCALAPPDATA", - "APPDATA", - "TEMP", - "TMP", - "TMPDIR", - "POWERSHELL", - "PWSH", - ] - : [ - "HOME", - "LOGNAME", - "PATH", - "SHELL", - "USER", - "__CF_USER_TEXT_ENCODING", - "LANG", - "LC_ALL", - "TERM", - "TMPDIR", - "TZ", - ]; +const INHERITED_ENV = IS_WINDOWS + ? [ + "PATH", + "PATHEXT", + "SHELL", + "COMSPEC", + "SYSTEMROOT", + "WINDIR", + "SYSTEMDRIVE", + "USERNAME", + "USERDOMAIN", + "USERPROFILE", + "HOMEDRIVE", + "HOMEPATH", + "PROGRAMFILES", + "PROGRAMFILES(X86)", + "PROGRAMW6432", + "PROGRAMDATA", + "LOCALAPPDATA", + "APPDATA", + "TEMP", + "TMP", + "TMPDIR", + "POWERSHELL", + "PWSH", + ] + : ["HOME", "LOGNAME", "PATH", "SHELL", "USER", "__CF_USER_TEXT_ENCODING", "LANG", "LC_ALL", "TERM", "TMPDIR", "TZ"]; +/** Certificate bundles Codex always passes on, as absolute paths (`CUSTOM_CA_ENV_KEYS`). */ const CA_BUNDLE_ENV = [ "CODEX_CA_CERTIFICATE", "SSL_CERT_FILE", @@ -114,6 +104,18 @@ const CA_BUNDLE_ENV = [ "npm_config_cafile", "NPM_CONFIG_CAFILE", ]; +/** Names Codex never lets a model-reachable process have (`NON_INHERITABLE_ENV_VARS`), even from `env`. */ +const NON_INHERITABLE_ENV = [ + "CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN", + "NODE_REPL_AUTH_TOKEN", + "CODEX_GUARDIAN_DECISIONS_API_KEY", + "OPENAI_FEDERATION_RULE_ID", + "OPENAI_IDENTITY_TOKEN_FILE", + "OPENAI_IDENTITY_TOKEN_SOURCE", + "OPENAI_SPIFFE_AUDIENCE", + "OPENAI_SPIFFE_ID", + "OPENAI_WORKLOAD_IDENTITY_CONTEXT", +]; /** Fields Codex rejects on a stdio server, and on a streamable HTTP server. */ const NOT_STDIO = [ @@ -137,7 +139,10 @@ interface CodexPlugin { id: string; name: string; marketplace: string; - /** Skill namespace and MCP server prefix: the name, or `.` when two enabled plugins share it. */ + /** + * Skill namespace and MCP server prefix: the name, or `:` when two enabled + * plugins share it. Neither part may contain `:`, so the qualified form never meets another. + */ label: string; /** The active version's folder, symlinks resolved; every package path stays inside it. */ root: string; @@ -152,7 +157,7 @@ interface CodexPlugin { interface PluginList { plugins: CodexPlugin[]; warnings: string[]; - /** Scient Agent's launch environment, without a project's `.env` values. */ + /** Scient Agent's launch environment, without any `.env` file's values. */ env: Record; } @@ -187,6 +192,47 @@ async function lstatOrNull(file: string): Promise { } } +/** Environment names compare case-insensitively on Windows, as Codex compares them there. */ +function sameEnvName(left: string, right: string): boolean { + return IS_WINDOWS ? left.toUpperCase() === right.toUpperCase() : left === right; +} + +function envValue(env: Record, name: string): string | undefined { + if (!IS_WINDOWS) return env[name]; + const key = Object.keys(env).find(candidate => sameEnvName(candidate, name)); + return key === undefined ? undefined : env[key]; +} + +/** + * The environment Codex gives a plugin's local stdio server: its variable list and the server's + * `env_vars` from the launch environment, certificate bundles as absolute paths, then the + * server's own `env`, never the names Codex withholds. The server inherits nothing else. + */ +function stdioEnv( + env: Record, + forwarded: readonly string[], + declared: Record | undefined, +): Record { + const result: Record = {}; + const put = (name: string, value: string) => { + for (const key of Object.keys(result)) if (sameEnvName(key, name)) delete result[key]; + result[name] = value; + }; + for (const name of [...INHERITED_ENV, ...forwarded]) { + const value = envValue(env, name); + if (value !== undefined) put(name, value); + } + for (const name of CA_BUNDLE_ENV) { + const value = envValue(env, name); + if (value) put(name, path.resolve(value)); + } + for (const [name, value] of Object.entries(declared ?? {})) put(name, value); + for (const key of Object.keys(result)) { + if (NON_INHERITABLE_ENV.some(name => sameEnvName(name, key))) delete result[key]; + } + return result; +} + /** The first legacy manifest present, read; null (with a warning) when none is usable. */ async function readLegacyManifest( root: string, @@ -195,6 +241,12 @@ async function readLegacyManifest( ): Promise<{ manifestPath: string; manifest: Record } | null> { for (const relative of LEGACY_MANIFESTS) { const manifestPath = path.join(root, relative); + const folder = await lstatOrNull(path.dirname(manifestPath)); + if (folder === null) continue; + if (!folder.isDirectory()) { + warnings.push(`[codex-plugins] Ignoring ${id}: ${path.dirname(relative)} is not a folder`); + return null; + } const stat = await lstatOrNull(manifestPath); if (stat === null) continue; if (!stat.isFile()) { @@ -276,17 +328,37 @@ async function readToml(file: string, warnings: string[]): Promise, higher: Record): Record { + const merged: Record = { ...lower }; + for (const [key, value] of Object.entries(higher)) { + const below = merged[key]; + merged[key] = isRecord(below) && isRecord(value) ? mergeLayers(below, value) : value; + } + return merged; +} + +/** Codex's system folder: `/etc/codex`, or `OpenAI\Codex` in ProgramData on Windows. */ +function systemDir(): string { + return IS_WINDOWS ? path.join(process.env.ProgramData || "C:\\ProgramData", "OpenAI", "Codex") : "/etc/codex"; +} + /** - * Where an organization's Codex policy lives (requirements, managed config, macOS managed - * preferences). Codex enforces them over the user's config; Scient Agent cannot, so it loads no - * plugins while one is present. + * The first organization policy Codex would enforce over the user's config (requirements, a + * legacy managed config, macOS managed preferences, or a Windows Group Policy requirements path), + * or undefined. Scient Agent cannot apply one, so it loads no plugins while one is present. */ -function managedPolicyFiles(): string[] { - if (process.platform === "win32") { - const programData = process.env.ProgramData || "C:\\ProgramData"; - return [path.join(programData, "OpenAI", "Codex", "requirements.toml")]; +async function managedPolicy(): Promise { + if (IS_WINDOWS) { + const key = "HKLM\\SOFTWARE\\Policies\\OpenAI\\Codex"; + const query = Bun.spawnSync(["reg", "query", key, "/v", "RequirementsPath", "/reg:64"], { + stdout: "ignore", + stderr: "ignore", + }); + if (query.exitCode === 0) return `${key}\\RequirementsPath`; } - const files = ["/etc/codex/requirements.toml", "/etc/codex/managed_config.toml"]; + const files = [path.join(systemDir(), "requirements.toml")]; + if (!IS_WINDOWS) files.push("/etc/codex/managed_config.toml"); if (process.platform === "darwin") { const managed = "/Library/Managed Preferences"; files.push( @@ -294,19 +366,20 @@ function managedPolicyFiles(): string[] { path.join(managed, os.userInfo().username, "com.openai.codex.plist"), ); } - return files; + for (const file of files) if ((await lstatOrNull(file)) !== null) return file; + return undefined; } /** Installed, enabled Codex plugins outside {@link HOST_PLUGINS}. */ async function listCodexPlugins(ctx: LoadContext): Promise { const warnings: string[] = []; - // The environment Scient Agent was launched with: a project's `.env` never chooses Codex's - // home or the credentials sent to a plugin's server. - const env = filterChildShellEnv(Bun.env); - for (const file of managedPolicyFiles()) { - if ((await lstatOrNull(file)) === null) continue; + // The environment Scient Agent was launched with: no `.env` file, from this project or one the + // agent worked in before, chooses Codex's home or what reaches a plugin's server. + const env = filterChildShellEnv(getLaunchEnv()); + const policy = await managedPolicy(); + if (policy !== undefined) { warnings.push( - `[codex-plugins] Codex is managed by an organization policy (${file}), which Scient Agent cannot apply; no Codex plugins load`, + `[codex-plugins] Codex is managed by an organization policy (${policy}), which Scient Agent cannot apply; no Codex plugins load`, ); return { plugins: [], warnings, env }; } @@ -314,12 +387,9 @@ async function listCodexPlugins(ctx: LoadContext): Promise { const home = env.CODEX_HOME?.trim() || path.join(ctx.home, ".codex"); const user = await readToml(path.join(home, "config.toml"), warnings); if (user === null) return { plugins: [], warnings, env }; - // The system layer sits under the user's; per-plugin tables and `_default` merge by key. - const system = process.platform === "win32" ? null : await readToml("/etc/codex/config.toml", warnings); - const table: Record = { - ...(isRecord(system?.plugins) ? system.plugins : {}), - ...(isRecord(user.plugins) ? user.plugins : {}), - }; + const system = await readToml(path.join(systemDir(), "config.toml"), warnings); + const merged = mergeLayers(system ?? {}, user); + const table = isRecord(merged.plugins) ? merged.plugins : {}; const defaults = isRecord(table._default) ? table._default : {}; const enabledByDefault = defaults.enabled !== false; const read = await Promise.all( @@ -330,12 +400,12 @@ async function listCodexPlugins(ctx: LoadContext): Promise { }), ); const found = read.filter(plugin => plugin !== null); - const sharedNames = new Set( + const shared = new Set( found.filter((plugin, index) => found.findIndex(other => other.name === plugin.name) !== index).map(p => p.name), ); const plugins = found.map(plugin => ({ ...plugin, - label: sharedNames.has(plugin.name) ? `${plugin.name}.${plugin.marketplace}` : plugin.name, + label: shared.has(plugin.name) ? `${plugin.name}:${plugin.marketplace}` : plugin.name, })); return { plugins, warnings, env }; } @@ -354,7 +424,8 @@ async function packagePath(plugin: CodexPlugin, value: unknown, key: string, war async function loadSkills(ctx: LoadContext): Promise> { if (!isUserSourceEnabled(PROVIDER_ID, ctx)) return { items: [] }; const { plugins, warnings } = await listCodexPlugins(ctx); - const dirsByPlugin = await Promise.all( + const items: Skill[] = []; + await Promise.all( plugins.map(async plugin => { const declared = plugin.format === "standard" ? undefined : plugin.manifest.skills; const entries = declared == null ? ["skills"] : Array.isArray(declared) ? declared : [declared]; @@ -363,19 +434,22 @@ async function loadSkills(ctx: LoadContext): Promise> { const dir = await packagePath(plugin, entry, "skills", warnings); if (dir !== null) dirs.add(dir); } - return { plugin, dirs: [...dirs] }; + for (const dir of dirs) { + const result = await scanSkillsFromDir(ctx, { + dir, + providerId: PROVIDER_ID, + level: "user", + pluginName: plugin.label, + }); + if (result.warnings) warnings.push(...result.warnings); + // A skill folder or SKILL.md linked out of the package does not load, as in Codex. + for (const skill of result.items) { + if ((await resolveContainedPath(plugin.root, skill.path)).status === "ok") items.push(skill); + else warnings.push(`[codex-plugins] Ignoring skill outside ${plugin.id}: ${skill.path}`); + } + } }), ); - const scans = dirsByPlugin.flatMap(({ plugin, dirs }) => - dirs.map(dir => - scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user", pluginName: plugin.label }), - ), - ); - const items: Skill[] = []; - for (const result of await Promise.all(scans)) { - items.push(...result.items); - if (result.warnings) warnings.push(...result.warnings); - } return { items, warnings }; } @@ -405,11 +479,18 @@ const isStringList = (value: unknown): value is string[] => const isStringMap = (value: unknown): value is Record => isRecord(value) && Object.values(value).every(item => typeof item === "string"); -/** Codex's `env_vars` entry: a name, or `{ name, source = "local" }`. */ -function envVarName(entry: unknown): string | undefined { - if (typeof entry === "string") return entry; - if (isRecord(entry) && typeof entry.name === "string" && (entry.source ?? "local") === "local") return entry.name; - return undefined; +/** The names of Codex's `env_vars` entries (a name, or `{ name, source = "local" }`); null when one is malformed. */ +function envVarNames(value: unknown): string[] | null { + if (value == null) return []; + if (!Array.isArray(value)) return null; + const names: string[] = []; + for (const entry of value) { + if (typeof entry === "string") names.push(entry); + else if (isRecord(entry) && typeof entry.name === "string" && (entry.source ?? "local") === "local") { + names.push(entry.name); + } else return null; + } + return names; } type Mapped = { server: Partial } | { error: string }; @@ -423,23 +504,27 @@ async function mapLegacyServer( server: Record, env: Record, ): Promise { - const isStdio = typeof server.command === "string"; - if (!isStdio && typeof server.url !== "string") return { error: "it declares neither command nor url" }; + if (server.command != null && typeof server.command !== "string") return { error: "invalid command" }; + if (server.url != null && typeof server.url !== "string") return { error: "invalid url" }; + const isStdio = server.command != null; + if (!isStdio && server.url == null) return { error: "it declares neither command nor url" }; const wrong = (isStdio ? NOT_STDIO : NOT_HTTP).find(key => server[key] != null); if (wrong !== undefined) return { error: `${wrong} is not supported for ${isStdio ? "stdio" : "streamable HTTP"}` }; - const timeout = - typeof server.tool_timeout_sec === "number" && server.tool_timeout_sec > 0 - ? { timeout: server.tool_timeout_sec * 1000 } - : {}; + const common = { + // `enabled = false` in the declaration turns the server off in Codex. + ...(server.enabled === false && { enabled: false }), + ...(typeof server.tool_timeout_sec === "number" && + server.tool_timeout_sec > 0 && { timeout: server.tool_timeout_sec * 1000 }), + }; if (isStdio) { const command = (server.command as string).trim(); if (!command) return { error: "command is empty" }; if (server.args != null && !isStringList(server.args)) return { error: "invalid args" }; if (server.env != null && !isStringMap(server.env)) return { error: "invalid env" }; - if (server.env_vars != null && !Array.isArray(server.env_vars)) return { error: "invalid env_vars" }; - const forwarded = ((server.env_vars as unknown[] | undefined) ?? []).map(envVarName); - if (forwarded.some(name => name === undefined)) return { error: "invalid env_vars" }; + const forwarded = envVarNames(server.env_vars); + if (forwarded === null) return { error: "invalid env_vars" }; + if (server.cwd != null && typeof server.cwd !== "string") return { error: "invalid cwd" }; // Codex runs a server from the package unless it names a folder inside it. const cwd = typeof server.cwd === "string" ? path.resolve(plugin.root, server.cwd) : plugin.root; if (!(await isContainedResolved(plugin.root, cwd))) return { error: `cwd ${server.cwd} leaves the package` }; @@ -454,11 +539,11 @@ async function mapLegacyServer( transport: "stdio", command: resolvedCommand, ...(server.args != null && { args: server.args as string[] }), - ...(server.env != null && { env: server.env as Record }), + env: stdioEnv(env, forwarded, server.env as Record | undefined), envPolicy: "literal", - envInherit: [...new Set([...INHERITED_ENV, ...CA_BUNDLE_ENV, ...(forwarded as string[])])], + envInherit: [], cwd, - ...timeout, + ...common, }, }; } @@ -478,10 +563,10 @@ async function mapLegacyServer( // Static headers are data; the others name variables of the launch environment, as in Codex. const headers: Record = { ...(server.http_headers as Record | undefined) }; for (const [header, name] of Object.entries((server.env_http_headers ?? {}) as Record)) { - const value = env[name]?.trim(); + const value = envValue(env, name)?.trim(); if (value) headers[header] = value; } - const bearer = server.bearer_token_env_var ? env[server.bearer_token_env_var as string]?.trim() : undefined; + const bearer = server.bearer_token_env_var ? envValue(env, server.bearer_token_env_var as string)?.trim() : ""; if (bearer) headers.Authorization = `Bearer ${bearer}`; // Codex's OAuth client settings, snake_case or the camelCase plugins may use. const oauthTable = (server.oauth ?? {}) as Record; @@ -506,19 +591,21 @@ async function mapLegacyServer( headerPolicy: "origin-locked", ...(Object.keys(oauth).length > 0 && { oauth }), ...(resource !== null && { auth: { type: "oauth" as const, resource } }), - ...timeout, + ...common, }, }; } -/** The plugin's server map: the manifest's inline map, its named file, or the package's `.mcp.json`. */ +/** A legacy server map: the manifest's inline map, its named file, or the package's `.mcp.json`. */ async function readLegacyServerMap( plugin: CodexPlugin, + manifest: Record, + manifestPath: string, warnings: string[], ): Promise<{ servers: Record; sourcePath: string } | null> { - const declared = plugin.manifest.mcpServers; + const declared = manifest.mcpServers; let parsed: unknown = declared; - let sourcePath = plugin.manifestPath; + let sourcePath = manifestPath; if (!isRecord(declared)) { const file = await packagePath(plugin, declared ?? ".mcp.json", "mcpServers", warnings); if (file === null) { @@ -539,18 +626,26 @@ async function readLegacyServerMap( return isRecord(servers) ? { servers, sourcePath } : null; } -/** An Agent Plugins package's `mcp.json`, read under that standard, keyed by server name. */ +/** + * An Agent Plugins package's `mcp.json`, read under that standard and Codex's rules for it: the + * file must be a regular file at the root, `sse` servers do not run, and a stdio server takes the + * `env_vars` its package's legacy declaration of the same server adds (dropping the `${NAME}` + * placeholders those variables replace). + */ async function readStandardServers( ctx: LoadContext, plugin: CodexPlugin, + env: Record, warnings: string[], ): Promise<{ servers: Record>; sourcePath: string } | null> { - const resolved = await resolveContainedPath(plugin.root, path.join(plugin.root, "mcp.json")); - if (resolved.status !== "ok") { - if (resolved.status === "outside") warnings.push(`[codex-plugins] ${plugin.id}: mcp.json leaves the package`); + const file = path.join(plugin.root, "mcp.json"); + const stat = await lstatOrNull(file); + if (stat === null) return null; + if (!stat.isFile()) { + warnings.push(`[codex-plugins] ${plugin.id}: mcp.json is not a regular file`); return null; } - const raw = await readFile(resolved.realPath); + const raw = await readFile(file); if (raw === null) return null; const digest = new Bun.CryptoHasher("sha256").update(`codex:${plugin.id}`).digest("hex").slice(0, 16); const pluginData = path.join(getPluginsDir(ctx.home), "data", `codex-${plugin.name}-${digest}`); @@ -560,15 +655,37 @@ async function readStandardServers( return null; } warnings.push(...result.warnings.map(warning => `[codex-plugins] ${plugin.id}: ${warning}`)); - if (result.servers.some(server => server.transport === "stdio")) await fs.mkdir(pluginData, { recursive: true }); + const quiet: string[] = []; + const legacy = await readLegacyManifest(plugin.root, plugin.id, quiet); + const overlay = (await readLegacyServerMap(plugin, legacy?.manifest ?? {}, legacy?.manifestPath ?? file, quiet)) + ?.servers; const servers: Record> = {}; for (const { name, ...server } of result.servers) { - servers[name] = - server.transport === "stdio" - ? { ...server, envPolicy: "literal", envInherit: [...INHERITED_ENV, ...CA_BUNDLE_ENV] } - : { ...server, headerPolicy: "origin-locked" }; + if (server.transport === "sse") { + warnings.push(`[codex-plugins] Skipping MCP server "${name}" of ${plugin.id}: Codex does not run sse servers`); + continue; + } + if (server.transport !== "stdio") { + servers[name] = { ...server, headerPolicy: "origin-locked" }; + continue; + } + const declared = overlay?.[name]; + const forwarded = isRecord(declared) && declared.command != null ? (envVarNames(declared.env_vars) ?? []) : []; + // A `${NAME}` placeholder for a forwarded variable gives way to that variable's real value. + const kept = Object.entries(server.env ?? {}).filter( + ([key, value]) => + !forwarded.some(variable => sameEnvName(key, variable) && sameEnvName(value, `\${${variable}}`)), + ); + servers[name] = { + ...server, + env: stdioEnv(env, forwarded, Object.fromEntries(kept)), + envPolicy: "literal", + envInherit: [], + }; } - return { servers, sourcePath: resolved.realPath }; + if (Object.values(servers).some(server => server.transport === "stdio")) + await fs.mkdir(pluginData, { recursive: true }); + return { servers, sourcePath: file }; } async function loadMCPServers(ctx: LoadContext): Promise> { @@ -577,8 +694,11 @@ async function loadMCPServers(ctx: LoadContext): Promise> const items: MCPServer[] = []; for (const plugin of plugins) { const policies = isRecord(plugin.config.mcp_servers) ? plugin.config.mcp_servers : {}; - const standard = plugin.format === "standard" ? await readStandardServers(ctx, plugin, warnings) : null; - const legacy = plugin.format === "legacy" ? await readLegacyServerMap(plugin, warnings) : null; + const standard = plugin.format === "standard" ? await readStandardServers(ctx, plugin, env, warnings) : null; + const legacy = + plugin.format === "legacy" + ? await readLegacyServerMap(plugin, plugin.manifest, plugin.manifestPath, warnings) + : null; const declared: Record = standard?.servers ?? legacy?.servers ?? {}; const sourcePath = standard?.sourcePath ?? legacy?.sourcePath ?? plugin.manifestPath; for (const [serverName, server] of Object.entries(declared)) { @@ -609,8 +729,9 @@ async function loadMCPServers(ctx: LoadContext): Promise> items.push({ name: `${plugin.label}:${serverName}`, ...mapped.server, - // `[plugins."".mcp_servers.] enabled = false` turns the server off in Codex. - ...(policy.enabled === false && { enabled: false }), + // The plugin's `mcp_servers.` table turns the server off with `enabled = false`, and + // with the enterprise sign-in Codex no longer supports there. + ...((policy.enabled === false || policy.auth === "ema_auth") && { enabled: false }), _source: createSourceMeta(PROVIDER_ID, sourcePath, "user", undefined, plugin.label), }); } diff --git a/packages/coding-agent/test/scient/codex-plugins.test.ts b/packages/coding-agent/test/scient/codex-plugins.test.ts index 880d9e0b9d..e8b247b94d 100644 --- a/packages/coding-agent/test/scient/codex-plugins.test.ts +++ b/packages/coding-agent/test/scient/codex-plugins.test.ts @@ -169,10 +169,10 @@ describe("installed Codex plugins", () => { transport: "stdio", }); // Codex passes its own short list plus the server's env_vars, never the whole environment. - expect(byName.get("research:papers")?.env).toBeUndefined(); - expect(byName.get("research:papers")?.envInherit).toEqual( - expect.arrayContaining(["PATH", "HOME", "CODEX_PLUGIN_TEST_TOKEN"]), - ); + const papers = byName.get("research:papers"); + expect(papers?.envInherit).toEqual([]); + expect(papers?.env).toMatchObject({ PATH: process.env.PATH, CODEX_PLUGIN_TEST_TOKEN: "forwarded-value" }); + expect(papers?.env?.CODEX_PLUGIN_TEST_PAT).toBeUndefined(); expect(byName.get("research:tracker")).toMatchObject({ url: "https://mcp.example.test/mcp", headers: { Authorization: "Bearer pat-value" }, @@ -384,16 +384,132 @@ describe("installed Codex plugins", () => { expect(warnings).toContainEqual(expect.stringContaining("Ignoring mcpServers path outside linked@market")); }); - it("keeps two marketplaces' same-named plugins apart", async () => { + it("keeps same-named plugins from different marketplaces apart, whatever their names", async () => { const server = { mcpServers: { api: { command: "node" } } }; await install("twin@alpha", { ".codex-plugin/plugin.json": { name: "twin" }, ".mcp.json": server }); await install("twin@beta", { ".codex-plugin/plugin.json": { name: "twin" }, ".mcp.json": server }); + // Its name is what `twin` qualified with `alpha` would look like if dots qualified names. + await install("twin.alpha@gamma", { ".codex-plugin/plugin.json": { name: "twin.alpha" }, ".mcp.json": server }); expect([...(await load()).byName.keys()].filter(name => name.startsWith("twin")).sort()).toEqual([ "twin.alpha:api", - "twin.beta:api", + "twin:alpha:api", + "twin:beta:api", ]); }); + it("keeps startup dotenv values out of the launch environment after the agent changes folders", async () => { + const first = temp.join("first-project"); + const second = temp.join("second-project"); + await Bun.write(path.join(first, ".env"), "CODEX_HOME=/from/dotenv\nCODEX_PLUGIN_TEST_SECRET=dotenv-secret\n"); + await Bun.write(path.join(first, ".env.local"), "CODEX_PLUGIN_TEST_LOCAL=local-secret\n"); + await fs.mkdir(second, { recursive: true }); + // A fresh process, so the dotenv files load at its own startup in `first`. + const utils = path.join(import.meta.dir, "../../../utils/src/index.ts"); + const script = [ + `const { getLaunchEnv, setProjectDir } = await import(${JSON.stringify(utils)});`, + `setProjectDir(${JSON.stringify(second)});`, + "const env = getLaunchEnv();", + "console.log(JSON.stringify([Bun.env.CODEX_HOME, env.CODEX_HOME, env.CODEX_PLUGIN_TEST_SECRET, env.CODEX_PLUGIN_TEST_LOCAL, env.CODEX_PLUGIN_TEST_PAT]));", + ].join("\n"); + // With --no-env-file only the agent's own loader reads .env; without it Bun autoloads + // .env and .env.local too, as when the agent runs from source. + for (const flags of [["--no-env-file"], []]) { + const run = Bun.spawnSync([process.execPath, ...flags, "-e", script], { + cwd: first, + env: { PATH: process.env.PATH, HOME: temp.join("home"), CODEX_PLUGIN_TEST_PAT: "exported" }, + }); + // JSON writes a missing value as null. + expect(JSON.parse(run.stdout.toString().trim().split("\n").at(-1) ?? "null")).toEqual([ + "/from/dotenv", + null, + null, + null, + "exported", + ]); + } + }); + + it("follows Codex on disabled declarations, withheld variables and linked package folders", async () => { + await install( + "rules@market", + { + ".codex-plugin/plugin.json": { name: "rules" }, + ".mcp.json": { + mcpServers: { + off: { command: "node", enabled: false }, + retired: { command: "node", args: ["retired.mjs"] }, + numeric: { command: 7, url: "https://mcp.example.test/mcp" }, + withheld: { command: "node", env: { NODE_REPL_AUTH_TOKEN: "x", KEEP: "y" } }, + }, + }, + }, + ["enabled = true", '[plugins."rules@market".mcp_servers.retired]', 'auth = "ema_auth"'], + ); + const outside = temp.join("outside-manifest"); + await Bun.write(path.join(outside, "plugin.json"), JSON.stringify({ name: "linkedfolder" })); + const linkedRoot = await install("linkedfolder@market", { + ".mcp.json": { mcpServers: { x: { command: "node" } } }, + }); + await fs.symlink(outside, path.join(linkedRoot, ".codex-plugin"), "dir"); + clearFsCache(); + const { byName, warnings } = await load(); + expect(byName.get("rules:off")?.enabled).toBe(false); + expect(byName.get("rules:retired")?.enabled).toBe(false); + expect(byName.has("rules:numeric")).toBe(false); + expect(warnings).toContainEqual(expect.stringContaining('"numeric" of rules@market: invalid command')); + expect(byName.get("rules:withheld")?.env).toMatchObject({ KEEP: "y" }); + expect(byName.get("rules:withheld")?.env?.NODE_REPL_AUTH_TOKEN).toBeUndefined(); + expect(byName.has("linkedfolder:x")).toBe(false); + expect(warnings).toContainEqual( + expect.stringContaining("Ignoring linkedfolder@market: .codex-plugin is not a folder"), + ); + }); + + it("drops a skill linked out of a real skills folder", async () => { + const outside = temp.join("outside-skill"); + await writeSkill(outside, "escaped"); + const root = await install("mixed@market", { ".codex-plugin/plugin.json": { name: "mixed" } }); + await writeSkill(root, "inside"); + await fs.symlink(path.join(outside, "skills", "escaped"), path.join(root, "skills", "escaped"), "dir"); + clearFsCache(); + const names = (await skills()).map(skill => skill.name); + expect(names).toContain("inside"); + expect(names).not.toContain("escaped"); + }); + + it("applies Codex's rules to an Agent Plugins package's mcp.json", async () => { + restoreEnvValue("CODEX_PLUGIN_TEST_PAT", "pat-value"); + const schema = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json"; + await install("portable2@market", { + "plugin.json": { $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", name: "portable2" }, + "mcp.json": { + $schema: schema, + mcpServers: { + events: { type: "sse", url: "https://mcp.example.test/sse" }, + local: { + type: "stdio", + command: "node", + env: { CODEX_PLUGIN_TEST_PAT: "$" + "{CODEX_PLUGIN_TEST_PAT}", MODE: "x" }, + }, + }, + }, + // The package's legacy declaration forwards the variable the placeholder stands for. + ".codex-plugin/plugin.json": { name: "portable2" }, + ".mcp.json": { mcpServers: { local: { command: "node", env_vars: ["CODEX_PLUGIN_TEST_PAT"] } } }, + }); + const linked = await install("linkedmcp@market", { + "plugin.json": { $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", name: "linkedmcp" }, + "real-mcp.json": { $schema: schema, mcpServers: { y: { type: "stdio", command: "node" } } }, + }); + await fs.symlink(path.join(linked, "real-mcp.json"), path.join(linked, "mcp.json")); + clearFsCache(); + const { byName, warnings } = await load(); + expect(byName.has("portable2:events")).toBe(false); + expect(byName.get("portable2:local")?.env).toMatchObject({ CODEX_PLUGIN_TEST_PAT: "pat-value", MODE: "x" }); + expect(byName.has("linkedmcp:y")).toBe(false); + expect(warnings).toContainEqual(expect.stringContaining("linkedmcp@market: mcp.json is not a regular file")); + }); + it("reads Codex's manifest precedence: a root Agent Plugins manifest, then the legacy folders", async () => { await install("portable@market", { "plugin.json": { $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", name: "portable" }, diff --git a/packages/utils/src/env.ts b/packages/utils/src/env.ts index a6d5b777e5..6e9654538f 100644 --- a/packages/utils/src/env.ts +++ b/packages/utils/src/env.ts @@ -383,6 +383,30 @@ export function withOmpOtelEnv(fn: () => T): T { } } +// scient(SA-CODEX-PLUGINS): begin - Codex plugins read only the environment the agent was launched with. +const launchProjectDir = getProjectDir(); +let launchDotenvValues: ReadonlySet | undefined; + +/** + * The environment the agent was launched with, whichever folder it works in now: the exec + * environment when it is known (procfs, `--no-env-file`), else the environment without any value + * the launch folder's dotenv files (all those Bun autoloads) or the agent's own `.env` files + * (agent, config root, home) define. Codex reads its home, its plugins' credentials and their + * servers' variables from its launch environment alone; so does the agent when it runs them. + */ +export function getLaunchEnv(): Record { + if (launchEnvValues) return Object.fromEntries(launchEnvValues); + launchDotenvValues ??= new Set(getDotenvEnvValues(launchProjectDir, Bun.env)); + const result: Record = {}; + for (const key in Bun.env) { + const value = Bun.env[key]; + if (value === undefined || launchDotenvValues.has(value)) continue; + if ([projectEnv, agentEnv, piEnv, homeEnv].some(file => file[key] === value)) continue; + result[key] = value; + } + return result; +} +// scient(SA-CODEX-PLUGINS): end for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) { for (const key in file) { // scient(SA-ROOT): begin - A host-assigned root owns the agent's own variables. diff --git a/scripts/scient/divergences.json b/scripts/scient/divergences.json index 3d21582963..eaf8da666b 100644 --- a/scripts/scient/divergences.json +++ b/scripts/scient/divergences.json @@ -520,7 +520,7 @@ }, "SA-CODEX-PLUGINS": { "status": "active", - "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of the Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex; CODEX_HOME from the launch environment, never a project's .env), layered over /etc/codex/config.toml, a table without enabled taking [plugins._default]. It reads the version Codex runs in $CODEX_HOME/plugins/cache/// with Codex's manifest precedence: a root Agent Plugins plugin.json (its skills/ and mcp.json, read under that standard), else .codex-plugin, .claude-plugin or .cursor-plugin/plugin.json, a link or non-file there rejecting the plugin. A server must declare exactly one transport with only that transport's Codex fields; package files, cwd and relative commands must stay inside the symlink-resolved package. Stdio servers inherit only Codex's variable list (HOME, PATH and the like, certificate-bundle variables, and the server's env_vars: MCPServer.envInherit), with literal env values; HTTP servers carry literal, origin-locked headers, bearer_token_env_var and env_http_headers read from the launch environment, and their OAuth client settings, scopes and oauth_resource. Servers are named :, or .: when two enabled plugins share a name; a plugin's mcp_servers..enabled = false disables one. Skipped with a warning while siblings load: servers whose tools Codex narrows (enabled_tools, or a non-empty disabled_tools), which Scient Agent cannot enforce, and servers with malformed or unsupported fields (http_headers_helper, auth other than oauth). OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded, and nothing loads while an organization policy manages Codex (/etc/codex/requirements.toml or managed_config.toml, macOS managed preferences for com.openai.codex, %ProgramData%\\OpenAI\\Codex\\requirements.toml). Not applied: Codex profiles, project .codex/config.toml layers and cloud-delivered config.", + "contract": "The opt-in user source codex-plugins (enabledProviders or SCIENT_AGENT_ENABLE_SOURCES; codex does not imply it) loads the skills and MCP servers of the Codex plugins enabled in $CODEX_HOME/config.toml (default ~/.codex), merged at every depth over Codex's system config.toml (/etc/codex, or OpenAI\\Codex in ProgramData), a table without enabled taking [plugins._default]. CODEX_HOME, header credentials and servers' variables come from getLaunchEnv() (packages/utils env.ts: the exec environment when known, else the environment without any value the launch folder's Bun-autoloaded dotenv files or the agent's own .env files define, whichever folder the agent works in now), never a .env file. It reads the version Codex runs in $CODEX_HOME/plugins/cache/// with Codex's manifest precedence: a root Agent Plugins plugin.json (its skills/ and a regular-file mcp.json, read under that standard, sse servers left out, a stdio server taking the env_vars its package's legacy declaration of it adds), else .codex-plugin, .claude-plugin or .cursor-plugin/plugin.json, a link or non-file there or a linked folder holding it rejecting the plugin. A legacy server must declare exactly one transport with correctly typed fields and only that transport's Codex fields; package files, each skill, cwd and relative commands must stay inside the symlink-resolved package. A stdio server's env is what Codex would give it (its variable list, certificate bundles as absolute paths, its env_vars, then its literal env, without Codex's non-inheritable names) and it inherits nothing else (MCPServer.envInherit = []); HTTP servers carry literal, origin-locked headers, bearer_token_env_var and env_http_headers values, and their OAuth client settings, scopes and oauth_resource. Servers are named :, or :: when two enabled plugins share a name. enabled = false in a declaration or in the plugin's mcp_servers. table, or auth = \"ema_auth\" there, disables a server. Skipped with a warning while siblings load: servers whose tools Codex narrows (enabled_tools, or a non-empty disabled_tools), which Scient Agent cannot enforce, and servers with malformed or unsupported fields (http_headers_helper, auth other than oauth). OpenAI host-only plugins (browser, chrome, codex-app-tools, computer-use, unified-computer-use from openai-bundled), servers launched by computer-use-client-launcher or signed in with Codex's ChatGPT session, app references and hooks are not loaded, and nothing loads while an organization policy manages Codex (requirements.toml in the system folder or at the Windows Group Policy RequirementsPath, /etc/codex/managed_config.toml, macOS managed preferences for com.openai.codex). Not applied: Codex profiles, project .codex/config.toml layers and cloud-delivered config.", "owned": [ "packages/coding-agent/src/scient/codex-plugins.ts", "packages/coding-agent/test/scient/codex-plugins.test.ts" @@ -532,7 +532,8 @@ "packages/coding-agent/src/mcp/config.ts", "packages/coding-agent/src/mcp/transports/stdio.ts", "packages/coding-agent/src/mcp/types.ts", - "packages/coding-agent/CHANGELOG.md" + "packages/coding-agent/CHANGELOG.md", + "packages/utils/src/env.ts" ], "verification": [ "bun --cwd=packages/coding-agent test test/scient/codex-plugins.test.ts"