@cosmicstack/mercury-agent 0.2.7 → 0.3.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync13, existsSync as existsSync16 } from "fs";
 import { fileURLToPath } from "url";
 import { dirname as dirname3, join as join11 } from "path";
 import { Command } from "commander";
@@ -14,8 +14,12 @@ import { join } from "path";
 import { homedir } from "os";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { config as loadDotenv } from "dotenv";
-loadDotenv();
 var MERCURY_HOME = join(homedir(), ".mercury");
+loadDotenv();
+var mercuryEnvPath = join(MERCURY_HOME, ".env");
+if (existsSync(mercuryEnvPath)) {
+  loadDotenv({ path: mercuryEnvPath });
+}
 function getMercuryHome() {
   return process.env.MERCURY_HOME || MERCURY_HOME;
 }
@@ -73,6 +77,10 @@ function getDefaultConfig() {
         streaming: getEnvBool("TELEGRAM_STREAMING", true)
       }
     },
+    github: {
+      username: getEnv("GITHUB_USERNAME", ""),
+      email: getEnv("GITHUB_EMAIL", "")
+    },
     memory: {
       dir: getEnv("MEMORY_DIR", join(home, "memory")),
       shortTermMaxMessages: getEnvNum("SHORT_TERM_MAX_MESSAGES", 20)
@@ -1002,6 +1010,12 @@ You can override this:
     if (this.tokenBudget.getUsagePercentage() > 70) {
       prompt += "\nBe concise to conserve tokens.";
     }
+    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) {
+      prompt += "\n\nGitHub companion is active. You can create pull requests, review PRs, manage issues, and use the GitHub API. When the user asks to 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.";
+    }
     return prompt;
   }
   async processInternalPrompt(prompt, channelId, channelType) {
@@ -1705,16 +1719,16 @@ var CLIChannel = class extends BaseChannel {
     }
   }
   async prompt(question) {
-    return new Promise((resolve10) => {
-      this.rl?.question(question, (answer) => resolve10(answer.trim()));
+    return new Promise((resolve11) => {
+      this.rl?.question(question, (answer) => resolve11(answer.trim()));
     });
   }
   async askPermission(prompt) {
-    return new Promise((resolve10) => {
+    return new Promise((resolve11) => {
       console.log("");
       console.log(chalk2.yellow(`  \u26A0 ${prompt}`));
       this.rl?.question(chalk2.yellow("  > "), (answer) => {
-        resolve10(answer.trim());
+        resolve11(answer.trim());
       });
     });
   }
@@ -1977,15 +1991,15 @@ var TelegramChannel = class extends BaseChannel {
         reply_markup: keyboard
       });
     }
-    return new Promise((resolve10) => {
-      this.pendingApprovals.set(`${id}:yes`, () => resolve10("yes"));
-      this.pendingApprovals.set(`${id}:always`, () => resolve10("always"));
-      this.pendingApprovals.set(`${id}:no`, () => resolve10("no"));
+    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"));
       setTimeout(() => {
         this.pendingApprovals.delete(`${id}:yes`);
         this.pendingApprovals.delete(`${id}:always`);
         this.pendingApprovals.delete(`${id}:no`);
-        resolve10("no");
+        resolve11("no");
       }, 12e4);
     });
   }
@@ -2209,7 +2223,7 @@ var TokenBudget = class {
 
 // src/capabilities/permissions.ts
 import { existsSync as existsSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync6, mkdirSync as mkdirSync6 } from "fs";
-import { join as join6, resolve, sep } from "path";
+import { join as join6, resolve as resolve2, sep } from "path";
 import { homedir as homedir2 } from "os";
 import { parse as parseYaml3, stringify as stringifyYaml3 } from "yaml";
 var DEFAULT_MANIFEST = {
@@ -2334,8 +2348,8 @@ var PermissionManager = class {
   clearElevation() {
     this.elevatedCommands.clear();
   }
-  isElevated(tool25) {
-    if (this.elevatedCommands.has(tool25)) return true;
+  isElevated(tool30) {
+    if (this.elevatedCommands.has(tool30)) return true;
     return false;
   }
   isShellElevated() {
@@ -2392,7 +2406,7 @@ var PermissionManager = class {
     if (!fs3.enabled) {
       return { allowed: false, reason: "Filesystem capability is disabled" };
     }
-    const resolved = resolve(path3);
+    const resolved = resolve2(path3);
     const scope = this.findScope(resolved);
     const tempScope = this.findTempScope(resolved);
     if (scope) {
@@ -2482,7 +2496,7 @@ var PermissionManager = class {
     return this.manifest.capabilities.git.enabled && this.manifest.capabilities.git.approveWrite;
   }
   addScope(path3, read, write) {
-    const resolved = resolve(path3);
+    const resolved = resolve2(path3);
     const existing = this.findScope(resolved);
     if (existing) {
       existing.read = existing.read || read;
@@ -2500,7 +2514,7 @@ var PermissionManager = class {
   findScope(resolvedPath) {
     const scopes = this.manifest.capabilities.filesystem.scopes;
     for (const scope of scopes) {
-      const scopeResolved = resolve(scope.path.replace(/^~/, homedir2()));
+      const scopeResolved = resolve2(scope.path.replace(/^~/, homedir2()));
       if (resolvedPath === scopeResolved || resolvedPath.startsWith(scopeResolved + sep)) {
         return scope;
       }
@@ -2527,13 +2541,13 @@ Allow access?`;
     return { allowed: false, reason: `Permission denied for ${mode} access to ${path3}` };
   }
   addTempScope(path3, read, write) {
-    const resolved = resolve(path3);
+    const resolved = resolve2(path3);
     this.tempScopes.push({ path: resolved, read, write });
     logger.info({ path: resolved, read, write }, "Temp permission scope added (session only)");
   }
   findTempScope(resolvedPath) {
     for (const scope of this.tempScopes) {
-      const scopeResolved = resolve(scope.path.replace(/^~/, homedir2()));
+      const scopeResolved = resolve2(scope.path.replace(/^~/, homedir2()));
       if (resolvedPath === scopeResolved || resolvedPath.startsWith(scopeResolved + sep)) {
         return scope;
       }
@@ -2559,7 +2573,7 @@ Allow access?`;
     for (const p of pathPatterns) {
       const match = command.match(p);
       if (match) {
-        const candidate = resolve(match[1].replace(/^~/, homedir2()));
+        const candidate = resolve2(match[1].replace(/^~/, homedir2()));
         if (!candidate.startsWith(this.cwd)) {
           return candidate;
         }
@@ -2595,7 +2609,7 @@ Allow access?`;
 import { tool } from "ai";
 import { z } from "zod";
 import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 function createReadFileTool(permissions) {
   return tool({
     description: "Read the contents of a file. The path must be within an allowed scope.",
@@ -2603,10 +2617,10 @@ function createReadFileTool(permissions) {
       path: z.string().describe("Absolute or relative path to the file")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve2(path3);
+      const resolved = resolve3(path3);
       const check = await permissions.checkFsAccess(resolved, "read");
       if (!check.allowed) {
-        const parentDir = resolve2(resolved, "..");
+        const parentDir = resolve3(resolved, "..");
         return `Error: Permission denied for read access to ${resolved}. Use the approve_scope tool with path="${parentDir}" and mode="read" to request access from the user.`;
       }
       if (!existsSync7(resolved)) {
@@ -2632,7 +2646,7 @@ 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 resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 function createWriteFileTool(permissions) {
   return tool2({
     description: "Write content to an existing file. The path must be within a writable scope.",
@@ -2641,10 +2655,10 @@ function createWriteFileTool(permissions) {
       content: z2.string().describe("The content to write to the file")
     }),
     execute: async ({ path: path3, content }) => {
-      const resolved = resolve3(path3);
+      const resolved = resolve4(path3);
       const check = await permissions.checkFsAccess(resolved, "write");
       if (!check.allowed) {
-        const parentDir = resolve3(resolved, "..");
+        const parentDir = resolve4(resolved, "..");
         return `Error: Permission denied for write access to ${resolved}. Use the approve_scope tool with path="${parentDir}" and mode="write" to request access from the user.`;
       }
       if (!existsSync8(resolved)) {
@@ -2664,7 +2678,7 @@ 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 resolve4, dirname as dirname2 } from "path";
+import { resolve as resolve5, dirname as dirname2 } from "path";
 function createCreateFileTool(permissions) {
   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.",
@@ -2673,10 +2687,10 @@ function createCreateFileTool(permissions) {
       content: z3.string().describe("The content of the new file")
     }),
     execute: async ({ path: path3, content }) => {
-      const resolved = resolve4(path3);
+      const resolved = resolve5(path3);
       const check = await permissions.checkFsAccess(resolved, "write");
       if (!check.allowed) {
-        const parentDir = resolve4(resolved, "..");
+        const parentDir = resolve5(resolved, "..");
         return `Error: Permission denied for write access to ${resolved}. Use the approve_scope tool with path="${parentDir}" and mode="write" to request access from the user.`;
       }
       if (existsSync9(resolved)) {
@@ -2700,7 +2714,7 @@ 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 resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 function createListDirTool(permissions) {
   return tool4({
     description: "List the contents of a directory. Shows file names, types, and sizes.",
@@ -2708,7 +2722,7 @@ function createListDirTool(permissions) {
       path: z4.string().describe("Absolute or relative path to the directory")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve5(path3);
+      const resolved = resolve6(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.`;
@@ -2758,7 +2772,7 @@ 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 resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 function createDeleteFileTool(permissions) {
   return tool5({
     description: "Delete a file. This action cannot be undone. The path must be within a writable scope. Always asks for confirmation.",
@@ -2766,10 +2780,10 @@ function createDeleteFileTool(permissions) {
       path: z5.string().describe("Absolute or relative path to the file to delete")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve6(path3);
+      const resolved = resolve7(path3);
       const check = await permissions.checkFsAccess(resolved, "write");
       if (!check.allowed) {
-        const parentDir = resolve6(resolved, "..");
+        const parentDir = resolve7(resolved, "..");
         return `Error: Permission denied for write access to ${resolved}. Use the approve_scope tool with path="${parentDir}" and mode="write" to request access from the user.`;
       }
       if (!existsSync11(resolved)) {
@@ -2793,7 +2807,7 @@ 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 resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 function createEditFileTool(permissions) {
   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.",
@@ -2803,10 +2817,10 @@ function createEditFileTool(permissions) {
       new_string: z6.string().describe("The text to replace it with")
     }),
     execute: async ({ path: path3, old_string, new_string }) => {
-      const resolved = resolve7(path3);
+      const resolved = resolve8(path3);
       const fsCheck = await permissions.checkFsAccess(resolved, "write");
       if (!fsCheck.allowed) {
-        const parentDir = resolve7(resolved, "..");
+        const parentDir = resolve8(resolved, "..");
         return `Error: Permission denied for write access to ${resolved}. Use the approve_scope tool with path="${parentDir}" and mode="write" to request access from the user.`;
       }
       try {
@@ -2837,7 +2851,7 @@ 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 resolve8, basename } from "path";
+import { resolve as resolve9, basename } from "path";
 function createSendFileTool(permissions, 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.",
@@ -2845,10 +2859,10 @@ function createSendFileTool(permissions, sendFile) {
       path: z7.string().describe("Absolute or relative path to the file to send")
     }),
     execute: async ({ path: path3 }) => {
-      const resolved = resolve8(path3);
+      const resolved = resolve9(path3);
       const check = await permissions.checkFsAccess(resolved, "read");
       if (!check.allowed) {
-        const parentDir = resolve8(resolved, "..");
+        const parentDir = resolve9(resolved, "..");
         return `Error: Permission denied for read access to ${resolved}. Use the approve_scope tool with path="${parentDir}" and mode="read" to request access from the user.`;
       }
       if (!existsSync12(resolved)) {
@@ -2876,7 +2890,7 @@ function createSendFileTool(permissions, sendFile) {
 // src/capabilities/filesystem/approve-scope.ts
 import { tool as tool8 } from "ai";
 import { z as z8 } from "zod";
-import { resolve as resolve9 } from "path";
+import { resolve as resolve10 } from "path";
 function createApproveScopeTool(permissions) {
   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.',
@@ -2885,7 +2899,7 @@ function createApproveScopeTool(permissions) {
       mode: z8.enum(["read", "write"]).describe("The access mode needed")
     }),
     execute: async ({ path: path3, mode }) => {
-      const resolved = resolve9(path3);
+      const resolved = resolve10(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.`;
@@ -3281,15 +3295,19 @@ function createGitAddTool() {
 import { tool as tool22 } from "ai";
 import { z as z22 } from "zod";
 import { execSync as execSync6 } from "child_process";
+var CO_AUTHOR = "Mercury <mercury@cosmicstack.org>";
 function createGitCommitTool() {
   return tool22({
-    description: "Record changes to the repository. Creates a new commit with staged changes.",
+    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")
     }),
     execute: async ({ message }) => {
       try {
-        const escapedMsg = message.replace(/"/g, '\\"');
+        const fullMessage = `${message}
+
+Co-authored-by: ${CO_AUTHOR}`;
+        const escapedMsg = fullMessage.replace(/"/g, '\\"');
         const result = execSync6(`git commit -m "${escapedMsg}"`, { encoding: "utf-8", timeout: 1e4 });
         return result.trim() || "Committed successfully.";
       } catch (err) {
@@ -3336,9 +3354,302 @@ Ask the user for permission. If they approve, try again. If they say "always", u
   });
 }
 
-// src/capabilities/web/fetch-url.ts
+// src/capabilities/github/create-pr.ts
 import { tool as tool24 } from "ai";
 import { z as z24 } from "zod";
+
+// src/utils/github.ts
+var GITHUB_API = "https://api.github.com";
+var cachedToken = null;
+function setGitHubToken(token) {
+  cachedToken = token;
+}
+function getGitHubToken() {
+  if (cachedToken) return cachedToken;
+  return process.env.GITHUB_TOKEN || null;
+}
+function isGitHubConfigured() {
+  return !!getGitHubToken();
+}
+async function githubRequest(path3, options = {}) {
+  const token = getGitHubToken();
+  if (!token) {
+    throw new Error("GITHUB_TOKEN not configured. Run mercury doctor to set it up.");
+  }
+  const url = path3.startsWith("http") ? path3 : `${GITHUB_API}${path3}`;
+  const headers = {
+    "Authorization": `Bearer ${token}`,
+    "Accept": "application/vnd.github.v3+json",
+    "User-Agent": "Mercury-Agent",
+    ...options.headers
+  };
+  const fetchOptions = {
+    method: options.method || "GET",
+    headers
+  };
+  if (options.body) {
+    fetchOptions.body = JSON.stringify(options.body);
+    headers["Content-Type"] = "application/json";
+  }
+  logger.info({ method: fetchOptions.method, path: path3 }, "GitHub API request");
+  const response = await fetch(url, fetchOptions);
+  const remaining = response.headers.get("x-ratelimit-remaining");
+  if (remaining && parseInt(remaining, 10) < 100) {
+    logger.warn({ remaining }, "GitHub API rate limit running low");
+  }
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`GitHub API ${response.status}: ${body.slice(0, 500)}`);
+  }
+  if (response.status === 204) return null;
+  return response.json();
+}
+function parseRepo(remoteUrl) {
+  const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/([^.\s]+)(?:\.git)?$/);
+  if (sshMatch) return { owner: sshMatch[1], repo: sshMatch[2] };
+  const httpsMatch = remoteUrl.match(/https:\/\/github\.com\/([^/]+)\/([^.\s]+)(?:\.git)?$/);
+  if (httpsMatch) return { owner: httpsMatch[1], repo: httpsMatch[2] };
+  return null;
+}
+async function getCurrentRepo() {
+  try {
+    const { execSync: execSync9 } = await import("child_process");
+    const remoteUrl = execSync9("git remote get-url origin", { encoding: "utf-8", timeout: 5e3 }).trim();
+    return parseRepo(remoteUrl);
+  } catch {
+    return null;
+  }
+}
+
+// src/capabilities/github/create-pr.ts
+function createCreatePrTool() {
+  return tool24({
+    description: "Create a pull request on GitHub. Requires GITHUB_TOKEN to be configured.",
+    parameters: z24.object({
+      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)
+    }),
+    execute: async ({ title, body, head, base, draft }) => {
+      try {
+        const repo = await getCurrentRepo();
+        if (!repo) return "Error: Could not detect GitHub repository. Make sure you are in a git repo with a GitHub remote.";
+        const result = await githubRequest(`/repos/${repo.owner}/${repo.repo}/pulls`, {
+          method: "POST",
+          body: {
+            title,
+            body,
+            head,
+            base,
+            draft
+          }
+        });
+        return `PR created: ${result.html_url}
+#${result.number}: ${result.title}
+${draft ? "(draft)" : ""} ${result.state}`;
+      } catch (err) {
+        return `Error creating PR: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/capabilities/github/review-pr.ts
+import { tool as tool25 } from "ai";
+import { z as z25 } from "zod";
+function createReviewPrTool() {
+  return tool25({
+    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({
+      number: z25.number().describe("PR number"),
+      comment: z25.string().describe("Review comment to post on the PR (optional)").optional()
+    }),
+    execute: async ({ number, comment }) => {
+      try {
+        const repo = await getCurrentRepo();
+        if (!repo) return "Error: Could not detect GitHub repository.";
+        const pr = await githubRequest(`/repos/${repo.owner}/${repo.repo}/pulls/${number}`);
+        if (!pr) return `Error: PR #${number} not found.`;
+        const diff = await githubRequest(`/repos/${repo.owner}/${repo.repo}/pulls/${number}`, {
+          headers: { "Accept": "application/vnd.github.v3.diff" }
+        });
+        let summary = `PR #${pr.number}: ${pr.title}
+`;
+        summary += `Author: ${pr.user?.login}
+`;
+        summary += `State: ${pr.state} (${pr.merged ? "merged" : pr.mergeable_state || "unknown"})
+`;
+        summary += `Branch: ${pr.head.ref} \u2192 ${pr.base.ref}
+`;
+        summary += `Changed files: ${pr.changed_files} | Additions: +${pr.additions} | Deletions: -${pr.deletions}
+
+`;
+        if (pr.body) {
+          summary += `Description:
+${pr.body.slice(0, 2e3)}
+
+`;
+        }
+        if (typeof diff === "string") {
+          const diffLines = diff.split("\n");
+          const maxDiffLines = 200;
+          summary += `Diff (first ${Math.min(diffLines.length, maxDiffLines)} of ${diffLines.length} lines):
+`;
+          summary += diffLines.slice(0, maxDiffLines).join("\n");
+          if (diffLines.length > maxDiffLines) {
+            summary += `
+
+... (${diffLines.length - maxDiffLines} more lines)`;
+          }
+        } else {
+          summary += `(Diff not available in text format)`;
+        }
+        if (comment) {
+          try {
+            await githubRequest(`/repos/${repo.owner}/${repo.repo}/pulls/${number}/reviews`, {
+              method: "POST",
+              body: {
+                body: comment,
+                event: "COMMENT"
+              }
+            });
+            summary += `
+
+Review comment posted.`;
+          } catch (err) {
+            summary += `
+
+Failed to post review comment: ${err.message}`;
+          }
+        }
+        return summary;
+      } catch (err) {
+        return `Error reviewing PR: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/capabilities/github/list-issues.ts
+import { tool as tool26 } from "ai";
+import { z as z26 } from "zod";
+function createListIssuesTool() {
+  return tool26({
+    description: "List open GitHub issues for the current repository. Requires GITHUB_TOKEN.",
+    parameters: z26.object({
+      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)
+    }),
+    execute: async ({ state, labels, limit }) => {
+      try {
+        const repo = await getCurrentRepo();
+        if (!repo) return "Error: Could not detect GitHub repository.";
+        const params = new URLSearchParams();
+        params.set("state", state);
+        params.set("per_page", String(Math.min(limit, 100)));
+        params.set("sort", "updated");
+        params.set("direction", "desc");
+        if (labels) params.set("labels", labels);
+        const issues = await githubRequest(`/repos/${repo.owner}/${repo.repo}/issues?${params}`);
+        if (!Array.isArray(issues) || issues.length === 0) {
+          return `No ${state} issues found.`;
+        }
+        const lines = issues.map((issue) => {
+          const labelStr = issue.labels?.map((l) => `[${l.name}]`).join(" ") || "";
+          return `#${issue.number} ${issue.title} ${labelStr} (${issue.state}, by ${issue.user?.login})`;
+        });
+        return `Issues in ${repo.owner}/${repo.repo} (${state}):
+${lines.join("\n")}`;
+      } catch (err) {
+        return `Error listing issues: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/capabilities/github/create-issue.ts
+import { tool as tool27 } from "ai";
+import { z as z27 } from "zod";
+function createCreateIssueTool() {
+  return tool27({
+    description: "Create a new GitHub issue in the current repository. Requires GITHUB_TOKEN.",
+    parameters: z27.object({
+      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()
+    }),
+    execute: async ({ title, body, labels }) => {
+      try {
+        const repo = await getCurrentRepo();
+        if (!repo) return "Error: Could not detect GitHub repository.";
+        const payload = { title, body };
+        if (labels && labels.length > 0) payload.labels = labels;
+        const result = await githubRequest(`/repos/${repo.owner}/${repo.repo}/issues`, {
+          method: "POST",
+          body: payload
+        });
+        return `Issue created: ${result.html_url}
+#${result.number}: ${result.title}`;
+      } catch (err) {
+        return `Error creating issue: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/capabilities/github/github-api.ts
+import { tool as tool28 } from "ai";
+import { z as z28 } from "zod";
+function createGithubApiTool(permissions) {
+  return tool28({
+    description: "Make a raw request to the GitHub API. Use this for any GitHub operation not covered by other tools. GET requests are auto-approved; write operations (POST, PUT, PATCH, DELETE) require approval.",
+    parameters: z28.object({
+      path: z28.string().describe("API path (e.g., /repos/owner/repo/releases)"),
+      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()
+    }),
+    execute: async ({ path: path3, method, body }) => {
+      const isWrite = ["POST", "PUT", "PATCH", "DELETE"].includes(method);
+      if (isWrite) {
+        const check = await permissions.checkShellCommand(`github-api ${method} ${path3}`);
+        if (!check.allowed) {
+          if (check.needsApproval) {
+            return `This GitHub API write operation requires approval: ${method} ${path3}
+
+Tell the user what this does and ask for confirmation. If approved, try again.`;
+          }
+          return `Error: ${check.reason}`;
+        }
+      }
+      try {
+        let parsedBody;
+        if (body) {
+          try {
+            parsedBody = JSON.parse(body);
+          } catch {
+            return "Error: body must be valid JSON.";
+          }
+        }
+        const result = await githubRequest(path3, {
+          method,
+          body: parsedBody
+        });
+        if (result === null) return "Request completed (204 No Content).";
+        if (typeof result === "string") return result;
+        return JSON.stringify(result, null, 2);
+      } catch (err) {
+        return `Error: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/capabilities/web/fetch-url.ts
+import { tool as tool29 } from "ai";
+import { z as z29 } from "zod";
 var MAX_CONTENT_LENGTH = 15e3;
 function stripHtml(html) {
   let text = html;
@@ -3371,11 +3682,11 @@ function stripHtml(html) {
   return text;
 }
 function createFetchUrlTool() {
-  return tool24({
+  return tool29({
     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: z24.object({
-      url: z24.string().describe("The URL to fetch"),
-      format: z24.enum(["text", "markdown"]).optional().describe("Output format (default: markdown)")
+    parameters: z29.object({
+      url: z29.string().describe("The URL to fetch"),
+      format: z29.enum(["text", "markdown"]).optional().describe("Output format (default: markdown)")
     }),
     execute: async ({ url, format }) => {
       const outputFormat = format ?? "markdown";
@@ -3497,6 +3808,14 @@ var CapabilityRegistry = class {
       this.tools.git_push = createGitPushTool(this.permissions);
       logger.info("Git tools registered");
     }
+    if (isGitHubConfigured()) {
+      this.tools.create_pr = createCreatePrTool();
+      this.tools.review_pr = createReviewPrTool();
+      this.tools.list_issues = createListIssuesTool();
+      this.tools.create_issue = createCreateIssueTool();
+      this.tools.github_api = createGithubApiTool(this.permissions);
+      logger.info("GitHub tools registered");
+    }
     this.tools.fetch_url = createFetchUrlTool();
     logger.info("Web fetch tool registered");
   }
@@ -4309,7 +4628,7 @@ async function runWithWatchdog(agentFn) {
   await attempt();
 }
 function sleep(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 
 // src/index.ts
@@ -4348,10 +4667,10 @@ function splashScreen() {
 }
 async function ask(prompt) {
   const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     rl.question(prompt, (answer) => {
       rl.close();
-      resolve10(answer.trim());
+      resolve11(answer.trim());
     });
   });
 }
@@ -4360,6 +4679,17 @@ 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);
 }
+function appendToEnv(key, value) {
+  const envPath = join11(getMercuryHome(), ".env");
+  let envContent = "";
+  if (existsSync16(envPath)) {
+    envContent = readFileSync12(envPath, "utf-8");
+  }
+  const lines = envContent.split("\n").filter((l) => !l.startsWith(`${key}=`) && l.trim() !== "");
+  lines.push(`${key}=${value}`);
+  writeFileSync13(envPath, lines.join("\n") + "\n", "utf-8");
+  process.env[key] = value;
+}
 async function configure(existingConfig) {
   const isReconfig = !!existingConfig;
   const config = existingConfig ?? loadConfig();
@@ -4458,6 +4788,23 @@ async function configure(existingConfig) {
   }
   hr();
   console.log("");
+  console.log(chalk6.bold.white("  GitHub (optional)"));
+  console.log(chalk6.dim("  Connect Mercury to GitHub for PRs, issues, and co-authored commits."));
+  console.log(chalk6.dim("  Leave empty to skip. You can add it later with mercury doctor."));
+  console.log("");
+  const ghUserCurrent = isReconfig && config.github.username ? ` [${config.github.username}]` : "";
+  const ghUsername = await ask(chalk6.white(`  GitHub username${ghUserCurrent}: `));
+  if (ghUsername) config.github.username = ghUsername;
+  const ghEmailCurrent = isReconfig && config.github.email ? ` [${config.github.email}]` : "";
+  const ghEmail = await ask(chalk6.white(`  GitHub email${ghEmailCurrent}: `));
+  if (ghEmail) config.github.email = ghEmail;
+  const ghTokenCurrent = process.env.GITHUB_TOKEN ? ` [${maskKey(process.env.GITHUB_TOKEN)}]` : "";
+  const ghToken = await ask(chalk6.white(`  GitHub PAT (repo scope)${ghTokenCurrent}: `));
+  if (ghToken) {
+    appendToEnv("GITHUB_TOKEN", ghToken);
+  }
+  hr();
+  console.log("");
   console.log(chalk6.bold.white("  Token Budget"));
   console.log("");
   const budgetPrompt = isReconfig ? chalk6.white(`  Daily token budget [${config.tokens.dailyBudget.toLocaleString()}]: `) : chalk6.white(`  Daily token budget [${config.tokens.dailyBudget.toLocaleString()}]: `);
@@ -4558,6 +4905,9 @@ async function runAgent(isDaemon = false) {
       await msg.sendFile(filePath);
     }
   });
+  if (process.env.GITHUB_TOKEN) {
+    setGitHubToken(process.env.GITHUB_TOKEN);
+  }
   capabilities.registerAll();
   const agent = new Agent(
     config,