superkick 0.1.0

data/lib/superkick/cost_accumulator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Per-agent cost tracker. Stores on the Agent object and records
+  # cost samples from PTY scraping and MCP self-reporting.
+  #
+  # Thread-safe — all mutations go through a mutex.
+  class CostAccumulator
+    MAX_SAMPLES = 100
+
+    attr_reader :total_tokens_in, :total_tokens_out, :total_cost_usd,
+      :samples, :last_sample_at
+
+    def initialize
+      @total_tokens_in = 0
+      @total_tokens_out = 0
+      @total_cost_usd = 0.0
+      @samples = []
+      @last_sample_at = nil
+      @mutex = Mutex.new
+    end
+
+    # Record a cost sample from any source.
+    # @param tokens_in [Integer] input tokens (incremental)
+    # @param tokens_out [Integer] output tokens (incremental)
+    # @param cost_usd [Float] cost in USD (incremental)
+    # @param source [Symbol] e.g. :pty_scrape, :mcp_report, :unknown
+    def record(tokens_in: 0, tokens_out: 0, cost_usd: 0.0, source: :unknown)
+      @mutex.synchronize do
+        @total_tokens_in += tokens_in
+        @total_tokens_out += tokens_out
+        @total_cost_usd += cost_usd
+        @samples << {
+          at: Time.now.iso8601,
+          tokens_in:, tokens_out:, cost_usd:, source:
+        }
+        @samples.shift if @samples.size > MAX_SAMPLES
+        @last_sample_at = Time.now
+      end
+    end
+
+    def to_h
+      @mutex.synchronize do
+        {
+          total_tokens_in: @total_tokens_in,
+          total_tokens_out: @total_tokens_out,
+          total_cost_usd: @total_cost_usd.round(4),
+          sample_count: @samples.size
+        }
+      end
+    end
+  end
+end

data/lib/superkick/cost_extractor.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Line-buffered cost extraction from PTY output.
+  #
+  # Buffers stripped output text and processes complete lines against
+  # driver-provided CostPattern instances. Uses cumulative-to-delta
+  # conversion so repeated status-bar refreshes (same cost) produce
+  # no duplicate samples.
+  class CostExtractor
+    MAX_BUFFER = 1024
+
+    def initialize(patterns:)
+      @patterns = patterns
+      @buffer = +""
+      @last_cumulative = {tokens_in: 0, tokens_out: 0, cost_usd: 0.0}
+    end
+
+    # Feed stripped output text. Returns array of cost deltas.
+    # Each delta is a hash like { tokens_in: N, cost_usd: F }.
+    def feed(text)
+      @buffer << text
+      deltas = []
+
+      while (idx = @buffer.index("\n"))
+        line = @buffer.slice!(0, idx + 1).strip
+        delta = process_line(line)
+        deltas << delta if delta
+      end
+
+      # Prevent unbounded buffer growth
+      @buffer = @buffer[-MAX_BUFFER..] || @buffer if @buffer.size > MAX_BUFFER
+
+      deltas
+    end
+
+    private
+
+    def process_line(line)
+      @patterns.each do |cp|
+        m = cp.pattern.match(line)
+        next unless m
+
+        raw = cp.extractor.call(m)
+        next unless raw
+
+        return compute_delta(raw)
+      end
+      nil
+    end
+
+    # Convert cumulative cost reports to incremental deltas.
+    def compute_delta(raw)
+      delta = {}
+      %i[tokens_in tokens_out cost_usd].each do |key|
+        next unless raw[key]
+        prev = @last_cumulative[key] || 0
+        d = raw[key] - prev
+        delta[key] = d if d > 0
+        @last_cumulative[key] = raw[key]
+      end
+      delta.empty? ? nil : delta
+    end
+  end
+end

