@cosmicstack/mercury-agent 0.4.0 → 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,12 +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
-- **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
 

package/dist/index.js

@@ -762,6 +762,48 @@ var Lifecycle = class {
 };
 
 // src/core/agent.ts
+var ToolCallLoopDetector = class {
+  recentCalls = [];
+  maxEntries = 10;
+  record(toolName, params) {
+    const paramsKey = JSON.stringify(params).slice(0, 100);
+    this.recentCalls.push({ tool: toolName, params: paramsKey });
+    if (this.recentCalls.length > this.maxEntries) {
+      this.recentCalls.shift();
+    }
+  }
+  detect() {
+    if (this.recentCalls.length < 3) return null;
+    const last = this.recentCalls[this.recentCalls.length - 1];
+    let consecutiveCount = 0;
+    for (let i = this.recentCalls.length - 1; i >= 0; i--) {
+      if (this.recentCalls[i].tool === last.tool && this.recentCalls[i].params === last.params) {
+        consecutiveCount++;
+      } else {
+        break;
+      }
+    }
+    if (consecutiveCount >= 3) {
+      return { tool: last.tool, count: consecutiveCount };
+    }
+    const lastTool = last.tool;
+    let toolCount = 0;
+    for (let i = this.recentCalls.length - 1; i >= 0; i--) {
+      if (this.recentCalls[i].tool === lastTool) {
+        toolCount++;
+      } else {
+        break;
+      }
+    }
+    if (toolCount >= 4) {
+      return { tool: lastTool, count: toolCount };
+    }
+    return null;
+  }
+  reset() {
+    this.recentCalls = [];
+  }
+};
 var MAX_STEPS = 10;
 var Agent = class {
   constructor(config, providers, identity, shortTerm, longTerm, episodic, channels, tokenBudget, capabilities, scheduler) {
@@ -923,6 +965,30 @@ You can override this:
       const recentMemory = this.shortTerm.getRecent(msg.channelId, 10);
       const relevantFacts = this.longTerm.search(msg.content, 3);
       const messages = [];
+      const recentSteps = this.shortTerm.getRecent(msg.channelId, 4);
+      let loopWarning = null;
+      if (recentSteps.length >= 3) {
+        const toolCallPattern = /\[Using: (.+?)\]/g;
+        const toolCalls = [];
+        for (const m of recentSteps) {
+          if (m.role === "assistant") {
+            let match;
+            while ((match = toolCallPattern.exec(m.content)) !== null) {
+              toolCalls.push(match[1]);
+            }
+          }
+        }
+        if (toolCalls.length >= 3) {
+          const last3 = toolCalls.slice(-3);
+          if (last3[0] === last3[1] && last3[1] === last3[2]) {
+            loopWarning = `[SYSTEM WARNING] You have called ${last3[0]} 3+ times in a row with the same result. Stop repeating this call. Try a different approach \u2014 if you're failing on permissions, try a different path. If you're failing on git push auth, use github_api with PUT /repos/{owner}/{repo}/contents/{path} to push files directly through the API.`;
+          }
+        }
+      }
+      if (loopWarning) {
+        messages.push({ role: "user", content: loopWarning });
+        messages.push({ role: "assistant", content: "Understood. I will try a different approach." });
+      }
       if (relevantFacts.length > 0) {
         messages.push({
           role: "user",
@@ -952,6 +1018,7 @@ You can override this:
       let usedProvider = null;
       let lastError = null;
       let streamedText = "";
+      const loopDetector = new ToolCallLoopDetector();
       const canStream = msg.channelType === "cli" || msg.channelType === "telegram" && this.telegramStreaming;
       for (const provider of fallbackIterator) {
         try {
@@ -967,6 +1034,13 @@ You can override this:
                 if (toolCalls && toolCalls.length > 0) {
                   const names = toolCalls.map((tc) => tc.toolName).join(", ");
                   logger.info({ tools: names }, "Tool call step");
+                  for (const tc of toolCalls) {
+                    loopDetector.record(tc.toolName, tc.args);
+                  }
+                  const loop = loopDetector.detect();
+                  if (loop) {
+                    logger.warn({ tool: loop.tool, count: loop.count }, "Tool call loop detected");
+                  }
                   await channel.send(`  [Using: ${names}]`, msg.channelId).catch(() => {
                   });
                 }
@@ -1004,6 +1078,13 @@ You can override this:
                 if (toolCalls && toolCalls.length > 0) {
                   const names = toolCalls.map((tc) => tc.toolName).join(", ");
                   logger.info({ tools: names }, "Tool call step");
+                  for (const tc of toolCalls) {
+                    loopDetector.record(tc.toolName, tc.args);
+                  }
+                  const loop = loopDetector.detect();
+                  if (loop) {
+                    logger.warn({ tool: loop.tool, count: loop.count }, "Tool call loop detected");
+                  }
                   if (channel && msg.channelType !== "internal") {
                     await channel.send(`  [Using: ${names}]`, msg.channelId).catch(() => {
                     });
@@ -1098,16 +1179,35 @@ You can override this:
     if (this.tokenBudget.getUsagePercentage() > 70) {
       prompt += "\nBe concise to conserve tokens.";
     }
+    prompt += `
+
+Environment:
+- Platform: ${process.platform}
+- Working directory: ${this.capabilities.getCwd()}`;
     const toolNames = this.capabilities.getToolNames();
     const githubTools = ["create_pr", "review_pr", "list_issues", "create_issue", "github_api"];
     const hasGitHub = githubTools.some((t) => toolNames.includes(t));
     if (hasGitHub) {
-      let githubHint = "\n\nGitHub companion is active. You can create pull requests, review PRs, manage issues, and use the GitHub API.";
+      let githubHint = "\n\nGitHub companion is active.";
       const { defaultOwner, defaultRepo } = this.config.github;
       if (defaultOwner && defaultRepo) {
         githubHint += ` Default repo: ${defaultOwner}/${defaultRepo}. Use this when the user doesn't specify a repo.`;
       }
-      githubHint += ' When the user says "create a PR", use create_pr. When they ask about issues, use list_issues or create_issue. When they ask to review a PR, use review_pr. Always specify owner and repo parameters.';
+      githubHint += `
+
+Available GitHub tools and when to use them:
+- git_add, git_commit, git_push: LOCAL git operations (stage, commit, push to a remote you have SSH/auth access to). All commits include "Co-authored-by: Mercury <mercury@cosmicstack.org>".
+- create_pr: Create a pull request on GitHub. The head branch must already exist on the remote.
+- review_pr: Get PR details and optionally post a review comment.
+- list_issues, create_issue: Browse and file issues.
+- github_api: Raw GitHub API access. IMPORTANT USE CASES:
+  - Push files directly to GitHub via PUT /repos/{owner}/{repo}/contents/{path} when git push fails due to auth. The body must include "message" and "content" (base64-encoded file content). This creates a commit on GitHub with Mercury as co-author.
+  - Delete files via DELETE /repos/{owner}/{repo}/contents/{path} with a "message" and "sha" in the body.
+  - Any other GitHub API operation not covered by the other tools.
+
+When the user asks to "push to GitHub" or "upload files" and git push fails, use github_api with PUT /repos/{owner}/{repo}/contents/{path} to push content directly through the API. This bypasses local git entirely.
+
+Always specify owner and repo parameters on GitHub tools. The user's GitHub username is ${this.config.github.username || "not set"}.'`;
       prompt += githubHint;
     }
     return prompt;
@@ -3828,11 +3928,42 @@ function createCreateIssueTool() {
 // src/capabilities/github/github-api.ts
 import { tool as tool30 } from "ai";
 import { z as z30 } from "zod";
+var CO_AUTHOR_NAME = "Mercury";
+var CO_AUTHOR_EMAIL = "mercury@cosmicstack.org";
+var CO_AUTHOR_TRAILER = `Co-authored-by: ${CO_AUTHOR_NAME} <${CO_AUTHOR_EMAIL}>`;
+function isContentCreatePath(path3) {
+  return /^\/repos\/[^/]+\/[^/]+\/contents\//.test(path3);
+}
+function injectCoAuthor(body) {
+  const result = { ...body };
+  if (typeof result.message === "string" && !result.message.includes(CO_AUTHOR_TRAILER)) {
+    result.message += `
+
+${CO_AUTHOR_TRAILER}`;
+  }
+  if (!result.committer || typeof result.committer !== "object") {
+    result.committer = { name: CO_AUTHOR_NAME, email: CO_AUTHOR_EMAIL };
+  }
+  if (!result.author || typeof result.author !== "object") {
+    result.author = { name: CO_AUTHOR_NAME, email: CO_AUTHOR_EMAIL };
+  }
+  return result;
+}
 function createGithubApiTool() {
   return tool30({
-    description: "Make a raw request to the GitHub API. Use this for any GitHub operation not covered by other tools. GET requests (read-only) are always allowed. Write operations (POST, PUT, PATCH, DELETE) will ask the user for approval via the permission system.",
+    description: `Make a raw request to the GitHub API. GET requests (read-only) are always allowed. Write operations (POST, PUT, PATCH, DELETE) may require user approval.
+
+Common operations you can perform:
+- Push a file: PUT /repos/{owner}/{repo}/contents/{path} \u2014 body must include "message" (commit message) and "content" (base64-encoded file). For updates, also include "sha" from the current file. Co-authored-by Mercury is automatically included.
+- Delete a file: DELETE /repos/{owner}/{repo}/contents/{path} \u2014 body must include "message" and "sha".
+- List branches: GET /repos/{owner}/{repo}/branches
+- Get file contents: GET /repos/{owner}/{repo}/contents/{path}
+- Search code: GET /search/code?q={query}
+- Any other GitHub API v3 endpoint.
+
+IMPORTANT: When the user wants to push code or files to GitHub and git push fails (auth issues, no SSH key, etc.), use PUT /repos/{owner}/{repo}/contents/{path} to create or update files directly through the API. This bypasses local git and creates a commit with Mercury as co-author.`,
     parameters: z30.object({
-      path: z30.string().describe("Full API path (e.g., /repos/owner/repo/issues or /user)"),
+      path: z30.string().describe("Full API path (e.g., /repos/owner/repo/issues or /repos/owner/repo/contents/path/to/file)"),
       method: z30.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method").default("GET"),
       body: z30.string().describe("JSON body for write requests (as a JSON string)").optional()
     }),
@@ -3846,6 +3977,9 @@ function createGithubApiTool() {
             return "Error: body must be valid JSON.";
           }
         }
+        if (parsedBody && isContentCreatePath(path3) && (method === "PUT" || method === "POST" || method === "PATCH")) {
+          parsedBody = injectCoAuthor(parsedBody);
+        }
         const result = await githubRequest(path3, {
           method,
           body: parsedBody