brainiac-github 0.0.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4606ec0c07107e122e51570364e05d20db3d0717e7a6679cdff85471f38e0b5
-  data.tar.gz: 73ad18ee4563e0e55d56a1cab2f8f8714484d3fee3bbc1c3763ec1e2886221eb
+  metadata.gz: 48b4b58174666e2efbd528ac3cf650cad735f25d84eedabffe4d201cdbe2acac
+  data.tar.gz: fd097926d92d623f56c7b5c26e7aa88726e952eb6ba21f1392bbecadaaf8f55e
 SHA512:
-  metadata.gz: 9c7240c8f7a3a1b57e72bc6245a50d7089c82736e6e0259c2944ca623fbb6839f564064b75788c3b8fc60489393b0fdc65ff932410da878b2bb19bc16327c801
-  data.tar.gz: 05405f8388fe9c817d4c2b59edde95f5ac6819112fa1f30f24d486a35a37c2dd417aad3f0c17f760e237f1d54681508e436cd1820f6b56eea5a1fc6ec77d1e96
+  metadata.gz: 828c3c2dfe74d72c92a717b68b1d79e4d9fddf1a73539f912b874895020b5254b8c64d630d391494099630d943cf3f6d47ca8b1726b6d783c8de509180096889
+  data.tar.gz: f0d3527e61e1b1b3bcf0f8f1e3da2a9ff63d39711238bb5c134f3826875949035256ed945a953335369c5db612255cee7703a8b302f51487dd1b97da8589de75

data/README.md

@@ -24,23 +24,193 @@ Config lives at `~/.brainiac/github.json`:
 ```json
 {
   "webhook_secret": "your-github-webhook-secret",
+  "allowed_owners": ["stowzilla", "ardavis"],
+  "apps": {
+    "brainiac": {
+      "id": "100000",
+      "private_key_path": "~/.brainiac/brainiac.pem",
+      "installations": {
+        "stowzilla": "11111111",
+        "ardavis": "22222222"
+      }
+    },
+    "galen": {
+      "id": "200000",
+      "private_key_path": "~/.brainiac/galen-brainiac.pem",
+      "installations": {
+        "stowzilla": "33333333",
+        "ardavis": "44444444"
+      }
+    }
+  },
   "repos": {}
 }
 ```
 
+The `allowed_owners` array restricts which GitHub accounts/orgs can trigger your
+agents. Events from repos not owned by a listed account are rejected with a 403
+before any processing occurs. If omitted, all owners are accepted (filtered
+downstream by project matching instead).
+
 Generate a webhook secret:
 
 ```bash
 ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
 ```
 