data/lib/superkick/cost_poller.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Periodic cost command injection for spawned agents with stale cost data.
+  #
+  # When passive PTY scraping hasn't produced a cost sample recently,
+  # the poller enqueues the driver's cost command (e.g. `/cost`, `/stats`)
+  # into the agent's InjectionQueue to force fresh data.
+  #
+  # Only runs for spawned (headless) agents — interactive agents have
+  # a human who can type `/cost` themselves.
+  class CostPoller
+    DEFAULT_INTERVAL = 300      # check every 5 minutes
+    DEFAULT_STALE_AFTER = 600   # cost data is stale after 10 minutes
+
+    def initialize(agent_id:, store:, buffer_client: nil, config: Superkick.config, interval: nil, stale_after: nil)
+      @agent_id = agent_id
+      @store = store
+      @config = config
+      @buffer_client = buffer_client || Buffer.client_from(store:, config:)
+      @interval = interval || @config.cost_poll_interval || DEFAULT_INTERVAL
+      @stale_after = stale_after || @config.cost_stale_after || DEFAULT_STALE_AFTER
+    end
+
+    def run
+      loop do
+        sleep @interval
+        poll
+      rescue => e
+        Superkick.logger.error("cost_poll:#{@agent_id}") { e.message }
+      end
+    end
+
+    private
+
+    def poll
+      return unless Superkick.driver&.cost_command
+
+      agent = @store.get(@agent_id)
+      return unless agent
+
+      last_sample_at = agent.cost.last_sample_at
+      if last_sample_at.nil? || stale?(last_sample_at)
+        enqueue_cost_command
+      end
+    end
+
+    def stale?(last_sample_at)
+      Time.now - last_sample_at > @stale_after
+    end
+
+    def enqueue_cost_command
+      return unless @buffer_client.reachable?(@agent_id)
+
+      command = Superkick.driver.cost_command
+      @buffer_client.send_command(@agent_id, "enqueue_injection",
+        id: "cost-#{@agent_id}-#{Time.now.to_i}",
+        prompt: command,
+        monitor_type: "system",
+        monitor_name: "cost_poller",
+        priority: "low",
+        ttl: 60,
+        supersede_key: "cost_poller")
+
+      Superkick.logger.debug("cost_poll:#{@agent_id}") { "Enqueued #{command}" }
+    rescue Buffer::Client::AgentUnreachable, SystemCallError, IOError, JSON::ParserError => e
+      Superkick.logger.debug("cost_poll:#{@agent_id}") { "Enqueue failed: #{e.message}" }
+    end
+  end
+end

