@cosmicstack/mercury-agent 0.3.4 → 0.4.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync13, existsSync as existsSync16 } from "fs";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync13, existsSync as existsSync18 } from "fs";
 import { fileURLToPath } from "url";
 import { dirname as dirname3, join as join11 } from "path";
 import { Command } from "commander";
@@ -45,7 +45,7 @@ function getDefaultConfig() {
       creator: getEnv("MERCURY_CREATOR", "")
     },
     providers: {
-      default: getEnv("DEFAULT_PROVIDER", "openai"),
+      default: getEnv("DEFAULT_PROVIDER", "deepseek"),
       openai: {
         name: "openai",
         apiKey: getEnv("OPENAI_API_KEY", ""),
@@ -66,6 +66,27 @@ function getDefaultConfig() {
         baseUrl: getEnv("DEEPSEEK_BASE_URL", "https://api.deepseek.com/v1"),
         model: getEnv("DEEPSEEK_MODEL", "deepseek-chat"),
         enabled: getEnvBool("DEEPSEEK_ENABLED", true)
+      },
+      grok: {
+        name: "grok",
+        apiKey: getEnv("GROK_API_KEY", ""),
+        baseUrl: getEnv("GROK_BASE_URL", "https://api.x.ai/v1"),
+        model: getEnv("GROK_MODEL", "grok-4"),
+        enabled: getEnvBool("GROK_ENABLED", true)
+      },
+      ollamaCloud: {
+        name: "ollamaCloud",
+        apiKey: getEnv("OLLAMA_CLOUD_API_KEY", ""),
+        baseUrl: getEnv("OLLAMA_CLOUD_BASE_URL", "https://ollama.com/api"),
+        model: getEnv("OLLAMA_CLOUD_MODEL", "gpt-oss:120b"),
+        enabled: getEnvBool("OLLAMA_CLOUD_ENABLED", true)
+      },
+      ollamaLocal: {
+        name: "ollamaLocal",
+        apiKey: "",
+        baseUrl: getEnv("OLLAMA_LOCAL_BASE_URL", "http://127.0.0.1:11434/api"),
+        model: getEnv("OLLAMA_LOCAL_MODEL", "gpt-oss:20b"),
+        enabled: getEnvBool("OLLAMA_LOCAL_ENABLED", false)
       }
     },
     channels: {
@@ -140,6 +161,25 @@ function deepMerge(target, source) {
   }
   return result;
 }
+function isProviderConfigured(provider) {
+  if (!provider.enabled) return false;
+  if (provider.name === "ollamaLocal") {
+    return provider.baseUrl.length > 0 && provider.model.length > 0;
+  }
+  return provider.apiKey.length > 0;
+}
+function setTelegramPairing(config, userId, chatId, username) {
+  config.channels.telegram.pairedUserId = userId;
+  config.channels.telegram.pairedChatId = chatId;
+  config.channels.telegram.pairedUsername = username || void 0;
+  return config;
+}
+function clearTelegramPairing(config) {
+  delete config.channels.telegram.pairedUserId;
+  delete config.channels.telegram.pairedChatId;
+  delete config.channels.telegram.pairedUsername;
+  return config;
+}
 
 // src/utils/logger.ts
 import pino from "pino";
@@ -573,6 +613,42 @@ var AnthropicProvider = class extends BaseProvider {
   }
 };
 
