What does this PR do?

Adds a native Spotify integration to Hermes as a first-class tool surface, using Spotify OAuth PKCE and Hermes' existing auth and credential lifecycle.

This PR does not add an MCP wrapper or a separate secret storage mechanism. Instead, it integrates Spotify into Hermes' current auth model (~/.hermes/auth.json) and exposes Spotify through native Hermes tools, toolsets, and CLI auth commands.

The implementation adds 9 native Spotify Hermes tools covering roughly 31 user-facing actions across playback, devices, queue, search, playlists, albums, library, and listening activity.

Those native tools are:

• spotify_playback
• spotify_devices
• spotify_queue
• spotify_search
• spotify_playlists
• spotify_albums
• spotify_saved_tracks
• spotify_saved_albums
• spotify_activity

Together they cover the following action surface:

• playback control and playback inspection
• device listing and playback transfer
• queue inspection and queue add
• search
• playlist list/get/create/update/add/remove
• album get and album track listing
• saved track list/save/remove
• saved album list/save/remove
• recently played and now playing

This approach keeps the integration aligned with Hermes architecture:

• PKCE-only auth flow
• no client_secret plaintext config pattern
• reuse of Hermes auth state storage and credential refresh lifecycle
• native tool registration and toolset wiring
• CLI auth commands for login/status/logout

It also includes follow-up UX hardening for Spotify-specific API behavior:

• friendlier handling for Spotify 401/403/404/429
• clearer guidance for Premium-gated playback endpoints
• explanatory handling for 204 No Content on now_playing and playback state

Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• ✅ Tests (adding or improving test coverage)

Changes Made

• Added Spotify PKCE auth support to Hermes auth lifecycle in hermes_cli/auth.py
  • stores provider state under providers.spotify in ~/.hermes/auth.json
  • supports token refresh without changing Hermes' active inference provider
  • reads Spotify config from Hermes env/config path instead of inventing new storage
• Added CLI auth integration in hermes_cli/auth_commands.py and hermes_cli/main.py
  • hermes auth spotify
  • hermes auth status spotify
  • hermes auth logout spotify
  • logout --provider spotify
• Added a thin Spotify API client in tools/providers/spotify_client.py
  • centralizes Spotify Web API calls
  • handles auth refresh/retry on 401
  • normalizes Spotify IDs / URLs / URIs
  • adds friendlier error messages for Spotify-specific API responses
  • uses generic /me/library endpoints for saved library operations
• Added native Spotify tool registration and handlers in tools/spotify_tool.py
• Added Spotify toolset registration in toolsets.py
• Added auth/client regression tests:
  • tests/hermes_cli/test_spotify_auth.py
  • tests/tools/test_spotify_client.py

How to Test

1. Set Spotify app config in Hermes env:

   HERMES_SPOTIFY_CLIENT_ID=...
   HERMES_SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
   

The redirect URI must be allow-listed in the Spotify developer app.

2. Authenticate with Spotify:

   hermes auth spotify
   hermes auth status spotify

3. Verify native tool behavior manually or through Hermes tool dispatch:

   • list devices
   • inspect now_playing / playback state
   • pause/resume playback
   • search tracks
   • add a track to queue
   • list playlists
   • create a temporary playlist, add/remove a track, then clean it up
   • list saved tracks / saved albums
   • save/remove/restore a saved track and saved album

4. Run automated tests:

   pytest -q tests/tools/test_spotify_client.py tests/hermes_cli/test_spotify_auth.py

Tests Run

Automated:

• pytest -q tests/tools/test_spotify_client.py tests/hermes_cli/test_spotify_auth.py
• Result: 13 passed

Unit / regression coverage added for:

• Spotify auth state persistence
• refresh flow without clobbering active provider
• 401 refresh-retry behavior in the client
• Spotify URL/URI normalization
• generic /me/library/contains usage
• generic /me/library remove behavior for saved tracks/albums
• friendly formatting of Spotify 403/404/429
• explanatory 204 behavior for empty now_playing
• explanatory native tool output for spotify_activity now_playing

Manual / live verification against a real Spotify account:

• PKCE login completed successfully
• auth state persisted to ~/.hermes/auth.json
• hermes auth status spotify returned valid logged-in state
• native device listing succeeded
• live playback command reached the active Spotify app
• pause/resume succeeded
• queue add succeeded
• playlist listing succeeded
• album fetch and album track listing succeeded
• saved tracks listing succeeded
• saved albums listing succeeded
• recently played succeeded
• now_playing native dispatch succeeded
• native tool dispatch for playlist create/add/remove succeeded
• temporary playlist cleanup succeeded
• saved album and saved track write-paths were verified end-to-end:
  • contains -> remove -> contains(false) -> save -> contains(true)

Notable validation after follow-up fix:

• legacy Spotify library contains endpoints returned 403
• generic library endpoints (/me/library, /me/library/contains) succeeded
• the implementation was updated accordingly and re-tested live

Checklist

Code

• I've read the Contributing Guide (https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md)
• My commit messages follow Conventional Commits (https://www.conventionalcommits.org/) (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs (https://github.com/NousResearch/hermes-agent/pulls) to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide (https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#cross-platform-compatibility) — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A