superkick 0.1.0

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

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Slack
+      # Watches a Slack channel for new messages and spawns agents.
+      #
+      # Polls `conversations.history` for top-level messages.  Each new
+      # message becomes a spawn event.  When `monitor_thread: true` (the
+      # default), the spawned agent automatically gets a `slack_thread`
+      # monitor that feeds user replies back as injections.
+      #
+      # Config keys:
+      #   channel          (required) — Slack channel ID (e.g. "C0123456789")
+      #   token            (optional) — Bot token, falls back to SLACK_BOT_TOKEN
+      #   channel_name     (optional) — Human-readable name for templates
+      #   filter_pattern   (optional) — Regex; only matching messages trigger spawns
+      #   ignore_bots      (optional, default true) — skip bot messages
+      #   ignore_threads   (optional, default true) — skip threaded replies
+      #   monitor_thread   (optional, default true) — auto-attach slack_thread monitor
+      class Spawner < Superkick::Spawner
+        API_URL = "https://slack.com"
+
+        attr_reader :conn, :seen_ts, :bot_user_id, :user_cache
+
+        def self.type = :slack
+
+        def self.description
+          "Watches a Slack channel for new messages and spawns AI coding " \
+            "agents to handle them. Supports thread monitoring so users " \
+            "can interact with the agent via Slack replies."
+        end
+
+        def self.required_config = %i[channel]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates", "spawn")
+        end
+
+        def self.agent_id(event)
+          "slack-message-#{event[:channel_id]}-#{event[:message_ts].tr(".", "-")}"
+        end
+
+        def self.setup_label = "Slack"
+
+        def self.setup_config
+          <<~YAML
+            slack:
+              type: slack
+              channel: C0123456789               # Slack channel ID
+              token: <%= env("SLACK_BOT_TOKEN") %>
+              # channel_name: general            # for display only
+              # ignore_bots: true                # ignore bot messages (default)
+              # ignore_threads: true             # only top-level messages (default)
+              # monitor_thread: true             # auto-attach thread monitor (default)
+              # filter_pattern: "^!ask "         # regex to filter messages
+              # max_duration: 3600
+          YAML
+        end
+
+        def initialize(name:, config:, handler:, connection: nil)
+          super(name:, config:, handler:)
+          @conn = connection
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @bot_user_id = fetch_bot_user_id
+          @oldest = Time.now.to_f.to_s
+          @seen_ts = Set.new
+          @user_cache = {}
+        end
+
+        def tick
+          messages = fetch_messages
+          messages.each do |msg|
+            event = build_event(msg)
+            attach_spawn_monitors(event, msg)
+            dispatch(event)
+          end
+        end
+
+        private
+
+        def fetch_messages
+          resp = @conn.get("/api/conversations.history") do |req|
+            req.params[:channel] = self[:channel]
+            req.params[:oldest] = @oldest
+            req.params[:limit] = 100
+          end
+
+          handle_response!(resp)
+          data = resp.body
+          return [] unless data[:ok]
+
+          messages = data[:messages] || []
+
+          # Filter bot messages
+          if self[:ignore_bots] != false
+            messages = messages.reject { it[:subtype] == "bot_message" || it[:bot_id] }
+            messages = messages.reject { it[:user] == @bot_user_id } if @bot_user_id
+          end
+
+          # Filter threaded replies (only top-level messages)
+          if self[:ignore_threads] != false
+            messages = messages.reject { it[:thread_ts] && it[:thread_ts] != it[:ts] }
+          end
+
+          # Apply filter_pattern
+          if self[:filter_pattern]
+            pattern = Regexp.new(self[:filter_pattern])
+            messages = messages.select { pattern.match?(it[:text].to_s) }
+          end
+
+          # Within-session dedup
+          new_messages = messages.reject { @seen_ts.include?(it[:ts]) }
+          new_messages.each { @seen_ts.add(it[:ts]) }
+
+          # Advance watermark
+          if messages.any?
+            latest = messages.map { it[:ts] }.max
+            @oldest = latest if latest && latest > @oldest
+          end
+
+          Superkick.logger.info(log_tag) { "Found #{messages.size} messages, #{new_messages.size} new" }
+          new_messages
+        end
+
+        def build_event(msg)
+          user_name = resolve_user_name(msg[:user])
+
+          sender = UserDrop.new(
+            id: msg[:user],
+            name: user_name
+          )
+
+          channel = ChannelDrop.new(
+            id: self[:channel],
+            name: self[:channel_name]
+          )
+
+          message = MessageDrop.new(
+            text: msg[:text].to_s,
+            sender:,
+            channel:,
+            message_ts: msg[:ts],
+            thread_ts: msg[:ts]
+          )
+
+          {
+            event_type: :slack_message,
+            channel_id: self[:channel],
+            channel_name: self[:channel_name] || self[:channel],
+            message_ts: msg[:ts],
+            slack_thread_ts: msg[:ts],
+            user: msg[:user],
+            user_name:,
+            text: msg[:text].to_s,
+            message:,
+            sender:,
+            channel:
+          }
+        end
+
+        def attach_spawn_monitors(event, _msg)
+          return unless self[:monitor_thread] != false
+
+          token = self[:token] || ENV["SLACK_BOT_TOKEN"]
+          event[:_spawn_monitors] = {
+            slack_thread: {
+              type: :slack_thread,
+              channel_id: self[:channel],
+              thread_ts: event[:message_ts],
+              token:
+            }
+          }
+
+          # Auto-attach a per-agent Slack notifier so lifecycle updates
+          # and agent events flow back to the originating Slack thread.
+          event[:_spawn_notifiers] = {
+            slack_thread: {
+              type: :slack,
+              token:,
+              channel: self[:channel],
+              thread_ts: event[:message_ts]
+            }
+          }
+        end
+
+        def resolve_user_name(user_id)
+          return nil unless user_id
+          return @user_cache[user_id] if @user_cache.key?(user_id)
+
+          resp = @conn.get("/api/users.info") do |req|
+            req.params[:user] = user_id
+          end
+
+          if resp.status == 200 && resp.body[:ok]
+            name = resp.body.dig(:user, :profile, :display_name)
+            name = resp.body.dig(:user, :real_name) if name.to_s.empty?
+            name = resp.body.dig(:user, :name) if name.to_s.empty?
+            @user_cache[user_id] = name || user_id
+          else
+            @user_cache[user_id] = user_id
+          end
+
+          @user_cache[user_id]
+        rescue => e
+          Superkick.logger.debug(log_tag) { "Could not resolve user #{user_id}: #{e.message}" }
+          @user_cache[user_id] = user_id
+        end
+
+        def fetch_bot_user_id
+          resp = @conn.get("/api/auth.test")
+          return nil unless resp.status == 200 && resp.body[:ok]
+
+          resp.body[:user_id]
+        rescue => e
+          Superkick.logger.warn(log_tag) { "Could not fetch bot identity: #{e.message}" }
+          nil
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299
+            # Slack API returns 200 for most errors; check :ok field in caller
+            nil
+          when 401, 403
+            raise FatalError, "Slack auth failed (HTTP #{resp.status})"
+          when 429
+            raise RateLimited, "Slack rate limited"
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["SLACK_BOT_TOKEN"]
+
+          Faraday.new(url: API_URL) do |f|
+            f.request :authorization, "Bearer", token if token
+            f.request :json
+            f.response :json, parser_options: {symbolize_names: true}
+            f.options.timeout = 10
+            f.options.open_timeout = 10
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/slack/templates/default.liquid

