superkick 0.1.0

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Slack
+      # Liquid Drop for a Slack message. Wraps the symbol-keyed hash built
+      # by Slack::Spawner so templates can use {{ message.text }},
+      # {{ message.sender.tag }}, {{ message.channel.ref }}, etc.
+      # Embeds UserDrop and ChannelDrop as nested drops for composition.
+      # Survives workflow context serialization via drop_type.
+      class MessageDrop < Superkick::Drop
+        def self.drop_type = "slack_message"
+
+        def text = @data[:text]
+
+        def sender = @data[:sender]
+
+        def channel = @data[:channel]
+
+        def message_ts = @data[:message_ts]
+
+        def thread_ts = @data[:thread_ts]
+
+        # Formatted reference: "@user_name in #channel"
+        def ref
+          sender_name = sender&.name || "unknown"
+          channel_ref = channel&.ref || "#unknown"
+          "@#{sender_name} in #{channel_ref}"
+        end
+      end
+
+      # Liquid Drop for a Slack user. Used in thread monitor events
+      # so templates can use {{ sender.name }}, {{ sender.tag }}.
+      class UserDrop < Superkick::Drop
+        def self.drop_type = "slack_user"
+
+        def id = @data[:id]
+
+        def name = @data[:name]
+
+        # Formatted tag: "Display Name (<@U123>)"
+        def tag
+          display = name || id || "unknown"
+          user_id = id
+          user_id ? "#{display} (<@#{user_id}>)" : display
+        end
+      end
+
+      # Liquid Drop for a Slack channel. Used in spawner and thread monitor
+      # events so templates can use {{ channel.name }}, {{ channel.ref }}.
+      class ChannelDrop < Superkick::Drop
+        def self.drop_type = "slack_channel"
+
+        def id = @data[:id]
+
+        def name = @data[:name]
+
+        # Formatted reference: "#channel-name" or the raw ID if no name.
+        def ref
+          channel_name = name || id
+          "##{channel_name}"
+        end
+      end
+    end
+  end
+end
+
+Superkick::Drop.register(Superkick::Integrations::Slack::MessageDrop)
+Superkick::Drop.register(Superkick::Integrations::Slack::UserDrop)
+Superkick::Drop.register(Superkick::Integrations::Slack::ChannelDrop)

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

