superkick 0.1.0

data/lib/superkick/spawn/workflow_executor.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Spawn
+    # WorkflowExecutor — resolves workflow config, builds enriched events, handles
+    # VCS ownership transfer, enforces iteration limits, and dispatches
+    # workflow spawns.
+    #
+    # Called by Supervisor when a spawned agent's goal reaches a terminal status
+    # and the spawner config has `on_complete:` or `on_fail:`.
+    class WorkflowExecutor
+      def initialize(store:, agent_spawner:, notification_dispatcher:, config: Superkick.config)
+        @store = store
+        @agent_spawner = agent_spawner
+        @notification_dispatcher = notification_dispatcher
+        @config = config
+      end
+
+      # Fire a workflow spawn if configured.
+      # @param agent_id [String] the parent agent that just finished
+      # @param goal_status [Symbol] :completed or :failed
+      # @param spawner_config [Hash] the parent spawner's config
+      def fire(agent_id:, goal_status:, spawner_config:)
+        hook_key = case goal_status
+        when :completed then :on_complete
+        when :failed then :on_fail
+        else return
+        end
+
+        hook_config = spawner_config[hook_key]
+        return unless hook_config
+
+        agent = @store.get(agent_id)
+        current_depth = agent&.spawn_info&.dig(:workflow_depth) || 0
+        parent_iterations = agent&.spawn_info&.dig(:workflow_iterations) || {}
+
+        resolved = resolve_workflow_config(hook_config, spawner_config)
+        return unless resolved
+
+        # Check iteration limit for the target spawner
+        target_name = resolved[:name]&.to_sym
+        if target_name
+          current_count = parent_iterations[target_name] || 0
+          max = resolved[:max_iterations]
+          if max && current_count >= max
+            Superkick.logger.warn("workflow_executor") {
+              "Max iterations reached for #{target_name} (#{current_count}/#{max}) in chain for #{agent_id} — not spawning"
+            }
+            dispatch_notification(
+              event: {event_type: :workflow_iterations_exceeded, monitor_type: :spawner,
+                      monitor_name: spawner_config[:name] || :system,
+                      goal_status:},
+              agent_id:,
+              message: "Max iterations reached for #{target_name} (#{current_count}/#{max}) in chain for #{agent_id}"
+            )
+            return
+          end
+        end
+
+        workflow_event = build_workflow_event(
+          agent_id:, goal_status:, spawner_config:,
+          workflow_config: resolved, depth: current_depth,
+          parent_iterations:
+        )
+
+        # VCS ownership transfer for inherit case
+        if hook_config[:repository].nil?
+          vcs_state = @agent_spawner.take_vcs_state(agent_id)
+
+          if vcs_state
+            workflow_event[:inherited_vcs_state] = vcs_state
+            workflow_event[:working_dir] = vcs_state[:destination] ||
+              agent&.spawn_info&.dig(:working_dir)
+          else
+            # No VCS state to transfer — pass parent working dir
+            workflow_event[:working_dir] = agent&.spawn_info&.dig(:working_dir)
+          end
+        end
+
+        # Fire notification
+        dispatch_notification(
+          event: {event_type: :workflow_triggered, monitor_type: :spawner,
+                  monitor_name: spawner_config[:name] || :system,
+                  goal_status:},
+          agent_id:,
+          message: "Workflow triggered for #{agent_id} (#{goal_status} → #{resolved[:name]})"
+        )
+
+        # Spawn in background thread
+        Thread.new do
+          @agent_spawner.spawn(event: workflow_event, spawner_config: resolved)
+        rescue => e
+          Superkick.logger.error("workflow_executor") {
+            "Workflow spawn failed for #{agent_id}: #{e.message}"
+          }
+          # Reclaim VCS state if spawn fails to avoid orphaned workspaces
+          reclaim_vcs_state(workflow_event)
+        end
+      end
+
+      private
+
+      def resolve_workflow_config(workflow_config, parent_config)
+        if workflow_config[:spawner]
+          # Reference to a named spawner
+          name = workflow_config[:spawner].to_sym
+          ref = @config.spawners[name]
+          unless ref
+            Superkick.logger.warn("workflow_executor") { "Workflow references unknown spawner: #{name}" }
+            return nil
+          end
+          ref.merge(name:, workflow_source: parent_config[:name])
+        else
+          # Inline config — fill in defaults from parent, merging driver configs
+          effective_driver = if workflow_config[:driver]
+            Driver.merge_driver(parent_config[:driver], workflow_config[:driver])
+          else
+            parent_config[:driver]
+          end
+
+          {
+            name: "#{parent_config[:name]}-workflow",
+            driver: effective_driver,
+            goal: workflow_config[:goal],
+            repository: workflow_config[:repository],
+            max_duration: workflow_config[:max_duration] || parent_config[:max_duration],
+            max_concurrent: workflow_config[:max_concurrent],
+            approval_required: workflow_config[:approval_required] || false,
+            prompt_template: workflow_config[:prompt_template],
+            workflow_source: parent_config[:name]
+          }.compact
+        end
+      end
+
+      def build_workflow_event(agent_id:, goal_status:, spawner_config:, workflow_config:, depth:, parent_iterations:)
+        agent = @store.get(agent_id)
+        original_event = agent&.spawn_info || {}
+
+        # Determine event_type for template resolution
+        event_type = workflow_config[:prompt_template] || :workflow_triggered
+
+        # Determine agent_id for the workflow spawn
+        stage = workflow_config[:name] || ((goal_status == :completed) ? "on_complete" : "on_fail")
+        workflow_agent_id = "#{agent_id}-workflow-#{stage}"
+
+        # Increment iteration count for the target spawner
+        target_name = workflow_config[:name]&.to_sym
+        workflow_iterations = parent_iterations.dup
+        workflow_iterations[target_name] = (workflow_iterations[target_name] || 0) + 1 if target_name
+
+        event = {
+          event_type:,
+          agent_id: workflow_agent_id,
+          monitor_type: :workflow,
+          monitor_name: spawner_config[:name] || :system,
+          parent_agent_id: agent_id,
+          parent_goal_status: goal_status,
+          parent_spawner_name: spawner_config[:name],
+          workflow_depth: depth + 1,
+          workflow_iterations:
+        }
+
+        # Forward serialized context from parent's spawn_info wholesale.
+        # This replaces the old FORWARDED_FIELDS approach — context carries
+        # all integration-specific data (Drops, scalars) without enumeration.
+        original_event[:context]&.each do |key, value|
+          event[key] = value
+        end
+
+        # Include failure retrospective when available
+        event[:parent_goal_summary] = agent.goal_summary if agent&.goal_summary
+
+        # Forward per-agent notifier configs so workflow children inherit them
+        event[:_spawn_notifiers] = agent.notifiers if agent&.notifiers&.any?
+
+        event
+      end
+
+      # Reclaim VCS resources from a failed workflow event to avoid orphaning.
+      def reclaim_vcs_state(workflow_event)
+        vcs_state = workflow_event.delete(:inherited_vcs_state)
+        vcs_state[:adapter].teardown(destination: vcs_state[:destination]) if vcs_state
+      rescue => e
+        Superkick.logger.error("workflow_executor") {
+          "VCS reclaim teardown failed: #{e.message}"
+        }
+      end
+
+      def dispatch_notification(...)
+        @notification_dispatcher.dispatch(...)
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/spawn/workflow_validator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Spawn
+    # WorkflowValidator — static validation for spawner workflow configs.
+    #
+    # Two checks, both called at server startup:
+    #
+    # 1. **Cycle detection** — walks `on_complete:` / `on_fail:` spawner
+    #    reference chains looking for cycles via visited-set tracking.
+    #
+    # 2. **Cyclic iteration requirement** — spawners with `allow_cycles: true`
+    #    must have an explicit `max_iterations` to prevent infinite recursion.
+    #
+    # Only `:spawner` references create chain links — inline configs are leaf
+    # nodes and cannot form cycles.
+    class WorkflowValidator
+      # Validate all spawner configs for cycles.
+      # @param spawners [Hash] the spawners config hash (name => config)
+      # @return [Array<Array<Symbol>>] list of cycles found (empty = valid)
+      def self.validate(spawners)
+        cycles = []
+        spawners.each_key do |name|
+          walk_chain(name.to_sym, spawners, {}, [], cycles)
+        end
+        cycles
+      end
+
+      # Find cyclic spawners that lack a max_iterations limit.
+      #
+      # Spawners with `allow_cycles: true` need an explicit iteration limit
+      # to prevent infinite recursion.
+      #
+      # @param spawners [Hash] the spawners config hash
+      # @return [Array<Symbol>] names of spawners missing an iteration limit
+      def self.cyclic_spawners_without_iteration_limit(spawners)
+        spawners.each_with_object([]) do |(name, config), missing|
+          next unless config[:allow_cycles]
+
+          missing << name.to_sym unless config[:max_iterations]
+        end
+      end
+
+      # Return the spawner names reachable from a config's on_complete/on_fail hooks.
+      def self.successors(config)
+        %i[on_complete on_fail].filter_map do |hook|
+          config[hook]&.dig(:spawner)&.to_sym
+        end
+      end
+      private_class_method :successors
+
+      def self.walk_chain(spawner, spawners, visited, path, cycles)
+        return if visited[spawner] == :done
+
+        if visited[spawner] == :in_progress
+          cycle_start = path.index(spawner)
+          cycles << path[cycle_start..] + [spawner]
+          return
+        end
+
+        visited[spawner] = :in_progress
+        path.push(spawner)
+
+        config = spawners[spawner]
+        successors(config || {}).each do |target|
+          walk_chain(target, spawners, visited, path, cycles)
+        end
+
+        path.pop
+        visited[spawner] = :done
+      end
+      private_class_method :walk_chain
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/spawner.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Spawner — server-level poller base class for spawning agents.
+  #
+  # Inherits the run loop, error handling, backoff, and config validation
+  # from Poller.  Differences from agent-bound monitors:
+  #
+  #   1. No @agent — spawners are not bound to any agent
+  #   2. Separate class-level registry — types don't collide with Monitor types
+  #   3. dispatch stamps an agent_id on the event
+  #   4. log_tag doesn't reference an agent ID
+  #
+  # Subclass contract (in addition to Poller's):
+  #   self.agent_id(event) → String — deterministic agent ID for dedup
+  #   self.spawn_templates_dir → path to kickoff ERB templates (optional)
+  class Spawner < Poller
+    @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, "Spawner 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
+
+      def lookup(type)
+        @registry[type.to_sym] or raise ArgumentError, "Unknown spawner type: #{type}"
+      end
+    end
+
+    # Subclasses must implement: given an event hash, return a string that
+    # uniquely identifies the work unit and serves as the agent ID.
+    def self.agent_id(event)
+      raise NotImplementedError, "#{self}.agent_id not implemented"
+    end
+
+    # Override to provide spawn-specific template directory.
+    def self.spawn_templates_dir
+      nil
+    end
+
+    # Override dispatch to stamp agent_id from the spawner class.
+    def dispatch(event)
+      full_event = event.merge(
+        monitor_type: self.class.type.to_s,
+        monitor_name: @name,
+        agent_id: self.class.agent_id(event)
+      )
+      @handler.handle(event: full_event)
+    end
+
+    # No agent — use spawner-specific tag.
+    def log_tag
+      "spawner:#{self.class.type}(#{@name})"
+    end
+  end
+end