+### GitHub App Setup
+
+The plugin uses GitHub Apps for two purposes:
+
+1. **Inbound events** — a single "Brainiac" app receives webhook events from all repos
+2. **Outbound identity** — per-agent apps post comments/reactions with distinct avatars
+
+This mirrors how Discord works: one gateway delivers all messages, each bot responds
+with its own token and avatar.
+
+#### Architecture
+
+```
+brainiac (app)       → webhook ACTIVE, receives all events
+galen-brainiac (app) → webhook DISABLED, Galen's posting identity
+glados-brainiac (app)→ webhook DISABLED, GLaDOS's posting identity
+```
+
+The "brainiac" agent in the registry also uses the brainiac app as its posting
+identity — so the webhook-receiver app doubles as the brainiac agent's identity.
+
+#### Step 1: Create the Brainiac App (Webhook Receiver)
+
+1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Set the following:
+   - **Name**: `brainiac` (or your preferred orchestrator name)
+   - **Homepage URL**: your Brainiac instance URL
+   - **Webhook URL**: `https://your-ngrok.ngrok-free.app/github`
+   - **Webhook secret**: paste the `webhook_secret` from your `github.json`
+3. Under **"Where can this GitHub App be installed?"**, select **"Any account"**
+   (allows installation on both personal accounts and organizations)
+4. Set **Permissions** (under "Repository permissions"):
+   - **Contents**: Read-only
+   - **Issues**: Read & Write
+   - **Pull requests**: Read & Write
+5. **Subscribe to events**:
+   - Issue comment
+   - Issues
+   - Pull request
+   - Pull request review
+   - Workflow run
+6. Create the app and note the **App ID**
+7. Generate a private key (see [Private Key Details](#private-key-details) below)
+8. Upload an avatar for the app
+9. **Install the app** on each account/org where you have repos:
+   - Go to the app's settings → "Install App" tab
+   - Install on your personal account (e.g. `ardavis`) — note the Installation ID
+     from the URL: `https://github.com/settings/installations/INSTALLATION_ID`
+   - Install on your org (e.g. `stowzilla`) — note that Installation ID too
+
+#### Step 2: Create Agent Identity Apps (One Per Agent)
+
+For each agent that should have its own avatar on PR comments:
+
+1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Set the following:
+   - **Name**: `galen-brainiac`, `glados-brainiac`, etc.
+   - **Homepage URL**: your Brainiac instance URL
+   - **Webhook**: uncheck **"Active"** (these apps don't receive events)
+3. Under **"Where can this GitHub App be installed?"**, select **"Any account"**
+4. Set **Permissions** (under "Repository permissions"):
+   - **Contents**: Read-only
+   - **Issues**: Read & Write
+   - **Pull requests**: Read & Write
+5. **Do NOT subscribe to any events** (webhook is disabled)
+6. Create the app and note the **App ID**
+7. Generate a private key
+8. Upload the agent's **avatar**
+9. **Install the app** on each account/org (same as the brainiac app)
+10. Repeat for each agent
+
+#### Step 3: Configure `github.json`
+
+```json
+{
+  "webhook_secret": "your-github-webhook-secret",
+  "allowed_owners": ["stowzilla", "ardavis"],
+  "apps": {
+    "brainiac": {
+      "id": "100000",
+      "private_key_path": "~/.brainiac/brainiac.pem",
+      "installations": {
+        "stowzilla": "11111111",
+        "ardavis": "22222222"
+      }
+    },
+    "galen": {
+      "id": "200000",
+      "private_key_path": "~/.brainiac/galen-brainiac.pem",
+      "installations": {
+        "stowzilla": "33333333",
+        "ardavis": "44444444"
+      }
+    },
+    "glados": {
+      "id": "300000",
+      "private_key_path": "~/.brainiac/glados-brainiac.pem",
+      "installations": {
+        "stowzilla": "55555555",
+        "ardavis": "66666666"
+      }
+    }
+  },
+  "repos": {}
+}
+```
+
+Each key in `apps` matches the agent's registry key (lowercase). The
+`installations` hash maps account/org names to their Installation IDs.
+
+#### Private Key Details
+
+The `.pem` file is generated by GitHub — you don't create it yourself. On your
+app's settings page (Settings → Developer settings → GitHub Apps → your app):
+
+1. Scroll to the **"Private keys"** section
+2. Click **"Generate a private key"**
+3. GitHub generates an RSA key pair, keeps the public half, and your browser
+   downloads the private half as a `.pem` file (named like
+   `your-app-name.2026-08-06.private-key.pem`)
+4. Move it to your brainiac config directory and lock down permissions:
+   ```bash
+   mv ~/Downloads/your-app-name.*.private-key.pem ~/.brainiac/galen-brainiac.pem
+   chmod 600 ~/.brainiac/galen-brainiac.pem
+   ```
+
+The plugin uses this key to sign JWTs for GitHub API authentication. Never
+commit `.pem` files to version control.
+
+#### Fallback
+
+If no app credentials are configured for an agent, the plugin falls back to
+using the `gh` CLI (which authenticates as your personal GitHub account).
+
+### Environment Variables
+
+As an alternative to config file values, you can set (applies to single-app mode only):
+
+- `GITHUB_WEBHOOK_SECRET` — webhook signature secret
+- `GITHUB_APP_ID` — GitHub App ID
+- `GITHUB_APP_PRIVATE_KEY_PATH` — path to the `.pem` private key file
+- `GITHUB_APP_INSTALLATION_ID` — installation ID
+
+For per-agent apps, use the config file — env vars don't support multiple apps.
+
 ### GitHub Webhook Setup
 
-1. Go to your repo → Settings → Webhooks → Add webhook
-2. Payload URL: `https://your-ngrok.ngrok-free.app/github`
-3. Content type: `application/json`
-4. Secret: paste your `webhook_secret`
-5. Events: Pull requests, Pull request reviews, Issue comments, Issues, Workflow runs
+The webhook is configured on the Brainiac app itself (Step 1 above) — no
+per-repo webhook setup is needed. The app-level webhook automatically receives
+events from all repos where the app is installed.
+
+If you have legacy per-repo webhooks pointing to `/github`, remove them to
+avoid duplicate event deliveries.
 
 ## CLI
 

data/lib/brainiac/plugins/github/app_client.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+require "jwt"
+require "time"
+
+module Brainiac
+  module Plugins
+    module Github
+      # HTTP client that authenticates as a GitHub App (installation).
+      #
+      # When app credentials are configured (app_id + private_key_path + installation_id),
+      # API calls are made as the App's bot user — so PR comments, reactions, etc.
+      # appear with the App's identity rather than a personal user.
+      #
+      # Supports per-agent apps: if "apps" hash in config has an entry for the agent,
+      # that agent's app credentials are used (separate avatar/identity per agent).
+      # Falls back to shared "app" config, then to `gh` CLI.
+      module AppClient
+        GITHUB_API = "https://api.github.com"
+        TOKEN_EXPIRY_BUFFER = 60 # refresh token 60s before expiry
+
+        # Per-agent token cache: { agent_key_or_nil => { token:, expires_at: } }
+        @tokens = {}
+        @mutex = Mutex.new
+
+        class << self
+          # Returns true if GitHub App credentials are fully configured.
+          # Checks per-agent first, then shared app config.
+          # Guards against empty-string values (common in template configs).
+          def configured?(agent_key = nil)
+            id = Config.app_id(agent_key)
+            key_path = Config.private_key_path(agent_key)
+            inst_id = Config.installation_id(agent_key)
+
+            !!(id && !id.empty? && key_path && inst_id && !inst_id.empty?)
+          end
+
+          # POST a comment on an issue or PR.
+          #
+          # @param repo [String] "owner/repo"
+          # @param pr_number [Integer]
+          # @param body [String] comment markdown
+          # @param agent_key [String, nil] agent key for per-agent app identity
+          # @return [Hash] parsed response
+          def create_comment(repo, pr_number, body, agent_key: nil)
+            post("/repos/#{repo}/issues/#{pr_number}/comments", { body: body }, agent_key: agent_key)
+          end
+
+          # POST a reaction on an issue comment.
+          #
+          # @param repo [String] "owner/repo"
+          # @param comment_id [Integer]
+          # @param reaction [String] e.g. "eyes", "+1", "rocket"
+          # @param agent_key [String, nil] agent key for per-agent app identity
+          # @return [Hash] parsed response
+          def create_comment_reaction(repo, comment_id, reaction, agent_key: nil)
+            post("/repos/#{repo}/issues/comments/#{comment_id}/reactions", { content: reaction }, agent_key: agent_key)
+          end
+
+          # POST a reaction on a PR review.
+          #
+          # @param repo [String] "owner/repo"
+          # @param review_id [Integer]
+          # @param reaction [String]
+          # @param agent_key [String, nil] agent key for per-agent app identity
+          # @return [Hash] parsed response
+          def create_review_reaction(repo, review_id, reaction, agent_key: nil)
+            post("/repos/#{repo}/pulls/reviews/#{review_id}/reactions", { content: reaction }, agent_key: agent_key)
+          end
+
+          # GET request to GitHub API.
+          #
+          # @param path [String] API path (e.g. "/repos/owner/repo/pulls/1")
+          # @param agent_key [String, nil] agent key for per-agent app identity
+          # @return [Hash] parsed response
+          def get(path, agent_key: nil)
+            request(:get, path, agent_key: agent_key)
+          end
+
+          # POST request to GitHub API.
+          #
+          # @param path [String] API path
+          # @param body [Hash] request body
+          # @param agent_key [String, nil] agent key for per-agent app identity
+          # @return [Hash] parsed response
+          def post(path, body, agent_key: nil)
+            request(:post, path, body, agent_key: agent_key)
+          end
+
+          # Reset cached tokens (useful for testing or when credentials change).
+          def reset!
+            @mutex.synchronize do
+              @tokens = {}
+            end
+          end
+
+          # Public accessor for installation tokens (used to inject GH_TOKEN into agent env).
+          # Returns the raw token string, or nil on failure.
+          def installation_token_for(agent_key = nil, repo_owner: nil)
+            installation_token(agent_key, repo_owner: repo_owner)
+          rescue StandardError
+            nil
+          end
+
+          private
+
+          def request(method, path, body = nil, agent_key: nil)
+            repo_owner = extract_repo_owner(path)
+            token = installation_token(agent_key, repo_owner: repo_owner)
+            uri = URI("#{GITHUB_API}#{path}")
+
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            http.open_timeout = 10
+            http.read_timeout = 30
+
+            req = case method
+                  when :get
+                    Net::HTTP::Get.new(uri.request_uri)
+                  when :post
+                    Net::HTTP::Post.new(uri.request_uri)
+                  end
+
+            req["Authorization"] = "Bearer #{token}"
+            req["Accept"] = "application/vnd.github+json"
+            req["X-GitHub-Api-Version"] = "2022-11-28"
+            req["User-Agent"] = "Brainiac-GitHub-App"
+            req.body = JSON.generate(body) if body
+            req.content_type = "application/json" if body
+
+            response = http.request(req)
+
+            raise "GitHub API error #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+            JSON.parse(response.body)
+          end
+
+          # Extract the repo owner from an API path like "/repos/stowzilla/brainiac/pulls/1"
+          def extract_repo_owner(path)
+            match = path.match(%r{^/repos/([^/]+)/})
+            match&.[](1)
+          end
+
+          # Generate a short-lived JWT signed with the App's private key.
+          # Used to request an installation access token.
+          def generate_jwt(agent_key = nil)
+            private_key = OpenSSL::PKey::RSA.new(File.read(Config.private_key_path(agent_key)))
+            now = Time.now.to_i
+
+            payload = {
+              iat: now - 60, # issued at (60s clock drift allowance)
+              exp: now + (10 * 60), # expires in 10 minutes (max allowed)
+              iss: Config.app_id(agent_key)
+            }
+
+            JWT.encode(payload, private_key, "RS256")
+          end
+
+          # Fetch or return a cached installation access token.
+          # Tokens are valid for 1 hour; we refresh 60s early.
+          # Cache key includes agent_key and repo_owner for proper scoping.
+          def installation_token(agent_key = nil, repo_owner: nil)
+            inst_id = Config.installation_id(agent_key, repo_owner: repo_owner)
+            raise "No installation ID configured#{" for #{repo_owner}" if repo_owner}" unless inst_id
+
+            cache_key = "#{agent_key || "shared"}-#{inst_id}"
+
+            @mutex.synchronize do
+              cached = @tokens[cache_key]
+              return cached[:token] if cached && Time.now.to_i < cached[:expires_at]
+
+              jwt = generate_jwt(agent_key)
+              uri = URI("#{GITHUB_API}/app/installations/#{inst_id}/access_tokens")
+
+              http = Net::HTTP.new(uri.host, uri.port)
+              http.use_ssl = true
+              http.open_timeout = 10
+              http.read_timeout = 30
+
+              req = Net::HTTP::Post.new(uri.request_uri)
+              req["Authorization"] = "Bearer #{jwt}"
+              req["Accept"] = "application/vnd.github+json"
+              req["X-GitHub-Api-Version"] = "2022-11-28"
+              req["User-Agent"] = "Brainiac-GitHub-App"
+
+              response = http.request(req)
+
+              raise "Failed to get installation token: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+              data = JSON.parse(response.body)
+              token = data["token"]
+              expires_at = Time.parse(data["expires_at"]).to_i - TOKEN_EXPIRY_BUFFER
+
+              @tokens[cache_key] = { token: token, expires_at: expires_at }
+              token
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/cli.rb

@@ -51,10 +51,27 @@ module Brainiac
 
             config = JSON.parse(File.read(config_file))
             secret = config["webhook_secret"]
+            app_config = config["app"] || {}
+
             puts "GitHub Configuration:"
             puts "  Config file: #{config_file}"
             puts "  Webhook secret: #{secret && !secret.empty? ? "#{secret[0..5]}..." : "(not set)"}"
             puts "  Repos: #{config.fetch("repos", {}).keys.join(", ").then { |s| s.empty? ? "(none)" : s }}"
+            puts ""
+            puts "  App Authentication:"
+            if app_config["id"] && !app_config["id"].to_s.empty?
+              puts "    App ID: #{app_config["id"]}"
+              puts "    Private key: #{app_config["private_key_path"] || "(not set)"}"
+              puts "    Installation ID: #{app_config["installation_id"] || "(not set)"}"
+              key_path = app_config["private_key_path"]
+              if key_path && File.exist?(File.expand_path(key_path))
+                puts "    Status: ✅ configured"
+              else
+                puts "    Status: ⚠️  private key file not found"
+              end
+            else
+              puts "    Status: not configured (using gh CLI fallback)"
+            end
           end
 
           def cmd_status

data/lib/brainiac/plugins/github/config.rb

@@ -22,6 +22,7 @@ module Brainiac
 
             @config = load_config
             @last_mtime = File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+            AppClient.reset! if defined?(AppClient)
             LOG.info "[GitHub] Reloaded configuration"
           end
 
@@ -29,8 +30,83 @@ module Brainiac
             @config["webhook_secret"] || ENV.fetch("GITHUB_WEBHOOK_SECRET", nil)
           end
 
+          # Per-agent app credentials from the "apps" hash.
+          # Falls back to the shared "app" config if no per-agent entry exists.
+
+          def app_id(agent_key = nil)
+            per_agent_value(agent_key, "id") ||
+              @config.dig("app", "id")&.to_s ||
+              ENV.fetch("GITHUB_APP_ID", nil)
+          end
+
+          def private_key_path(agent_key = nil)
+            path = per_agent_value(agent_key, "private_key_path") ||
+                   @config.dig("app", "private_key_path") ||
+                   ENV.fetch("GITHUB_APP_PRIVATE_KEY_PATH", nil)
+            return nil unless path
+
+            expanded = File.expand_path(path)
+            File.exist?(expanded) ? expanded : nil
+          end
+
+          def installation_id(agent_key = nil, repo_owner: nil)
+            # Check per-agent config first
+            if agent_key
+              normalized = agent_key.to_s.downcase
+              agent_conf = @config.dig("apps", normalized)
+              if agent_conf
+                # Per-agent may have multiple installations keyed by owner
+                if repo_owner && agent_conf["installations"]
+                  return agent_conf.dig("installations", repo_owner)&.to_s || agent_conf["installation_id"]&.to_s
+                end
+
+                # Flat installation_id
+                return agent_conf["installation_id"]&.to_s if agent_conf["installation_id"]
+
+                # No repo_owner specified but installations hash exists — return first available
+                # (used by configured? check where repo_owner isn't known yet)
+                return agent_conf["installations"].values.first&.to_s if agent_conf["installations"]&.any?
+              end
+            end
+
+            # Shared app config — check installations hash first, then flat installation_id
+            if repo_owner && @config.dig("app", "installations")
+              found = @config.dig("app", "installations", repo_owner)&.to_s
+              return found if found
+            end
+
+            @config.dig("app", "installation_id")&.to_s ||
+              ENV.fetch("GITHUB_APP_INSTALLATION_ID", nil)
+          end
+
+          # Returns the agent key that should be used for a given context.
+          # If per-agent apps are configured and the agent has an entry, returns that key.
+          # Otherwise returns nil (use shared app).
+          def agent_app_configured?(agent_key)
+            return false unless agent_key
+
+            !!@config.dig("apps", agent_key.to_s.downcase)
+          end
+
+          # Check if a repo owner is in the allowed_owners list.
+          # If allowed_owners is not configured (empty/missing), all owners are allowed.
+          def owner_allowed?(owner)
+            allowed = @config["allowed_owners"]
+            return true unless allowed.is_a?(Array) && !allowed.empty?
+
+            allowed.include?(owner)
+          end
+
           private
 
+          def per_agent_value(agent_key, field)
+            return nil unless agent_key
+
+            # Agent names come in as display names ("Galen") but config keys are lowercase ("galen")
+            normalized = agent_key.to_s.downcase
+            @config.dig("apps", normalized, field)&.to_s
+          end
+
           def load_config
             return {} unless File.exist?(CONFIG_FILE)
 

data/lib/brainiac/plugins/github/handler.rb

@@ -35,7 +35,7 @@ module Brainiac
             end
 
             _internal_id, card_info = result
-            card_number = card_info["number"]
+            card_number = extract_card_number(card_info)
             unless card_number
               LOG.warn "Card has no number — can't comment or move"
               return [200, { status: "ignored", reason: "card has no number" }.to_json]
@@ -63,7 +63,7 @@ module Brainiac
             return [200, { status: "ignored", reason: "no matching card" }.to_json] unless result
 
             _internal_id, card_info = result
-            card_number = card_info["number"]
+            card_number = extract_card_number(card_info)
             worktree = card_info["worktree"]
 
             return [200, { status: "ignored", reason: "no worktree" }.to_json] unless worktree && File.directory?(worktree)
@@ -104,17 +104,16 @@ module Brainiac
 
             if result
               _internal_id, card_info = result
-              card_number = card_info["number"]
+              card_number = extract_card_number(card_info)
               unless card_number
                 LOG.warn "Card has no number — can't dispatch review"
                 return [200, { status: "ignored", reason: "card has no number" }.to_json]
               end
-              card_key = "card-#{card_number}"
             else
               card_info = {}
               card_number = nil
-              card_key = "pr-#{repo_name.tr("/", "-")}-#{pr_number}"
             end
+            card_key = "pr-review-#{repo_name.tr("/", "-")}-#{pr_number}"
 
             return [200, { status: "ignored", reason: "session already active" }.to_json] if session_active?(card_key)
 
@@ -135,6 +134,7 @@ module Brainiac
             comment_body = comment["body"] || ""
             comment_id = comment["id"]
             comment_user = comment.dig("user", "login")
+            comment_user_type = comment.dig("user", "type")
             repo_name = payload.dig("repository", "full_name")
 
             unless issue["pull_request"]
@@ -150,29 +150,37 @@ module Brainiac
 
             project_key, project_config = project_result
             pr_number = issue["number"]
+            agent_name = agent_name_for(project_config)
 
-            pr_data = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}", "--jq", "{branch: .head.ref}",
-                              chdir: project_config["repo_path"])
-            branch = JSON.parse(pr_data)["branch"]
+            # Mention detection: if the comment mentions a specific agent, dispatch
+            # that agent instead of the project's default. This enables cross-agent
+            # reviews on PRs.
+            #
+            # Supported syntax (to avoid tagging real GitHub users with @):
+            #   "Threepio, review this"   — name + comma at the start
+            #   "/ask Threepio review"    — /ask Name
+            #   "/Threepio review this"   — /Name
+            #   "@Threepio review this"   — @Name (legacy, works but tags real users)
+            mentioned = detect_github_mention(comment_body)
+            if mentioned && mentioned.downcase != agent_name.downcase && local_agent_names.include?(mentioned)
+              LOG.info "[GitHub] Mention detected: #{mentioned} in PR comment (default agent: #{agent_name})"
+              agent_name = mentioned
+            end
 
+            # Ignore comments from this project's own bot to prevent self-triggering.
+            # Cross-agent bot comments (e.g. GLaDOS commenting on Galen's PR) are still processed.
+            if comment_user_type == "Bot" && own_bot_comment?(comment_user, agent_name)
+              LOG.info "Ignoring self-triggered bot comment from #{comment_user} (agent: #{agent_name})"
+              return [200, { status: "ignored", reason: "self-triggered bot comment" }.to_json]
+            end
+
+            branch = fetch_pr_branch(repo_name, pr_number, agent_name, project_config)
             result = find_work_item_by_branch(branch)
 
-            if result
-              _, card_info = result
-              card_number = card_info["number"]
-              worktree = card_info["worktree"]
+            card_number, worktree = resolve_comment_worktree(result, mentioned, agent_name, pr_number, project_config)
+            return worktree if worktree.is_a?(Array)
 
-              unless worktree && File.directory?(worktree)
-                LOG.info "No active worktree for PR ##{pr_number}, ignoring comment"
-                return [200, { status: "ignored", reason: "no active worktree" }.to_json]
-              end
-
-              card_key = "card-#{card_number}"
-            else
-              card_number = nil
-              worktree = project_config["repo_path"]
-              card_key = "pr-#{repo_name.tr("/", "-")}-#{pr_number}"
-            end
+            card_key = "pr-comment-#{repo_name.tr("/", "-")}-#{pr_number}-#{agent_name.downcase}"
 
             if session_active?(card_key)
               LOG.info "Skipping PR comment on #{card_key} — agent session already active"
@@ -182,7 +190,7 @@ module Brainiac
             card_context = card_number ? " for card ##{card_number}" : ""
             LOG.info "PR comment from #{comment_user} on PR ##{pr_number}#{card_context} (project: #{project_key})"
             dispatch_pr_comment(card_number, card_key, pr_number, comment_id, comment_user, comment_body,
-                                repo_name, worktree, project_key, project_config)
+                                repo_name, worktree, project_key, project_config, agent_name: agent_name)
 
             [200, { status: "processed", card: card_number, pr: pr_number, comment_id: comment_id, project: project_key }.to_json]
           rescue StandardError => e
