superkick 0.1.0

data/lib/superkick/injector.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Superkick
+  # Orchestrates a single injection attempt by sending a rendered prompt to
+  # the agent's InjectionQueue via the buffer client.
+  #
+  # The server no longer checks preconditions (idle state, guards) — the
+  # agent's InjectionQueue handles all gating locally with zero latency.
+  #
+  # Returns :enqueued or :skipped.
+  class Injector
+    def initialize(store:, notification_dispatcher:, buffer_client: nil, config: Superkick.config)
+      @store = store
+      @config = config
+      @notification_dispatcher = notification_dispatcher
+      @buffer_client = buffer_client || Buffer.client_from(store:, config:)
+    end
+
+    def inject(agent_id:, event:)
+      unless @buffer_client.reachable?(agent_id)
+        Superkick.logger.debug("injector") { "Agent #{agent_id} not reachable — skipping" }
+        return :skipped
+      end
+
+      prompt_text = TemplateRenderer.render(event)
+
+      @buffer_client.send_command(agent_id, "enqueue_injection",
+        id: SecureRandom.uuid,
+        prompt: prompt_text,
+        monitor_type: event[:monitor_type],
+        monitor_name: event[:monitor_name],
+        priority: event[:injection_priority] || :normal,
+        ttl: event[:injection_ttl] || monitor_ttl(event),
+        supersede_key: event[:injection_supersede_key])
+
+      Superkick.logger.info("injector") { "Enqueued #{event[:event_type]} for agent #{agent_id}" }
+      :enqueued
+    rescue => e
+      Superkick.logger.error("injector") { "Injection error for #{agent_id}: #{e.message}\n#{e.backtrace.first(5).join("\n")}" }
+      :error
+    end
+
+    private
+
+    def monitor_ttl(event)
+      # Allow per-monitor TTL override via monitor config
+      agent_id = event[:agent_id]
+      monitor_name = event[:monitor_name]
+
+      if agent_id && monitor_name
+        agent = @store.get(agent_id)
+        config = agent&.monitor_config(monitor_name)
+        return config[:injection_ttl] if config&.dig(:injection_ttl)
+      end
+
+      InjectionQueue::DEFAULT_TTL
+    end
+
+    def dispatch_notification(...)
+      @notification_dispatcher.dispatch(...)
+    end
+  end
+end