data/lib/superkick/driver/profile_source.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Superkick
+  class Driver
+    # ProfileSource — abstract base class for named driver profile sources.
+    #
+    # A profile is a named, reusable set of driver configuration options
+    # (type, config_dir, command, args, env) that can be referenced by name
+    # from spawner configs via `driver: { profile: :review }`.
+    #
+    # This follows the same registry + build pattern as RepositorySource:
+    #   - StaticProfileSource for YAML-configured profiles (the default)
+    #   - Future implementations can back onto a database for hosted mode
+    #
+    # Profile Hash structure:
+    #   { type: :claude_code,
+    #     config_dir: "~/.superkick/driver-configs/review/.claude",
+    #     command: "/opt/bin/claude",
+    #     args: ["--verbose"],
+    #     env: { "ANTHROPIC_API_KEY" => "sk-review" } }
+    #
+    # Subclass contract:
+    #   self.type     → unique Symbol (e.g. :static)
+    #   get(name)     → profile Hash or nil
+    #   list          → Hash of { name_sym => profile Hash }
+    class ProfileSource
+      @registry = {}
+
+      class << self
+        include Superkick::Registry
+
+        def register(source_class)
+          key = source_class.type
+          raise ArgumentError, "ProfileSource :#{key} already registered" if @registry.key?(key)
+          @registry[key] = source_class
+        end
+
+        def lookup(name)
+          @registry[name.to_sym] or raise ArgumentError, "Unknown profile source type: #{name.inspect}"
+        end
+
+        def registered
+          @registry.dup.freeze
+        end
+
+        # Build a source from a profiles config hash.
+        #
+        # Accepts a Hash where each key is a profile name and each value is
+        # a profile config hash (type, config_dir, command, args, env).
+        #
+        # Currently always builds a StaticProfileSource. Future typed sources
+        # (e.g. database-backed) can be distinguished by a :source_type key.
+        def build(config)
+          config = {} if config.nil?
+          StaticProfileSource.new(config)
+        end
+      end
+
+      def self.type
+        raise NotImplementedError, "#{self}.type not implemented"
+      end
+
+      # Look up a profile by name.
+      # @param name [Symbol, String] profile name
+      # @return [Hash, nil] normalized profile config or nil
+      def get(name)
+        raise NotImplementedError, "#{self.class}#get not implemented"
+      end
+
+      # List all profiles.
+      # @return [Hash] { name_sym => profile Hash }
+      def list
+        raise NotImplementedError, "#{self.class}#list not implemented"
+      end
+
+      def empty?
+        list.empty?
+      end
+
+      def size
+        list.size
+      end
+    end
+
+    # StaticProfileSource — profiles defined inline in the YAML config.
+    #
+    # Each key is a profile name, each value is a driver config hash.
+    #
+    # Example YAML:
+    #   drivers:
+    #     profiles:
+    #       review:
+    #         type: claude_code
+    #         config_dir: ~/.superkick/driver-configs/review/.claude
+    #         env:
+    #           ANTHROPIC_API_KEY: sk-review
+    #       worker:
+    #         type: claude_code
+    #         config_dir: ~/.superkick/driver-configs/worker/.claude
+    class StaticProfileSource < ProfileSource
+      def self.type = :static
+
+      def initialize(profiles_config = {})
+        raw = profiles_config.is_a?(Hash) ? profiles_config : {}
+        @profiles = raw.each_with_object({}) do |(name, config), h|
+          next unless config.is_a?(Hash)
+          h[name.to_sym] = normalize_profile(name, config)
+        end.freeze
+      end
+
+      def get(name)
+        @profiles[name.to_sym]
+      end
+
+      def list
+        @profiles
+      end
+
+      private
+
+      def normalize_profile(name, config)
+        profile = {name: name.to_sym}
+        profile[:type] = config[:type].to_sym if config[:type]
+        profile[:config_dir] = File.expand_path(config[:config_dir]) if config[:config_dir]
+        profile[:command] = config[:command] if config[:command]
+        profile[:args] = Array(config[:args]) if config[:args]
+        profile[:env] = config[:env] if config[:env].is_a?(Hash)
+        profile
+      end
+    end
+
+    ProfileSource.register(StaticProfileSource)
+  end
+end