@@ -245,6 +253,132 @@ module Brainiac
             nil
           end
 
+          # Generate a GH_TOKEN env var for the agent process so `gh` CLI
+          # authenticates as the app bot instead of the user's personal account.
+          # Falls back to the shared "brainiac" app if the agent's own app isn't configured.
+          # Returns empty hash if no app credentials are available at all.
+          def github_agent_env(agent_name, repo_name)
+            # Try agent's own app first, fall back to shared "brainiac" app
+            effective_agent = if AppClient.configured?(agent_name)
+                                agent_name
+                              elsif AppClient.configured?("brainiac")
+                                LOG.info "[GitHub] Agent #{agent_name} has no app configured, falling back to shared brainiac app"
+                                "brainiac"
+                              end
+            return {} unless effective_agent
+
+            repo_owner = repo_name.split("/").first
+            token = AppClient.installation_token_for(effective_agent, repo_owner: repo_owner)
+            return {} unless token
+
+            { "GH_TOKEN" => token }
+          rescue StandardError => e
+            LOG.warn "[GitHub] Could not generate agent token: #{e.message}"
+            {}
+          end
+
+          # Extract the card number from a work item info hash, supporting both
+          # the old flat format ("number") and new source-based format ("sources.fizzy.card_number").
+          def extract_card_number(card_info)
+            card_info["number"] || card_info.dig("sources", "fizzy", "card_number")
+          end
+
+          # Fetch the head branch name of a PR using the GitHub App or `gh` CLI.
+          def fetch_pr_branch(repo_name, pr_number, agent_name, project_config)
+            if AppClient.configured?(agent_name)
+              pr_response = AppClient.get("/repos/#{repo_name}/pulls/#{pr_number}", agent_key: agent_name)
+              pr_response.dig("head", "ref")
+            else
+              pr_data = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}", "--jq", "{branch: .head.ref}",
+                                chdir: project_config["repo_path"])
+              JSON.parse(pr_data)["branch"]
+            end
+          end
+
+          # Resolve the card number and worktree for a PR comment.
+          # Returns [card_number, worktree_path] on success, or a Rack response array
+          # (to be returned early) when the comment should be ignored.
+          def resolve_comment_worktree(result, mentioned, agent_name, pr_number, project_config)
+            return [nil, project_config["repo_path"]] unless result
+
+            _, card_info = result
+            card_number = extract_card_number(card_info)
+            worktree = card_info["worktree"]
+
+            is_mention = mentioned && mentioned.downcase == agent_name.downcase
+            if is_mention
+              worktree = project_config["repo_path"] unless worktree && File.directory?(worktree)
+            else
+              unless worktree && File.directory?(worktree)
+                LOG.info "No active worktree for PR ##{pr_number}, ignoring comment"
+                return [200, { status: "ignored", reason: "no active worktree" }.to_json]
+              end
+            end
+
+            [card_number, worktree]
+          end
+
+          # Detect an agent mention in a GitHub PR comment using syntax that
+          # avoids tagging real GitHub users.
+          #
+          # Supported patterns (case-insensitive):
+          #   "Threepio, review this"        — agent name + comma at the start of text
+          #   "/ask Threepio review"         — /ask followed by agent name
+          #   "/Threepio review this"        — slash followed by agent name
+          #   "@threepio-brainiac review"    — @name-brainiac (matches bot username pattern)
+          #
+          # Returns the display name of the matched agent, or nil.
+          def detect_github_mention(text)
+            return nil if text.nil? || text.strip.empty?
+
+            downcased = text.strip.downcase
+            agent_names = all_agent_names
+
+            agent_names.each do |name|
+              name_lower = name.downcase
+
+              # Pattern: "Name, ..." at the start (vocative)
+              return name if downcased.match?(/\A#{Regexp.escape(name_lower)}\s*,/)
+
+              # Pattern: "/ask Name ..."
+              return name if downcased.match?(%r{\A/ask\s+#{Regexp.escape(name_lower)}\b})
+
+              # Pattern: "/Name ..."
+              return name if downcased.match?(%r{\A/#{Regexp.escape(name_lower)}\b})
+
+              # Pattern: "@Name-brainiac ..." (matches the bot account naming convention)
+              return name if downcased.match?(/@#{Regexp.escape(name_lower)}-brainiac\b/)
+            end
+
+            nil
+          end
+
+          # Check if a bot comment is from the same agent that would handle this PR.
+          # e.g. "galen-brainiac[bot]" is a self-trigger for agent "Galen",
+          # but "glados-brainiac[bot]" is a cross-agent request and should be processed.
+          def own_bot_comment?(bot_login, agent_name)
+            # Bot logins are like "galen-brainiac[bot]" — check if it starts with the agent name
+            normalized_login = bot_login.to_s.downcase.delete_suffix("[bot]")
+            normalized_agent = agent_name.to_s.downcase
+            normalized_login.start_with?(normalized_agent)
+          end
+
+          # Extract PRs array from a work item, supporting both old flat format and new source-based format.
+          def extract_prs(card_info)
+            card_info.dig("sources", "github", "prs") || card_info["prs"] || []
+          end
+
+          # Store PRs in the correct location based on the work item format.
+          def store_prs(card_info, prs)
+            if card_info.key?("sources")
+              card_info["sources"] ||= {}
+              card_info["sources"]["github"] ||= {}
+              card_info["sources"]["github"]["prs"] = prs
+            else
+              card_info["prs"] = prs
+            end
+          end
+
           def process_merged_pr(card_info, card_number, branch, pull_request, pr_url, pr_title, project_key, project_config, repo_path)
             mark_work_item_merged(card_number)
             cleanup_work_item_worktrees(card_number, repo_path: repo_path,
@@ -270,28 +404,33 @@ module Brainiac
             end
 
             internal_id, card_info = result
-            prs = card_info["prs"] || []
+            prs = extract_prs(card_info)
             return if prs.any? { |p| p["number"] == pr_number }
 
             prs << { "number" => pr_number, "url" => pr_url }
-            card_info["prs"] = prs
+            store_prs(card_info, prs)
 
             map = load_work_item_map
             map[internal_id] = card_info
             save_work_item_map(map)
-            LOG.info "[PR Track] Tracked PR ##{pr_number} on card ##{card_info["number"]} (branch: #{branch})"
+            LOG.info "[PR Track] Tracked PR ##{pr_number} on card ##{extract_card_number(card_info)} (branch: #{branch})"
           end
 
           def dispatch_pr_comment(card_number, card_key, pr_number, comment_id, comment_user, comment_body,
-                                  repo_name, worktree, project_key, project_config)
+                                  repo_name, worktree, project_key, project_config, agent_name: nil)
+            agent_name ||= agent_name_for(project_config)
+
             Thread.new do
-              run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/issues/comments/#{comment_id}/reactions",
-                      "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: worktree)
+              if AppClient.configured?(agent_name)
+                AppClient.create_comment_reaction(repo_name, comment_id, "eyes", agent_key: agent_name)
+              else
+                run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/issues/comments/#{comment_id}/reactions",
+                        "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: worktree)
+              end
             rescue StandardError => e
               LOG.warn "Could not add reaction to comment: #{e.message}"
             end
 
-            agent_name = agent_name_for(project_config)
             prompt = render_prompt(Prompts::PR_COMMENT,
                                    { "CARD_NUMBER" => card_number || "PR-#{pr_number}",
                                      "CARD_ID" => card_number || "PR-#{pr_number}",
@@ -301,15 +440,18 @@ module Brainiac
                                                                       project_key: project_key, comment_body: comment_body),
                                    agent_name: agent_name, channel: :github)
 
-            intent_ctx = fetch_pr_intent_context(pr_number, repo_name)
-            pid, log_file = run_agent(prompt, project_config: project_config, chdir: worktree,
-                                              log_name: "pr-comment-#{pr_number}",
-                                              model: detect_model(project_config, text: comment_body),
-                                              effort: detect_effort(project_config, text: comment_body),
-                                              agent_name: agent_name, source: :github,
-                                              source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: worktree },
-                                              message: comment_body, channel: "GitHub PR comment",
-                                              context: intent_ctx)
+            intent_ctx = fetch_pr_intent_context(pr_number, repo_name, agent_name)
+            agent_env = github_agent_env(agent_name, repo_name)
+            run_agent_opts = { project_config: project_config, chdir: worktree,
+                               log_name: "pr-comment-#{pr_number}",
+                               model: detect_model(project_config, text: comment_body),
+                               effort: detect_effort(project_config, text: comment_body),
+                               agent_name: agent_name, source: :github,
+                               source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: worktree },
+                               message: comment_body, channel: "GitHub PR comment",
+                               context: intent_ctx }
+            run_agent_opts[:env] = agent_env if method(:run_agent).parameters.flatten.include?(:env)
+            pid, log_file = run_agent(prompt, **run_agent_opts)
             return unless pid
 
             register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
@@ -318,18 +460,25 @@ module Brainiac
           def dispatch_pr_review(card_number, card_key, card_info, pr_number, review, reviewer,
                                  repo_name, project_key, project_config, repo_path)
             review_id = review["id"]
+            agent_name = agent_name_for(project_config)
+
             Thread.new do
-              run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/pulls/reviews/#{review_id}/reactions",
-                      "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: repo_path)
+              if AppClient.configured?(agent_name)
+                AppClient.create_review_reaction(repo_name, review_id, "eyes", agent_key: agent_name)
+              else
+                run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/pulls/reviews/#{review_id}/reactions",
+                        "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: repo_path)
+              end
+
+              react_to_review_comments(review_id, pr_number, repo_name, repo_path, agent_name)
             rescue StandardError => e
               LOG.warn "Could not add reaction to review: #{e.message}"
             end
 
-            agent_name = agent_name_for(project_config)
             Brainiac.emit(:pr_review_received, card_number: card_number, reviewer: reviewer,
                                                agent_name: agent_name, project_config: project_config, repo_path: repo_path)
 
-            review_context = build_review_context(reviewer, review, pr_number, repo_name)
+            review_context = build_review_context(reviewer, review, pr_number, repo_name, agent_name)
             worktree = card_info["worktree"]
             work_dir = worktree && File.directory?(worktree) ? worktree : repo_path
 
@@ -342,23 +491,26 @@ module Brainiac
                                                                       project_key: project_key),
                                    agent_name: agent_name, channel: :github)
 
-            pid, log_file = run_agent(prompt, project_config: project_config, chdir: work_dir,
-                                              log_name: "review-#{card_number || "pr-#{pr_number}"}",
-                                              agent_name: agent_name,
-                                              source: :github,
-                                              source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: work_dir },
-                                              message: review["body"], channel: "GitHub PR review",
-                                              context: fetch_pr_intent_context(pr_number, repo_name))
+            agent_env = github_agent_env(agent_name, repo_name)
+            run_agent_opts = { project_config: project_config, chdir: work_dir,
+                               log_name: "review-#{card_number || "pr-#{pr_number}"}",
+                               agent_name: agent_name,
+                               source: :github,
+                               source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: work_dir },
+                               message: review["body"], channel: "GitHub PR review",
+                               context: fetch_pr_intent_context(pr_number, repo_name, agent_name) }
+            run_agent_opts[:env] = agent_env if method(:run_agent).parameters.flatten.include?(:env)
+            pid, log_file = run_agent(prompt, **run_agent_opts)
             return unless pid
 
             register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
           end
 