+// src/providers/ollama.ts
+import { createOllama } from "ollama-ai-provider";
+var OllamaProvider = class extends BaseProvider {
+  name;
+  model;
+  client;
+  modelInstance;
+  constructor(config) {
+    super(config);
+    this.name = config.name;
+    this.model = config.model;
+    const headers = config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : void 0;
+    this.client = createOllama({
+      baseURL: config.baseUrl,
+      headers
+    });
+    this.modelInstance = this.client(config.model);
+  }
+  async generateText(_prompt, _systemPrompt) {
+    throw new Error("Use getModelInstance() with the AI SDK agent loop");
+  }
+  async *streamText(_prompt, _systemPrompt) {
+    throw new Error("Use getModelInstance() with the AI SDK agent loop");
+  }
+  isAvailable() {
+    if (!this.config.enabled) return false;
+    if (this.name === "ollamaLocal") {
+      return this.config.baseUrl.length > 0 && this.config.model.length > 0;
+    }
+    return this.config.apiKey.length > 0;
+  }
+  getModelInstance() {
+    return this.modelInstance;
+  }
+};
+
 // src/providers/registry.ts
 var ProviderRegistry = class {
   providers = /* @__PURE__ */ new Map();
@@ -581,14 +657,24 @@ var ProviderRegistry = class {
   constructor(config) {
     this.defaultName = config.providers.default;
     const entries = [
+      config.providers.deepseek,
       config.providers.openai,
       config.providers.anthropic,
-      config.providers.deepseek
+      config.providers.grok,
+      config.providers.ollamaCloud,
+      config.providers.ollamaLocal
     ];
     for (const pc of entries) {
-      if (!pc.enabled || !pc.apiKey) continue;
+      if (!isProviderConfigured(pc)) continue;
       try {
-        const provider = pc.name === "anthropic" ? new AnthropicProvider(pc) : new OpenAICompatProvider(pc);
+        let provider;
+        if (pc.name === "anthropic") {
+          provider = new AnthropicProvider(pc);
+        } else if (pc.name === "ollamaCloud" || pc.name === "ollamaLocal") {
+          provider = new OllamaProvider(pc);
+        } else {
+          provider = new OpenAICompatProvider(pc);
+        }
         this.providers.set(pc.name, provider);
         logger.info({ provider: pc.name, model: pc.model }, "Provider registered");
       } catch (err) {
@@ -676,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) {
@@ -837,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",
@@ -866,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 {
@@ -881,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(() => {
                   });
                 }
@@ -918,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(() => {
                     });
@@ -1012,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;
@@ -1190,11 +1376,13 @@ Or use /budget override, /budget reset, /budget set <number> anytime.`,
     if (cmd === "/status") {
       const config = ctx.config();
       const budget = ctx.tokenBudget();
+      const telegramPairing = config.channels.telegram.pairedUserId != null ? `paired to user ${config.channels.telegram.pairedUserId}${config.channels.telegram.pairedUsername ? ` (@${config.channels.telegram.pairedUsername})` : ""}` : "unpaired";
       const lines = [
         `**${config.identity.name}** \u2014 Status`,
         `Owner: ${config.identity.owner || "(not set)"}`,
         `Provider: ${config.providers.default}`,
         `Telegram: ${config.channels.telegram.enabled ? "enabled" : "disabled"}`,
+        `Telegram pairing: ${telegramPairing}`,
         `Budget: ${budget.getStatusText()}`,
         `Skills: ${ctx.skillNames().length > 0 ? ctx.skillNames().join(", ") : "none"}`
       ];
@@ -1727,16 +1915,16 @@ var CLIChannel = class extends BaseChannel {
     }
   }
   async prompt(question) {
-    return new Promise((resolve11) => {
-      this.rl?.question(question, (answer) => resolve11(answer.trim()));
+    return new Promise((resolve13) => {
+      this.rl?.question(question, (answer) => resolve13(answer.trim()));
     });
   }
   async askPermission(prompt) {
-    return new Promise((resolve11) => {
+    return new Promise((resolve13) => {
       console.log("");
       console.log(chalk2.yellow(`  \u26A0 ${prompt}`));
       this.rl?.question(chalk2.yellow("  > "), (answer) => {
-        resolve11(answer.trim());
+        resolve13(answer.trim());
       });
     });
   }
@@ -1752,6 +1940,7 @@ var TelegramChannel = class extends BaseChannel {
   constructor(config) {
     super();
     this.config = config;
+    this.ownerChatId = config.channels.telegram.pairedChatId ?? null;
   }
   config;
   type = "telegram";
@@ -1773,9 +1962,33 @@ var TelegramChannel = class extends BaseChannel {
     bot.api.config.use(autoRetry());
     bot.on("message:text", async (ctx) => {
       const chatId = ctx.chat.id;
-      if (!this.isAllowedChat(chatId)) return;
+      const userId = ctx.from?.id;
+      const text = ctx.message.text?.trim() || "";
+      if (!userId) return;
+      if (ctx.chat.type !== "private") {
+        await this.sendDirectMessage(chatId, "This bot is only available in private one-to-one chats.");
+        return;
+      }
+      if (!this.isPaired()) {
+        await this.handleUnpairedMessage(userId, chatId, text, ctx.from?.username);
+        return;
+      }
+      if (!this.isAuthorizedUser(userId)) {
+        await this.sendDirectMessage(chatId, "This bot is not available to you.");
+        return;
+      }
       this.ownerChatId = chatId;
       logger.info({ chatId, text: ctx.message.text?.slice(0, 50) }, "Telegram message received");
+      const command = text.toLowerCase();
+      if (command === "/start" || command === "/pair") {
+        await this.sendDirectMessage(chatId, this.getPairingStatusMessage());
+        return;
+      }
+      if (command === "/unpair") {
+        this.unpair();
+        await this.sendDirectMessage(chatId, "Telegram pairing removed. Send /start to pair this Mercury instance again.");
+        return;
+      }
       const msg = {
         id: ctx.message.message_id.toString(),
         channelId: `telegram:${chatId}`,
@@ -1815,6 +2028,8 @@ var TelegramChannel = class extends BaseChannel {
   async registerCommands() {
     if (!this.bot) return;
     const commands = [
+      { command: "start", description: "Pair this Telegram account to Mercury" },
+      { command: "pair", description: "Pair this Telegram account to Mercury" },
       { command: "help", description: "Show capabilities and commands manual" },
       { command: "status", description: "Show agent config, budget, and uptime" },
       { command: "tools", description: "List all loaded tools" },
@@ -1823,7 +2038,8 @@ var TelegramChannel = class extends BaseChannel {
       { command: "budget_override", description: "Override budget for one request" },
       { command: "budget_reset", description: "Reset token usage to zero" },
       { command: "budget_set", description: "Set new daily token budget" },
-      { command: "stream", description: "Toggle text streaming on/off" }
+      { command: "stream", description: "Toggle text streaming on/off" },
+      { command: "unpair", description: "Remove Telegram pairing for this Mercury instance" }
     ];
     try {
       await this.bot.api.setMyCommands(commands);
@@ -1999,15 +2215,15 @@ var TelegramChannel = class extends BaseChannel {
         reply_markup: keyboard
       });
     }
-    return new Promise((resolve11) => {
-      this.pendingApprovals.set(`${id}:yes`, () => resolve11("yes"));
-      this.pendingApprovals.set(`${id}:always`, () => resolve11("always"));
-      this.pendingApprovals.set(`${id}:no`, () => resolve11("no"));
+    return new Promise((resolve13) => {
+      this.pendingApprovals.set(`${id}:yes`, () => resolve13("yes"));
+      this.pendingApprovals.set(`${id}:always`, () => resolve13("always"));
+      this.pendingApprovals.set(`${id}:no`, () => resolve13("no"));
       setTimeout(() => {
         this.pendingApprovals.delete(`${id}:yes`);
         this.pendingApprovals.delete(`${id}:always`);
         this.pendingApprovals.delete(`${id}:no`);
-        resolve11("no");
+        resolve13("no");
       }, 12e4);
     });
   }
@@ -2044,19 +2260,57 @@ var TelegramChannel = class extends BaseChannel {
     return [".mp4", ".mov", ".avi", ".mkv", ".webm"].includes(ext);
   }
   parseChatId(targetId) {
-    if (!targetId) return this.ownerChatId;
+    if (!targetId) return this.ownerChatId ?? this.config.channels.telegram.pairedChatId ?? null;
     if (targetId.startsWith("telegram:")) {
       const raw = Number(targetId.split(":")[1]);
-      return isNaN(raw) ? this.ownerChatId : raw;
+      return isNaN(raw) ? this.ownerChatId ?? this.config.channels.telegram.pairedChatId ?? null : raw;
     }
-    if (targetId === "notification") return this.ownerChatId;
+    if (targetId === "notification") return this.ownerChatId ?? this.config.channels.telegram.pairedChatId ?? null;
     const num = Number(targetId);
-    return isNaN(num) ? this.ownerChatId : num;
+    return isNaN(num) ? this.ownerChatId ?? this.config.channels.telegram.pairedChatId ?? null : num;
+  }
+  isPaired() {
+    return typeof this.config.channels.telegram.pairedUserId === "number";
   }
-  isAllowedChat(chatId) {
-    const allowed = this.config.channels.telegram.allowedChatIds;
-    if (!allowed || allowed.length === 0) return true;
-    return allowed.includes(chatId);
+  isAuthorizedUser(userId) {
+    return this.config.channels.telegram.pairedUserId === userId;
+  }
+  async handleUnpairedMessage(userId, chatId, text, username) {
+    const command = text.toLowerCase();
+    if (command === "/start" || command === "/pair") {
+      setTelegramPairing(this.config, userId, chatId, username);
+      saveConfig(this.config);
+      this.ownerChatId = chatId;
+      logger.info({ chatId, userId, username }, "Telegram paired to owner");
+      await this.sendDirectMessage(chatId, this.getPairingStatusMessage(true));
+      return;
+    }
+    await this.sendDirectMessage(
+      chatId,
+      "This Mercury instance is not paired yet. Send /start to pair this bot to your Telegram account."
+    );
+  }
+  getPairingStatusMessage(newlyPaired = false) {
+    const username = this.config.channels.telegram.pairedUsername ? ` (@${this.config.channels.telegram.pairedUsername})` : "";
+    const prefix = newlyPaired ? "Telegram paired successfully." : "This Telegram account is already paired.";
+    return `${prefix}
+
+Owner user ID: ${this.config.channels.telegram.pairedUserId}${username}`;
+  }
+  unpair() {
+    clearTelegramPairing(this.config);
+    saveConfig(this.config);
+    this.ownerChatId = null;
+    logger.info("Telegram pairing cleared");
+  }
+  async sendDirectMessage(chatId, content) {
+    if (!this.bot) return;
+    try {
+      await this.bot.api.sendMessage(chatId, mdToTelegram(content), { parse_mode: "HTML" });
+    } catch {
+      await this.bot.api.sendMessage(chatId, content).catch(() => {
+      });
+    }
   }
 };
 
@@ -2356,8 +2610,8 @@ var PermissionManager = class {
   clearElevation() {
     this.elevatedCommands.clear();
   }
-  isElevated(tool30) {
-    if (this.elevatedCommands.has(tool30)) return true;
+  isElevated(tool32) {
+    if (this.elevatedCommands.has(tool32)) return true;
     return false;
   }
   isShellElevated() {
@@ -2617,15 +2871,15 @@ Allow access?`;
 import { tool } from "ai";
 import { z } from "zod";
 import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve3 } from "path";
-function createReadFileTool(permissions) {
+import { resolve as resolve3, isAbsolute } from "path";
+function createReadFileTool(permissions, getCwd) {
   return tool({
     description: "Read the contents of a file. The path must be within an allowed scope.",
     parameters: z.object({
       path: z.string().describe("Absolute or relative path to the file")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve3(path3);
+      const resolved = isAbsolute(path3) ? resolve3(path3) : resolve3(getCwd(), path3);
       const check = await permissions.checkFsAccess(resolved, "read");
       if (!check.allowed) {
         const parentDir = resolve3(resolved, "..");
@@ -2654,8 +2908,8 @@ function createReadFileTool(permissions) {
 import { tool as tool2 } from "ai";
 import { z as z2 } from "zod";
 import { existsSync as existsSync8, writeFileSync as writeFileSync7 } from "fs";
-import { resolve as resolve4 } from "path";
-function createWriteFileTool(permissions) {
+import { resolve as resolve4, isAbsolute as isAbsolute2 } from "path";
+function createWriteFileTool(permissions, getCwd) {
   return tool2({
     description: "Write content to an existing file. The path must be within a writable scope.",
     parameters: z2.object({
@@ -2663,7 +2917,7 @@ function createWriteFileTool(permissions) {
       content: z2.string().describe("The content to write to the file")
     }),
     execute: async ({ path: path3, content }) => {
-      const resolved = resolve4(path3);
+      const resolved = isAbsolute2(path3) ? resolve4(path3) : resolve4(getCwd(), path3);
       const check = await permissions.checkFsAccess(resolved, "write");
       if (!check.allowed) {
         const parentDir = resolve4(resolved, "..");
@@ -2686,8 +2940,8 @@ function createWriteFileTool(permissions) {
 import { tool as tool3 } from "ai";
 import { z as z3 } from "zod";
 import { existsSync as existsSync9, writeFileSync as writeFileSync8, mkdirSync as mkdirSync7 } from "fs";
-import { resolve as resolve5, dirname as dirname2 } from "path";
-function createCreateFileTool(permissions) {
+import { resolve as resolve5, dirname as dirname2, isAbsolute as isAbsolute3 } from "path";
+function createCreateFileTool(permissions, getCwd) {
   return tool3({
     description: "Create a new file with the given content. Also creates parent directories if needed. The path must be within a writable scope.",
     parameters: z3.object({
@@ -2695,7 +2949,7 @@ function createCreateFileTool(permissions) {
       content: z3.string().describe("The content of the new file")
     }),
     execute: async ({ path: path3, content }) => {
-      const resolved = resolve5(path3);
+      const resolved = isAbsolute3(path3) ? resolve5(path3) : resolve5(getCwd(), path3);
       const check = await permissions.checkFsAccess(resolved, "write");
       if (!check.allowed) {
         const parentDir = resolve5(resolved, "..");
@@ -2722,15 +2976,15 @@ function createCreateFileTool(permissions) {
 import { tool as tool4 } from "ai";
 import { z as z4 } from "zod";
 import { existsSync as existsSync10, readdirSync as readdirSync2, statSync } from "fs";
-import { resolve as resolve6 } from "path";
-function createListDirTool(permissions) {
+import { resolve as resolve6, isAbsolute as isAbsolute4 } from "path";
+function createListDirTool(permissions, getCwd) {
   return tool4({
     description: "List the contents of a directory. Shows file names, types, and sizes.",
     parameters: z4.object({
       path: z4.string().describe("Absolute or relative path to the directory")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve6(path3);
+      const resolved = isAbsolute4(path3) ? resolve6(path3) : resolve6(getCwd(), path3);
       const check = await permissions.checkFsAccess(resolved, "read");
       if (!check.allowed) {
         return `Error: Permission denied for read access to ${resolved}. Use the approve_scope tool with path="${resolved}" and mode="read" to request access from the user.`;
@@ -2780,15 +3034,15 @@ function formatSize(bytes) {
 import { tool as tool5 } from "ai";
 import { z as z5 } from "zod";
 import { existsSync as existsSync11, unlinkSync as unlinkSync2 } from "fs";
-import { resolve as resolve7 } from "path";
-function createDeleteFileTool(permissions) {
+import { resolve as resolve7, isAbsolute as isAbsolute5 } from "path";
+function createDeleteFileTool(permissions, getCwd) {
   return tool5({
     description: "Delete a file. This action cannot be undone. The path must be within a writable scope. Always asks for confirmation.",
     parameters: z5.object({
       path: z5.string().describe("Absolute or relative path to the file to delete")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve7(path3);
+      const resolved = isAbsolute5(path3) ? resolve7(path3) : resolve7(getCwd(), path3);
       const check = await permissions.checkFsAccess(resolved, "write");
       if (!check.allowed) {
         const parentDir = resolve7(resolved, "..");
@@ -2815,8 +3069,8 @@ function createDeleteFileTool(permissions) {
 import { tool as tool6 } from "ai";
 import { z as z6 } from "zod";
 import { readFileSync as readFileSync9, writeFileSync as writeFileSync9 } from "fs";
-import { resolve as resolve8 } from "path";
-function createEditFileTool(permissions) {
+import { resolve as resolve8, isAbsolute as isAbsolute6 } from "path";
+function createEditFileTool(permissions, getCwd) {
   return tool6({
     description: "Edit a file by replacing an exact string match with new content. Use this instead of write_file when you only need to change part of a file. The old_string must match exactly (including whitespace and indentation). Fails if old_string is not found or found multiple times.",
     parameters: z6.object({
@@ -2825,7 +3079,7 @@ function createEditFileTool(permissions) {
       new_string: z6.string().describe("The text to replace it with")
     }),
     execute: async ({ path: path3, old_string, new_string }) => {
-      const resolved = resolve8(path3);
+      const resolved = isAbsolute6(path3) ? resolve8(path3) : resolve8(getCwd(), path3);
       const fsCheck = await permissions.checkFsAccess(resolved, "write");
       if (!fsCheck.allowed) {
         const parentDir = resolve8(resolved, "..");
@@ -2859,15 +3113,15 @@ function createEditFileTool(permissions) {
 import { tool as tool7 } from "ai";
 import { z as z7 } from "zod";
 import { existsSync as existsSync12, statSync as statSync2 } from "fs";
-import { resolve as resolve9, basename } from "path";
-function createSendFileTool(permissions, sendFile) {
+import { resolve as resolve9, basename, isAbsolute as isAbsolute7 } from "path";
+function createSendFileTool(permissions, getCwd, sendFile) {
   return tool7({
     description: "Send a file to the user. On Telegram the file is uploaded as an attachment. On CLI the file path and size are displayed. The path must be within an allowed read scope.",
     parameters: z7.object({
       path: z7.string().describe("Absolute or relative path to the file to send")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve9(path3);
+      const resolved = isAbsolute7(path3) ? resolve9(path3) : resolve9(getCwd(), path3);
       const check = await permissions.checkFsAccess(resolved, "read");
       if (!check.allowed) {
         const parentDir = resolve9(resolved, "..");
@@ -2895,19 +3149,43 @@ function createSendFileTool(permissions, sendFile) {
   });
 }
 
-// src/capabilities/filesystem/approve-scope.ts
+// src/capabilities/messaging/send-message.ts
 import { tool as tool8 } from "ai";
 import { z as z8 } from "zod";
-import { resolve as resolve10 } from "path";
-function createApproveScopeTool(permissions) {
+function createSendMessageTool(sendMessage) {
   return tool8({
-    description: 'Request user approval to access a directory outside current scopes. Use this when a file tool returns a permission denied error. The user gets an approval prompt (Allow/Always/Deny buttons on Telegram, yes/always/no on CLI). "Allow" grants session-only access. "Always" persists to disk. After approval, retry the original file operation.',
+    description: "Send a message to the paired user through the configured outbound channel. Currently this sends only to the paired Telegram owner. Use this only when the user explicitly asks you to send something to Telegram or asks for scheduled results to be sent there.",
     parameters: z8.object({
-      path: z8.string().describe("The directory path to request access to"),
-      mode: z8.enum(["read", "write"]).describe("The access mode needed")
+      content: z8.string().describe("The message content to send to the paired Telegram owner")
+    }),
+    execute: async ({ content }) => {
+      const trimmed = content.trim();
+      if (!trimmed) {
+        return "Error: Message content cannot be empty.";
+      }
+      try {
+        await sendMessage(trimmed);
+        return "Message sent to the paired Telegram owner.";
+      } catch (err) {
+        return `Error sending message: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/capabilities/filesystem/approve-scope.ts
+import { tool as tool9 } from "ai";
+import { z as z9 } from "zod";
+import { resolve as resolve10, isAbsolute as isAbsolute8 } from "path";
+function createApproveScopeTool(permissions, getCwd) {
+  return tool9({
+    description: 'Request user approval to access a directory outside current scopes. Use this when a file tool returns a permission denied error. The user gets an approval prompt (Allow/Always/Deny buttons on Telegram, yes/always/no on CLI). "Allow" grants session-only access. "Always" persists to disk. After approval, retry the original file operation.',
+    parameters: z9.object({
+      path: z9.string().describe("The directory path to request access to"),
+      mode: z9.enum(["read", "write"]).describe("The access mode needed")
     }),
     execute: async ({ path: path3, mode }) => {
-      const resolved = resolve10(path3);
+      const resolved = isAbsolute8(path3) ? resolve10(path3) : resolve10(getCwd(), path3);
       const result = await permissions.requestScopeExternal(resolved, mode);
       if (result.allowed) {
         return `Access approved for ${mode} access to ${resolved}. You can now retry the file operation.`;
@@ -2918,17 +3196,19 @@ function createApproveScopeTool(permissions) {
 }
 
 // src/capabilities/shell/run-command.ts
-import { tool as tool9 } from "ai";
-import { z as z9 } from "zod";
+import { tool as tool10 } from "ai";
+import { z as z10 } from "zod";
 import { execSync } from "child_process";
-function createRunCommandTool(permissions) {
-  return tool9({
-    description: `Run a shell command. Commands run in the current working directory unless an absolute path is given.
+import { resolve as resolve11, isAbsolute as isAbsolute9 } from "path";
+import { existsSync as existsSync13 } from "fs";
+function createRunCommandTool(permissions, getCwd, setCwd) {
+  return tool10({
+    description: `Run a shell command in the current working directory. Use the cd tool to change directories first \u2014 cd commands within this tool only affect chained commands (e.g., "cd /path && ls"), not subsequent calls.
 Blocked commands (sudo, rm -rf /, etc.) are never executed.
 Auto-approved commands (ls, cat, git status, curl, etc.) run without asking.
-Other commands require user approval \u2014 tell the user what command you want to run and ask for confirmation. If they say "yes", try again. If they say "always", use the approve_command tool.`,
-    parameters: z9.object({
-      command: z9.string().describe("The shell command to execute")
+Other commands require user approval.`,
+    parameters: z10.object({
+      command: z10.string().describe("The shell command to execute")
     }),
     execute: async ({ command }) => {
       const check = await permissions.checkShellCommand(command);
@@ -2942,20 +3222,25 @@ Tell the user what this command does and ask for permission. If they approve, tr
         }
         return `Error: ${check.reason}`;
       }
+      const cwd = getCwd();
       try {
-        logger.info({ cmd: command }, "Executing shell command");
+        logger.info({ cmd: command, cwd }, "Executing shell command");
         const result = execSync(command, {
-          cwd: process.cwd(),
+          cwd,
           timeout: 3e4,
           maxBuffer: 1024 * 1024,
           encoding: "utf-8",
           stdio: ["pipe", "pipe", "pipe"]
         });
-        const output = result?.trim() || "(no output)";
-        return output;
+        const trimmedOutput = result?.trim() || "(no output)";
+        detectCd(command, cwd, setCwd);
+        return trimmedOutput;
       } catch (err) {
         const stderr = err.stderr?.trim();
         const stdout = err.stdout?.trim();
+        if (stdout || stderr) {
+          detectCd(command, cwd, setCwd);
+        }
         let msg = `Command exited with code ${err.status || "unknown"}`;
         if (stdout) msg += `
 Output: ${stdout}`;
@@ -2966,15 +3251,66 @@ Error: ${stderr}`;
     }
   });
 }
+function detectCd(command, currentCwd, setCwd) {
+  const trimmed = command.trim();
+  const cdOnly = trimmed.match(/^cd\s+(.+)$/);
+  if (cdOnly) {
+    const target = cdOnly[1].replace(/^["']|["']$/g, "").replace(/~/, process.env.HOME || "");
+    const resolved = isAbsolute9(target) ? target : resolve11(currentCwd, target);
+    if (existsSync13(resolved)) {
+      setCwd(resolved);
+    }
+    return;
+  }
+  const cdChain = trimmed.match(/cd\s+(.+?)\s*&&/);
+  if (cdChain) {
+    const target = cdChain[1].replace(/^["']|["']$/g, "").replace(/~/, process.env.HOME || "");
+    const resolved = isAbsolute9(target) ? target : resolve11(currentCwd, target);
+    if (existsSync13(resolved)) {
+      setCwd(resolved);
+    }
+  }
+}
+
+// src/capabilities/shell/cd.ts
+import { tool as tool11 } from "ai";
+import { z as z11 } from "zod";
+import { resolve as resolve12, isAbsolute as isAbsolute10 } from "path";
+import { existsSync as existsSync14, statSync as statSync3 } from "fs";
+function createCdTool(getCwd, setCwd) {
+  return tool11({
+    description: "Change the current working directory. All subsequent file operations, shell commands, and git operations will use this directory. Use this before running commands in a specific project folder.",
+    parameters: z11.object({
+      path: z11.string().describe("The directory to change to. Can be absolute or relative to the current directory.")
+    }),
+    execute: async ({ path: path3 }) => {
+      const cwd = getCwd();
+      const resolved = isAbsolute10(path3) ? resolve12(path3) : resolve12(cwd, path3);
+      if (!existsSync14(resolved)) {
+        return `Error: Directory not found: ${resolved}`;
+      }
+      try {
+        const stat = statSync3(resolved);
+        if (!stat.isDirectory()) {
+          return `Error: Not a directory: ${resolved}`;
+        }
+      } catch {
+        return `Error: Cannot access: ${resolved}`;
+      }
+      setCwd(resolved);
+      return `Changed directory to ${resolved}`;
+    }
+  });
+}
 
 // src/capabilities/shell/approve-command.ts
-import { tool as tool10 } from "ai";
-import { z as z10 } from "zod";
+import { tool as tool12 } from "ai";
+import { z as z12 } from "zod";
 function createApproveCommandTool(permissions) {
-  return tool10({
+  return tool12({
     description: 'Permanently approve a command type so it runs without asking in the future. Use this when the user says "always" or "always approve" for a command. For example, if the user says "always approve curl", call this with command="curl".',
-    parameters: z10.object({
-      command: z10.string().describe('The base command to permanently approve (e.g. "curl", "docker", "npm")')
+    parameters: z12.object({
+      command: z12.string().describe('The base command to permanently approve (e.g. "curl", "docker", "npm")')
     }),
     execute: async ({ command }) => {
       const baseCmd = command.trim().split(/\s+/)[0];
@@ -2985,15 +3321,15 @@ function createApproveCommandTool(permissions) {
 }
 
 // src/capabilities/skills/install-skill.ts
-import { tool as tool11 } from "ai";
-import { z as z11 } from "zod";
+import { tool as tool13 } from "ai";
+import { z as z13 } from "zod";
 import { parse as parseYaml4 } from "yaml";
 function createInstallSkillTool(skillLoader) {
-  return tool11({
+  return tool13({
     description: "Install a new skill by providing SKILL.md markdown content or a URL. The content must have YAML frontmatter (---) with at least name and description fields.",
-    parameters: z11.object({
-      content: z11.string().optional().describe("Raw SKILL.md markdown content with YAML frontmatter"),
-      url: z11.string().optional().describe("URL to fetch a SKILL.md from")
+    parameters: z13.object({
+      content: z13.string().optional().describe("Raw SKILL.md markdown content with YAML frontmatter"),
+      url: z13.string().optional().describe("URL to fetch a SKILL.md from")
     }),
     execute: async ({ content, url }) => {
       let skillContent;
@@ -3033,12 +3369,12 @@ function createInstallSkillTool(skillLoader) {
 }
 
 // src/capabilities/skills/list-skills.ts
-import { tool as tool12 } from "ai";
-import { z as z12 } from "zod";
+import { tool as tool14 } from "ai";
+import { z as z14 } from "zod";
 function createListSkillsTool(skillLoader) {
-  return tool12({
+  return tool14({
     description: "List all installed skills with their names and descriptions.",
-    parameters: z12.object({}),
+    parameters: z14.object({}),
     execute: async () => {
       const skills = skillLoader.getDiscovered();
       if (skills.length === 0) {
@@ -3050,13 +3386,13 @@ function createListSkillsTool(skillLoader) {
 }
 
 // src/capabilities/skills/use-skill.ts
-import { tool as tool13 } from "ai";
-import { z as z13 } from "zod";
+import { tool as tool15 } from "ai";
+import { z as z15 } from "zod";
 function createUseSkillTool(skillLoader, permissions) {
-  return tool13({
+  return tool15({
     description: "Load and invoke a skill by name. Returns the skill's full instructions which should be followed as guidance for the current task.",
-    parameters: z13.object({
-      name: z13.string().describe("Name of the skill to invoke")
+    parameters: z15.object({
+      name: z15.string().describe("Name of the skill to invoke")
     }),
     execute: async ({ name }) => {
       const skill = skillLoader.load(name);
@@ -3083,18 +3419,18 @@ Allowed tools: ${skill["allowed-tools"].join(", ")}`;
 }
 
 // src/capabilities/scheduler/schedule-task.ts
-import { tool as tool14 } from "ai";
-import { z as z14 } from "zod";
+import { tool as tool16 } from "ai";
+import { z as z16 } from "zod";
 import cron2 from "node-cron";
 function createScheduleTaskTool(scheduler, getContext) {
-  return tool14({
+  return tool16({
     description: 'Schedule a task. Use "cron" for recurring tasks (e.g. "0 9 * * *" for daily at 9am) or "delay_seconds" for one-shot delayed tasks (e.g. 15 for "remind me in 15 seconds"). Provide exactly one of cron or delay_seconds.',
-    parameters: z14.object({
-      cron: z14.string().optional().describe('Cron expression for recurring tasks (e.g. "0 9 * * *" for daily at 9am)'),
-      delay_seconds: z14.number().optional().describe('Delay in seconds for one-shot tasks (e.g. 15 for "remind me in 15 seconds")'),
-      description: z14.string().describe("Human-readable description of what this task does"),
-      prompt: z14.string().optional().describe("Prompt to send to the agent when the task fires"),
-      skill_name: z14.string().optional().describe("Name of a skill to invoke when the task fires")
+    parameters: z16.object({
+      cron: z16.string().optional().describe('Cron expression for recurring tasks (e.g. "0 9 * * *" for daily at 9am)'),
+      delay_seconds: z16.number().optional().describe('Delay in seconds for one-shot tasks (e.g. 15 for "remind me in 15 seconds")'),
+      description: z16.string().describe("Human-readable description of what this task does"),
+      prompt: z16.string().optional().describe("Prompt to send to the agent when the task fires"),
+      skill_name: z16.string().optional().describe("Name of a skill to invoke when the task fires")
     }),
     execute: async ({ cron: cronExpr, delay_seconds, description, prompt, skill_name }) => {
       if (!cronExpr && !delay_seconds) {
@@ -3147,12 +3483,12 @@ function createScheduleTaskTool(scheduler, getContext) {
 }
 
 // src/capabilities/scheduler/list-tasks.ts
-import { tool as tool15 } from "ai";
-import { z as z15 } from "zod";
+import { tool as tool17 } from "ai";
+import { z as z17 } from "zod";
 function createListTasksTool(scheduler) {
-  return tool15({
+  return tool17({
     description: "List all scheduled tasks with their cron expressions and descriptions.",
-    parameters: z15.object({}),
+    parameters: z17.object({}),
     execute: async () => {
       const manifests = scheduler.getManifests();
       if (manifests.length === 0) {
@@ -3167,13 +3503,13 @@ function createListTasksTool(scheduler) {
 }
 
 // src/capabilities/scheduler/cancel-task.ts
-import { tool as tool16 } from "ai";
-import { z as z16 } from "zod";
+import { tool as tool18 } from "ai";
+import { z as z18 } from "zod";
 function createCancelTaskTool(scheduler) {
-  return tool16({
+  return tool18({
     description: "Cancel and remove a scheduled task by its ID.",
-    parameters: z16.object({
-      id: z16.string().describe("ID of the scheduled task to cancel")
+    parameters: z18.object({
+      id: z18.string().describe("ID of the scheduled task to cancel")
     }),
     execute: async ({ id }) => {
       const manifests = scheduler.getManifests();
@@ -3189,12 +3525,12 @@ function createCancelTaskTool(scheduler) {
 }
 
 // src/capabilities/system/budget-status.ts
-import { tool as tool17 } from "ai";
-import { z as z17 } from "zod";
+import { tool as tool19 } from "ai";
+import { z as z19 } from "zod";
 function createBudgetStatusTool(tokenBudget) {
-  return tool17({
+  return tool19({
     description: "Check the current token budget status \u2014 how many tokens have been used today, how many remain, and what percentage is consumed.",
-    parameters: z17.object({}),
+    parameters: z19.object({}),
     execute: async () => {
       return tokenBudget.getStatusText();
     }
@@ -3202,19 +3538,19 @@ function createBudgetStatusTool(tokenBudget) {
 }
 
 // src/capabilities/git/git-status.ts
-import { tool as tool18 } from "ai";
-import { z as z18 } from "zod";
+import { tool as tool20 } from "ai";
+import { z as z20 } from "zod";
 import { execSync as execSync2 } from "child_process";
-function createGitStatusTool() {
-  return tool18({
+function createGitStatusTool(getCwd) {
+  return tool20({
     description: "Show the working tree status. Returns staged, unstaged, and untracked files.",
-    parameters: z18.object({
-      path: z18.string().optional().describe("Path to check (defaults to current directory)")
+    parameters: z20.object({
+      path: z20.string().optional().describe("Path to check (defaults to current directory)")
     }),
     execute: async ({ path: path3 }) => {
       try {
         const cmd = path3 ? `git -C "${path3}" status --porcelain` : "git status --porcelain";
-        const result = execSync2(cmd, { encoding: "utf-8", timeout: 1e4 });
+        const result = execSync2(cmd, { encoding: "utf-8", timeout: 1e4, cwd: getCwd() });
         if (!result.trim()) return "Working tree clean \u2014 no changes.";
         return result.trim();
       } catch (err) {
@@ -3225,22 +3561,22 @@ function createGitStatusTool() {
 }
 
 // src/capabilities/git/git-diff.ts
-import { tool as tool19 } from "ai";
-import { z as z19 } from "zod";
+import { tool as tool21 } from "ai";
+import { z as z21 } from "zod";
 import { execSync as execSync3 } from "child_process";
-function createGitDiffTool() {
-  return tool19({
+function createGitDiffTool(getCwd) {
+  return tool21({
     description: "Show changes between commits, commit and working tree, etc. Shows what has been modified.",
-    parameters: z19.object({
-      path: z19.string().optional().describe("File or directory to diff"),
-      staged: z19.boolean().optional().describe("Show staged changes (cached) instead of unstaged")
+    parameters: z21.object({
+      path: z21.string().optional().describe("File or directory to diff"),
+      staged: z21.boolean().optional().describe("Show staged changes (cached) instead of unstaged")
     }),
     execute: async ({ path: path3, staged }) => {
       try {
         let cmd = "git diff";
         if (staged) cmd += " --cached";
         if (path3) cmd += ` -- "${path3}"`;
-        const result = execSync3(cmd, { encoding: "utf-8", timeout: 15e3 });
+        const result = execSync3(cmd, { encoding: "utf-8", timeout: 15e3, cwd: getCwd() });
         if (!result.trim()) return "No differences found.";
         const truncated = result.length > 15e3 ? result.slice(0, 15e3) + "\n... (truncated)" : result;
         return truncated;
@@ -3252,22 +3588,22 @@ function createGitDiffTool() {
 }
 
 // src/capabilities/git/git-log.ts
-import { tool as tool20 } from "ai";
-import { z as z20 } from "zod";
+import { tool as tool22 } from "ai";
+import { z as z22 } from "zod";
 import { execSync as execSync4 } from "child_process";
-function createGitLogTool() {
-  return tool20({
+function createGitLogTool(getCwd) {
+  return tool22({
     description: "Show commit logs. Returns recent commit history with hash, author, date, and message.",
-    parameters: z20.object({
-      count: z20.number().optional().describe("Number of commits to show (default 10)"),
-      path: z20.string().optional().describe("File or directory to show log for")
+    parameters: z22.object({
+      count: z22.number().optional().describe("Number of commits to show (default 10)"),
+      path: z22.string().optional().describe("File or directory to show log for")
     }),
     execute: async ({ count, path: path3 }) => {
       try {
         const n = count ?? 10;
         let cmd = `git log --oneline --decorate -${n}`;
         if (path3) cmd += ` -- "${path3}"`;
-        const result = execSync4(cmd, { encoding: "utf-8", timeout: 1e4 });
+        const result = execSync4(cmd, { encoding: "utf-8", timeout: 1e4, cwd: getCwd() });
         if (!result.trim()) return "No commits found.";
         return result.trim();
       } catch (err) {
@@ -3278,19 +3614,19 @@ function createGitLogTool() {
 }
 
 // src/capabilities/git/git-add.ts
-import { tool as tool21 } from "ai";
-import { z as z21 } from "zod";
+import { tool as tool23 } from "ai";
+import { z as z23 } from "zod";
 import { execSync as execSync5 } from "child_process";
-function createGitAddTool() {
-  return tool21({
+function createGitAddTool(getCwd) {
+  return tool23({
     description: "Add file contents to the index (staging area). Prepares files for commit.",
-    parameters: z21.object({
-      paths: z21.array(z21.string()).describe("File paths to stage")
+    parameters: z23.object({
+      paths: z23.array(z23.string()).describe("File paths to stage")
     }),
     execute: async ({ paths }) => {
       try {
         const fileArgs = paths.map((p) => `"${p}"`).join(" ");
-        const result = execSync5(`git add ${fileArgs}`, { encoding: "utf-8", timeout: 1e4 });
+        const result = execSync5(`git add ${fileArgs}`, { encoding: "utf-8", timeout: 1e4, cwd: getCwd() });
         return `Staged ${paths.length} file(s): ${paths.join(", ")}`;
       } catch (err) {
         return `Error: ${err.stderr?.trim() || err.message}`;
@@ -3300,15 +3636,15 @@ function createGitAddTool() {
 }
 
 // src/capabilities/git/git-commit.ts
-import { tool as tool22 } from "ai";
-import { z as z22 } from "zod";
+import { tool as tool24 } from "ai";
+import { z as z24 } from "zod";
 import { execSync as execSync6 } from "child_process";
 var CO_AUTHOR = "Mercury <mercury@cosmicstack.org>";
-function createGitCommitTool() {
-  return tool22({
+function createGitCommitTool(getCwd) {
+  return tool24({
     description: "Record changes to the repository. Creates a new commit with staged changes. Automatically includes a Co-authored-by trailer for attribution.",
-    parameters: z22.object({
-      message: z22.string().describe("Commit message")
+    parameters: z24.object({
+      message: z24.string().describe("Commit message")
     }),
     execute: async ({ message }) => {
       try {
@@ -3316,7 +3652,7 @@ function createGitCommitTool() {
 
 Co-authored-by: ${CO_AUTHOR}`;
         const escapedMsg = fullMessage.replace(/"/g, '\\"');
-        const result = execSync6(`git commit -m "${escapedMsg}"`, { encoding: "utf-8", timeout: 1e4 });
+        const result = execSync6(`git commit -m "${escapedMsg}"`, { encoding: "utf-8", timeout: 1e4, cwd: getCwd() });
         return result.trim() || "Committed successfully.";
       } catch (err) {
         const stderr = err.stderr?.trim() || "";
@@ -3330,15 +3666,15 @@ Co-authored-by: ${CO_AUTHOR}`;
 }
 
 // src/capabilities/git/git-push.ts
-import { tool as tool23 } from "ai";
-import { z as z23 } from "zod";
+import { tool as tool25 } from "ai";
+import { z as z25 } from "zod";
 import { execSync as execSync7 } from "child_process";
-function createGitPushTool(permissions) {
-  return tool23({
+function createGitPushTool(permissions, getCwd) {
+  return tool25({
     description: "Push commits to a remote repository. This modifies a remote and requires approval.",
-    parameters: z23.object({
-      remote: z23.string().optional().describe("Remote name (default: origin)"),
-      branch: z23.string().optional().describe("Branch name (default: current branch)")
+    parameters: z25.object({
+      remote: z25.string().optional().describe("Remote name (default: origin)"),
+      branch: z25.string().optional().describe("Branch name (default: current branch)")
     }),
     execute: async ({ remote, branch }) => {
       const cmd = `git push ${remote || "origin"} ${branch || ""}`.trim();
@@ -3353,7 +3689,7 @@ Ask the user for permission. If they approve, try again. If they say "always", u
         return `Error: ${check.reason}`;
       }
       try {
-        const result = execSync7(cmd, { encoding: "utf-8", timeout: 3e4 });
+        const result = execSync7(cmd, { encoding: "utf-8", timeout: 3e4, cwd: getCwd() });
         return result.trim() || "Pushed successfully.";
       } catch (err) {
         return `Error: ${err.stderr?.trim() || err.message}`;
@@ -3363,8 +3699,8 @@ Ask the user for permission. If they approve, try again. If they say "always", u
 }
 
 // src/capabilities/github/create-pr.ts
-import { tool as tool24 } from "ai";
-import { z as z24 } from "zod";
+import { tool as tool26 } from "ai";
+import { z as z26 } from "zod";
 
 // src/utils/github.ts
 var GITHUB_API = "https://api.github.com";
@@ -3419,16 +3755,16 @@ async function githubRequest(path3, options = {}) {
 
 // src/capabilities/github/create-pr.ts
 function createCreatePrTool() {
-  return tool24({
+  return tool26({
     description: "Create a pull request on GitHub. Requires GITHUB_TOKEN to be configured.",
-    parameters: z24.object({
-      owner: z24.string().describe("Repository owner (username or org)"),
-      repo: z24.string().describe("Repository name"),
-      title: z24.string().describe("PR title"),
-      body: z24.string().describe("PR description (markdown supported)").default(""),
-      head: z24.string().describe("The branch containing the changes"),
-      base: z24.string().describe("The branch to merge into").default("main"),
-      draft: z24.boolean().describe("Create as draft PR").default(false)
+    parameters: z26.object({
+      owner: z26.string().describe("Repository owner (username or org)"),
+      repo: z26.string().describe("Repository name"),
+      title: z26.string().describe("PR title"),
+      body: z26.string().describe("PR description (markdown supported)").default(""),
+      head: z26.string().describe("The branch containing the changes"),
+      base: z26.string().describe("The branch to merge into").default("main"),
+      draft: z26.boolean().describe("Create as draft PR").default(false)
     }),
     execute: async ({ owner, repo, title, body, head, base, draft }) => {
       try {
@@ -3447,16 +3783,16 @@ ${draft ? "(draft)" : ""} ${result.state}`;
 }
 
 // src/capabilities/github/review-pr.ts
-import { tool as tool25 } from "ai";
-import { z as z25 } from "zod";
+import { tool as tool27 } from "ai";
+import { z as z27 } from "zod";
 function createReviewPrTool() {
-  return tool25({
+  return tool27({
     description: "Get details of a pull request including the diff. Reviews the PR and returns the title, body, changed files, and diff. Optionally post a review comment.",
-    parameters: z25.object({
-      owner: z25.string().describe("Repository owner (username or org)"),
-      repo: z25.string().describe("Repository name"),
-      number: z25.number().describe("PR number"),
-      comment: z25.string().describe("Review comment to post on the PR (optional)").optional()
+    parameters: z27.object({
+      owner: z27.string().describe("Repository owner (username or org)"),
+      repo: z27.string().describe("Repository name"),
+      number: z27.number().describe("PR number"),
+      comment: z27.string().describe("Review comment to post on the PR (optional)").optional()
     }),
     execute: async ({ owner, repo, number, comment }) => {
       try {
@@ -3522,17 +3858,17 @@ Failed to post review comment: ${err.message}`;
 }
 
 // src/capabilities/github/list-issues.ts
-import { tool as tool26 } from "ai";
-import { z as z26 } from "zod";
+import { tool as tool28 } from "ai";
+import { z as z28 } from "zod";
 function createListIssuesTool() {
-  return tool26({
+  return tool28({
     description: "List GitHub issues for a repository. Requires GITHUB_TOKEN.",
-    parameters: z26.object({
-      owner: z26.string().describe("Repository owner (username or org)"),
-      repo: z26.string().describe("Repository name"),
-      state: z26.enum(["open", "closed", "all"]).describe("Filter by issue state").default("open"),
-      labels: z26.string().describe("Comma-separated label names to filter by (optional)").optional(),
-      limit: z26.number().describe("Maximum number of issues to return").default(10)
+    parameters: z28.object({
+      owner: z28.string().describe("Repository owner (username or org)"),
+      repo: z28.string().describe("Repository name"),
+      state: z28.enum(["open", "closed", "all"]).describe("Filter by issue state").default("open"),
+      labels: z28.string().describe("Comma-separated label names to filter by (optional)").optional(),
+      limit: z28.number().describe("Maximum number of issues to return").default(10)
     }),
     execute: async ({ owner, repo, state, labels, limit }) => {
       try {
@@ -3560,17 +3896,17 @@ ${lines.join("\n")}`;
 }
 
 // src/capabilities/github/create-issue.ts
-import { tool as tool27 } from "ai";
-import { z as z27 } from "zod";
+import { tool as tool29 } from "ai";
+import { z as z29 } from "zod";
 function createCreateIssueTool() {
-  return tool27({
+  return tool29({
     description: "Create a new GitHub issue in a repository. Requires GITHUB_TOKEN.",
-    parameters: z27.object({
-      owner: z27.string().describe("Repository owner (username or org)"),
-      repo: z27.string().describe("Repository name"),
-      title: z27.string().describe("Issue title"),
-      body: z27.string().describe("Issue description (markdown supported)").default(""),
-      labels: z27.array(z27.string()).describe("Label names to apply").optional()
+    parameters: z29.object({
+      owner: z29.string().describe("Repository owner (username or org)"),
+      repo: z29.string().describe("Repository name"),
+      title: z29.string().describe("Issue title"),
+      body: z29.string().describe("Issue description (markdown supported)").default(""),
+      labels: z29.array(z29.string()).describe("Label names to apply").optional()
     }),
     execute: async ({ owner, repo, title, body, labels }) => {
       try {
@@ -3590,15 +3926,46 @@ function createCreateIssueTool() {
 }
 
 // src/capabilities/github/github-api.ts
-import { tool as tool28 } from "ai";
-import { z as z28 } from "zod";
+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 tool28({
-    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.",
-    parameters: z28.object({
-      path: z28.string().describe("Full API path (e.g., /repos/owner/repo/issues or /user)"),
-      method: z28.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method").default("GET"),
-      body: z28.string().describe("JSON body for write requests (as a JSON string)").optional()
+  return tool30({
+    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 /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()
     }),
     execute: async ({ path: path3, method, body }) => {
       try {
@@ -3610,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
@@ -3625,8 +3995,8 @@ function createGithubApiTool() {
 }
 
 // src/capabilities/web/fetch-url.ts
-import { tool as tool29 } from "ai";
-import { z as z29 } from "zod";
+import { tool as tool31 } from "ai";
+import { z as z31 } from "zod";
 var MAX_CONTENT_LENGTH = 15e3;
 function stripHtml(html) {
   let text = html;
@@ -3659,11 +4029,11 @@ function stripHtml(html) {
   return text;
 }
 function createFetchUrlTool() {
-  return tool29({
+  return tool31({
     description: "Fetch a URL and return its content as text. Strips HTML to readable markdown-like format. Useful for reading documentation, APIs, or web pages.",
-    parameters: z29.object({
-      url: z29.string().describe("The URL to fetch"),
-      format: z29.enum(["text", "markdown"]).optional().describe("Output format (default: markdown)")
+    parameters: z31.object({
+      url: z31.string().describe("The URL to fetch"),
+      format: z31.enum(["text", "markdown"]).optional().describe("Output format (default: markdown)")
     }),
     execute: async ({ url, format }) => {
       const outputFormat = format ?? "markdown";
@@ -3715,9 +4085,11 @@ var CapabilityRegistry = class {
   scheduler;
   tokenBudget;
   sendFileHandler;
+  sendMessageHandler;
   currentChannelId = "cli";
   currentChannelType = "cli";
   chatCommandContext;
+  currentCwd = process.cwd();
   constructor(skillLoader, scheduler, tokenBudget) {
     this.permissions = new PermissionManager();
     this.skillLoader = skillLoader;
@@ -3737,26 +4109,40 @@ var CapabilityRegistry = class {
   getChannelContext() {
     return { channelId: this.currentChannelId, channelType: this.currentChannelType };
   }
+  getCwd() {
+    return this.currentCwd;
+  }
+  setCwd(dir) {
+    this.currentCwd = dir;
+  }
   setSendFileHandler(handler) {
     this.sendFileHandler = handler;
   }
+  setSendMessageHandler(handler) {
+    this.sendMessageHandler = handler;
+  }
   registerAll() {
     const manifest = this.permissions.getManifest();
     if (manifest.capabilities.filesystem.enabled) {
-      this.tools.read_file = createReadFileTool(this.permissions);
-      this.tools.write_file = createWriteFileTool(this.permissions);
-      this.tools.create_file = createCreateFileTool(this.permissions);
-      this.tools.list_dir = createListDirTool(this.permissions);
-      this.tools.delete_file = createDeleteFileTool(this.permissions);
-      this.tools.edit_file = createEditFileTool(this.permissions);
+      this.tools.read_file = createReadFileTool(this.permissions, () => this.getCwd());
+      this.tools.write_file = createWriteFileTool(this.permissions, () => this.getCwd());
+      this.tools.create_file = createCreateFileTool(this.permissions, () => this.getCwd());
+      this.tools.list_dir = createListDirTool(this.permissions, () => this.getCwd());
+      this.tools.delete_file = createDeleteFileTool(this.permissions, () => this.getCwd());
+      this.tools.edit_file = createEditFileTool(this.permissions, () => this.getCwd());
       if (this.sendFileHandler) {
-        this.tools.send_file = createSendFileTool(this.permissions, this.sendFileHandler);
+        this.tools.send_file = createSendFileTool(this.permissions, () => this.getCwd(), this.sendFileHandler);
       }
-      this.tools.approve_scope = createApproveScopeTool(this.permissions);
+      this.tools.approve_scope = createApproveScopeTool(this.permissions, () => this.getCwd());
       logger.info("Filesystem tools registered");
     }
+    if (this.sendMessageHandler) {
+      this.tools.send_message = createSendMessageTool(this.sendMessageHandler);
+      logger.info("Messaging tool registered");
+    }
     if (manifest.capabilities.shell.enabled) {
-      this.tools.run_command = createRunCommandTool(this.permissions);
+      this.tools.run_command = createRunCommandTool(this.permissions, () => this.getCwd(), (dir) => this.setCwd(dir));
+      this.tools.cd = createCdTool(() => this.getCwd(), (dir) => this.setCwd(dir));
       this.tools.approve_command = createApproveCommandTool(this.permissions);
       logger.info("Shell tools registered");
     }
@@ -3777,12 +4163,12 @@ var CapabilityRegistry = class {
       logger.info("Budget tool registered");
     }
     if (manifest.capabilities.git?.enabled) {
-      this.tools.git_status = createGitStatusTool();
-      this.tools.git_diff = createGitDiffTool();
-      this.tools.git_log = createGitLogTool();
-      this.tools.git_add = createGitAddTool();
-      this.tools.git_commit = createGitCommitTool();
-      this.tools.git_push = createGitPushTool(this.permissions);
+      this.tools.git_status = createGitStatusTool(() => this.getCwd());
+      this.tools.git_diff = createGitDiffTool(() => this.getCwd());
+      this.tools.git_log = createGitLogTool(() => this.getCwd());
+      this.tools.git_add = createGitAddTool(() => this.getCwd());
+      this.tools.git_commit = createGitCommitTool(() => this.getCwd());
+      this.tools.git_push = createGitPushTool(this.permissions, () => this.getCwd());
       logger.info("Git tools registered");
     }
     if (isGitHubConfigured()) {
@@ -3808,7 +4194,7 @@ var CapabilityRegistry = class {
 };
 
 // src/skills/loader.ts
-import { existsSync as existsSync13, readFileSync as readFileSync10, readdirSync as readdirSync3, mkdirSync as mkdirSync8, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync10, readdirSync as readdirSync3, mkdirSync as mkdirSync8, writeFileSync as writeFileSync10 } from "fs";
 import { join as join8 } from "path";
 import { parse as parseYaml5 } from "yaml";
 var SKILL_FILE = "SKILL.md";
@@ -3838,7 +4224,7 @@ var SkillLoader = class {
   discover() {
     this.discovered.clear();
     this.loaded.clear();
-    if (!existsSync13(this.skillsDir)) {
+    if (!existsSync15(this.skillsDir)) {
       mkdirSync8(this.skillsDir, { recursive: true });
       this.seedTemplate();
       return [];
@@ -3847,7 +4233,7 @@ var SkillLoader = class {
     for (const entry of entries) {
       if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
       const skillPath = join8(this.skillsDir, entry.name, SKILL_FILE);
-      if (!existsSync13(skillPath)) continue;
+      if (!existsSync15(skillPath)) continue;
       try {
         const raw = readFileSync10(skillPath, "utf-8");
         const parsed = parseSkillMd(raw);
@@ -3869,7 +4255,7 @@ var SkillLoader = class {
     for (const entry of readdirSync3(this.skillsDir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
       const skillPath = join8(this.skillsDir, entry.name, SKILL_FILE);
-      if (!existsSync13(skillPath)) continue;
+      if (!existsSync15(skillPath)) continue;
       try {
         const raw = readFileSync10(skillPath, "utf-8");
         const parsed = parseSkillMd(raw);
@@ -3878,8 +4264,8 @@ var SkillLoader = class {
         const skill = {
           ...parsed.meta,
           instructions: parsed.instructions,
-          scriptsDir: existsSync13(join8(skillDir, "scripts")) ? join8(skillDir, "scripts") : void 0,
-          referencesDir: existsSync13(join8(skillDir, "references")) ? join8(skillDir, "references") : void 0
+          scriptsDir: existsSync15(join8(skillDir, "scripts")) ? join8(skillDir, "scripts") : void 0,
+          referencesDir: existsSync15(join8(skillDir, "references")) ? join8(skillDir, "references") : void 0
         };
         this.loaded.set(name, skill);
         return skill;
@@ -3900,7 +4286,7 @@ var SkillLoader = class {
   }
   saveSkill(name, content) {
     const skillDir = join8(this.skillsDir, name);
-    if (!existsSync13(skillDir)) {
+    if (!existsSync15(skillDir)) {
       mkdirSync8(skillDir, { recursive: true });
     }
     writeFileSync10(join8(skillDir, SKILL_FILE), content, "utf-8");
@@ -3963,6 +4349,7 @@ function getManual() {
     ["edit_file", "Replace specific text in a file", "path, old_string, new_string"],
     ["list_dir", "List directory contents", "path"],
     ["delete_file", "Delete a file", "path"],
+    ["send_message", "Send a message to the paired Telegram owner", "content"],
     ["run_command", "Execute a shell command", "command"],
     ["approve_command", "Permanently approve a command type", 'command (e.g. "curl")'],
     ["fetch_url", "Fetch a URL and return content", "url, format? (text/markdown)"],
@@ -3999,6 +4386,7 @@ function getManual() {
     ["mercury doctor", "Reconfigure settings (Enter keeps current)"],
     ["mercury setup", "Re-run the setup wizard"],
     ["mercury status", "Show config and daemon status"],
+    ["mercury telegram unpair", "Clear the paired Telegram owner"],
     ["mercury help", "Show this manual"],
     ["mercury service install", "Install as system service (auto-start)"],
     ["mercury service uninstall", "Uninstall system service"],
@@ -4013,13 +4401,16 @@ function getManual() {
   sections.push(chalk3.dim("  Type these during a conversation (no API calls)."));
   sections.push("");
   const chat = [
+    ["/start", "Pair this Telegram account to Mercury"],
+    ["/pair", "Pair this Telegram account to Mercury"],
     ["/help", "Show this manual"],
     ["/status", "Show config and budget info"],
     ["/tools", "List currently loaded tools"],
     ["/skills", "List installed skills"],
     ["/stream", "Toggle text streaming on/off (Telegram)"],
     ["/stream on", "Enable streaming (live text updates)"],
-    ["/stream off", "Disable streaming (single message)"]
+    ["/stream off", "Disable streaming (single message)"],
+    ["/unpair", "Remove Telegram pairing for this Mercury instance"]
   ];
   for (const [cmd, desc] of chat) {
     sections.push(`  ${chalk3.white(cmd.padEnd(16))} ${desc}`);
@@ -4082,7 +4473,7 @@ function getManual() {
 
 // src/cli/daemon.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync11, writeFileSync as writeFileSync11, unlinkSync as unlinkSync3, mkdirSync as mkdirSync9, openSync } from "fs";
+import { existsSync as existsSync16, readFileSync as readFileSync11, writeFileSync as writeFileSync11, unlinkSync as unlinkSync3, mkdirSync as mkdirSync9, openSync } from "fs";
 import { join as join9 } from "path";
 import process2 from "process";
 import chalk4 from "chalk";
@@ -4096,7 +4487,7 @@ function logPath() {
 }
 function readPid() {
   const path3 = pidPath();
-  if (!existsSync14(path3)) return null;
+  if (!existsSync16(path3)) return null;
   try {
     const pid = parseInt(readFileSync11(path3, "utf-8").trim(), 10);
     if (isNaN(pid)) return null;
@@ -4133,7 +4524,7 @@ function startBackground() {
     }
   }
   const home = getMercuryHome();
-  if (!existsSync14(home)) {
+  if (!existsSync16(home)) {
     mkdirSync9(home, { recursive: true });
   }
   const logFile = logPath();
@@ -4214,7 +4605,7 @@ function restartDaemon() {
 }
 function showLogs() {
   const logFile = logPath();
-  if (!existsSync14(logFile)) {
+  if (!existsSync16(logFile)) {
     console.log(chalk4.dim("  No daemon log file found."));
     console.log("");
     return;
@@ -4236,7 +4627,7 @@ function tryAutoDaemonize() {
       }
     }
     const home = getMercuryHome();
-    if (!existsSync14(home)) {
+    if (!existsSync16(home)) {
       mkdirSync9(home, { recursive: true });
     }
     const logFile = logPath();
@@ -4260,7 +4651,7 @@ function tryAutoDaemonize() {
 }
 
 // src/cli/service.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync10, writeFileSync as writeFileSync12, unlinkSync as unlinkSync4 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync10, writeFileSync as writeFileSync12, unlinkSync as unlinkSync4 } from "fs";
 import { join as join10 } from "path";
 import { homedir as homedir3 } from "os";
 import chalk5 from "chalk";
@@ -4270,9 +4661,9 @@ var WIN_TASK_NAME = "MercuryAgent";
 function isServiceInstalled() {
   const platform = process.platform;
   if (platform === "darwin") {
-    return existsSync15(join10(homedir3(), "Library", "LaunchAgents", "com.cosmicstack.mercury.plist"));
+    return existsSync17(join10(homedir3(), "Library", "LaunchAgents", "com.cosmicstack.mercury.plist"));
   } else if (platform === "linux") {
-    return existsSync15(join10(homedir3(), ".config", "systemd", "user", "mercury.service"));
+    return existsSync17(join10(homedir3(), ".config", "systemd", "user", "mercury.service"));
   } else if (platform === "win32") {
     try {
       execSync8(`schtasks /query /tn "${WIN_TASK_NAME}"`, { stdio: "pipe", shell: "cmd.exe" });
@@ -4328,7 +4719,7 @@ function showServiceStatus() {
 function installMac() {
   const plistDir = join10(homedir3(), "Library", "LaunchAgents");
   const plistPath = join10(plistDir, "com.cosmicstack.mercury.plist");
-  if (!existsSync15(plistDir)) {
+  if (!existsSync17(plistDir)) {
     mkdirSync10(plistDir, { recursive: true });
   }
   const nodeBin = getNodeBinPath();
@@ -4389,7 +4780,7 @@ function installMac() {
 }
 function uninstallMac() {
   const plistPath = join10(homedir3(), "Library", "LaunchAgents", "com.cosmicstack.mercury.plist");
-  if (!existsSync15(plistPath)) {
+  if (!existsSync17(plistPath)) {
     console.log(chalk5.yellow("  Mercury service is not installed."));
     console.log("");
     process.exit(0);
@@ -4410,7 +4801,7 @@ function uninstallMac() {
 }
 function showMacStatus() {
   const plistPath = join10(homedir3(), "Library", "LaunchAgents", "com.cosmicstack.mercury.plist");
-  if (!existsSync15(plistPath)) {
+  if (!existsSync17(plistPath)) {
     console.log(chalk5.yellow("  Mercury service is not installed."));
     console.log(chalk5.dim("  Run `mercury service install` to set it up."));
     console.log("");
@@ -4428,7 +4819,7 @@ function showMacStatus() {
 }
 function installLinux() {
   const systemdDir = join10(homedir3(), ".config", "systemd", "user");
-  if (!existsSync15(systemdDir)) {
+  if (!existsSync17(systemdDir)) {
     mkdirSync10(systemdDir, { recursive: true });
   }
   const servicePath = join10(systemdDir, "mercury.service");
@@ -4480,7 +4871,7 @@ WantedBy=default.target`;
 }
 function uninstallLinux() {
   const servicePath = join10(homedir3(), ".config", "systemd", "user", "mercury.service");
-  if (!existsSync15(servicePath)) {
+  if (!existsSync17(servicePath)) {
     console.log(chalk5.yellow("  Mercury service is not installed."));
     console.log("");
     process.exit(0);
@@ -4506,7 +4897,7 @@ function uninstallLinux() {
 }
 function showLinuxStatus() {
   const servicePath = join10(homedir3(), ".config", "systemd", "user", "mercury.service");
-  if (!existsSync15(servicePath)) {
+  if (!existsSync17(servicePath)) {
     console.log(chalk5.yellow("  Mercury service is not installed."));
     console.log(chalk5.dim("  Run `mercury service install` to set it up."));
     console.log("");
@@ -4605,7 +4996,7 @@ async function runWithWatchdog(agentFn) {
   await attempt();
 }
 function sleep(ms) {
-  return new Promise((resolve11) => setTimeout(resolve11, ms));
+  return new Promise((resolve13) => setTimeout(resolve13, ms));
 }
 
 // src/index.ts
@@ -4644,10 +5035,10 @@ function splashScreen() {
 }
 async function ask(prompt) {
   const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve11) => {
+  return new Promise((resolve13) => {
     rl.question(prompt, (answer) => {
       rl.close();
-      resolve11(answer.trim());
+      resolve13(answer.trim());
     });
   });
 }
@@ -4656,10 +5047,149 @@ function maskKey(key) {
   if (key.length <= 8) return "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
   return key.slice(0, 4) + "\u2022\u2022\u2022\u2022" + key.slice(-4);
 }
+var PROVIDER_OPTIONS = [
+  { key: "deepseek", label: "DeepSeek" },
+  { key: "openai", label: "OpenAI" },
+  { key: "anthropic", label: "Anthropic" },
+  { key: "grok", label: "Grok (xAI)" },
+  { key: "ollamaCloud", label: "Ollama Cloud" },
+  { key: "ollamaLocal", label: "Ollama Local" }
+];
+function getConfiguredProviderNames(config) {
+  return PROVIDER_OPTIONS.map((option) => option.key).filter((key) => isProviderConfigured(config.providers[key]));
+}
+function getProviderLabel(name) {
+  return PROVIDER_OPTIONS.find((option) => option.key === name)?.label || name;
+}
+function parseProviderSelection(input) {
+  const values = input.split(/[\s,]+/).map((value) => value.trim()).filter(Boolean);
+  if (values.length === 0) return [];
+  const selected = [];
+  for (const value of values) {
+    const index = parseInt(value, 10);
+    if (isNaN(index) || index < 1 || index > PROVIDER_OPTIONS.length) {
+      return null;
+    }
+    const provider = PROVIDER_OPTIONS[index - 1].key;
+    if (!selected.includes(provider)) {
+      selected.push(provider);
+    }
+  }
+  return selected;
+}
+async function chooseProvidersToConfigure(config, isReconfig) {
+  const configured = getConfiguredProviderNames(config);
+  while (true) {
+    for (let i = 0; i < PROVIDER_OPTIONS.length; i++) {
+      const option = PROVIDER_OPTIONS[i];
+      const status = configured.includes(option.key) ? " (configured)" : "";
+      console.log(chalk6.white(`    ${i + 1}. ${option.label}${status}`));
+    }
+    console.log("");
+    const prompt = isReconfig ? chalk6.white("  Choose providers to configure [comma-separated, Enter keeps current]: ") : chalk6.white("  Choose providers to configure [comma-separated, Enter for DeepSeek]: ");
+    const input = await ask(prompt);
+    const parsed = parseProviderSelection(input);
+    if (parsed === null) {
+      console.log(chalk6.red("  Please choose valid provider numbers, like `1` or `1,3,5`."));
+      console.log("");
+      continue;
+    }
+    if (parsed.length > 0) return parsed;
+    if (!isReconfig) return ["deepseek"];
+    return configured.length > 0 ? configured : ["deepseek"];
+  }
+}
+async function chooseDefaultProvider(config) {
+  const configured = getConfiguredProviderNames(config);
+  if (configured.length === 0) {
+    return;
+  }
+  if (configured.length === 1) {
+    config.providers.default = configured[0];
+    console.log(chalk6.dim(`  Default provider set to ${getProviderLabel(configured[0])}`));
+    return;
+  }
+  const suggested = configured.includes("deepseek") ? "deepseek" : configured[0];
+  console.log("");
+  console.log(chalk6.bold.white("  Default Provider"));
+  console.log(chalk6.dim("  Select the LLM provider Mercury should use first."));
+  console.log("");
+  for (let i = 0; i < configured.length; i++) {
+    const provider = configured[i];
+    const recommended = provider === suggested ? " (recommended)" : "";
+    const current = provider === config.providers.default ? " (current)" : "";
+    console.log(chalk6.white(`    ${i + 1}. ${getProviderLabel(provider)}${recommended}${current}`));
+  }
+  console.log("");
+  while (true) {
+    const choice = await ask(chalk6.white(`  Choose [1-${configured.length}] [Enter for ${getProviderLabel(suggested)}]: `));
+    if (!choice) {
+      config.providers.default = suggested;
+      return;
+    }
+    const num = parseInt(choice, 10);
+    if (num >= 1 && num <= configured.length) {
+      config.providers.default = configured[num - 1];
+      return;
+    }
+    console.log(chalk6.red("  Please choose a valid number from the list above."));
+  }
+}
+function looksLikeToken(value, minLength = 20) {
+  return value.length >= minLength && !/\s/.test(value) && /[A-Za-z]/.test(value) && /\d/.test(value);
+}
+function validateApiKey(provider, value) {
+  if (provider === "openai") {
+    return /^sk-(proj-|svcacct-)?[A-Za-z0-9_-]{16,}$/i.test(value) ? null : "OpenAI keys must start with `sk-`, `sk-proj-`, or `sk-svcacct-`.";
+  }
+  if (provider === "anthropic") {
+    return /^sk-ant-[A-Za-z0-9_-]{16,}$/i.test(value) ? null : "Anthropic keys must start with `sk-ant-`.";
+  }
+  if (provider === "deepseek") {
+    return /^sk-[A-Za-z0-9_-]{16,}$/i.test(value) ? null : "DeepSeek keys must start with `sk-`.";
+  }
+  if (provider === "grok") {
+    return looksLikeToken(value) ? null : "Grok keys must look like a real API token: long, no spaces, and not plain text.";
+  }
+  if (provider === "ollamaCloud") {
+    return looksLikeToken(value) ? null : "Ollama Cloud keys must look like a real API token: long, no spaces, and not plain text.";
+  }
+  return null;
+}
+function validateBaseUrl(value) {
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return "Base URL must start with http:// or https://.";
+    }
+    return null;
+  } catch {
+    return "Please enter a valid URL.";
+  }
+}
+function validateModelName(value) {
+  if (!value.trim()) return "Model name is required.";
+  if (/\s/.test(value)) return "Model name cannot contain spaces.";
+  return null;
+}
+async function promptValidatedValue(prompt, validator, existingValue, options) {
+  while (true) {
+    const value = await ask(prompt);
+    if (!value) {
+      if (existingValue) return existingValue;
+      if (options?.allowSkip) return void 0;
+      console.log(chalk6.red("  A value is required here."));
+      continue;
+    }
+    const error = validator(value);
+    if (!error) return value;
+    console.log(chalk6.red(`  ${error}`));
+  }
+}
 function appendToEnv(key, value) {
   const envPath = join11(getMercuryHome(), ".env");
   let envContent = "";
-  if (existsSync16(envPath)) {
+  if (existsSync18(envPath)) {
     envContent = readFileSync12(envPath, "utf-8");
   }
   const lines = envContent.split("\n").filter((l) => !l.startsWith(`${key}=`) && l.trim() !== "");
@@ -4709,49 +5239,108 @@ async function configure(existingConfig) {
   console.log("");
   console.log(chalk6.bold.white("  LLM Providers"));
   if (isReconfig) {
-    console.log(chalk6.dim("  Current keys shown masked. Enter new value to change, Enter to keep."));
+    console.log(chalk6.dim("  Choose which providers to configure now. Existing values are shown where available."));
   } else {
-    console.log(chalk6.dim("  At least one API key is required."));
+    console.log(chalk6.dim("  Choose one or more providers. Press Enter to configure DeepSeek by default."));
   }
   console.log("");
-  const dsMask = isReconfig && config.providers.deepseek.apiKey ? ` [${maskKey(config.providers.deepseek.apiKey)}]` : "";
-  const deepseekKey = await ask(chalk6.white(`  DeepSeek API key${dsMask}: `));
-  if (deepseekKey) {
-    config.providers.deepseek.apiKey = deepseekKey;
-  }
-  const oaiMask = isReconfig && config.providers.openai.apiKey ? ` [${maskKey(config.providers.openai.apiKey)}]` : " (Enter to skip)";
-  const openaiKey = await ask(chalk6.white(`  OpenAI API key${oaiMask}: `));
-  if (openaiKey) config.providers.openai.apiKey = openaiKey;
-  const antMask = isReconfig && config.providers.anthropic.apiKey ? ` [${maskKey(config.providers.anthropic.apiKey)}]` : " (Enter to skip)";
-  const anthropicKey = await ask(chalk6.white(`  Anthropic API key${antMask}: `));
-  if (anthropicKey) config.providers.anthropic.apiKey = anthropicKey;
-  const hasKey = config.providers.deepseek.apiKey || config.providers.openai.apiKey || config.providers.anthropic.apiKey;
-  if (!hasKey) {
-    console.log(chalk6.red("\n  At least one LLM API key is required."));
-    process.exit(1);
-  }
-  const availableProviders = [];
-  if (config.providers.deepseek.apiKey) availableProviders.push("deepseek");
-  if (config.providers.openai.apiKey) availableProviders.push("openai");
-  if (config.providers.anthropic.apiKey) availableProviders.push("anthropic");
-  if (isReconfig && availableProviders.length > 1) {
+  while (true) {
+    const selectedProviders = await chooseProvidersToConfigure(config, isReconfig);
     console.log("");
-    console.log(chalk6.bold.white("  Default Provider"));
-    console.log(chalk6.dim("  Select the default LLM provider (the one used first)."));
-    console.log("");
-    for (let i = 0; i < availableProviders.length; i++) {
-      const marker = availableProviders[i] === config.providers.default ? " (current)" : "";
-      console.log(chalk6.white(`    ${i + 1}. ${availableProviders[i]}${marker}`));
+    for (const provider of selectedProviders) {
+      if (provider === "deepseek") {
+        const mask = isReconfig && config.providers.deepseek.apiKey ? ` [${maskKey(config.providers.deepseek.apiKey)}]` : "";
+        const key = await promptValidatedValue(
+          chalk6.white(`  DeepSeek API key${mask}${isReconfig ? "" : " (Enter to skip)"}: `),
+          (value) => validateApiKey("deepseek", value),
+          isReconfig ? config.providers.deepseek.apiKey : void 0,
+          { allowSkip: true }
+        );
+        if (key) {
+          config.providers.deepseek.apiKey = key;
+          config.providers.deepseek.enabled = true;
+        }
+        continue;
+      }
+      if (provider === "openai") {
+        const mask = isReconfig && config.providers.openai.apiKey ? ` [${maskKey(config.providers.openai.apiKey)}]` : "";
+        const key = await promptValidatedValue(
+          chalk6.white(`  OpenAI API key${mask}${isReconfig ? "" : " (Enter to skip)"}: `),
+          (value) => validateApiKey("openai", value),
+          isReconfig ? config.providers.openai.apiKey : void 0,
+          { allowSkip: true }
+        );
+        if (key) {
+          config.providers.openai.apiKey = key;
+          config.providers.openai.enabled = true;
+        }
+        continue;
+      }
+      if (provider === "anthropic") {
+        const mask = isReconfig && config.providers.anthropic.apiKey ? ` [${maskKey(config.providers.anthropic.apiKey)}]` : "";
+        const key = await promptValidatedValue(
+          chalk6.white(`  Anthropic API key${mask}${isReconfig ? "" : " (Enter to skip)"}: `),
+          (value) => validateApiKey("anthropic", value),
+          isReconfig ? config.providers.anthropic.apiKey : void 0,
+          { allowSkip: true }
+        );
+        if (key) {
+          config.providers.anthropic.apiKey = key;
+          config.providers.anthropic.enabled = true;
+        }
+        continue;
+      }
+      if (provider === "grok") {
+        const mask = isReconfig && config.providers.grok.apiKey ? ` [${maskKey(config.providers.grok.apiKey)}]` : "";
+        const key = await promptValidatedValue(
+          chalk6.white(`  Grok API key${mask}${isReconfig ? "" : " (Enter to skip)"}: `),
+          (value) => validateApiKey("grok", value),
+          isReconfig ? config.providers.grok.apiKey : void 0,
+          { allowSkip: true }
+        );
+        if (key) {
+          config.providers.grok.apiKey = key;
+          config.providers.grok.enabled = true;
+        }
+        continue;
+      }
+      if (provider === "ollamaCloud") {
+        const mask = isReconfig && config.providers.ollamaCloud.apiKey ? ` [${maskKey(config.providers.ollamaCloud.apiKey)}]` : "";
+        const key = await promptValidatedValue(
+          chalk6.white(`  Ollama Cloud API key${mask}${isReconfig ? "" : " (Enter to skip)"}: `),
+          (value) => validateApiKey("ollamaCloud", value),
+          isReconfig ? config.providers.ollamaCloud.apiKey : void 0,
+          { allowSkip: true }
+        );
+        if (key) {
+          config.providers.ollamaCloud.apiKey = key;
+          config.providers.ollamaCloud.enabled = true;
+        }
+        continue;
+      }
+      if (provider === "ollamaLocal") {
+        config.providers.ollamaLocal.baseUrl = await promptValidatedValue(
+          chalk6.white(`  Ollama Local base URL [${config.providers.ollamaLocal.baseUrl}]: `),
+          validateBaseUrl,
+          config.providers.ollamaLocal.baseUrl
+        );
+        config.providers.ollamaLocal.model = await promptValidatedValue(
+          chalk6.white(`  Ollama Local model [${config.providers.ollamaLocal.model}]: `),
+          validateModelName,
+          config.providers.ollamaLocal.model
+        );
+        config.providers.ollamaLocal.enabled = true;
+      }
     }
-    console.log("");
-    const choice = await ask(chalk6.white(`  Choose [1-${availableProviders.length}] [Enter to keep ${config.providers.default}]: `));
-    const num = parseInt(choice, 10);
-    if (num >= 1 && num <= availableProviders.length) {
-      config.providers.default = availableProviders[num - 1];
+    const configuredProviders = getConfiguredProviderNames(config);
+    if (configuredProviders.length === 0) {
+      console.log(chalk6.red("  You need to configure at least one LLM provider to continue."));
+      console.log(chalk6.dim("  Let\u2019s try that step again."));
+      console.log("");
+      continue;
     }
-  } else if (!isReconfig) {
-    config.providers.default = availableProviders[0];
-    console.log(chalk6.dim(`  Default provider set to ${config.providers.default}`));
+    await chooseDefaultProvider(config);
+    break;
   }
   hr();
   console.log("");
@@ -4760,6 +5349,11 @@ async function configure(existingConfig) {
     console.log(chalk6.dim('  Leave empty to keep current value. Enter "none" to disable.'));
   } else {
     console.log(chalk6.dim("  Leave empty to skip. You can add it later."));
+    console.log(chalk6.dim("  To create a bot token:"));
+    console.log(chalk6.dim("    1. Open Telegram and message @BotFather"));
+    console.log(chalk6.dim("    2. Run /newbot and follow the prompts"));
+    console.log(chalk6.dim("    3. Copy the bot token BotFather gives you"));
+    console.log(chalk6.dim("    4. Paste that token here"));
   }
   console.log("");
   const tgMask = isReconfig && config.channels.telegram.botToken ? ` [${maskKey(config.channels.telegram.botToken)}]` : "";
@@ -4767,7 +5361,11 @@ async function configure(existingConfig) {
   if (isReconfig && telegramToken.toLowerCase() === "none") {
     config.channels.telegram.enabled = false;
     config.channels.telegram.botToken = "";
+    clearTelegramPairing(config);
   } else if (telegramToken) {
+    if (telegramToken !== config.channels.telegram.botToken) {
+      clearTelegramPairing(config);
+    }
     config.channels.telegram.botToken = telegramToken;
     config.channels.telegram.enabled = true;
   }
@@ -4878,10 +5476,10 @@ async function runAgent(isDaemon = false) {
   const providers = new ProviderRegistry(config);
   if (!providers.hasProviders()) {
     if (isDaemon) {
-      logger.error("No LLM providers available. Run `mercury doctor` to configure API keys.");
+      logger.error("No LLM providers available. Run `mercury doctor` to configure providers.");
       return;
     }
-    console.log(chalk6.red("  No LLM providers available. Run `mercury doctor` to configure API keys."));
+    console.log(chalk6.red("  No LLM providers available. Run `mercury doctor` to configure providers."));
     process.exit(1);
   }
   const available = providers.listAvailable();
@@ -4915,6 +5513,18 @@ async function runAgent(isDaemon = false) {
       await msg.sendFile(filePath);
     }
   });
+  capabilities.setSendMessageHandler(async (content) => {
+    const telegram = channels.get("telegram");
+    const pairedChatId = config.channels.telegram.pairedChatId;
+    const pairedUserId = config.channels.telegram.pairedUserId;
+    if (!config.channels.telegram.enabled || !telegram) {
+      throw new Error("Telegram is not configured. Add a bot token in setup or run `mercury doctor`.");
+    }
+    if (pairedChatId == null || pairedUserId == null) {
+      throw new Error("Telegram is not paired. Complete the pairing flow with /start or /pair from the Telegram owner account.");
+    }
+    await telegram.send(content, `telegram:${pairedChatId}`);
+  });
   if (process.env.GITHUB_TOKEN) {
     setGitHubToken(process.env.GITHUB_TOKEN);
   }
@@ -5055,8 +5665,9 @@ program.command("status").description("Show current configuration and daemon sta
   if (config.identity.creator) {
     console.log(`  Creator:  ${chalk6.white(config.identity.creator)}`);
   }
-  console.log(`  Provider: ${chalk6.white(config.providers.default)}`);
+  console.log(`  Provider: ${chalk6.white(getProviderLabel(config.providers.default))}`);
   console.log(`  Telegram: ${config.channels.telegram.enabled ? chalk6.green("enabled") : chalk6.dim("disabled")}`);
+  console.log(`  Telegram Pairing: ${config.channels.telegram.pairedUserId != null ? chalk6.green(`paired to user ${config.channels.telegram.pairedUserId}${config.channels.telegram.pairedUsername ? ` (@${config.channels.telegram.pairedUsername})` : ""}`) : chalk6.dim("unpaired")}`);
   console.log(`  Skills:   ${skills.length > 0 ? chalk6.green(skills.map((s) => s.name).join(", ")) : chalk6.dim("none")}`);
   console.log(`  Budget:   ${chalk6.white(config.tokens.dailyBudget.toLocaleString())} tokens/day`);
   console.log(`  Setup:    ${isSetupComplete() ? chalk6.green("complete") : chalk6.red("not done")}`);
@@ -5067,6 +5678,28 @@ program.command("status").description("Show current configuration and daemon sta
 program.command("help").description("Show capabilities and commands manual").action(() => {
   console.log(getManual());
 });
+var telegramCmd = program.command("telegram").description("Manage Telegram pairing and access");
+telegramCmd.command("unpair").description("Clear the paired Telegram owner for this Mercury instance").action(() => {
+  const config = loadConfig();
+  const daemon = getDaemonStatus();
+  if (config.channels.telegram.pairedUserId == null) {
+    console.log("");
+    console.log(chalk6.dim("  Telegram is already unpaired."));
+    console.log("");
+    return;
+  }
+  clearTelegramPairing(config);
+  saveConfig(config);
+  console.log("");
+  console.log(chalk6.green("  \u2713 Telegram pairing cleared."));
+  if (daemon.running) {
+    console.log(chalk6.dim("  Restarting the background daemon to apply the change immediately..."));
+    restartDaemon();
+  } else {
+    console.log(chalk6.dim("  The next private Telegram user to send /start will pair this Mercury instance."));
+  }
+  console.log("");
+});
 var serviceCmd = program.command("service").description("Manage Mercury as a system service (auto-start, crash recovery)");
 serviceCmd.command("install").description("Install Mercury as a system service (auto-start on boot)").action(() => {
   installService();