Skip to content

scient: load installed Codex plugins' skills and MCP servers - #79

Merged
yaacovcorcos merged 30 commits into
mainfrom
claude/codex-plugins-20261121
Nov 22, 2026
Merged

yaacovcorcos merged 30 commits into
mainfrom
claude/codex-plugins-20261121

Conversation

@yaacovcorcos

Copy link
Copy Markdown
Contributor

Scient Agent now loads the skills and MCP servers of plugins installed and enabled in Codex, so a plugin added to Codex also works in Scient Agent.

  • New discovery source codex-plugins. It reads $CODEX_HOME/config.toml [plugins."<name>@<marketplace>"] and uses the same package version Codex runs from plugins/cache. Skills go through the existing skill reader and MCP servers through the existing Codex MCP mapping (env_vars, bearer_token_env_var, timeouts, package-relative command/cwd). Servers are named <plugin>:<server>.
  • It is opt-in through SCIENT_AGENT_ENABLE_SOURCES=codex-plugins or enabledProviders. --runtime-info lists it under enableSources so a host can check for it.
  • Left out: plugins that need OpenAI's host (browser, chrome, computer-use, unified-computer-use, codex-app-tools), servers launched by computer-use-client-launcher (Messages) or with auth: "chatgpt", .app.json app references (the ChatGPT-apps route already covers them), and hooks.
  • Ledger entry: SA-CODEX-PLUGINS.

Tests: the new codex-plugins tests plus the affected discovery, runtime-info and claude-plugins tests (52) pass. Typecheck, oxlint, oxfmt and the divergence check are clean. No plugin MCP server was started in testing.

Desktop side: ScientFactory/scient-desktop#1061 sets the source and shows Codex plugins as working with Scient Agent when the agent supports it.

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
…er 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.
@yaacovcorcos

Copy link
Copy Markdown
Contributor Author

0af9eab fixes two findings from a holistic Codex review:

  • A Codex plugin MCP server is no longer imported with more tools than Codex allows. A server whose .mcp.json entry or [plugins."<id>".mcp_servers.<name>] policy sets enabled_tools (or a non-empty disabled_tools) is skipped with a warning, because Scient Agent's MCP servers have no tool filter.
  • A malformed server is skipped with a warning, and its siblings still load. Before, it rejected the whole source.