-          def build_review_context(reviewer, review, pr_number, repo_name)
+          def build_review_context(reviewer, review, pr_number, repo_name, agent_key = nil)
             context = "GitHub PR Review from @#{reviewer}:\n\n"
             context += "Review body:\n#{review["body"]}\n\n" if review["body"] && !review["body"].empty?
 
-            review_comments = fetch_pr_review_comments(pr_number, repo_name)
+            review_comments = fetch_pr_review_comments(pr_number, repo_name, agent_key)
             if review_comments.any?
               context += "Line-specific comments:\n"
               review_comments.each do |comment|
@@ -368,25 +520,63 @@ module Brainiac
             context
           end
 
-          def fetch_pr_review_comments(pr_number, repo)
-            output = run_cmd("gh", "api", "/repos/#{repo}/pulls/#{pr_number}/comments",
-                             "--jq", ".[] | {path, line, body, user: .user.login}",
-                             chdir: PROJECTS.values.first&.dig("repo_path") || Dir.pwd)
-            output.lines.map { |line| JSON.parse(line) }
+          def fetch_pr_review_comments(pr_number, repo, agent_key = nil)
+            if AppClient.configured?(agent_key)
+              response = AppClient.get("/repos/#{repo}/pulls/#{pr_number}/comments", agent_key: agent_key)
+              # Response is an array of comment objects
+              response.map { |c| { "path" => c["path"], "line" => c["line"], "body" => c["body"], "user" => c.dig("user", "login") } }
+            else
+              output = run_cmd("gh", "api", "/repos/#{repo}/pulls/#{pr_number}/comments",
+                               "--jq", ".[] | {path, line, body, user: .user.login}",
+                               chdir: PROJECTS.values.first&.dig("repo_path") || Dir.pwd)
+              output.lines.map { |line| JSON.parse(line) }
+            end
           rescue StandardError => e
             LOG.warn "Could not fetch PR review comments: #{e.message}"
             []
           end
 
