superkick 0.1.0

data/lib/superkick/integrations/github/goal.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "octokit"
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Goal that checks whether a GitHub PR has been merged.
+      #
+      # All config keys are optional — repo and branch are auto-detected from the
+      # git working directory when not provided.  The working_dir is injected by
+      # AgentSpawner at spawn time.
+      #
+      # Configuration:
+      #   goal:
+      #     type: github_pr_merged
+      #     repo: org/my-repo          # optional, inferred from git remote
+      #     token: ghp_xxx             # optional, falls back to GITHUB_TOKEN
+      #     check_interval: 120
+      class PrMergedGoal < Superkick::Goal
+        GITHUB_SSH_RE = %r{github\.com[:/](?<repo>[^/]+/[^\s.]+)}
+        GITHUB_HTTPS_RE = %r{github\.com/(?<repo>[^/\s]+/[^\s.]+)}
+
+        def self.type = :github_pr_merged
+
+        def self.description
+          "Polls GitHub to check whether a PR has been merged. Repo and branch " \
+            "are auto-detected from the git working directory when not provided."
+        end
+
+        def initialize(config:, agent_id:)
+          super
+          @cached_repo = nil
+          @cached_pr_number = config[:pr_number]
+        end
+
+        def check
+          repo = resolve_repo
+          return :pending unless repo
+
+          if @cached_pr_number
+            check_pr(repo, @cached_pr_number)
+          else
+            branch = resolve_branch
+            return :pending unless branch
+
+            find_and_check_pr(repo, branch)
+          end
+        rescue Octokit::TooManyRequests
+          Superkick.logger.warn("goal:github_pr_merged") { "Rate limited for #{agent_id}" }
+          :errored
+        rescue Octokit::Unauthorized => e
+          Superkick.logger.error("goal:github_pr_merged") { "Auth failed for #{agent_id}: #{e.message}" }
+          :errored
+        rescue => e
+          Superkick.logger.error("goal:github_pr_merged") { "Check failed for #{agent_id}: #{e.message}" }
+          :errored
+        end
+
+        def teardown
+          @client = nil
+        end
+
+        private
+
+        def check_pr(repo, number)
+          pr = client.pull_request(repo, number)
+          pr_state(pr)
+        end
+
+        def find_and_check_pr(repo, branch)
+          owner = repo.split("/").first
+          prs = client.pull_requests(repo, state: "all", head: "#{owner}:#{branch}")
+          pr = prs.first
+          return :pending unless pr
+
+          @cached_pr_number = pr.number
+          pr_state(pr)
+        end
+
+        def pr_state(pr)
+          if pr.merged_at
+            :completed
+          elsif pr.state == "closed"
+            :failed
+          else
+            :in_progress
+          end
+        end
+
+        def resolve_repo
+          @cached_repo ||= config[:repo] || detect_repo
+        end
+
+        def resolve_branch
+          config[:branch] || detect_branch
+        end
+
+        def detect_repo
+          out = run_git("remote", "-v")
+          return nil unless out
+
+          out.each_line do |line|
+            m = GITHUB_SSH_RE.match(line) || GITHUB_HTTPS_RE.match(line)
+            return m[:repo].delete_suffix(".git") if m
+          end
+
+          nil
+        end
+
+        def detect_branch
+          out = run_git("symbolic-ref", "--short", "HEAD")&.strip
+          out unless out&.empty?
+        end
+
+        def run_git(*args)
+          dir = config[:working_dir] || Dir.pwd
+          IO.popen(["git", "-C", dir, *args], err: File::NULL) { |io| io.read }
+        rescue SystemCallError, IOError => e
+          Superkick.logger.debug("goal:github_pr_merged") { "git failed: #{e.message}" }
+          nil
+        end
+
+        def client
+          @client ||= begin
+            token = config[:token] || ENV["GITHUB_TOKEN"]
+            Octokit::Client.new(access_token: token)
+          end
+        end
+      end
+    end
+  end
+end
+
+Superkick::Goal.register(Superkick::Integrations::GitHub::PrMergedGoal)