data/lib/superkick/input_buffer.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Thread-safe buffer that tracks the user's current partial (unsubmitted)
+  # input and any active injection guards.
+  #
+  # Raw terminal byte sequences handled:
+  #   - Printable UTF-8 chars → append to buffer
+  #   - \x03 (C-c)            → clear buffer, clear submit-on-clear guards
+  #   - \r outside paste mode → clear buffer, clear submit-on-clear guards
+  #   - \r inside paste mode  → treated as \n (pasted newline, not submit)
+  #   - \x7f / \x08           → backspace (remove last char)
+  #   - \x1b[200~ / \x1b[201~ → bracketed paste start/end markers
+  #   - Other ANSI escapes    → discarded (not stored in buffer)
+  class InputBuffer
+    def initialize
+      @mutex = Mutex.new
+      @buffer = "".dup
+      @paste_mode = false
+      # guards: { name_string => { reason: String, clear_on_submit: bool } }
+      @guards = {}
+    end
+
+    # Feed raw bytes from the terminal into the buffer.
+    def append(bytes)
+      bytes = bytes.dup.force_encoding(Encoding::BINARY)
+
+      @mutex.synchronize do
+        i = 0
+        while i < bytes.bytesize
+          b = bytes.byteslice(i, 1)
+
+          # Bracketed paste start: ESC [ 2 0 0 ~
+          if bytes.byteslice(i, 6) == "\x1b[200~"
+            @paste_mode = true
+            i += 6
+            next
+          end
+
+          # Bracketed paste end: ESC [ 2 0 1 ~
+          if bytes.byteslice(i, 6) == "\x1b[201~"
+            @paste_mode = false
+            i += 6
+            next
+          end
+
+          # ANSI / escape sequences
+          if b == "\x1b"
+            nxt = bytes.byteslice(i + 1, 1)
+            if nxt == "["
+              # CSI sequence: skip parameter bytes then one final byte
+              j = i + 2
+              j += 1 while j < bytes.bytesize && bytes.byteslice(j, 1) =~ /[0-9;]/
+              i = j + 1
+            elsif nxt == "]"
+              # OSC: skip until BEL (\x07) or ST (ESC \); advance j past the terminator
+              j = i + 2
+              loop do
+                break if j >= bytes.bytesize
+                if bytes.byteslice(j, 1) == "\x07"
+                  j += 1  # skip BEL
+                  break
+                end
+                if bytes.byteslice(j, 1) == "\x1b" && bytes.byteslice(j + 1, 1) == "\\"
+                  j += 2  # skip ESC \
+                  break
+                end
+                j += 1
+              end
+              i = j
+            else
+              # Two-byte escape — skip
+              i += 2
+            end
+            next
+          end
+
+          ord = b.ord
+
+          # C-c → submit (clear buffer + guards)
+          if ord == 0x03
+            @buffer = "".dup
+            clear_submit_guards!
+            i += 1
+            next
+          end
+
+          # CR → submit outside paste, newline inside paste
+          if ord == 0x0D
+            if @paste_mode
+              @buffer << "\n"
+            else
+              @buffer = "".dup
+              clear_submit_guards!
+            end
+            i += 1
+            next
+          end
+
+          # Backspace / DEL
+          if ord == 0x7F || ord == 0x08
+            @buffer.chop! unless @buffer.empty?
+            i += 1
+            next
+          end
+
+          # Printable (including high UTF-8 bytes)
+          if ord >= 0x20
+            char_len = utf8_char_byte_length(ord)
+            @buffer << bytes.byteslice(i, char_len).force_encoding(Encoding::UTF_8)
+            i += char_len
+            next
+          end
+
+          # Everything else — skip
+          i += 1
+        end
+      end
+    end
+
+    # Returns the current partial input string (copy).
+    def contents
+      @mutex.synchronize { @buffer.dup }
+    end
+
+    # Unconditionally clears the buffer (called by Buffer::Server on inject).
+    def clear
+      @mutex.synchronize do
+        @buffer = "".dup
+        @paste_mode = false
+      end
+    end
+
+    # --- Injection guards --------------------------------------------------
+
+    def set_guard(name, reason, clear_on_submit: true)
+      @mutex.synchronize do
+        @guards[name.to_s] = {reason:, clear_on_submit:}
+      end
+    end
+
+    def clear_guard(name)
+      @mutex.synchronize { @guards.delete(name.to_s) }
+    end
+
+    # Returns { name_string => reason_string } for active guards.
+    def guards
+      @mutex.synchronize do
+        @guards.transform_values { it[:reason] }
+      end
+    end
+
+    def guards_active?
+      @mutex.synchronize { !@guards.empty? }
+    end
+
+    private
+
+    def clear_submit_guards!
+      @guards.reject! { |_, v| v[:clear_on_submit] }
+    end
+
+    def utf8_char_byte_length(first_byte_ord)
+      if first_byte_ord >= 0xF0 then 4
+      elsif first_byte_ord >= 0xE0 then 3
+      elsif first_byte_ord >= 0xC0 then 2
+      else 1
+      end
+    end
+  end
+end

data/lib/superkick/integrations/bugsnag/README.md