+          # React with 👀 to each individual comment in a review submission.
+          # This makes reactions visible on line-level file comments, not just the review wrapper.
+          def react_to_review_comments(review_id, pr_number, repo_name, repo_path, agent_key = nil)
+            if AppClient.configured?(agent_key)
+              comments = AppClient.get("/repos/#{repo_name}/pulls/#{pr_number}/reviews/#{review_id}/comments", agent_key: agent_key)
+              comment_ids = comments.map { |c| c["id"] }
+            else
+              output = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}/reviews/#{review_id}/comments",
+                               "--jq", ".[].id", chdir: repo_path)
+              comment_ids = output.lines.map(&:strip).reject(&:empty?)
+            end
+
+            comment_ids.each do |comment_id|
+              if AppClient.configured?(agent_key)
+                AppClient.create_comment_reaction(repo_name, comment_id, "eyes", agent_key: agent_key)
+              else
+                run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/pulls/comments/#{comment_id}/reactions",
+                        "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: repo_path)
+              end
+            end
+          rescue StandardError => e
+            LOG.warn "Could not react to review comments: #{e.message}"
+          end
+
           # Lightweight recent PR comment context for intent classification.
           # Returns "author: message" format (last 5 issue comments on the PR).
-          def fetch_pr_intent_context(pr_number, repo_name)
-            output = run_cmd("gh", "api", "/repos/#{repo_name}/issues/#{pr_number}/comments",
-                             "--jq", ".[-5:] | .[] | \"\\(.user.login): \\(.body[0:200])\"",
-                             chdir: PROJECTS.values.first&.dig("repo_path") || Dir.pwd)
-            return nil if output.strip.empty?
+          def fetch_pr_intent_context(pr_number, repo_name, agent_key = nil)
+            if AppClient.configured?(agent_key)
+              comments = AppClient.get("/repos/#{repo_name}/issues/#{pr_number}/comments", agent_key: agent_key)
+              entries = comments.last(5).map { |c| "#{c.dig("user", "login")}: #{c["body"]&.slice(0, 200)}" }
+              return nil if entries.empty?
+
+              entries.join("\n")
+            else
+              output = run_cmd("gh", "api", "/repos/#{repo_name}/issues/#{pr_number}/comments",
+                               "--jq", ".[-5:] | .[] | \"\\(.user.login): \\(.body[0:200])\"",
+                               chdir: PROJECTS.values.first&.dig("repo_path") || Dir.pwd)
+              return nil if output.strip.empty?
 
