build!: publish to PyPI, with the protocol distribution renamed to agentenv-framework-protocol

[earakely-scale]

Merge with bump-version. The two PyPI pending publishers are registered (below). The internal release index keeps the protocol's former name, agentenv-protocol: the release job builds its copies under that name, so nothing internal changes.

Each release now also goes to PyPI, and the protocol distribution is renamed so PyPI will accept it.

Why the rename

PyPI refuses agentenv-protocol: an unrelated agent-env-protocol already exists and normalizes to the same name. The protocol package is now the distribution agentenv-framework-protocol.

• Its import package stays agentenv_protocol and its directory stays packages/agentenv-protocol, so no code that imports it changes.
• The uv workspace, agentenv-framework's dependency, the exact-pin rewrite in the release job, the clean-install gate and the lock check follow the new name.
• So do the explorer's version lookup (its JSON key is unchanged), the plugin compatibility and self-install checks, the A2A agent install hints and the docs.
• The runtime-dependency test now reads an editable install's import packages from its .pth, not from the distribution name.

The internal release index

The CircleCI release job still publishes both packages to the internal index, where the protocol keeps its former distribution name. Before building, it renames the protocol package to agentenv-protocol and pins agentenv-framework to agentenv-protocol==<version>. The consumers and the pin-bump automation read and write agentenv-protocol and are unchanged. The explorer's docs metadata reads the protocol version under either name.

PyPI publishing

• .github/workflows/publish-pypi.yml: runs on a v* tag, with trusted publishing and no stored token.
  • Two jobs, each in its own environment, because PyPI binds a pending publisher to one workflow and environment per project.
  • protocol (environment pypi-protocol) builds and publishes agentenv-framework-protocol.
  • Then framework (environment pypi) builds agentenv-framework pinned to that exact protocol version and publishes it.
  • Each job runs twine check --strict first and skips files already on PyPI, so a rerun is safe.
  • Only GitHub-owned actions (SHA-pinned) and uv from PyPI.
• Environments: pypi and pypi-protocol exist and accept only v* tags.
• README: it becomes the PyPI page. It installs with pip install agentenv-framework (the clone stays for development) and uses absolute links and image URLs. The protocol README says how to install it and names its import package.
• pyproject.toml: the description (the PyPI summary) now says what the package is.

PyPI pending publishers: agentenv-framework (workflow publish-pypi.yml, environment pypi) and agentenv-framework-protocol (same workflow, environment pypi-protocol); owner scaleapi, repository agentenv-framework.

Test plan

• Unit tier: 5629 passed, 13 skipped. Installer tier: 60 passed.
• The clean-install gate runs end to end: wheels built from this tree, installed with dependencies from public PyPI, hello run twice, every score 1.
• The workflow's build steps ran locally.
  • Both packages build as agentenv_framework_protocol-* / agentenv_framework-*.
  • The pin rewrite changes only the dependency line.
  • twine check --strict passes on all four files.
• scripts/bump_version.py bumps both versions and both editable uv.lock entries under the new name.
• circleci config validate passes.
• The release job's two build steps ran as written in a Linux container.
  • They produced agentenv_protocol-0.1.268 and an agentenv-framework that requires agentenv-protocol==0.1.268.
  • Installed together, agent-env --version runs, and the explorer reports both versions.
• After merge: both packages appear on PyPI, and pip install agentenv-framework in a clean environment gets the release.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR is not ready to merge while plugins can bypass a declared protocol version requirement.

Findings

1.  Old plugin requirements get skipped ▶
2.  README contradicts itself on PyPI ▶
3.  Release tools can change ▶

Fix with agent prompt

### Issue 1
src/agent_env/plugins/_requirements.py:undefined-17
If an existing plugin declares a requirement on `agentenv-protocol`, the new `CORE` list does not recognize it. `incompatibility()` skips the requirement, so the plugin can load even when its declared protocol constraint should stop it. Keep requirements using the former name from silently passing.

### Issue 2
README.md:undefined-66
The install section says both packages are on PyPI, but the Releases section still says neither is on a public index. Readers cannot tell whether `pip install agentenv-framework` should work. Update the Releases section to match.

### Issue 3
.github/workflows/publish-pypi.yml:undefined-32
Each release installs the latest `uv` and fetches `twine` without a version pin. A later tool update could break the checks or upload even when the release code has not changed. Pin both to versions tested with this workflow.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Release tags can now publish both packages to PyPI, with the protocol published before the framework. The protocol’s PyPI distribution is renamed to avoid a name conflict, while its import package stays the same and CircleCI keeps the old name for the internal index.

• Adds trusted PyPI publishing jobs and updates the install guide for pip install agentenv-framework.
• Updates the workspace, compatibility checks, release builds, and documentation for the renamed protocol distribution.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  T["Release tag"] --> P["Build and publish agentenv-framework-protocol"]
  P --> F["Build and publish agentenv-framework with exact protocol pin"]
  T --> I["Internal release build: rename protocol to agentenv-protocol"]

Loading

_{Reviews (4) · Last reviewed commit: "Merge remote-tracking branch 'origin/mai..."}

[greptile-apps]

README contradicts itself on PyPI
The install section says both packages are on PyPI, but the Releases section still says neither is on a public index. Readers cannot tell whether pip install agentenv-framework should work. Update the Releases section to match.

Prompt To Fix With AI

This is a comment left during a code review.
Path: README.md
Line: 66

Comment:
**README contradicts itself on PyPI**
The install section says both packages are on PyPI, but the Releases section still says neither is on a public index. Readers cannot tell whether `pip install agentenv-framework` should work. Update the Releases section to match.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Release tools can change
Each release installs the latest uv and fetches twine without a version pin. A later tool update could break the checks or upload even when the release code has not changed. Pin both to versions tested with this workflow.

Prompt To Fix With AI

This is a comment left during a code review.
Path: .github/workflows/publish-pypi.yml
Line: 31

Comment:
**Release tools can change**
Each release installs the latest `uv` and fetches `twine` without a version pin. A later tool update could break the checks or upload even when the release code has not changed. Pin both to versions tested with this workflow.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Old plugin requirements get skipped

If an existing plugin declares a requirement on agentenv-protocol, the new CORE list does not recognize it. incompatibility() skips the requirement, so the plugin can load even when its declared protocol constraint should stop it. Keep requirements using the former name from silently passing.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/plugins/_requirements.py
Line: 17

Comment:
**Old plugin requirements get skipped**

If an existing plugin declares a requirement on `agentenv-protocol`, the new `CORE` list does not recognize it. `incompatibility()` skips the requirement, so the plugin can load even when its declared protocol constraint should stop it. Keep requirements using the former name from silently passing.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.