@cosmicstack/mercury-agent 0.4.0 → 0.5.0

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">
@@ -110,6 +110,13 @@ In daemon mode, Telegram becomes your primary channel — CLI is log-only since
 | `mercury setup` | Re-run the setup wizard |
 | `mercury status` | Show config and daemon status |
 | `mercury help` | Show full manual |
+| `mercury telegram list` | List approved and pending Telegram users |
+| `mercury telegram approve <code\|id>` | Approve a pairing code or pending request |
+| `mercury telegram reject <id>` | Reject a pending Telegram access request |
+| `mercury telegram remove <id>` | Remove an approved Telegram user |
+| `mercury telegram promote <id>` | Promote a Telegram member to admin |
+| `mercury telegram demote <id>` | Demote a Telegram admin to member |
+| `mercury telegram reset` | Clear all Telegram access and start fresh |
 | `mercury service install` | Install as system service (auto-start on boot) |
 | `mercury service uninstall` | Uninstall system service |
 | `mercury service status` | Show system service status |
@@ -136,8 +143,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` |
@@ -148,8 +156,20 @@ Type these during a conversation — they don't consume API tokens. Work on both
 
 | Channel | Features |
 |---------|----------|
-| **CLI** | Readline prompt, real-time text streaming, markdown rendering, file display |
-| **Telegram** | HTML formatting, file uploads (photos, audio, video, documents), typing indicators, `/budget` commands |
+| **CLI** | Readline prompt, arrow-key command menus, real-time text streaming, markdown rendering |
+| **Telegram** | HTML formatting, file uploads, typing indicators, multi-user access with admin/member roles |
+
+### Telegram Access
+
+Mercury uses an **organization access model** with admins and members.
+
+- **First-time setup:** Send `/start` to your bot, receive a pairing code, enter it in the CLI with `mercury telegram approve <code>`. You become the first admin.
+- **Additional users:** Send `/start` to request access. Admins approve or reject from the CLI.
+- **Roles:** Admins can approve/reject requests, promote/demote users, and reset access. Members can chat with Mercury.
+- **Reset:** Admins can send `/unpair` in Telegram or run `mercury telegram reset` in the CLI to clear all access and start fresh.
+- Private chats only — group messages are always ignored.
+
+CLI commands: `mercury telegram list|approve|reject|remove|promote|demote|reset`
 
 ## Scheduler
 
@@ -165,6 +185,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,12 +199,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
-- **Grok / xAI** — OpenAI-compatible Grok models
-- **Ollama Cloud** — remote Ollama models via API key
-- **Ollama Local** — models running on your local Ollama instance
+| 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