fix: resolve pip packages from site-packages instead of agent dir

[vCillusion]

When pip install --target . is run inside the hermes-agent checkout, third-party package directories (openai/, pydantic/, requests/, etc.) end up alongside real Hermes source files. With the agent dir at the front of sys.path (insert(0)), Python resolves imports from those local directories, breaking whenever the host platform differs from the container (e.g. macOS .so files inside a Linux image).

Fix: append agent dir to sys.path instead of prepending. This lets site-packages resolve pip packages correctly while still allowing Hermes-specific modules (run_agent, hermes/, etc.) to resolve since they do not exist in site-packages.

Also improves verify_hermes_imports() to surface the actual exception message in startup logs, making it much easier to diagnose why a module failed to import.

[nesquena-hermes]

Thanks for this fix, @vCillusion — this is a real bug and the solution is correct.

What the fix does:

sys.path.insert(0, agent_dir) puts the agent checkout at the front of the path, which means import pydantic resolves to whatever version (and platform ABI) happens to be sitting in that directory rather than the properly-installed site-packages. On a Linux container that was previously set up on macOS (or vice versa), this silently breaks every extension module. Changing to sys.path.append() moves the agent dir to the end, where it still exposes Hermes-specific modules (run_agent, hermes/, etc.) without shadowing system packages.

The verify_hermes_imports() signature change (returning errors dict with full exception text) is a welcome improvement — "missing modules: ['run_agent']" with no further detail is genuinely unhelpful; the .so ABI mismatch message will save hours of debugging.

One thing to confirm: server.py now unpacks the three-tuple ok, missing, errors = verify_hermes_imports(). Are there any other callers of verify_hermes_imports() in the codebase that unpack it as a two-tuple and would need updating? Worth a quick grep before merge.

Otherwise this looks clean and ready to go. Changes are minimal, focused, and well-commented.

[nesquena]

Review: PR #76 — fix sys.path ordering for pip-installed packages

Security Audit

Clean. Python-only changes, no external resources, no injection vectors. The except Exception broadening is scoped to error message capture only.

Code Review

The fix is correct — sys.path.insert(0) was causing agent-dir packages (openai/, pydantic/) to shadow system site-packages, breaking cross-platform containers. sys.path.append() resolves hermes-specific modules (run_agent, hermes/) just fine since they don't exist in site-packages.

Confirmed: verify_hermes_imports() has only one caller (server.py:64), which the PR updates to unpack the 3-tuple. No breakage.

The error message improvement is a welcome bonus — showing the actual exception (e.g. .so ABI mismatch) instead of just the module name will save real debugging time.

Tests

401 passed, 23 failed — no regressions. All 23 are pre-existing.

Verdict

Small, focused, well-commented fix for a real bug. Approved.