-            output.strip
+              output.strip
+            end
           rescue StandardError => e
             LOG.warn "[GitHub] Could not fetch intent context for PR ##{pr_number}: #{e.message}" if defined?(LOG)
             nil

data/lib/brainiac/plugins/github/version.rb

@@ -3,7 +3,7 @@
 module Brainiac
   module Plugins
     module Github
-      VERSION = "0.0.6"
+      VERSION = "0.2.0"
     end
   end
 end

data/lib/brainiac/plugins/github.rb

@@ -4,6 +4,7 @@ require_relative "github/version"
 require_relative "github/metadata"
 require_relative "github/cli"
 require_relative "github/config"
+require_relative "github/app_client"
 require_relative "github/prompts"
 require_relative "github/notifications"
 require_relative "github/handler"
@@ -63,12 +64,17 @@ module Brainiac
 
             work_dir = source_context[:work_dir] || Dir.pwd
             agent_display = ctx[:agent_name] || "Agent"
+            agent_key = ctx[:agent_key]
             snippet = ctx[:snippet]
             snippet_block = snippet ? "\n```\n#{snippet[-1500..]}\n```" : ""
             comment_body = "💥 **#{agent_display} crashed** (exit code #{ctx[:exit_status]})\n\nLog: `#{ctx[:log_file]}`#{snippet_block}"
 
             begin
