Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(spotify): music by voice, and the device problem solved rather than reported
Harald3bc5d0c04fc0
diff --git a/docs/marketplace/spotify-oauth-setup.md b/docs/marketplace/spotify-oauth-setup.mdnew file mode 100644index 0000000000..92a9fd199b--- /dev/null+++ b/docs/marketplace/spotify-oauth-setup.md@@ -0,0 +1,99 @@+# Spotify plugin setup++The Spotify plugin logs in through an app **you** register once, and there is no+way around that: since 11 February 2026 a Spotify Development Mode app allows at+most **five authorized users**, so no shared Jarvis-owned client could ever serve+everyone who downloads this project. Every install registers its own.++The good news is that Spotify's version of this is the shortest in the catalog.+It takes about five minutes, needs **no client secret**, and — unlike Google —+has no consent-screen review and no verification queue.++## Before you start++**Controlling playback requires Spotify Premium.** Play, pause, skip and volume+all answer `403` for a free account. That is Spotify's rule, not a limitation of+this app. Reading what is currently playing works on any account, so a free+listener still gets a useful plugin, just not a remote control.++Since February 2026 the *owner* of a Development Mode app also has to hold an+active Premium subscription. If yours lapses, the app stops working.++## Part A — register the app++1. Sign in at <https://developer.spotify.com/dashboard> and click **Create app**.+2. Fill in:+ - **App name** — anything, e.g. `Personal Jarvis`+ - **App description** — anything, e.g. `Personal voice assistant`+ - **Redirect URI** — exactly this, then click **Add**:++ ```+ http://127.0.0.1:3125/callback+ ```++ - **Which API/SDKs are you planning to use?** — tick **Web API**+3. Accept the terms and click **Save**.+4. Open the app's **Settings** and copy the **Client ID**.++Two mistakes to avoid on step 2, both of which produce+`INVALID_CLIENT: Invalid redirect URI` at login:++- **`localhost` does not work.** Spotify explicitly rejects it and requires the+ loopback IP literal. It must read `127.0.0.1`.+- **The URI must match character for character**, including the port and the+ `/callback` path. No trailing slash.++You do **not** need the client secret. Jarvis uses PKCE, which secures the flow+without one.++## Part B — connect it in Jarvis++1. Open **Plugins**, find the Spotify card, click **Connect**.+2. Expand **"Use your own OAuth client (advanced)"** and paste the Client ID.+ Jarvis stores it in the credential manager as `spotify_oauth_client_id`;+ leave the secret field empty.+3. Continue. Your browser opens Spotify's approval page, which lists what Jarvis+ is asking for. Approve it.+4. The tab reports `Connected.` and can be closed.++Prefer the in-app field over editing `data/plugin_catalog.json` by hand: a+catalog re-sync overwrites that file and would silently reset a working client+back to the placeholder. The environment variable `SPOTIFY_OAUTH_CLIENT_ID`+works too.++## Keeping it connected++Spotify caps a refresh token at **six months**. Jarvis renews the hourly access+token in the background without asking, but twice a year the card will ask you+to reconnect. Nothing can extend that — it is a fixed ceiling on Spotify's side,+which is why the card says "provider limited" rather than promising forever.++**Disconnecting** removes the local credential. Spotify publishes no revocation+endpoint, so to withdraw the authorization at Spotify as well, go to+**Account → Apps** on spotify.com and remove it there.++## What you can say once it is connected++- "play Radiohead" · "play my running playlist" · "play the new Bonobo album"+- "skip this one" · "go back" · "pause the music" · "carry on"+- "what song is this?"+- "turn the music down"+- "queue up Bohemian Rhapsody"++## When something does not work++| What you see | What it means |+|---|---|+| `INVALID_CLIENT: Invalid redirect URI` | The redirect URI in the dashboard is not exactly `http://127.0.0.1:3125/callback` — most often `localhost` instead of `127.0.0.1`. |+| "Spotify only allows remote control with Premium" | The account is on the free tier. Reading still works; controlling does not. |+| "Spotify is not open anywhere" | The Web API commands Spotify Connect, it does not play audio itself. Open Spotify on any device — phone, desktop, speaker — and it becomes controllable. |+| "Spotify is idle on several devices" | More than one client is open and none is active. Say which one, or press play once on the device you mean. |+| The card asks to reconnect after months | The six-month refresh-token ceiling. Reconnect once. |++## Why not an off-the-shelf MCP server?++Spotify publishes no MCP server and no agent integration of any kind — only the+Web API. The community servers that exist want a plaintext `spotify-config.json`+holding a client **secret** plus a terminal `npm run auth` step, which would+replace this repo's keyring-backed Connect button with a worse and less safe+flow. Hence a native tool, matching Gmail, Drive, Calendar and Home Assistant.diff --git a/jarvis/brain/factory.py b/jarvis/brain/factory.pyindex ef79fd3c32..0dd8aa132b 100644--- a/jarvis/brain/factory.py+++ b/jarvis/brain/factory.py@@ -195,6 +195,12 @@ ROUTER_TOOLS = frozenset({# directly; otherwise a connected Drive is not callable by voice/chat. Never# a spawn (AP-5/AP-14)."google_drive",+ # Spotify Marketplace plugin (2026-08-17): native REST tool, same rationale+ # as gmail — Spotify publishes no MCP server at all, so it must be+ # router-visible directly; otherwise connected Spotify is not callable by+ # voice, which is the entire point of a music plugin. risk_tier "monitor":+ # starting music is audible and instantly undone. Never a spawn (AP-5/AP-14).+ "spotify",# Computer-Use (Wave 1, 2026-05-29): first-class, clearly-described tool to# drive the user's LIVE desktop (open apps, click, type, scroll, operate# any GUI). The router previously had no honest desktop path — spawn-workerdiff --git a/jarvis/marketplace/seed_catalog.json b/jarvis/marketplace/seed_catalog.jsonindex 4ff789fe19..cb185dcd09 100644--- a/jarvis/marketplace/seed_catalog.json+++ b/jarvis/marketplace/seed_catalog.json@@ -529,6 +529,42 @@},"native_tool": "home_assistant","post_install_hint_md": "Try “turn off the living room lights” or “is the garage door still open”. Acting on a device asks for confirmation first."+ },+ {+ "id": "spotify",+ "display_name": "Spotify",+ "description": "Play music, skip tracks and hear what is playing",+ "category": "Media & Creativity",+ "logo_slug": "spotify",+ "logo_color": "1ED760",+ "featured": true,+ "longevity": "provider_limited",+ "longevity_note": "Spotify caps a refresh token at six months, so the connection asks to be renewed twice a year. Nothing can extend that.",+ "oauth_client_family": "spotify",+ "auth": {+ "mode": "oauth_pkce_loopback",+ "authorization_url": "https://accounts.spotify.com/authorize",+ "token_url": "https://accounts.spotify.com/api/token",+ "client_id": "REPLACE_WITH_YOUR_SPOTIFY_CLIENT_ID",+ "callback_port": 3125,+ "callback_path": "/callback",+ "scopes": [+ "user-read-playback-state",+ "user-modify-playback-state",+ "user-read-currently-playing",+ "playlist-read-private",+ "playlist-modify-private",+ "playlist-modify-public",+ "user-library-read"+ ],+ "scope_separator": "space",+ "user_scopes_only": false,+ "refresh_supported": true,+ "refresh_token_ttl_days": 180,+ "offline_access": false+ },+ "native_tool": "spotify",+ "post_install_hint_md": "Setup: see docs/marketplace/spotify-oauth-setup.md. Spotify has no shared client — every install registers its own app, which takes about five minutes and needs no client secret. Register the redirect URI **exactly** as `http://127.0.0.1:3125/callback`; Spotify rejects `localhost`.\n\nControlling playback (play, pause, skip, volume) requires Spotify **Premium** — Spotify's own rule, not ours. Reading what is playing works on a free account. Spotify offers no revoke endpoint, so disconnecting here removes the local credential; remove the app itself under Account → Apps."}]}diff --git a/jarvis/marketplace/usage_cards/spotify.md b/jarvis/marketplace/usage_cards/spotify.mdnew file mode 100644index 0000000000..a70342e635--- /dev/null+++ b/jarvis/marketplace/usage_cards/spotify.md@@ -0,0 +1,12 @@+---+plugin_id: spotify+keywords: spotify, musik, music, música, lied, song, canción, track, titel, album, álbum, playlist, wiedergabeliste, lista de reproducción, künstler, artist, artista, band, grupo, spiel, spiele, play, pon, reproduce, pausier, pause, pausa, stopp, stop, überspring, skip, salta, next, siguiente, weiter, zurück, previous, anterior, lauter, louder, sube, leiser, quieter, baja, lautstärke, volume, volumen, was läuft, what is playing, qué suena # i18n-allow: spoken-input matching vocabulary (de/en/es), not prose+---+Use the spotify tool to play and control the user's music.++- To start something, pass what the user said as `query` and set `type`: `track` for a song, `artist` for a band, `album`, `playlist` for a named list of theirs.+- `play` without a query resumes paused playback; `pause`, `next`, `previous` and `set_volume` steer what is already running.+- `now_playing` answers "what song is this" — it reports the track, artist and which device it is coming out of.+- Report the track the response names, not the words the user used. Spotify's top hit is sometimes not what they meant, and saying it aloud is how they notice.+- Nothing open anywhere means there is no device to play on. Say so plainly and offer to open Spotify; it is not a broken connection.+- Playback control requires Spotify Premium. If Spotify refuses, name that as Spotify's own rule — reading what plays still works without it.diff --git a/jarvis/plugins/tool/spotify_rest.py b/jarvis/plugins/tool/spotify_rest.pynew file mode 100644index 0000000000..ee99a86e6a--- /dev/null+++ b/jarvis/plugins/tool/spotify_rest.py@@ -0,0 +1,559 @@+"""spotify tool — play, steer and read the user's Spotify from voice or chat.++Native REST tool rather than MCP, for the same reason as the other marketplace+connectors: Spotify publishes no MCP server and no agent integration at all —+only the Web API. What community MCP servers exist want a plaintext+``spotify-config.json`` holding a client secret plus a terminal ``npm run auth``,+which trades this repo's keyring-backed connect button for a worse flow (AP-2).++Three properties of Spotify's API shape everything below:++* **The Web API produces no audio.** It drives Spotify Connect, so it can only+ command a device that already runs a Spotify client. With nothing open, every+ playback call answers 404 ``NO_ACTIVE_DEVICE`` — a state this tool resolves+ (one device: adopt it) or reports plainly, never retries blindly.+* **Controlling playback requires Premium.** Spotify answers 403 for a free+ account on play/pause/skip/volume. Reading stays open to everyone, so a free+ listener still gets "what is playing" instead of a dead plugin.+* **Answers are frequently 204 with an empty body.** Every player command+ returns no content on success, so nothing here may parse a response body it+ did not check for first.++Risk tier ``monitor``: starting music is audible and instantly reversible, so it+is audited but never prompts. Unlike Home Assistant, nothing here can unlock a+door. A direct gated action, never a spawn (AP-5/AP-14).+"""+from __future__ import annotations++from collections.abc import Awaitable, Callable+from typing import Any++from jarvis.core.protocols import ExecutionContext, ToolResult++_API = "https://api.spotify.com/v1"++_NOT_CONNECTED = "Spotify is not connected — connect it in the Plugins view."+_NEEDS_RECONNECT = (+ "Spotify rejected the stored authorization. Reconnect Spotify in the "+ "Plugins view."+)+_NEEDS_PREMIUM = (+ "Spotify only allows remote control with Premium — that is Spotify's rule, "+ "not a limit of this app. Reading what is playing still works."+)+_NO_DEVICE = (+ "Spotify is not open anywhere, so there is nothing to play on. Open Spotify "+ "on this machine, a phone or a speaker and try again."+)++# Spotify's Development Mode caps search at 10 results (default 5). Asking for+# more is a 400, not a silent trim, so the ceiling lives here rather than in the+# caller's head.+_SEARCH_MAX = 10++# What `play` accepts. A track plays as a `uris` list; everything else is a+# context (album/artist/playlist) — Spotify rejects the wrong one with a 400.+_CONTEXT_TYPES = ("album", "artist", "playlist")+++def _default_token_provider() -> str | None:+ from jarvis.marketplace.token_store import TokenStore++ tokens = TokenStore().load("spotify")+ return tokens.access if tokens is not None else None+++async def _default_refresher(observed_access_token: str | None = None) -> bool:+ """Refresh the stored Spotify token in place. Returns True on success.++ On an un-healable failure (revoked grant, placeholder client id, a refresh+ token past Spotify's six-month ceiling) it flags ``needs_reauth`` so the+ Plugins view stops showing a green "connected" that lies. Best-effort: any+ error returns False and never raises into the tool."""+ from jarvis.marketplace.connect_helpers import build_handler_from_catalog+ from jarvis.marketplace.refresh_scheduler import refresh_plugin_token+ from jarvis.marketplace.token_store import TokenStore++ attempt = await refresh_plugin_token(+ "spotify",+ TokenStore(),+ build_handler_from_catalog,+ force=True,+ observed_access_token=observed_access_token,+ )+ return attempt.usable+++def _artists(item: dict[str, Any]) -> str:+ names = [a.get("name") for a in item.get("artists") or [] if a.get("name")]+ return ", ".join(n for n in names if n)+++def _slim_item(item: dict[str, Any]) -> dict[str, Any]:+ """Project a search hit to what a spoken answer needs: who, what, and the+ URI needed to actually play it. The raw object carries images, markets and+ external ids that would bury the answer and blow the prompt budget."""+ out: dict[str, Any] = {+ "name": item.get("name"),+ "uri": item.get("uri"),+ "type": item.get("type"),+ }+ if artists := _artists(item):+ out["artist"] = artists+ album = item.get("album")+ if isinstance(album, dict) and album.get("name"):+ out["album"] = album["name"]+ if (owner := item.get("owner")) and isinstance(owner, dict):+ out["owner"] = owner.get("display_name")+ if isinstance(item.get("total_tracks"), int):+ out["total_tracks"] = item["total_tracks"]+ return out+++def _slim_device(device: dict[str, Any]) -> dict[str, Any]:+ return {+ "id": device.get("id"),+ "name": device.get("name"),+ "type": device.get("type"),+ "is_active": bool(device.get("is_active")),+ "volume_percent": device.get("volume_percent"),+ }+++def _summarize_playback(state: dict[str, Any]) -> dict[str, Any]:+ """Reduce the playback state object to what is worth reading aloud."""+ item = state.get("item") or {}+ out: dict[str, Any] = {+ "is_playing": bool(state.get("is_playing")),+ "track": item.get("name"),+ "uri": item.get("uri"),+ }+ if artists := _artists(item):+ out["artist"] = artists+ album = item.get("album")+ if isinstance(album, dict) and album.get("name"):+ out["album"] = album["name"]+ device = state.get("device")+ if isinstance(device, dict):+ out["device"] = device.get("name")+ out["volume_percent"] = device.get("volume_percent")+ return out+++class SpotifyRestTool:+ name: str = "spotify"+ risk_tier: str = "monitor"+ description: str = (+ "Play and control the user's Spotify: start a song, artist, album or "+ "playlist, pause, skip, go back, set the volume, queue something up, or "+ "say what is currently playing. Use for 'play Radiohead', 'skip this "+ "one', 'what song is this', 'pause the music', 'turn the music down', "+ "'play my running playlist'. Actions: now_playing, play, pause, next, "+ "previous, set_volume, queue, search, list_devices, list_playlists. "+ "Requires the Spotify plugin to be connected in the Plugins view; "+ "controlling playback needs Spotify Premium."+ )+ schema: dict[str, Any] = {+ "type": "object",+ "properties": {+ "action": {+ "type": "string",+ "enum": [+ "now_playing",+ "play",+ "pause",+ "next",+ "previous",+ "set_volume",+ "queue",+ "search",+ "list_devices",+ "list_playlists",+ ],+ "default": "now_playing",+ },+ "query": {+ "type": "string",+ "description": (+ "what to play, queue or search for, e.g. 'Radiohead', "+ "'Bohemian Rhapsody', 'my running playlist'. Leave out on "+ "play to simply resume what is paused."+ ),+ },+ "type": {+ "type": "string",+ "enum": ["track", "album", "artist", "playlist"],+ "default": "track",+ "description": "what the query names",+ },+ "device_id": {+ "type": "string",+ "description": "play on a specific device (from list_devices)",+ },+ "volume_percent": {+ "type": "integer",+ "description": "0-100, for set_volume",+ },+ "limit": {"type": "integer", "default": 5, "description": "search hits, max 10"},+ },+ "required": ["action"],+ }++ def __init__(+ self,+ access_token_provider: Callable[[], str | None] | None = None,+ transport: Any | None = None,+ token_refresher: Callable[[], Awaitable[bool]] | None = None,+ ) -> None:+ from ._http_pool import HttpClientPool++ self._token_provider = access_token_provider or _default_token_provider+ self._refresher = token_refresher+ # Keep-alive pool: a play is search + devices + play in a row, so one+ # warm TLS connection beats three handshakes.+ self._pool = HttpClientPool(transport=transport)++ # -- internal helpers ---------------------------------------------------++ def _bearer(self) -> dict[str, str] | None:+ token = self._token_provider()+ if not token:+ return None+ return {"Authorization": f"Bearer {token}", "User-Agent": "Personal-Jarvis/1.0"}++ async def _with_auth_retry(+ self, do_call: Callable[[dict[str, str]], Awaitable[Any]]+ ) -> Any:+ """Run an authenticated call; on a 401 refresh once and retry.++ Spotify access tokens live exactly one hour, so this path is ordinary+ rather than exceptional — without it every session longer than an hour+ would hand the user an auth error for a connection that is perfectly+ healthy."""+ import httpx++ headers = self._bearer()+ if headers is None:+ return {"error": _NOT_CONNECTED}+ try:+ return await do_call(headers)+ except httpx.HTTPStatusError as exc:+ if exc.response.status_code != 401:+ raise+ observed_token = headers["Authorization"].removeprefix("Bearer ")+ try:+ if self._refresher is None:+ refreshed = bool(await _default_refresher(observed_token))+ else:+ refreshed = bool(await self._refresher())+ except Exception: # noqa: BLE001 — refresher must never crash the tool+ refreshed = False+ if not refreshed:+ return {"error": _NEEDS_RECONNECT}+ headers = self._bearer()+ if headers is None:+ return {"error": _NEEDS_RECONNECT}+ return await do_call(headers)++ async def _request(+ self,+ method: str,+ path: str,+ headers: dict[str, str],+ *,+ params: dict[str, Any] | None = None,+ json_body: dict[str, Any] | None = None,+ ) -> Any:+ """One Spotify call. Returns parsed JSON, or ``None`` for the empty+ 204 body every successful player command answers with."""+ client = self._pool.client()+ resp = await client.request(+ method,+ f"{_API}{path}",+ params=params,+ json=json_body,+ headers=headers,+ )+ resp.raise_for_status()+ if resp.status_code == 204 or not resp.content:+ return None+ return resp.json()++ @staticmethod+ def _reason(exc: Any) -> str:+ """Spotify's machine-readable failure reason, e.g. NO_ACTIVE_DEVICE.++ The body is `{"error": {"status", "message", "reason"}}` — but only on+ player endpoints, and only sometimes, so every step is guarded."""+ try:+ payload = exc.response.json()+ except Exception: # noqa: BLE001 — a non-JSON error body is still an error+ return ""+ error = payload.get("error") if isinstance(payload, dict) else None+ if isinstance(error, dict):+ return str(error.get("reason") or "")+ return ""++ async def _devices(self, headers: dict[str, str]) -> list[dict[str, Any]]:+ payload = await self._request("GET", "/me/player/devices", headers)+ devices = (payload or {}).get("devices")+ return [d for d in devices if isinstance(d, dict)] if isinstance(devices, list) else []++ async def _player_command(+ self,+ method: str,+ path: str,+ *,+ params: dict[str, Any] | None = None,+ json_body: dict[str, Any] | None = None,+ device_id: str | None = None,+ ) -> dict[str, Any]:+ """A playback command, with the two failures Spotify actually produces+ turned into something a person can act on.++ ``NO_ACTIVE_DEVICE`` is the common one and is worth healing rather than+ reporting: if the user has exactly one Spotify client open, that is+ unambiguously the one they meant, so the command is re-sent aimed at it.+ With several open, guessing would start music in the wrong room, so the+ list goes back to the user instead."""+ import httpx++ async def _do(headers: dict[str, str]) -> dict[str, Any]:+ query = dict(params or {})+ if device_id:+ query["device_id"] = device_id+ try:+ await self._request(+ method, path, headers, params=query or None, json_body=json_body+ )+ return {"ok": True, "device_id": device_id}+ except httpx.HTTPStatusError as exc:+ status = exc.response.status_code+ if status == 403:+ return {"error": _NEEDS_PREMIUM}+ if status != 404 or self._reason(exc) != "NO_ACTIVE_DEVICE":+ raise+ # 404 NO_ACTIVE_DEVICE — nothing is listening yet.+ if device_id:+ return {"error": _NO_DEVICE}+ open_devices = await self._devices(headers)+ if not open_devices:+ return {"error": _NO_DEVICE}+ if len(open_devices) > 1:+ return {+ "error": (+ "Spotify is idle on several devices — say which one, or "+ "start playback there once."+ ),+ "devices": [_slim_device(d) for d in open_devices],+ }+ target = open_devices[0]+ query = dict(params or {})+ query["device_id"] = target.get("id")+ try:+ await self._request(+ method, path, headers, params=query, json_body=json_body+ )+ except httpx.HTTPStatusError as exc:+ if exc.response.status_code == 403:+ return {"error": _NEEDS_PREMIUM}+ raise+ return {"ok": True, "device": target.get("name"), "device_id": target.get("id")}++ return await self._with_auth_retry(_do)++ # -- public actions (also directly unit-testable) -----------------------++ async def now_playing(self) -> dict[str, Any]:+ async def _do(headers: dict[str, str]) -> dict[str, Any]:+ state = await self._request("GET", "/me/player", headers)+ # 204: Spotify is connected but nothing is loaded anywhere.+ if not state:+ return {"is_playing": False, "message": "Nothing is playing on Spotify."}+ return _summarize_playback(state)++ return await self._with_auth_retry(_do)++ async def search(+ self, *, query: str, item_type: str = "track", limit: int = 5+ ) -> dict[str, Any]:+ capped = max(1, min(int(limit), _SEARCH_MAX))++ async def _do(headers: dict[str, str]) -> dict[str, Any]:+ payload = await self._request(+ "GET",+ "/search",+ headers,+ params={"q": query, "type": item_type, "limit": capped},+ )+ bucket = (payload or {}).get(f"{item_type}s") or {}+ items = [i for i in (bucket.get("items") or []) if isinstance(i, dict)]+ return {+ "query": query,+ "type": item_type,+ "results": [_slim_item(i) for i in items],+ }++ return await self._with_auth_retry(_do)++ async def play(+ self,+ *,+ query: str = "",+ item_type: str = "track",+ device_id: str | None = None,+ ) -> dict[str, Any]:+ body: dict[str, Any] | None = None+ started: dict[str, Any] | None = None++ if query:+ found = await self.search(query=query, item_type=item_type, limit=1)+ if found.get("error"):+ return found+ results = found.get("results") or []+ if not results:+ return {"error": f"Spotify has nothing called {query!r}."}+ started = results[0]+ uri = started.get("uri")+ if not uri:+ return {"error": f"Spotify returned no playable id for {query!r}."}+ body = (+ {"context_uri": uri}+ if item_type in _CONTEXT_TYPES+ else {"uris": [uri]}+ )++ out = await self._player_command(+ "PUT", "/me/player/play", json_body=body, device_id=device_id+ )+ if out.get("error"):+ return out+ # Report what the SERVER said is playable, not what the model asked for.+ # Spotify needs a moment before /me/player reflects the new track, so+ # reading it straight back would report the previous song as the result.+ if started:+ out["started"] = started+ else:+ out["resumed"] = True+ return out++ async def pause(self) -> dict[str, Any]:+ return await self._player_command("PUT", "/me/player/pause")++ async def next_track(self) -> dict[str, Any]:+ return await self._player_command("POST", "/me/player/next")++ async def previous_track(self) -> dict[str, Any]:+ return await self._player_command("POST", "/me/player/previous")++ async def set_volume(self, *, volume_percent: int) -> dict[str, Any]:+ level = max(0, min(int(volume_percent), 100))+ out = await self._player_command(+ "PUT", "/me/player/volume", params={"volume_percent": level}+ )+ if not out.get("error"):+ out["volume_percent"] = level+ return out++ async def queue(self, *, query: str, item_type: str = "track") -> dict[str, Any]:+ found = await self.search(query=query, item_type=item_type, limit=1)+ if found.get("error"):+ return found+ results = found.get("results") or []+ if not results:+ return {"error": f"Spotify has nothing called {query!r}."}+ item = results[0]+ out = await self._player_command(+ "POST", "/me/player/queue", params={"uri": item.get("uri")}+ )+ if not out.get("error"):+ out["queued"] = item+ return out++ async def list_devices(self) -> dict[str, Any]:+ async def _do(headers: dict[str, str]) -> dict[str, Any]:+ devices = await self._devices(headers)+ return {"devices": [_slim_device(d) for d in devices]}++ return await self._with_auth_retry(_do)++ async def list_playlists(self, *, limit: int = 20) -> dict[str, Any]:+ async def _do(headers: dict[str, str]) -> dict[str, Any]:+ payload = await self._request(+ "GET", "/me/playlists", headers, params={"limit": max(1, min(limit, 50))}+ )+ items = [i for i in ((payload or {}).get("items") or []) if isinstance(i, dict)]+ return {"playlists": [_slim_item(i) for i in items]}++ return await self._with_auth_retry(_do)++ # -- Tool protocol ------------------------------------------------------++ async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:+ action = (args.get("action") or "now_playing").strip()+ query = (args.get("query") or "").strip()+ item_type = (args.get("type") or "track").strip() or "track"+ try:+ if action == "now_playing":+ out = await self.now_playing()+ elif action == "play":+ out = await self.play(+ query=query, item_type=item_type, device_id=args.get("device_id")+ )+ elif action == "pause":+ out = await self.pause()+ elif action == "next":+ out = await self.next_track()+ elif action == "previous":+ out = await self.previous_track()+ elif action == "set_volume":+ level = args.get("volume_percent")+ if level is None:+ return ToolResult(+ success=False, output=None, error="volume_percent missing"+ )+ out = await self.set_volume(volume_percent=int(level))+ elif action == "queue":+ if not query:+ return ToolResult(+ success=False, output=None, error="queue needs a query"+ )+ out = await self.queue(query=query, item_type=item_type)+ elif action == "search":+ if not query:+ return ToolResult(+ success=False, output=None, error="search needs a query"+ )+ out = await self.search(+ query=query, item_type=item_type, limit=int(args.get("limit", 5))+ )+ elif action == "list_devices":+ out = await self.list_devices()+ elif action == "list_playlists":+ out = await self.list_playlists()+ else:+ return ToolResult(success=False, output=None, error=f"unknown action {action!r}")+ except Exception as exc: # noqa: BLE001+ return ToolResult(success=False, output=None, error=self._explain(exc))++ if isinstance(out, dict) and out.get("error"):+ return ToolResult(success=False, output=None, error=out["error"])+ return ToolResult(success=True, output=out)++ @staticmethod+ def _explain(exc: Exception) -> str:+ """Turn a transport or API failure into something a person can act on."""+ import httpx++ if isinstance(exc, httpx.HTTPStatusError):+ status = exc.response.status_code+ if status == 403:+ return _NEEDS_PREMIUM+ if status == 404:+ return _NO_DEVICE+ if status == 429:+ retry = exc.response.headers.get("Retry-After", "a moment")+ return f"Spotify is rate-limiting this app — try again in {retry}s."+ if isinstance(exc, httpx.ConnectError | httpx.ConnectTimeout):+ return "Could not reach Spotify. Check this machine's internet connection."+ return str(exc)diff --git a/jarvis/skills/builtin/__init__.py b/jarvis/skills/builtin/__init__.pyindex d34387609e..0589a92e17 100644--- a/jarvis/skills/builtin/__init__.py+++ b/jarvis/skills/builtin/__init__.py@@ -47,6 +47,7 @@ _PLUGIN_PAIRED_SKILLS: tuple[str, ...] = ("plugin-airtable","plugin-cal_com","plugin-home_assistant",+ "plugin-spotify",)BUILTIN_SKILL_NAMES: tuple[str, ...] = (diff --git a/jarvis/skills/builtin/plugin-spotify/SKILL.md b/jarvis/skills/builtin/plugin-spotify/SKILL.mdnew file mode 100644index 0000000000..f8ce12c725--- /dev/null+++ b/jarvis/skills/builtin/plugin-spotify/SKILL.md@@ -0,0 +1,25 @@+---+schema_version: "1"+name: plugin-spotify+description: Play and control the user's music on Spotify.+when_to_use: Use when the user wants music — start a song, artist, album or playlist, pause, skip, go back, change the volume, queue something up, or ask what is playing right now.+category: media+plugin_id: spotify+intent_verbs: [spiel, spiele, abspielen, pausier, pausiere, stopp, stoppe, überspring, überspringe, skip, weiter, zurück, lauter, leiser, play, pause, resume, next, previous, queue, turn, pon, reproduce, pausa, salta, siguiente, sube, baja] # i18n-allow: spoken-input vocabulary, de/en/es+intent_objects: [spotify, musik, music, música, lied, song, canción, track, titel, album, álbum, playlist, wiedergabeliste, lista, künstler, artist, artista, band, radio, lautstärke, volume, volumen] # i18n-allow: spoken-input vocabulary, de/en/es+triggers:+ - type: voice+ pattern: '(spotify|musik|music|música)' # i18n-allow: spoken-input vocabulary+requires_tools: [spotify]+risk_policy:+ default_tier: monitor+---++Use the connected Spotify to play and steer the user's music.++- Play by name, not by id: pass what the user said as `query` and set `type` to what they meant — `track` for a song, `artist` for a band, `album`, or `playlist` for "my running playlist". The tool searches and plays the top hit in one step.+- "Play" with no name resumes what is paused. Do not search for something to fill the gap.+- Say what actually started. The result carries the track and artist Spotify matched, which is often not literally what the user said — reporting it is how they catch a wrong hit immediately.+- Spotify plays through a device, not through this app. If nothing is open anywhere, say exactly that and offer to open Spotify — do not report it as an error or a broken connection. When several devices are idle, ask which one instead of picking.+- Controlling playback needs Spotify Premium. On that refusal, name it as Spotify's rule and stay useful: reading what is playing still works on a free account.+- Volume is a percentage from 0 to 100. "Quieter" is a step down from the current level, not a jump to zero — read the state first if you do not know it.diff --git a/jarvis/ui/web/frontend/src/assets/brands/LOGOS.md b/jarvis/ui/web/frontend/src/assets/brands/LOGOS.mdindex fa616d50da..c6fe0dd1f9 100644--- a/jarvis/ui/web/frontend/src/assets/brands/LOGOS.md+++ b/jarvis/ui/web/frontend/src/assets/brands/LOGOS.md@@ -85,6 +85,7 @@ we could not obtain. Record it below with `own work` as the legal basis.| linear | svgl `linear.svg` (brand purple, legible on dark) | MIT | 2026-07-25 || notion | svgl `notion.svg` (the light variant, for dark backgrounds) | MIT | 2026-07-25 || slack | gilbarbara/logos `slack-icon.svg` | CC0 | 2026-07-25 |+| spotify | gilbarbara/logos `spotify-icon.svg` | CC0 | 2026-08-17 || supabase | gilbarbara/logos `supabase-icon.svg` | CC0 | 2026-07-25 || telegram | gilbarbara/logos `telegram.svg` | CC0 | 2026-07-25 || todoist | gilbarbara/logos `todoist-icon.svg` | CC0 | 2026-07-25 |diff --git a/jarvis/ui/web/frontend/src/assets/brands/spotify.svg b/jarvis/ui/web/frontend/src/assets/brands/spotify.svgnew file mode 100644index 0000000000..a16d8aa0a8--- /dev/null+++ b/jarvis/ui/web/frontend/src/assets/brands/spotify.svg@@ -0,0 +1,7 @@+<?xml version="1.0" encoding="UTF-8"?>+<svg width="256px" height="256px" viewBox="0 0 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid">+ <title>Spotify</title>+ <g>+ <path d="M127.999236,0 C57.3087105,0 0,57.3085507 0,128.000764 C0,198.696035 57.3087105,256 127.999236,256 C198.697403,256 256,198.696035 256,128.000764 C256,57.3131363 198.697403,0.00611405337 127.997707,0.00611405337 L127.999236,0 Z M186.69886,184.613841 C184.406145,188.373984 179.48445,189.566225 175.724397,187.258169 C145.671485,168.900724 107.838626,164.743168 63.2835265,174.923067 C58.990035,175.901315 54.7102999,173.211132 53.7320747,168.916009 C52.7492641,164.620887 55.428684,160.34105 59.7328748,159.362801 C108.491286,148.222996 150.314998,153.019471 184.054595,173.639116 C187.814648,175.947171 189.00686,180.853699 186.69886,184.613841 L186.69886,184.613841 Z M202.365748,149.76068 C199.476927,154.456273 193.33245,155.938931 188.640026,153.050041 C154.234012,131.90153 101.787386,125.776777 61.0916907,138.130222 C55.8138602,139.724462 50.2395052,136.749975 48.6376614,131.481189 C47.0480455,126.203233 50.0239899,120.639444 55.2926496,119.034505 C101.778216,104.929384 159.568396,111.761839 199.079523,136.042273 C203.771946,138.931163 205.254569,145.075787 202.365748,149.762209 L202.365748,149.76068 Z M203.710807,113.467659 C162.457218,88.964062 94.394144,86.7110334 55.0068244,98.6655362 C48.6819873,100.58382 41.9933726,97.0132133 40.0766627,90.6882251 C38.1599527,84.3601798 41.7274177,77.675991 48.0568402,75.7531212 C93.2707135,62.0270714 168.433562,64.6790421 215.929451,92.8755277 C221.63067,96.2520136 223.495412,103.599577 220.117478,109.281061 C216.754829,114.970188 209.38757,116.845674 203.716921,113.467659 L203.710807,113.467659 Z" fill="#1ED760"></path>+ </g>+</svg>diff --git a/jarvis/ui/web/frontend/src/views/PluginsView.tsx b/jarvis/ui/web/frontend/src/views/PluginsView.tsxindex 20d29d7685..a3107821ff 100644--- a/jarvis/ui/web/frontend/src/views/PluginsView.tsx+++ b/jarvis/ui/web/frontend/src/views/PluginsView.tsx@@ -358,6 +358,7 @@ const OAUTH_FAMILY_LABEL: Record<string, string> = {slack: "Slack",asana: "Asana",microsoft: "Microsoft",+ spotify: "Spotify",};function oauthClientFamily(@@ -376,6 +377,7 @@ const OAUTH_CLIENT_CONSOLE: Record<string, string> = {google: "https://console.cloud.google.com/auth/clients",slack: "https://api.slack.com/apps",asana: "https://app.asana.com/0/my-apps",+ spotify: "https://developer.spotify.com/dashboard",};type TabId = "browse" | "installed" | "community";diff --git a/pyproject.toml b/pyproject.tomlindex a8adce8bef..79df5a1da6 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -637,6 +637,15 @@ google_calendar = "jarvis.plugins.tool.google_calendar_rest:GoogleCalendarRestTo# monitored, share/delete ask), never a spawn (AP-5/AP-14). Entry-point name# matches the catalog native_tool + token-store key "google_drive".google_drive = "jarvis.plugins.tool.drive_rest:DriveRestTool"+# Spotify (marketplace plugin, 2026-08-17) — play/pause/skip/volume/search over+# the Spotify Web API using the marketplace-stored OAuth token. Native because+# Spotify ships NO MCP server and no agent integration at all; the community+# servers want a plaintext client secret in a config file plus a terminal auth+# step, which would trade the keyring-backed connect button for a worse flow+# (AP-2). Router-tier, risk_tier "monitor" — audible and instantly reversible,+# so it is audited without prompting. Never a spawn (AP-5/AP-14). Entry-point+# name matches the catalog native_tool + token-store key "spotify".+spotify = "jarvis.plugins.tool.spotify_rest:SpotifyRestTool"screen-snapshot = "jarvis.plugins.tool.screen_snapshot:ScreenSnapshotTool"move-mouse = "jarvis.plugins.tool.move_mouse:MoveMouseTool"switch-window = "jarvis.plugins.tool.switch_window:SwitchWindowTool"diff --git a/tests/unit/plugins/tool/test_spotify_rest.py b/tests/unit/plugins/tool/test_spotify_rest.pynew file mode 100644index 0000000000..66c84bc35d--- /dev/null+++ b/tests/unit/plugins/tool/test_spotify_rest.py@@ -0,0 +1,286 @@+"""Unit tests for the Spotify REST tool.++Weighted towards the three failures Spotify actually produces in the wild — no+active device, a free account, and an access token that died after its hour —+because those are what decide whether the plugin is usable or merely present.+"""+from __future__ import annotations++import httpx++from jarvis.plugins.tool.spotify_rest import SpotifyRestTool++_TRACK = {+ "name": "Paranoid Android",+ "uri": "spotify:track:6LgJvl0Xdtc73RJ1mmpotq",+ "type": "track",+ "artists": [{"name": "Radiohead"}],+ "album": {"name": "OK Computer"},+}+++_FAKE_TOKEN = "tok123" # noqa: S105 — a literal for MockTransport, not a credential+++def _tool(handler, token: str | None = _FAKE_TOKEN, refresher=None):+ return SpotifyRestTool(+ access_token_provider=lambda: token,+ transport=httpx.MockTransport(handler),+ token_refresher=refresher,+ )+++def _no_device_response() -> httpx.Response:+ return httpx.Response(+ 404,+ json={+ "error": {+ "status": 404,+ "message": "Player command failed: No active device found",+ "reason": "NO_ACTIVE_DEVICE",+ }+ },+ )+++async def test_not_connected_without_token():+ tool = SpotifyRestTool(access_token_provider=lambda: None)+ out = await tool.now_playing()+ assert "not connected" in out["error"].lower()+++async def test_now_playing_handles_empty_204_body():+ """Spotify answers 204 with no body when nothing is loaded. Parsing that as+ JSON is the crash this guards."""++ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(204)++ out = await _tool(handler).now_playing()+ assert out["is_playing"] is False+ assert "Nothing is playing" in out["message"]+++async def test_now_playing_summarizes_track_and_device():+ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(+ 200,+ json={+ "is_playing": True,+ "item": _TRACK,+ "device": {"name": "Küchenlautsprecher", "volume_percent": 40},+ },+ )++ out = await _tool(handler).now_playing()+ assert out["track"] == "Paranoid Android"+ assert out["artist"] == "Radiohead"+ assert out["album"] == "OK Computer"+ assert out["device"] == "Küchenlautsprecher"+++async def test_play_searches_then_starts_track_as_uris():+ seen: list[tuple[str, str]] = []++ def handler(request: httpx.Request) -> httpx.Response:+ seen.append((request.method, request.url.path))+ if request.url.path == "/v1/search":+ return httpx.Response(200, json={"tracks": {"items": [_TRACK]}})+ assert request.url.path == "/v1/me/player/play"+ # A track must go out as `uris`; a context_uri here is a 400 from Spotify.+ assert b"uris" in request.content+ return httpx.Response(204)++ out = await _tool(handler).play(query="Paranoid Android")+ assert out["ok"] is True+ assert out["started"]["artist"] == "Radiohead"+ assert [m for m, _ in seen] == ["GET", "PUT"]+++async def test_play_playlist_uses_context_uri():+ playlist = {"name": "Laufen", "uri": "spotify:playlist:42", "type": "playlist"}++ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/v1/search":+ return httpx.Response(200, json={"playlists": {"items": [playlist]}})+ assert b"context_uri" in request.content+ return httpx.Response(204)++ out = await _tool(handler).play(query="Laufen", item_type="playlist")+ assert out["ok"] is True and out["started"]["name"] == "Laufen"+++async def test_play_without_query_resumes_and_never_searches():+ seen: list[str] = []++ def handler(request: httpx.Request) -> httpx.Response:+ seen.append(request.url.path)+ return httpx.Response(204)++ out = await _tool(handler).play()+ assert out["resumed"] is True+ assert seen == ["/v1/me/player/play"]+++async def test_play_reports_when_spotify_has_no_match():+ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(200, json={"tracks": {"items": []}})++ out = await _tool(handler).play(query="asdkjhasd")+ assert "nothing called" in out["error"]+++async def test_no_active_device_adopts_the_only_open_one():+ """One open client is unambiguous, so the command is re-aimed rather than+ handed back to the user as an error."""+ calls: list[str] = []++ def handler(request: httpx.Request) -> httpx.Response:+ path = request.url.path+ calls.append(path)+ if path == "/v1/me/player/devices":+ return httpx.Response(+ 200,+ json={"devices": [{"id": "dev1", "name": "Laptop", "is_active": False}]},+ )+ if "device_id=dev1" in str(request.url):+ return httpx.Response(204)+ return _no_device_response()++ out = await _tool(handler).pause()+ assert out["ok"] is True+ assert out["device"] == "Laptop"+ assert calls == [+ "/v1/me/player/pause",+ "/v1/me/player/devices",+ "/v1/me/player/pause",+ ]+++async def test_no_active_device_with_several_asks_instead_of_guessing():+ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/v1/me/player/devices":+ return httpx.Response(+ 200,+ json={+ "devices": [+ {"id": "a", "name": "Laptop", "is_active": False},+ {"id": "b", "name": "Küche", "is_active": False},+ ]+ },+ )+ return _no_device_response()++ out = await _tool(handler).pause()+ assert "several devices" in out["error"]+ assert {d["name"] for d in out["devices"]} == {"Laptop", "Küche"}+++async def test_no_device_at_all_is_explained_not_raised():+ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/v1/me/player/devices":+ return httpx.Response(200, json={"devices": []})+ return _no_device_response()++ out = await _tool(handler).next_track()+ assert "not open anywhere" in out["error"]+++async def test_free_account_403_names_premium_as_spotifys_rule():+ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(403, json={"error": {"status": 403, "reason": "PREMIUM_REQUIRED"}})++ out = await _tool(handler).pause()+ assert "Premium" in out["error"]+ assert "Reading what is playing still works" in out["error"]+++async def test_expired_token_refreshes_once_and_retries():+ tokens = iter(["stale", "fresh"])+ current = {"value": next(tokens)}+ seen_auth: list[str] = []++ def handler(request: httpx.Request) -> httpx.Response:+ seen_auth.append(request.headers.get("authorization", ""))+ if request.headers.get("authorization") == "Bearer stale":+ return httpx.Response(401, json={"error": {"status": 401}})+ return httpx.Response(200, json={"is_playing": False, "item": {}})++ async def refresher() -> bool:+ current["value"] = next(tokens)+ return True++ tool = SpotifyRestTool(+ access_token_provider=lambda: current["value"],+ transport=httpx.MockTransport(handler),+ token_refresher=refresher,+ )+ out = await tool.now_playing()+ assert "error" not in out+ assert seen_auth == ["Bearer stale", "Bearer fresh"]+++async def test_failed_refresh_asks_for_reconnect():+ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(401, json={"error": {"status": 401}})++ async def refresher() -> bool:+ return False++ out = await _tool(handler, refresher=refresher).now_playing()+ assert "Reconnect" in out["error"]+++async def test_search_limit_is_capped_at_the_dev_mode_ceiling():+ """Spotify's Development Mode rejects limit > 10 with a 400."""+ seen: dict[str, str] = {}++ def handler(request: httpx.Request) -> httpx.Response:+ seen["url"] = str(request.url)+ return httpx.Response(200, json={"tracks": {"items": []}})++ await _tool(handler).search(query="x", limit=50)+ assert "limit=10" in seen["url"]+++async def test_set_volume_clamps_to_range():+ seen: dict[str, str] = {}++ def handler(request: httpx.Request) -> httpx.Response:+ seen["url"] = str(request.url)+ return httpx.Response(204)++ out = await _tool(handler).set_volume(volume_percent=180)+ assert "volume_percent=100" in seen["url"]+ assert out["volume_percent"] == 100+++async def test_queue_reports_what_was_queued():+ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/v1/search":+ return httpx.Response(200, json={"tracks": {"items": [_TRACK]}})+ return httpx.Response(204)++ out = await _tool(handler).queue(query="Paranoid Android")+ assert out["queued"]["name"] == "Paranoid Android"+++async def test_execute_unknown_action_fails():+ res = await SpotifyRestTool(access_token_provider=lambda: "x").execute(+ {"action": "wipe_library"}, ctx=None # type: ignore[arg-type]+ )+ assert not res.success+++async def test_execute_set_volume_requires_a_level():+ res = await SpotifyRestTool(access_token_provider=lambda: "x").execute(+ {"action": "set_volume"}, ctx=None # type: ignore[arg-type]+ )+ assert not res.success and "volume_percent" in (res.error or "")+++async def test_execute_search_requires_a_query():+ res = await SpotifyRestTool(access_token_provider=lambda: "x").execute(+ {"action": "search"}, ctx=None # type: ignore[arg-type]+ )+ assert not res.success and "query" in (res.error or "")