build: ship the explorer's web UI in the agentenv-framework wheel - #52

What and why

The published wheel carries only the explorer's API. The server serves a built UI from agent_env/explorer/static/ (packaged_ui_dir()), but no release step builds one. The ui job builds the static export on every PR as a check and throws it away. So with pip install 'agentenv-framework[explorer]', agent-env up serves JSON at / and prints a …/docs (UI) link that returns 404. This PR ships the UI in every release. It stays in the framework under the [explorer] extra rather than becoming a separate package, as agreed with @polakamtejas.

• A new explorer-ui job in publish-pypi.yml runs npm ci && npm run build:static and uploads the export as a workflow artifact.
  • It's a separate job because the PyPI jobs can mint tokens. Running npm packages inside them would let a compromised dependency publish to PyPI. This job has contents: read only, and uses no cache, since caches are a known release-poisoning vector.
  • framework downloads the export into explorer/static/ before uv build. A new step runs .github/scripts/check_explorer_ui.py, which fails the publish unless the wheel has agent_env/explorer/static/index.html and every /_next/ script, stylesheet and font that page references. Unit tests are in tst/unit/test_check_explorer_ui.py.
  • protocol now waits for explorer-ui too, so a failed UI build publishes nothing, instead of shipping the protocol and stopping before the framework.
• Packaging:
  • explorer/static/ is git-ignored so the build output can't be committed, and it's listed as a hatch artifact so it still ships.
  • The sdist leaves out src/agent_env/explorer/ui/ entirely, as the wheel does, and ships the UI as its built export. Hatch reads only the root .gitignore, so packing ui/ took whatever a working tree held there. Building the UI in place produced a 159 MB sdist, over PyPI's 100 MB limit, and a local .env.local would have shipped too (Greptile's catch). The sdist's copy of the UI source was already incomplete anyway: the root lib/ pattern dropped all 42 files of ui/src/lib/.
• PR-time check: the existing ui job now packages the export the way the release does. It runs the same script, and fails if the sdist contains anything under explorer/ui/, so a packaging regression shows up on a PR rather than mid-release.
• AGENTS.md: the explorer row says where the UI's source lives, how it ships, and that a source checkout serves only the API.

Licensing was already covered: THIRD_PARTY_NOTICES.md has an "Explorer UI dependencies" section that anticipates a distribution including the built UI, and that file ships in the wheel.

How it was tested

• PR job path, in a worktree of this commit with the UI built in place and node_modules present:
  • The wheel has all 43 UI files including index.html, no UI source, and is 2.5 MB (1.1 MB today).
  • The sdist is 3.3 MB, has nothing under explorer/ui/, and carries the built UI. With a planted ui/.env.local holding a sentinel, the sdist has 0 .env.local entries and no file containing the sentinel.
  • git status stays clean.
• Release path, in a clean worktree with the prebuilt export, the job's protocol-pin rewrite and uv build --no-sources:
  • The UI check passes and twine check --strict passes.
  • The check fails when the wheel is broken: the same wheel with _next/ stripped (all 14 missing assets named), and the current UI-less 0.9.1265 wheel (missing index.html).
• Runtime: I installed the release-built wheel with [explorer] and ran agent-env up:
  • /, /docs and /environments serve the UI, and /api/v1/envs still serves the API.
  • In an earlier prototype, a headless browser rendered the Environments hub, and all five of its same-origin API calls returned 200.
• check-jsonschema (vendor.github-workflows) and actionlint with shellcheck pass on both workflows.
• ci: create a GitHub release for each tag, with notes from its pull requests #48 compatibility: this branch merges with ci: create a GitHub release for each tag, with notes from its pull requests #48 without conflicts. The combined publish-pypi.yml (explorer-ui → protocol → framework → release) also passes actionlint.

bump-version is set, so the release this merge triggers is the first to ship the UI. I'll install it from PyPI afterwards and confirm agent-env up serves the explorer.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, though two earlier, non-blocking packaging checks remain incomplete.

Findings

1.  Missing page assets pass checks ▶
2.  Source files escape archive check ▶

### Issue 1
.github/workflows/local-backends.yml:undefined-86
This check and the release check only look for `index.html`. A wheel can pass both while missing the `_next` files the explorer serves, leaving users with a page whose scripts or styles do not load. Check for a built asset in the wheel too.

### Issue 2
.github/workflows/local-backends.yml:undefined-87
If the sdist contains `explorer/ui/` and `tar` still has paths to list, `grep -q` stops at the first match and closes the pipe. With `pipefail`, `tar` can then fail from a broken pipe, making the `if` condition false. The job passes instead of flagging the files. Let `grep` read the full listing.

```suggestion
          if tar tzf dist/*.tar.gz | grep '/explorer/ui/' >/dev/null; then echo "::error::the sdist includes the UI's source tree"; exit 1; fi
```

---

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

Summary

Release builds now put the explorer’s static web UI in the framework wheel and source distribution, while leaving the UI source in the repository. PR workflows also build and check these distributions so missing UI files or bundled UI source are caught before release.

• Builds the UI separately, then passes its export to the framework build.
• Packages the built UI while excluding its source tree.
• Checks wheel assets and source-distribution contents in PR CI.

_{Reviews (3) · Last reviewed commit: "build: check every asset the explorer's ..."}