-              run_cmd("gh", "pr", "comment", pr_number.to_s, "--repo", repo_name, "--body", comment_body, chdir: work_dir)
+              if AppClient.configured?(agent_key)
+                AppClient.create_comment(repo_name, pr_number, comment_body, agent_key: agent_key)
+              else
+                run_cmd("gh", "pr", "comment", pr_number.to_s, "--repo", repo_name, "--body", comment_body, chdir: work_dir)
+              end
               LOG.info "[GitHub] Posted crash comment on PR ##{pr_number}"
             rescue StandardError => e
               LOG.error "[GitHub] Failed to post crash comment: #{e.message}"
@@ -84,11 +90,23 @@ module Brainiac
             request.body.rewind
             payload_body = request.body.read
 
+            # Dedup: GitHub sends X-GitHub-Delivery as a unique ID per webhook delivery.
+            # Drop duplicates (can occur due to threading or retries).
+            delivery_id = request.env["HTTP_X_GITHUB_DELIVERY"]
+            if delivery_id && Brainiac::Plugins::Github.already_delivered?(delivery_id)
+              halt 200, { status: "ignored", reason: "duplicate delivery" }.to_json
+            end
+
             Brainiac::Plugins::Github.verify_signature!(request, payload_body)
 
             payload = JSON.parse(payload_body)
             event = request.env["HTTP_X_GITHUB_EVENT"]
 
