PR #15460: fix(whatsapp): bundle bridge.js with the gateway package so pip/Nix installs find it (#15336)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/15460

Description (problem / solution / changelog)

What does this PR do?

Fixes `#15336`. The WhatsApp bridge (Node.js daemon launched by `WhatsAppAdapter`) lived at `scripts/whatsapp-bridge/` — outside any Python package. Setuptools' `find_packages` only ships files that live INSIDE a package directory, so `pip install` (and downstream Nix / Docker / Homebrew installs that build from the wheel) silently dropped the bridge from the artifact. When users on those install paths tried to start the WhatsApp gateway:

``` ✗ Bridge script not found at /nix/store/.../site-packages/scripts/whatsapp-bridge/bridge.js ```

Even though the source tree had `scripts/whatsapp-bridge/bridge.js`, the installed wheel did not.

Fix

Move the bridge inside the `gateway` package — its only consumer — and register it as setuptools package-data so wheels actually contain it. The directory now lives at `gateway/whatsapp_bridge/` and resolves cleanly under both source-tree runs and installed wheels.

Changes

• `git mv scripts/whatsapp-bridge/ → gateway/whatsapp_bridge/` (5 files: `bridge.js`, `allowlist.js`, `allowlist.test.mjs`, `package.json`, `package-lock.json`)
• New `gateway/whatsapp_bridge/init.py` marker — required so `find_packages` treats it as a regular setuptools package and the package-data globs reliably include the JS files (PEP 420 namespace packages have spotty package-data support across setuptools versions)
• `pyproject.toml`: new `[tool.setuptools.package-data]` entry: ```toml "gateway.whatsapp_bridge" = [".js", ".mjs", "package.json", "package-lock.json"] ``` Globs deliberately exclude `node_modules` — the `hermes setup` flow re-creates that tree at runtime via `npm install`, so we don't bloat the wheel with a resolved dependency tree.
• Update three resolvers:
  • `gateway/platforms/whatsapp.py::WhatsAppAdapter._DEFAULT_BRIDGE_DIR` → `Path(file).parents[1] / "whatsapp_bridge"`
  • `hermes_cli/main.py`: bridge-deps install step now resolves via `gateway.file` so it works under wheel installs too
  • `hermes_cli/doctor.py`: same — npm-audit step also uses the package-relative path
• Doc updates in `CONTRIBUTING.md` and `website/docs/user-guide/docker.md` to point at the new path

Related Issue

Fixes #15336

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (file move; no behavior change beyond the bug fix)

Test plan

• 5 new tests in `tests/gateway/test_whatsapp_bridge_packaging.py` — all green on py3.11 venv
• All 43 pre-existing whatsapp tests still pass (`test_whatsapp_connect.py` + `test_whatsapp_formatting.py`) — 48 total green
• Verified regression guards: temporarily removed the `gateway.whatsapp_bridge` package-data entry from `pyproject.toml`; `test_pyproject_package_data_covers_bridge_files` correctly failed with the exact assertion message ("wheel installs will not contain bridge.js (#15336)"). Restored → all 5 pass.

Test coverage detail

`test_whatsapp_bridge_packaging.py` (5 tests):

• `test_bridge_dir_resolves_from_gateway_package` — `_DEFAULT_BRIDGE_DIR` computes to a real existing directory
• `test_bridge_dir_lives_inside_gateway_package` — pin the location so a future move doesn't silently desync from `pyproject.toml`
• `test_bridge_dir_contains_required_files` — `bridge.js`, `allowlist.js`, `package.json` all present
• `test_pyproject_package_data_covers_bridge_files` — parses `pyproject.toml` via `tomllib` so this regression is caught even outside an installed wheel; pins both `*.js` and `package.json` patterns
• `test_bridge_init_marker_present` — the `init.py` marker exists (the thing that makes the directory a real setuptools package on every version)

Why move to `gateway/whatsapp_bridge/` and not just include `scripts/`?

Considered but rejected:

1. Add `scripts/init.py` — would also pull every other dev script (`build_skills_index.py`, `contributor_audit.py`, `release.py`, etc.) into the importable Python namespace. Bigger surface, fragile.
2. `[tool.setuptools.data-files]` — places files under `<prefix>/` not `site-packages/`, doesn't match the resolver path or fix the `pip install` case.
3. PEP 420 namespace packages with `scripts.*` — works on modern setuptools but breaks on older versions still in use across the install matrix (Nix pins setuptools per channel, Homebrew lags).

Moving inside `gateway/` is the smallest surface area that works on every setuptools version, keeps the bridge next to its only consumer, and matches the existing `hermes_cli = ["web_dist/**/*"]` pattern already in the codebase.

Out of scope

• Symlinking back to `scripts/whatsapp-bridge/` for backward compat with operator scripts that might `cd scripts/whatsapp-bridge && npm install` directly. The `hermes setup` flow now does that via the new path; a follow-up could add an alias.
• The Dockerfile reference (already mentions the bridge but uses `pip install -e .` so it picks up the source-tree path automatically). Verified the Dockerfile builds unchanged.

Changed files

• CONTRIBUTING.md (modified, +3/-3)
• gateway/platforms/whatsapp.py (modified, +119/-7)
• gateway/whatsapp_bridge/__init__.py (added, +22/-0)
• gateway/whatsapp_bridge/allowlist.js (renamed, +0/-0)
• gateway/whatsapp_bridge/allowlist.test.mjs (renamed, +0/-0)
• gateway/whatsapp_bridge/bridge.js (renamed, +0/-0)
• gateway/whatsapp_bridge/package-lock.json (renamed, +0/-0)
• gateway/whatsapp_bridge/package.json (renamed, +0/-0)
• hermes_cli/doctor.py (modified, +18/-2)
• hermes_cli/main.py (modified, +14/-2)
• pyproject.toml (modified, +7/-0)
• tests/gateway/test_whatsapp_bridge_packaging.py (added, +292/-0)
• tests/gateway/test_whatsapp_connect.py (modified, +5/-0)
• tests/gateway/test_whatsapp_formatting.py (modified, +5/-0)
• website/docs/user-guide/docker.md (modified, +1/-1)