@@ -0,0 +1,17 @@
+{% header %}{{ event_type | event_emoji }} {{ event_type | format_title }}{% endheader %}
+{% section %}{{ message }}{% endsection %}
+{% capture meta %}
+{% if agent_id %}*Agent:* `{{ agent_id }}`
+{% endif %}
+{% if monitor %}*Monitor:* {{ monitor.name }}
+*Type:* {{ monitor.type }}
+{% endif %}
+{% if team %}*Team:* `{{ team.id }}`
+{% endif %}
+{% if agent.role %}*Role:* {{ agent.role }}
+{% endif %}
+{% if spawner %}*Spawner:* {{ spawner.name }}
+{% endif %}
+{% endcapture %}
+{% if meta != blank %}{% context %}{{ meta | join_present: " | " }}{% endcontext %}{% endif %}
+{{ message }}

data/lib/superkick/integrations/slack/templates/slack_reply.liquid

@@ -0,0 +1,3 @@
+SUPERKICK [{{ "now" | time }}]: Slack reply from {{ user_name }}
+
+{{ text }}

data/lib/superkick/integrations/slack/templates/spawn/slack_message.liquid

@@ -0,0 +1,10 @@
+SUPERKICK [{{ "now" | time }}]: Slack message from {{ user_name }} in {{ channel_name }}
+
+## Message
+
+{{ text }}
+
+Please read the message carefully and work on the request. If the user
+provided specific instructions, follow them. If you need clarification,
+use superkick_post_update to communicate your progress or questions.
+When you are done, use superkick_signal_goal to signal completion.