New tests cover both. Desktop (ScientFactory/scient-desktop#1061) also now honors disabledProviders containing codex-plugins.

Codex review of 0af9eab:
- 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 <plugin>.<marketplace>.
- 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.
…ment and server rules

Second Codex review of 4d90a48:
- 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 <plugin>:<marketplace>, which no plugin name can collide with.
@yaacovcorcos
yaacovcorcos force-pushed the claude/codex-plugins-20261121 branch from ce4418f to e53bde7 Compare November 22, 2026 08:38
…, overlay, skill containment, fail-closed policy

Third Codex review of e53bde7:
- getLaunchEnv() returns only an authoritative snapshot (procfs, --no-env-file, or the compiled
  binary's environment before the agent's .env files, told by its bundled module URL); otherwise
  nothing loads, with a warning. The loader takes it through filterProcessEnv.
- An ema_auth key in a plugin's mcp_servers.<name> table disables the server; a server whose
  tools Codex asks about (prompt, writes or an unknown approval mode) is skipped.
- Agent Plugins stdio servers take env_vars only from a valid .codex-plugin declaration of the
  same server as a valid stdio server; Codex's non-inheritable names match in any case.
- Skills are scanned as Codex scans them (recursive for legacy plugins), each folder and SKILL.md
  contained before it is read, and carry containRoot for skill://.
- A policy location that cannot be checked counts as managed; Windows uses the ProgramData known
  folder and managed_config.toml in CODEX_HOME.
- Tests stand in for the launch environment instead of relying on mutations after Bun starts.
… field types and paths, fail-closed Windows probe

Fourth Codex review of 65ffa2e:
- getLaunchEnv() trusts the compiled binary only through __SCIENT_AGENT_NO_DOTENV__, which only
  compile-binary.ts defines (beside autoloadDotenv false), and no run given an explicit --env-file.
- A server with an ema_auth policy entry is left out with a warning, so enabledServers cannot start it.
- Legacy manifests and servers must have the field types Codex accepts (a .codex-plugin overlay too),
  manifest paths must be ./-relative without .., and a server bound to another Codex environment is
  skipped.
- Windows reads the ProgramData known folder and the 64-bit RequirementsPath in one PowerShell query;
  a failed query counts as managed. A leftover CODEX_HOME/managed_config.toml no longer does, as in Codex.
- Not changed: auto approval defers to the session's approval policy in Codex
  (mcp_permission_prompt_is_auto_approved), as it does to Scient Agent's approval mode here.
…lbacks, tool-name suffixes, strict Windows probe

Fifth Codex review of a507587:
- The Windows probe stops on any error and counts only an explicit success as no policy; a spawn
  failure counts as managed.
- A server whose tools Codex hides (non-empty omit_tools_from, values checked) is skipped.
- The user's [[skills.config]] rules apply to plugin skills in Codex's order (canonical path or name).
- Durations must be ones Rust's Duration::try_from_secs_f64 takes, so a negative startup_timeout_sec
  rejects the declaration and its env_vars.
- Manifest paths Codex drops fall back to skills/ and .mcp.json, as in Codex.
- Servers whose names would give their tools the same names take a stable -<6 hex> suffix.
…strict [plugins], u64 timeouts, POSIX paths

Sixth Codex review of 24ee20a:
- Server names no longer take a suffix that depends on other plugins, so disabledServers and
  enabledServers keep matching; the normalized tool-name collision stays a documented gap.
- [[skills.config]] names match <manifest name>:<skill>, as Codex namespaces plugin skills.
- A merged [plugins] table with a field of a type Codex rejects loads nothing, as in Codex.
- startup_timeout_ms must fit a u64.
- A backslash separates manifest path parts only on Windows, and rooted paths are dropped.
…rs, stable ids, Codex skill names, app and limit checks

Seventh Codex review of e6abb5a:
- CODEX_HOME is used exactly as set; it must be a folder and is canonicalized, as in Codex.
- [features] plugins anything but true turns every plugin off.
- A plugin server the config's own [mcp_servers] names is left out: Codex runs that entry instead.
- [[skills.config]] names match only <manifest name>:<skill>, the package folder standing in for a
  blank manifest name.
- auto_provision and apps (AppConfig, its tools and links) are type-checked with the rest of [plugins].
- A server with a per-tool output_token_limit is skipped.
- Servers are always named <plugin>@<marketplace>:<server> and skills carry the plugin ID, so no
  other plugin's arrival renames them and saved settings keep matching.
…nd duplicates, Codex skill names

Eighth Codex review of c3a232e:
- Each imported HTTP server signs in under its own credential (mcpOAuthServerCredentialId:
  mcp_oauth:server:<profile>:<name>:<url>), never another server's at the same URL; the profile and
  URL parsers read it. Reauthorization takes its values literally, asks for its configured scopes
  (empty meaning none, discovery's scope dropped) and oauth_resource first, stores the credential
  under that id and writes nothing back.
- A server Codex turns off (enabled = false in its declaration or policy) is left out, so
  enabledServers cannot start it.
- Servers two enabled plugins declare under one name are left out: Codex runs only one.
- Skill names collapse their whitespace as Codex's parser does before rules match them.
@yaacovcorcos
yaacovcorcos force-pushed the claude/codex-plugins-20261121 branch from fbf45cf to c9eaa43 Compare November 22, 2026 10:46
…er precedence, fallback skill names

Ninth Codex review of c9eaa43:
- Reconnecting a server bound to its own sign-in keeps its auth block and headers, and matches only
  a manager entry with the same credential id.
- TUI /mcp unauth removes only a bound server's own credential and rewrites no config.
- A server declaring bearer_token_env_var is bound as an apikey: no OAuth sign-in answers it and
  reauthorization refuses it, as Codex never offers it OAuth login; a configured Authorization header
  wins over a bound sign-in.
- A skill's folder-name fallback collapses Unicode whitespace too.
- Native reauthorization keeps the flow's invalid-URL diagnostic.
…earer, header order, Unicode selector trim, toggles

Tenth Codex review of 084a5de:
- mcp/config.ts drops a server-bound credential id from any definition but a codex-plugins one whose
  name and URL give it; lookup answers a bound id only for its own URL under the active profile;
  reauthorization and TUI /mcp unauth act on it only for a discovered server whose name and URL give it.
- A server whose bearer_token_env_var is unset or empty is skipped, as Codex refuses to start it.
  Headers are set in Codex's order (static, environment, bearer), each replacing one of the same name
  in any case.
- [[skills.config]] name selectors are trimmed of Unicode whitespace.
- /mcp enable and disable toggle an imported server through disabledServers.
…ath, tolerate malformed ids, Codex header and namespace rules

Eleventh Codex review of 97a0826:
- trustedMcpAuth / withTrustedMcpAuth (mcp/oauth-flow.ts) keep a server-bound credential id only on the
  server the codex-plugins source imported under it; applied in config conversion, at every MCPManager
  connection, and in /mcp test (TUI and ACP).
- isMcpOAuthServerCredentialId tolerates non-string ids, so a malformed native credentialId no longer
  aborts MCP discovery.
- Headers follow Codex: names must be HTTP tokens and values tab or visible ASCII, else skipped; an
  environment value is used as set unless only whitespace; an invalid bearer skips the server.
- A manifest name of Unicode whitespace alone is blank, so the package folder names its skills.
…-ins, tool timeout cap

- /mcp test binds only the selected definition's own source; config-file helpers never bind; a live imported server's sign-in challenge is answered for that live definition.
- A server-bound sign-in made with another OAuth client than the configured one is not used.
- tool_timeout_sec is a hard cap on tool calls (toolTimeoutMs) that call arguments never extend; tool_timeout_sec = 0 skips the server.
…ient IDs, Codex tool-timeout default

- The manager judges a server-bound sign-in only by the source supplied with that definition; /mcp test syncs the tested definition with its own source.
- The client-ID check compares exact IDs for confidential clients only and leaves non-bound lookups untouched; imports with a client secret but no ID, a blank secret, or a padded client ID are skipped.
- Imported tool calls default to Codex's 300 s cap, and the HTTP transport carries the remaining cap through the auth refresh and retry.
… deadline per tool call

- An empty client_secret stays present and is rejected; authorization_server_issuer and token_endpoint_auth_method skip the server; a padded secret skips it like a padded client ID.
- A bound confidential sign-in is used only when its stored client ID and secret both match the configured ones, since refresh sends the stored secret.
- MCPRequestOptions.deadlineAt carries one deadline through the HTTP auth retry and the tool bridge's auth reconnect, 503/expired-session reconnect and replay; a reconnect pending at the deadline ends the call.
…nfig

- Hosts and tests hand the tool bridge connections without config; toolCallDeadline read connection.config unconditionally and threw (CI: tool-bridge-structured-content).
…sh, monotonic tool deadline

- OAuth aliases fold by key presence before type checks; blank checks use Rust's Unicode White_Space.
- Server-bound sign-ins store no client secret; refresh and re-sign-in send only the secret the current definition configures.
- Tool-call deadlines and progress restarts run on performance.now(); no refresh, retry or replay starts once the deadline is spent.
…ut stored secrets, spent-deadline sends, Codex server names

- Server-bound code exchange and refresh refuse redirects; refreshMCPOAuthToken reads trailing options even without a resource.
- refreshManagedMcpOAuthCredential enforces the bound-row secret rule for every caller, the auth broker included.
- stdio writes no capped call whose cap ran out before sending; the bridge starts no reconnect once the deadline is spent.
- Declared server names Codex's validate_mcp_server_name rejects are skipped.
- scient-agent mcp list prints each MCP server's status (connected, needs-auth, failed, pending), plugin ID, tool count and whether a browser sign-in serves it; mcp login <name> runs the /mcp reauth flow and prints the authorization URL for the host to open.
- A bound server refused by an authorization server that registers only approved clients (Figma) says so in plain words.
- RPC sessions reconnect a disconnected sign-in server before a prompt once its stored sign-in is new or changed, so a sign-in from the host reaches running conversations without a restart.
- --runtime-info lists mcp in hostCommands; ledger, SCIENT.md and CHANGELOG updated.
…s unblocked

- mcp list and mcp login print only messages written here (an HTTP status at most), never a server's or authorization server's text, which can echo a token, code or secret.
- Both commands bind the user's settings, so enabledProviders and disabledProviders apply as in a conversation.
- mcp login signs in to the definition discovery selected: an imported server's from the manager, never a same-named config entry it shadowed.
- McpSignInPickup is seeded with the session's own sign-ins, runs one at a time, holds a prompt at most 1.5 s and finishes in the background; a broker is re-read at most every 10 s.
- A bound server needing its client secret at every refresh is not offered or signed in to while a broker holds the sign-ins.
…elected entry

- mcp login withholds a sign-in page whose resource carries a user name, password or query (a server's own key) from the host and stops the flow.
- An ordinary server signs in from the file discovery read it from, only when that entry expanded matches the selected definition; a definition no file holds signs in as discovered.
- The sign-in pickup treats a malformed definition's lookup as no sign-in, so seeding cannot stop RPC startup.
…ansport

- A Cursor or Claude entry that gives only a URL reaches reauthorization with the transport discovery inferred, keeping its raw placeholders for write-back; before, reauthorization refused it as stdio.
- A server a browser sign-in cannot serve (turned off, local, own key, broker without its secret) is refused before reauthorization in words written here; a refusal from the shared engine, whose text can quote a server's expanded arguments, is printed as a fixed message.
- A server address with a user name, password or query is refused before reauthorization starts, so no request carries it as a resource.
- A sign-in page whose own address carries a user name or password is withheld; its query (OAuth parameters, the sign-in server's settings) is kept.
… address

- mcp login checks the discovered definition (turned off, no browser sign-in, broker without its secret, keyed address) before any connection, so not even a refresh of a stored sign-in carries a keyed address.
- mcp list offers no sign-in for a server whose address carries a user name, password or query.
- canSignIn reads a config file's auth: null as no auth block, as the credential lookup does, so seeding the sign-in pickup cannot throw.
… mcp output fully flushed

- McpSignInPickup reconnects each newly signed-in server on its own, never twice at once, and publishes tools as each connects, so a stalled server holds up no other.
- RPC runs the pickup before skill dispatch, so a skill invoked right after a sign-in sees the new tools.
- mcp list and mcp login wait for stdout to drain before exiting; a failed write exits nonzero.
…ps under way; steering unaffected

- mcp list and mcp login write each JSON line with Bun.write(Bun.stdout), in order, and exit only after the last one resolved; a failed write exits nonzero.
- A later prompt joins a sign-in re-read and any reconnect still under way, within its own wait, without starting a second attempt.
- RPC steer and follow-up keep their previous admission path; the pickup runs after them, before skill and builtin dispatch.
…it starts

- After the shared re-read, a pickup joins a reconnect another prompt started from that read instead of skipping it.
@yaacovcorcos
yaacovcorcos merged commit 63f07e5 into main Nov 22, 2026
42 of 44 checks passed
@yaacovcorcos
yaacovcorcos deleted the claude/codex-plugins-20261121 branch November 22, 2026 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant