superkick 0.1.0

data/lib/superkick/spawn/agent_spawner.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Superkick
+  module Spawn
+    # AgentSpawner — manages repository acquisition and agent subprocess lifecycle
+    # for spawned agents. Delegates process management to an Agent::Runtime.
+    class AgentSpawner
+      attr_writer :supervisor
+
+      def initialize(store:, notification_dispatcher:, config: Superkick.config, runtime: Agent::Runtime::Local.new,
+        spawn_injector: nil, supervisor: nil)
+        @store = store
+        @config = config
+        @runtime = runtime
+        @spawn_injector = spawn_injector || Spawn::Injector.new(store:)
+        @supervisor = supervisor
+        @notification_dispatcher = notification_dispatcher
+        @runtime_handles = {}
+        @vcs_state = {}  # agent_id => { adapter:, destination: }
+        @cooldowns = {}
+        @mutex = Mutex.new
+      end
+
+      # Spawn a new agent.
+      # @return [Hash] { status:, agent_id:, handle: }
+      def spawn(event:, spawner_config:)
+        max = spawner_config[:max_concurrent]
+        if max && active_count >= max
+          return {status: :at_capacity}
+        end
+
+        spawner_name = spawner_config[:name]
+        if spawner_name && cooldown_active?(spawner_name, spawner_config)
+          Superkick.logger.info("spawner") { "Cooldown active for #{spawner_name} — skipping" }
+          return {status: :cooldown}
+        end
+
+        agent_id = generate_agent_id(event, spawner_config)
+
+        # Workflow VCS inheritance: skip setup if inherited VCS state is present
+        if event[:inherited_vcs_state]
+          @mutex.synchronize { @vcs_state[agent_id] = event[:inherited_vcs_state] }
+          working_dir = event[:working_dir] || Dir.pwd
+        else
+          working_dir = run_setup(event, spawner_config)
+        end
+
+        handle = start_proxy(agent_id:, working_dir:,
+          spawner_config:)
+
+        @mutex.synchronize { @runtime_handles[agent_id] = handle }
+
+        wait_for_registration(agent_id)
+
+        # Stamp spawn_info on the agent
+        agent = @store.get(agent_id)
+        if agent
+          info = {
+            spawner_name:,
+            event_type: event[:event_type].to_s,
+            spawned_at: Time.now.iso8601
+          }
+          # Workflow metadata
+          info[:workflow_depth] = event[:workflow_depth] if event[:workflow_depth]
+          info[:workflow_iterations] = event[:workflow_iterations] if event[:workflow_iterations]
+          info[:parent_agent_id] = event[:parent_agent_id] if event[:parent_agent_id]
+          info[:workflow_source] = spawner_config[:workflow_source] if spawner_config[:workflow_source]
+          info[:working_dir] = working_dir
+          info[:context] = extract_context(event)
+          agent.spawn_info = info
+          agent.set_working_dir(working_dir)
+
+          # Agent metadata from event
+          agent.set_team(team_id: event[:team_id], team_role: event[:team_role]) if event[:team_id]
+          agent.set_role(event[:role]) if event[:role]
+
+          # Auto-attach monitors from spawner event (includes team_log when present)
+          attach_spawn_monitors(agent, event)
+
+          # Auto-attach per-agent notifiers from spawner event
+          attach_spawn_notifiers(agent, event)
+        end
+
+        @spawn_injector.inject(agent_id:, event:,
+          spawner_config:)
+
+        # Record cooldown timestamp
+        @mutex.synchronize { @cooldowns[spawner_name] = Process.clock_gettime(Process::CLOCK_MONOTONIC) } if spawner_name
+
+        # Start goal checker — defaults to agent_reported when no goal is configured
+        goal_config = spawner_config[:goal] || {type: :agent_signal}
+        if @supervisor
+          enriched = goal_config.merge(working_dir:)
+          # Wire team_id into goal config so the group goal can find its workers
+          enriched = enriched.merge(team_id: event[:team_id]) if event[:team_id]
+          # Inject rehydrated event context so goals can access Drops directly
+          # (e.g. self[:issue].number for GitHubIssueResolvedGoal)
+          context = extract_context(event)
+          rehydrated = Superkick::Drop.rehydrate(context)
+          rehydrated.each { |k, v| enriched[k] = v unless enriched.key?(k) }
+          @supervisor.start_goal_checker(agent_id:, goal_config: enriched, spawner_config:)
+        end
+
+        # Start cost poller if any budget is configured
+        if spawner_config[:budget]&.any? && @supervisor
+          @supervisor.start_cost_poller(agent_id:, spawner_config:)
+        end
+
+        dispatch_notification(
+          event: {event_type: :agent_spawned, monitor_type: :spawner, monitor_name: spawner_name || :system},
+          agent_id:,
+          message: "Agent #{agent_id} spawned by #{spawner_name || "system"}"
+        )
+
+        # Fire team_created when a team lead is spawned
+        if event[:team_id] && event[:team_role] == :lead
+          dispatch_notification(
+            event: {event_type: :team_created, monitor_type: :spawner, monitor_name: spawner_name || :system,
+                    team_id: event[:team_id], team_members: [agent_id]},
+            agent_id:,
+            message: "Team #{event[:team_id]} created with lead #{agent_id}"
+          )
+        end
+
+        {status: :spawned, agent_id:, handle:}
+      rescue => e
+        Superkick.logger.error("spawner") { "Spawn failed: #{e.message}\n#{e.backtrace.first(5).join("\n")}" }
+        {status: :error, error: e.message}
+      end
+
+      # Clean up when a spawned agent ends.
+      def agent_ended(agent_id)
+        vcs = @mutex.synchronize { @vcs_state.delete(agent_id) }
+        vcs[:adapter].teardown(destination: vcs[:destination]) if vcs
+
+        @mutex.synchronize { @runtime_handles.delete(agent_id) }
+      rescue => e
+        Superkick.logger.warn("agent_spawner") { "Cleanup failed for #{agent_id}: #{e.message}" }
+      end
+
+      # Terminate a spawned agent gracefully.
+      def terminate(agent_id)
+        handle = @mutex.synchronize { @runtime_handles[agent_id] }
+        return unless handle
+
+        @runtime.terminate(handle:)
+      rescue Errno::ESRCH
+        agent_ended(agent_id)
+      end
+
+      def active_count
+        @mutex.synchronize { @runtime_handles.size }
+      end
+
+      def runtime_handles
+        @mutex.synchronize { @runtime_handles.dup }
+      end
+
+      def register_handle(agent_id, handle)
+        @mutex.synchronize { @runtime_handles[agent_id] = handle }
+      end
+
+      # Record a cooldown timestamp for a spawner. Used by tests to simulate
+      # recent spawn activity without going through the full spawn flow.
+      def record_cooldown(spawner_name:, at: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+        @mutex.synchronize { @cooldowns[spawner_name] = at }
+      end
+
+      # Remove and return the VCS state for an agent.
+      # Used by Spawn::WorkflowExecutor for VCS ownership transfer.
+      def take_vcs_state(agent_id)
+        @mutex.synchronize { @vcs_state.delete(agent_id) }
+      end
+
+      def generate_agent_id(event, config)
+        if event[:agent_id]
+          event[:agent_id]
+        else
+          base = config[:name] || "spawned"
+          "#{base}-#{Process.pid}-#{SecureRandom.hex(4)}"
+        end
+      end
+
+      def run_setup(event, config)
+        return Dir.pwd unless config[:repository]
+
+        agent_id = generate_agent_id(event, config)
+        acquire_repository(event, config, agent_id)
+      end
+
+      private
+
+      def attach_spawn_monitors(agent, event)
+        monitors = event[:_spawn_monitors]
+        return unless monitors.is_a?(Hash) && monitors.any?
+
+        monitors.each do |name, monitor_config|
+          agent.set_monitor_config(name.to_sym, monitor_config)
+          @supervisor&.enqueue(:add_monitor, agent_id: agent.id, monitor_name: name.to_sym)
+        end
+      end
+
+      def attach_spawn_notifiers(agent, event)
+        notifiers = event[:_spawn_notifiers]
+        return unless notifiers.is_a?(Hash) && notifiers.any?
+
+        notifiers.each do |name, notifier_config|
+          agent.set_notifier_config(name.to_sym, notifier_config)
+        end
+        @notification_dispatcher.register_agent_notifiers(agent.id) if @notification_dispatcher.respond_to?(:register_agent_notifiers)
+      end
+
+      def start_proxy(agent_id:, working_dir:, spawner_config:)
+        driver_config = resolve_driver_config(spawner_config[:driver])
+        exe = File.expand_path($PROGRAM_NAME)
+
+        command = [exe, "agent", "--agent-id", agent_id, "--headless"]
+
+        if driver_config
+          command += ["--driver", driver_config[:type].to_s] if driver_config[:type]
+          command += ["--driver-config-dir", File.expand_path(driver_config[:config_dir])] if driver_config[:config_dir]
+          command += ["--driver-command", driver_config[:command]] if driver_config[:command]
+        end
+
+        command += ["--"] + driver_config[:args] if driver_config&.dig(:args)&.any?
+
+        spawn_env = driver_config&.dig(:env) || {}
+        spawn_env["SUPERKICK_AGENT_ID"] = agent_id
+
+        @runtime.provision(
+          agent_id:,
+          config: {env: spawn_env, command:, working_dir:}
+        )
+      end
+
+      def resolve_driver_config(driver)
+        Driver.normalize_driver(driver, profile_source: @config.driver_profile_source)
+      end
+
+      def acquire_repository(event, config, agent_id)
+        repository_name = config[:repository].to_sym
+        repository = @config.repository_source.find_by_name(repository_name)
+        raise Poller::FatalError, "Unknown repository: #{repository_name}" unless repository
+
+        adapter = VersionControl.for_repository(repository)
+        branch = interpolate_branch(config[:branch_template] || "superkick-{{ agent_id }}", event)
+        base_branch = config[:base_branch] || "main"
+        destination = File.join(@config.workspaces_dir, agent_id)
+
+        adapter.acquire(source: repository, destination:, branch:, base_branch:)
+        @mutex.synchronize { @vcs_state[agent_id] = {adapter:, destination:} }
+        destination
+      end
+
+      # Keys that are internal spawn/workflow metadata, not integration context.
+      INTERNAL_EVENT_KEYS = %i[
+        event_type monitor_type monitor_name agent_id
+        team_id team_role role
+        inherited_pipeline inherited_vcs_state working_dir
+        parent_agent_id parent_goal_status parent_goal_summary parent_spawner_name
+        workflow_depth workflow_iterations
+        _spawn_monitors _spawn_notifiers
+      ].freeze
+
+      def extract_context(event)
+        event.except(*INTERNAL_EVENT_KEYS)
+          .transform_values { Superkick::Drop.serialize(it) }
+      end
+
+      def interpolate_branch(template, event)
+        context = extract_context(event)
+        rehydrated = Superkick::Drop.rehydrate(context)
+        assigns = rehydrated.transform_keys(&:to_s)
+        assigns["agent_id"] = event[:agent_id].to_s if event[:agent_id]
+
+        liquid_template = ::Liquid::Template.parse(template)
+        liquid_template.render(assigns)
+      end
+
+      def cooldown_active?(spawner_name, config)
+        cooldown = config[:cooldown]
+        return false unless cooldown
+
+        last_spawn = @mutex.synchronize { @cooldowns[spawner_name] }
+        return false unless last_spawn
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - last_spawn
+        elapsed < cooldown
+      end
+
+      def wait_for_registration(agent_id, timeout: 30)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          return if @store.has?(agent_id)
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            raise "Agent #{agent_id} did not register within #{timeout}s"
+          end
+          sleep 0.5
+        end
+      end
+
+      def dispatch_notification(...)
+        @notification_dispatcher.dispatch(...)
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/spawn/approval_store.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Superkick
+  module Spawn
+    # Thread-safe store for pending spawn approvals and rejection records.
+    #
+    # When a spawner has `approval_required: true`, the Spawn::Handler stores
+    # the event here instead of spawning immediately. The user approves via
+    # `superkick approve <id>` (or rejects via `superkick reject <id>`), which
+    # triggers or discards the spawn.
+    #
+    # Rejected agent IDs are remembered so the spawner doesn't immediately
+    # re-dispatch the same event. Rejections can be cleared individually
+    # via `superkick approve --clear <id>` or all at once via
+    # `superkick approve --clear-all`.
+    class ApprovalStore
+      attr_reader :pending
+
+      def initialize
+        @pending = {}
+        @rejected = {}
+        @mutex = Mutex.new
+      end
+
+      # Add a pending approval. Returns the approval ID.
+      # Skips if the agent_id has been rejected.
+      def add(event:, spawner_config:)
+        id = generate_id(event)
+        @mutex.synchronize do
+          return nil if @rejected[id]
+
+          @pending[id] = {
+            id:,
+            event:,
+            spawner_config:,
+            created_at: Time.now.iso8601,
+            agent_id: event[:agent_id]
+          }
+        end
+        id
+      end
+
+      # Remove and return a pending approval by ID.
+      def take(id)
+        @mutex.synchronize { @pending.delete(id) }
+      end
+
+      # Get a pending approval without removing it.
+      def get(id)
+        @mutex.synchronize { @pending[id] }
+      end
+
+      # List all pending approvals.
+      def list
+        @mutex.synchronize { @pending.values.dup }
+      end
+
+      # Check if a pending or rejected entry exists for a given agent_id.
+      def has_agent?(agent_id)
+        @mutex.synchronize do
+          @rejected.key?(agent_id) ||
+            @pending.any? { |_, v| v[:agent_id] == agent_id }
+        end
+      end
+
+      # Record a rejection with an optional reason.
+      def reject(id, reason: nil)
+        entry = @mutex.synchronize { @pending.delete(id) }
+        return nil unless entry
+
+        @mutex.synchronize do
+          @rejected[id] = {
+            id:,
+            agent_id: entry[:agent_id],
+            rejected_at: Time.now.iso8601,
+            reason:
+          }
+        end
+        entry
+      end
+
+      # Check if an ID has been rejected.
+      def rejected?(id)
+        @mutex.synchronize { @rejected.key?(id) }
+      end
+
+      # List all rejections.
+      def rejections
+        @mutex.synchronize { @rejected.values.dup }
+      end
+
+      # Clear a specific rejection, allowing the event to be re-dispatched.
+      def clear_rejection(id)
+        @mutex.synchronize { @rejected.delete(id) }
+      end
+
+      # Clear all rejections.
+      def clear_all_rejections
+        @mutex.synchronize { @rejected.clear }
+      end
+
+      private
+
+      def generate_id(event)
+        event[:agent_id] || "approval-#{SecureRandom.hex(4)}"
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/spawn/handler.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Spawn
+    # Handler — event handler for spawners.
+    #
+    # Receives events from spawners, checks dedup via AgentStore, and delegates
+    # to Spawn::AgentSpawner. This is the spawner equivalent of InjectHandler.
+    #
+    # When `approval_required: true` is set on the spawner config, events are
+    # held in the Spawn::ApprovalStore and a `agent_pending_approval` notification is
+    # fired instead of spawning immediately. The user approves via
+    # `superkick approve <id>`.
+    class Handler
+      attr_reader :result
+
+      def initialize(spawner:, store:, spawner_config:, notification_dispatcher:, approval_store: nil,
+        repository_source: nil)
+        @spawner = spawner
+        @store = store
+        @spawner_config = spawner_config
+        @approval_store = approval_store
+        @notification_dispatcher = notification_dispatcher
+        @repository_source = repository_source
+        @pending = []
+        @pending_mutex = Mutex.new
+        @result = nil
+      end
+
+      # Handle a dispatched event.
+      # @return [Symbol] :spawned, :duplicate, :at_capacity, :cooldown, :pending_approval, :error
+      def handle(event:)
+        agent_id = event[:agent_id]
+
+        if agent_id && @store.has?(agent_id)
+          Superkick.logger.info("spawn_handler") { "Agent #{agent_id} already exists — skipping" }
+          return :duplicate
+        end
+
+        # Check if approval is required
+        if @spawner_config[:approval_required] && @approval_store
+          if agent_id && @approval_store.has_agent?(agent_id)
+            Superkick.logger.info("spawn_handler") { "Approval already pending for #{agent_id} — skipping" }
+            return :pending_approval
+          end
+
+          approval_id = @approval_store.add(event:, spawner_config: @spawner_config)
+          spawner_name = @spawner_config[:name]
+          Superkick.logger.info("spawn_handler") { "Approval required for #{agent_id} — queued as #{approval_id}" }
+
+          dispatch_notification(
+            event: {event_type: :agent_pending_approval, monitor_type: :spawner, monitor_name: spawner_name || :system,
+                    approval_id:},
+            agent_id: agent_id || approval_id,
+            message: "Agent #{agent_id || approval_id} pending approval from #{spawner_name || "spawner"}"
+          )
+          return :pending_approval
+        end
+
+        spawn_event(event)
+      rescue => e
+        Superkick.logger.error("spawn_handler") { "Spawn error: #{e.message}" }
+        :error
+      end
+
+      # Retry any pending events (e.g. those that were at capacity).
+      def flush_pending
+        events = @pending_mutex.synchronize do
+          evts = @pending.dup
+          @pending.clear
+          evts
+        end
+
+        events.each do |ev|
+          result = handle(event: ev)
+          @pending_mutex.synchronize { @pending << ev } if result == :at_capacity || result == :cooldown
+        end
+      end
+
+      private
+
+      def spawn_event(event)
+        agent_id = event[:agent_id]
+
+        # Enrich event for workflow: team (team lead mode)
+        if @spawner_config[:workflow] == :team
+          event = enrich_for_team(event)
+        end
+
+        @result = @spawner.spawn(event:, spawner_config: effective_spawner_config)
+
+        case @result[:status]
+        when :spawned
+          Superkick.logger.info("spawn_handler") { "Spawned agent #{@result[:agent_id]} for #{agent_id}" }
+        when :at_capacity
+          Superkick.logger.warn("spawn_handler") { "At capacity — queuing #{agent_id}" }
+          @pending_mutex.synchronize { @pending << event }
+        when :cooldown
+          Superkick.logger.info("spawn_handler") { "Cooldown active — queuing #{agent_id}" }
+          @pending_mutex.synchronize { @pending << event }
+        end
+
+        @result[:status]
+      end
+
+      # Enrich a spawn event for workflow: team — add team metadata and
+      # repository source context so the planning agent can decompose work.
+      def enrich_for_team(event)
+        team_id = event[:agent_id]
+        event.merge(
+          team_id:,
+          team_role: :lead,
+          role: "Lead",
+          repository_context: @repository_source&.to_prompt_context,
+          prompt_template: "team/planning_agent",
+          _spawn_monitors: {
+            team_log: {type: :team_log, team_id:}
+          }
+        )
+      end
+
+      # Return the effective spawner config, applying driver cascade and
+      # team workflow defaults.
+      def effective_spawner_config
+        config = @spawner_config
+        if config[:workflow] == :team
+          config = config.merge(goal: {type: :agent_signal}) unless config[:goal]
+
+          lead_driver = config.dig(:team, :lead, :driver)
+          if lead_driver
+            config = config.merge(driver: Driver.merge_driver(config[:driver], lead_driver))
+          end
+        end
+        config
+      end
+
+      def dispatch_notification(...)
+        @notification_dispatcher.dispatch(...)
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/spawn/injector.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Spawn
+    # Injector — handles injecting a kickoff prompt into a newly spawned
+    # agent. Extracted from Spawn::AgentSpawner to isolate injection protocol logic
+    # (buffer client polling, template rendering) from workspace setup and
+    # process management.
+    #
+    # Uses the agent's InjectionQueue with :high priority so spawn kickoffs
+    # are injected before any queued monitor events.
+    class Injector
+      WORKFLOW_TEMPLATES_DIR = File.join(__dir__, "..", "templates", "workflow")
+
+      def initialize(store:, buffer_client: nil)
+        @store = store
+        @buffer_client = buffer_client || Buffer.client_from(store:)
+      end
+
+      # Inject a kickoff prompt into a spawned agent.
+      # Waits for the buffer to become reachable, renders the template,
+      # and sends the prompt via `enqueue_injection` with high priority.
+      def inject(agent_id:, event:, spawner_config:)
+        wait_for_buffer(agent_id)
+
+        prompt = render(event, spawner_config)
+        return unless prompt
+
+        enqueue_to_buffer(agent_id, prompt, event)
+      end
+
+      private
+
+      def wait_for_buffer(agent_id, timeout: 30)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          break if @buffer_client.reachable?(agent_id)
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            Superkick.logger.warn("spawn_injector") { "Buffer not reachable for #{agent_id} — skipping kickoff" }
+            return
+          end
+          sleep 0.5
+        end
+      end
+
+      def render(event, spawner_config)
+        template_path = resolve_spawn_template(event, spawner_config)
+        return nil unless template_path
+
+        source = File.read(template_path, encoding: "utf-8")
+        render_event = rehydrate_context(event)
+        TemplateRenderer.render_source(source, render_event, monitor_type: event[:monitor_type])
+      end
+
+      # Rehydrate serialized Drop values in the event so templates get real
+      # Drop objects ({{ issue.title }}, {{ story.ref }}, etc.).
+      # Serialized context comes from workflow forwarding where Drops were
+      # serialized to hashes with _drop_type markers.
+      def rehydrate_context(event)
+        event.transform_values { Superkick::Drop.rehydrate(it) }
+      end
+
+      def enqueue_to_buffer(agent_id, prompt, event)
+        @buffer_client.send_command(agent_id, "enqueue_injection",
+          id: "spawn-#{agent_id}",
+          prompt:,
+          monitor_type: event[:monitor_type] || "spawner",
+          monitor_name: event[:monitor_name] || "system",
+          priority: "high",
+          ttl: 600)
+
+        Superkick.logger.info("spawn_injector") { "Enqueued kickoff prompt for #{agent_id}" }
+      end
+
+      def resolve_spawn_template(event, _spawner_config)
+        monitor_type = event[:monitor_type].to_s
+        monitor_name = event[:monitor_name]&.to_s
+        event_type = event[:event_type].to_s
+
+        # 1. User per-instance: ~/.superkick/templates/spawners/<name>/<event>.liquid
+        if monitor_name
+          path = File.join(Superkick.config.templates_dir, "spawners", monitor_name, "#{event_type}.liquid")
+          return path if File.exist?(path)
+        end
+
+        # 2. User per-type: ~/.superkick/templates/spawners/<type>/<event>.liquid
+        path = File.join(Superkick.config.templates_dir, "spawners", monitor_type, "#{event_type}.liquid")
+        return path if File.exist?(path)
+
+        # 2b. Workflow default: ~/.superkick/templates/spawners/workflow/<event>.liquid
+        if monitor_type == "workflow"
+          path = File.join(Superkick.config.templates_dir, "spawners", "workflow", "#{event_type}.liquid")
+          return path if File.exist?(path)
+        end
+
+        # 3. Bundled spawner templates from the spawner class
+        klass = Spawner.registered[monitor_type.to_sym]
+        if klass&.spawn_templates_dir
+          path = File.join(klass.spawn_templates_dir, "#{event_type}.liquid")
+          return path if File.exist?(path)
+        end
+
+        # 4. Bundled workflow default template
+        if monitor_type == "workflow"
+          path = File.join(WORKFLOW_TEMPLATES_DIR, "#{event_type}.liquid")
+          return path if File.exist?(path)
+
+          # Fall back to workflow_triggered.liquid for any workflow event type
+          path = File.join(WORKFLOW_TEMPLATES_DIR, "workflow_triggered.liquid")
+          return path if File.exist?(path)
+        end
+
+        nil
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end