superkick 0.1.0

data/lib/superkick/configuration.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Superkick
+  class Configuration
+    attr_accessor :base_dir,
+      :poll_interval,
+      :idle_threshold,
+      :inject_clear_delay,
+      :rate_limit_backoff,
+      :error_backoff,
+      :log_level,
+      :monitors,
+      :privileged_types,
+      :notifications,
+      :notification_privileged_types,
+      :spawners,
+      :attach_history_size,
+      :attach_escape_key,
+      :attach_rw_idle_timeout,
+      :attach_replay_buffer_size,
+      :attach_max_connections,
+      :budget,
+      :cost_poll_interval,
+      :cost_stale_after,
+      :repositories,
+      :max_workers_per_team,
+      :server,
+      :driver_profiles,
+      :runtime,
+      :session_recording_enabled,
+      :session_recording_max_size
+
+    attr_reader :context_documents
+
+    def context_documents=(value)
+      @context_documents = value
+      @resolved_context_document_patterns = nil
+    end
+
+    def initialize
+      @base_dir = ENV.fetch("SUPERKICK_DIR", File.join(Dir.home, ".superkick"))
+      @poll_interval = 30
+      @idle_threshold = 5.0
+      @inject_clear_delay = 0.15
+      @rate_limit_backoff = 60
+      @error_backoff = 10
+      @log_level = :info
+      @monitors = {}
+      @privileged_types = []
+      @notifications = []
+      @notification_privileged_types = []
+      @spawners = {}
+      @attach_history_size = 100 * 1024 # 100 KB
+      @attach_escape_key = "\x01" # Ctrl-A
+      @attach_rw_idle_timeout = 300 # 5 minutes
+      @attach_replay_buffer_size = 65_536 # 64 KB (relay-side history for remote attach)
+      @attach_max_connections = 10 # max concurrent user connections per agent at relay
+      @budget = {}
+      @cost_poll_interval = nil
+      @cost_stale_after = nil
+      @repositories = {}
+      @context_documents = []
+      @max_workers_per_team = 5
+      @server = {}
+      @driver_profiles = {}
+      @runtime = {}
+      @session_recording_enabled = true
+      @session_recording_max_size = 100 * 1024 * 1024 # 100 MB
+    end
+
+    # Resolved server type from server config.
+    # Inferred from the presence of :url when not explicitly set.
+    def server_type
+      explicit = @server[:type]&.to_sym
+      return explicit if explicit
+
+      @server[:url] ? :hosted : :local
+    end
+
+    # Is the named monitor instance privileged?
+    # Checks the per-monitor "privileged" flag in the monitors config.
+    def monitor_privileged?(name)
+      config = @monitors[name.to_sym]
+      config.is_a?(Hash) && config[:privileged] == true
+    end
+
+    # Is the given monitor type privileged?
+    def type_privileged?(type)
+      @privileged_types.include?(type.to_sym)
+    end
+
+    # Is the named notifier instance privileged?
+    # Checks the per-notifier "privileged" flag in the notifications config.
+    def notifier_privileged?(name)
+      @notifications.any? { |n| n.is_a?(Hash) && n[:name]&.to_sym == name.to_sym && n[:privileged] == true }
+    end
+
+    # Is the given notifier type privileged?
+    def notifier_type_privileged?(type)
+      @notification_privileged_types.include?(type.to_sym)
+    end
+
+    # Filesystem paths — all derived from base_dir.
+
+    def run_dir = File.join(base_dir, "run")
+    def socket_path = File.join(run_dir, "server.sock")
+    def pid_path = File.join(run_dir, "server.pid")
+    def log_path = File.join(base_dir, "superkick.log")
+    def agents_dir = File.join(base_dir, "sessions")
+    def templates_dir = File.join(base_dir, "templates")
+    def output_logs_dir = File.join(base_dir, "logs")
+    def recordings_dir = File.join(base_dir, "recordings")
+
+    def teams_dir = File.join(base_dir, "teams")
+    def workspaces_dir = File.join(base_dir, "workspaces")
+
+    attr_writer :repository_source
+
+    def repository_source
+      @repository_source ||= RepositorySource.build(@repositories)
+    end
+
+    # Resolve the global context_documents config into a { name => pattern } hash.
+    # Accepts bare strings/symbols (resolved from Repository::CONTEXT_DOCUMENT_PATTERNS)
+    # and custom entries with name: + pattern: keys.
+    def resolved_context_document_patterns
+      @resolved_context_document_patterns ||= resolve_context_document_config(@context_documents)
+    end
+
+    def driver_profile_source
+      @driver_profile_source ||= Driver::ProfileSource.build(@driver_profiles)
+    end
+
+    def agent_runtime
+      @agent_runtime ||= build_agent_runtime
+    end
+
+    private
+
+    def resolve_context_document_config(config)
+      return {} unless config.is_a?(Array) && config.any?
+
+      config.each_with_object({}) do |entry, h|
+        if entry.is_a?(Hash) && entry[:name] && entry[:pattern]
+          h[entry[:name].to_sym] = entry[:pattern].to_s
+        elsif entry.is_a?(String) || entry.is_a?(Symbol)
+          name = entry.to_sym
+          pattern = Repository::CONTEXT_DOCUMENT_PATTERNS[name]
+          h[name] = pattern if pattern
+        end
+      end
+    end
+
+    def build_agent_runtime
+      type = @runtime[:type]&.to_sym || :local
+      klass = Agent::Runtime.lookup(type)
+      runtime_config = @runtime[type] || {}
+      runtime_config = runtime_config.merge(server: build_runtime_server_context)
+      klass.new(**runtime_config)
+    end
+
+    def build_runtime_server_context
+      ctx = {type: server_type}
+      ctx[:base_dir] = base_dir if server_type == :local
+      ctx
+    end
+
+    public
+
+    def buffer_socket_path(agent_id)
+      File.join(run_dir, "buffer-#{agent_id}.sock")
+    end
+
+    def attach_socket_path(agent_id)
+      File.join(run_dir, "attach-#{agent_id}.sock")
+    end
+  end
+end