data/lib/superkick/integrations/github/issue_goal.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "octokit"
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Goal that checks whether a GitHub issue has been closed.
+      #
+      # Any close reason (completed, not_planned) counts as success — the
+      # requirement is simply that the issue is resolved.
+      #
+      # Configuration:
+      #   goal:
+      #     type: github_issue_resolved
+      #     repo: org/my-repo             # optional, inferred from git remote
+      #     token: ghp_xxx                # optional, falls back to GITHUB_TOKEN
+      #
+      # The issue is injected from the event context via AgentSpawner.
+      # AgentSpawner rehydrates the serialized context and merges it into goal
+      # config, so config[:issue] is an IssueDrop with .number, .title, etc.
+      class IssueResolvedGoal < Superkick::Goal
+        GITHUB_SSH_RE = PrMergedGoal::GITHUB_SSH_RE
+        GITHUB_HTTPS_RE = PrMergedGoal::GITHUB_HTTPS_RE
+
+        def self.type = :github_issue_resolved
+
+        def self.description
+          "Polls GitHub to check whether an issue has been closed. " \
+            "Any close reason counts as success."
+        end
+
+        def self.required_config = %i[]
+
+        def check
+          repo = resolve_repo
+          return :pending unless repo
+
+          issue_number = resolve_issue_number
+          return :pending unless issue_number
+
+          issue = client.issue(repo, issue_number)
+
+          case issue.state
+          when "closed" then :completed
+          else :in_progress
+          end
+        rescue Octokit::TooManyRequests
+          Superkick.logger.warn("goal:github_issue_resolved") { "Rate limited for #{agent_id}" }
+          :errored
+        rescue Octokit::Unauthorized => e
+          Superkick.logger.error("goal:github_issue_resolved") { "Auth failed for #{agent_id}: #{e.message}" }
+          :errored
+        rescue => e
+          Superkick.logger.error("goal:github_issue_resolved") { "Check failed for #{agent_id}: #{e.message}" }
+          :errored
+        end
+
+        def teardown
+          @client = nil
+        end
+
+        private
+
+        def resolve_issue_number
+          @cached_issue_number ||= config[:issue]&.number
+        end
+
+        def resolve_repo
+          @cached_repo ||= config[:repo] || detect_repo
+        end
+
+        def detect_repo
+          out = run_git("remote", "-v")
+          return nil unless out
+
+          out.each_line do |line|
+            m = GITHUB_SSH_RE.match(line) || GITHUB_HTTPS_RE.match(line)
+            return m[:repo].delete_suffix(".git") if m
+          end
+
+          nil
+        end
+
+        def run_git(*args)
+          dir = config[:working_dir] || Dir.pwd
+          IO.popen(["git", "-C", dir, *args], err: File::NULL) { |io| io.read }
+        rescue SystemCallError, IOError => e
+          Superkick.logger.debug("goal:github_issue_resolved") { "git failed: #{e.message}" }
+          nil
+        end
+
+        def client
+          @client ||= begin
+            token = config[:token] || ENV["GITHUB_TOKEN"]
+            Octokit::Client.new(access_token: token)
+          end
+        end
+      end
+    end
+  end
+end
+
+Superkick::Goal.register(Superkick::Integrations::GitHub::IssueResolvedGoal)