data/lib/superkick/integrations/slack/thread_monitor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Slack
+      # Polls a Slack thread for new replies and injects them into the agent.
+      #
+      # Typically auto-attached by the Slack spawner via `_spawn_monitors`
+      # when `monitor_thread: true`.  Each new reply from a human user
+      # becomes a high-priority injection event.
+      #
+      # Config keys (injected at spawn time):
+      #   channel_id  (required) — Slack channel ID
+      #   thread_ts   (required) — Root message timestamp
+      #   token       (optional) — Bot token, falls back to SLACK_BOT_TOKEN
+      class ThreadMonitor < Superkick::Monitor
+        API_URL = "https://slack.com"
+
+        attr_reader :conn, :seen_ts, :bot_user_id
+
+        def self.type = :slack_thread
+
+        def self.description
+          "Polls a Slack thread for new replies and injects them as " \
+            "high-priority prompts into the agent."
+        end
+
+        def self.required_config = %i[channel_id thread_ts]
+
+        def self.templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def initialize(name:, config:, handler:, agent: nil, server_context: {}, connection: nil)
+          super(name:, config:, handler:, agent:, server_context:)
+          @conn = connection
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @bot_user_id = fetch_bot_user_id
+          @oldest = self[:thread_ts]
+          @seen_ts = Set.new([self[:thread_ts]])
+          @user_cache = {}
+        end
+
+        def tick
+          replies = fetch_replies
+          replies.each do |reply|
+            user_name = resolve_user_name(reply[:user])
+            sender = Slack::UserDrop.new(id: reply[:user], name: user_name)
+            channel = Slack::ChannelDrop.new(id: self[:channel_id])
+
+            dispatch(
+              event_type: :slack_reply,
+              user: reply[:user],
+              user_name:,
+              text: reply[:text].to_s,
+              message_ts: reply[:ts],
+              sender:,
+              channel:,
+              injection_priority: :high,
+              injection_ttl: 900
+            )
+          end
+        end
+
+        private
+
+        def fetch_replies
+          resp = @conn.get("/api/conversations.replies") do |req|
+            req.params[:channel] = self[:channel_id]
+            req.params[:ts] = self[:thread_ts]
+            req.params[:oldest] = @oldest
+            req.params[:limit] = 100
+          end
+
+          handle_response!(resp)
+          data = resp.body
+          return [] unless data[:ok]
+
+          messages = data[:messages] || []
+
+          # Skip bot's own messages
+          if @bot_user_id
+            messages = messages.reject { it[:user] == @bot_user_id }
+          end
+          messages = messages.reject { it[:subtype] == "bot_message" || it[:bot_id] }
+
+          # Within-session dedup
+          new_replies = messages.reject { @seen_ts.include?(it[:ts]) }
+          new_replies.each { @seen_ts.add(it[:ts]) }
+
+          # Advance watermark
+          if messages.any?
+            latest = messages.map { it[:ts] }.max
+            @oldest = latest if latest && latest > @oldest
+          end
+
+          Superkick.logger.info(log_tag) { "Found #{new_replies.size} new replies" }
+          new_replies
+        end
+
+        def resolve_user_name(user_id)
+          return nil unless user_id
+          return @user_cache[user_id] if @user_cache.key?(user_id)
+
+          resp = @conn.get("/api/users.info") do |req|
+            req.params[:user] = user_id
+          end
+
+          if resp.status == 200 && resp.body[:ok]
+            name = resp.body.dig(:user, :profile, :display_name)
+            name = resp.body.dig(:user, :real_name) if name.to_s.empty?
+            name = resp.body.dig(:user, :name) if name.to_s.empty?
+            @user_cache[user_id] = name || user_id
+          else
+            @user_cache[user_id] = user_id
+          end
+
+          @user_cache[user_id]
+        rescue => e
+          Superkick.logger.debug(log_tag) { "Could not resolve user #{user_id}: #{e.message}" }
+          @user_cache[user_id] = user_id
+        end
+
+        def fetch_bot_user_id
+          resp = @conn.get("/api/auth.test")
+          return nil unless resp.status == 200 && resp.body[:ok]
+
+          resp.body[:user_id]
+        rescue => e
+          Superkick.logger.warn(log_tag) { "Could not fetch bot identity: #{e.message}" }
+          nil
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then nil
+          when 401, 403 then raise FatalError, "Slack auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Slack rate limited"
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["SLACK_BOT_TOKEN"]
+
+          Faraday.new(url: API_URL) do |f|
+            f.request :authorization, "Bearer", token if token
+            f.request :json
+            f.response :json, parser_options: {symbolize_names: true}
+            f.options.timeout = 10
+            f.options.open_timeout = 10
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/slack.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "slack/drops"
+require_relative "slack/notifier"
+require_relative "slack/spawner"
+require_relative "slack/thread_monitor"
+
+module Superkick
+  Notifier.register(Integrations::Slack::Notifier)
+  Spawner.register(Integrations::Slack::Spawner)
+  Monitor.register(Integrations::Slack::ThreadMonitor)
+end

