superkick 0.1.0

data/lib/superkick/monitor.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Monitor — abstract base class for agent-bound event source monitors.
+  #
+  # Inherits the run loop, error handling, backoff, and config validation
+  # from Poller.  Adds agent binding, the Probe nested class, and the
+  # class-level monitor registry.
+  #
+  # Subclass contract (in addition to Poller's):
+  #   tick                   → called each interval; use dispatch(event) to emit
+  #   on_start               → optional hook called once before the run loop
+  #
+  # Optionally define a nested Probe class (< Monitor::Probe) for auto-detection
+  # of monitor config from the local environment.
+  #
+  # Subclasses register themselves:
+  #   Superkick::Monitor.register(MyMonitor)
+  class Monitor < Poller
+    # ── Probe — abstract base for environment probes ──────────────────────
+    #
+    # Probes run server-side using an environment snapshot collected from the
+    # agent at registration time.  The server aggregates environment_actions
+    # from all registered probes, sends them to the agent, and distributes
+    # the response to each probe's detect method.
+    #
+    # Subclass contract:
+    #   self.type                → unique Symbol  (conventionally matches the Monitor type)
+    #   self.description         → human-readable summary of what the probe detects (optional)
+    #   self.environment_actions → Array of action hashes needed by this probe
+    #   self.detect(environment:) → {} or { monitor_name: { type: "…", config… } }
+    class Probe
+      @registry = {}
+
+      class << self
+        include Superkick::Registry
+
+        def register(klass)
+          raise ArgumentError, "#{klass} must define self.type" unless klass.respond_to?(:type)
+
+          key = klass.type.to_sym
+          raise ArgumentError, "Probe type :#{key} already registered" if @registry.key?(key)
+
+          @registry[key] = klass
+        end
+
+        def deregister(type)
+          @registry.delete(type.to_sym)
+        end
+
+        def registered
+          @registry.dup.freeze
+        end
+
+        # Replace the probe registry. Used by tests to isolate probe
+        # registration without disturbing globally registered probes.
+        def reset_registry!(registry = {})
+          @registry = registry
+        end
+
+        # Collect environment actions from all registered probes, deduplicated.
+        # @return [Array<Hash>] merged action list
+        def all_environment_actions
+          seen = Set.new
+          @registry.values.each_with_object([]) do |klass, actions|
+            next unless klass.respond_to?(:environment_actions)
+
+            klass.environment_actions.each do |action|
+              key = action_dedup_key(action)
+              unless seen.include?(key)
+                seen.add(key)
+                actions << action
+              end
+            end
+          end
+        end
+
+        # Run every registered probe against an environment snapshot.
+        # @param environment [Hash] environment data from the agent
+        # @return [Hash] merged monitor configs from all probes
+        def detect_all(environment:)
+          @registry.values.each_with_object({}) do |klass, h|
+            h.merge!(klass.detect(environment:) || {})
+          end
+        end
+
+        def type
+          raise NotImplementedError, "#{self}.type not defined"
+        end
+
+        # Optional human-readable description of what the probe detects.
+        def description
+          nil
+        end
+
+        # Environment actions this probe requires. Override in subclasses.
+        # @return [Array<Hash>] e.g. [{ action: :git_branch }, { action: :git_remotes }]
+        def environment_actions
+          []
+        end
+
+        # Subclasses must override.
+        # @param environment [Hash] environment data from the agent
+        # @return [Hash] empty or { monitor_name: config_hash }
+        def detect(environment:)
+          raise NotImplementedError, "#{self}.detect not implemented"
+        end
+
+        private
+
+        # Deduplication key for environment actions.
+        # :file_exists actions with different paths are distinct.
+        def action_dedup_key(action)
+          key = action[:action].to_sym
+          if key == :file_exists
+            paths = (action[:paths] || []).sort
+            [key, paths]
+          else
+            [key]
+          end
+        end
+      end
+    end
+
+    # ── Class-level plugin registry ────────────────────────────────────────
+
+    @registry = {}
+
+    class << self
+      include Superkick::Registry
+
+      def register(klass)
+        raise ArgumentError, "#{klass} must define self.type" unless klass.respond_to?(:type)
+        key = klass.type.to_sym
+        raise ArgumentError, "Monitor type :#{key} already registered" if @registry.key?(key)
+
+        @registry[key] = klass
+        Probe.register(klass.probe_class) if klass.probe_class
+      end
+
+      def deregister(type)
+        key = type.to_sym
+        klass = @registry.delete(key)
+        Probe.deregister(key) if klass&.probe_class
+      end
+
+      def registered
+        @registry.dup.freeze
+      end
+
+      def lookup(type)
+        @registry[type.to_sym] or raise ArgumentError, "Unknown monitor type: #{type.inspect}"
+      end
+
+      # Convenience: runs all registered probes against an environment snapshot.
+      # Delegates to Probe.detect_all.
+      def detect_all(environment:)
+        Probe.detect_all(environment:)
+      end
+
+      # Convenience: collects all environment actions from registered probes.
+      # Delegates to Probe.all_environment_actions.
+      def all_environment_actions
+        Probe.all_environment_actions
+      end
+
+      # Returns the nested Probe class if one is defined, nil otherwise.
+      # Subclasses can override for explicit control.
+      def probe_class
+        const_defined?(:Probe, false) ? const_get(:Probe) : nil
+      end
+
+      # Fill in missing config values from the agent's environment snapshot.
+      # Subclasses override to infer values from the environment data
+      # (e.g. repo/branch from git remotes, story ID from branch name).
+      #
+      # Called by the Supervisor before constructing a monitor instance,
+      # so it works for all config sources (YAML, probes, spawners, MCP).
+      #
+      # Must not overwrite explicitly provided values.
+      # @param config [Hash] partial config (may be empty)
+      # @param environment [Hash] environment snapshot from the agent
+      # @return [Hash] config with missing values filled in
+      def resolve_config(config, environment: {})
+        config
+      end
+    end
+
+    # ── Instance ──────────────────────────────────────────────────────────
+
+    attr_reader :agent, :server_context
+
+    def initialize(name:, config:, handler:, agent: nil, server_context: {})
+      super(name:, config:, handler:)
+      @agent = agent
+      @server_context = server_context
+    end
+
+    # Emit an event.  Stamps monitor_type and monitor_name, then delegates
+    # to the handler.
+    def dispatch(event)
+      full_event = event.merge(
+        monitor_type: self.class.type.to_s,
+        monitor_name: @name
+      )
+
+      @handler.handle(event: full_event)
+    end
+
+    def log_tag
+      agent_id = @agent&.id || "server"
+      "#{self.class.type}(#{@name}):#{agent_id}"
+    end
+  end
+end

data/lib/superkick/notification_dispatcher.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Holds long-lived notifier instances so stateful notifiers can track
+  # per-agent state across events (e.g. Slack thread_ts for threading).
+  #
+  # Created once at server startup and passed to all server-side components
+  # via constructor injection. Stateless notifiers work unchanged — state
+  # is opt-in via `stateful?`.
+  #
+  # When an agent's event stream ends (completed, failed, timed_out,
+  # terminated), `agent_finished` is called automatically so stateful
+  # notifiers can clean up per-agent state.
+  #
+  # Accepts an optional `store:` (AgentStore) to enrich payloads with
+  # agent context (team_id, team_role, spawner_name, etc.).
+  class NotificationDispatcher
+    TERMINAL_EVENT_TYPES = %w[
+      agent_completed agent_failed agent_timed_out agent_terminated
+      team_completed team_failed team_timed_out
+    ].freeze
+
+    # Structural spawn_info fields (agent metadata, not integration context).
+    # Integration context is now stored in spawn_info[:context] and rehydrated.
+    SPAWN_INFO_METADATA_FIELDS = %i[
+      spawner_name parent_agent_id workflow_depth workflow_source
+    ].freeze
+
+    def initialize(state_store:, store: nil, notifications: Superkick.config.notifications, notifiers: nil,
+      internal_notifiers: nil)
+      @notifiers = notifiers || build_notifiers(notifications:, state_store:)
+      # Internal notifiers are always present regardless of config (e.g. Team::LogNotifier)
+      @notifiers.concat(internal_notifiers) if internal_notifiers
+      @store = store
+      @state_store = state_store
+      @agent_notifiers = {}  # agent_id => { name => [notifier, events_filter] }
+      @agent_notifiers_mutex = Mutex.new
+    end
+
+    # Dispatch an event to all configured notifiers in a background thread.
+    # Each notifier is isolated — one failure doesn't prevent others.
+    def dispatch(event:, agent_id:, rendered_prompt: nil, message: nil)
+      Thread.new do
+        payload = build_payload(event:, agent_id:, rendered_prompt:, message:)
+        event_type = payload[:event_type]
+
+        fire_notifiers(@notifiers, payload, event_type)
+
+        # Per-agent notifiers
+        agent_notifiers = @agent_notifiers_mutex.synchronize { @agent_notifiers[agent_id]&.values&.dup }
+        fire_notifiers(agent_notifiers, payload, event_type) if agent_notifiers
+
+        # Call agent_finished on stateful notifiers after terminal events
+        if TERMINAL_EVENT_TYPES.include?(event_type)
+          finish_agent(agent_id)
+        end
+      rescue => e
+        Superkick.logger.error("notifier") { "dispatch error: #{e.message}" }
+      end
+    end
+
+    # Notify stateful notifiers that an agent's event stream is over.
+    # Called automatically after terminal events, but can also be called
+    # explicitly by the Supervisor during cleanup.
+    def agent_finished(agent_id)
+      @notifiers.each do |notifier, _|
+        next unless notifier.stateful?
+
+        notifier.agent_finished(agent_id:)
+      rescue => e
+        Superkick.logger.error("notifier") { "#{notifier.class.type} agent_finished failed: #{e.message}" }
+      end
+
+      # Clean up per-agent notifiers
+      agent_notifiers = @agent_notifiers_mutex.synchronize { @agent_notifiers.delete(agent_id) }
+      return unless agent_notifiers
+
+      agent_notifiers.each_value do |notifier, _|
+        next unless notifier.stateful?
+
+        notifier.agent_finished(agent_id:)
+      rescue => e
+        Superkick.logger.error("notifier") { "#{notifier.class.type} per-agent agent_finished failed: #{e.message}" }
+      end
+    end
+
+    # Build and register per-agent notifiers from the agent's notifier configs.
+    # Called by AgentSpawner after attaching notifier configs to the agent.
+    def register_agent_notifiers(agent_id)
+      agent = @store&.get(agent_id.to_s)
+      return unless agent&.notifiers&.any?
+
+      named = {}
+      agent.notifiers.each do |name, config|
+        pair = build_one_notifier(config)
+        named[name.to_sym] = pair if pair
+      end
+      return if named.empty?
+
+      @agent_notifiers_mutex.synchronize { @agent_notifiers[agent_id] = named }
+    end
+
+    # Add a single per-agent notifier by name. Called by Control::Server
+    # when superkick_add_notifier is invoked on a running agent.
+    def add_agent_notifier(agent_id, name)
+      agent = @store&.get(agent_id.to_s)
+      return unless agent
+
+      config = agent.notifier_config(name)
+      return unless config
+
+      pair = build_one_notifier(config)
+      return unless pair
+
+      @agent_notifiers_mutex.synchronize do
+        @agent_notifiers[agent_id] ||= {}
+        @agent_notifiers[agent_id][name.to_sym] = pair
+      end
+    end
+
+    # Remove a single per-agent notifier by name. Called by Control::Server
+    # when superkick_remove_notifier is invoked on a running agent.
+    # Calls agent_finished on stateful notifiers for proper cleanup.
+    def remove_agent_notifier(agent_id, name)
+      pair = @agent_notifiers_mutex.synchronize do
+        @agent_notifiers.dig(agent_id, name.to_sym)&.tap do
+          @agent_notifiers[agent_id]&.delete(name.to_sym)
+          remaining = @agent_notifiers[agent_id]
+          @agent_notifiers.delete(agent_id) if remaining && remaining.empty?
+        end
+      end
+      return unless pair
+
+      notifier, _ = pair
+      return unless notifier.stateful?
+
+      notifier.agent_finished(agent_id:)
+    rescue => e
+      Superkick.logger.error("notifier") { "#{notifier.class.type} per-agent agent_finished failed: #{e.message}" }
+    end
+
+    private
+
+    alias_method :finish_agent, :agent_finished
+
+    def fire_notifiers(notifier_pairs, payload, event_type)
+      notifier_pairs.each do |notifier, events_filter|
+        next if events_filter && !events_filter.include?(event_type)
+
+        notifier.notify(payload)
+      rescue => e
+        Superkick.logger.error("notifier") { "#{notifier.class.type} failed: #{e.message}" }
+      end
+    end
+
+    def build_payload(event:, agent_id:, rendered_prompt:, message:)
+      {
+        event_type: event[:event_type].to_s,
+        monitor: MonitorDrop.new(
+          name: event[:monitor_name],
+          type: event[:monitor_type]
+        ),
+        agent_id: agent_id.to_s,
+        message: message || summary_for(event),
+        rendered_prompt:,
+        timestamp: Time.now.utc.iso8601,
+        context: build_context(agent_id:, event:)
+      }
+    end
+
+    def build_context(agent_id:, event:)
+      context = {}
+
+      agent = @store&.get(agent_id.to_s)
+
+      if agent
+        agent_data = {id: agent.id}
+        agent_data[:role] = agent.role if agent.role
+        agent_data[:team_role] = agent.team_role if agent.team_role
+        agent_data[:claimed] = true if agent.claimed?
+
+        if agent.spawn_info
+          agent_data[:spawned_at] = agent.spawn_info[:spawned_at] if agent.spawn_info[:spawned_at]
+        end
+
+        cost_data = agent.cost.to_h
+        agent_data[:cost_usd] = cost_data[:total_cost_usd] if cost_data[:total_cost_usd] > 0
+
+        # Nest goal under agent — event-level goal_status overrides agent state
+        goal_status = (event[:goal_status] || agent.goal_status)&.to_s
+        if goal_status && !goal_status.empty?
+          goal_data = {status: goal_status}
+          goal_data[:summary] = agent.goal_summary if agent.goal_summary
+          agent_data[:goal] = GoalDrop.new(goal_data)
+        end
+
+        context[:agent] = AgentDrop.new(agent_data)
+
+        if agent.team_id
+          team_data = {id: agent.team_id}
+          team_data[:members] = event[:team_members] if event[:team_members]
+          context[:team] = TeamDrop.new(team_data)
+        end
+
+        if agent.spawn_info
+          SPAWN_INFO_METADATA_FIELDS.each do |field|
+            next if field == :spawner_name
+            value = agent.spawn_info[field]
+            context[field] = value if value
+          end
+
+          if agent.spawn_info[:spawner_name]
+            context[:spawner] = SpawnerDrop.new(name: agent.spawn_info[:spawner_name])
+          end
+
+          # Rehydrate integration context (Drops become real objects)
+          if agent.spawn_info[:context]
+            rehydrated = Superkick::Drop.rehydrate(agent.spawn_info[:context])
+            rehydrated.each { |k, v| context[k] = v unless context.key?(k) }
+          end
+        end
+      end
+
+      # Forward event-level fields (not agent state — these describe the triggering event)
+      context[:budget] = event[:budget] if event[:budget]
+      context[:spent] = event[:spent] if event[:spent]
+      context[:approval_id] = event[:approval_id].to_s if event[:approval_id]
+      context[:repository_name] = event[:repository_name].to_s if event[:repository_name]
+      context[:artifact_name] = event[:artifact_name].to_s if event[:artifact_name]
+      context[:kind] = event[:kind] if event[:kind]
+      context[:target_agent_id] = event[:target_agent_id].to_s if event[:target_agent_id]
+      context[:slack_thread_ts] = event[:slack_thread_ts] if event[:slack_thread_ts]
+
+      # Build team Drop from event-level fields when no agent context exists
+      if !context[:team] && event[:team_members]
+        context[:team] = TeamDrop.new(members: event[:team_members])
+      end
+
+      context
+    end
+
+    def summary_for(event)
+      type = event[:event_type].to_s
+      monitor = event[:monitor_name] || event[:monitor_type]
+      "Superkick: #{type} from #{monitor}"
+    end
+
+    # Build a single [notifier, events_filter] pair from a config hash.
+    # Returns nil if the notifier type is unknown.
+    def build_one_notifier(config)
+      type_name = config[:type]
+      klass = Notifier.registered[type_name.to_sym]
+      unless klass
+        Superkick.logger.warn("notifier") { "Unknown notifier type: #{type_name.inspect}" }
+        return nil
+      end
+      events_filter = config[:events]&.map(&:to_s)
+      [klass.new(state_store: @state_store, **config.except(:type, :events, :name, :privileged)), events_filter]
+    end
+
+    # Build notifier instances from the configured notification list.
+    # Returns an array of [notifier, event_filter] pairs.
+    # event_filter is nil (all events) or an Array of event type strings.
+    def build_notifiers(notifications:, state_store:)
+      configs = notifications
+      configs = [{type: "terminal_bell"}] if configs.empty?
+
+      configs.filter_map do |config|
+        type_name = config[:type]
+        klass = Notifier.registered[type_name.to_sym]
+        unless klass
+          Superkick.logger.warn("notifier") { "Unknown notifier type: #{type_name.inspect}" }
+          next
+        end
+        events_filter = config[:events]&.map(&:to_s)
+        [klass.new(state_store:, **config.except(:type, :events)), events_filter]
+      end
+    end
+  end
+end

