superkick 0.1.0

data/lib/superkick/drivers/copilot.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Superkick
+  module Drivers
+    class Copilot < Driver
+      DEFAULT_CONFIG_DIR = File.join(Dir.home, ".copilot").freeze
+
+      def self.driver_name = :copilot
+
+      def initialize(cli_command: "copilot", config_dir: DEFAULT_CONFIG_DIR, **)
+        @cli_command = cli_command
+        @config_dir = config_dir
+      end
+
+      attr_reader :cli_command
+
+      def driver_name = :copilot
+
+      def prompt_patterns
+        [/^\s*@\s*$/]
+      end
+
+      def apply_config_dir(config_dir, env:, args:)
+        env["COPILOT_HOME"] = config_dir
+      end
+
+      def install_mcp(exe_path:)
+        config_path = File.join(@config_dir, "mcp-config.json")
+        config = load_config(config_path)
+        return print_manual_instructions(exe_path) unless config
+
+        servers = config["servers"] || []
+        existing = servers.find { |s| s["name"] == "superkick" }
+
+        if existing && existing["command"] == exe_path
+          $stdout.puts "Superkick already configured in #{config_path}."
+          return
+        end
+
+        if existing
+          existing["command"] = exe_path
+        else
+          servers << {"name" => "superkick", "type" => "local",
+                       "command" => exe_path, "args" => ["mcp"]}
+          config["servers"] = servers
+        end
+
+        write_config(config_path, config)
+        verb = existing ? "Updated" : "Installed"
+        $stdout.puts "#{verb} superkick MCP server in #{config_path}."
+      end
+
+      private
+
+      def load_config(path)
+        return {} unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        $stdout.puts "Parse error in #{path}: #{e.message}"
+        nil
+      end
+
+      def write_config(path, config)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(config))
+      end
+    end
+  end
+end
+
+Superkick::Driver.register(Superkick::Drivers::Copilot)

data/lib/superkick/drivers/gemini.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Superkick
+  module Drivers
+    class Gemini < Driver
+      DEFAULT_CONFIG_DIR = File.join(Dir.home, ".gemini").freeze
+
+      def self.driver_name = :gemini
+
+      def initialize(cli_command: "gemini", config_dir: DEFAULT_CONFIG_DIR, **)
+        @cli_command = cli_command
+        @config_dir = config_dir
+      end
+
+      attr_reader :cli_command
+
+      def driver_name = :gemini
+
+      def prompt_patterns
+        [/gemini>\s*$/, /^\s*>\s*$/]
+      end
+
+      def cost_patterns
+        [
+          CostPattern.new(
+            pattern: /Estimated cost:\s*\$([0-9]+\.?[0-9]*)/,
+            extractor: ->(m) { {cost_usd: m[1].to_f} }
+          ),
+          CostPattern.new(
+            pattern: /Tokens used:\s*([\d,]+)\s*input,\s*([\d,]+)\s*output/,
+            extractor: ->(m) {
+              {tokens_in: m[1].delete(",").to_i,
+               tokens_out: m[2].delete(",").to_i}
+            }
+          )
+        ]
+      end
+
+      def cost_command = "/stats"
+
+      def apply_config_dir(config_dir, env:, args:)
+        env["GEMINI_CLI_HOME"] = config_dir
+      end
+
+      def install_mcp(exe_path:)
+        config_path = File.join(@config_dir, "settings.json")
+        config = load_config(config_path)
+        return print_manual_instructions(exe_path) unless config
+
+        existing = config.dig("mcpServers", "superkick", "command")
+
+        if existing == exe_path
+          $stdout.puts "Superkick already configured in #{config_path}."
+          return
+        end
+
+        config["mcpServers"] ||= {}
+        config["mcpServers"]["superkick"] = {"command" => exe_path, "args" => ["mcp"]}
+        write_config(config_path, config)
+        verb = existing ? "Updated" : "Installed"
+        $stdout.puts "#{verb} superkick MCP server in #{config_path}."
+      end
+
+      private
+
+      def load_config(path)
+        return {} unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        $stdout.puts "Parse error in #{path}: #{e.message}"
+        nil
+      end
+
+      def write_config(path, config)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(config))
+      end
+    end
+  end
+end
+
+Superkick::Driver.register(Superkick::Drivers::Gemini)