data/lib/superkick/liquid.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Liquid — includable DSL for declaring Liquid customizations on monitors,
+  # spawners, and notifiers. Provides `liquid do ... end` class-level DSL.
+  #
+  # Usage:
+  #
+  #   class MyMonitor < Monitor
+  #     liquid do
+  #       filter :pr_ref do |number, title = nil|
+  #         title ? "##{number} \"#{title}\"" : "##{number}"
+  #       end
+  #     end
+  #   end
+  #
+  #   class MyNotifier < Notifier
+  #     liquid do
+  #       context do
+  #         attribute :blocks, default: -> { [] }
+  #         attribute :text
+  #       end
+  #
+  #       block :header do |ctx, content|
+  #         ctx.blocks << { type: "header", text: content }
+  #       end
+  #     end
+  #   end
+  module Liquid
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def liquid(&definition)
+        @liquid_config = Config.new
+        @liquid_config.instance_eval(&definition)
+        @liquid_config.freeze
+      end
+
+      def liquid_config
+        @liquid_config || Config::EMPTY
+      end
+    end
+
+    # Config — captures DSL declarations (filters, context class, blocks).
+    # Immutable after freeze.
+    class Config
+      attr_reader :filters, :context_class, :blocks, :tags
+
+      def initialize
+        @filters = {}
+        @context_class = nil
+        @blocks = {}
+        @tags = {}
+      end
+
+      # Declare an inline filter. Generates a Liquid filter module behind the scenes.
+      def filter(name, &handler)
+        @filters[name] = handler
+      end
+
+      # Declare the context class for block tag accumulation.
+      # Without a block: sets a pre-existing class.
+      # With a block: builds an anonymous context class with attribute DSL.
+      def context(klass = nil, &definition)
+        if klass
+          @context_class = klass
+        elsif definition
+          @context_class = Context.build(&definition)
+        end
+      end
+
+      # Declare a Liquid block tag.
+      def block(name, &handler)
+        @blocks[name] = handler
+      end
+
+      # Declare a bodyless Liquid tag (no end tag required).
+      # Handler receives (accumulator, attributes).
+      def tag(name, &handler)
+        @tags[name] = handler
+      end
+
+      def freeze
+        @filters.freeze
+        @blocks.freeze
+        @tags.freeze
+        super
+      end
+
+      EMPTY = new.freeze
+    end
+
+    # Context — builder for anonymous context classes used as block tag
+    # accumulators. Builds a class with declared attributes and defaults.
+    class Context
+      def self.build(&definition)
+        builder = new
+        builder.instance_eval(&definition)
+        builder.build_class
+      end
+
+      def initialize
+        @attributes = {}
+      end
+
+      def attribute(name, default: nil)
+        @attributes[name] = default
+      end
+
+      def build_class
+        attrs = @attributes.dup
+        Class.new do
+          attrs.each_key do |name|
+            attr_accessor name
+          end
+
+          define_method(:initialize) do
+            attrs.each do |name, default|
+              value = default.respond_to?(:call) ? default.call : default
+              instance_variable_set(:"@#{name}", value)
+            end
+          end
+        end
+      end
+    end
+  end
+end