data/lib/superkick/connection.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Superkick
+  # Bidirectional connection wrapper for Unix domain sockets.
+  # Adds newline-delimited JSON framing on top of a raw socket.
+  # Used by both the control plane (Control::Server, Control::Client)
+  # and the data plane (Buffer::Server, Buffer::Client, etc.).
+  # The underlying socket is managed by the caller — Connection does not own
+  # the socket lifecycle, it just closes it when asked.
+  class Connection
+    # Open a fresh UNIXSocket to +path+ and wrap it.
+    def self.open(path)
+      new(UNIXSocket.new(path))
+    end
+
+    def initialize(socket)
+      @socket = socket
+    end
+
+    # Encode +hash+ as newline-delimited JSON and write it to the socket.
+    # Used by clients to send requests.
+    def send_message(hash)
+      @socket.write("#{JSON.generate(hash)}\n")
+      @socket.flush
+    end
+
+    # Send a successful response. +payload+ is merged into { ok: true }.
+    def reply(payload = {})
+      @socket.write("#{JSON.generate({ok: true}.merge(payload))}\n")
+      @socket.flush
+    end
+
+    # Send an error response.
+    def error(message)
+      @socket.write("#{JSON.generate({ok: false, error: message})}\n")
+      @socket.flush
+    end
+
+    # Read one line from the socket and decode it. Returns nil if the peer
+    # closed the connection before sending a complete line.
+    def receive_message
+      line = @socket.gets
+      return nil unless line
+
+      JSON.parse(line.chomp, symbolize_names: true)
+    end
+
+    def close
+      @socket.close
+    rescue IOError, Errno::EBADF, Errno::ENOTCONN
+      nil
+    end
+  end
+end

data/lib/superkick/control/client.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Superkick
+  module Control
+    @clients = {}
+    extend ClientRegistry
+
+    # Control client for communicating with the Superkick server.
+    #
+    # The default implementation communicates over a Unix socket. In hosted
+    # mode, a subclass (Hosted::Control::Client) communicates over HTTPS.
+    #
+    # All call sites use Control.client_from to construct the right
+    # implementation for the configured server type.
+    class Client
+      # Shared exception that callers rescue regardless of server type.
+      class ServerUnavailable < StandardError; end
+
+      # Raised when the hosted server rejects the API key (HTTP 401).
+      class AuthenticationError < ServerUnavailable; end
+
+      def self.from(config: Superkick.config, **_kwargs)
+        new(socket_path: config.socket_path)
+      end
+
+      TIMEOUT = 1 # seconds
+
+      def initialize(socket_path: Superkick.config.socket_path)
+        @socket_path = socket_path
+      end
+
+      # Send a command to the server and return the wrapped response.
+      # @param command [String] control command name
+      # @param params  [Hash]   extra key/value params merged into the request
+      # @return [Control::Reply] wrapped response from the server
+      def request(command, **params)
+        payload = {command: command}.merge(params)
+        connection = Superkick::Connection.new(connect)
+
+        begin
+          connection.send_message(payload)
+          raw = connection.receive_message
+          raise ServerUnavailable, "Server closed connection before responding" unless raw
+
+          Reply.new(raw)
+        ensure
+          connection.close
+        end
+      rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE
+        raise ServerUnavailable, "Server socket not found at #{@socket_path}"
+      end
+
+      # Returns true if the server is reachable.
+      def alive?
+        request("ping").success?
+      rescue ServerUnavailable
+        false
+      end
+
+      # No-op — each request opens and closes its own connection.
+      def close
+      end
+
+      private
+
+      def connect
+        sock = UNIXSocket.new(@socket_path)
+        sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO,
+          [TIMEOUT, 0].pack("l_2"))
+        sock
+      rescue Errno::ENOENT
+        raise ServerUnavailable, "Server socket not found: #{@socket_path}"
+      end
+    end
+  end
+end

data/lib/superkick/control/reply.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Control
+    # Wraps a parsed control response hash to provide a typed interface.
+    # Returned by Control::Client#request so callers don't have to poke at
+    # raw hash keys to check success or read the error message.
+    #
+    # The envelope fields (:ok, :error) are handled by the convenience
+    # methods. All other payload fields are accessible via [].
+    class Reply
+      def initialize(hash)
+        @hash = hash
+      end
+
+      # True when the server replied with ok: true.
+      def success?
+        @hash[:ok] == true
+      end
+
+      # True when the server replied with ok: false (or ok is absent).
+      def error?
+        !success?
+      end
+
+      # The error string from an error response; nil on success.
+      def error_message
+        @hash[:error]
+      end
+
+      # Access a payload field by key, just like a Hash.
+      def [](key)
+        @hash[key]
+      end
+
+      # Returns the payload without the envelope fields (:ok, :error).
+      # Useful when forwarding the response to another layer.
+      def payload
+        @hash.except(:ok, :error)
+      end
+    end
+  end
+end