feat: DevKit 1.2.0 — portable plugins and compatibility preflight - #29
Merged
Merged
Conversation
Reviewer's GuideDevKit 1.2.0 adopts portable Agent Plugins packaging alongside the retained Codex format, relocates portable runtime state to client-managed data, and adds deterministic artifact, extracted-package, CI, and stdio validation. A bounded read-only preflight reports package consistency and explicitly avoids claiming installation, host capability, model availability, broker authority, or dispatch, while the existing 17-tool, model-neutral, fail-closed runtime contracts remain unchanged. Sequence diagram for read-only package compatibility preflightsequenceDiagram
participant Operator
participant Preflight as check_compatibility.py
participant Package as Plugin package
Operator->>Preflight: inspect_package(plugin_root)
Preflight->>Package: Read manifests and MCP configurations
Preflight->>Package: Read pyproject.toml, server.py, uv.lock, and skills
Preflight-->>Operator: JSON consistency report
Note over Preflight: execution_authorized = false
Note over Preflight: Host installation, forwarding, broker, models, and dispatch remain unverified
Flow diagram for artifact and release preflight validationflowchart TD
Source[Source checkout] --> Build[Build deterministic artifact]
Build --> Artifact[Extracted plugin artifact]
Source --> Check[Run compatibility preflight]
Artifact --> Check
Check -->|pass| Stdio[Run package and stdio validation]
Stdio --> CI[CI artifact checks]
CI --> Release[Release preflight]
Check -->|fail| Stop[Stop release]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Ayleovelle
marked this pull request as ready for review
September 30, 2026 05:16
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path=".codex-plugin/check_compatibility.py" line_range="99-100" />
<code_context>
+
+ check(label, load)
+
+ def identity():
+ portable, legacy = data["portable_manifest"], data["codex_manifest"]
+ allowed = {"$schema", *IDENTITY, "extensions"}
+ if (
+ set(portable) != allowed
+ or portable["$schema"]
+ != "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"
+ ):
+ raise PackageError("portable_manifest_fields_differ")
+ if portable["name"] != NAME or any(
+ portable[key] != legacy[key] for key in IDENTITY
+ ):
+ raise PackageError("manifest_identity_drift")
+ extension = portable["extensions"]
+ if extension != {"com.openai": {"interface": legacy["interface"]}}:
+ raise PackageError("openai_overlay_drift")
+ if legacy.get("mcpServers") != "./.mcp.json":
+ raise PackageError("legacy_mcp_pointer_drift")
</code_context>
<issue_to_address>
**issue (broader_impact):** The compatibility preflight accepts arbitrary extra fields in `.codex-plugin/plugin.json`, including legacy execution surfaces such as `hooks`, `agents`, or `skills`, because it compares only the selected identity fields and `interface`. A package can therefore receive an `ok: true` report while its retained Codex manifest has gained an unreviewed runtime surface.
**Triggers:** When a checked package contains a legacy manifest with the expected identity but additional execution-related fields.
**Suggested fix:** Validate the legacy manifest against its closed expected field set, or explicitly reject all legacy runtime-surface fields before reporting success.
```suggestion
portable, legacy = data["portable_manifest"], data["codex_manifest"]
allowed = {"$schema", *IDENTITY, "extensions"}
legacy_allowed = {*IDENTITY, "mcpServers", "interface"}
if set(legacy) != legacy_allowed:
raise PackageError("legacy_manifest_fields_differ")
```
</issue_to_address>Sourcery assessment
Needs a human reviewer. 1 finding to address first, and if the portable manifest or MCP environment mapping is wrong, a host could launch the server with an incorrect durable data or cache location, leaving records or runtime state that would need to be migrated or cleaned up after a revert. The checker and release gate are otherwise reversible, and the diff does not grant access, send data externally, move money, or delete records.
Blocking findings: .codex-plugin/check_compatibility.py:100
Comment on lines
+99
to
+100
| portable, legacy = data["portable_manifest"], data["codex_manifest"] | ||
| allowed = {"$schema", *IDENTITY, "extensions"} |
There was a problem hiding this comment.
issue (broader_impact): The compatibility preflight accepts arbitrary extra fields in .codex-plugin/plugin.json, including legacy execution surfaces such as hooks, agents, or skills, because it compares only the selected identity fields and interface. A package can therefore receive an ok: true report while its retained Codex manifest has gained an unreviewed runtime surface.
Triggers: When a checked package contains a legacy manifest with the expected identity but additional execution-related fields.
Suggested fix: Validate the legacy manifest against its closed expected field set, or explicitly reject all legacy runtime-surface fields before reporting success.
Suggested change
| portable, legacy = data["portable_manifest"], data["codex_manifest"] | |
| allowed = {"$schema", *IDENTITY, "extensions"} | |
| portable, legacy = data["portable_manifest"], data["codex_manifest"] | |
| allowed = {"$schema", *IDENTITY, "extensions"} | |
| legacy_allowed = {*IDENTITY, "mcpServers", "interface"} | |
| if set(legacy) != legacy_allowed: | |
| raise PackageError("legacy_manifest_fields_differ") |
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.
Scope
Prepare DevKit 1.2.0 for the current ChatGPT/Codex plugin packaging model while retaining the existing Codex compatibility configuration and fail-closed runtime contracts.
plugin.jsonand typed stdiomcp.json; retain.codex-plugin/plugin.jsonand.mcp.json.PLUGIN_DATArather than writing a virtual environment into the installed plugin.Primary evidence
The portable MCP schema does not allow legacy
env_vars; it is deliberately not copied. Current models are discovered from actual task metadata, not hard-coded from release notes.Verification so far
21e3360: 156 failed, 2041 passed, 33 skipped, 226 subtests passed; failed test IDs exactly match the unmodified Linux baseline.21e33606fb60e5080b87d12819909c6d4efe9f59(CI run #86, 2026-09-30). Windows runtime/Fast Lane and Linux artifact checks are green.Boundaries
No merge, release, marketplace publication, new MCP tool, remote service, credential, hook trust or security-policy change. Client-specific actual installation has not been verified. The compatibility report explicitly keeps host environment forwarding and private broker attestation unverified.
Summary by Sourcery
Adopt portable Agent Plugins packaging and add compatibility preflight validation while retaining Codex support and fail-closed runtime behavior.
New Features:
Bug Fixes:
Enhancements:
CI:
Documentation:
Tests: