fix(hub): advertise declared agent distribution packages

[kovtcharov]

The hub no longer invents a PyPI package from an agent's implementation language. The flagship declares its existing npm package, and agents without package metadata retain GAIA and source installation options.

Fixes #3550.

Test plan:

• Website suite: 92 passed, including the real flagship manifest/package contract.
• Production Astro build against the live hub catalog passed; generated flagship page contains no nonexistent pip command.
• Whitespace checks and independent review passed.

The flagship npm tab uses the new manifest metadata after catalog publication.

[github-actions]

Approve

The hub used to build a pip install gaia-agent-<id> command out of nothing more than "this agent is written in Python" — and those wheels aren't on PyPI, so every Python agent's page offered an install command that fails. This PR drops that invented lane and has the flagship declare the npm package it really publishes. The reasoning checks out: @amd-gaia/gaia@0.1.1 is live on npm, the flagship genuinely ships as a frozen binary plus an npm client (same shape as the email agent), and the repo's own install messaging already routes users to a source install because the wheels are unpublished.

One thing to be aware of, not a blocker: the npm tab on the flagship page only appears once the hub catalog picks up the new manifest, and the manifest version is unchanged — so it lands with the next release publish, as the description says. Until then the page shows the GAIA app install and a source build, both of which work.

Real-world evidence

No evidence-bundle.md was produced for this PR, so I exercised the changed surface myself rather than relying on static review alone:

$ npm test            # website/
 Test Files  4 passed (4)
      Tests  92 passed (92)

$ HUB_CATALOG_URL=https://hub.amd-gaia.ai npm run build
[build] 5 page(s) built in 1.58s — Complete!

$ grep -rl "pip install gaia-agent" dist/     → no matches
$ flagship page install commands:
      3 gaia agent install gaia
      3 git clone https://github.com/amd/gaia.git

The generated flagship page no longer contains a pip command, which is the user-visible outcome the PR claims. I also confirmed @amd-gaia/gaia resolves on the npm registry at 0.1.1, so the command the new manifest field will advertise is real.

🔍 Technical details

🟢 Minor — stale comment now contradicts the code (website/src/data/catalog.ts:90)

The npm_package field doc still describes the removed lane: "Absent → pip/GAIA (language-driven)". The function comment above installMethods was updated; this one wasn't.

  // shown first, with npm as the embed path. Absent → the GAIA app install plus
  // a source build; implementation language never implies a PyPI wheel.

Note — when the npm tab actually appears (hub/agents/gaia/python/gaia-agent.yaml:7)

The live index currently has npm_package: null for gaia at latest_version: 0.1.1, and the Worker only refreshes display metadata from the manifest of the published latest version (workers/agent-hub/src/catalog.ts:110). With the manifest version unchanged at 0.1.1, the field reaches the catalog on the next release publish. Nothing breaks in the meantime — the card degrades to GAIA + source. Confirmed the publisher POSTs the raw YAML (src/gaia/hub/publisher.py:256), so the new key does flow through; the Python AgentManifest dataclass ignoring unknown top-level keys is pre-existing and matches how the email agent already declares this field.

Strengths

• The removal is backed by the repo's own state rather than a guess: src/gaia/agents/install_hints.py already documents that gaia-agent-* wheels are unpublished ([Bug] Unable to install chat agent: gaia-agent-chat missing from registry and amd-gaia[agents] extra triggers downgrade #2240) and points users at a source install, so the website was the last surface still advertising pip.
• The new test reads the real gaia-agent.yaml and package.json and asserts they agree, so a typo'd or renamed npm package fails CI instead of shipping a 404 install command — this is the contract check that would have caught the class of bug being fixed.
• The flagship's npm_package flips isNpmSidecar on, which changes the page's packaging wording to "npm client + frozen sidecar / no Python needed". That's accurate here — release_agent_gaia.yml freezes the sidecar with PyInstaller per platform and @amd-gaia/gaia fetches and SHA-256 verifies it.

[github-actions]

Verdict: Approve

The fix is correct and well-targeted. The hub install card was generating pip install gaia-agent-<id> for every Python agent regardless of whether a PyPI wheel exists; the gaia flagship is npm-distributed, so that command would silently fail for users. Adding npm_package to the manifest and using that field as the sole discriminator for the pip path matches the pattern already in place for the email agent.

The new test reads the actual YAML and package.json to confirm the npm_package value, then asserts the rendered methods — good integration coverage that would catch a drift between the manifest and the catalog logic. The existing chat-agent assertion (['gaia', 'source']) correctly reflects the removal of the spurious pip lane for that agent.

No security issues, no breaking CLI/API changes, no architecture violations.

🔍 Technical details

One forward-looking note (not blocking): installMethods now has no path to surface a pip install for an agent that genuinely does publish to PyPI in the future. The mechanism would need a pypi_package field analogous to npm_package. Worth tracking if hub agents ever add a wheel distribution — not a problem today since none do.

catalog.ts:476-480 — the updated JSDoc comment accurately reflects the new invariant ("Implementation language does not prove that a package was published to PyPI"). Clear and correct.

catalog.test.ts:44-53 — the test dynamically imports node:fs and yaml inside an async test body. This is fine in Vitest/Jest ESM mode but worth noting: if the YAML parse fails (e.g. yaml not installed in the website workspace), the test errors rather than failing with a useful assertion message. Not a blocker, just a potential DX note.

[kovtcharov]

Merged current main into this branch; it's up to date and conflict-free again.

The only conflict was the flagship npm CHANGELOG: this PR and main each added a line under Fixed. Both entries are kept.

🔍 Technical details

• Merge commit cd7fb16a (main at 1a4cccaa).
• hub/agents/gaia/npm/CHANGELOG.md: kept the hub install-card entry and main's TUI clear-conversation entry. gaia-agent.yaml auto-merged: npm_package from this PR plus main's tools_count: 80.
• Tests: tests/unit/test_hub_manifest.py, test_hub_packager.py, test_hub_publisher.py, test_agent_pypi_publish.py, test_hub_install_sidecar_contract.py: 147 passed. hub/agents/gaia/python/tests/test_gaia_agent.py: 18 passed, 1 failed (test_manifest_tools_count_matches_real_registry). That test fails the same way on main on this machine.
• I couldn't run the website vitest suite here because this machine has no Node. website/ is unchanged by the merge (main didn't touch it), so CI's run is the real check.

[kovtcharov-amd]

Merged main in — 24 commits behind, no conflicts.

🔍 Technical details

Merge commit only — no hand resolution. Net vs main: hub/agents/gaia/python/gaia-agent.yaml, hub/agents/gaia/npm/CHANGELOG.md, website/src/data/catalog.ts, website/src/data/catalog.test.ts (+20/−11).

Tests on the merge result: test_hub_catalog.py, test_hub_manifest.py, test_hub_installer.py, test_hub_compatibility.py, test_hub_install_sidecar_contract.py — 252 passed. The website/ vitest suite was not run locally (no node_modules in this checkout); CI covers it.