superkick 0.1.0

data/lib/superkick/attach/protocol.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Attach
+    # Binary wire protocol for the attach system.  Shared by Attach::Server and
+    # Attach::Client.  Uses length-prefixed frames — 1 byte type + 4 byte big-endian
+    # length + payload.  JSON is only used for infrequent control messages (meta,
+    # resize, hello); output and input frames carry raw bytes with zero overhead.
+    module Protocol
+      OUTPUT = 0x01
+      INPUT = 0x02
+      META = 0x03
+      RESIZE = 0x04
+      HISTORY = 0x05
+      ERROR = 0x06
+      HELLO = 0x07
+      COMMAND = 0x08
+      NOTIFY = 0x09
+
+      # Write a single frame to an IO.
+      # @param io   [IO]      writable socket
+      # @param type [Integer]  message type constant
+      # @param data [String]   payload bytes
+      def self.write_frame(io, type, data)
+        data = data.b if data.encoding != Encoding::BINARY
+        header = [type, data.bytesize].pack("CN")
+        io.write(header)
+        io.write(data)
+        io.flush
+      end
+
+      # Read a single frame from an IO.
+      # @return [Array(Integer, String)] [type, payload] or nil on EOF
+      def self.read_frame(io)
+        header = io.read(5)
+        return nil unless header && header.bytesize == 5
+
+        type, len = header.unpack("CN")
+        payload = if len > 0
+          io.read(len)
+        else
+          "".b
+        end
+        return nil unless payload && payload.bytesize == len
+
+        [type, payload]
+      end
+
+      # Build a frame as a binary string without writing to an IO.
+      # Used by the WebSocket bridges and transports to construct frames
+      # for sending over WebSocket binary messages.
+      # @param type [Integer]  message type constant
+      # @param data [String]   payload bytes
+      # @return [String] binary frame bytes
+      def self.build_frame(type, data)
+        data = data.b if data.encoding != Encoding::BINARY
+        [type, data.bytesize].pack("CN") + data
+      end
+
+      # Convenience: write a JSON-encoded frame.
+      def self.write_json_frame(io, type, hash)
+        write_frame(io, type, JSON.generate(hash))
+      end
+
+      # Convenience: decode a JSON payload.
+      def self.decode_json(payload)
+        JSON.parse(payload, symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/superkick/attach/server.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "socket"
+require "fileutils"
+
+module Superkick
+  module Attach
+    # Per-agent attach endpoint.  Runs inside the `superkick agent` process
+    # alongside Buffer::Server.  Manages connected attach clients and broadcasts
+    # PTY output to all of them.
+    #
+    # Supports multiple concurrent read-only clients and at most one read-write
+    # client at a time.  Read-write clients can forward keystrokes and terminal
+    # resize events to the PTY.
+    #
+    # Mode switching:
+    # - Force-takeover: HELLO with `force: true` demotes existing RW holder
+    # - In-session: COMMAND frames with `promote_rw`, `force_promote_rw`,
+    #   or `demote_ro` actions to switch modes without reconnecting
+    # - Auto-promote: claiming an agent auto-promotes to RW when slot is vacant
+    # - Idle timeout: RW clients auto-demoted after `attach_rw_idle_timeout`
+    #   seconds of no INPUT frames
+    class Server
+      attr_reader :socket_path, :history
+
+      def initialize(agent_id:, pty_proxy:, control_client: nil, config: Superkick.config)
+        @agent_id = agent_id
+        @pty_proxy = pty_proxy
+        @control_client = control_client
+        @history = HistoryBuffer.new(capacity: config.attach_history_size)
+        @socket_path = config.attach_socket_path(agent_id)
+        @rw_idle_timeout = config.attach_rw_idle_timeout
+        @clients = []          # Array of { socket:, mode: }
+        @clients_mutex = Mutex.new
+        @server = nil
+        @accept_thread = nil
+        @idle_check_thread = nil
+        @rw_client = nil       # at most one read-write client
+        @rw_last_input_at = nil # monotonic timestamp of last INPUT frame from RW client
+        @broadcast_callbacks = []
+      end
+
+      def start
+        FileUtils.mkdir_p(File.dirname(@socket_path))
+        FileUtils.rm_f(@socket_path)
+        @server = UNIXServer.new(@socket_path)
+        @accept_thread = Thread.new { accept_loop }
+        start_idle_check if @rw_idle_timeout && @rw_idle_timeout > 0
+        self
+      end
+
+      def stop
+        begin
+          @server&.close
+        rescue IOError
+          nil
+        end
+        begin
+          @accept_thread&.kill
+        rescue ThreadError
+          nil
+        end
+        begin
+          @idle_check_thread&.kill
+        rescue ThreadError
+          nil
+        end
+        @clients_mutex.synchronize do
+          @clients.each do |c|
+            c[:socket].close
+          rescue IOError
+            nil
+          end
+          @clients.clear
+        end
+        FileUtils.rm_f(@socket_path)
+      end
+
+      # Register a callback that receives every data chunk passed to broadcast().
+      # Used by the Hosted::Attach::Bridge to forward output to the relay.
+      def on_broadcast(&block)
+        @broadcast_callbacks << block
+      end
+
+      # Called by PtyProxy#proxy_output on every chunk of PTY output.
+      # Writes to history buffer and broadcasts to all connected clients.
+      def broadcast(data)
+        @history.write(data)
+
+        @clients_mutex.synchronize do
+          @clients.reject! do |client|
+            Protocol.write_frame(client[:socket], Protocol::OUTPUT, data)
+            false
+          rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+            Superkick.logger.debug("attach:#{@agent_id}") { "Client disconnected" }
+            @rw_client = nil if @rw_client == client[:socket]
+            true # remove from list
+          end
+        end
+
+        @broadcast_callbacks.each { it.call(data) }
+      end
+
+      # Accept a raw Protocol frame from the hosted bridge (remote input).
+      # The relay handles RW exclusivity for remote users — it only forwards
+      # INPUT and RESIZE frames from the RW user.
+      def handle_remote_input(data)
+        data = data.b if data.is_a?(String) && data.encoding != Encoding::BINARY
+        return if data.bytesize < 5
+
+        type = data.getbyte(0)
+        payload_len = data[1, 4].unpack1("N")
+        payload = data[5, payload_len]
+        return unless payload
+
+        case type
+        when Protocol::INPUT
+          @pty_proxy.enqueue_inject(payload)
+        when Protocol::RESIZE
+          resize_data = Protocol.decode_json(payload)
+          @pty_proxy.resize(resize_data[:rows], resize_data[:cols])
+        end
+      end
+
+      private
+
+      def accept_loop
+        loop do
+          raw = @server.accept
+          Thread.new(raw) { handle_client(it) }
+        rescue IOError, Errno::EBADF
+          break
+        rescue => e
+          Superkick.logger.error("attach:#{@agent_id}") {
+            "Accept error: #{e.message}"
+          }
+        end
+      end
+
+      def handle_client(socket)
+        # 1. Read hello frame
+        frame = Protocol.read_frame(socket)
+        unless frame && frame[0] == Protocol::HELLO
+          begin
+            socket.close
+          rescue IOError
+            nil
+          end
+          return
+        end
+
+        hello = Protocol.decode_json(frame[1])
+        mode = (hello[:mode] == "rw") ? :rw : :ro
+        force = hello[:force] == true
+
+        # 2. Check read-write exclusivity
+        if mode == :rw
+          @clients_mutex.synchronize do
+            if @rw_client
+              if force
+                demote_rw_client_locked("Read-write taken over by another client", event_type: :attach_force_takeover)
+              else
+                Protocol.write_json_frame(socket, Protocol::ERROR,
+                  {message: "Another read-write client is already connected"})
+                begin
+                  socket.close
+                rescue IOError
+                  nil
+                end
+                return
+              end
+            end
+            @rw_client = socket
+            @rw_last_input_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+        end
+
+        # 3. Send metadata
+        meta = build_meta
+        Protocol.write_json_frame(socket, Protocol::META, meta)
+
+        # 4. Replay history
+        history_data = @history.snapshot
+        unless history_data.empty?
+          Protocol.write_frame(socket, Protocol::HISTORY, history_data)
+        end
+
+        # 5. Register client for broadcast
+        client_entry = {socket:, mode:}
+        @clients_mutex.synchronize { @clients << client_entry }
+
+        # 6. Unified frame processing loop — all clients (RW and RO) use the
+        # same loop.  INPUT and RESIZE are only forwarded for the active RW
+        # client; COMMAND frames are always processed.
+        read_client_frames(socket)
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        # Client disconnected
+      ensure
+        @clients_mutex.synchronize do
+          @clients.reject! { |c| c[:socket] == socket }
+          @rw_client = nil if @rw_client == socket
+        end
+        begin
+          socket.close
+        rescue IOError
+          nil
+        end
+      end
+
+      def read_client_frames(socket)
+        loop do
+          frame = Protocol.read_frame(socket)
+          break unless frame
+
+          type, payload = frame
+          case type
+          when Protocol::INPUT
+            if @rw_client == socket
+              @rw_last_input_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              @pty_proxy.enqueue_inject(payload)
+            end
+          when Protocol::RESIZE
+            if @rw_client == socket
+              data = Protocol.decode_json(payload)
+              @pty_proxy.resize(data[:rows], data[:cols])
+            end
+          when Protocol::COMMAND
+            cmd = Protocol.decode_json(payload)
+            handle_attach_command(cmd, socket)
+          end
+        end
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        # Client disconnected
+      end
+
+      def handle_attach_command(cmd, socket)
+        case cmd[:action]
+        when "claim"
+          control = Control.client_from
+          result = control.request("claim_agent", agent_id: @agent_id)
+          Superkick.logger.info("attach:#{@agent_id}") { "Claim via attach: #{result.success? ? "ok" : result.error_message}" }
+          # Auto-promote to RW when claiming and slot is vacant
+          if result.success?
+            @clients_mutex.synchronize do
+              promote_client_locked(socket) unless @rw_client
+            end
+          end
+        when "unclaim"
+          control = Control.client_from
+          result = control.request("unclaim_agent", agent_id: @agent_id)
+          Superkick.logger.info("attach:#{@agent_id}") { "Unclaim via attach: #{result.success? ? "ok" : result.error_message}" }
+        when "promote_rw"
+          @clients_mutex.synchronize do
+            if @rw_client == socket
+              notify_client(socket, "Already in read-write mode")
+            elsif @rw_client
+              notify_client(socket, "Read-write slot is occupied — use forced promotion to take over")
+            else
+              promote_client_locked(socket)
+            end
+          end
+        when "force_promote_rw"
+          @clients_mutex.synchronize do
+            if @rw_client == socket
+              notify_client(socket, "Already in read-write mode")
+            else
+              demote_rw_client_locked("Read-write taken over by another client", event_type: :attach_force_takeover) if @rw_client
+              promote_client_locked(socket)
+            end
+          end
+        when "demote_ro"
+          @clients_mutex.synchronize do
+            if @rw_client == socket
+              @rw_client = nil
+              @rw_last_input_at = nil
+              entry = @clients.find { it[:socket] == socket }
+              entry[:mode] = :ro if entry
+              Superkick.logger.info("attach:#{@agent_id}") { "Client voluntarily demoted to read-only" }
+              notify_client(socket, "Switched to read-only mode")
+            else
+              notify_client(socket, "Already in read-only mode")
+            end
+          end
+        end
+      rescue Control::Client::ServerUnavailable
+        Superkick.logger.warn("attach:#{@agent_id}") { "Cannot #{cmd[:action]}: server unavailable" }
+      end
+
+      # Promote a client to RW.  MUST be called while holding @clients_mutex.
+      def promote_client_locked(socket)
+        @rw_client = socket
+        @rw_last_input_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        entry = @clients.find { it[:socket] == socket }
+        entry[:mode] = :rw if entry
+
+        Superkick.logger.info("attach:#{@agent_id}") { "Client promoted to read-write" }
+        notify_client(socket, "Promoted to read-write mode")
+        dispatch_attach_event(:attach_promoted, "Client promoted to read-write mode")
+      end
+
+      # Demote the current RW client to RO.  Sends a NOTIFY frame to inform them.
+      # MUST be called while holding @clients_mutex.
+      def demote_rw_client_locked(reason, event_type: :attach_demoted)
+        old_socket = @rw_client
+        return unless old_socket
+
+        @rw_client = nil
+        @rw_last_input_at = nil
+
+        entry = @clients.find { it[:socket] == old_socket }
+        entry[:mode] = :ro if entry
+
+        Superkick.logger.info("attach:#{@agent_id}") { "RW client demoted: #{reason}" }
+        notify_client(old_socket, reason)
+        dispatch_attach_event(event_type, reason)
+      end
+
+      # Send a NOTIFY frame to a client.  Swallows IO errors.
+      def notify_client(socket, message)
+        Protocol.write_json_frame(socket, Protocol::NOTIFY, {message:})
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        nil
+      end
+
+      # Fire a notification event to the server so it can dispatch to notifiers
+      # (Slack, command, terminal bell, etc.).  Best-effort — swallows errors.
+      def dispatch_attach_event(event_type, reason)
+        return unless @control_client
+
+        @control_client.request("attach_event",
+          agent_id: @agent_id,
+          event_type: event_type.to_s,
+          reason:)
+      rescue Control::Client::ServerUnavailable
+        nil
+      end
+
+      # Background thread that periodically checks if the RW client has been
+      # idle (no INPUT frames) past the configured timeout.
+      def start_idle_check
+        @idle_check_thread = Thread.new do
+          check_interval = [@rw_idle_timeout / 2.0, 30].min
+          loop do
+            sleep check_interval
+            @clients_mutex.synchronize do
+              next unless @rw_client && @rw_last_input_at
+
+              elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @rw_last_input_at
+              if elapsed >= @rw_idle_timeout
+                demote_rw_client_locked(
+                  "Demoted to read-only after #{@rw_idle_timeout.to_i}s of inactivity",
+                  event_type: :attach_idle_timeout
+                )
+              end
+            end
+          rescue => e
+            Superkick.logger.error("attach:#{@agent_id}") { "Idle check error: #{e.message}" }
+          end
+        end
+      end
+
+      def build_meta
+        {
+          agent_id: @agent_id,
+          history_bytes: @history.size
+        }
+      end
+    end
+  end
+end

data/lib/superkick/budget_checker.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Centralized budget evaluation. Checks per-agent, per-spawner,
+  # and global budget limits on each cost report.
+  #
+  # Returns an array of violations, each a Hash:
+  #   { level: :agent/:spawner/:global, budget:, spent:, action: :warning/:exceeded }
+  class BudgetChecker
+    def initialize(store:, config: Superkick.config)
+      @store = store
+      @config = config
+    end
+
+    # Check all budget levels for an agent.
+    # @return [Array<Hash>] violations (empty means all budgets ok)
+    def check(agent)
+      violations = []
+      violations.concat(check_agent_budget(agent))
+      violations.concat(check_spawner_budget(agent))
+      violations.concat(check_global_budget)
+      violations
+    end
+
+    private
+
+    def check_agent_budget(agent)
+      per_agent = per_agent_budget_config(agent)
+      return [] unless per_agent
+
+      max = per_agent[:max_cost_usd]
+      return [] unless max
+
+      spent = agent.cost.to_h[:total_cost_usd]
+      warn_pct = per_agent[:warning_threshold_percentage] || 80
+
+      if spent >= max
+        [{level: :agent, budget: max, spent:, action: :exceeded}]
+      elsif spent >= (max * warn_pct / 100.0)
+        [{level: :agent, budget: max, spent:, action: :warning}]
+      else
+        []
+      end
+    end
+
+    def check_spawner_budget(agent)
+      return [] unless agent.spawn_info
+
+      spawner_name = agent.spawn_info[:spawner_name]&.to_sym
+      config = @config.spawners[spawner_name]
+      return [] unless config
+
+      max = config.dig(:budget, :max_cost_usd)
+      return [] unless max
+
+      window = (config.dig(:budget, :window_hours) || 24) * 3600
+      cutoff = Time.now - window
+
+      total = 0.0
+      @store.each do |a|
+        next unless a.spawn_info&.dig(:spawner_name)&.to_sym == spawner_name
+        spawned_at = a.spawn_info[:spawned_at]
+        next unless spawned_at
+        begin
+          next if Time.iso8601(spawned_at) < cutoff
+        rescue ArgumentError
+          next
+        end
+        total += a.cost.to_h[:total_cost_usd]
+      end
+
+      warn_pct = config.dig(:budget, :warning_threshold_percentage) || 80
+
+      if total >= max
+        [{level: :spawner, budget: max, spent: total, action: :exceeded}]
+      elsif total >= (max * warn_pct / 100.0)
+        [{level: :spawner, budget: max, spent: total, action: :warning}]
+      else
+        []
+      end
+    end
+
+    def check_global_budget
+      max = @config.budget[:max_cost_usd]
+      return [] unless max
+
+      window = (@config.budget[:window_hours] || 24) * 3600
+      cutoff = Time.now - window
+
+      total = 0.0
+      @store.each do |a|
+        next unless a.spawn_info
+        spawned_at = a.spawn_info[:spawned_at]
+        next unless spawned_at
+        begin
+          next if Time.iso8601(spawned_at) < cutoff
+        rescue ArgumentError
+          next
+        end
+        total += a.cost.to_h[:total_cost_usd]
+      end
+
+      warn_pct = @config.budget[:warning_threshold_percentage] || 80
+
+      if total >= max
+        [{level: :global, budget: max, spent: total, action: :exceeded}]
+      elsif total >= (max * warn_pct / 100.0)
+        [{level: :global, budget: max, spent: total, action: :warning}]
+      else
+        []
+      end
+    end
+
+    def per_agent_budget_config(agent)
+      return nil unless agent.spawn_info
+      spawner_name = agent.spawn_info[:spawner_name]&.to_sym
+      @config.spawners.dig(spawner_name, :budget, :per_agent)
+    end
+  end
+end

data/lib/superkick/buffer/client.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Superkick
+  module Buffer
+    @clients = {}
+    extend ClientRegistry
+
+    # Buffer client for communicating with agents' buffer servers.
+    #
+    # The default implementation communicates over a Unix socket. In hosted
+    # mode, a subclass (Hosted::Buffer::Client) routes commands through
+    # WebSocket relays.
+    #
+    # All server-side components (Injector, SpawnInjector, CostPoller,
+    # Supervisor) use Buffer.client_from to construct the right implementation
+    # for the configured server type.
+    class Client
+      # Shared exception that callers rescue regardless of server type.
+      class AgentUnreachable < StandardError; end
+
+      def self.from(store:, **_kwargs)
+        new(store:)
+      end
+
+      def initialize(store:)
+        @store = store
+      end
+
+      # Send a command to the agent's buffer server and return the parsed response.
+      # @param agent_id [String]
+      # @param command [String] buffer command name
+      # @param params [Hash] extra key/value params merged into the request
+      # @return [Hash] parsed response from the buffer server
+      def request(agent_id, command, **params)
+        socket_path = resolve_socket_path(agent_id)
+        connection = Superkick::Connection.open(socket_path)
+        begin
+          connection.send_message({command:}.merge(params))
+          response = connection.receive_message
+          raise AgentUnreachable, "Buffer server closed connection" unless response
+          response
+        ensure
+          connection.close
+        end
+      rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::ECONNRESET
+        raise AgentUnreachable, "Buffer socket not found for agent #{agent_id}"
+      end
+
+      # Fire-and-forget: send a command, log and swallow AgentUnreachable.
+      def send_command(agent_id, command, **params)
+        request(agent_id, command, **params)
+      rescue AgentUnreachable => e
+        Superkick.logger.debug(log_tag) { "Send failed for #{agent_id}: #{e.message}" }
+        nil
+      end
+
+      # Check if the agent's buffer socket is reachable.
+      def reachable?(agent_id)
+        agent = @store.get(agent_id)
+        return false unless agent&.buffer_socket_path
+
+        socket_path = agent.buffer_socket_path
+        File.exist?(socket_path)
+      end
+
+      # Probe the agent's buffer endpoint to verify it's alive.
+      def probe(agent_id)
+        response = request(agent_id, "ping")
+        response&.fetch(:ok, false) == true
+      rescue AgentUnreachable, SystemCallError, IOError, JSON::ParserError
+        false
+      end
+
+      private
+
+      def log_tag
+        "buffer:client"
+      end
+
+      def resolve_socket_path(agent_id)
+        agent = @store.get(agent_id)
+        socket_path = agent&.buffer_socket_path
+        raise AgentUnreachable, "No buffer socket for agent #{agent_id}" unless socket_path && File.exist?(socket_path)
+
+        socket_path
+      end
+    end
+  end
+end