Directory-installed plugin silently fails to load: bundled cws_agent_sdk not importable → agent stays offline #13

Summary

When the plugin is installed as a directory under ~/.hermes/plugins/hermes-openmax/ (i.e. the whole repo is cloned/copied in, rather than installed via hermes plugins install / uv pip install), the adapter fails to load because the bundled cws_agent_sdk package is not importable. Worse, the failure is silent — the gateway starts normally, the agent simply never connects to OpenMax and shows offline, with no obvious error in the gateway journal.

Environment

• hermes-openmax 0.1.5
• Hermes Agent gateway running as a systemd user service, venv at ~/.hermes/hermes-agent/venv (Python 3.11)
• Plugin present at ~/.hermes/plugins/hermes-openmax/ as a directory containing both hermes_openmax/ and cws_agent_sdk/

Root cause

The repo ships two packages side by side: hermes_openmax/ (the adapter) and its dependency cws_agent_sdk/. The adapter imports the SDK at hermes_openmax/adapter.py:28:

from cws_agent_sdk import CwsBridge, CwsConfig, InboundMessage

When Hermes loads a directory plugin, it loads hermes_openmax via importlib.util.spec_from_file_location, which does not put the plugin root on sys.path. Since cws_agent_sdk was never installed into the venv (a bare directory drop-in doesn't run pip), the import raises ModuleNotFoundError: No module named 'cws_agent_sdk'. The result:

import cws_agent_sdk fails → plugin load fails → the cws platform never registers → adapter never starts → no WebSocket to OpenMax → agent shows offline.

Everything else (credentials, CWS_BFF_URL, CWS_WS_URL, org, network) is fine — a standalone probe with the same .env completes token exchange, ws-ticket, and WebSocket connect, and the server reports presence: online.

Why it's hard to diagnose (the silent-failure part)

The plugin's load-time error does not appear in the gateway journal. Diagnostic output on the plugin path goes through print(), whose stdout is block-buffered under systemd, so the ModuleNotFoundError never surfaces. From the operator's side it just looks like "gateway is running but the agent is offline," with nothing pointing at a failed import.

Reproduction

1. git clone https://github.com/openmaxai/hermes-openmax.git ~/.hermes/plugins/hermes-openmax (directory install, no pip step)
2. Configure .env (CWS_BFF_URL, CWS_WS_URL, CWS_API_KEY, …)
3. Restart the gateway
4. Observe: agent shows offline; no cws connection; gateway journal shows no plugin error
5. Confirm the cause: ~/.hermes/hermes-agent/venv/bin/python -c "import cws_agent_sdk" → ModuleNotFoundError

Note on the README

The README documents hermes plugins install openmaxai/hermes-openmax --enable and uv pip install 'git+…' as the primary install paths — those do install both packages + deps into the venv and work correctly. The problem is specific to the directory drop-in path. The README's directory option (ln -s /path/to/hermes-openmax/hermes_openmax ~/.hermes/plugins/hermes-openmax) symlinks only the inner hermes_openmax package, which still leaves cws_agent_sdk unimportable unless it was separately pip-installed — this hard dependency isn't called out.

Suggested fixes (any one helps)

1. Fail loudly. On import error at load time, log a clear error through the gateway's logger (not print()), e.g. "hermes-openmax failed to load: cws_agent_sdk not importable — install the plugin via hermes plugins install / uv pip install, or add cws_agent_sdk to the venv." A silent offline state is the worst part of this bug.
2. Make the directory path self-sufficient. Either bootstrap sys.path to include the plugin root when cws_agent_sdk isn't found, or fold cws_agent_sdk under the hermes_openmax package namespace so a single-package directory install is complete.
3. Document the hard dependency. If the directory install path is supported, state explicitly that cws_agent_sdk (and httpx / websockets) must be present in the hermes venv, with the exact command.

Workaround (what we did)

Symlinked the bundled SDK into the venv's site-packages so it becomes importable, then restarted the gateway:

ln -sfn ~/.hermes/plugins/hermes-openmax/cws_agent_sdk \
  ~/.hermes/hermes-agent/venv/lib/python3.11/site-packages/cws_agent_sdk

(httpx / websockets were already present in the venv.) After restart the adapter loads, the gateway establishes the WebSocket to OpenMax, and the agent shows online.