data/lib/superkick/notifier.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "liquid"
+
+module Superkick
+  # Notifier — base class for notification channels.
+  #
+  # Notifications fire on two kinds of events:
+  #   1. Monitor injections (from Injector after a successful injection)
+  #   2. Agent lifecycle events (from Supervisor/AgentSpawner)
+  #
+  # Subclass contract:
+  #   self.type          → unique Symbol  (e.g. :terminal_bell, :command)
+  #   self.templates_dir → path to bundled Liquid templates (optional)
+  #   notify(payload)    → called with a Hash of event details; should not raise
+  #   liquid do ... end  → declare Liquid filters, blocks, context (optional)
+  #
+  # Subclasses register themselves:
+  #   Superkick::Notifier.register(MyNotifier)
+  #
+  # Configuration (config.yml):
+  #
+  #   notifications:
+  #     - type: terminal_bell
+  #     - type: command
+  #       run: "notify-send 'Superkick' '$SUPERKICK_MESSAGE'"
+  #       events:
+  #         - agent_blocked
+  #         - agent_completed
+  #
+  # The optional `events:` filter restricts which event types a notifier
+  # receives. When absent, the notifier receives all events.
+  #
+  # When notifications is empty or not set, defaults to [{ type: :terminal_bell }].
+  #
+  # Agent lifecycle event types (see LIFECYCLE_EVENTS constant for full list):
+  #   - agent_spawned, agent_completed, agent_failed, agent_timed_out,
+  #     agent_blocked, agent_stalled, agent_terminated, agent_claimed,
+  #     agent_unclaimed, agent_pending_approval
+  #   - workflow_triggered, workflow_iterations_exceeded
+  #   - budget_warning, budget_exceeded
+  #   - team_created, team_completed, team_failed, team_timed_out,
+  #     worker_spawned, teammate_message, teammate_blocker
+  #   - attach_promoted, attach_demoted, attach_idle_timeout, attach_force_takeover
+  class Notifier
+    include Superkick::Liquid
+
+    # ── Registry (stores classes, keyed by type) ─────────────────────────
+    @registry = {}
+
+    LIFECYCLE_EVENTS = %i[
+      agent_spawned
+      agent_completed
+      agent_failed
+      agent_timed_out
+      agent_blocked
+      agent_stalled
+      agent_terminated
+      agent_claimed
+      agent_unclaimed
+      agent_pending_approval
+      workflow_triggered
+      workflow_iterations_exceeded
+      budget_warning
+      budget_exceeded
+      team_created
+      team_completed
+      team_failed
+      team_timed_out
+      worker_spawned
+      teammate_message
+      teammate_blocker
+      attach_promoted
+      attach_demoted
+      attach_idle_timeout
+      attach_force_takeover
+      agent_update
+      artifact_published
+    ].freeze
+
+    class << self
+      include Superkick::Registry
+
+      def register(notifier_class)
+        key = notifier_class.type
+        raise ArgumentError, "Notifier :#{key} is already registered" if @registry.key?(key)
+        @registry[key] = notifier_class
+      end
+
+      def lookup(name)
+        @registry[name.to_sym] or raise ArgumentError, "Unknown notifier: #{name.inspect}"
+      end
+
+      def registered
+        @registry.dup.freeze
+      end
+
+      private
+    end
+
+    # ── Class interface ────────────────────────────────────────────────
+
+    def self.type
+      raise NotImplementedError, "#{self}.type not implemented"
+    end
+
+    # Path to bundled Liquid templates. Override in subclasses.
+    def self.templates_dir = nil
+
+    # Setup wizard metadata. Override in subclasses that should appear in `superkick setup`.
+    def self.setup_label = nil
+    def self.setup_config = nil
+
+    # ── Instance interface ───────────────────────────────────────────────
+
+    def initialize(state_store:, **_opts)
+      @state_store = state_store
+    end
+
+    def notify(payload)
+      raise NotImplementedError, "#{self.class}#notify not implemented"
+    end
+
+    # Override to return true if this notifier tracks state across events.
+    # Stateful notifiers persist for the server's lifetime and receive
+    # agent_finished callbacks when an agent's event stream ends.
+    def stateful? = false
+
+    # Called when an agent's event stream is definitively over.
+    # Stateful notifiers use this to clean up per-agent state.
+    # Default no-op — only stateful notifiers need to implement this.
+    def agent_finished(agent_id:) = nil
+
+    # Build the accumulator for block tag rendering. Uses the context class
+    # from `liquid do { context { ... } }` if declared, otherwise a plain Hash.
+    def build_accumulator
+      context_class = self.class.liquid_config.context_class
+      context_class ? context_class.new : {}
+    end
+
+    # Render a notification template for the given payload.
+    # Returns { structured:, text: } via NotifierTemplate, or nil if no
+    # template is found.
+    #
+    # Context fields are merged into top-level assigns so templates can
+    # access Drops directly (e.g. `{{ team.id }}` instead of
+    # `{{ context.team.id }}`). Top-level payload keys take precedence
+    # on collision.
+    def render_notification(payload)
+      source = TemplateRenderer.resolve_notification(self.class, payload[:event_type])
+      return nil unless source
+
+      env = TemplateRenderer.environment_for(self.class)
+      assigns = build_template_assigns(payload)
+      accumulator = build_accumulator
+
+      NotifierTemplate.render(source:, environment: env, assigns:, accumulator:)
+    end
+
+    private
+
+    def build_template_assigns(payload)
+      context = payload[:context] || {}
+      # Context fields form the base; top-level payload keys win on collision
+      assigns = context.transform_keys(&:to_s)
+      payload.each do |k, v|
+        next if k == :context
+        assigns[k.to_s] = v
+      end
+      assigns
+    end
+  end
+end