@juspay/yama 2.4.2 → 2.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.6.0](https://github.com/juspay/yama/compare/v2.5.0...v2.6.0) (2026-06-04)
+
+
+### Features
+
+* **action:** add Yama self-review workflow with LiteLLM/Vertex auth ([5ebb73f](https://github.com/juspay/yama/commit/5ebb73f2450951b5f97d97a6a3caa89377a150af))
+
+# [2.5.0](https://github.com/juspay/yama/compare/v2.4.2...v2.5.0) (2026-06-03)
+
+
+### Features
+
+* **github:** add GitHub provider for PR reviews ([0b8e45f](https://github.com/juspay/yama/commit/0b8e45f30a95a30988c0dc6f84e929d2338108fe))
+
 ## [2.4.2](https://github.com/juspay/yama/compare/v2.4.1...v2.4.2) (2026-04-24)
 
 

package/dist/cli/cli.js

@@ -43,6 +43,8 @@ function setupReviewCommand() {
         .option("--mode <mode>", "Review mode (pr|local)", "pr")
         .option("-w, --workspace <workspace>", "Bitbucket workspace")
         .option("-r, --repository <repository>", "Repository name")
+        .option("--owner <owner>", "GitHub owner/organization")
+        .option("--repo <repo>", "GitHub repository (alternative to --repository)")
         .option("-p, --pr <id>", "Pull request ID")
         .option("-b, --branch <branch>", "Branch name (finds PR automatically)")
         .option("--repo-path <path>", "Local repository path (local mode)")
@@ -93,10 +95,39 @@ function setupReviewCommand() {
                 }
                 process.exit(result.decision === "BLOCKED" ? 1 : 0);
             }
-            if (!options.workspace || !options.repository) {
-                console.error("❌ Error: --workspace and --repository are required in pr mode");
+            // Auto-detect provider and validate required parameters.
+            // --repo is GitHub-only; Bitbucket uses --repository so that
+            // 'yama review --workspace acme --repo service' is not misread as mixed.
+            const hasGitHub = options.owner || options.repo;
+            const hasBitbucket = options.workspace || options.repository;
+            if (hasGitHub && hasBitbucket) {
+                console.error("❌ Error: Cannot mix GitHub (--owner/--repo) and Bitbucket (--workspace/--repository) parameters");
                 process.exit(1);
             }
+            if (!hasGitHub && !hasBitbucket) {
+                console.error("❌ Error: Either GitHub (--owner and --repo) or Bitbucket (--workspace and --repository) parameters are required");
+                process.exit(1);
+            }
+            if (hasGitHub) {
+                if (!options.owner) {
+                    console.error("❌ Error: --owner is required when using GitHub parameters");
+                    process.exit(1);
+                }
+                if (!options.repo) {
+                    console.error("❌ Error: --repo is required when using GitHub parameters");
+                    process.exit(1);
+                }
+            }
+            else {
+                if (!options.workspace) {
+                    console.error("❌ Error: --workspace is required when using Bitbucket parameters");
+                    process.exit(1);
+                }
+                if (!options.repository) {
+                    console.error("❌ Error: --repository is required when using Bitbucket parameters");
+                    process.exit(1);
+                }
+            }
             if (!options.pr && !options.branch) {
                 console.error("❌ Error: Either --pr or --branch must be specified");
                 process.exit(1);
@@ -111,9 +142,17 @@ function setupReviewCommand() {
             }
             const request = {
                 mode: "pr",
+                provider: hasGitHub ? "github" : "bitbucket",
+                owner: options.owner,
+                repo: options.repo,
                 workspace: options.workspace,
                 repository: options.repository,
                 pullRequestId,
+                // GitHub SDK/prompt paths read prNumber; mirror pullRequestId for
+                // GitHub only so Bitbucket behavior stays unchanged.
+                prNumber: hasGitHub && typeof pullRequestId === "number"
+                    ? pullRequestId
+                    : undefined,
                 branch: options.branch,
                 dryRun: globalOpts.dryRun || false,
                 verbose: globalOpts.verbose || false,
@@ -122,7 +161,9 @@ function setupReviewCommand() {
                 focus,
                 outputSchemaVersion: options.outputSchemaVersion,
             };
-            await yama.initialize(request.configPath);
+            // Thread the request into initialize so MCP servers are set up for the
+            // correct provider (GitHub vs Bitbucket) before review starts.
+            await yama.initialize(request.configPath, "pr", request);
             console.log("🚀 Starting autonomous AI review...\n");
             const result = options.reviewOnly
                 ? await yama.startReview(request)
@@ -140,6 +181,8 @@ function setupReviewCommand() {
                 console.log("\n📄 Full Results:");
                 console.log(JSON.stringify(result, null, 2));
             }
+            // Surface outputs for the composite GitHub Action (provider-agnostic).
+            await writeGitHubOutputs(result);
             process.exit(result.decision === "BLOCKED" ? 1 : 0);
         }
         catch (error) {
@@ -152,6 +195,34 @@ function setupReviewCommand() {
         }
     });
 }
+/**
+ * Append PR review outputs to the GitHub Actions output file so a composite
+ * Action can expose them as step outputs. No-op outside GitHub Actions (when
+ * GITHUB_OUTPUT is unset). Provider-agnostic: works for Bitbucket too.
+ */
+async function writeGitHubOutputs(result) {
+    const outputPath = process.env.GITHUB_OUTPUT;
+    if (!outputPath) {
+        return;
+    }
+    const issues = result.statistics?.issuesFound;
+    const summary = (result.summary || "").trim();
+    const lines = [
+        `decision=${result.decision}`,
+        `summary<<EOF\n${summary}\nEOF`,
+        `critical-issues=${issues?.critical ?? 0}`,
+        `major-issues=${issues?.major ?? 0}`,
+        `minor-issues=${issues?.minor ?? 0}`,
+        `total-comments=${result.statistics?.totalComments ?? 0}`,
+    ];
+    try {
+        const fs = await import("fs/promises");
+        await fs.appendFile(outputPath, `${lines.join("\n")}\n`, "utf8");
+    }
+    catch (error) {
+        console.error("⚠️  Failed to write GitHub Action outputs:", error.message);
+    }
+}
 /**
  * Enhance description command
  */

package/dist/index.js

@@ -5,6 +5,10 @@
 // ============================================================================
 // Core Exports
 // ============================================================================
+// `YamaOrchestrator` is exported below as a class, which exposes it to SDK
+// consumers as BOTH a value and a type (with all of its public methods). A
+// separate `export type { YamaOrchestrator }` is intentionally omitted because
+// it would collide with this value export (TS2300: Duplicate identifier).
 export { YamaOrchestrator, createYama, YamaOrchestrator as YamaV2Orchestrator, createYama as createYamaV2, } from "./v2/core/YamaV2Orchestrator.js";
 export { LearningOrchestrator, createLearningOrchestrator, } from "./v2/core/LearningOrchestrator.js";
 export { ConfigLoader } from "./v2/config/ConfigLoader.js";

package/dist/v2/config/ConfigLoader.d.ts

@@ -15,9 +15,14 @@ export declare class ConfigLoader {
      */
     getConfig(): YamaConfig;
     /**
-     * Validate configuration completeness and correctness
+     * Validate configuration completeness and correctness.
+     *
+     * @param mode      "pr" requires VCS credentials; "local" is SDK-first and skips them.
+     * @param provider  Detected VCS provider. When "github", Bitbucket env vars are
+     *                  NOT required (a GitHub token is required instead); otherwise
+     *                  Bitbucket credentials are validated as before.
      */
-    validate(mode?: "pr" | "local"): Promise<void>;
+    validate(mode?: "pr" | "local", provider?: "github" | "bitbucket"): Promise<void>;
     /**
      * Resolve configuration file path
      */

package/dist/v2/config/ConfigLoader.js

@@ -53,9 +53,14 @@ export class ConfigLoader {
         return this.config;
     }
     /**
-     * Validate configuration completeness and correctness
+     * Validate configuration completeness and correctness.
+     *
+     * @param mode      "pr" requires VCS credentials; "local" is SDK-first and skips them.
+     * @param provider  Detected VCS provider. When "github", Bitbucket env vars are
+     *                  NOT required (a GitHub token is required instead); otherwise
+     *                  Bitbucket credentials are validated as before.
      */
-    async validate(mode = "pr") {
+    async validate(mode = "pr", provider) {
         if (!this.config) {
             throw new ConfigurationError("No configuration to validate");
         }
@@ -69,15 +74,29 @@ export class ConfigLoader {
         }
         // Local mode is SDK-first and does not require MCP credentials.
         if (mode === "pr") {
-            // Check environment variables for Bitbucket (required in PR mode)
-            if (!process.env.BITBUCKET_USERNAME) {
-                errors.push("BITBUCKET_USERNAME environment variable not set");
-            }
-            if (!process.env.BITBUCKET_TOKEN) {
-                errors.push("BITBUCKET_TOKEN environment variable not set");
+            if (provider === "github") {
+                // GitHub provider: require a GitHub token instead of Bitbucket creds.
+                // Token resolution order mirrors MCPServerManager: GITHUB_TOKEN →
+                // GH_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GITHUB_ACCESS_TOKEN
+                // (GITHUB_ACCESS_TOKEN is the dedicated PAT used in Curator/DNV).
+                if (!process.env.GITHUB_TOKEN &&
+                    !process.env.GH_TOKEN &&
+                    !process.env.GITHUB_PERSONAL_ACCESS_TOKEN &&
+                    !process.env.GITHUB_ACCESS_TOKEN) {
+                    errors.push("GitHub provider selected but no GitHub token found. Set GITHUB_TOKEN (or GH_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN / GITHUB_ACCESS_TOKEN).");
+                }
             }
-            if (!process.env.BITBUCKET_BASE_URL) {
-                errors.push("BITBUCKET_BASE_URL environment variable not set");
+            else {
+                // Bitbucket provider (default): require Bitbucket credentials.
+                if (!process.env.BITBUCKET_USERNAME) {
+                    errors.push("BITBUCKET_USERNAME environment variable not set");
+                }
+                if (!process.env.BITBUCKET_TOKEN) {
+                    errors.push("BITBUCKET_TOKEN environment variable not set");
+                }
+                if (!process.env.BITBUCKET_BASE_URL) {
+                    errors.push("BITBUCKET_BASE_URL environment variable not set");
+                }
             }
             if (this.config.mcpServers.jira.enabled) {
                 if (!process.env.JIRA_EMAIL) {

package/dist/v2/config/DefaultConfig.js

@@ -45,6 +45,19 @@ export class DefaultConfig {
                 bitbucket: {
                     blockedTools: [],
                 },
+                github: {
+                    enabled: true,
+                    url: "https://api.githubcopilot.com/mcp/",
+                    transport: "http",
+                    blockedTools: [
+                        "push_files",
+                        "create_or_update_file",
+                        "create_branch",
+                        "delete_file",
+                        "create_pull_request_with_copilot",
+                        "assign_copilot_to_issue",
+                    ],
+                },
                 jira: {
                     enabled: false, // Opt-in: users must explicitly enable Jira integration
                     blockedTools: [],

package/dist/v2/core/LearningOrchestrator.js

@@ -9,6 +9,7 @@ import { ConfigLoader } from "../config/ConfigLoader.js";
 import { LangfusePromptManager } from "../prompts/LangfusePromptManager.js";
 import { KnowledgeBaseManager } from "../learning/KnowledgeBaseManager.js";
 import { MemoryManager } from "../memory/MemoryManager.js";
+import { getProviderToolset, } from "../providers/ProviderToolset.js";
 import { buildObservabilityConfigFromEnv, validateObservabilityConfig, } from "../utils/ObservabilityConfig.js";
 export class LearningOrchestrator {
     neurolink;
@@ -157,7 +158,7 @@ export class LearningOrchestrator {
                     for (const [category, items] of byCategory) {
                         parts.push(`${category}: ${items.join("; ")}`);
                     }
-                    const ownerId = MemoryManager.buildOwnerId(request.workspace, request.repository);
+                    const ownerId = MemoryManager.buildOwnerId(request.workspace, request.repository, request.provider || "bitbucket");
                     await this.neurolink.generate({
                         input: { text: parts.join(". ") },
                         provider: this.config.ai.provider,
@@ -228,17 +229,32 @@ export class LearningOrchestrator {
      */
     buildFetchCommentsInstructions(request) {
         const aiPatterns = this.config.knowledgeBase.aiAuthorPatterns.join(", ");
+        // Derive the PR-read tool name and identifier format from the provider
+        // toolset so a GitHub learn run asks for the tool it actually has.
+        // The learn flow's only provider signal is request.provider; default to
+        // bitbucket to preserve existing behavior.
+        const provider = request.provider === "github" ? "github" : "bitbucket";
+        const toolset = getProviderToolset(provider);
+        const prReadTool = toolset.prReadToolName;
+        // Bitbucket: workspace/repository/pull_request_id (byte-identical to before).
+        // GitHub: owner/repo/pull_number — the same repository identifiers carried
+        // by the Bitbucket-shaped request, relabelled to GitHub's vocabulary.
+        const prDetails = provider === "github"
+            ? `  <owner>${request.workspace}</owner>
+  <repo>${request.repository}</repo>
+  <pull_number>${request.pullRequestId}</pull_number>`
+            : `  <workspace>${request.workspace}</workspace>
+  <repository>${request.repository}</repository>
+  <pull_request_id>${request.pullRequestId}</pull_request_id>`;
         return `
 <task>Fetch and analyze ALL PR comments for learning extraction</task>
 
 <pr-details>
-  <workspace>${request.workspace}</workspace>
-  <repository>${request.repository}</repository>
-  <pull_request_id>${request.pullRequestId}</pull_request_id>
+${prDetails}
 </pr-details>
 
 <instructions>
-1. Use get_pull_request tool to fetch the PR details including all comments/activities
+1. Use ${prReadTool} tool to fetch the PR details including all comments/activities
 2. Look through ALL comments on the PR (both active and resolved if available)
 3. Identify AI-generated comments by:
    - Author patterns: ${aiPatterns}

package/dist/v2/core/MCPServerManager.d.ts

@@ -6,10 +6,21 @@ import { MCPServersConfig } from "../types/config.types.js";
 export declare class MCPServerManager {
     private initialized;
     /**
-     * Setup all MCP servers in NeuroLink
-     * Bitbucket is always enabled, Jira is optional based on config
+     * Setup MCP servers based on detected provider
+     * GitHub MCP OR Bitbucket MCP (not both) - whichever is needed
+     * Jira is optional for both
      */
-    setupMCPServers(neurolink: any, config: MCPServersConfig): Promise<void>;
+    setupMCPServers(neurolink: any, config: MCPServersConfig, provider?: "github" | "bitbucket"): Promise<void>;
+    /**
+     * Reset PR-mode MCP setup so {@link setupMCPServers} can re-register for a
+     * different provider within the same process (e.g. one orchestrator instance
+     * reviewing a Bitbucket PR then a GitHub PR). Removes the previously-registered
+     * provider server (Bitbucket or GitHub) so the new provider's server takes its
+     * place, and clears the `initialized` guard. The optional Jira server is left
+     * in place — it is provider-agnostic and shared. Single-provider runs never
+     * call this, so their behaviour is unchanged.
+     */
+    resetForProviderSwitch(neurolink: any, previousProvider: "github" | "bitbucket"): Promise<void>;
     /**
      * Setup local git MCP server for SDK/local mode.
      * Mandatory in local mode.
@@ -22,6 +33,36 @@ export declare class MCPServerManager {
      * Setup Bitbucket MCP server (hardcoded, always enabled)
      */
     private setupBitbucketMCP;
+    /**
+     * Setup GitHub MCP server.
+     *
+     * Registers GitHub's hosted REMOTE HTTP MCP server via NeuroLink, mirroring
+     * Curator's proven pattern (transport: "http" + Bearer auth header). The old
+     * `npx @github/github-mcp-server` package does not exist, so stdio is only
+     * supported for an explicitly-configured self-hosted / Docker server.
+     *
+     * URL + transport are config-driven (`mcpServers.github.{url,transport,command,args}`),
+     * defaulting to the remote HTTP endpoint.
+     */
+    private setupGitHubMCP;
+    /**
+     * Poll {@link listMCPServers} until the named server reports "connected" with
+     * at least one tool, or the timeout elapses. Returns the last-seen server
+     * entry (possibly not-yet-connected) so the caller can decide how to proceed.
+     *
+     * Bounded by `timeoutMs` via the loop condition — it cannot run indefinitely.
+     */
+    private waitForMCPServer;
+    /**
+     * Build the remote HTTP GitHub MCP registration (default path).
+     * A Bearer token is required for the hosted endpoint.
+     */
+    private buildGitHubHttpConfig;
+    /**
+     * Build a self-hosted / Docker stdio GitHub MCP registration.
+     * Only used when `mcpServers.github.transport === "stdio"`; requires `command`.
+     */
+    private buildGitHubStdioConfig;
     /**
      * Setup Jira MCP server (hardcoded, optionally enabled)
      */

package/dist/v2/core/MCPServerManager.js

@@ -4,22 +4,52 @@
  */
 import { join } from "path";
 import { MCPServerError } from "../types/v2.types.js";
+/**
+ * Default remote HTTP endpoint for GitHub's hosted MCP server.
+ * Overridable via `mcpServers.github.url`.
+ */
+const DEFAULT_GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/";
+/**
+ * Default write tools blocked on the GitHub MCP server.
+ * Mirrors Curator's proven pattern: the AI never mutates the repo directly —
+ * the single write path is the review-comment / review-submit tools, which are
+ * intentionally NOT blocked here.
+ */
+const DEFAULT_GITHUB_BLOCKED_TOOLS = [
+    "push_files",
+    "create_or_update_file",
+    "create_branch",
+    "delete_file",
+    "create_pull_request_with_copilot",
+    "assign_copilot_to_issue",
+];
 export class MCPServerManager {
     // MCP servers are managed entirely by NeuroLink
     // No need to track tools locally
     initialized = false;
     /**
-     * Setup all MCP servers in NeuroLink
-     * Bitbucket is always enabled, Jira is optional based on config
+     * Setup MCP servers based on detected provider
+     * GitHub MCP OR Bitbucket MCP (not both) - whichever is needed
+     * Jira is optional for both
      */
-    async setupMCPServers(neurolink, config) {
+    async setupMCPServers(neurolink, config, provider = "bitbucket") {
         if (this.initialized) {
             return;
         }
         console.log("🔌 Setting up MCP servers...");
-        // Setup Bitbucket MCP (always enabled)
-        await this.setupBitbucketMCP(neurolink, config.bitbucket?.blockedTools);
-        // Setup Jira MCP (optional)
+        console.log(`   📍 Provider: ${provider}`);
+        // Setup provider-specific MCP (only one needed)
+        if (provider === "github") {
+            // Fail fast rather than passing an undefined/disabled config downstream.
+            if (!config.github || config.github.enabled === false) {
+                throw new MCPServerError("GitHub provider selected but mcpServers.github is not enabled");
+            }
+            await this.setupGitHubMCP(neurolink, config.github);
+        }
+        else {
+            await this.setupBitbucketMCP(neurolink, config.bitbucket?.blockedTools);
+        }
+        // Setup Jira MCP (optional, works with both providers)
         if (config.jira.enabled) {
             await this.setupJiraMCP(neurolink, config.jira.blockedTools);
         }
@@ -30,6 +60,26 @@ export class MCPServerManager {
         await this.logDiagnostics(neurolink);
         console.log("✅ MCP servers configured\n");
     }
+    /**
+     * Reset PR-mode MCP setup so {@link setupMCPServers} can re-register for a
+     * different provider within the same process (e.g. one orchestrator instance
+     * reviewing a Bitbucket PR then a GitHub PR). Removes the previously-registered
+     * provider server (Bitbucket or GitHub) so the new provider's server takes its
+     * place, and clears the `initialized` guard. The optional Jira server is left
+     * in place — it is provider-agnostic and shared. Single-provider runs never
+     * call this, so their behaviour is unchanged.
+     */
+    async resetForProviderSwitch(neurolink, previousProvider) {
+        const serverName = previousProvider === "github" ? "github" : "bitbucket";
+        try {
+            await neurolink.removeExternalMCPServer?.(serverName);
+        }
+        catch {
+            // Non-fatal: if removal fails the subsequent re-register will surface a
+            // clearer error. Proceed to allow re-setup.
+        }
+        this.initialized = false;
+    }
     /**
      * Setup local git MCP server for SDK/local mode.
      * Mandatory in local mode.
@@ -145,6 +195,154 @@ export class MCPServerManager {
             throw new MCPServerError(`Failed to setup Bitbucket MCP server: ${error.message}`);
         }
     }
+    /**
+     * Setup GitHub MCP server.
+     *
+     * Registers GitHub's hosted REMOTE HTTP MCP server via NeuroLink, mirroring
+     * Curator's proven pattern (transport: "http" + Bearer auth header). The old
+     * `npx @github/github-mcp-server` package does not exist, so stdio is only
+     * supported for an explicitly-configured self-hosted / Docker server.
+     *
+     * URL + transport are config-driven (`mcpServers.github.{url,transport,command,args}`),
+     * defaulting to the remote HTTP endpoint.
+     */
+    async setupGitHubMCP(neurolink, githubConfig) {
+        try {
+            console.log("   🔧 Registering GitHub MCP server...");
+            // Be robust to a possibly-undefined config: default URL + transport +
+            // blockedTools so registration still works if the caller passes nothing.
+            const transport = githubConfig?.transport ?? "http";
+            // ADDITIVE, not replacing: always enforce the default write-block denylist
+            // and union it with any user-provided entries, so a user-supplied
+            // `blockedTools` can only EXTEND the denylist — never un-block write tools
+            // like push_files / create_or_update_file.
+            const blockedTools = Array.from(new Set([
+                ...DEFAULT_GITHUB_BLOCKED_TOOLS,
+                ...(githubConfig?.blockedTools ?? []),
+            ]));
+            // An explicit token is REQUIRED. gh CLI auth (hosts.yml) cannot supply a
+            // Bearer token for the remote HTTP transport, so we do not accept it as a
+            // substitute. The hosted endpoint (api.githubcopilot.com) expects a real
+            // GitHub PAT — the ephemeral Actions GITHUB_TOKEN may be rejected. Token
+            // resolution order mirrors Curator's proven setup (GITHUB_ACCESS_TOKEN):
+            //   GITHUB_TOKEN → GH_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GITHUB_ACCESS_TOKEN.
+            const ghToken = process.env.GITHUB_TOKEN ||
+                process.env.GH_TOKEN ||
+                process.env.GITHUB_PERSONAL_ACCESS_TOKEN ||
+                process.env.GITHUB_ACCESS_TOKEN;
+            if (!ghToken) {
+                throw new MCPServerError("Missing GitHub authentication: set GITHUB_TOKEN (or GH_TOKEN / " +
+                    "GITHUB_PERSONAL_ACCESS_TOKEN / GITHUB_ACCESS_TOKEN). The remote HTTP " +
+                    "transport requires an explicit GitHub PAT; 'gh auth login' alone is " +
+                    "not sufficient.");
+            }
+            const config = transport === "stdio"
+                ? this.buildGitHubStdioConfig(githubConfig, ghToken, blockedTools)
+                : this.buildGitHubHttpConfig(githubConfig, ghToken, blockedTools);
+            await neurolink.addExternalMCPServer("github", config);
+            // The remote HTTP endpoint (api.githubcopilot.com) connects asynchronously
+            // — TLS handshake + auth + tool discovery take ~3-4s, and NeuroLink may only
+            // finish discovery lazily on the first generate() call. Poll briefly for a
+            // healthy status, but for the HTTP transport DO NOT hard-fail if it is not
+            // yet "connected": the tools are resolved when the review runs (this mirrors
+            // Curator's proven pattern). For a local stdio server we keep the strict
+            // check, since a local process should connect promptly.
+            const ghServer = await this.waitForMCPServer(neurolink, "github", 12000);
+            const connected = ghServer?.status === "connected" && (ghServer?.tools?.length ?? 0) > 0;
+            if (transport === "stdio" && !connected) {
+                throw new MCPServerError(`GitHub MCP server registered but not connected (status: ${ghServer?.status ?? "unknown"}, tools: ${ghServer?.tools?.length ?? 0}). Possible startup timeout.`);
+            }
+            if (connected) {
+                console.log(`   ✅ GitHub MCP server registered and tools available (transport: ${transport})`);
+            }
+            else {
+                console.warn(`   ⚠️  GitHub MCP server registered but not yet reporting connected ` +
+                    `(status: ${ghServer?.status ?? "unknown"}, tools: ${ghServer?.tools?.length ?? 0}). ` +
+                    `Remote tools are discovered on first use; continuing.`);
+            }
+            if (transport === "http") {
+                console.log(`   🌐 Remote endpoint: ${config.url}`);
+            }
+            console.log(`   🚫 Blocked write tools: ${blockedTools.join(", ")}`);
+        }
+        catch (error) {
+            throw new MCPServerError(`Failed to setup GitHub MCP server: ${error.message}`);
+        }
+    }
+    /**
+     * Poll {@link listMCPServers} until the named server reports "connected" with
+     * at least one tool, or the timeout elapses. Returns the last-seen server
+     * entry (possibly not-yet-connected) so the caller can decide how to proceed.
+     *
+     * Bounded by `timeoutMs` via the loop condition — it cannot run indefinitely.
+     */
+    async waitForMCPServer(neurolink, name, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        let last;
+        while (Date.now() < deadline) {
+            const servers = await neurolink
+                .listMCPServers()
+                .catch(() => []);
+            last = (servers || []).find((server) => server.name === name);
+            if (last?.status === "connected" && (last.tools?.length ?? 0) > 0) {
+                return last;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+        return last;
+    }
+    /**
+     * Build the remote HTTP GitHub MCP registration (default path).
+     * A Bearer token is required for the hosted endpoint.
+     */
+    buildGitHubHttpConfig(githubConfig, ghToken, blockedTools) {
+        if (!ghToken) {
+            throw new MCPServerError("GitHub remote HTTP MCP server requires a token. Set GITHUB_TOKEN " +
+                "(or GH_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN / GITHUB_ACCESS_TOKEN); " +
+                "'gh auth login' alone is not sufficient for the remote transport.");
+        }
+        // The hosted endpoint is slow to connect (~3-4s TLS handshake + remote auth);
+        // a generous timeout + retry/backoff prevents spurious "not connected"
+        // failures. Values mirror Curator's production GitHub MCP registration.
+        return {
+            transport: "http",
+            url: githubConfig?.url ?? DEFAULT_GITHUB_MCP_URL,
+            headers: {
+                Authorization: `Bearer ${ghToken}`,
+            },
+            blockedTools,
+            timeout: 30000,
+            retryConfig: {
+                maxAttempts: 3,
+                initialDelay: 1000,
+                maxDelay: 10000,
+                backoffMultiplier: 2,
+            },
+        };
+    }
+    /**
+     * Build a self-hosted / Docker stdio GitHub MCP registration.
+     * Only used when `mcpServers.github.transport === "stdio"`; requires `command`.
+     */
+    buildGitHubStdioConfig(githubConfig, ghToken, blockedTools) {
+        const command = githubConfig?.command;
+        if (!command) {
+            throw new MCPServerError("GitHub stdio transport requires 'mcpServers.github.command' " +
+                "(e.g. a self-hosted/Docker GitHub MCP server binary).");
+        }
+        return {
+            transport: "stdio",
+            command,
+            args: githubConfig?.args ?? [],
+            env: ghToken
+                ? {
+                    GITHUB_PERSONAL_ACCESS_TOKEN: ghToken,
+                    GITHUB_TOKEN: ghToken,
+                }
+                : undefined,
+            blockedTools,
+        };
+    }
     /**
      * Setup Jira MCP server (hardcoded, optionally enabled)
      */

package/dist/v2/core/YamaV2Orchestrator.d.ts

@@ -16,16 +16,18 @@ export declare class YamaOrchestrator {
     private config;
     private initialized;
     private mcpInitialized;
+    private mcpProvider;
     private localGitMcpInitialized;
     private exploreToolRegistered;
     private currentToolContext;
     private initOptions;
     private bootstrapStandardsCache;
+    private detectedProvider;
     constructor(options?: YamaInitOptions);
     /**
      * Initialize Yama with configuration and MCP servers
      */
-    initialize(configPath?: string, mode?: ReviewMode): Promise<void>;
+    initialize(configPath?: string, mode?: ReviewMode, request?: ReviewRequest): Promise<void>;
     /**
      * Start autonomous AI review
      */
@@ -97,6 +99,23 @@ export declare class YamaOrchestrator {
      * Calculate statistics from session
      */
     private calculateStatistics;
+    /**
+     * Count the changed files actually reviewed, from the session tool calls.
+     *
+     * Bitbucket: get_pull_request_diff is called once per file by design, so the
+     * raw count of diff-tool calls already equals the files reviewed. This path is
+     * byte-for-byte identical to the previous behaviour.
+     *
+     * GitHub: pull_request_read is overloaded — the SAME tool name serves
+     * method="get" (PR shell), "get_files" (changed-file list) and "get_diff"
+     * (unified diff). Counting every pull_request_read call therefore inflates the
+     * number. Instead, count DISTINCT file paths the review actually touched, taken
+     * from the inline pending-review comments (add_comment_to_pending_review →
+     * args.path). Fall back to the number of distinct get_files/get_diff reads when
+     * no inline comments were posted (e.g. a clean approval), so a reviewed-but-
+     * clean PR is not reported as 0 files.
+     */
+    private countFilesReviewed;
     /**
      * Extract issue counts from comment tool calls
      */