data/lib/superkick/drivers/goose.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Superkick
+  module Drivers
+    class Goose < Driver
+      DEFAULT_CONFIG_DIR = File.join(Dir.home, ".config", "goose").freeze
+
+      def self.driver_name = :goose
+
+      def initialize(cli_command: "goose", config_dir: DEFAULT_CONFIG_DIR, **)
+        @cli_command = cli_command
+        @config_dir = config_dir
+      end
+
+      attr_reader :cli_command
+
+      def driver_name = :goose
+
+      def prompt_patterns
+        [/goose>\s*$/, /^\s*>\s*$/]
+      end
+
+      def apply_config_dir(config_dir, env:, args:)
+        env["GOOSE_CONFIG_DIR"] = config_dir
+      end
+
+      def install_mcp(exe_path:)
+        config_path = File.join(@config_dir, "config.yaml")
+        config = load_config(config_path)
+        return print_manual_instructions(exe_path) unless config
+
+        extensions = config["extensions"] || {}
+        existing = extensions.dig("superkick", "command")
+
+        if existing == exe_path
+          $stdout.puts "Superkick already configured in #{config_path} (path matches)."
+          return
+        end
+
+        extensions["superkick"] = {
+          "command" => exe_path,
+          "args" => ["mcp"],
+          "type" => "stdio",
+          "timeout" => 300
+        }
+        config["extensions"] = extensions
+        write_config(config_path, config)
+        verb = existing ? "Updated" : "Installed"
+        $stdout.puts "#{verb} superkick MCP server in #{config_path}."
+      end
+
+      private
+
+      def load_config(path)
+        return {} unless File.exist?(path)
+
+        YAML.safe_load_file(path) || {}
+      rescue Psych::SyntaxError => e
+        $stdout.puts "Parse error in #{path}: #{e.message}"
+        nil
+      end
+
+      def write_config(path, config)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, YAML.dump(config))
+      end
+    end
+  end
+end
+
+Superkick::Driver.register(Superkick::Drivers::Goose)

data/lib/superkick/drivers.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Namespace for driver subclasses. Each driver lives in its own file under
+# lib/superkick/drivers/<name>.rb and subclasses Superkick::Driver.
+module Superkick
+  module Drivers
+  end
+end
+
+# Load the base class first, then all built-in drivers.
+require_relative "driver"
+require_relative "drivers/claude_code"
+require_relative "drivers/copilot"
+require_relative "drivers/codex"
+require_relative "drivers/gemini"
+require_relative "drivers/goose"

data/lib/superkick/drop.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module Superkick
+  # Base class for all Superkick Liquid Drops. Provides serialization,
+  # deserialization, and the shared `initialize(data)` / `@data` pattern
+  # that every Drop follows.
+  #
+  # Subclasses must implement:
+  #   - `self.drop_type` → unique String identifier (e.g. "github_issue")
+  #
+  # Register subclasses with `Superkick::Drop.register(MyDrop)`.
+  #
+  # Serialization stamps `_drop_type` markers on hashes so Drops can be
+  # reconstructed from JSON-persisted data (e.g. spawn_info[:context]).
+  class Drop < ::Liquid::Drop
+    @registry = {}
+
+    def initialize(data)
+      super()
+      @data = data
+    end
+
+    def self.drop_type
+      raise NotImplementedError, "#{name} must implement self.drop_type"
+    end
+
+    class << self
+      include Superkick::Registry
+    end
+
+    def self.register(klass)
+      @registry[klass.drop_type] = klass
+    end
+
+    def self.lookup(type)
+      @registry[type.to_s]
+    end
+
+    def self.registered
+      @registry.dup.freeze
+    end
+
+    # Recursively serialize Drops into plain hashes with _drop_type markers.
+    def self.serialize(value)
+      case value
+      when Superkick::Drop then value.to_h
+      when Array then value.map { serialize(it) }
+      when Hash then value.transform_values { serialize(it) }
+      else value
+      end
+    end
+
+    # Recursively reconstruct Drops from _drop_type-marked hashes.
+    def self.rehydrate(value)
+      case value
+      when Hash
+        if (type = value[:_drop_type])
+          klass = lookup(type)
+          return value unless klass # unknown type, pass through
+
+          data = value.except(:_drop_type)
+            .transform_values { rehydrate(it) }
+          klass.new(data)
+        else
+          value.transform_values { rehydrate(it) }
+        end
+      when Array then value.map { rehydrate(it) }
+      else value
+      end
+    end
+
+    # Serialize this Drop to a JSON-safe hash with a _drop_type marker.
+    def to_h
+      @data.transform_values { Superkick::Drop.serialize(it) }
+        .merge(_drop_type: self.class.drop_type)
+    end
+  end
+end

