switch to http mcp

.husky/pre-commit

@@ -8,5 +8,5 @@ if git diff --cached --name-only | grep -q "^package.json$"; then
     pnpm build
 
     # Add the built files and lockfile to the commit
-    git add entry mcp-server pnpm-lock.yaml
+    git add entry pnpm-lock.yaml
 fi

agents/claude.ts

@@ -6,7 +6,6 @@ import { agent, installFromNpmTarball } from "./shared.ts";
 
 export const claude = agent({
   name: "claude",
-  inputKeys: ["anthropic_api_key"],
   install: async () => {
     const versionRange = packageJson.dependencies["@anthropic-ai/claude-agent-sdk"] || "latest";
     return await installFromNpmTarball({
@@ -19,6 +18,7 @@ export const claude = agent({
     process.env.ANTHROPIC_API_KEY = apiKey;
 
     const prompt = addInstructions(payload);
+    console.log(prompt);
 
     const queryInstance = query({
       prompt,
@@ -62,37 +62,15 @@ const messageHandlers: SDKMessageHandlers = {
         if (content.type === "text" && content.text?.trim()) {
           log.box(content.text.trim(), { title: "Claude" });
         } else if (content.type === "tool_use") {
-          log.info(`→ ${content.name}`);
-
           // Track bash tool IDs
           if (content.name === "bash" && content.id) {
             bashToolIds.add(content.id);
           }
 
-          if (content.input) {
-            const input = content.input as any;
-            if (input.description) log.info(`   └─ ${input.description}`);
-            if (input.command) log.info(`   └─ command: ${input.command}`);
-            if (input.file_path) log.info(`   └─ file: ${input.file_path}`);
-            if (input.content) {
-              const preview =
-                input.content.length > 100
-                  ? `${input.content.substring(0, 100)}...`
-                  : input.content;
-              log.info(`   └─ content: ${preview}`);
-            }
-            if (input.query) log.info(`   └─ query: ${input.query}`);
-            if (input.pattern) log.info(`   └─ pattern: ${input.pattern}`);
-            if (input.url) log.info(`   └─ url: ${input.url}`);
-            if (input.edits && Array.isArray(input.edits)) {
-              log.info(`   └─ edits: ${input.edits.length} changes`);
-              input.edits.forEach((edit: any, index: number) => {
-                if (edit.file_path) log.info(`      ${index + 1}. ${edit.file_path}`);
-              });
-            }
-            if (input.task) log.info(`   └─ task: ${input.task}`);
-            if (input.bash_command) log.info(`   └─ bash_command: ${input.bash_command}`);
-          }
+          log.toolCall({
+            toolName: content.name,
+            input: content.input,
+          });
         }
       }
     }

agents/codex.ts

@@ -1,4 +1,6 @@
 import { spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { Codex, type CodexOptions, type ThreadEvent } from "@openai/codex-sdk";
 import { log } from "../utils/cli.ts";
 import { addInstructions } from "./instructions.ts";
@@ -6,7 +8,6 @@ import { agent, type ConfigureMcpServersParams, installFromNpmTarball } from "./
 
 export const codex = agent({
   name: "codex",
-  inputKeys: ["openai_api_key"],
   install: async () => {
     return await installFromNpmTarball({
       packageName: "@openai/codex",
@@ -18,6 +19,13 @@ export const codex = agent({
     process.env.OPENAI_API_KEY = apiKey;
     process.env.GITHUB_INSTALLATION_TOKEN = githubInstallationToken;
 
+    // create config directory for codex before setting HOME
+    const tempHome = process.env.PULLFROG_TEMP_DIR!;
+    const configDir = join(tempHome, ".config", "codex");
+    mkdirSync(configDir, { recursive: true });
+
+    process.env.HOME = tempHome;
+
     configureCodexMcpServers({ mcpServers, cliPath });
 
     // Configure Codex
@@ -45,6 +53,7 @@ export const codex = agent({
       let finalOutput = "";
       for await (const event of streamedTurn.events) {
         const handler = messageHandlers[event.type];
+        log.debug(JSON.stringify(event, null, 2));
         if (handler) {
           handler(event as never);
         }
@@ -107,12 +116,21 @@ const messageHandlers: {
   "item.started": (event) => {
     const item = event.item;
     if (item.type === "command_execution") {
-      log.info(`→ ${item.command}`);
       commandExecutionIds.add(item.id);
+      log.toolCall({
+        toolName: item.command,
+        input: (item as any).args || {},
+      });
     } else if (item.type === "agent_message") {
       // Will be handled on completion
     } else if (item.type === "mcp_tool_call") {
-      log.info(`→ ${item.tool} (${item.server})`);
+      log.toolCall({
+        toolName: item.tool,
+        input: {
+          server: item.server,
+          ...((item as any).arguments || {}),
+        },
+      });
     }
     // Reasoning items are handled on completion for better readability
   },
@@ -149,7 +167,7 @@ const messageHandlers: {
       const reasoningText = item.text.trim();
       // Remove markdown bold markers if present for cleaner output
       const cleanText = reasoningText.replace(/\*\*/g, "");
-      log.info(cleanText);
+      log.box(cleanText, { title: "Codex" });
     }
   },
   error: (event) => {
@@ -159,34 +177,30 @@ const messageHandlers: {
 
 /**
  * Configure MCP servers for Codex using the CLI.
- * Codex CLI syntax: codex mcp add <name> --env KEY=value -- <command> [args...]
+ * For HTTP-based servers, use: codex mcp add <name> --url <url>
  */
 function configureCodexMcpServers({ mcpServers, cliPath }: ConfigureMcpServersParams): void {
   for (const [serverName, serverConfig] of Object.entries(mcpServers)) {
-    const command = serverConfig.command;
-    const args = serverConfig.args || [];
-    const envVars = serverConfig.env || {};
+    if (serverConfig.type === "http") {
+      // HTTP-based MCP server - use --url flag
+      const addArgs = ["mcp", "add", serverName, "--url", serverConfig.url];
 
-    const addArgs = ["mcp", "add", serverName];
+      log.info(`Adding MCP server '${serverName}' at ${serverConfig.url}...`);
+      const addResult = spawnSync("node", [cliPath, ...addArgs], {
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
 
-    // Add environment variables as --env flags first
-    for (const [key, value] of Object.entries(envVars)) {
-      addArgs.push("--env", `${key}=${value}`);
-    }
-
-    addArgs.push("--", command, ...args);
-
-    log.info(`Adding MCP server '${serverName}'...`);
-    const addResult = spawnSync("node", [cliPath, ...addArgs], {
-      stdio: "pipe",
-      encoding: "utf-8",
-    });
-
-    if (addResult.status !== 0) {
+      if (addResult.status !== 0) {
+        throw new Error(
+          `codex mcp add failed: ${addResult.stderr || addResult.stdout || "Unknown error"}`
+        );
+      }
+      log.info(`✓ MCP server '${serverName}' configured`);
+    } else {
       throw new Error(
-        `codex mcp add failed: ${addResult.stderr || addResult.stdout || "Unknown error"}`
+        `Unsupported MCP server type for Codex: ${(serverConfig as any).type || "unknown"}`
       );
     }
-    log.info(`✓ MCP server '${serverName}' configured`);
   }
 }

agents/cursor.ts

@@ -1,13 +1,137 @@
 import { spawn } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { log } from "../utils/cli.ts";
 import { addInstructions } from "./instructions.ts";
 import { agent, type ConfigureMcpServersParams, installFromCurl } from "./shared.ts";
 
+// cursor cli event types inferred from stream-json output
+interface CursorSystemEvent {
+  type: "system";
+  subtype?: string;
+  [key: string]: unknown;
+}
+
+interface CursorUserEvent {
+  type: "user";
+  message?: {
+    role: string;
+    content: Array<{ type: string; text?: string }>;
+  };
+  [key: string]: unknown;
+}
+
+interface CursorThinkingEvent {
+  type: "thinking";
+  subtype: "delta" | "completed";
+  text?: string;
+  [key: string]: unknown;
+}
+
+interface CursorAssistantEvent {
+  type: "assistant";
+  model_call_id?: string;
+  message?: {
+    role: string;
+    content: Array<{ type: string; text?: string }>;
+  };
+  [key: string]: unknown;
+}
+
+interface CursorToolCallEvent {
+  type: "tool_call";
+  subtype: "started" | "completed";
+  call_id?: string;
+  tool_call?: {
+    mcpToolCall?: {
+      args?: {
+        name?: string;
+        args?: unknown;
+        toolName?: string;
+        providerIdentifier?: string;
+      };
+      result?: {
+        success?: {
+          content?: Array<{ text?: { text?: string } }>;
+          isError?: boolean;
+        };
+      };
+    };
+  };
+  [key: string]: unknown;
+}
+
+interface CursorResultEvent {
+  type: "result";
+  subtype: "success" | "error";
+  result?: string;
+  duration_ms?: number;
+  [key: string]: unknown;
+}
+
+type CursorEvent =
+  | CursorSystemEvent
+  | CursorUserEvent
+  | CursorThinkingEvent
+  | CursorAssistantEvent
+  | CursorToolCallEvent
+  | CursorResultEvent;
+
+const messageHandlers = {
+  system: (_event: CursorSystemEvent) => {
+    // system init events - no logging needed
+  },
+  user: (_event: CursorUserEvent) => {
+    // user messages already logged in prompt box
+  },
+  thinking: (_event: CursorThinkingEvent) => {
+    // thinking events are internal - no logging needed
+  },
+  assistant: (event: CursorAssistantEvent) => {
+    // only log finalized messages (ones with model_call_id)
+    // cursor emits each message twice: once without model_call_id, then again with it
+    if (event.model_call_id) {
+      const text = event.message?.content?.[0]?.text;
+      if (text?.trim()) {
+        log.box(text.trim(), { title: "Cursor" });
+      }
+    }
+  },
+  tool_call: (event: CursorToolCallEvent) => {
+    if (event.subtype === "started") {
+      // handle both MCP tools and built-in tools (bash, WebFetch, etc)
+      const mcpToolCall = event.tool_call?.mcpToolCall;
+      const builtinToolCall = (event.tool_call as any)?.builtinToolCall;
+
+      if (mcpToolCall?.args?.toolName && mcpToolCall?.args?.args) {
+        log.toolCall({
+          toolName: mcpToolCall.args.toolName,
+          input: mcpToolCall.args.args,
+        });
+      } else if (builtinToolCall?.args?.name && builtinToolCall?.args?.args) {
+        log.toolCall({
+          toolName: builtinToolCall.args.name,
+          input: builtinToolCall.args.args,
+        });
+      }
+    } else if (event.subtype === "completed") {
+      const isError = event.tool_call?.mcpToolCall?.result?.success?.isError;
+      if (isError) {
+        log.warning("Tool call failed");
+      }
+    }
+  },
+  result: async (event: CursorResultEvent) => {
+    if (event.subtype === "success" && event.duration_ms) {
+      const durationSec = (event.duration_ms / 1000).toFixed(1);
+      log.debug(`Cursor completed in ${durationSec}s`);
+    }
+  },
+};
+
 export const cursor = agent({
   name: "cursor",
-  inputKeys: ["cursor_api_key"],
   install: async () => {
     return await installFromCurl({
       installUrl: "https://cursor.com/install",
@@ -21,29 +145,35 @@ export const cursor = agent({
     configureCursorMcpServers({ mcpServers, cliPath });
 
     try {
-      // Run cursor-agent in non-interactive mode with the prompt
-      // Using -p flag for prompt, --output-format text for plain text output
-      // and --approve-mcps to automatically approve all MCP servers
       const fullPrompt = addInstructions(payload);
 
-      // Find temp directory from cliPath to set HOME for MCP config lookup
-      const tempDir = cliPath.split("/.local/bin/")[0];
-
       log.info("Running Cursor CLI...");
 
-      // Use spawn to handle streaming output
-      // Use --print flag explicitly for non-interactive mode
+      const startTime = Date.now();
+
       return new Promise((resolve) => {
         const child = spawn(
           cliPath,
-          ["--print", fullPrompt, "--output-format", "text", "--approve-mcps", "--force"],
+          [
+            "--print",
+            fullPrompt,
+            "--output-format",
+            "stream-json",
+            "--stream-partial-output",
+            "--approve-mcps",
+            "--force",
+          ],
           {
-            cwd: process.cwd(), // Run in current working directory
+            cwd: process.cwd(),
             env: {
-              ...process.env,
               CURSOR_API_KEY: apiKey,
               GITHUB_INSTALLATION_TOKEN: githubInstallationToken,
-              HOME: tempDir, // Set HOME so Cursor CLI can find .cursor/mcp.json
+              LOG_LEVEL: process.env.LOG_LEVEL,
+              NODE_ENV: process.env.NODE_ENV,
+              HOME: process.env.HOME,
+              PATH: process.env.PATH,
+              // Don't override HOME - Cursor CLI needs access to macOS keychain
+              // MCP config is written to tempDir/.cursor/mcp.json which Cursor will find
             },
             stdio: ["ignore", "pipe", "pipe"], // Ignore stdin, pipe stdout/stderr
           }
@@ -52,41 +182,54 @@ export const cursor = agent({
         let stdout = "";
         let stderr = "";
 
-        // Log when process starts
         child.on("spawn", () => {
           log.debug("Cursor CLI process spawned");
         });
 
-        child.stdout?.on("data", (data) => {
+        child.stdout?.on("data", async (data) => {
           const text = data.toString();
           stdout += text;
-          // Stream output in real-time
-          process.stdout.write(text);
+
+          try {
+            const event = JSON.parse(text) as CursorEvent;
+
+            // route to appropriate handler
+            const handler = messageHandlers[event.type as keyof typeof messageHandlers];
+            if (handler) {
+              await handler(event as never);
+            }
+
+            // debug: log all events
+            log.debug(`[cursor event] ${JSON.stringify(event, null, 2)}`);
+          } catch {
+            // ignore parse errors - might be formatted tool call logs from cursor cli
+            // our handlers log tool calls instead, so we don't need to display these
+          }
         });
 
         child.stderr?.on("data", (data) => {
           const text = data.toString();
           stderr += text;
-          // Log errors as they come - but also write to stdout so we can see it
           process.stderr.write(text);
           log.warning(text);
         });
 
-        // Handle process exit
-        child.on("close", (code, signal) => {
+        child.on("close", async (code, signal) => {
           if (signal) {
             log.warning(`Cursor CLI terminated by signal: ${signal}`);
           }
 
+          const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
           if (code === 0) {
-            log.success("Cursor CLI completed successfully");
+            log.success(`Cursor CLI completed successfully in ${duration}s`);
             resolve({
               success: true,
               output: stdout.trim(),
             });
           } else {
             const errorMessage = stderr || `Cursor CLI exited with code ${code}`;
-            log.error(`Cursor CLI failed: ${errorMessage}`);
+            log.error(`Cursor CLI failed after ${duration}s: ${errorMessage}`);
             resolve({
               success: false,
               error: errorMessage,
@@ -96,8 +239,9 @@ export const cursor = agent({
         });
 
         child.on("error", (error) => {
+          const duration = ((Date.now() - startTime) / 1000).toFixed(1);
           const errorMessage = error.message || String(error);
-          log.error(`Cursor CLI execution failed: ${errorMessage}`);
+          log.error(`Cursor CLI execution failed after ${duration}s: ${errorMessage}`);
           resolve({
             success: false,
             error: errorMessage,
@@ -117,14 +261,30 @@ export const cursor = agent({
   },
 });
 
-/**
- * Configure MCP servers for Cursor by writing to the Cursor configuration file.
- * For cursor, we need to add the MCP servers to the Cursor configuration file manually as there is no CLI command to do this.
- */
-function configureCursorMcpServers({ mcpServers, cliPath }: ConfigureMcpServersParams) {
-  const tempDir = cliPath.split("/.local/bin/")[0];
-  const cursorConfigDir = join(tempDir, ".cursor");
+// There was an issue on macOS when you set HOME to a temp directory
+// it was unable to find the macOS keychain and would fail
+// temp solution is to stick with the actual $HOME
+function configureCursorMcpServers({ mcpServers }: ConfigureMcpServersParams) {
+  const realHome = homedir();
+  const cursorConfigDir = join(realHome, ".cursor");
   const mcpConfigPath = join(cursorConfigDir, "mcp.json");
   mkdirSync(cursorConfigDir, { recursive: true });
-  writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers }, null, 2), "utf-8");
+
+  // Convert to Cursor's expected format (HTTP config)
+  const cursorMcpServers: Record<string, { type: string; url: string }> = {};
+  for (const [serverName, serverConfig] of Object.entries(mcpServers)) {
+    if (serverConfig.type !== "http") {
+      throw new Error(
+        `Unsupported MCP server type for Cursor: ${(serverConfig as any).type || "unknown"}`
+      );
+    }
+
+    cursorMcpServers[serverName] = {
+      type: "http",
+      url: serverConfig.url,
+    };
+  }
+
+  writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers: cursorMcpServers }, null, 2), "utf-8");
+  log.info(`MCP config written to ${mcpConfigPath}`);
 }

agents/gemini.ts

@@ -2,17 +2,154 @@ import { spawnSync } from "node:child_process";
 import { log } from "../utils/cli.ts";
 import { spawn } from "../utils/subprocess.ts";
 import { addInstructions } from "./instructions.ts";
-import { agent, type ConfigureMcpServersParams, installFromNpmTarball } from "./shared.ts";
+import { agent, type ConfigureMcpServersParams, installFromGithub } from "./shared.ts";
+
+// gemini cli event types inferred from stream-json output (NDJSON format)
+interface GeminiInitEvent {
+  type: "init";
+  timestamp?: string;
+  session_id?: string;
+  model?: string;
+  [key: string]: unknown;
+}
+
+interface GeminiMessageEvent {
+  type: "message";
+  timestamp?: string;
+  role?: "user" | "assistant";
+  content?: string;
+  delta?: boolean;
+  [key: string]: unknown;
+}
+
+interface GeminiToolUseEvent {
+  type: "tool_use";
+  timestamp?: string;
+  tool_name?: string;
+  tool_id?: string;
+  parameters?: unknown;
+  [key: string]: unknown;
+}
+
+interface GeminiToolResultEvent {
+  type: "tool_result";
+  timestamp?: string;
+  tool_id?: string;
+  status?: "success" | "error";
+  output?: string;
+  [key: string]: unknown;
+}
+
+interface GeminiResultEvent {
+  type: "result";
+  timestamp?: string;
+  status?: "success" | "error";
+  stats?: {
+    total_tokens?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    duration_ms?: number;
+    tool_calls?: number;
+  };
+  [key: string]: unknown;
+}
+
+type GeminiEvent =
+  | GeminiInitEvent
+  | GeminiMessageEvent
+  | GeminiToolUseEvent
+  | GeminiToolResultEvent
+  | GeminiResultEvent;
+
+let assistantMessageBuffer = "";
+
+const messageHandlers = {
+  init: (_event: GeminiInitEvent) => {
+    // initialization event - no logging needed
+    assistantMessageBuffer = "";
+  },
+  message: (event: GeminiMessageEvent) => {
+    if (event.role === "assistant" && event.content?.trim()) {
+      if (event.delta) {
+        // accumulate delta messages
+        assistantMessageBuffer += event.content;
+      } else {
+        // final message - log it
+        const message = event.content.trim();
+        if (message) {
+          log.box(message, { title: "Gemini" });
+        }
+        assistantMessageBuffer = "";
+      }
+    } else if (event.role === "assistant" && !event.delta && assistantMessageBuffer.trim()) {
+      // if we have buffered content and get a non-delta message, log the buffer
+      log.box(assistantMessageBuffer.trim(), { title: "Gemini" });
+      assistantMessageBuffer = "";
+    }
+  },
+  tool_use: (event: GeminiToolUseEvent) => {
+    if (event.tool_name) {
+      // log intent for create_working_comment
+      if (event.tool_name === "create_working_comment" && event.parameters) {
+        const params = event.parameters as { intent?: string; [key: string]: unknown };
+        if (params.intent) {
+          log.box(params.intent.trim(), { title: "Intent" });
+        }
+      }
+
+      log.toolCall({
+        toolName: event.tool_name,
+        input: event.parameters || {},
+      });
+    }
+  },
+  tool_result: (event: GeminiToolResultEvent) => {
+    if (event.status === "error") {
+      const errorMsg =
+        typeof event.output === "string" ? event.output : JSON.stringify(event.output);
+      log.warning(`Tool call failed: ${errorMsg}`);
+    }
+  },
+  result: async (event: GeminiResultEvent) => {
+    // log any remaining buffered assistant message
+    if (assistantMessageBuffer.trim()) {
+      log.box(assistantMessageBuffer.trim(), { title: "Gemini" });
+      assistantMessageBuffer = "";
+    }
+
+    if (event.status === "success" && event.stats) {
+      const stats = event.stats;
+      const rows: Array<Array<{ data: string; header?: boolean } | string>> = [
+        [
+          { data: "Input Tokens", header: true },
+          { data: "Output Tokens", header: true },
+          { data: "Total Tokens", header: true },
+          { data: "Tool Calls", header: true },
+          { data: "Duration (ms)", header: true },
+        ],
+        [
+          String(stats.input_tokens || 0),
+          String(stats.output_tokens || 0),
+          String(stats.total_tokens || 0),
+          String(stats.tool_calls || 0),
+          String(stats.duration_ms || 0),
+        ],
+      ];
+      await log.summaryTable(rows);
+    } else if (event.status === "error") {
+      log.error(`Gemini CLI failed: ${JSON.stringify(event)}`);
+    }
+  },
+};
 
 export const gemini = agent({
   name: "gemini",
-  inputKeys: ["google_api_key", "gemini_api_key"],
   install: async () => {
-    return await installFromNpmTarball({
-      packageName: "@google/gemini-cli",
-      version: "latest",
-      executablePath: "dist/index.js",
-      installDependencies: true,
+    return await installFromGithub({
+      owner: "google-gemini",
+      repo: "gemini-cli",
+      tag: "v0.16.0",
+      assetName: "gemini.js",
     });
   },
   run: async ({ payload, apiKey, mcpServers, githubInstallationToken, cliPath }) => {
@@ -32,21 +169,45 @@ export const gemini = agent({
     try {
       const result = await spawn({
         cmd: "node",
-        args: [cliPath, "--yolo", "--output-format", "text", sessionPrompt],
+        args: [cliPath, "--yolo", "--output-format=stream-json", "-p", sessionPrompt],
         env: {
+          PATH: process.env.PATH || "",
+          HOME: process.env.HOME || "",
+          TMPDIR: process.env.TMPDIR || "/tmp",
           GEMINI_API_KEY: apiKey,
           GITHUB_INSTALLATION_TOKEN: githubInstallationToken,
+          LOG_LEVEL: process.env.LOG_LEVEL!,
+          NODE_ENV: process.env.NODE_ENV!,
         },
-        onStdout: (chunk) => {
-          const trimmed = chunk.trim();
-          if (trimmed) {
-            log.info(trimmed);
-            finalOutput += trimmed + "\n";
+        timeout: 600000, // 10 minutes
+        onStdout: async (chunk) => {
+          const text = chunk.toString();
+          finalOutput += text;
+
+          // parse each line as JSON (gemini cli outputs one JSON object per line)
+          const lines = text.split("\n");
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+
+            log.debug(`[gemini stdout] ${trimmed}`);
+
+            try {
+              const event = JSON.parse(trimmed) as GeminiEvent;
+              const handler = messageHandlers[event.type as keyof typeof messageHandlers];
+              if (handler) {
+                await handler(event as never);
+              }
+            } catch {
+              console.log("parse error", trimmed);
+              // ignore parse errors - might be non-JSON output from gemini cli
+            }
           }
         },
         onStderr: (chunk) => {
           const trimmed = chunk.trim();
           if (trimmed) {
+            log.debug(`[gemini stderr] ${trimmed}`);
             log.warning(trimmed);
             finalOutput += trimmed + "\n";
           }
@@ -54,7 +215,11 @@ export const gemini = agent({
       });
 
       if (result.exitCode !== 0) {
-        const errorMessage = result.stderr || result.stdout || "Unknown error";
+        const errorMessage =
+          result.stderr ||
+          finalOutput ||
+          result.stdout ||
+          "Unknown error - no output from Gemini CLI";
         log.error(`Gemini CLI exited with code ${result.exitCode}: ${errorMessage}`);
         return {
           success: false,
@@ -84,32 +249,31 @@ export const gemini = agent({
 
 /**
  * Configure MCP servers for Gemini using the CLI.
- * Gemini CLI syntax: gemini mcp add <name> <commandOrUrl> [args...] --env KEY=value
+ * Gemini CLI syntax: gemini mcp add <name> <commandOrUrl> [args...] --transport <type>
+ * For HTTP-based servers, use: gemini mcp add <name> <url> --transport http
  */
 function configureGeminiMcpServers({ mcpServers, cliPath }: ConfigureMcpServersParams): void {
   for (const [serverName, serverConfig] of Object.entries(mcpServers)) {
-    const command = serverConfig.command;
-    const args = serverConfig.args || [];
-    const envVars = serverConfig.env || {};
+    if (serverConfig.type === "http") {
+      // HTTP-based MCP server - use URL with --transport http flag
+      const addArgs = ["mcp", "add", serverName, serverConfig.url, "--transport", "http"];
 
-    const addArgs = ["mcp", "add", serverName, command, ...args];
+      log.info(`Adding MCP server '${serverName}' at ${serverConfig.url}...`);
+      const addResult = spawnSync("node", [cliPath, ...addArgs], {
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
 
-    // Add environment variables as --env flags
-    for (const [key, value] of Object.entries(envVars)) {
-      addArgs.push("--env", `${key}=${value}`);
-    }
-
-    log.info(`Adding MCP server '${serverName}'...`);
-    const addResult = spawnSync("node", [cliPath, ...addArgs], {
-      stdio: "pipe",
-      encoding: "utf-8",
-    });
-
-    if (addResult.status !== 0) {
+      if (addResult.status !== 0) {
+        throw new Error(
+          `gemini mcp add failed: ${addResult.stderr || addResult.stdout || "Unknown error"}`
+        );
+      }
+      log.info(`✓ MCP server '${serverName}' configured`);
+    } else {
       throw new Error(
-        `gemini mcp add failed: ${addResult.stderr || addResult.stdout || "Unknown error"}`
+        `Unsupported MCP server type for Gemini: ${(serverConfig as any).type || "unknown"}`
       );
     }
-    log.info(`✓ MCP server '${serverName}' configured`);
   }
 }

agents/index.ts

@@ -1,13 +1,13 @@
+import type { AgentName } from "../external.ts";
 import { claude } from "./claude.ts";
 import { codex } from "./codex.ts";
 import { cursor } from "./cursor.ts";
 import { gemini } from "./gemini.ts";
+import type { Agent } from "./shared.ts";
 
 export const agents = {
   claude,
   codex,
   cursor,
   gemini,
-} as const;
-
-export type AgentInputKey = (typeof agents)[keyof typeof agents]["inputKeys"][number];
+} satisfies Record<AgentName, Agent>;

agents/instructions.ts

@@ -1,5 +1,6 @@
+import { encode as toonEncode } from "@toon-format/toon";
 import type { Payload } from "../external.ts";
-import { ghPullfrogMcpName } from "../mcp/index.ts";
+import { ghPullfrogMcpName } from "../external.ts";
 import { modes } from "../modes.ts";
 
 export const addInstructions = (payload: Payload) =>
@@ -15,6 +16,8 @@ You do not add unecessary comments, tests, or documentation unless explicitly pr
 You adapt your writing style to the style of your coworkers, while never being unprofessional.
 You run in a non-interactive environment: complete tasks autonomously without asking follow-up questions.
 You make reasonable assumptions when details are missing, but fail with an explicit error if critical information is missing (e.g. user asks to review a PR but does not provide a link or ID).
+Never push commits directly to protected branches: main, master, production. Always create a feature branch. All created branches must be prefixed with "pullfrog/" and have VERY specific names in order to avoid collisions.
+Never add co-author trailers (e.g., "Co-authored-by" or "Co-Authored-By") to commit messages. Commits should only include the commit message itself, without any co-author attribution.
 
 ## SECURITY
 
@@ -62,4 +65,4 @@ ${[...modes, ...payload.modes].map((w) => `    - "${w.name}": ${w.description}`)
 
 ${payload.prompt}
 
-${JSON.stringify(payload.event, null, 2)}`;
+${toonEncode(payload.event)}`;

agents/shared.ts

@@ -1,9 +1,12 @@
 import { spawnSync } from "node:child_process";
 import { chmodSync, createWriteStream, existsSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pipeline } from "node:stream/promises";
-import type { McpStdioServerConfig } from "@anthropic-ai/claude-agent-sdk";
-import type { Payload } from "../external.ts";
+import type { McpHttpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import type { show } from "@ark/util";
+import { type AgentManifest, type AgentName, agentsManifest, type Payload } from "../external.ts";
 import { log } from "../utils/cli.ts";
 
 /**
@@ -11,8 +14,8 @@ import { log } from "../utils/cli.ts";
  */
 export interface AgentResult {
   success: boolean;
-  output?: string;
-  error?: string;
+  output?: string | undefined;
+  error?: string | undefined;
   metadata?: Record<string, unknown>;
 }
 
@@ -23,7 +26,7 @@ export interface AgentConfig {
   apiKey: string;
   githubInstallationToken: string;
   payload: Payload;
-  mcpServers: Record<string, McpStdioServerConfig>;
+  mcpServers: Record<string, McpHttpServerConfig>;
   cliPath: string;
 }
 
@@ -31,7 +34,7 @@ export interface AgentConfig {
  * Parameters for configuring MCP servers
  */
 export interface ConfigureMcpServersParams {
-  mcpServers: Record<string, McpStdioServerConfig>;
+  mcpServers: Record<string, McpHttpServerConfig>;
   cliPath: string;
 }
 
@@ -53,6 +56,17 @@ export interface InstallFromCurlParams {
   executableName: string;
 }
 
+/**
+ * Parameters for installing from GitHub releases
+ */
+export interface InstallFromGithubParams {
+  owner: string;
+  repo: string;
+  tag?: string;
+  assetName?: string;
+  executablePath?: string;
+}
+
 /**
  * NPM registry response data structure
  */
@@ -166,6 +180,91 @@ export async function installFromNpmTarball({
   return cliPath;
 }
 
+/**
+ * Install a CLI tool from GitHub releases
+ * Downloads the latest release asset from GitHub and returns the path to the executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export async function installFromGithub({
+  owner,
+  repo,
+  tag,
+  assetName,
+  executablePath,
+}: InstallFromGithubParams): Promise<string> {
+  log.info(`📦 Installing ${owner}/${repo} from GitHub releases...`);
+
+  // fetch release from GitHub API (specific tag or latest)
+  const releaseUrl = tag
+    ? `https://api.github.com/repos/${owner}/${repo}/releases/tags/${tag}`
+    : `https://api.github.com/repos/${owner}/${repo}/releases/latest`;
+  log.info(`Fetching release from ${releaseUrl}...`);
+  const releaseResponse = await fetch(releaseUrl);
+  if (!releaseResponse.ok) {
+    throw new Error(
+      `Failed to fetch release: ${releaseResponse.status} ${releaseResponse.statusText}`
+    );
+  }
+
+  const releaseData = (await releaseResponse.json()) as {
+    tag_name: string;
+    assets: Array<{
+      name: string;
+      browser_download_url: string;
+    }>;
+  };
+
+  log.info(`Found release: ${releaseData.tag_name}`);
+
+  const asset = releaseData.assets.find((a) => a.name === assetName);
+  if (!asset) {
+    throw new Error(`Asset '${assetName}' not found in release ${releaseData.tag_name}`);
+  }
+  const assetUrl = asset.browser_download_url;
+
+  log.info(`Downloading asset from ${assetUrl}...`);
+
+  // create temp directory
+  const tempDirPrefix = `${owner}-${repo}-github-`;
+  const tempDir = await mkdtemp(join(tmpdir(), tempDirPrefix));
+
+  // determine file extension and download path
+  const urlPath = new URL(assetUrl).pathname;
+  const fileName = urlPath.split("/").pop() || "asset";
+  const downloadPath = join(tempDir, fileName);
+
+  // download the asset
+  const assetResponse = await fetch(assetUrl);
+  if (!assetResponse.ok) {
+    throw new Error(
+      `Failed to download asset: ${assetResponse.status} ${assetResponse.statusText}`
+    );
+  }
+
+  if (!assetResponse.body) throw new Error("Response body is null");
+  const fileStream = createWriteStream(downloadPath);
+  await pipeline(assetResponse.body, fileStream);
+  log.info(`Downloaded asset to ${downloadPath}`);
+
+  // determine the executable path
+  let cliPath: string;
+  if (executablePath) {
+    cliPath = join(tempDir, executablePath);
+  } else {
+    // no executablePath, assume the downloaded file is the executable
+    cliPath = downloadPath;
+  }
+
+  if (!existsSync(cliPath)) {
+    throw new Error(`Executable not found at ${cliPath}`);
+  }
+
+  chmodSync(cliPath, 0o755);
+  log.info(`✓ Installed from GitHub release at ${cliPath}`);
+
+  return cliPath;
+}
+
 /**
  * Install a CLI tool from a curl-based install script
  * Downloads the install script, runs it with HOME set to temp directory, and returns the path to the CLI executable
@@ -203,8 +302,11 @@ export async function installFromCurl({
   const installResult = spawnSync("bash", [installScriptPath], {
     cwd: tempDir,
     env: {
-      ...process.env,
       HOME: tempDir, // Cursor install script uses HOME for installation path
+      PATH: process.env.PATH || "",
+      SHELL: process.env.SHELL || "/bin/bash",
+      USER: process.env.USER || "",
+      TMPDIR: process.env.TMPDIR || "/tmp",
     },
     stdio: "pipe",
     encoding: "utf-8",
@@ -232,13 +334,18 @@ export async function installFromCurl({
   return cliPath;
 }
 
-export const agent = <const agent extends Agent>(agent: agent): agent => {
-  return agent;
+export const agent = <const input extends AgentInput>(input: input): defineAgent<input> => {
+  return { ...input, ...agentsManifest[input.name] } as never;
 };
 
-export type Agent = {
-  name: string;
-  inputKeys: string[];
+export interface AgentInput {
+  name: AgentName;
   install: () => Promise<string>;
   run: (config: AgentConfig) => Promise<AgentResult>;
-};
+}
+
+export interface Agent extends AgentInput, AgentManifest {}
+
+type agentManifest<name extends AgentName> = (typeof agentsManifest)[name];
+
+type defineAgent<input extends AgentInput> = show<input & agentManifest<input["name"]>>;

entry.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 /**
  * Entry point for GitHub Action
  */
@@ -5,7 +7,7 @@
 import * as core from "@actions/core";
 import { flatMorph } from "@ark/util";
 import { agents } from "./agents/index.ts";
-import { AgentName, type Inputs, main } from "./main.ts";
+import { type Inputs, main } from "./main.ts";
 import { log } from "./utils/cli.ts";
 
 async function run(): Promise<void> {
@@ -20,9 +22,8 @@ async function run(): Promise<void> {
   try {
     const inputs: Required<Inputs> = {
       prompt: core.getInput("prompt", { required: true }),
-      agent: core.getInput("agent") ? AgentName.assert(core.getInput("agent")) : undefined,
       ...flatMorph(agents, (_, agent) =>
-        agent.inputKeys.map((inputKey) => [inputKey, core.getInput(inputKey)])
+        agent.apiKeyNames.map((inputKey) => [inputKey, core.getInput(inputKey)])
       ),
     };
 

esbuild.config.js

@@ -59,7 +59,7 @@ const sharedConfig = {
   drop: [],
 };
 
-// Build the main entry bundle (without MCP)
+// Build the main entry bundle
 await build({
   ...sharedConfig,
   entryPoints: ["./entry.ts"],
@@ -67,12 +67,4 @@ await build({
   plugins: [stripShebangPlugin],
 });
 
-// Build the MCP server bundle
-await build({
-  ...sharedConfig,
-  entryPoints: ["./mcp/server.ts"],
-  outfile: "./mcp-server",
-  plugins: [stripShebangPlugin],
-});
-
 console.log("✅ Build completed successfully!");

external.ts

@@ -1,6 +1,142 @@
-import type { AgentName } from "./main.ts";
+/**
+ * ⚠️ NO IMPORTS except modes.ts - this file is imported by Next.js and must avoid pulling in backend code.
+ * All shared constants, types, and data used by both the Next.js app and the action runtime live here.
+ * Other files in action/ re-export from this file for backward compatibility.
+ */
+
+import { type } from "arktype";
 import type { Mode } from "./modes.ts";
 
+// mcp name constant
+export const ghPullfrogMcpName = "gh_pullfrog";
+
+export interface AgentManifest {
+  displayName: string;
+  apiKeyNames: string[];
+  url: string;
+}
+
+// agent manifest - static metadata about available agents
+export const agentsManifest = {
+  claude: {
+    displayName: "Claude Code",
+    apiKeyNames: ["anthropic_api_key"],
+    url: "https://claude.com/claude-code",
+  },
+  codex: {
+    displayName: "Codex CLI",
+    apiKeyNames: ["openai_api_key"],
+    url: "https://platform.openai.com/docs/guides/codex",
+  },
+  cursor: {
+    displayName: "Cursor CLI",
+    apiKeyNames: ["cursor_api_key"],
+    url: "https://cursor.com/",
+  },
+  gemini: {
+    displayName: "Gemini CLI",
+    apiKeyNames: ["google_api_key", "gemini_api_key"],
+    url: "https://ai.google.dev/gemini-api/docs",
+  },
+} as const satisfies Record<string, AgentManifest>;
+
+// agent name type - union of agent slugs
+export type AgentName = keyof typeof agentsManifest;
+export const AgentName = type.enumerated(...Object.keys(agentsManifest));
+
+export type AgentApiKeyName = (typeof agentsManifest)[AgentName]["apiKeyNames"][number];
+
+// discriminated union for payload event based on trigger
+export type PayloadEvent =
+  | {
+      trigger: "pull_request_opened";
+      pr_number: number;
+      pr_title: string;
+      pr_body: string | null;
+      branch: string;
+      [key: string]: any;
+    }
+  | {
+      trigger: "pull_request_review_requested";
+      pr_number: number;
+      pr_title: string;
+      pr_body: string | null;
+      branch: string;
+      [key: string]: any;
+    }
+  | {
+      trigger: "pull_request_review_submitted";
+      pr_number: number;
+      review_id: number;
+      review_body: string | null;
+      review_state: string;
+      review_comments: any[];
+      context: any;
+      branch: string;
+      [key: string]: any;
+    }
+  | {
+      trigger: "pull_request_review_comment_created";
+      pr_number: number;
+      pr_title: string;
+      comment_id: number;
+      comment_body: string;
+      thread?: any;
+      branch: string;
+      [key: string]: any;
+    }
+  | {
+      trigger: "issues_opened";
+      issue_number: number;
+      issue_title: string;
+      issue_body: string | null;
+      [key: string]: any;
+    }
+  | {
+      trigger: "issues_assigned";
+      issue_number: number;
+      issue_title: string;
+      issue_body: string | null;
+      [key: string]: any;
+    }
+  | {
+      trigger: "issues_labeled";
+      issue_number: number;
+      issue_title: string;
+      issue_body: string | null;
+      [key: string]: any;
+    }
+  | {
+      trigger: "issue_comment_created";
+      comment_id: number;
+      comment_body: string;
+      issue_number: number;
+      branch?: string;
+      [key: string]: any;
+    }
+  | {
+      trigger: "check_suite_completed";
+      pr_number: number;
+      pr_title: string;
+      pr_body: string | null;
+      pull_request: any;
+      branch: string;
+      check_suite: {
+        id: number;
+        head_sha: string;
+        head_branch: string | null;
+        status: string | null;
+        conclusion: string | null;
+        url: string;
+      };
+      [key: string]: any;
+    }
+  | {
+      trigger: "unknown";
+      [key: string]: any;
+    };
+
+// payload type for agent execution
 export type Payload = {
   "~pullfrog": true;
 
@@ -16,8 +152,9 @@ export type Payload = {
 
   /**
    * Event data from webhook payload.
+   * Discriminated union based on trigger field.
    */
-  readonly event: object;
+  readonly event: PayloadEvent;
 
   /**
    * Execution mode configuration

fixtures/basic.txt

@@ -1 +1 @@
-create a comment on https://github.com/pullfrogai/scratch/pull/29 that says ribbit
+use debug_shell_command tool to run 'git status' and explain the result

main.ts

@@ -3,10 +3,14 @@ import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { flatMorph } from "@ark/util";
+import { encode as toonEncode } from "@toon-format/toon";
 import { type } from "arktype";
 import { agents } from "./agents/index.ts";
-import type { Payload } from "./external.ts";
+import type { AgentResult } from "./agents/shared.ts";
+import type { AgentName, AgentName as AgentNameType, Payload } from "./external.ts";
+import { agentsManifest } from "./external.ts";
 import { createMcpConfigs } from "./mcp/config.ts";
+import { startMcpHttpServer } from "./mcp/server.ts";
 import { modes } from "./modes.ts";
 import packageJson from "./package.json" with { type: "json" };
 import { fetchRepoSettings } from "./utils/api.ts";
@@ -17,24 +21,23 @@ import {
   revokeInstallationToken,
   setupGitHubInstallationToken,
 } from "./utils/github.ts";
-import { setupGitAuth, setupGitConfig } from "./utils/setup.ts";
+import { setupGitAuth, setupGitBranch, setupGitConfig } from "./utils/setup.ts";
 
-export const AgentName = type.enumerated(...Object.values(agents).map((agent) => agent.name));
-export type AgentName = typeof AgentName.infer;
+// runtime validation using agents (needed for ArkType)
+// Note: The AgentName type is defined in external.ts, this is the runtime validator
 
 export const AgentInputKey = type.enumerated(
-  ...Object.values(agents).flatMap((agent) => agent.inputKeys)
+  ...Object.values(agents).flatMap((agent) => agent.apiKeyNames)
 );
 export type AgentInputKey = typeof AgentInputKey.infer;
 
 const keyInputDefs = flatMorph(agents, (_, agent) =>
-  agent.inputKeys.map((inputKey) => [inputKey, "string | undefined?"] as const)
+  agent.apiKeyNames.map((inputKey) => [inputKey, "string | undefined?"] as const)
 );
 
 export const Inputs = type({
   prompt: "string",
   ...keyInputDefs,
-  "agent?": AgentName.or("undefined"),
 });
 
 export type Inputs = typeof Inputs.infer;
@@ -46,16 +49,29 @@ export interface MainResult {
 }
 
 export async function main(inputs: Inputs): Promise<MainResult> {
-  const partialCtx = await initializeContext(inputs);
-  const ctx = partialCtx as MainContext;
+  let pollInterval: NodeJS.Timeout | null = null;
+  let mcpServerClose: (() => Promise<void>) | undefined;
+  let githubInstallationToken: string | undefined;
 
   try {
-    await determineAgent(ctx);
-    setupGitAuth(ctx.githubInstallationToken, ctx.repoContext);
+    // parse payload early to extract agent
+    const payload = parsePayload(inputs);
+
+    const partialCtx = await initializeContext(inputs, payload);
+    const ctx = partialCtx as MainContext;
+    githubInstallationToken = ctx.githubInstallationToken;
+
+    setupGitAuth({
+      githubInstallationToken: ctx.githubInstallationToken,
+      repoContext: ctx.repoContext,
+    });
     await setupTempDirectory(ctx);
     setupMcpLogPolling(ctx);
+    pollInterval = ctx.pollInterval;
 
-    ctx.payload = parsePayload(inputs);
+    setupGitBranch(ctx.payload);
+    await startMcpServer(ctx);
+    mcpServerClose = ctx.mcpServerClose;
     setupMcpServers(ctx);
     await installAgentCli(ctx);
     validateApiKey(ctx);
@@ -71,10 +87,38 @@ export async function main(inputs: Inputs): Promise<MainResult> {
       error: errorMessage,
     };
   } finally {
-    await cleanup(partialCtx);
+    if (pollInterval) {
+      clearInterval(pollInterval);
+    }
+    if (mcpServerClose) {
+      await mcpServerClose();
+    }
+    if (githubInstallationToken) {
+      await revokeInstallationToken(githubInstallationToken);
+    }
   }
 }
 
+/**
+ * Get agents that have matching API keys in the inputs
+ */
+function getAvailableAgents(inputs: Inputs): (typeof agents)[AgentNameType][] {
+  return Object.values(agents).filter((agent) =>
+    agent.apiKeyNames.some((inputKey) => inputs[inputKey])
+  );
+}
+
+/**
+ * Get all possible API key names from agentsManifest using flatMorph
+ */
+function getAllPossibleKeyNames(): string[] {
+  return Object.keys(
+    flatMorph(agentsManifest, (_, manifest) =>
+      manifest.apiKeyNames.map((keyName) => [keyName, true] as const)
+    )
+  );
+}
+
 /**
  * Throw an error for missing API key with helpful message linking to repo settings
  */
@@ -82,12 +126,10 @@ function throwMissingApiKeyError({
   agentName,
   inputKeys,
   repoContext,
-  inputs,
 }: {
-  agentName: string;
+  agentName: string | null;
   inputKeys: string[];
   repoContext: RepoContext;
-  inputs: Inputs;
 }): never {
   const apiUrl = process.env.API_URL || "https://pullfrog.ai";
   const settingsUrl = `${apiUrl}/console/${repoContext.owner}/${repoContext.name}`;
@@ -99,12 +141,11 @@ function throwMissingApiKeyError({
   const githubRepoUrl = `https://github.com/${repoContext.owner}/${repoContext.name}`;
   const githubSecretsUrl = `${githubRepoUrl}/settings/secrets/actions`;
 
-  // Find which agents have inputKeys that match the provided inputs
-  const availableAgents = Object.values(agents).filter((agent) =>
-    agent.inputKeys.some((inputKey) => inputs[inputKey])
-  );
-
-  let message = `Pullfrog is configured to use ${agentName}, but the associated API key was not provided.
+  let message = `${
+    agentName === null
+      ? "Pullfrog has no agent configured and no API keys are available in the environment."
+      : `Pullfrog is configured to use ${agentName}, but the associated API key was not provided.`
+  }
 
 To fix this, add the required secret to your GitHub repository:
 
@@ -114,10 +155,8 @@ To fix this, add the required secret to your GitHub repository:
 4. Set the value to your API key
 5. Click "Add secret"`;
 
-  // If other credentials are present, suggest alternative agents
-  if (availableAgents.length > 0) {
-    const agentNames = availableAgents.map((agent) => agent.name).join(", ");
-    message += `\n\nAlternatively, configure Pullfrog to use an agent with existing credentials in your environment (${agentNames}) at ${settingsUrl}`;
+  if (agentName === null) {
+    message += `\n\nAlternatively, configure Pullfrog to use an agent at ${settingsUrl}`;
   }
 
   log.error(message);
@@ -127,53 +166,95 @@ To fix this, add the required secret to your GitHub repository:
 interface MainContext {
   inputs: Inputs;
   githubInstallationToken: string;
-  tokenToRevoke: string | null;
   repoContext: RepoContext;
-  agentName: AgentName;
-  agent: (typeof agents)[AgentName];
+  agentName: AgentNameType;
+  agent: (typeof agents)[AgentNameType];
   sharedTempDir: string;
   mcpLogPath: string;
   pollInterval: NodeJS.Timeout | null;
   payload: Payload;
+  mcpServerUrl: string;
+  mcpServerClose: () => Promise<void>;
   mcpServers: ReturnType<typeof createMcpConfigs>;
   cliPath: string;
   apiKey: string;
 }
 
 async function initializeContext(
-  inputs: Inputs
-): Promise<Omit<MainContext, "payload" | "mcpServers" | "cliPath" | "apiKey">> {
+  inputs: Inputs,
+  payload: Payload
+): Promise<
+  Omit<MainContext, "mcpServerUrl" | "mcpServerClose" | "mcpServers" | "cliPath" | "apiKey">
+> {
   log.info(`🐸 Running pullfrog/action@${packageJson.version}...`);
   Inputs.assert(inputs);
   setupGitConfig();
 
-  const { githubInstallationToken, wasAcquired } = await setupGitHubInstallationToken();
-  const tokenToRevoke = wasAcquired ? githubInstallationToken : null;
+  const githubInstallationToken = await setupGitHubInstallationToken();
   const repoContext = parseRepoContext();
 
+  // resolve agent and update payload with resolved agent name
+  const { agentName, agent } = await resolveAgent(
+    inputs,
+    payload,
+    githubInstallationToken,
+    repoContext
+  );
+  const resolvedPayload = { ...payload, agent: agentName };
+
   return {
     inputs,
     githubInstallationToken,
-    tokenToRevoke,
     repoContext,
-    agentName: "claude" as AgentName,
-    agent: agents.claude,
+    agentName,
+    agent,
+    payload: resolvedPayload,
     sharedTempDir: "",
     mcpLogPath: "",
     pollInterval: null,
   };
 }
 
-async function determineAgent(
-  ctx: Omit<MainContext, "payload" | "mcpServers" | "cliPath" | "apiKey">
-): Promise<void> {
+async function resolveAgent(
+  inputs: Inputs,
+  payload: Payload,
+  githubInstallationToken: string,
+  repoContext: RepoContext
+): Promise<{ agentName: AgentNameType; agent: (typeof agents)[AgentNameType] }> {
   const repoSettings = await fetchRepoSettings({
-    token: ctx.githubInstallationToken,
-    repoContext: ctx.repoContext,
+    token: githubInstallationToken,
+    repoContext,
   });
 
-  ctx.agentName = ctx.inputs.agent || repoSettings.defaultAgent || "claude";
-  ctx.agent = agents[ctx.agentName];
+  const agentOverride = process.env.AGENT_OVERRIDE as AgentName | undefined;
+  const configuredAgentName = agentOverride || payload.agent || repoSettings.defaultAgent || null;
+
+  if (configuredAgentName) {
+    const agentName = configuredAgentName;
+    const agent = agents[agentName];
+    if (!agent) {
+      throw new Error(`invalid agent name: ${agentName}`);
+    }
+    log.info(`Selected configured agent: ${agentName}`);
+    return { agentName, agent };
+  }
+
+  const availableAgents = getAvailableAgents(inputs);
+  const availableAgentNames = availableAgents.map((agent) => agent.name).join(", ");
+  log.debug(`Available agents: ${availableAgentNames || "none"}`);
+
+  if (availableAgents.length === 0) {
+    throwMissingApiKeyError({
+      agentName: configuredAgentName,
+      inputKeys: getAllPossibleKeyNames(),
+      repoContext,
+    });
+  }
+
+  const agentName = availableAgents[0].name;
+  const agent = availableAgents[0];
+  log.info(`No agent configured, defaulting to first available agent: ${agentName}`);
+  return { agentName, agent };
 }
 
 async function setupTempDirectory(
@@ -212,15 +293,35 @@ function parsePayload(inputs: Inputs): Payload {
       "~pullfrog": true,
       agent: null,
       prompt: inputs.prompt,
-      event: {},
+      event: {
+        trigger: "unknown",
+      },
       modes,
     };
   }
 }
 
-function setupMcpServers(ctx: MainContext): void {
+async function startMcpServer(ctx: MainContext): Promise<void> {
+  // Set environment variables for MCP server tools
+  const repoContext = parseRepoContext();
+  const githubRepository = `${repoContext.owner}/${repoContext.name}`;
   const allModes = [...modes, ...(ctx.payload.modes || [])];
-  ctx.mcpServers = createMcpConfigs(ctx.githubInstallationToken, allModes);
+
+  process.env.GITHUB_INSTALLATION_TOKEN = ctx.githubInstallationToken;
+  process.env.GITHUB_REPOSITORY = githubRepository;
+  process.env.PULLFROG_MODES = JSON.stringify(allModes);
+  process.env.PULLFROG_PAYLOAD = JSON.stringify(ctx.payload);
+
+  // GITHUB_RUN_ID is already set in GitHub Actions, no need to set it here
+
+  const { url, close } = await startMcpHttpServer();
+  ctx.mcpServerUrl = url;
+  ctx.mcpServerClose = close;
+  log.info(`🚀 MCP server started at ${url}`);
+}
+
+function setupMcpServers(ctx: MainContext): void {
+  ctx.mcpServers = createMcpConfigs(ctx.mcpServerUrl);
   log.debug(`📋 MCP Config: ${JSON.stringify(ctx.mcpServers, null, 2)}`);
 }
 
@@ -229,23 +330,24 @@ async function installAgentCli(ctx: MainContext): Promise<void> {
 }
 
 function validateApiKey(ctx: MainContext): void {
-  const matchingInputKey = ctx.agent.inputKeys.find(
-    (inputKey) => ctx.inputs[inputKey as AgentInputKey]
-  );
+  const matchingInputKey = ctx.agent.apiKeyNames.find((inputKey) => ctx.inputs[inputKey]);
   if (!matchingInputKey) {
     throwMissingApiKeyError({
       agentName: ctx.agentName,
-      inputKeys: ctx.agent.inputKeys,
+      inputKeys: ctx.agent.apiKeyNames,
       repoContext: ctx.repoContext,
-      inputs: ctx.inputs,
     });
   }
-  ctx.apiKey = ctx.inputs[matchingInputKey as AgentInputKey]!;
+  ctx.apiKey = ctx.inputs[matchingInputKey]!;
 }
 
-async function runAgent(ctx: MainContext): Promise<import("./agents/shared.ts").AgentResult> {
+async function runAgent(ctx: MainContext): Promise<AgentResult> {
   log.info(`Running ${ctx.agentName}...`);
-  log.box(ctx.payload.prompt, { title: "Prompt" });
+  // strip context from event
+  const { context: _context, ...eventWithoutContext } = ctx.payload.event;
+  // format: prompt + two newlines + TOON encoded event
+  const promptContent = `${ctx.payload.prompt}\n\n${toonEncode(eventWithoutContext)}`;
+  log.box(promptContent, { title: "Prompt" });
 
   return ctx.agent.run({
     payload: ctx.payload,
@@ -256,9 +358,7 @@ async function runAgent(ctx: MainContext): Promise<import("./agents/shared.ts").
   });
 }
 
-async function handleAgentResult(
-  result: import("./agents/shared.ts").AgentResult
-): Promise<MainResult> {
+async function handleAgentResult(result: AgentResult): Promise<MainResult> {
   if (!result.success) {
     return {
       success: false,
@@ -275,14 +375,3 @@ async function handleAgentResult(
     output: result.output || "",
   };
 }
-
-async function cleanup(
-  ctx: Omit<MainContext, "payload" | "mcpServers" | "cliPath" | "apiKey">
-): Promise<void> {
-  if (ctx.pollInterval) {
-    clearInterval(ctx.pollInterval);
-  }
-  if (ctx.tokenToRevoke) {
-    await revokeInstallationToken(ctx.tokenToRevoke);
-  }
-}

mcp/README.md

@@ -0,0 +1,92 @@
+# gh_pullfrog MCP Tools
+
+this directory contains the mcp (model context protocol) server tools for interacting with github.
+
+## available tools
+
+### check suite tools
+
+#### `get_check_suite_logs`
+get workflow run logs for a failed check suite.
+
+**parameters:**
+- `check_suite_id` (number): the id from check_suite.id in the webhook payload
+
+**replaces:** `gh run list` and `gh run view --log`
+
+**returns:**
+all logs from all failed workflow runs in the check suite, including:
+- workflow run details (id, name, html_url, conclusion)
+- job details for each workflow run (id, name, status, conclusion, logs)
+
+**example:**
+```typescript
+// when handling a check_suite_completed webhook
+await mcp.call("gh_pullfrog/get_check_suite_logs", {
+  check_suite_id: check_suite.id
+});
+```
+
+### review tools
+
+#### `get_review_comments`
+get all line-by-line comments for a specific pull request review.
+
+**parameters:**
+- `pull_number` (number): the pull request number
+- `review_id` (number): the id from review.id in the webhook payload
+
+**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/comments`
+
+**returns:**
+array of review comments including:
+- file path, line number, comment body
+- side (LEFT/RIGHT) and position in diff
+- user, timestamps, html_url
+- in_reply_to_id for threaded comments
+
+**example:**
+```typescript
+// when handling a pull_request_review_submitted webhook
+await mcp.call("gh_pullfrog/get_review_comments", {
+  pull_number: 47,
+  review_id: review.id
+});
+```
+
+#### `list_pull_request_reviews`
+list all reviews for a pull request.
+
+**parameters:**
+- `pull_number` (number): the pull request number
+
+**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews`
+
+**returns:**
+array of reviews with:
+- review id, body, state (approved/changes_requested/commented)
+- user, commit_id, submitted_at, html_url
+
+**example:**
+```typescript
+await mcp.call("gh_pullfrog/list_pull_request_reviews", {
+  pull_number: 47
+});
+```
+
+### other tools
+
+see individual files for documentation on other tools:
+- `comment.ts` - create, edit, and update comments
+- `issue.ts` - create issues
+- `pr.ts` - create pull requests
+- `prInfo.ts` - get pull request information
+- `review.ts` - create pull request reviews
+- `selectMode.ts` - select execution mode
+
+## usage in agents
+
+agents should never use the `gh` cli. instead, they should use the mcp tools provided by this server.
+
+the agent instructions automatically include guidance on using these tools.
+

mcp/arkConfig.ts

@@ -0,0 +1,7 @@
+import { configure } from "arktype/config";
+
+configure({
+  toJsonSchema: {
+    dialect: null,
+  },
+});

mcp/checkSuite.ts

@@ -0,0 +1,94 @@
+import { type } from "arktype";
+import { contextualize, tool } from "./shared.ts";
+
+export const GetCheckSuiteLogs = type({
+  check_suite_id: type.number.describe("the id from check_suite.id"),
+});
+
+export const GetCheckSuiteLogsTool = tool({
+  name: "get_check_suite_logs",
+  description:
+    "get workflow run logs for a failed check suite. pass check_suite.id from the webhook payload.",
+  parameters: GetCheckSuiteLogs,
+  execute: contextualize(async ({ check_suite_id }, ctx) => {
+    // get workflow runs for this specific check suite
+    const workflowRuns = await ctx.octokit.paginate(
+      ctx.octokit.rest.actions.listWorkflowRunsForRepo,
+      {
+        owner: ctx.owner,
+        repo: ctx.name,
+        check_suite_id,
+        per_page: 100,
+      }
+    );
+
+    const failedRuns = workflowRuns.filter((run) => run.conclusion === "failure");
+
+    if (failedRuns.length === 0) {
+      return {
+        check_suite_id,
+        message: "no failed workflow runs found for this check suite",
+        workflow_runs: [],
+      };
+    }
+
+    // get logs for each failed run
+    const logsForRuns = await Promise.all(
+      failedRuns.map(async (run) => {
+        const jobs = await ctx.octokit.paginate(ctx.octokit.rest.actions.listJobsForWorkflowRun, {
+          owner: ctx.owner,
+          repo: ctx.name,
+          run_id: run.id,
+        });
+
+        const jobLogs = await Promise.all(
+          jobs.map(async (job) => {
+            try {
+              const logsResponse = await ctx.octokit.rest.actions.downloadJobLogsForWorkflowRun({
+                owner: ctx.owner,
+                repo: ctx.name,
+                job_id: job.id,
+              });
+
+              const logsUrl = logsResponse.url;
+              const logsText = await fetch(logsUrl).then((r) => r.text());
+
+              return {
+                job_id: job.id,
+                job_name: job.name,
+                status: job.status,
+                conclusion: job.conclusion,
+                started_at: job.started_at,
+                completed_at: job.completed_at,
+                logs: logsText,
+              };
+            } catch (error) {
+              return {
+                job_id: job.id,
+                job_name: job.name,
+                status: job.status,
+                conclusion: job.conclusion,
+                started_at: job.started_at,
+                completed_at: job.completed_at,
+                error: `failed to fetch logs: ${error}`,
+              };
+            }
+          })
+        );
+
+        return {
+          workflow_run_id: run.id,
+          workflow_name: run.name,
+          html_url: run.html_url,
+          conclusion: run.conclusion,
+          jobs: jobLogs,
+        };
+      })
+    );
+
+    return {
+      check_suite_id,
+      workflow_runs: logsForRuns,
+    };
+  }),
+});

mcp/comment.ts

@@ -1,6 +1,46 @@
 import { type } from "arktype";
+import type { Payload } from "../external.ts";
+import { agentsManifest } from "../external.ts";
+import { parseRepoContext } from "../utils/github.ts";
 import { contextualize, tool } from "./shared.ts";
 
+const PULLFROG_DIVIDER = "<!-- PULLFROG_DIVIDER_DO_NOT_REMOVE_PLZ -->";
+
+function buildCommentFooter(payload: Payload): string {
+  const repoContext = parseRepoContext();
+  const runId = process.env.GITHUB_RUN_ID;
+
+  const agentName = payload.agent;
+  const agentInfo = agentName ? agentsManifest[agentName] : null;
+  const agentDisplayName = agentInfo?.displayName || "Unknown Agent";
+  const agentUrl = agentInfo?.url || "https://pullfrog.ai";
+
+  // build workflow run URL: https://github.com/{owner}/{repo}/actions/runs/{runId}
+  const workflowRunUrl = runId
+    ? `https://github.com/${repoContext.owner}/${repoContext.name}/actions/runs/${runId}`
+    : `https://github.com/${repoContext.owner}/${repoContext.name}`;
+
+  return `
+${PULLFROG_DIVIDER}
+---
+
+<sup>🐸 Triggered by [Pullfrog](https://pullfrog.ai) | 🤖 [${agentDisplayName}](${agentUrl}) | [View workflow run](${workflowRunUrl}) | [𝕏](https://x.com/pullfrogai)</sup>`;
+}
+
+function stripExistingFooter(body: string): string {
+  const dividerIndex = body.indexOf(PULLFROG_DIVIDER);
+  if (dividerIndex === -1) {
+    return body;
+  }
+  return body.substring(0, dividerIndex).trimEnd();
+}
+
+function addFooter(body: string, payload: Payload): string {
+  const bodyWithoutFooter = stripExistingFooter(body);
+  const footer = buildCommentFooter(payload);
+  return `${bodyWithoutFooter}${footer}`;
+}
+
 export const Comment = type({
   issueNumber: type.number.describe("the issue number to comment on"),
   body: type.string.describe("the comment body content"),
@@ -11,11 +51,13 @@ export const CreateCommentTool = tool({
   description: "Create a comment on a GitHub issue",
   parameters: Comment,
   execute: contextualize(async ({ issueNumber, body }, ctx) => {
+    const bodyWithFooter = addFooter(body, ctx.payload);
+
     const result = await ctx.octokit.rest.issues.createComment({
       owner: ctx.owner,
       repo: ctx.name,
       issue_number: issueNumber,
-      body: body,
+      body: bodyWithFooter,
     });
 
     return {
@@ -37,11 +79,13 @@ export const EditCommentTool = tool({
   description: "Edit a GitHub issue comment by its ID",
   parameters: EditComment,
   execute: contextualize(async ({ commentId, body }, ctx) => {
+    const bodyWithFooter = addFooter(body, ctx.payload);
+
     const result = await ctx.octokit.rest.issues.updateComment({
       owner: ctx.owner,
       repo: ctx.name,
       comment_id: commentId,
-      body: body,
+      body: bodyWithFooter,
     });
 
     return {
@@ -73,11 +117,14 @@ export const CreateWorkingCommentTool = tool({
       throw new Error("create_working_comment may not be called multiple times");
     }
 
+    const body = `${intent} <img src="https://pullfrog.ai/party-parrot.gif" width="14px" height="14px" style="vertical-align: middle; margin-left: 4px;" />`;
+    const bodyWithFooter = addFooter(body, ctx.payload);
+
     const result = await ctx.octokit.rest.issues.createComment({
       owner: ctx.owner,
       repo: ctx.name,
       issue_number: issueNumber,
-      body: intent,
+      body: bodyWithFooter,
     });
 
     workingCommentId = result.data.id;
@@ -104,11 +151,13 @@ export const UpdateWorkingCommentTool = tool({
       throw new Error("create_working_comment must be called before update_working_comment");
     }
 
+    const bodyWithFooter = addFooter(body, ctx.payload);
+
     const result = await ctx.octokit.rest.issues.updateComment({
       owner: ctx.owner,
       repo: ctx.name,
       comment_id: workingCommentId,
-      body,
+      body: bodyWithFooter,
     });
 
     return {

mcp/config.ts

@@ -2,33 +2,18 @@
  * Simple MCP configuration helper for adding our minimal GitHub comment server
  */
 
-import type { McpStdioServerConfig } from "@anthropic-ai/claude-agent-sdk";
-import { fromHere } from "@ark/fs";
-import type { Mode } from "../modes.ts";
-import { parseRepoContext } from "../utils/github.ts";
-import { ghPullfrogMcpName } from "./index.ts";
+import type { McpHttpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { ghPullfrogMcpName } from "../external.ts";
 
 export type McpName = typeof ghPullfrogMcpName;
 
-export type McpConfigs = Record<McpName, McpStdioServerConfig>;
-
-export function createMcpConfigs(githubInstallationToken: string, modes: Mode[]): McpConfigs {
-  const repoContext = parseRepoContext();
-  const githubRepository = `${repoContext.owner}/${repoContext.name}`;
-
-  // In production (GitHub Actions), mcp-server.js is in same directory as entry.js (where this is bundled)
-  // In development, server.ts is in the same directory as this file (config.ts)
-  const serverPath = process.env.GITHUB_ACTIONS ? fromHere("mcp-server.js") : fromHere("server.ts");
+export type McpConfigs = Record<McpName, McpHttpServerConfig>;
 
+export function createMcpConfigs(mcpServerUrl: string): McpConfigs {
   return {
     [ghPullfrogMcpName]: {
-      command: "node",
-      args: [serverPath],
-      env: {
-        GITHUB_INSTALLATION_TOKEN: githubInstallationToken,
-        GITHUB_REPOSITORY: githubRepository,
-        PULLFROG_MODES: JSON.stringify(modes),
-      },
+      type: "http",
+      url: mcpServerUrl,
     },
   };
 }

mcp/debug.ts

@@ -0,0 +1,45 @@
+import { type } from "arktype";
+import { $ } from "../utils/shell.ts";
+import type { ToolResult } from "./shared.ts";
+import { tool } from "./shared.ts";
+
+export const DebugShellCommand = type({});
+
+export const DebugShellCommandTool = tool({
+  name: "debug_shell_command",
+  description:
+    "debug tool: runs 'git status' and returns the output. use this to test shell command execution in the MCP server.",
+  parameters: DebugShellCommand,
+  execute: async (): Promise<ToolResult> => {
+    try {
+      const result = $("git", ["status"]);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                command: "git status",
+                output: result.trim(),
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+});

mcp/files.ts

@@ -0,0 +1,48 @@
+import { type } from "arktype";
+import { $ } from "../utils/shell.ts";
+import { contextualize, tool } from "./shared.ts";
+
+export const ListFiles = type({
+  path: type.string
+    .describe("The path to list files from (defaults to current directory)")
+    .default("."),
+});
+
+export const ListFilesTool = tool({
+  name: "list_files",
+  description:
+    "List files in the repository using git ls-files. Useful for discovering the file structure and locating files.",
+  parameters: ListFiles,
+  execute: contextualize(async ({ path }) => {
+    try {
+      // Use git ls-files to list tracked files
+      // This respects .gitignore and gives a clean list of source files
+      const pathStr = path ?? ".";
+      const output = $("git", pathStr === "." ? ["ls-files"] : ["ls-files", pathStr], {
+        log: false,
+      });
+      const files = output.split("\n").filter((f) => f.trim() !== "");
+
+      if (files.length === 0) {
+        // Fallback for non-git environments or untracked files
+        const findOutput = $(
+          "find",
+          [pathStr, "-maxdepth", "3", "-not", "-path", "*/.*", "-type", "f"],
+          { log: false }
+        );
+        return {
+          files: findOutput.split("\n").filter((f) => f.trim() !== ""),
+          method: "find",
+        };
+      }
+
+      return { files, method: "git" };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        error: `Failed to list files: ${errorMessage}`,
+        hint: "Try using a specific path if the repository root is not the current directory.",
+      };
+    }
+  }),
+});

mcp/index.ts

@@ -1,4 +1,2 @@
-// for reasos this can't live alongide config.ts
-// because its imported into the frontend UI
-// and we don't want to pull in FastMCP, etc
-export const ghPullfrogMcpName = "gh-pullfrog";
+// re-export from external.ts for backward compatibility
+export { ghPullfrogMcpName } from "../external.ts";

mcp/pr.ts

@@ -1,6 +1,6 @@
-import { execSync } from "node:child_process";
 import { type } from "arktype";
 import { log } from "../utils/cli.ts";
+import { $ } from "../utils/shell.ts";
 import { contextualize, tool } from "./shared.ts";
 
 export const PullRequest = type({
@@ -15,9 +15,7 @@ export const PullRequestTool = tool({
   parameters: PullRequest,
   execute: contextualize(async ({ title, body, base }, ctx) => {
     // Get the current branch name
-    const currentBranch = execSync("git rev-parse --abbrev-ref HEAD", {
-      encoding: "utf8",
-    }).trim();
+    const currentBranch = $("git", ["rev-parse", "--abbrev-ref", "HEAD"], { log: false });
 
     log.info(`Current branch: ${currentBranch}`);
 

mcp/prInfo.ts

@@ -1,6 +1,6 @@
-import { execSync } from "node:child_process";
 import { type } from "arktype";
 import { log } from "../utils/cli.ts";
+import { $ } from "../utils/shell.ts";
 import { contextualize, tool } from "./shared.ts";
 
 export const PullRequestInfo = type({
@@ -30,13 +30,14 @@ export const PullRequestInfoTool = tool({
 
     // Automatically fetch and checkout branches for review
     log.info(`Fetching base branch: origin/${baseBranch}`);
-    execSync(`git fetch origin ${baseBranch} --depth=20`, { stdio: "inherit" });
+    $("git", ["fetch", "origin", baseBranch, "--depth=20"]);
 
     log.info(`Fetching PR branch: origin/${headBranch}`);
-    execSync(`git fetch origin ${headBranch}`, { stdio: "inherit" });
+    $("git", ["fetch", "origin", headBranch]);
 
     log.info(`Checking out PR branch: origin/${headBranch}`);
-    execSync(`git checkout origin/${headBranch}`, { stdio: "inherit" });
+    // check out a local branch tracking the remote branch so we can push changes
+    $("git", ["checkout", "-B", headBranch, `origin/${headBranch}`]);
 
     return {
       number: data.number,

mcp/reviewComments.ts

@@ -0,0 +1,76 @@
+import { type } from "arktype";
+import { contextualize, tool } from "./shared.ts";
+
+export const GetReviewComments = type({
+  pull_number: type.number.describe("The pull request number"),
+  review_id: type.number.describe("The review ID to get comments for"),
+});
+
+export const GetReviewCommentsTool = tool({
+  name: "get_review_comments",
+  description:
+    "Get all review comments for a specific pull request review. Returns line-by-line comments that were left on specific code locations.",
+  parameters: GetReviewComments,
+  execute: contextualize(async ({ pull_number, review_id }, ctx) => {
+    const comments = await ctx.octokit.paginate(ctx.octokit.rest.pulls.listCommentsForReview, {
+      owner: ctx.owner,
+      repo: ctx.name,
+      pull_number,
+      review_id,
+    });
+
+    return {
+      review_id,
+      pull_number,
+      comments: comments.map((comment) => ({
+        id: comment.id,
+        body: comment.body,
+        path: comment.path,
+        line: comment.line,
+        side: comment.side,
+        start_line: comment.start_line,
+        start_side: comment.start_side,
+        user: typeof comment.user === "string" ? comment.user : comment.user?.login,
+        created_at: comment.created_at,
+        updated_at: comment.updated_at,
+        html_url: comment.html_url,
+        in_reply_to_id: comment.in_reply_to_id,
+        diff_hunk: comment.diff_hunk,
+        reactions: comment.reactions,
+      })),
+      count: comments.length,
+    };
+  }),
+});
+
+export const ListPullRequestReviews = type({
+  pull_number: type.number.describe("The pull request number to list reviews for"),
+});
+
+export const ListPullRequestReviewsTool = tool({
+  name: "list_pull_request_reviews",
+  description:
+    "List all reviews for a pull request. Returns all reviews including approvals, request changes, and comments.",
+  parameters: ListPullRequestReviews,
+  execute: contextualize(async ({ pull_number }, ctx) => {
+    const reviews = await ctx.octokit.paginate(ctx.octokit.rest.pulls.listReviews, {
+      owner: ctx.owner,
+      repo: ctx.name,
+      pull_number,
+    });
+
+    return {
+      pull_number,
+      reviews: reviews.map((review) => ({
+        id: review.id,
+        body: review.body,
+        state: review.state,
+        user: review.user?.login,
+        commit_id: review.commit_id,
+        submitted_at: review.submitted_at,
+        html_url: review.html_url,
+      })),
+      count: reviews.length,
+    };
+  }),
+});

mcp/server.ts

@@ -1,32 +1,97 @@
+import "./arkConfig.ts";
+// this must be imported first
+import { createServer } from "node:net";
 import { FastMCP } from "fastmcp";
+import { ghPullfrogMcpName } from "../external.ts";
+import { GetCheckSuiteLogsTool } from "./checkSuite.ts";
 import {
   CreateCommentTool,
   CreateWorkingCommentTool,
   EditCommentTool,
   UpdateWorkingCommentTool,
 } from "./comment.ts";
+import { DebugShellCommandTool } from "./debug.ts";
 import { IssueTool } from "./issue.ts";
 import { PullRequestTool } from "./pr.ts";
 import { PullRequestInfoTool } from "./prInfo.ts";
 import { ReviewTool } from "./review.ts";
+import { GetReviewCommentsTool, ListPullRequestReviewsTool } from "./reviewComments.ts";
 import { SelectModeTool } from "./selectMode.ts";
 import { addTools } from "./shared.ts";
 
-const server = new FastMCP({
-  name: "gh-pullfrog",
-  version: "0.0.1",
-});
+/**
+ * Find an available port starting from the given port
+ */
+async function findAvailablePort(startPort: number): Promise<number> {
+  const checkPort = (port: number): Promise<boolean> => {
+    return new Promise((resolve) => {
+      const server = createServer();
+      server.once("error", () => {
+        server.close();
+        resolve(false);
+      });
+      server.listen(port, () => {
+        server.close(() => {
+          resolve(true);
+        });
+      });
+    });
+  };
 
-addTools(server, [
-  SelectModeTool,
-  CreateCommentTool,
-  EditCommentTool,
-  CreateWorkingCommentTool,
-  UpdateWorkingCommentTool,
-  IssueTool,
-  PullRequestTool,
-  ReviewTool,
-  PullRequestInfoTool,
-]);
+  let port = startPort;
+  while (port < startPort + 100) {
+    if (await checkPort(port)) {
+      return port;
+    }
+    port++;
+  }
+  throw new Error(`Could not find available port starting from ${startPort}`);
+}
 
-server.start();
+/**
+ * Start the MCP HTTP server and return the URL and close function
+ */
+export async function startMcpHttpServer(): Promise<{ url: string; close: () => Promise<void> }> {
+  const server = new FastMCP({
+    name: ghPullfrogMcpName,
+    version: "0.0.1",
+  });
+
+  addTools(server, [
+    SelectModeTool,
+    CreateCommentTool,
+    EditCommentTool,
+    CreateWorkingCommentTool,
+    UpdateWorkingCommentTool,
+    IssueTool,
+    PullRequestTool,
+    ReviewTool,
+    PullRequestInfoTool,
+    GetReviewCommentsTool,
+    ListPullRequestReviewsTool,
+    GetCheckSuiteLogsTool,
+    DebugShellCommandTool,
+  ]);
+
+  const port = await findAvailablePort(3764);
+  const host = "127.0.0.1";
+  const endpoint = "/mcp";
+
+  await server.start({
+    transportType: "httpStream",
+    httpStream: {
+      port,
+      host,
+      endpoint,
+    },
+  });
+
+  const url = `http://${host}:${port}${endpoint}`;
+
+  return {
+    url,
+    close: async () => {
+      await server.stop();
+    },
+  };
+}

mcp/shared.ts

@@ -1,8 +1,7 @@
-import { cached } from "@ark/util";
 import { Octokit } from "@octokit/rest";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { FastMCP, Tool } from "fastmcp";
-import { log } from "../utils/cli.ts";
+import type { Payload } from "../external.ts";
 import { parseRepoContext, type RepoContext } from "../utils/github.ts";
 
 export interface ToolResult {
@@ -13,7 +12,22 @@ export interface ToolResult {
   isError?: boolean;
 }
 
-export const getMcpContext = cached((): McpContext => {
+export function getPayload(): Payload {
+  const payloadEnv = process.env.PULLFROG_PAYLOAD;
+  if (!payloadEnv) {
+    throw new Error("PULLFROG_PAYLOAD environment variable is required");
+  }
+
+  try {
+    return JSON.parse(payloadEnv) as Payload;
+  } catch (error) {
+    throw new Error(
+      `Failed to parse PULLFROG_PAYLOAD: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+export function getMcpContext(): McpContext {
   const githubInstallationToken = process.env.GITHUB_INSTALLATION_TOKEN;
   if (!githubInstallationToken) {
     throw new Error("GITHUB_INSTALLATION_TOKEN environment variable is required");
@@ -24,46 +38,16 @@ export const getMcpContext = cached((): McpContext => {
     octokit: new Octokit({
       auth: githubInstallationToken,
     }),
+    payload: getPayload(),
   };
-});
+}
 
 export interface McpContext extends RepoContext {
   octokit: Octokit;
+  payload: Payload;
 }
 
-export const tool = <const params>(toolDef: Tool<any, StandardSchemaV1<params>>) => {
-  // Wrap the execute function to add logging with the tool name
-  const toolName = toolDef.name;
-  const originalExecute = toolDef.execute;
-
-  toolDef.execute = async (args: params, context: any) => {
-    try {
-      const result = await originalExecute(args, context);
-      // Check if result is a ToolResult with isError property
-      const isError =
-        result && typeof result === "object" && "isError" in result && result.isError === true;
-      const resultData =
-        result && typeof result === "object" && "content" in result
-          ? (result as ToolResult).content[0]?.text
-          : undefined;
-
-      if (isError && resultData) {
-        log.toolCall({ toolName, request: args, error: resultData });
-      } else if (resultData) {
-        log.toolCall({ toolName, request: args, result: resultData });
-      } else {
-        log.toolCall({ toolName, request: args });
-      }
-      return result;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      log.toolCall({ toolName, request: args, error: errorMessage });
-      throw error;
-    }
-  };
-
-  return toolDef;
-};
+export const tool = <const params>(toolDef: Tool<any, StandardSchemaV1<params>>) => toolDef;
 
 export const addTools = (server: FastMCP, tools: Tool<any, any>[]) => {
   for (const tool of tools) {

modes.ts

@@ -1,4 +1,4 @@
-import { ghPullfrogMcpName } from "./mcp/index.ts";
+import { ghPullfrogMcpName } from "./external.ts";
 
 export interface Mode {
   name: string;
@@ -6,55 +6,92 @@ export interface Mode {
   prompt: string;
 }
 
+const initialCommentInstruction = `When the task is associated with an issue/PR, use ${ghPullfrogMcpName}/create_working_comment to create an initial Working Comment with a conversational description of what work you are about to perform.`;
+
 export const modes: Mode[] = [
-  {
-    name: "Plan",
-    description:
-      "Create plans, break down tasks, outline steps, analyze requirements, understand scope of work, or provide task breakdowns",
-    prompt: `Follow these steps:
-1. Create initial response comment using ${ghPullfrogMcpName}/create_working_comment saying "I'll {summary of request}"
-2. If the request requires understanding the codebase structure, dependencies, or conventions, gather relevant context (read AGENTS.md if it exists, understand how to install dependencies, run tests, run builds, and make changes according to best practices). Skip this step if the prompt is trivial and self-contained.
-3. Analyze the request and break it down into clear, actionable tasks
-4. Consider dependencies, potential challenges, and implementation order
-5. Create a structured plan with clear milestones
-6. Update your comment using ${ghPullfrogMcpName}/update_working_comment to present the plan in a clear, organized format
-7. Continue updating the same comment as needed (never create additional comments - always use update_working_comment)`,
-  },
   {
     name: "Build",
     description:
       "Implement, build, create, or develop code changes; make specific changes to files or features; execute a plan; or handle tasks with specific implementation details",
     prompt: `Follow these steps:
-1. Create initial response comment using ${ghPullfrogMcpName}/create_working_comment saying "I'll {summary of request}"
-2. If the request requires understanding the codebase structure, dependencies, or conventions, gather relevant context (read AGENTS.md if it exists, understand how to install dependencies, run tests, run builds, and make changes according to best practices). Skip this step if the prompt is trivial and self-contained.
-3. Understand the requirements and any existing plan
-4. Make the necessary code changes
-5. Test your changes to ensure they work correctly
-6. Update your comment using ${ghPullfrogMcpName}/update_working_comment to share progress and results
-7. Continue updating the same comment as you make progress (never create additional comments - always use update_working_comment)`,
+1. ${initialCommentInstruction}
+
+2. If the request requires understanding the codebase structure, dependencies, or conventions, gather relevant context. Read AGENTS.md if it exists, understand how to install dependencies, run tests, run builds, and make changes according to best practices). Skip this step if the prompt is trivial and self-contained.
+
+3. Create a branch for your work. The branch name should be prefixed with "pullfrog/". The rest of the name should reflect the exact changes you are making. It should be specific to avoid collisions with other branches. Never commit to directly to main, master, or production.
+
+4. Understand the requirements and any existing plan
+
+5. Make the necessary code changes. Create intermediate commits if called for.
+
+6. Test your changes to ensure they work correctly
+
+7. Update your comment using ${ghPullfrogMcpName}/update_working_comment to share progress and results.
+
+8. Continue updating the same comment as you make progress. Never create additional comments. Always use update_working_comment.
+
+9. When you are done, create a final commit. If relevant, indicate which issue the PR addresses somewhere in the commit message (e.g. "Fixes #123"). Create a PR with an informative title and body. If relevant, include links to the issue or comment that triggered the PR.
+
+10. Update the Working Comment one final time with a summary of the results. Include links to any created issues/PRs, e.g. \`[View PR](https://github.com/org/repo/pull/123)\`
+`,
   },
   {
     name: "Review",
     description:
       "Review code, PRs, or implementations; provide feedback or suggestions; identify issues; or check code quality, style, and correctness",
     prompt: `Follow these steps:
-1. Create initial response comment using ${ghPullfrogMcpName}/create_working_comment saying "I'll review this"
+1. ${initialCommentInstruction}
+
 2. Get PR info with ${ghPullfrogMcpName}/get_pull_request (this automatically prepares the repository by fetching and checking out the PR branch)
+
 3. View diff: git diff origin/<base>...origin/<head> (use line numbers from this for inline comments, replace <base> and <head> with 'base' and 'head' from PR info)
+
 4. Read files from the checked-out PR branch to understand the implementation
+
 5. Update your comment using ${ghPullfrogMcpName}/update_working_comment with findings as you review
+
 6. When submitting review: use the 'comments' array for ALL specific code issues - include the file path and line position from the diff
+
 7. Only use the 'body' field for a brief summary (1-2 sentences) or for feedback that doesn't apply to a specific code location
+
 8. Continue updating the same comment as needed (never create additional comments - always use update_working_comment)`,
+  },
+  {
+    name: "Plan",
+    description:
+      "Create plans, break down tasks, outline steps, analyze requirements, understand scope of work, or provide task breakdowns",
+    prompt: `Follow these steps:
+1. ${initialCommentInstruction}
+
+2. If the request requires understanding the codebase structure, dependencies, or conventions, gather relevant context (read AGENTS.md if it exists, understand how to install dependencies, run tests, run builds, and make changes according to best practices). Skip this step if the prompt is trivial and self-contained.
+
+3. Analyze the request and break it down into clear, actionable tasks
+
+4. Consider dependencies, potential challenges, and implementation order
+
+5. Create a structured plan with clear milestones
+
+6. Update your comment using ${ghPullfrogMcpName}/update_working_comment to present the plan in a clear, organized format
+
+7. Continue updating the same comment as needed (never create additional comments - always use update_working_comment)`,
   },
   {
     name: "Prompt",
     description:
       "Fallback for tasks that don't fit other workflows, direct prompts via comments, or requests requiring general assistance without a specific workflow pattern",
     prompt: `Follow these steps:
-1. Create an initial "Working Comment" using ${ghPullfrogMcpName}/create_working_comment saying "I'll {summary of request}"
+1. ${initialCommentInstruction}
+
 2. Perform the requested task. Only take action if you have high confidence that you understand what is being asked. If you are not sure, ask for clarification. Take stock of the tools at your disposal.
-3. As your work progresses, update your Working Comment to share progress and results using ${ghPullfrogMcpName}/update_working_comment. Do not create additional comments unless you are explicitly asked to do so.
-4. When you finish the task, update the Working Comment a final time with a summary of the results and links to any created issues, PRs, etc.`,
+
+3. If the task involves making code changes:
+   - Create a branch for your work. The branch name should be prefixed with "pullfrog/". The rest of the name should reflect the exact changes you are making. It should be specific to avoid collisions with other branches. Never commit to directly to main, master, or production.
+   - Make the necessary code changes. Create intermediate commits if called for.
+   - Test your changes to ensure they work correctly.
+   - When you are done, create a final commit. If relevant, indicate which issue the PR addresses somewhere in the commit message (e.g. "Fixes #123"). Create a PR with an informative title and body. If relevant, include links to the issue or comment that triggered the PR.
+
+4. As your work progresses, update your Working Comment to share progress and results using ${ghPullfrogMcpName}/update_working_comment. Do not create additional comments unless you are explicitly asked to do so.
+
+5. When you finish the task, update the Working Comment a final time with a summary of the results and links to any created issues, PRs, etc.`,
   },
 ];

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pullfrog/action",
-  "version": "0.0.108",
+  "version": "0.0.113",
   "type": "module",
   "files": [
     "index.js",

play.ts

@@ -6,15 +6,15 @@ import { flatMorph } from "@ark/util";
 import arg from "arg";
 import { config } from "dotenv";
 import { agents } from "./agents/index.ts";
+import type { AgentResult } from "./agents/shared.ts";
 import { type Inputs, main } from "./main.ts";
 import { log } from "./utils/cli.ts";
 import { setupTestRepo } from "./utils/setup.ts";
 
 config();
+config({ path: join(process.cwd(), "../.env") });
 
-export async function run(
-  prompt: string
-): Promise<{ success: boolean; output?: string | undefined; error?: string | undefined }> {
+export async function run(prompt: string): Promise<AgentResult> {
   try {
     const tempDir = join(process.cwd(), ".temp");
     setupTestRepo({ tempDir, forceClean: true });
@@ -22,11 +22,13 @@ export async function run(
     const originalCwd = process.cwd();
     process.chdir(tempDir);
 
+    // check if prompt is a pullfrog payload and extract agent
+    // note: agent from payload will be used by determineAgent with highest precedence
+    // we don't need to extract it here since main() will parse the payload
     const inputs: Required<Inputs> = {
       prompt,
-      agent: "claude",
       ...flatMorph(agents, (_, agent) =>
-        agent.inputKeys.map((inputKey) => [inputKey, process.env[inputKey.toUpperCase()]])
+        agent.apiKeyNames.map((inputKey) => [inputKey, process.env[inputKey.toUpperCase()]])
       ),
     };
 
@@ -139,6 +141,8 @@ Examples:
     if (!result.success) {
       process.exit(1);
     }
+
+    process.exit(0);
   } catch (err) {
     log.error((err as Error).message);
     process.exit(1);

scratch.ts

@@ -2,15 +2,14 @@ import { spawnSync } from "child_process";
 import { existsSync } from "fs";
 
 function findCliPath(name: string): string | null {
-    
-      const result = spawnSync("which", [name], { encoding: "utf-8" });
-      if (result.status === 0 && result.stdout) {
-        const cliPath = result.stdout.trim();
-        if (cliPath && existsSync(cliPath)) {
-          return cliPath;
-        }
-      }
-    return null;
+  const result = spawnSync("which", [name], { encoding: "utf-8" });
+  if (result.status === 0 && result.stdout) {
+    const cliPath = result.stdout.trim();
+    if (cliPath && existsSync(cliPath)) {
+      return cliPath;
+    }
   }
-  
-console.log(findCliPath("codei"));
+  return null;
+}
+
+console.log(findCliPath("codei"));

todo.md

@@ -1,34 +0,0 @@
-## CURRENT
-
-[] gemini installation speed (bundle/esm.sh?) (TODO: SHAWN)
-[] handle defaulting agent name value (TODO: SHAWN)
-
-[] test agent/mode combinations
-[] test if home directory mcp.json works if mcp.json is specified in repo
-[] add footer to the working comment ("executed by {agent}", link to pullfrog (homepage) w/ small logo?, feedback (create github issue), link to workflow run)- see https://github.com/colinhacks/zod/issues/5459#issuecomment-3548382991
-
-## MAYBE
-
-[] investigate repo config file
-[] try to find heavy claude code user
-[] investigate including terminal output from bash commands as collapsed groups from claude
-[] test initialization trade offs for pullfrog.yml
-
-## DONE
- 
-[x] investigate mcp naming convention
-[x] input just accepts one key for API key
-[x] look into trigger.yml without installation
-[x] cancel installation token at the end of github action
-[x] avoid exposing env adding ## SECURITY prompt
-[x] add modes to prompt 
-[x] progressively update comment
-[x] don't allow rejecting prs
-[x] fix pnpm caching
-[x] fix prompt to avoid narration like "I just read all tools from MCP server"
-[x] handle progressive comment updating from pullfrog mcp
-[x] jules/gemini support
-[x] standardize mcp server
-[x] entry.js
-[x] split up prompts, load dynamically based on mode
-[x] log.txt to stdout

utils/api.ts

@@ -1,5 +1,4 @@
-import type { AgentName } from "../main.ts";
-import { log } from "./cli.ts";
+import type { AgentName } from "../external.ts";
 import type { RepoContext } from "./github.ts";
 
 export interface Mode {
@@ -36,9 +35,7 @@ export async function fetchRepoSettings({
   token: string;
   repoContext: RepoContext;
 }): Promise<RepoSettings> {
-  log.info("Fetching repository settings...");
   const settings = await getRepoSettings(token, repoContext);
-  log.info("Repository settings fetched");
   return settings;
 }
 

utils/cli.ts

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import * as core from "@actions/core";
+import { table } from "table";
 
 const isGitHubActions = !!process.env.GITHUB_ACTIONS;
-const isDebugEnabled = process.env.LOG_LEVEL === "debug";
+const isDebugEnabled = () => process.env.LOG_LEVEL === "debug";
 
 /**
  * Start a collapsed group (GitHub Actions) or regular group (local)
@@ -78,7 +79,11 @@ function boxString(
   }
 
   const maxLineLength = Math.max(...wrappedLines.map((line) => line.length));
-  const boxWidth = maxLineLength + padding * 2;
+  const contentBoxWidth = maxLineLength + padding * 2;
+
+  // ensure box width is at least as wide as the title line when title exists
+  const titleLineLength = title ? ` ${title} `.length : 0;
+  const boxWidth = Math.max(contentBoxWidth, titleLineLength);
 
   let result = "";
 
@@ -160,6 +165,43 @@ async function summaryTable(
   core.info(`\n${tableText}\n`);
 }
 
+/**
+ * Print a formatted table using the table package
+ * Also logs to console and GitHub Actions summary
+ */
+async function printTable(
+  rows: Array<Array<{ data: string; header?: boolean } | string>>,
+  options?: {
+    title?: string;
+  }
+): Promise<void> {
+  const { title } = options || {};
+
+  // Convert rows to string arrays for the table package
+  const tableData = rows.map((row) =>
+    row.map((cell) => {
+      if (typeof cell === "string") {
+        return cell;
+      }
+      return cell.data;
+    })
+  );
+
+  const formatted = table(tableData);
+
+  if (title) {
+    core.info(`\n${title}`);
+  }
+  core.info(`\n${formatted}\n`);
+
+  if (isGitHubActions) {
+    if (title) {
+      core.summary.addRaw(`**${title}**\n\n`);
+    }
+    core.summary.addRaw(`\`\`\`\n${formatted}\n\`\`\`\n`);
+  }
+}
+
 /**
  * Print a separator line
  */
@@ -220,7 +262,7 @@ export const log = {
    * Print debug message (only if LOG_LEVEL=debug)
    */
   debug: (message: string): void => {
-    if (isDebugEnabled) {
+    if (isDebugEnabled()) {
       if (isGitHubActions) {
         core.debug(message);
       } else {
@@ -240,6 +282,11 @@ export const log = {
    */
   summaryTable,
 
+  /**
+   * Print a formatted table using the table package
+   */
+  table: printTable,
+
   /**
    * Print a separator line
    */
@@ -265,10 +312,24 @@ export const log = {
    */
   endGroup,
 
+  /**
+   * Log tool call information to console with formatted output
+   */
+  toolCall: ({ toolName, input }: { toolName: string; input: unknown }): void => {
+    let output = `→ ${toolName}\n`;
+
+    const inputFormatted = formatJsonValue(input);
+    if (inputFormatted !== "{}") {
+      output += formatIndentedField("input", inputFormatted);
+    }
+
+    log.info(output.trimEnd());
+  },
+
   /**
    * Log MCP tool call information to mcpLog.txt in the temp directory
    */
-  toolCall: ({
+  toolCallToFile: ({
     toolName,
     request,
     result,
@@ -302,7 +363,7 @@ function getMcpLogPath(): string {
 /**
  * Format a value as JSON, using compact format for simple values and pretty-printed for complex ones
  */
-function formatJsonValue(value: unknown): string {
+export function formatJsonValue(value: unknown): string {
   const compact = JSON.stringify(value);
   return compact.length > 80 || compact.includes("\n") ? JSON.stringify(value, null, 2) : compact;
 }
@@ -311,7 +372,7 @@ function formatJsonValue(value: unknown): string {
  * Format a multi-line string with proper indentation for tool call output
  * First line has the label, subsequent lines are indented 4 spaces
  */
-function formatIndentedField(label: string, content: string): string {
+export function formatIndentedField(label: string, content: string): string {
   if (!content.includes("\n")) {
     return `  ${label}: ${content}\n`;
   }

utils/github.ts

@@ -43,12 +43,6 @@ interface RepositoriesResponse {
   repositories: Repository[];
 }
 
-function checkExistingToken(): string | null {
-  const inputToken = core.getInput("github_installation_token");
-  const envToken = process.env.GITHUB_INSTALLATION_TOKEN;
-  return inputToken || envToken || null;
-}
-
 function isGitHubActionsEnvironment(): boolean {
   return Boolean(process.env.GITHUB_ACTIONS);
 }
@@ -249,24 +243,13 @@ async function acquireNewToken(): Promise<string> {
 
 /**
  * Setup GitHub installation token for the action
- * Returns the token and whether it was acquired (needs revocation)
  */
-export async function setupGitHubInstallationToken(): Promise<{
-  githubInstallationToken: string;
-  wasAcquired: boolean;
-}> {
-  const existingToken = checkExistingToken();
-  if (existingToken) {
-    core.setSecret(existingToken);
-    log.info("Using provided GitHub installation token");
-    return { githubInstallationToken: existingToken, wasAcquired: false };
-  }
-
+export async function setupGitHubInstallationToken(): Promise<string> {
   const acquiredToken = await acquireNewToken();
   core.setSecret(acquiredToken);
   process.env.GITHUB_INSTALLATION_TOKEN = acquiredToken;
 
-  return { githubInstallationToken: acquiredToken, wasAcquired: true };
+  return acquiredToken;
 }
 
 /**

utils/setup.ts

@@ -1,7 +1,9 @@
 import { execSync } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
+import type { Payload } from "../external.ts";
 import { log } from "./cli.ts";
 import type { RepoContext } from "./github.ts";
+import { $ } from "./shell.ts";
 
 export interface SetupOptions {
   tempDir: string;
@@ -25,7 +27,7 @@ export function setupTestRepo(options: SetupOptions): void {
       rmSync(tempDir, { recursive: true, force: true });
 
       log.info("📦 Cloning pullfrogai/scratch into .temp...");
-      execSync(`git clone ${repoUrl} ${tempDir}`, { stdio: "inherit" });
+      $("git", ["clone", repoUrl, tempDir]);
     } else {
       log.info("📦 Resetting existing .temp repository...");
       execSync("git reset --hard HEAD && git clean -fd", {
@@ -35,26 +37,28 @@ export function setupTestRepo(options: SetupOptions): void {
     }
   } else {
     log.info("📦 Cloning pullfrogai/scratch into .temp...");
-    execSync(`git clone ${repoUrl} ${tempDir}`, { stdio: "inherit" });
+    $("git", ["clone", repoUrl, tempDir]);
   }
 }
 
 /**
  * Setup git configuration to avoid identity errors
- * Only runs in GitHub Actions environment to avoid overwriting local git config
+ * Uses --local flag to scope config to the current repo only
  */
 export function setupGitConfig(): void {
-  // Only set up git config in GitHub Actions environment
-  // In local development, use the user's existing git config
-  if (!process.env.GITHUB_ACTIONS) {
-    return;
-  }
-
+  const repoDir = process.cwd();
   log.info("🔧 Setting up git configuration...");
   try {
-    execSync('git config user.email "action@pullfrog.ai"', { stdio: "pipe" });
-    execSync('git config user.name "Pullfrog Action"', { stdio: "pipe" });
-    log.debug("setupGitConfig: ✓ Git configuration set successfully");
+    // Use --local to scope config to this repo only, preventing leakage to user's global config
+    execSync('git config --local user.email "action@pullfrog.ai"', {
+      cwd: repoDir,
+      stdio: "pipe",
+    });
+    execSync('git config --local user.name "Pullfrog Action"', {
+      cwd: repoDir,
+      stdio: "pipe",
+    });
+    log.debug("setupGitConfig: ✓ Git configuration set successfully (scoped to repo)");
   } catch (error) {
     // If git config fails, log warning but don't fail the action
     // This can happen if we're not in a git repo or git isn't available
@@ -65,28 +69,72 @@ export function setupGitConfig(): void {
 }
 
 /**
- * Setup git authentication using GitHub token
- * Only runs in GitHub Actions environment to avoid breaking local git remotes
+ * Setup git authentication using GitHub installation token
+ * Always uses the installation token, scoped to the current repo only
  */
-export function setupGitAuth(githubToken: string, repoContext: RepoContext): void {
-  // Only set up git auth in GitHub Actions environment
-  // In local testing, this would overwrite the real git remote with fake credentials
-  if (!process.env.GITHUB_ACTIONS) {
-    return;
-  }
+export function setupGitAuth(ctx: {
+  githubInstallationToken: string;
+  repoContext: RepoContext;
+}): void {
+  const repoDir = process.cwd();
 
   log.info("🔐 Setting up git authentication...");
 
   // Remove existing git auth headers that actions/checkout might have set
+  // Use --local to scope to this repo only
   try {
-    execSync("git config --unset-all http.https://github.com/.extraheader", { stdio: "inherit" });
+    execSync("git config --local --unset-all http.https://github.com/.extraheader", {
+      cwd: repoDir,
+      stdio: "pipe",
+    });
     log.info("✓ Removed existing authentication headers");
   } catch {
-    log.info("No existing authentication headers to remove");
+    log.debug("No existing authentication headers to remove");
   }
 
   // Update remote URL to embed the token
-  const remoteUrl = `https://x-access-token:${githubToken}@github.com/${repoContext.owner}/${repoContext.name}.git`;
-  execSync(`git remote set-url origin "${remoteUrl}"`, { stdio: "inherit" });
-  log.info("✓ Updated remote URL with authentication token");
+  // This is scoped to the repo's .git/config, not the user's global config
+  const remoteUrl = `https://x-access-token:${ctx.githubInstallationToken}@github.com/${ctx.repoContext.owner}/${ctx.repoContext.name}.git`;
+  $("git", ["remote", "set-url", "origin", remoteUrl], { cwd: repoDir });
+  log.info("✓ Updated remote URL with authentication token (scoped to repo)");
+}
+
+/**
+ * Setup git branch based on payload event context
+ * Automatically checks out the appropriate branch before agent execution
+ */
+export function setupGitBranch(payload: Payload): void {
+  const branch = payload.event.branch;
+  const repoDir = process.cwd();
+
+  if (!branch) {
+    log.debug("No branch specified in payload, using default branch");
+    return;
+  }
+
+  log.info(`🌿 Setting up git branch: ${branch}`);
+
+  try {
+    // Fetch the branch from origin
+    log.debug(`Fetching branch from origin: ${branch}`);
+    execSync(`git fetch origin ${branch}`, {
+      cwd: repoDir,
+      stdio: "pipe",
+    });
+
+    // Checkout the branch, creating local tracking branch
+    log.debug(`Checking out branch: ${branch}`);
+    execSync(`git checkout -B ${branch} origin/${branch}`, {
+      cwd: repoDir,
+      stdio: "pipe",
+    });
+
+    log.info(`✓ Successfully checked out branch: ${branch}`);
+  } catch (error) {
+    // If git operations fail, log warning but don't fail the action
+    // The agent might still be able to work with the default branch
+    log.warning(
+      `Failed to checkout branch ${branch}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
 }

utils/shell.ts

@@ -0,0 +1,83 @@
+import { spawnSync } from "node:child_process";
+
+interface ShellOptions {
+  cwd?: string;
+  encoding?:
+    | "utf-8"
+    | "utf8"
+    | "ascii"
+    | "base64"
+    | "base64url"
+    | "hex"
+    | "latin1"
+    | "ucs-2"
+    | "ucs2"
+    | "utf16le";
+  log?: boolean;
+  onError?: (result: { status: number; stdout: string; stderr: string }) => void;
+}
+
+/**
+ * Execute a shell command safely using spawnSync with argument arrays.
+ * Prevents shell injection by avoiding string interpolation in shell commands.
+ *
+ * @param cmd - The command to execute
+ * @param args - Array of arguments to pass to the command
+ * @param options - Optional configuration (cwd, encoding, onError)
+ * @returns The trimmed stdout output
+ * @throws Error if command fails and no onError handler is provided
+ */
+export function $(cmd: string, args: string[], options?: ShellOptions): string {
+  const encoding = options?.encoding ?? "utf-8";
+
+  // CRITICAL: use "ignore" for stdin instead of "inherit" to avoid breaking MCP transport
+  // when running inside an MCP server, stdin is used for JSON-RPC protocol
+  const result = spawnSync(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding,
+    cwd: options?.cwd,
+  });
+
+  const stdout = result.stdout ?? "";
+  const stderr = result.stderr ?? "";
+
+  // Write output to process streams so it behaves like stdio: "inherit"
+  // CRITICAL: when running inside an MCP server, stdout is used for JSON-RPC protocol
+  // so we must write to stderr instead to avoid corrupting the protocol
+  // Only log if log option is not explicitly set to false
+  if (options?.log !== false) {
+    // if stdout is a TTY, it's safe to write to it; otherwise it's likely a pipe used for JSON-RPC
+    const canWriteToStdout = process.stdout.isTTY === true;
+    if (stdout) {
+      if (canWriteToStdout) {
+        process.stdout.write(stdout);
+      } else {
+        // stdout is a pipe (MCP context) - write to stderr instead
+        process.stderr.write(stdout);
+      }
+    }
+    if (stderr) {
+      process.stderr.write(stderr);
+    }
+  }
+
+  // Handle errors
+  if (result.status !== 0) {
+    const errorResult = {
+      status: result.status ?? -1,
+      stdout,
+      stderr,
+    };
+
+    if (options?.onError) {
+      options.onError(errorResult);
+      return stdout.trim();
+    }
+
+    throw new Error(
+      `Command failed with exit code ${errorResult.status}: ${stderr || "Unknown error"}`
+    );
+  }
+
+  return stdout.trim();
+}

utils/subprocess.ts

@@ -29,8 +29,12 @@ export async function spawn(options: SpawnOptions): Promise<SpawnResult> {
   let stderrBuffer = "";
 
   return new Promise((resolve, reject) => {
+    // security: caller must provide complete env object, not merged with process.env
     const child = nodeSpawn(cmd, args, {
-      env: env ? { ...process.env, ...env } : process.env,
+      env: env || {
+        PATH: process.env.PATH || "",
+        HOME: process.env.HOME || "",
+      },
       stdio: ["pipe", "pipe", "pipe"],
       cwd: cwd || process.cwd(),
     });