+            repo_owner = payload.dig("repository", "owner", "login")
+            if repo_owner && !Brainiac::Plugins::Github::Config.owner_allowed?(repo_owner)
+              halt 403, { error: "Repository owner not in allowed_owners", owner: repo_owner }.to_json
+            end
+
             reload_projects!
             reload_agent_registry!
             Brainiac::Plugins::Github::Config.reload!
@@ -164,6 +182,21 @@ module Brainiac
         computed = "sha256=#{OpenSSL::HMAC.hexdigest("sha256", secret, payload_body)}"
         halt 403, { error: "Invalid GitHub signature" }.to_json unless Rack::Utils.secure_compare(signature, computed)
       end
+
+      # Track recent delivery IDs to prevent duplicate processing.
+      # Thread-safe via Mutex. Keeps last 100 IDs.
+      @recent_deliveries = []
+      @delivery_mutex = Mutex.new
+
+      def self.already_delivered?(delivery_id)
+        @delivery_mutex.synchronize do
+          return true if @recent_deliveries.include?(delivery_id)
+
+          @recent_deliveries << delivery_id
+          @recent_deliveries.shift if @recent_deliveries.size > 100
+          false
+        end
+      end
     end
   end
 end

data/templates/github.json.example

@@ -1,4 +1,11 @@
 {
-  "webhook_secret": "your-github-webhook-secret",
+  "webhook_secret": "",
+  "allowed_owners": [],
+  "apps": {},
+  "app": {
+    "id": "",
+    "private_key_path": "~/.brainiac/github-app-private-key.pem",
+    "installation_id": ""
+  },
   "repos": {}
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac-github
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Davis
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.0.14
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -89,6 +103,7 @@ files:
 - LICENSE
 - README.md
 - lib/brainiac/plugins/github.rb
+- lib/brainiac/plugins/github/app_client.rb
 - lib/brainiac/plugins/github/cli.rb
 - lib/brainiac/plugins/github/config.rb
 - lib/brainiac/plugins/github/handler.rb