data/lib/superkick/drops.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Liquid Drops for core Superkick objects used in notification templates,
+  # team digest templates, and workflow templates.
+
+  # Wraps team information for template access.
+  #
+  # Properties: id, members
+  class TeamDrop < Superkick::Drop
+    def self.drop_type = "team"
+
+    def id = @data[:id]
+
+    def members = @data[:members]
+  end
+
+  # Wraps spawner information for template access.
+  #
+  # Properties: name
+  class SpawnerDrop < Superkick::Drop
+    def self.drop_type = "spawner"
+
+    def name = @data[:name]&.to_s
+  end
+
+  # Wraps monitor information for template access.
+  #
+  # Properties: name, type
+  class MonitorDrop < Superkick::Drop
+    def self.drop_type = "monitor"
+
+    def name = @data[:name]&.to_s
+
+    def type = @data[:type]&.to_s
+  end
+
+  # Wraps goal state for template access in notifications.
+  # Nested under AgentDrop — accessed as {{ agent.goal.status }}.
+  #
+  # Properties: status, summary
+  class GoalDrop < Superkick::Drop
+    def self.drop_type = "goal"
+
+    def status = @data[:status]&.to_s
+
+    def summary = @data[:summary]
+  end
+
+  # Wraps agent metadata for template access in notifications.
+  #
+  # Properties: id, role, team_role, spawned_at, cost_usd, claimed, goal
+  class AgentDrop < Superkick::Drop
+    def self.drop_type = "agent"
+
+    def id = @data[:id]
+
+    def role = @data[:role]&.to_s
+
+    def team_role = @data[:team_role]&.to_s
+
+    def spawned_at = @data[:spawned_at]
+
+    def cost_usd = @data[:cost_usd]
+
+    def claimed = @data[:claimed]
+
+    def goal = @data[:goal]
+  end
+
+  Drop.register(TeamDrop)
+  Drop.register(SpawnerDrop)
+  Drop.register(MonitorDrop)
+  Drop.register(GoalDrop)
+  Drop.register(AgentDrop)
+end

data/lib/superkick/environment_executor.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Superkick
+  # EnvironmentExecutor — agent-side action executor for server-driven probes.
+  #
+  # The server sends an array of action hashes describing what environment data
+  # it needs (git branch, git remotes, file existence checks). The executor
+  # runs each action in the agent's working directory and returns the results.
+  #
+  # The executor has no knowledge of monitors or probes — it is a simple,
+  # self-contained action runner.
+  #
+  # Supported actions:
+  #   { action: :git_branch }
+  #     → String or nil (current branch name)
+  #
+  #   { action: :git_remotes }
+  #     → Array of { name: String, url: String } or nil
+  #
+  #   { action: :file_exists, paths: [String, ...] }
+  #     → Hash of { path => Boolean }
+  class EnvironmentExecutor
+    def initialize(working_dir:)
+      @working_dir = working_dir
+    end
+
+    # Execute a list of action hashes and return the merged results.
+    #
+    # @param actions [Array<Hash>] each with an :action key
+    # @return [Hash] merged results keyed by action name
+    def execute(actions)
+      actions.each_with_object({}) do |action, result|
+        key = action[:action]&.to_sym
+        next unless key
+
+        case key
+        when :git_branch
+          result[:git_branch] ||= execute_git_branch
+        when :git_remotes
+          result[:git_remotes] ||= execute_git_remotes
+        when :file_exists
+          existing = result[:file_exists] || {}
+          existing.merge!(execute_file_exists(action[:paths] || []))
+          result[:file_exists] = existing
+        else
+          Superkick.logger.debug("environment_executor") { "Unknown action: #{key}" }
+        end
+      end
+    end
+
+    private
+
+    def execute_git_branch
+      out = run_git("symbolic-ref", "--short", "HEAD")&.strip
+      out unless out&.empty?
+    end
+
+    def execute_git_remotes
+      out = run_git("remote", "-v")
+      return nil unless out
+
+      remotes = {}
+      out.each_line do |line|
+        parts = line.split
+        next unless parts.size >= 2
+
+        name = parts[0]
+        url = parts[1]
+        # git remote -v shows each remote twice (fetch + push); deduplicate by name
+        remotes[name] ||= {name:, url:}
+      end
+
+      remotes.values
+    end
+
+    def execute_file_exists(paths)
+      paths.each_with_object({}) do |path, result|
+        full_path = File.join(@working_dir, path)
+        result[path] = File.exist?(full_path)
+      end
+    end
+
+    def run_git(*args)
+      IO.popen(["git", "-C", @working_dir, *args], err: File::NULL) { |io| io.read }
+    rescue SystemCallError, IOError => e
+      Superkick.logger.debug("environment_executor") { "git command failed: #{e.message}" }
+      nil
+    end
+  end
+end