@@ -0,0 +1,426 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Slack
+      # Posts a message to Slack when an injection or lifecycle event occurs.
+      #
+      # Supports two authentication modes:
+      #
+      #   1. Incoming Webhook — simplest setup, posts to a single channel:
+      #        notifications:
+      #          - type: slack
+      #            webhook_url: <%= env("SLACK_WEBHOOK_URL") %>
+      #
+      #   2. Web API (chat.postMessage) — can target any channel:
+      #        notifications:
+      #          - type: slack
+      #            token: <%= env("SLACK_BOT_TOKEN") %>
+      #            channel: "#superkick-notifications"
+      #
+      # Messages use Block Kit for rich formatting with a plain-text
+      # fallback in the top-level `text` field.
+      #
+      # Template support:
+      #   Block Kit structure is defined via Liquid templates with custom
+      #   block tags and bodyless tags covering all Block Kit block types.
+      #
+      #   Block tags: {% header %}, {% section %}, {% context %}, {% image %},
+      #   {% button %}, {% fields %}, {% rich_text %}, {% video %}, {% input %}
+      #
+      #   Bodyless tags: {% divider %}, {% file %}
+      #
+      #   Consecutive {% button %} tags auto-group into one actions block.
+      #
+      #   Templates also have access to the `event_emoji`, `format_title`,
+      #   and `join_present` filters for event type formatting.
+      #
+      #   Templates are resolved from:
+      #     1. ~/.superkick/templates/notifications/slack/<event_type>.liquid
+      #     2. <bundled>/templates/<event_type>.liquid
+      #     3. ~/.superkick/templates/notifications/slack/default.liquid
+      #     4. <bundled>/templates/default.liquid
+      #
+      # Thread correlation (Web API only):
+      #   When using the Web API, the notifier is stateful and tracks
+      #   `thread_ts` per agent. The first message for an agent creates
+      #   a new thread; subsequent events reply to that thread. This keeps
+      #   the channel clean when many agents are active. Webhook mode
+      #   cannot thread (Slack webhooks don't return a `ts`), so messages
+      #   are standalone.
+      class Notifier < Superkick::Notifier
+        def self.type = :slack
+
+        def self.templates_dir = File.expand_path("templates", __dir__)
+
+        def self.setup_label = "Slack"
+
+        def self.setup_config
+          <<~YAML
+            # Slack — choose one authentication mode:
+
+            # Option 1: Incoming Webhook (single channel, no token needed)
+            - type: slack
+              webhook_url: <%= env("SLACK_WEBHOOK_URL") %>
+
+            # Option 2: Web API (any channel, supports threading)
+            # - type: slack
+            #   token: <%= env("SLACK_BOT_TOKEN") %>
+            #   channel: "#superkick-notifications"
+            #   # events:                        # restrict which events fire
+            #   #   - agent_completed
+            #   #   - agent_failed
+            #   #   - agent_blocked
+          YAML
+        end
+
+        WEBHOOK_TIMEOUT = 10
+        API_URL = "https://slack.com"
+
+        EMOJI_MAP = {
+          "agent_spawned" => ":rocket:",
+          "agent_completed" => ":white_check_mark:",
+          "agent_failed" => ":x:",
+          "agent_timed_out" => ":hourglass:",
+          "agent_blocked" => ":warning:",
+          "agent_stalled" => ":zzz:",
+          "agent_terminated" => ":stop_sign:",
+          "agent_claimed" => ":raised_hand:",
+          "agent_unclaimed" => ":wave:",
+          "agent_pending_approval" => ":eyes:",
+          "workflow_triggered" => ":gear:",
+          "workflow_iterations_exceeded" => ":no_entry:",
+          "budget_warning" => ":money_with_wings:",
+          "budget_exceeded" => ":moneybag:",
+          "team_created" => ":busts_in_silhouette:",
+          "team_completed" => ":trophy:",
+          "team_failed" => ":boom:",
+          "team_timed_out" => ":hourglass_flowing_sand:",
+          "worker_spawned" => ":construction_worker:",
+          "teammate_message" => ":speech_balloon:",
+          "teammate_blocker" => ":octagonal_sign:",
+          "attach_promoted" => ":arrow_up:",
+          "attach_demoted" => ":arrow_down:",
+          "attach_idle_timeout" => ":zzz:",
+          "attach_force_takeover" => ":rotating_light:",
+          "agent_update" => ":memo:",
+          "artifact_published" => ":package:"
+        }.freeze
+
+        # Keyword-to-emoji mapping for fuzzy matching on unknown event types.
+        # Checked in order — first keyword found in the event type string wins.
+        KEYWORD_EMOJI = [
+          ["completed", ":white_check_mark:"],
+          ["succeeded", ":white_check_mark:"],
+          ["passed", ":white_check_mark:"],
+          ["failed", ":x:"],
+          ["errored", ":x:"],
+          ["error", ":x:"],
+          ["timed_out", ":hourglass:"],
+          ["timeout", ":hourglass:"],
+          ["warning", ":warning:"],
+          ["blocked", ":warning:"],
+          ["stalled", ":zzz:"],
+          ["spawned", ":rocket:"],
+          ["created", ":busts_in_silhouette:"],
+          ["started", ":rocket:"],
+          ["terminated", ":stop_sign:"],
+          ["stopped", ":stop_sign:"],
+          ["exceeded", ":no_entry:"],
+          ["triggered", ":gear:"],
+          ["message", ":speech_balloon:"],
+          ["approved", ":white_check_mark:"],
+          ["rejected", ":no_entry:"],
+          ["deployed", ":rocket:"],
+          ["merged", ":white_check_mark:"]
+        ].freeze
+
+        def self.event_emoji(event_type)
+          type_str = event_type.to_s
+          return EMOJI_MAP[type_str] if EMOJI_MAP.key?(type_str)
+
+          KEYWORD_EMOJI.each do |keyword, emoji|
+            return emoji if type_str.include?(keyword)
+          end
+
+          ":bell:"
+        end
+
+        liquid do
+          context do
+            attribute :blocks, default: -> { [] }
+          end
+
+          filter :event_emoji do |event_type|
+            Superkick::Integrations::Slack::Notifier.event_emoji(event_type)
+          end
+
+          filter :format_title do |event_type|
+            event_type.to_s.tr("_", " ").gsub(/\b\w/, &:upcase)
+          end
+
+          filter :join_present do |input, delimiter = " | "|
+            input.to_s.split("\n").map(&:strip).reject(&:empty?).join(delimiter)
+          end
+
+          block :header do |ctx, text, _attrs|
+            ctx.blocks << {type: "header", text: {type: "plain_text", text:, emoji: true}}
+          end
+
+          block :section do |ctx, text, _attrs|
+            ctx.blocks << {type: "section", text: {type: "mrkdwn", text:}}
+          end
+
+          block :context do |ctx, text, _attrs|
+            ctx.blocks << {type: "context", elements: [{type: "mrkdwn", text:}]}
+          end
+
+          tag :divider do |ctx, _attrs|
+            ctx.blocks << {type: "divider"}
+          end
+
+          block :image do |ctx, text, attrs|
+            block = {
+              type: "image",
+              image_url: attrs["url"],
+              alt_text: attrs["alt_text"] || ""
+            }
+            block[:title] = {type: "plain_text", text:, emoji: true} unless text.empty?
+            ctx.blocks << block
+          end
+
+          block :button do |ctx, text, attrs|
+            element = {
+              type: "button",
+              text: {type: "plain_text", text:, emoji: true}
+            }
+            element[:url] = attrs["url"] if attrs["url"]
+            element[:action_id] = attrs["action_id"] if attrs["action_id"]
+            element[:value] = attrs["value"] if attrs["value"]
+            element[:style] = attrs["style"] if attrs["style"]
+
+            # Auto-group: consecutive buttons share one actions block
+            if ctx.blocks.last&.dig(:type) == "actions"
+              ctx.blocks.last[:elements] << element
+            else
+              ctx.blocks << {type: "actions", elements: [element]}
+            end
+          end
+
+          block :fields do |ctx, text, _attrs|
+            field_texts = text.split("\n").map(&:strip).reject(&:empty?)
+            fields = field_texts.map { {type: "mrkdwn", text: it} }
+            ctx.blocks << {type: "section", fields:}
+          end
+
+          block :rich_text do |ctx, text, _attrs|
+            ctx.blocks << {
+              type: "rich_text",
+              elements: [{
+                type: "rich_text_section",
+                elements: [{type: "text", text:}]
+              }]
+            }
+          end
+
+          block :video do |ctx, text, attrs|
+            block = {
+              type: "video",
+              title: {type: "plain_text", text:, emoji: true},
+              video_url: attrs["url"],
+              thumbnail_url: attrs["thumbnail_url"] || "",
+              alt_text: attrs["alt_text"] || ""
+            }
+            block[:description] = {type: "plain_text", text: attrs["description"]} if attrs["description"]
+            ctx.blocks << block
+          end
+
+          tag :file do |ctx, attrs|
+            ctx.blocks << {
+              type: "file",
+              external_id: attrs["external_id"],
+              source: attrs["source"] || "remote"
+            }
+          end
+
+          block :input do |ctx, text, attrs|
+            element = {type: attrs["type"] || "plain_text_input"}
+            element[:action_id] = attrs["action_id"] if attrs["action_id"]
+            if attrs["placeholder"]
+              element[:placeholder] = {type: "plain_text", text: attrs["placeholder"]}
+            end
+
+            block = {
+              type: "input",
+              label: {type: "plain_text", text:, emoji: true},
+              element:
+            }
+            block[:dispatch_action] = true if attrs["dispatch_action"] == "true"
+            ctx.blocks << block
+          end
+        end
+
+        def initialize(webhook_url: nil, token: nil, channel: nil, thread_ts: nil, connection: nil, **opts)
+          super(**opts)
+          @webhook_url = webhook_url
+          @token = token
+          @channel = channel
+          @initial_thread_ts = thread_ts
+          @connection = connection
+        end
+
+        # Stateful when using the Web API — tracks thread_ts per agent.
+        # Webhook mode cannot thread (no ts in response), so it's effectively stateless.
+        def stateful? = !!(@token && @channel)
+
+        def agent_finished(agent_id:)
+          @state_store.delete(:slack, agent_id.to_s)
+        end
+
+        def notify(payload)
+          body = build_body(payload)
+
+          if @webhook_url
+            post_webhook(body)
+          elsif @token && @channel
+            thread_key = payload.dig(:context, :team)&.id || payload[:agent_id]
+            seed_thread_ts = payload.dig(:context, :slack_thread_ts)
+            post_api(body, agent_id: payload[:agent_id], thread_key:, seed_thread_ts:)
+          else
+            Superkick.logger.warn("notifier:slack") { "No webhook_url or token+channel configured" }
+          end
+        rescue => e
+          Superkick.logger.warn("notifier:slack") { "Failed: #{e.message}" }
+        end
+
+        private
+
+        def post_webhook(body)
+          uri = URI.parse(@webhook_url)
+          conn = @connection || build_connection(url: "#{uri.scheme}://#{uri.host}")
+          response = conn.post(uri.request_uri) do |req|
+            req.body = body
+          end
+
+          unless (200..299).cover?(response.status)
+            Superkick.logger.warn("notifier:slack") { "Webhook returned HTTP #{response.status}" }
+          end
+        end
+
+        def post_api(body, agent_id: nil, thread_key: nil, seed_thread_ts: nil)
+          body[:channel] = @channel
+
+          key = thread_key || agent_id
+          thread_ts = key && @state_store.get(:slack, key.to_s)&.dig(:thread_ts)
+
+          # Seed from constructor (per-agent notifier) or spawn context
+          seed = seed_thread_ts || @initial_thread_ts
+          if !thread_ts && seed && key
+            thread_ts = seed
+            @state_store.put(:slack, key.to_s, {thread_ts:})
+          end
+
+          body[:thread_ts] = thread_ts if thread_ts
+
+          conn = @connection || build_connection(url: API_URL, token: @token)
+          response = conn.post("/api/chat.postMessage") do |req|
+            req.body = body
+          end
+
+          if response.status == 200
+            data = response.body
+            if data[:ok]
+              # Capture thread_ts from the first message for this agent/team
+              if !thread_ts && key && data[:ts]
+                existing = @state_store.get(:slack, key.to_s)
+                @state_store.put(:slack, key.to_s, {thread_ts: data[:ts]}) unless existing
+              end
+            else
+              Superkick.logger.warn("notifier:slack") { "Slack API error: #{data[:error]}" }
+            end
+          else
+            Superkick.logger.warn("notifier:slack") { "Slack API returned HTTP #{response.status}" }
+          end
+        end
+
+        def build_connection(url:, token: nil)
+          Faraday.new(url:) do |f|
+            f.request :json
+            f.request :authorization, "Bearer", token if token
+            f.response :json, parser_options: {symbolize_names: true}
+            f.options.timeout = WEBHOOK_TIMEOUT
+            f.options.open_timeout = WEBHOOK_TIMEOUT
+          end
+        end
+
+        def build_body(payload)
+          template_result = render_notification(payload)
+
+          if template_result && !template_result[:structured].blocks.empty?
+            {
+              text: template_result[:text],
+              blocks: template_result[:structured].blocks
+            }
+          else
+            build_body_fallback(payload)
+          end
+        end
+
+        def build_body_fallback(payload)
+          event_type = payload[:event_type]
+          emoji = self.class.event_emoji(event_type)
+          title = format_title(event_type)
+          message = payload[:message]
+
+          {
+            text: message,
+            blocks: build_blocks_fallback(emoji:, title:, payload:)
+          }
+        end
+
+        def build_blocks_fallback(emoji:, title:, payload:)
+          blocks = [
+            {
+              type: "header",
+              text: {type: "plain_text", text: "#{emoji} #{title}", emoji: true}
+            },
+            {
+              type: "section",
+              text: {type: "mrkdwn", text: payload[:message]}
+            }
+          ]
+
+          context_parts = []
+          context_parts << "*Agent:* `#{payload[:agent_id]}`" unless payload[:agent_id].to_s.empty?
+
+          monitor = payload[:monitor]
+          if monitor
+            context_parts << "*Monitor:* #{monitor.name}" unless monitor.name.to_s.empty?
+            context_parts << "*Type:* #{monitor.type}" unless monitor.type.to_s.empty?
+          end
+
+          ctx = payload[:context] || {}
+          team = ctx[:team]
+          context_parts << "*Team:* `#{team.id}`" if team&.id
+          agent = ctx[:agent]
+          context_parts << "*Role:* #{agent.role}" if agent&.role
+          spawner = ctx[:spawner]
+          context_parts << "*Spawner:* #{spawner.name}" if spawner
+
+          unless context_parts.empty?
+            blocks << {
+              type: "context",
+              elements: [{type: "mrkdwn", text: context_parts.join(" | ")}]
+            }
+          end
+
+          blocks
+        end
+
+        def format_title(event_type)
+          event_type.to_s.tr("_", " ").gsub(/\b\w/, &:upcase)
+        end
+      end
+    end
+  end
+end