Parent: #14182

Goal

Create the hermes_agent/ package by moving every source file into it and rewriting all imports. This is the biggest PR — every file moves, no logic changes. One .git-blame-ignore-revs entry.

Commit strategy

Move areas

Top-level modules → proper homes

agent/ → hermes_agent/agent/ + hermes_agent/providers/

• ~48 files
• Core agent files stay in agent/
• Transports, adapters, credentials, pricing, rate limiting → providers/
• Context engine, compressor, references → agent/context/
• Memory manager, provider → agent/memory/
• Image gen provider, registry → agent/image_gen/

tools/ → hermes_agent/tools/ + hermes_agent/backends/

• ~77 files
• tools/environments/ → hermes_agent/backends/ (promoted — independent axis)
• Browser tools → tools/browser/
• MCP tools → tools/mcp/
• Skills tools → tools/skills/
• Media tools → tools/media/
• File tools → tools/files/
• Security tools → tools/security/
• Remaining flat tools keep tools/ prefix, drop _tool suffix

hermes_cli/ + cli.py → hermes_agent/cli/

• ~51 files
• Auth modules → cli/auth/
• Model modules → cli/models/
• UI modules (banner, colors, output, skin, curses, tips, status, completion) → cli/ui/
• hermes_cli/setup.py → cli/setup_wizard.py (avoid setuptools confusion)

Other packages

External consumers (import rewrites only, no moves)

• tests/**/*.py
• plugins/**/*.py
• scripts/*.py
• tui_gateway/*.py
• environments/*.py (RL envs)

Infrastructure updates

• pyproject.toml — entry points, packages.find, package-data
• Dockerfile — COPY paths, CMD/ENTRYPOINT
• docker/entrypoint.sh — Python invocations
• flake.nix — source path
• nix/packages.nix, nix/python.nix, nix/nixosModules.nix
• .github/workflows/*.yml — test/lint paths
• MANIFEST.in — include patterns
• AGENTS.md / CLAUDE.md — path references

Things to discover along the way

This list will grow as we hit unknown unknowns:

• Circular import issues when reorganizing
• String-based dynamic imports (importlib.import_module("tools." + name))
• Config files with module path strings (YAML, TOML, JSON)
• Plugin system assumptions about import paths
• sys.modules manipulation
• Relative imports that need converting
• Test fixtures or conftest files with path assumptions
• Entry points in packaging (Homebrew, Nix) beyond pyproject.toml

Verification

python -c "import hermes_agent"
rg "^from (agent|tools|hermes_cli|gateway|cron|acp_adapter|run_agent|model_tools|toolsets|toolset_distributions|mcp_serve|hermes_constants|hermes_state|hermes_logging|hermes_time)[\. ]" hermes_agent/ tests/
pytest
hermes --help
hermes-agent --help

After this PR stabilizes

• Extract the final move map → write scripts/migrate_imports.py
• Land migration script as a separate PR before this one merges
• Notify contributors with open PRs