data/lib/superkick/goal.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Goal — base class for spawned agent goal checks.
+  #
+  # A goal defines what "finished" means for a spawned agent.  The Supervisor
+  # runs a periodic check thread per spawned agent; on each tick it calls
+  # `check` and acts on the result.
+  #
+  # Subclass contract:
+  #   self.type   → unique Symbol (e.g. :command, :agent_exit, :agent_signal)
+  #   check       → one of STATUSES
+  #   teardown    → optional cleanup (default no-op)
+  #
+  # Status vocabulary:
+  #   :pending      — not started / waiting (non-terminal, default)
+  #   :in_progress  — actively working (non-terminal, stored for observability)
+  #   :errored      — potentially recoverable issue (non-terminal, stored)
+  #   :completed    — succeeded (terminal → terminates agent)
+  #   :failed       — irrecoverable (terminal → terminates agent)
+  #   :timed_out    — max_duration exceeded (terminal, set by Supervisor)
+  #
+  # Subclasses register themselves:
+  #   Superkick::Goal.register(MyGoal)
+  #
+  # Configuration (inside a spawner's goal: block in config.yml):
+  #
+  #   spawners:
+  #     my-spawner:
+  #       goal:
+  #         type: command
+  #         run: "gh pr list --head $BRANCH --json number -q '.[0].number'"
+  class Goal
+    STATUSES = %i[pending in_progress errored completed failed timed_out].freeze
+    TERMINAL_STATUSES = %i[completed failed timed_out].freeze
+
+    attr_reader :config, :agent_id
+
+    def initialize(config:, agent_id:)
+      @config = config
+      @agent_id = agent_id
+    end
+
+    # ── Registry (stores classes, keyed by type) ─────────────────────────
+    @registry = {}
+
+    class << self
+      include Superkick::Registry
+
+      def register(goal_class)
+        key = goal_class.type
+        raise ArgumentError, "Goal :#{key} already registered" if @registry.key?(key)
+        @registry[key] = goal_class
+      end
+
+      def lookup(name)
+        @registry[name.to_sym] or raise ArgumentError, "Unknown goal type: #{name.inspect}"
+      end
+
+      def registered
+        @registry.dup.freeze
+      end
+
+      # Build a goal instance from a spawner's goal config hash.
+      def build(config, agent_id:)
+        type_name = config[:type]
+        raise ArgumentError, "Goal config must include :type" unless type_name
+        klass = lookup(type_name.to_s.to_sym)
+        klass.new(config:, agent_id:)
+      end
+    end
+
+    # ── Instance interface ───────────────────────────────────────────────
+
+    def self.type
+      raise NotImplementedError, "#{self}.type not implemented"
+    end
+
+    # Human-readable description for discovery. Override in subclasses.
+    def self.description = nil
+
+    # Required config keys. Override in subclasses that need specific config.
+    def self.required_config = []
+
+    # Check whether the goal has been reached.
+    # @return [Symbol] one of STATUSES
+    def check
+      raise NotImplementedError, "#{self.class}#check not implemented"
+    end
+
+    def teardown
+      # Default no-op — goals may override to clean up resources.
+    end
+  end
+end

data/lib/superkick/goals/agent_exit.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Goals
+    # Goal that completes when the AI CLI process exits.
+    #
+    # This doesn't actively check anything — the Supervisor calls
+    # `signal!` when the agent process ends (via the unregister flow).
+    # Clean exit (0) → :completed, non-zero → :failed.
+    #
+    # Configuration:
+    #   goal:
+    #     type: agent_exit
+    class AgentExit < Goal
+      def self.type = :agent_exit
+
+      def self.description
+        "Completes when the AI CLI process exits. Clean exit (0) maps to " \
+          "completed, non-zero maps to failed."
+      end
+
+      def initialize(config:, agent_id:)
+        super
+        @status = :pending
+        @mutex = Mutex.new
+      end
+
+      # Called by the Supervisor when the agent process exits.
+      # @param status [Symbol] :completed or :failed
+      def signal!(status)
+        @mutex.synchronize { @status = status.to_sym }
+      end
+
+      def check
+        @mutex.synchronize { @status }
+      end
+    end
+  end
+end
+
+Superkick::Goal.register(Superkick::Goals::AgentExit)

data/lib/superkick/goals/agent_signal.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Goals
+    # Goal that completes when the AI CLI calls the `superkick_signal_goal` MCP tool.
+    #
+    # The signal is received via IPC → stored on the Agent's goal_status →
+    # and `check` reads it.  This goal is purely reactive; it never polls.
+    #
+    # This is the default goal type when no goal is specified in spawner config.
+    #
+    # Configuration:
+    #   goal:
+    #     type: agent_signal
+    class AgentSignal < Goal
+      def self.type = :agent_signal
+
+      def self.description
+        "Completes when the agent calls the superkick_signal_goal MCP tool. " \
+          "Use this when the agent should decide when it is done. " \
+          "This is the default goal type."
+      end
+
+      def initialize(config:, agent_id:)
+        super
+        @status = :pending
+        @mutex = Mutex.new
+      end
+
+      # Called by the IPC server when a superkick_signal_goal arrives.
+      def signal!(status)
+        @mutex.synchronize { @status = status.to_sym }
+      end
+
+      def check
+        @mutex.synchronize { @status }
+      end
+    end
+  end
+end
+
+Superkick::Goal.register(Superkick::Goals::AgentSignal)