data/lib/superkick/driver.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Cost extraction pattern — matched against stripped PTY output lines.
+  # @param pattern [Regexp] matched against the line
+  # @param extractor [Proc] receives MatchData, returns { tokens_in:, tokens_out:, cost_usd: } (all optional)
+  CostPattern = Data.define(:pattern, :extractor)
+
+  # Driver — base class for AI coding CLI drivers.
+  #
+  # The registry stores **classes**. Superkick.use(:driver_name, **opts)
+  # instantiates the class and stores the instance on Superkick.driver.
+  # Consumers read from the instance directly.
+  #
+  # ## Instance interface (the contract)
+  #
+  #   driver_name       → Symbol   — unique identifier (e.g. :claude_code)
+  #   cli_command       → String   — executable name or path (e.g. "claude")
+  #   prompt_patterns   → [Regexp] — matched against stripped pty output to detect idle prompt
+  #   injection_guards  → [PatternGuard] — suppress injection when any pattern matches
+  #   install_mcp(exe_path:) → void — configure the CLI's MCP settings for Superkick
+  #
+  # ## Subclass contract
+  #
+  # Subclasses must:
+  #   - Define `self.driver_name` (used as the registry key)
+  #   - Implement `initialize(**opts)` accepting driver-specific config
+  #   - Implement instance methods: driver_name, cli_command
+  #
+  # Subclasses may override:
+  #   - prompt_patterns (default: [])
+  #   - injection_guards (default: [])
+  #   - install_mcp (default: prints manual instructions)
+  class Driver
+    # ── Registry (stores classes) ──────────────────────────────────────────
+    @registry = {}
+
+    class << self
+      include Superkick::Registry
+
+      def register(driver_class)
+        key = driver_class.driver_name
+        raise ArgumentError, "Driver :#{key} is already registered" if @registry.key?(key)
+        @registry[key] = driver_class
+      end
+
+      def lookup(name)
+        @registry[name.to_sym] or raise ArgumentError, "Unknown driver: #{name.inspect}"
+      end
+
+      def registered
+        @registry.dup.freeze
+      end
+
+      def names
+        @registry.keys
+      end
+    end
+
+    # ── Driver config normalization and merging ────────────────────────────
+
+    # Normalize a polymorphic driver value to a Hash.
+    #
+    # Accepts:
+    #   - String/Symbol → { type: :driver_name }
+    #   - Hash → dup with symbolized :type
+    #   - nil → nil
+    #
+    # When the Hash contains a :profile key and a profile_source is provided,
+    # the named profile is resolved and used as the base, with any remaining
+    # keys merged on top.
+    def self.normalize_driver(driver, profile_source: nil)
+      case driver
+      when String, Symbol
+        {type: driver.to_sym}
+      when Hash
+        resolved = driver.dup
+        resolved[:type] = resolved[:type].to_sym if resolved[:type]
+
+        # Resolve profile reference
+        if resolved[:profile] && profile_source
+          profile_name = resolved.delete(:profile).to_sym
+          profile = profile_source.get(profile_name)
+          if profile
+            overrides = resolved.empty? ? nil : resolved
+            resolved = profile.dup
+            resolved = merge_driver(resolved, overrides) if overrides
+          else
+            Superkick.logger.warn("driver") { "Unknown driver profile: #{profile_name.inspect}" }
+          end
+        elsif resolved[:profile]
+          # Profile reference without source — strip the key, it's unresolvable
+          resolved.delete(:profile)
+        end
+
+        resolved
+      end
+    end
+
+    # Deep-merge two driver config values.
+    #
+    # When the override is a String/Symbol, it replaces the entire base
+    # config (no merge — it's a complete type override with no extra options).
+    #
+    # When both are Hashes:
+    # - Scalar keys (type, config_dir, command) — override wins
+    # - args — arrays are concatenated (base first, then override)
+    # - env — hashes are merged (override keys win)
+    def self.merge_driver(base, override)
+      return normalize_driver(base) unless override
+      return normalize_driver(override) unless base
+
+      # String/Symbol override = complete replacement (no merge)
+      return normalize_driver(override) if override.is_a?(String) || override.is_a?(Symbol)
+
+      base = normalize_driver(base)
+      override = normalize_driver(override)
+
+      merged = base.merge(override)
+      # Deep-merge env hashes
+      if base[:env] && override[:env]
+        merged[:env] = base[:env].merge(override[:env])
+      end
+      # Concatenate args arrays
+      if base[:args] && override[:args]
+        merged[:args] = base[:args] + override[:args]
+      end
+      merged
+    end
+
+    # ── Instance interface ─────────────────────────────────────────────────
+
+    def driver_name = raise(NotImplementedError, "#{self.class}#driver_name not implemented")
+    def cli_command = raise(NotImplementedError, "#{self.class}#cli_command not implemented")
+    def prompt_patterns = []
+    def injection_guards = []
+
+    # Returns an array of CostPattern structs for extracting cost data
+    # from PTY output. Each pattern extracts cost data from a line.
+    # @return [Array<CostPattern>] — empty by default (no cost tracking)
+    def cost_patterns = []
+
+    # Returns the CLI command string that displays cost/usage info,
+    # or nil if the CLI has no such command.
+    # @return [String, nil]
+    def cost_command = nil
+
+    # Apply config_dir override to the spawned process environment and args.
+    # Each driver knows how its CLI accepts a settings directory override
+    # (env var, flag, etc.). The base implementation is a no-op.
+    #
+    # @param config_dir [String] expanded path to the config/settings directory
+    # @param env [Hash] mutable env hash — add env vars here
+    # @param args [Array] mutable args array — prepend flags here
+    def apply_config_dir(config_dir, env:, args:)
+      # No-op by default — drivers that support config_dir override this
+    end
+
+    # MCP installation — default prints generic manual instructions.
+    # Subclasses override to write their specific config file.
+    def install_mcp(exe_path:)
+      print_manual_instructions(exe_path)
+    end
+
+    private
+
+    def print_manual_instructions(exe_path)
+      $stdout.puts <<~MSG
+        Could not automatically configure MCP. Add the following manually:
+
+          Command   : #{exe_path} mcp
+          Args      : (none)
+          Transport : stdio
+
+        Consult your CLI's documentation for MCP server configuration.
+      MSG
+    end
+  end
+end

