@cosmicstack/mercury-agent 0.3.4 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@
 </p>
 
 <p align="center">
-  Runs 24/7 from CLI or Telegram. 21 built-in tools. Extensible skills. Asks before it acts.
+  Runs 24/7 from CLI or Telegram. 31 built-in tools. Extensible skills. Asks before it acts.
 </p>
 
 <p align="center">
@@ -136,8 +136,9 @@ Type these during a conversation — they don't consume API tokens. Work on both
 
 | Category | Tools |
 |----------|-------|
-| **Filesystem** | `read_file`, `write_file`, `create_file`, `edit_file`, `list_dir`, `delete_file`, `send_file` |
-| **Shell** | `run_command`, `approve_command` |
+| **Filesystem** | `read_file`, `write_file`, `create_file`, `edit_file`, `list_dir`, `delete_file`, `send_file`, `approve_scope` |
+| **Shell** | `run_command`, `cd`, `approve_command` |
+| **Messaging** | `send_message` |
 | **Git** | `git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push` |
 | **Web** | `fetch_url` |
 | **Skills** | `install_skill`, `list_skills`, `use_skill` |
@@ -151,6 +152,15 @@ Type these during a conversation — they don't consume API tokens. Work on both
 | **CLI** | Readline prompt, real-time text streaming, markdown rendering, file display |
 | **Telegram** | HTML formatting, file uploads (photos, audio, video, documents), typing indicators, `/budget` commands |
 
+### Telegram Pairing
+
+Mercury uses a **single-owner pairing model** — only one Telegram account can be paired at a time.
+
+- **Unpaired bots** only process `/start` or `/pair`. All other messages are ignored. This prevents unauthorized access.
+- **To pair:** Send `/start` to your Mercury bot in a private chat. The bot records your user ID and chat ID.
+- **To unpair:** Send `/unpair` to remove the pairing.
+- Mercury only works in private (one-to-one) chats. Group messages are ignored.
+
 ## Scheduler
 
 - **Recurring**: `schedule_task` with cron expressions (`0 9 * * *` for daily at 9am)
@@ -165,6 +175,7 @@ All runtime data lives in `~/.mercury/` — not in your project directory.
 | Path | Purpose |
 |------|---------|
 | `~/.mercury/mercury.yaml` | Main config (providers, channels, budget) |
+| `~/.mercury/.env` | API keys and tokens (loaded alongside project .env) |
 | `~/.mercury/soul/*.md` | Agent personality (soul, persona, taste, heartbeat) |
 | `~/.mercury/permissions.yaml` | Capabilities and approval rules |
 | `~/.mercury/skills/` | Installed skills |
@@ -178,9 +189,18 @@ All runtime data lives in `~/.mercury/` — not in your project directory.
 
 Configure multiple LLM providers. Mercury tries them in order and falls back automatically:
 
-- **DeepSeek** — default, cost-effective
-- **OpenAI** — GPT-4o-mini and others
-- **Anthropic** — Claude and others
+| Provider | Default Model | API Key | Notes |
+|----------|--------------|---------|-------|
+| **DeepSeek** | deepseek-chat | `DEEPSEEK_API_KEY` | Default, cost-effective |
+| **OpenAI** | gpt-4o-mini | `OPENAI_API_KEY` | GPT-4o, o3, etc. |
+| **Anthropic** | claude-sonnet-4 | `ANTHROPIC_API_KEY` | Claude Sonnet, Haiku, Opus |
+| **Grok (xAI)** | grok-4 | `GROK_API_KEY` | OpenAI-compatible endpoint |
+| **Ollama Cloud** | gpt-oss:120b | `OLLAMA_CLOUD_API_KEY` | Remote Ollama via API |
+| **Ollama Local** | gpt-oss:20b | No key needed | Local Ollama instance |
+
+When a provider fails, Mercury automatically tries the next one. It remembers the last successful provider and starts there on the next request.
+
+> **More providers incoming** — Google Gemini, Mistral, and others are on the roadmap. Mercury's OpenAI-compatible architecture also supports custom endpoints via base URL configuration.
 
 ## Architecture