data/lib/superkick/integrations/github/issue_spawner.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "octokit"
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Watches GitHub for newly created or reopened issues and spawns agents.
+      #
+      # Polls the GitHub Issues API with configurable filters (labels, assignee,
+      # milestone, creator).  Uses an updated_at watermark so reopened issues are
+      # caught automatically.
+      #
+      # Config keys:
+      #   repo              (required) — owner/name
+      #   token             (optional) — falls back to GITHUB_TOKEN
+      #   labels            (optional) — array of label names (AND filter)
+      #   assignee          (optional) — username, "*" (any), or "none"
+      #   milestone         (optional) — milestone number, "*", or "none"
+      #   creator           (optional) — filter by issue creator
+      #   exclude_pull_requests (optional, default true) — filter out PRs
+      class IssueSpawner < Superkick::Spawner
+        attr_reader :seen_issue_ids, :client
+
+        def initialize(name:, config:, handler:, client: nil)
+          super(name:, config:, handler:)
+          @client = client
+        end
+
+        def self.type = :github_issues
+
+        def self.description
+          "Watches GitHub for newly created or reopened issues and spawns " \
+            "AI coding agents to work on them. Supports filtering by labels, " \
+            "assignee, milestone, and creator."
+        end
+
+        def self.required_config = %i[repo]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "github-issue-#{event[:repo].tr("/", "-")}-#{event[:issue].number}"
+        end
+
+        def self.setup_label = "GitHub Issues"
+
+        def self.setup_config
+          <<~YAML
+            github_issues:
+              type: github_issues
+              repo: org/repo
+              token: <%= env("GITHUB_TOKEN") %>
+              # labels:                          # only issues with ALL of these labels
+              #   - bug
+              # assignee: "*"                    # "*" = assigned, "none" = unassigned, or a username
+              # milestone: v1.0
+              # max_duration: 3600               # hard timeout in seconds
+              # cooldown: 300                    # minimum seconds between spawns
+              # on_complete:
+              #   spawner: review_pr             # chain to another spawner on success
+          YAML
+        end
+
+        def tick
+          issues = fetch_issues
+          issues.each do |issue|
+            dispatch(
+              event_type: :issue_opened,
+              repo: self[:repo],
+              issue: IssueDrop.new({
+                number: issue.number,
+                title: issue.title,
+                body: issue.body.to_s,
+                url: issue.html_url,
+                author: issue.user.login,
+                labels: issue.labels.map(&:name),
+                assignees: issue.assignees.map(&:login),
+                milestone: issue.milestone&.title,
+                created_at: issue.created_at.to_s,
+                updated_at: issue.updated_at.to_s
+              })
+            )
+          end
+        rescue Octokit::TooManyRequests => e
+          raise RateLimited, e.message
+        rescue Octokit::Unauthorized => e
+          raise FatalError, "GitHub auth failed: #{e.message}"
+        rescue Octokit::NotFound => e
+          Superkick.logger.warn(log_tag) { "GitHub resource not found: #{e.message}" }
+        end
+
+        def on_start
+          @client ||= build_client
+          @seen_issue_ids = Set.new
+          @since = Time.now.utc
+        end
+
+        private
+
+        def fetch_issues
+          params = {
+            state: "open",
+            sort: "updated",
+            direction: "asc",
+            since: @since.iso8601
+          }
+
+          params[:labels] = self[:labels].join(",") if self[:labels]&.any?
+          params[:assignee] = self[:assignee] if self[:assignee]
+          params[:milestone] = self[:milestone] if self[:milestone]
+          params[:creator] = self[:creator] if self[:creator]
+
+          all_issues = @client.list_issues(self[:repo], **params)
+
+          # GitHub's issues endpoint includes PRs; filter them out by default
+          exclude_prs = self[:exclude_pull_requests] != false
+          if exclude_prs
+            all_issues = all_issues.reject { it.respond_to?(:pull_request) && it.pull_request }
+          end
+
+          # Within-session dedup
+          new_issues = all_issues.reject { @seen_issue_ids.include?(it.number) }
+          new_issues.each { @seen_issue_ids.add(it.number) }
+
+          # Advance watermark
+          if all_issues.any?
+            latest = all_issues.map(&:updated_at).compact.max
+            @since = latest if latest && latest > @since
+          end
+
+          Superkick.logger.info(log_tag) { "Found #{all_issues.size} issues, #{new_issues.size} new" }
+          new_issues
+        end
+
+        def build_client
+          token = self[:token] || ENV["GITHUB_TOKEN"]
+
+          Octokit::Client.new(
+            access_token: token,
+            middleware: faraday_stack
+          )
+        end
+
+        def faraday_stack
+          Faraday::RackBuilder.new do |builder|
+            builder.request :retry,
+              max: 3,
+              interval: 0.5,
+              backoff_factor: 2,
+              exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
+            builder.adapter Faraday.default_adapter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/github/monitor.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "octokit"
+require "time"
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Polls GitHub CI check runs and PR activity for a registered agent.
+      #
+      # Required per-agent config keys: branch, repo
+      # Optional config key: token (or GITHUB_TOKEN env var)
+      #
+      # Events emitted: ci_failure, ci_success, pr_comment, pr_review
+      # Watermarks persisted to registry: last_comment_id, last_review_id,
+      #                                   last_ci_sha, last_ci_status
+      class Monitor < Superkick::Monitor
+        GITHUB_SSH_RE = %r{github\.com[:/](?<repo>[^/]+/[^\s.]+)}
+        GITHUB_HTTPS_RE = %r{github\.com/(?<repo>[^/\s]+/[^\s.]+)}
+
+        attr_reader :client
+
+        def initialize(name:, config:, handler:, agent: nil, server_context: {}, client: nil)
+          super(name:, config:, handler:, agent:, server_context:)
+          @client = client
+        end
+
+        def self.type = :github
+
+        def self.description
+          "Monitors GitHub pull requests for CI status changes, new comments, and code reviews. " \
+            "Injects context when CI fails, new PR comments arrive, or reviews are submitted. " \
+            "Requires a repo (org/name) and branch. Optionally accepts a token for private repos " \
+            "(or set GITHUB_TOKEN env var)."
+        end
+
+        def self.required_config = %i[branch repo]
+
+        def self.setup_label = "GitHub"
+
+        def self.setup_config
+          <<~YAML
+            github:
+              token: <%= env("GITHUB_TOKEN") %>
+              # repo and branch are auto-detected from git remote.
+              # Uncomment to override:
+              # repo: org/repo
+              # branch: main
+          YAML
+        end
+
+        def self.templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        # Fill in missing branch and repo from the agent's environment snapshot.
+        def self.resolve_config(config, environment: {})
+          config[:branch] ||= environment[:git_branch]
+          config[:repo] ||= parse_github_repo(environment[:git_remotes])
+          config
+        end
+
+        # Extract org/repo from git remote URLs.
+        def self.parse_github_repo(remotes)
+          return nil unless remotes
+
+          remotes.each do |remote|
+            url = remote[:url].to_s
+            m = GITHUB_SSH_RE.match(url) || GITHUB_HTTPS_RE.match(url)
+            return m[:repo].delete_suffix(".git") if m
+          end
+
+          nil
+        end
+
+        def tick
+          branch = self[:branch]
+          repo = self[:repo]
+
+          check_ci(repo, branch)
+          check_pr_comments(repo, branch)
+          check_pr_reviews(repo, branch)
+        rescue Octokit::TooManyRequests => e
+          raise RateLimited, e.message
+        rescue Octokit::Unauthorized => e
+          raise FatalError, "GitHub auth failed: #{e.message}"
+        rescue Octokit::NotFound => e
+          Superkick.logger.warn(log_tag) { "GitHub resource not found: #{e.message}" }
+        end
+
+        def on_start
+          @client ||= build_client
+        end
+
+        private
+
+        # ── CI checks ──────────────────────────────────────────────────────────
+
+        def check_ci(repo, branch)
+          sha = head_sha(repo, branch)
+          return unless sha
+
+          # Avoid re-reporting the same SHA
+          last_sha = self[:last_ci_sha]
+          last_status = self[:last_ci_status]
+
+          runs = @client.check_runs_for_ref(repo, sha, accept: "application/vnd.github+json")
+          checks = runs.check_runs
+
+          return if checks.empty?
+
+          # Consider all completed
+          completed = checks.select { |c| c.status == "completed" }
+          return unless completed.size == checks.size
+
+          current_status = (completed.all? { |c| c.conclusion == "success" }) ? "success" : "failure"
+
+          # Only fire if status changed or it's a new SHA
+          return if sha == last_sha && current_status == last_status
+
+          @agent.set_monitor_field(@name, :last_ci_sha, sha)
+          @agent.set_monitor_field(@name, :last_ci_status, current_status)
+
+          # Reload config to pick up persisted watermarks
+          @config[:last_ci_sha] = sha
+          @config[:last_ci_status] = current_status
+
+          failed = completed.reject { |c| c.conclusion == "success" }
+          event_type = (current_status == "success") ? :ci_success : :ci_failure
+
+          dispatch(
+            event_type:,
+            repo:,
+            branch:,
+            sha:,
+            failed_checks: failed.map(&:name),
+            check_count: checks.size,
+            injection_supersede_key: "ci_status",
+            **((event_type == :ci_success) ? {injection_ttl: 60} : {})
+          )
+        end
+
+        def head_sha(repo, branch)
+          @client.branch(repo, branch).commit.sha
+        rescue Octokit::NotFound
+          nil
+        end
+
+        # ── PR comments ────────────────────────────────────────────────────────
+
+        def check_pr_comments(repo, branch)
+          pr = open_pr(repo, branch)
+          return unless pr
+
+          last_id = self[:last_comment_id]&.to_i || 0
+          comments = @client.issue_comments(repo, pr.number)
+
+          new_comments = comments.select { |c| c.id > last_id }
+          return if new_comments.empty?
+
+          # Persist the highest seen comment ID
+          max_id = new_comments.map(&:id).max
+          @agent.set_monitor_field(@name, :last_comment_id, max_id)
+          @config[:last_comment_id] = max_id
+
+          new_comments.each do |comment|
+            dispatch(
+              event_type: :pr_comment,
+              repo:,
+              branch:,
+              pull_request: PullRequestDrop.new({
+                number: pr.number,
+                title: pr.title
+              }),
+              comment: CommentDrop.new({
+                author: comment.user.login,
+                body: comment.body.to_s.strip,
+                url: comment.html_url
+              })
+            )
+          end
+        end
+
+        # ── PR reviews ─────────────────────────────────────────────────────────
+
+        def check_pr_reviews(repo, branch)
+          pr = open_pr(repo, branch)
+          return unless pr
+
+          last_id = self[:last_review_id]&.to_i || 0
+          reviews = @client.pull_request_reviews(repo, pr.number)
+
+          new_reviews = reviews.select { |r| r.id > last_id && r.state != "PENDING" }
+          return if new_reviews.empty?
+
+          max_id = new_reviews.map(&:id).max
+          @agent.set_monitor_field(@name, :last_review_id, max_id)
+          @config[:last_review_id] = max_id
+
+          new_reviews.each do |review|
+            dispatch(
+              event_type: :pr_review,
+              repo:,
+              branch:,
+              pull_request: PullRequestDrop.new({
+                number: pr.number,
+                title: pr.title
+              }),
+              review: ReviewDrop.new({
+                author: review.user.login,
+                state: review.state,
+                body: review.body.to_s.strip,
+                url: review.html_url
+              }),
+              **((review.state == "CHANGES_REQUESTED") ? {injection_priority: :high} : {})
+            )
+          end
+        end
+
+        # Memoize the open PR for this branch within a single tick.
+        def open_pr(repo, branch)
+          @open_pr_cache ||= {}
+          @open_pr_cache[branch] ||= begin
+            prs = @client.pull_requests(repo, state: "open", head: "#{repo.split("/").first}:#{branch}")
+            prs.first
+          end
+        end
+
+        def build_client
+          token = self[:token] || ENV["GITHUB_TOKEN"]
+
+          Octokit::Client.new(
+            access_token: token,
+            middleware: faraday_stack
+          )
+        end
+
+        def faraday_stack
+          Faraday::RackBuilder.new do |builder|
+            builder.request :retry,
+              max: 3,
+              interval: 0.5,
+              backoff_factor: 2,
+              exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
+            builder.adapter Faraday.default_adapter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/github/probe.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module GitHub
+      # Detects a GitHub repository from the agent's environment snapshot and
+      # returns the monitor config needed to start a Monitor for this agent.
+      class Monitor::Probe < Superkick::Monitor::Probe
+        def self.type = :github
+
+        def self.description
+          "Detects GitHub repository and current branch from git remote configuration."
+        end
+
+        def self.environment_actions
+          [{action: :git_branch}, {action: :git_remotes}]
+        end
+
+        # @param environment [Hash] environment data from the agent
+        # @return [Hash] { github: { type: "github", branch: …, repo: … } } or {}
+        def self.detect(environment:)
+          config = Monitor.resolve_config({}, environment:)
+          return {} unless config[:branch] && config[:repo]
+
+          {github: config.merge(type: "github")}
+        end
+      end
+    end
+  end
+end