diff --git a/SCIENT.md b/SCIENT.md index ebaeeac3cf..f19dd7a614 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`, 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/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..a621a19345 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`), 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 ### 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/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/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/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 new file mode 100644 index 0000000000..8241154ad0 --- /dev/null +++ b/packages/coding-agent/src/scient/codex-plugins.ts @@ -0,0 +1,756 @@ +/** + * Installed Codex plugins (SA-CODEX-PLUGINS). + * + * Codex lists plugins in `$CODEX_HOME/config.toml` (default `~/.codex`) as + * `[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 { 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"; +import { type Skill, skillCapability } from "../capability/skill"; +import type { LoadContext, LoadResult } from "../capability/types"; +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"; +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"; + +/** + * 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, 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"]; + +/** + * 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 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). Nothing else, API keys included, reaches the server. + */ +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", + "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", +]; +/** 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 = [ + "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; + name: string; + marketplace: string; + /** + * 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; + /** `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 any `.env` file's 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); +} + +/** 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: 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; + } +} + +/** 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, + id: string, + warnings: string[], +): 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()) { + 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 | null> { + 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 = 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 { + 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; + } +} + +/** Codex's layer merge: tables merge key by key at every depth, and the higher layer's other values win. */ +function mergeLayers(lower: Record, 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"; +} + +/** + * 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. + */ +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 = [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( + path.join(managed, "com.openai.codex.plist"), + path.join(managed, os.userInfo().username, "com.openai.codex.plist"), + ); + } + 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: 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 (${policy}), which Scient Agent cannot apply; no Codex plugins load`, + ); + return { plugins: [], warnings, env }; + } + // 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 }; + 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( + Object.entries(table).map(([id, config]) => { + 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; + }), + ); + const found = read.filter(plugin => plugin !== null); + 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: shared.has(plugin.name) ? `${plugin.name}:${plugin.marketplace}` : plugin.name, + })); + return { plugins, warnings, env }; +} + +/** 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 = 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.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 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]; + const dirs = new Set(); + for (const entry of entries) { + const dir = await packagePath(plugin, entry, "skills", warnings); + if (dir !== null) dirs.add(dir); + } + 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}`); + } + } + }), + ); + 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 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; +} + +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"); + +/** 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 }; + +/** + * 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 { + 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 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" }; + 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` }; + // 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[] }), + env: stdioEnv(env, forwarded, server.env as Record | undefined), + envPolicy: "literal", + envInherit: [], + cwd, + ...common, + }, + }; + } + + 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 = envValue(env, name)?.trim(); + if (value) headers[header] = value; + } + 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; + 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 } }), + ...common, + }, + }; +} + +/** 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 = manifest.mcpServers; + let parsed: unknown = declared; + let sourcePath = manifestPath; + if (!isRecord(declared)) { + 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((await readFile(file)) ?? ""); + } 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; +} + +/** + * 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 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(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}`); + 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}`)); + 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) { + 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: [], + }; + } + 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> { + if (!isUserSourceEnabled(PROVIDER_ID, ctx)) return { items: [] }; + const { plugins, warnings, env } = await listCodexPlugins(ctx); + 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, 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)) { + if (!isRecord(server)) continue; + const skip = `[codex-plugins] Skipping MCP server "${serverName}" of ${plugin.id}`; + const reason = hostOnlyReason(server); + if (reason !== undefined) { + 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; + } + let mapped: Mapped; + try { + mapped = standard !== null ? { server } : await mapLegacyServer(plugin, server, env); + } catch (error) { + mapped = { error: String(error) }; + } + if ("error" in mapped) { + warnings.push(`${skip}: ${mapped.error} (${sourcePath})`); + continue; + } + items.push({ + name: `${plugin.label}:${serverName}`, + ...mapped.server, + // 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), + }); + } + } + 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..e8b247b94d --- /dev/null +++ b/packages/coding-agent/test/scient/codex-plugins.test.ts @@ -0,0 +1,576 @@ +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 { 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", + "CODEX_PLUGIN_TEST_SECRET", +]; + +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"); + // The loader reports symlink-resolved paths (macOS temp folders live under /private). + researchRoot = await fs.realpath(researchRoot); + researchSkill = await fs.realpath(researchSkill); + 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, + envPolicy: "literal", + timeout: 30_000, + transport: "stdio", + }); + // Codex passes its own short list plus the server's env_vars, never the whole environment. + 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" }, + headerPolicy: "origin-locked", + transport: "http", + }); + // 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 fs.realpath(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 (${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 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: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" }, + ".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/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/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 49188463ad..eaf8da666b 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,27 @@ "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 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" + ], + "upstream": [ + "packages/coding-agent/src/capability/index.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", + "packages/utils/src/env.ts" + ], + "verification": [ + "bun --cwd=packages/coding-agent test test/scient/codex-plugins.test.ts" + ] } } }