@@ -0,0 +1,98 @@
+# Bugsnag Spawner
+
+Type: `:bugsnag`
+
+Watches Bugsnag for open errors and spawns AI coding agents to fix them. Polls
+the Bugsnag Data Access API for errors matching configurable filters (severity,
+release stage, error class, version, minimum event count).
+
+Errors are tracked by ID to prevent re-dispatching. Errors that fail client-side
+filters (e.g. below `minimum_events`) are retried on subsequent ticks so they
+fire once the threshold is crossed.
+
+## Configuration
+
+```yaml
+spawners:
+  bugsnag:
+    type: bugsnag
+    project_id: "abc123def456"
+    token: <%= env("BUGSNAG_TOKEN") %>
+    driver: claude_code
+    severity:
+      - error
+    release_stage: production
+    minimum_events: 5
+    error_classes:
+      include:
+        - NoMethodError
+        - RuntimeError
+      exclude:
+        - Net::ReadTimeout
+    versions:
+      - latest
+    filters:
+      app.release_stage:
+        - production
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `project_id` | yes | — | Bugsnag project ID |
+| `token` | no | `$BUGSNAG_TOKEN` | Bugsnag API auth token |
+| `severity` | no | `["error"]` | Severity filter (array or include/exclude hash) |
+| `release_stage` | no | `"production"` | Release stage name |
+| `minimum_events` | no | `1` | Minimum event count before dispatching |
+| `error_classes` | no | — | Error class filter (array or include/exclude hash) |
+| `versions` | no | — | Version filter (array or include/exclude hash; `"latest"` resolves via releases API) |
+| `filters` | no | — | Additional Bugsnag API filter fields (hash, passed through directly) |
+
+### List filter format
+
+The `severity`, `error_classes`, and `versions` keys accept two formats:
+
+- **Array** — treated as an include list: `["error", "warning"]`
+- **Hash** — explicit include/exclude: `{ include: ["error"], exclude: ["info"] }`
+
+Include filters are applied server-side (via the Bugsnag API). Exclude filters
+are applied client-side after fetching.
+
+## Agent ID format
+
+```
+bugsnag-error-{error_id}
+```
+
+Where `error_id` is the Bugsnag error ID. Dedup is handled by `AgentStore` —
+if an agent with the same ID already exists, the spawn is skipped.
+
+## Events
+
+### `error_opened`
+
+Dispatched when a new open error is found that passes all filters.
+
+Template variables:
+
+| Variable | Description |
+|----------|-------------|
+| `error_id` | Bugsnag error ID |
+| `error_class` | Exception class name (e.g. `NoMethodError`) |
+| `message` | Error message string |
+| `severity` | Severity level (`error`, `warning`, `info`) |
+| `status` | Bugsnag error status (e.g. `open`) |
+| `events` | Total event count |
+| `users` | Number of affected users |
+| `first_seen` | Timestamp of first occurrence |
+| `last_seen` | Timestamp of most recent occurrence |
+| `release_stages` | Array of release stages where the error was seen |
+| `url` | Bugsnag dashboard URL for this error |
+| `project_url` | Bugsnag dashboard URL for the project |
+| `project_id` | Bugsnag project ID |
+
+## Error handling
+
+- **401/403** — raises `FatalError`, stops the spawner (authentication failure)
+- **429** — raises `RateLimited`, backs off per the standard poller backoff
+- **404** — logged as warning, skipped (resource not found)
+- Other HTTP errors — logged as warning, skipped

data/lib/superkick/integrations/bugsnag/spawner.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Superkick
+  module Integrations
+    module Bugsnag
+      # Watches Bugsnag for open errors and spawns AI coding agents to fix them.
+      #
+      # Polls the Bugsnag Data Access API for errors matching configurable filters
+      # (severity, release stage, error class, event count, version).  Tracks
+      # dispatched error IDs in-memory to avoid re-dispatching.  Errors that
+      # fail client-side filters (e.g. below minimum_events) are retried on
+      # subsequent ticks so they fire once the threshold is crossed.
+      #
+      # Config keys:
+      #   project_id       (required) — Bugsnag project ID
+      #   token            (optional) — API auth token, falls back to $BUGSNAG_TOKEN
+      #   severity         (optional) — array or include/exclude hash, default ["error"]
+      #   release_stage    (optional) — release stage name, default "production"
+      #   minimum_events   (optional) — minimum event count to dispatch, default 1
+      #   error_classes    (optional) — array or include/exclude hash
+      #   versions         (optional) — array or include/exclude hash; "latest" resolves to newest release
+      #   filters          (optional) — hash of additional Bugsnag API filter fields
+      #
+      # List filter configs (severity, error_classes, versions) accept either form:
+      #   - Array  → treated as include list:  ["error", "warning"]
+      #   - Hash   → include/exclude keys:    { include: ["error"], exclude: ["info"] }
+      class Spawner < Superkick::Spawner
+        attr_reader :conn
+
+        API_BASE = "https://api.bugsnag.com"
+        DEFAULT_SEVERITY = %w[error].freeze
+        DEFAULT_RELEASE_STAGE = "production"
+        DEFAULT_MINIMUM_EVENTS = 1
+        PER_PAGE = 30
+
+        def self.type = :bugsnag
+
+        def self.description
+          "Watches Bugsnag for open errors and spawns AI coding agents to " \
+            "fix them. Supports filtering by severity, release stage, error " \
+            "class, version, and minimum event count."
+        end
+
+        def self.required_config = %i[project_id]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "bugsnag-error-#{event[:error_id]}"
+        end
+
+        def self.setup_label = "Bugsnag"
+
+        def self.setup_config
+          <<~YAML
+            bugsnag:
+              type: bugsnag
+              project_id: "abc123def456"
+              token: <%= env("BUGSNAG_TOKEN") %>
+              # severity:                        # error severities to watch (default: [error])
+              #   - error
+              # release_stage: production         # default
+              # minimum_events: 1                 # minimum occurrences before spawning
+              # max_duration: 3600
+          YAML
+        end
+
+        def initialize(name:, config:, handler:, connection: nil)
+          super(name:, config:, handler:)
+          @conn = connection
+        end
+
+        def tick
+          errors = fetch_errors
+          errors.each do |error|
+            next if filtered_by_severity?(error)
+            next if filtered_by_error_class?(error)
+            next if filtered_by_minimum_events?(error)
+
+            # Mark as seen only after passing all filters — an error below
+            # minimum_events today may cross the threshold on a future tick.
+            @seen_error_ids.add(error["id"])
+
+            dispatch(
+              event_type: :error_opened,
+              error_id: error["id"],
+              error_class: error["error_class"],
+              message: error["message"].to_s,
+              severity: error["severity"],
+              status: error["status"],
+              events: error["events"],
+              users: error["users_affected"] || error["users"],
+              first_seen: error["first_seen"],
+              last_seen: error["last_seen"],
+              release_stages: error["release_stages"],
+              url: error["url"],
+              project_url: error["project_url"],
+              project_id: self[:project_id]
+            )
+          end
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @seen_error_ids = Set.new
+          @latest_version = nil
+        end
+
+        private
+
+        # -- Bugsnag errors API ---------------------------------------------------
+
+        def fetch_errors
+          project_id = self[:project_id]
+          params = build_params
+
+          path = "/projects/#{project_id}/errors"
+          Superkick.logger.debug(log_tag) { "Fetching errors: #{path} #{params.inspect}" }
+
+          resp = get(path, params)
+          return [] unless resp
+
+          errors = resp.body
+          return [] unless errors.is_a?(Array)
+
+          # Filter out already-dispatched errors.  New IDs are added to
+          # @seen_error_ids in tick, after client-side filters pass, so an
+          # error that was skipped (e.g. below minimum_events) gets retried.
+          new_errors = errors.reject { @seen_error_ids.include?(it["id"]) }
+
+          Superkick.logger.info(log_tag) { "Found #{errors.size} errors, #{new_errors.size} new" }
+          new_errors
+        end
+
+        def build_params
+          params = {
+            "sort" => "last_seen",
+            "direction" => "desc",
+            "status" => "open",
+            "per_page" => PER_PAGE.to_s
+          }
+
+          filters = build_filters
+          params["filters"] = JSON.generate(filters) unless filters.empty?
+
+          params
+        end
+
+        def build_filters
+          filters = {}
+
+          # Severity filter
+          sev = normalize_filter(self[:severity], default_include: DEFAULT_SEVERITY)
+          if sev[:include].any?
+            filters["event.severity"] = sev[:include].map { {type: "eq", value: it} }
+          end
+
+          # Release stage filter
+          stage = self[:release_stage]
+          stage = DEFAULT_RELEASE_STAGE if stage.nil?
+          if stage && !stage.empty?
+            filters["app.release_stage"] = [{type: "eq", value: stage}]
+          end
+
+          # Version filter (resolve "latest" to actual version string)
+          ver = normalize_filter(self[:versions])
+          if ver[:include].any?
+            resolved = resolve_versions(ver[:include])
+            if resolved.any?
+              filters["version.seen_in"] = resolved.map { {type: "eq", value: it} }
+            end
+          end
+
+          # Error class include filter (server-side)
+          ec = normalize_filter(self[:error_classes])
+          if ec[:include].any?
+            filters["event.class"] = ec[:include].map { {type: "eq", value: it} }
+          end
+
+          # Merge in user-provided passthrough filters
+          if self[:filters].is_a?(Hash)
+            self[:filters].each do |field, values|
+              values = Array(values)
+              filters[field.to_s] = values.map { {type: "eq", value: it} }
+            end
+          end
+
+          filters
+        end
+
+        def resolve_versions(versions)
+          versions.flat_map do |v|
+            if v.to_s.downcase == "latest"
+              latest = fetch_latest_version
+              latest ? [latest] : []
+            else
+              [v.to_s]
+            end
+          end
+        end
+
+        def fetch_latest_version
+          return @latest_version if @latest_version
+
+          resp = get("/projects/#{self[:project_id]}/releases", {"per_page" => "1"})
+          return nil unless resp
+
+          releases = resp.body
+          return nil unless releases.is_a?(Array) && releases.any?
+
+          @latest_version = releases.first["release_group"] || releases.first["version"]
+          Superkick.logger.debug(log_tag) { "Resolved latest version: #{@latest_version}" }
+          @latest_version
+        rescue => e
+          Superkick.logger.warn(log_tag) { "Could not fetch latest version: #{e.message}" }
+          nil
+        end
+
+        # -- Client-side filters --------------------------------------------------
+
+        def filtered_by_severity?(error)
+          excludes = normalize_filter(self[:severity])[:exclude]
+          return false unless excludes.any?
+
+          excludes.include?(error["severity"].to_s)
+        end
+
+        def filtered_by_error_class?(error)
+          excludes = normalize_filter(self[:error_classes])[:exclude]
+          return false unless excludes.any?
+
+          excludes.include?(error["error_class"].to_s)
+        end
+
+        def filtered_by_version?(error)
+          excludes = normalize_filter(self[:versions])[:exclude]
+          return false unless excludes.any?
+
+          # Version info isn't directly on the error object from the list endpoint,
+          # so version exclude is best-effort via the seen_in field if available.
+          seen_in = error["seen_in_versions"] || []
+          seen_in.any? { excludes.include?(it) }
+        end
+
+        def filtered_by_minimum_events?(error)
+          min = self[:minimum_events] || DEFAULT_MINIMUM_EVENTS
+          count = error["events"] || 0
+          count < min
+        end
+
+        # -- Filter normalization -------------------------------------------------
+
+        # Accepts either an Array (treated as include-only) or a Hash with
+        # :include / :exclude keys.  Returns { include: [...], exclude: [...] }.
+        def normalize_filter(value, default_include: [])
+          case value
+          when Array
+            {include: value, exclude: []}
+          when Hash
+            {include: Array(value[:include]), exclude: Array(value[:exclude])}
+          else
+            {include: default_include, exclude: []}
+          end
+        end
+
+        # -- HTTP -----------------------------------------------------------------
+
+        def get(path, params = {})
+          resp = @conn.get(path) do |req|
+            params.each { |k, v| req.params[k] = v }
+          end
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        # Returns true on success, raises on auth/rate-limit, returns false on 404.
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Bugsnag auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Bugsnag rate limited"
+          when 404
+            Superkick.logger.warn(log_tag) { "Bugsnag 404: resource not found" }
+            false
+          else
+            Superkick.logger.warn(log_tag) { "Bugsnag HTTP #{resp.status}" }
+            false
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["BUGSNAG_TOKEN"]
+
+          Faraday.new(url: API_BASE) do |f|
+            f.request :authorization, "token", token if token
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/bugsnag/templates/error_opened.liquid

@@ -0,0 +1,17 @@
+SUPERKICK [{{ "now" | time }}]: Bugsnag error — {{ error_class }}
+{% if url -%}
+URL: {{ url }}
+{% endif -%}
+Severity: {{ severity }} | Events: {{ events }}{% if users %} | Users: {{ users }}{% endif %}
+First seen: {{ first_seen }} | Last seen: {{ last_seen }}
+{% if release_stages.size > 0 -%}
+Release stages: {{ release_stages | join: ", " }}
+{% endif -%}
+
+## Error
+
+**{{ error_class }}**: {% if message == "" %}(no message){% else %}{{ message }}{% endif %}
+
+Please investigate this error, identify the root cause, implement a fix, and
+write tests to prevent regression. Check the Bugsnag dashboard for full stack
+traces and contextual data.

data/lib/superkick/integrations/bugsnag.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "bugsnag/spawner"
+
+module Superkick
+  Spawner.register(Integrations::Bugsnag::Spawner)
+end