Repository navigation
feat!: emit Agent Plugins packages from codex and add an agent-plugins target - #38
Merged
Merged
Conversation
steve-calvert-glean
added
breaking
steve-calvert-glean
force-pushed
the
feat/agent-plugins-format
branch
from
October 2, 2026 22:28
9001c2d to
75988e2
Compare
steve-calvert-glean
force-pushed
the
feat/mcp-dialects
branch
from
October 2, 2026 22:28
875874e to
a82431a
Compare
steve-calvert-glean
added a commit
that referenced
this pull request
Oct 19, 2026
Fixes from a self-review of the #37 + #38 stack. - F3: validate parsed SKILL.md frontmatter with gray-matter's default engines, so a ---js block ran through eval(). A shared parseMatter() helper now refuses the js and javascript engines, for every target. - F13: build could emit a plugin.json that validate rejects (a bad extension namespace, extra author fields). placeClientFields now runs the same manifest checks and fails the build. - F6: native dialects kept an Agent Plugins "./server" cwd as a bare relative path, which clients resolve against the user's project. It now becomes ${<root>}/server, like a ./ command. - F8: the agent-plugins target dropped scripts/ by default while still emitting MCP commands that point into it. scripts is now a default component, as it is for codex. - F1: validate re-rendered mcp.json and kept only render errors, so a server without "type" or with "http" passed. It now reports any server that is not already in normalized Agent Plugins form. - F15: add a test for default-format codex output with hooks/. - F9, F17, F18, F21: README upgrade note covers the MCP build errors, the MCP rules list is complete, install-snippet docs name agent-plugins, and CLAUDE.md agrees with CONFORMANCE.md on schemas.
…s target Agent Plugins 1.0 standardizes the plugin package: a closed root plugin.json, skills/, mcp.json, and reverse-domain extension namespaces. OpenAI now prefers it for Codex and ChatGPT and keeps .codex-plugin/plugin.json only as a fallback. - src/agent-plugins.ts: the package module. It builds the portable manifest, moves client fields under extensions[<namespace>], and validates a package against the spec (closed manifest, plugin name, mcp.json, and skill names per the Agent Skills spec). - codex: emits a package by default (root plugin.json with OpenAI settings under extensions.com.openai, plus mcp.json) and keeps .agents/plugins/marketplace.json. format: "legacy" keeps the .codex-plugin layout; validate detects the layout per plugin. - agent-plugins: a new standalone target that writes portable packages only, with no marketplace and no client profile. Client-only content kinds are a config error; non-portable manifest fields are a build error. - Targets can now choose a definition per config (forConfig) and post- process the merged manifest (finalizeManifest). - Vendors the official 1.0.0 schemas (with provenance) as the conformance oracle for codex and agent-plugins. BREAKING CHANGE: the codex target's default output layout changes from .codex-plugin/plugin.json + .mcp.json to an Agent Plugins package (plugin.json + mcp.json). Set `format: "legacy"` on the codex target to keep the previous layout. MCP config and skill names that Agent Plugins clients would skip now fail build or validate.
Fixes from a self-review of the #37 + #38 stack. - F3: validate parsed SKILL.md frontmatter with gray-matter's default engines, so a ---js block ran through eval(). A shared parseMatter() helper now refuses the js and javascript engines, for every target. - F13: build could emit a plugin.json that validate rejects (a bad extension namespace, extra author fields). placeClientFields now runs the same manifest checks and fails the build. - F6: native dialects kept an Agent Plugins "./server" cwd as a bare relative path, which clients resolve against the user's project. It now becomes ${<root>}/server, like a ./ command. - F8: the agent-plugins target dropped scripts/ by default while still emitting MCP commands that point into it. scripts is now a default component, as it is for codex. - F1: validate re-rendered mcp.json and kept only render errors, so a server without "type" or with "http" passed. It now reports any server that is not already in normalized Agent Plugins form. - F15: add a test for default-format codex output with hooks/. - F9, F17, F18, F21: README upgrade note covers the MCP build errors, the MCP rules list is complete, install-snippet docs name agent-plugins, and CLAUDE.md agrees with CONFORMANCE.md on schemas.
Resolves the self-review findings that needed a decision. - F2: findPackages stopped at depth 4, so validate missed a package at a valid deeper plugin path. The depth cap is gone; the walk still stops at each package and skips node_modules and dot-directories. - F7: a plugin.json that failed to parse or declared another $schema was not treated as a package. Codex then blamed a missing .codex-plugin/plugin.json, and the agent-plugins target skipped the plugin. Both now validate the root plugin.json and report it. - F10: the README now says Cursor output drops "type" from stdio and HTTP servers, instead of claiming native config is always unchanged.
steve-calvert-glean
force-pushed
the
feat/agent-plugins-format
branch
from
October 19, 2026 22:49
1181bde to
4fcabd3
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second of three PRs adding Agent Plugins support. Stacked on #37 (the MCP module); review that first. This PR's base is
feat/mcp-dialects.Why
Agent Plugins 1.0 standardizes the plugin package: a closed root
plugin.json,skills/,mcp.json, and reverse-domain extension namespaces. It deliberately leaves out marketplaces, hooks, agents, commands, and rules. OpenAI's packaging docs now prefer it for Codex and ChatGPT and keep.codex-plugin/plugin.jsononly as a compatibility fallback. Copilot/VS Code loads it too, and Cursor loads the skills and MCP parts.What
src/agent-plugins.ts, the package module. Builds the portable manifest, moves client fields underextensions[<namespace>], and validates a package against the spec: closed manifest, plugin name (§5.5),mcp.json(via feat: render MCP config into each target's MCP dialect #37'sagent-pluginsdialect), and each skill's name per the Agent Skills spec, which must also match its directory. Marketplaces stay on each target, as the spec intends.codexemits packages by default. It writes rootplugin.jsonwith OpenAI settings underextensions.com.openai, plusmcp.json, and keeps.agents/plugins/marketplace.json. Existing configs need no changes: authoredinterface/apps/hooksmove under the namespace automatically.format: "legacy"keeps the.codex-pluginlayout.validatedetects each plugin's layout on disk, the way Codex does.agent-pluginstarget. Portable packages only, underplugins/<name>/, with no marketplace (the spec defines none) and no client profile. Includingagents/commands/rules/hooksis a config error, and a non-portable manifest field is a build error.install-inforeports no install command, with a citation.forConfig(picks a definition per target config) andfinalizeManifest(runs after the author'smanifestoverride is merged).plugin.schema.jsonandmcp.schema.json(commit SHA and SHA-256 intests/fixtures/agent-plugins/SOURCE.md). Codex and agent-plugins output must validate against them via ajv's 2020-12 build, andpluginpack validatemust pass on the same output.Breaking change
The
codextarget's default output changes from.codex-plugin/plugin.json+.mcp.jsontoplugin.json+mcp.json. To keep the old layout, setformat: "legacy"on the codex target.Verification
npm run checkpasses (249 tests; 9 new intests/agent-plugins.test.ts, plus new conformance tests for codex AP, codex legacy, and agent-plugins).gleanwork/agent-pluginsfrom a temp copy:.codex-plugin/and.mcp.jsonare replaced byplugin.jsonandmcp.json.interfacelands underextensions.com.openai, and the shared Claude-style MCP config converts to valid Agent Pluginsmcp.json.overrides/codex/glean/mcp/config.json(cwd: ".") fails the build, and once it's removed,validaterejects theglean_runskill name, which Agent Plugins clients would skip.Next
(c) in
gleanwork/agent-plugins: delete the codex MCP override, decide on theglean_runrename, upgrade to 0.12, and regeneratecodex-plugins.