Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
feat: add Spotify integration and sub-agent orchestration with documentation and website updates
Salman Qureshia58e155cc802
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex b46eb318..fcb44526 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -320,16 +320,21 @@ Mercury supports sub-agents — independent worker processes that run in the sam- **Resource-aware**: Max concurrent agents auto-detected from CPU cores and available RAM- **Coordinated**: File locks prevent conflicting writes between agents- **Controllable**: `/agents`, `/halt`, `/stop`, `/reset` commands for full user control+- **Non-blocking**: Sub-agents run in background — the main agent stays responsive to new messages+- **Visible**: Progress notifications (`🔄 Agent a1: Using: read_file`) and completion messages (`✅ Agent a1 completed (8.2s)`) are sent to the user's channel+- **Fast-path commands**: Slash commands like `/agents`, `/halt`, `/spotify`, `/code` are processed immediately even while the main agent is busy### Architecture```User message → Main Agent → Decide:├─ Quick response → Handle inline, respond directly- └─ Heavy task → delegate_task tool → Spawn Sub-Agent- → Main Agent responds: "Working on it. Agent a1 tasked."+ └─ Heavy task → delegate_task tool → Spawn Sub-Agent (non-blocking)+ → Main Agent responds: "🤖 Agent a1 is working on..."→ Main Agent stays available for next message- → Sub-Agent completes → Main Agent notifies user+ → Sub-Agent progress: "🔄 Agent a1: Using: read_file, edit_file"+ → Sub-Agent completes: "✅ Agent a1 completed (8.2s): result..."+ → User can type /agents to check status at any time```### Component Overviewdiff --git a/website/docs/integrations/spotify.mdx b/website/docs/integrations/spotify.mdxnew file mode 100644index 00000000..f0aa17e2--- /dev/null+++ b/website/docs/integrations/spotify.mdx@@ -0,0 +1,196 @@+---+id: spotify+title: Spotify Integration+---++Mercury connects to your Spotify account natively — control playback, search music, manage playlists, and DJ on your devices through natural conversation. No browser tabs, no app switching. Just say "play some chill music" and Mercury handles the rest.++:::info Spotify Premium+Read-only features (search, top tracks, playlists, now playing) work on **free** Spotify accounts. **Playback control** (play, pause, skip, volume, shuffle, repeat, queue) requires a **Spotify Premium** subscription — this is a Spotify API limitation, not a Mercury restriction.+:::++## Setup++### Step 1: Create a Spotify Developer App++1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard)+2. Log in with your Spotify account+3. Click **"Create app"**+4. Fill in:+ - **App name**: `Mercury` (or anything you like)+ - **App description**: `Mercury Agent Spotify Integration`+ - **Redirect URI**: `http://127.0.0.1:8888/callback` — this must match exactly+5. Click **Save**+6. On the app's settings page, copy the **Client ID** and **Client Secret**++:::tip Development Mode+When your Spotify Developer app is in **development mode** (the default), you can grant access to up to **25 users**. Go to your app's settings → **User Management** → add the Spotify email addresses of anyone who should be able to connect. This is perfect for personal use or small teams. If you need more than 25 users, you'll need to request **extended quota** from Spotify.+:::++### Step 2: Configure Mercury++Run `mercury doctor` (or `mercury setup` for first-time setup):++```bash+mercury doctor+```++When prompted for Spotify, choose **Yes** and enter:++- **Spotify Client ID** — paste the Client ID from Step 1+- **Spotify Client Secret** — paste the Client Secret from Step 1++Press Enter on any other field to keep its current value. After setup, you'll see:++```+Spotify: not connected — run /spotify auth to link your account+```++### Step 3: Connect Your Spotify Account++Start Mercury and run:++```+/spotify auth+```++Choose your authorization method:++| Method | When to use |+|--------|------------|+| **Open browser** (recommended) | When Mercury is running locally on your machine |+| **Paste authorization code** | When browser auto-open fails, or via SSH |++For SSH or Telegram, Mercury will give you the auth URL. Open it on any device with a browser, then paste the `code` parameter from the redirect URL:++```+/spotify code <paste-your-code-here>+```++After successful auth, Mercury shows:++```+Spotify: connected as YourName+```++## Commands++| Command | Description |+|---------|-------------|+| `/spotify` | Show connection status, account name, plan, and active device |+| `/spotify auth` | Start OAuth flow (browser or manual code) |+| `/spotify code <code>` | Complete auth with a pasted authorization code |+| `/spotify logout` | Disconnect Spotify and clear saved tokens |+| `/spotify player` | Interactive player with arrow-key controls (CLI only) |+| `/spotify devices` | List available Spotify devices |+| `/spotify device <id>` | Set active device |+| `/spotify now` | Show what is currently playing |++## Spotify Tools++These are the tools Mercury uses when you talk about music:++### Read-only (works on free accounts)++| Tool | What it does |+|------|-------------|+| `spotify_search` | Search tracks, artists, albums, playlists |+| `spotify_now_playing` | Show what's currently playing |+| `spotify_devices` | List available Spotify devices |+| `spotify_top_tracks` | Get your top tracks (time_range: short/medium/long term) |+| `spotify_playlists` | Get your playlists |+| `spotify_like` | Save a track to your library |++### Playback control (requires Spotify Premium)++| Tool | What it does |+|------|-------------|+| `spotify_play` | Play a track, album, or playlist on a device |+| `spotify_pause` | Pause playback |+| `spotify_next` | Skip to next track |+| `spotify_previous` | Skip to previous track |+| `spotify_volume` | Set volume (0-100) |+| `spotify_shuffle` | Toggle shuffle on/off |+| `spotify_repeat` | Set repeat mode (off, track, context) |+| `spotify_queue` | Add a track to the playback queue |++## Using It++Just talk to Mercury naturally about music:++| You say | Mercury does |+|---------|-------------|+| "play some chill music" | Searches "lo-fi chill", picks tracks, plays on your device |+| "what are my top tracks?" | Calls `spotify_top_tracks`, shows results |+| "skip this song" | Calls `spotify_next` |+| "pause" | Calls `spotify_pause` |+| "play my playlist Road Trip" | Searches your playlists, plays the match |+| "set volume to 50" | Calls `spotify_volume(50)` |+| "what's playing?" | Calls `spotify_now_playing`, shows artist — track + progress bar |+| "add this to my queue" | Calls `spotify_queue` with current track |+| "shuffle on" | Calls `spotify_shuffle(true)` |++## Interactive Player (CLI)++The `/spotify player` command launches an interactive arrow-key player in your terminal:++```+ ▶ Play/Pause ◀ Previous ▶▶ Next+ 🔊 Volume 🔀 Shuffle 🔁 Repeat+ 🔍 Search 📋 Queue ✕ Exit+```++Every action shows real-time feedback with track info and a progress bar.++## Managing Devices++Spotify plays on **your devices** — phone, desktop, TV, speaker. Mercury never plays audio locally. Before playing, Mercury checks what devices are available:++```+/spotify devices+```++If no device is active, Mercury will tell you to open Spotify on a device first. You can set a default device:++```+/spotify device <device-id>+```++The device ID persists across sessions — Mercury remembers your preferred device.++## Token Management++Mercury stores your Spotify tokens in `~/.mercury/mercury.yaml`:++- **Access token** — short-lived, auto-refreshed+- **Refresh token** — long-lived, used to get new access tokens+- **Account info** — display name, user ID, plan (Premium/Free)++Tokens refresh automatically before they expire. If the refresh token itself expires (rare), run `/spotify auth` again.++### Disconnecting++```+/spotify logout+```++This clears all tokens and account info. Run `/spotify auth` to reconnect later.++## Security++:::warning Client credentials+Your Spotify Client ID and Client Secret are stored in `~/.mercury/mercury.yaml`. They are only used to authenticate with Spotify's API from your machine — never shared externally. Treat this file like any other credential.+:::++Your access and refresh tokens are also stored locally. Mercury never sends them anywhere except Spotify's API endpoints.++## Troubleshooting++| Issue | Solution |+|-------|----------|+| "Spotify Premium is required" error | You need Premium for playback control. Read-only features still work on free accounts. |+| 403 errors on play/pause/skip | Your account is on Spotify's free tier. Playback APIs are Premium-only. |+| "No active device" | Open Spotify on your phone/computer, play any song, then try again. |+| Browser doesn't open for auth | Use the manual code flow: `/spotify auth` → choose "Paste code" |+| Token expired after long idle | Run `/spotify auth` to get fresh tokens |+| Account name not showing | Run `/spotify` and Mercury will fetch it live from Spotify's API |\ No newline at end of filediff --git a/website/docs/integrations/sub-agents.mdx b/website/docs/integrations/sub-agents.mdxnew file mode 100644index 00000000..d392cad6--- /dev/null+++ b/website/docs/integrations/sub-agents.mdx@@ -0,0 +1,170 @@+---+id: sub-agents+title: Sub-Agents (Multi-Agent Mode)+---++Mercury isn't just a chatbot — it's an **orchestrator**. It can spawn parallel AI agents to handle tasks concurrently while continuing the conversation. This is sub-agent mode, and it changes how Mercury works fundamentally.++## Why Sub-Agents Matter++Traditional AI agents are single-threaded: one context window, one task at a time. If you ask Mercury to "research this topic, write the code, and review the result," it does them sequentially — each step blocks the next.++Sub-agents break this bottleneck:++- **Parallel execution** — Multiple tasks run simultaneously across isolated context windows+- **LLM-driven delegation** — Mercury itself decides when to delegate based on task complexity+- **Non-blocking** — You can keep chatting with Mercury while sub-agents work in the background+- **File locks** — Reader-writer locks prevent concurrent write conflicts between agents+- **Resource-aware** — Max concurrent agents is auto-detected from your system's CPU and RAM++## How It Works++```+You: "Build a REST API for users and write integration tests"++Mercury decides to delegate:+ 🤖 Multi-agent mode activated.+ **Agent a1** is now working on: "Build REST API endpoints for users"+ **Agent a2** is now working on: "Write integration tests for user endpoints"+ Active agents: 2/4++ You can continue chatting while the agents work.+ Use /agents to check status.++Mercury: I've delegated both tasks to parallel agents. Agent a1 is building the API+ and agent a2 is writing tests. They'll work independently.++ (you continue chatting normally)++ 🔄 Agent a1: Using: read_file, create_file+ 🔄 Agent a2: Using: list_dir, read_file++ ✅ **Agent a1** completed (12.3s): "REST API built with 5 endpoints"+ ✅ **Agent a2** completed (18.7s): "12 integration tests passing"++ Both agents are done. Want me to review the results together?+```++## Commands++| Command | Description |+|---------|-------------|+| `/agents` | List all sub-agents (running and completed) |+| `/halt` | Emergency: halt all sub-agents and clear the task queue |+| `/stop` | Full reset: halt agents, clear queue, release locks, clear task board |++Slash commands like `/agents`, `/halt`, `/stop`, `/spotify`, and `/code status` work **even while the main agent is busy** — they're processed immediately on a fast path.++## Delegation Tools++Mercury uses these tools to manage sub-agents:++| Tool | Description |+|------|-------------|+| `delegate_task` | Spawn a sub-agent with a task description and optional context |+| `list_agents` | Show all running and completed sub-agents |+| `stop_agent` | Halt a specific running sub-agent by ID |++When Mercury decides a task is complex enough to benefit from parallel execution, it calls `delegate_task`. You'll see a response like:++```+🤖 Multi-agent mode activated.++**Agent a1** is now working on: "Analyze the codebase structure for..."+Active agents: 1/4++You can continue chatting while the agent works. I'll notify you when it's done.+Use /agents to check status.+```++## Architecture++```+User message → Main Agent (orchestrator)+ ├─ delegate_task("research X") → Sub-Agent a1 (isolated context)+ ├─ delegate_task("implement Y") → Sub-Agent a2 (isolated context)+ └─ continues conversation → responds to user+ │+ a1: "🔄 Using: read_file"+ a1: "🔄 Using: edit_file"+ a2: "🔄 Using: list_dir"+ a1: "✅ completed (8.2s)"+ a2: "🔄 Using: create_file"+ a2: "✅ completed (15.1s)"+```++Each sub-agent:++- Has its **own context window** — the main agent's conversation doesn't pollute it+- Runs an independent **10-step agentic loop** with the same tool access+- Uses the **same permission system** — but with auto-approve for the task's scope+- Reports progress via the **notification channel** (CLI or Telegram)+- Respects **file locks** — if a1 is writing a file, a2 waits for the lock++## When Mercury Uses Sub-Agents++Mercury decides to delegate when:++- A task is **naturally parallelizable** (e.g., "research X while I code Y")+- The task benefits from an **isolated context window** (no pollution from the main conversation)+- A task is **complex enough** to warrant dedicated focus+- Multiple **independent investigations** would save time++You can also ask Mercury explicitly: "Use two agents for this" or "Delegate this task."++## What Happens While Agents Work++You can keep chatting normally. Mercury processes your messages as they come in. Sub-agent progress and completion appear as notification messages in your channel:++```+🔄 Agent a1: Starting task...+🔄 Agent a1: Using: read_file, edit_file+🔄 Agent a2: Using: fetch_url, create_file+✅ Agent a1 completed (8.2s): "Analyzed the codebase..."+🔄 Agent a2: Using: run_command+✅ Agent a2 completed (14.5s): "Tests passing..."+```++If you send `/agents`, you'll see the full status:++```+**Sub-Agents:**++🔄 a1: Build REST API endpoints — running (Using: read_file)+⏳ a2: Write integration tests — pending+```++## Configuration++Sub-agents are configured in `~/.mercury/mercury.yaml`:++```yaml+subagents:+ enabled: true+ maxConcurrent: auto # auto-detected from CPU/RAM, or set manually (e.g., 4)+ mode: auto # "auto" (LLM decides) or "manual" (user controls)+```++Environment variable overrides:++| Variable | Description |+|----------|------------|+| `SUBAGENTS_ENABLED` | Enable/disable sub-agents |+| `SUBAGENTS_MAX_CONCURRENT` | Max number of concurrent agents |+| `SUBAGENTS_MODE` | `auto` or `manual` |++## Programming Mode++Sub-agents pair well with Mercury's programming mode for code tasks:++| Command | Mode | Behavior |+|---------|------|----------|+| `/code plan` | Plan | Analyze without writing code |+| `/code execute` | Execute | Implement step by step |+| `/code off` | Off | Normal conversation |+| `/code toggle` | — | Cycle through modes |+| `/code status` | — | Show current mode |++## Programming Mode + Sub-Agents++When `/code plan` is active, Mercury will analyze a task and present a plan. If the plan involves parallel work, Mercury can delegate parts to sub-agents during `/code execute`. The `ask_user` tool lets Mercury present choices at decision points — on CLI this is an arrow-key menu, on Telegram it's inline buttons.\ No newline at end of filediff --git a/website/sidebars.ts b/website/sidebars.tsindex b9201883..b5b57644 100644--- a/website/sidebars.ts+++ b/website/sidebars.ts@@ -10,7 +10,7 @@ const sidebars: SidebarsConfig = {label: 'CLI Commands',collapsed: false,items: [- 'cli-commands/cli-commands',+ 'cli-commands/commands','cli-commands/doctor','cli-commands/in-chat-commands',],@@ -20,7 +20,7 @@ const sidebars: SidebarsConfig = {label: 'Daemon Mode',collapsed: true,items: [- 'daemon-mode/daemon-mode',+ 'daemon-mode/background-mode','daemon-mode/system-service','daemon-mode/platform-guide',],@@ -32,6 +32,8 @@ const sidebars: SidebarsConfig = {items: ['integrations/github-companion','integrations/telegram',+ 'integrations/spotify',+ 'integrations/sub-agents',],},{diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsxindex d2fd49e2..f9797315 100644--- a/website/src/pages/index.tsx+++ b/website/src/pages/index.tsx@@ -222,7 +222,7 @@ export default function LandingPage(): React.ReactElement {<><Head><title>Mercury — Soul-Driven AI Agent with Permission Guardrails | Cosmic Stack</title>- <meta name="description" content="The AI agent that asks before it acts. Permission guardrails, token efficiency, full control, and GitHub companion. Runs 24/7 from CLI or Telegram with multi-provider onboarding, model selection, skills, and scheduling." />+ <meta name="description" content="The AI agent that asks before it acts. Permission guardrails, token efficiency, sub-agent orchestration, Spotify integration, and full control. Runs 24/7 from CLI or Telegram with multi-provider onboarding, skills, and scheduling." /><meta property="og:title" content="Mercury — Soul-Driven AI Agent with Permission Guardrails" /><meta property="og:description" content="The AI agent that asks before it acts. Permission guardrails, token efficiency, and full control. Runs 24/7 from CLI or Telegram." /><meta property="og:type" content="website" />@@ -266,7 +266,7 @@ export default function LandingPage(): React.ReactElement {/_/ /_/_____/_/ |_|\\____/\\____/_/ |_| /_/`}</pre><p className="lp-hero-tagline">Soul-driven. Token-efficient. Always on.</p><p className="lp-hero-sub">- Your personal AI agent with 31 built-in tools, skill system, multi-channel access, GitHub companion, and+ Your personal AI agent with 31 built-in tools, skill system, multi-agent orchestration, Spotify integration, GitHub companion, andhardened permissions. Runs 24/7 from your terminal or Telegram.</p><div className="lp-hero-actions">@@ -298,6 +298,8 @@ export default function LandingPage(): React.ReactElement {{ icon: '⚡', title: 'Token-Efficient', desc: 'Daily token budgets with enforcement. Only soul + persona injected per request (~400 tokens). Progressive skill loading. Auto-concise when budget exceeds 70%.' },{ icon: '♾', title: 'Always On', desc: 'Background daemon by default. Cron scheduling, delayed tasks, and a heartbeat system. Auto-starts on boot, auto-restarts on crash.' },{ icon: '📡', title: 'Multi-Channel', desc: 'CLI with readline and arrow-key menus. Telegram with typing indicators, HTML formatting, file uploads, and private 1:1 access.' },+ { icon: '🤖', title: 'Sub-Agents', desc: 'Spawn parallel AI agents for concurrent tasks. Mercury orchestrates — research, code, and review run simultaneously. Non-blocking: keep chatting while agents work.' },+ { icon: '🎵', title: 'Spotify Integration', desc: 'Native Spotify control through conversation. Play music, manage playlists, DJ on your devices. Search, like, queue — all through natural language.' },{ icon: '🧩', title: 'Skill System', desc: 'Install community skills with a single command. Skills auto-load into context, get elevated permissions, and can be scheduled as recurring tasks.' },{ icon: '🛡', title: 'Permission Hardened', desc: 'Folder-level read/write scoping. Command blocklist. Pending approval flow. Ask Me or Allow All mode per session.' },].map((f, i) => (@@ -379,8 +381,9 @@ export default function LandingPage(): React.ReactElement {{ title: '💬 Messaging', items: ['send_message — Send a message to approved Telegram recipients'] },{ title: '🐚 Shell', items: ['run_command — Execute shell commands', 'cd — Change working directory', 'approve_command — Permanently approve a command'] },{ title: '📦 Git', items: ['git_status — Working tree status', 'git_diff — Show file changes', 'git_log — Commit history', 'git_add — Stage files', 'git_commit — Create commits', 'git_push — Push to remote'] },- { title: '🌐 Web', items: ['fetch_url — Fetch & strip HTML to text'] },{ title: '🐙 GitHub', items: ['create_pr — Create pull requests', 'review_pr — Review PRs + post comments', 'list_issues — List & filter issues', 'create_issue — Create new issues', 'github_api — Raw API access', 'Co-authored-by on every commit'] },+ { title: '🎵 Spotify', items: ['spotify_search — Search tracks, artists, albums, playlists', 'spotify_play — Play on your devices', 'spotify_pause/next/previous — Playback controls', 'spotify_now_playing — What\'s playing + progress bar', 'spotify_devices — List & select devices', 'spotify_like/top_tracks/playlists — Library access', 'spotify_volume/shuffle/repeat/queue — Full player control'] },+ { title: '🤖 Sub-Agents', items: ['delegate_task — Spawn parallel AI agents', 'list_agents — Monitor running agents', 'stop_agent — Halt a specific agent', '/agents — See all agents + status', '/halt — Emergency stop all agents', 'File locks for concurrent safety', 'Auto-concurrency from CPU/RAM'] },{ title: '🧩 Skills', items: ['install_skill — Install from URL or content', 'list_skills — Show installed skills', 'use_skill — Invoke a skill'] },{ title: '⏰ Scheduler', items: ['schedule_task — Cron or one-shot tasks', 'list_scheduled_tasks — View all tasks', 'cancel_scheduled_task — Cancel a task'] },{ title: '📊 System', items: ['budget_status — Check token budget'] },@@ -409,6 +412,8 @@ export default function LandingPage(): React.ReactElement {['Soul / Persona System', '4 markdown files', 'Custom instructions', 'CLAUDE.md'],['Token Budget', 'Daily budget + override', '—', '—'],['Multi-Channel', 'CLI + Telegram + more', 'All', 'All'],+ ['Sub-Agents', 'Parallel AI workers, non-blocking', '—', '—'],+ ['Spotify Integration', 'Native playback + DJ mode', '—', '—'],['Skill System', 'Install, invoke, schedule', '—', '—'],['Cron + Delayed Scheduling', 'Persisted, auto-restore', '—', '—'],['Permission Hardening', 'Blocklist + scope + approval', 'Confirmation prompts', 'Permission prompts'],@@ -443,6 +448,8 @@ export default function LandingPage(): React.ReactElement {{[{ label: 'Core', value: 'TypeScript + Node.js 18+', desc: 'ESM, tsup build, SQLite-backed second brain' },{ label: 'AI SDK', value: 'Vercel AI SDK v4', desc: 'streamText + generateText, 10-step agentic loop' },+ { label: 'Sub-Agents', value: 'Same-process async coroutines', desc: 'Parallel task delegation, file locks, resource-aware concurrency' },+ { label: 'Spotify', value: 'Native Web API integration', desc: 'OAuth2 auth, 14 tools, DJ mode skill, Premium + free support' },{ label: 'Providers', value: 'DeepSeek · OpenAI · Anthropic · Grok · Ollama Cloud · Ollama Local', desc: 'Validated onboarding, model discovery, and fallback with last-successful tracking' },{ label: 'Memory', value: 'JSONL + SQLite', desc: 'Short-term, long-term, episodic + second brain' },{ label: 'Telegram', value: 'grammY', desc: 'Long polling, pairing codes, CLI-managed access requests, broadcasts, file uploads' },