data/lib/superkick/drivers/claude_code.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Superkick
+  module Drivers
+    class ClaudeCode < Driver
+      DEFAULT_CONFIG_DIR = File.join(Dir.home, ".claude").freeze
+
+      def self.driver_name = :claude_code
+
+      def initialize(cli_command: "claude", config_dir: DEFAULT_CONFIG_DIR, **)
+        @cli_command = cli_command
+        @config_dir = config_dir
+      end
+
+      attr_reader :cli_command
+
+      def driver_name = :claude_code
+
+      def prompt_patterns
+        [
+          /^\s*>\s*$/,
+          /Human:\s*$/,
+          /\$\s*$/
+        ]
+      end
+
+      def injection_guards
+        [
+          Superkick::PatternGuard.new(
+            name: :image_attached,
+            pattern: /\[Image\s*#?\d+\]/i,
+            reason: "Image is attached to current input",
+            clear_on_submit: true
+          )
+        ]
+      end
+
+      def cost_patterns
+        [
+          CostPattern.new(
+            pattern: /Total cost:\s*\$([0-9]+\.?[0-9]*)/,
+            extractor: ->(m) { {cost_usd: m[1].to_f} }
+          ),
+          CostPattern.new(
+            pattern: /(\d+(?:\.\d+)?[km]?)\s*in,\s*(\d+(?:\.\d+)?[km]?)\s*out/i,
+            extractor: ->(m) {
+              {tokens_in: parse_token_count(m[1]),
+               tokens_out: parse_token_count(m[2])}
+            }
+          )
+        ]
+      end
+
+      def cost_command = "/cost"
+
+      def apply_config_dir(config_dir, env:, args:)
+        env["CLAUDE_CONFIG_DIR"] = 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} (path matches)."
+          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 parse_token_count(str)
+        num = str.to_f
+        case str[-1]
+        when "k", "K" then (num * 1_000).to_i
+        when "m", "M" then (num * 1_000_000).to_i
+        else num.to_i
+        end
+      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::ClaudeCode)

data/lib/superkick/drivers/codex.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Superkick
+  module Drivers
+    class Codex < Driver
+      DEFAULT_CONFIG_DIR = File.join(Dir.home, ".codex").freeze
+
+      def self.driver_name = :codex
+
+      def initialize(cli_command: "codex", config_dir: DEFAULT_CONFIG_DIR, **)
+        @cli_command = cli_command
+        @config_dir = config_dir
+      end
+
+      attr_reader :cli_command
+
+      def driver_name = :codex
+
+      def prompt_patterns
+        [/codex>\s*$/]
+      end
+
+      def apply_config_dir(config_dir, env:, args:)
+        env["CODEX_HOME"] = config_dir
+      end
+
+      def install_mcp(exe_path:)
+        config_path = File.join(@config_dir, "config.toml")
+        content = File.exist?(config_path) ? File.read(config_path) : ""
+
+        if content.include?("[mcp.servers.superkick]")
+          $stdout.puts "Superkick already present in #{config_path}."
+          return
+        end
+
+        if system("codex mcp add superkick #{exe_path} mcp",
+          out: File::NULL, err: File::NULL)
+          $stdout.puts "Superkick MCP server added via `codex mcp add`."
+          return
+        end
+
+        FileUtils.mkdir_p(File.dirname(config_path))
+        File.open(config_path, "a") do |f|
+          f.puts "\n[mcp.servers.superkick]"
+          f.puts "command = \"#{exe_path}\""
+          f.puts "args    = [\"mcp\"]"
+        end
+
+        $stdout.puts "Superkick MCP server installed in #{config_path}."
+      end
+    end
+  end
+end
+
+Superkick::Driver.register(Superkick::Drivers::Codex)