superkick 0.1.0

data/lib/superkick/goals/command.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Goals
+    # Goal that runs a shell command periodically.  Exit code determines
+    # the returned status:
+    #
+    #   exit 0 → :completed    (terminal — task succeeded)
+    #   exit 1 → :pending      (keep checking)
+    #   exit 2 → :in_progress  (actively working, stored for observability)
+    #   exit 3 → :errored      (recoverable issue, stored for observability)
+    #   exit 4 → :failed       (irrecoverable — task cannot be completed)
+    #   exit 5-125 → :errored  (reserved for future use, treated as recoverable)
+    #   exit 126+ → :failed    (shell/OS errors: 126=not executable, 127=not found, 128+=signal)
+    #
+    # The command is re-run each check cycle until a terminal status is
+    # reached or the agent is terminated.
+    #
+    # Configuration:
+    #   goal:
+    #     type: command
+    #     run: "gh pr list --head $BRANCH --json number -q '.[0].number'"
+    #     timeout: 30     # seconds, default 30
+    #
+    # Environment variables passed to the command:
+    #   SUPERKICK_AGENT_ID          — the agent ID
+    #   SUPERKICK_GOAL_COMPLETED    — exit code for :completed (0)
+    #   SUPERKICK_GOAL_PENDING      — exit code for :pending (1)
+    #   SUPERKICK_GOAL_IN_PROGRESS  — exit code for :in_progress (2)
+    #   SUPERKICK_GOAL_ERRORED      — exit code for :errored (3)
+    #   SUPERKICK_GOAL_FAILED       — exit code for :failed (4)
+    #
+    # Use the env vars instead of literal exit codes so scripts don't
+    # depend on the numeric mapping:
+    #
+    #   exit $SUPERKICK_GOAL_IN_PROGRESS
+    #
+    class Command < Goal
+      DEFAULT_TIMEOUT = 30
+
+      # Canonical exit codes — the env vars are the stable API.
+      EXIT_COMPLETED = 0
+      EXIT_PENDING = 1
+      EXIT_IN_PROGRESS = 2
+      EXIT_ERRORED = 3
+      EXIT_FAILED = 4
+
+      GOAL_ENV = {
+        "SUPERKICK_GOAL_COMPLETED" => EXIT_COMPLETED.to_s,
+        "SUPERKICK_GOAL_PENDING" => EXIT_PENDING.to_s,
+        "SUPERKICK_GOAL_IN_PROGRESS" => EXIT_IN_PROGRESS.to_s,
+        "SUPERKICK_GOAL_ERRORED" => EXIT_ERRORED.to_s,
+        "SUPERKICK_GOAL_FAILED" => EXIT_FAILED.to_s
+      }.freeze
+
+      def self.type = :command
+
+      def self.description
+        "Runs a shell command periodically. Exit code 0 means completed, " \
+          "1 means pending (keep checking), 4 means failed. " \
+          "Environment variables SUPERKICK_GOAL_* provide the exit codes."
+      end
+
+      def self.required_config = %i[run]
+
+      def check
+        cmd = config[:run]
+        raise ArgumentError, "Goal::Command requires a :run config key" unless cmd
+
+        timeout = config[:timeout] || DEFAULT_TIMEOUT
+        env = GOAL_ENV.merge("SUPERKICK_AGENT_ID" => agent_id)
+
+        result = ProcessRunner.run(cmd, timeout:, env:, chdir: Dir.pwd)
+
+        if result[:timed_out]
+          Superkick.logger.warn("goal:command") { "Command timed out for #{agent_id}" }
+          :pending
+        else
+          exit_code_to_status(result[:status].exitstatus)
+        end
+      rescue => e
+        Superkick.logger.error("goal:command") { "Check failed for #{agent_id}: #{e.message}" }
+        :pending
+      end
+
+      private
+
+      def exit_code_to_status(code)
+        case code
+        when EXIT_COMPLETED then :completed
+        when EXIT_PENDING then :pending
+        when EXIT_IN_PROGRESS then :in_progress
+        when EXIT_ERRORED then :errored
+        when EXIT_FAILED then :failed
+        when 5..125 then :errored
+        else :failed # 126+ (shell/OS errors)
+        end
+      end
+    end
+  end
+end
+
+Superkick::Goal.register(Superkick::Goals::Command)

data/lib/superkick/history_buffer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Thread-safe ring buffer that stores the most recent N bytes of PTY output.
+  # When a new attach client connects, the entire buffer is replayed so they
+  # see context rather than a blank screen.
+  class HistoryBuffer
+    DEFAULT_CAPACITY = 100 * 1024 # 100 KB
+
+    def initialize(capacity: DEFAULT_CAPACITY)
+      @capacity = capacity
+      @mutex = Mutex.new
+      @buffer = "".b
+    end
+
+    # Append PTY output data.  Trims from the front if capacity is exceeded.
+    def write(data)
+      @mutex.synchronize do
+        @buffer << data.b
+        if @buffer.bytesize > @capacity
+          excess = @buffer.bytesize - @capacity
+          @buffer = @buffer.byteslice(excess..)
+        end
+      end
+    end
+
+    # Return a copy of the current buffer contents.
+    # @return [String] binary string of recent PTY output
+    def snapshot
+      @mutex.synchronize { @buffer.dup }
+    end
+
+    # Current size in bytes.
+    def size
+      @mutex.synchronize { @buffer.bytesize }
+    end
+  end
+end

data/lib/superkick/hosted/attach/bridge.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Attach
+      # Agent-side bridge that connects the local Attach::Server to the hosted
+      # server over a persistent WebSocket. Unlike the Buffer bridge, this
+      # channel uses binary frames for streaming PTY output.
+      #
+      # Subclass of Superkick::Hosted::Bridge — inherits the WebSocket lifecycle,
+      # auth handshake, read loop, and reconnection with exponential backoff.
+      #
+      # Output forwarding: registers a broadcast callback on Attach::Server so
+      # that PTY output is forwarded to the relay as OUTPUT frames.
+      #
+      # Remote input: binary WebSocket messages from the relay (INPUT/RESIZE
+      # frames from remote users) are dispatched to the Attach::Server.
+      class Bridge < Superkick::Hosted::Bridge
+        def initialize(agent_id:, server_url:, api_key:, attach_server:)
+          super(agent_id:, server_url:, api_key:)
+          @attach_server = attach_server
+        end
+
+        private
+
+        def websocket_path
+          "/api/v1/agents/#{@agent_id}/attach/agent/ws"
+        end
+
+        def channel_name
+          "attach:ws"
+        end
+
+        def on_authenticated
+          @attach_server.on_broadcast do |data|
+            frame = Superkick::Attach::Protocol.build_frame(Superkick::Attach::Protocol::OUTPUT, data)
+            send_binary(frame)
+          end
+        end
+
+        def handle_server_message(message)
+          # Text messages from server (besides auth/ping) are not expected
+          # for the attach channel — all data is binary
+        end
+
+        def handle_binary_message(data)
+          @attach_server.handle_remote_input(data)
+        end
+      end
+    end
+  end
+end

data/lib/superkick/hosted/attach/client.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Attach
+      # WebSocket transport for attach sessions.
+      # Connects to the hosted server, authenticates, then streams
+      # Attach::Protocol binary frames over WebSocket messages.
+      class Client < Superkick::Attach::Client
+        CONNECT_TIMEOUT = 10 # seconds
+
+        def self.from(agent_id:, config: Superkick.config, mode: :ro, escape_key: "\x01", force: false)
+          server_config = config.server
+          new(
+            server_url: server_config[:url],
+            api_key: server_config[:api_key],
+            agent_id:,
+            mode:, escape_key:, force:
+          )
+        end
+
+        def initialize(server_url:, api_key:, agent_id:, **session_args)
+          super(**session_args)
+          @server_url = server_url.chomp("/")
+          @api_key = api_key
+          @agent_id = agent_id
+          @frame_queue = Queue.new
+          @reader_thread = nil
+
+          connect!
+        end
+
+        def read_frame
+          data = @frame_queue.pop
+          return nil if data == :eof
+
+          # Parse Protocol frame from binary data
+          return nil if data.bytesize < 5
+
+          type = data.getbyte(0)
+          len = data[1, 4].unpack1("N")
+          payload = data[5, len]
+          return nil unless payload && payload.bytesize == len
+
+          [type, payload]
+        end
+
+        def write_frame(type, data)
+          frame = Superkick::Attach::Protocol.build_frame(type, data)
+          @driver.binary(frame)
+          flush
+        end
+
+        def write_json_frame(type, hash)
+          write_frame(type, JSON.generate(hash))
+        end
+
+        def close
+          @driver&.close
+          @socket&.close
+          @reader_thread&.kill
+        rescue IOError, Errno::EBADF
+          nil
+        end
+
+        private
+
+        def connect!
+          uri = URI.parse("#{@server_url}/api/v1/agents/#{@agent_id}/attach/ws")
+          @socket = open_socket(uri)
+          @driver = create_driver(uri)
+
+          setup_handlers
+          @driver.start
+          flush
+
+          # Send auth
+          auth = {type: "auth", token: @api_key}
+          @driver.text(JSON.generate(auth))
+          flush
+
+          # Start background reader
+          @reader_thread = Thread.new { reader_loop }
+
+          # Wait for welcome
+          wait_for_welcome
+        end
+
+        def open_socket(uri)
+          default_port = (uri.scheme == "wss") ? 443 : 80
+          port = uri.port || default_port
+          tcp = TCPSocket.new(uri.host, port)
+
+          if uri.scheme == "wss"
+            require "openssl"
+            ctx = OpenSSL::SSL::SSLContext.new
+            ctx.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+            ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
+            ssl.hostname = uri.host
+            ssl.connect
+            ssl
+          else
+            tcp
+          end
+        end
+
+        def create_driver(uri)
+          require "websocket/driver"
+
+          wrapper = SocketWrapper.new(@socket, uri.to_s)
+          driver = WebSocket::Driver.client(wrapper)
+          driver.set_header("Authorization", "Bearer #{@api_key}")
+          driver
+        end
+
+        def setup_handlers
+          @welcome_received = false
+
+          @driver.on :message do |event|
+            handle_text_message(event.data)
+          end
+
+          @driver.on :binary do |event|
+            @frame_queue << event.data.b
+          end
+
+          @driver.on :close do
+            @frame_queue << :eof
+          end
+
+          @driver.on :error do |event|
+            Superkick.logger.error("attach:client:hosted") { "WebSocket error: #{event.message}" }
+            @frame_queue << :eof
+          end
+        end
+
+        def handle_text_message(data)
+          message = JSON.parse(data, symbolize_names: true)
+
+          case message[:type]
+          when "welcome"
+            @welcome_received = true
+          when "error"
+            Superkick.logger.error("attach:client:hosted") { "Server error: #{message[:message]}" }
+            @frame_queue << :eof
+          when "ping"
+            @driver.text(JSON.generate({type: "pong"}))
+            flush
+          end
+        rescue JSON::ParserError
+          nil
+        end
+
+        def reader_loop
+          loop do
+            data = begin
+              @socket.read_nonblock(4096)
+            rescue IO::WaitReadable
+              IO.select([@socket], nil, nil, 30)
+              retry
+            rescue IOError, Errno::ECONNRESET, Errno::EBADF
+              break
+            end
+
+            break unless data && !data.empty?
+
+            @driver.parse(data)
+            flush
+          end
+
+          @frame_queue << :eof
+        end
+
+        def wait_for_welcome
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + CONNECT_TIMEOUT
+          until @welcome_received
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise Errno::ETIMEDOUT, "WebSocket auth timeout" if remaining <= 0
+            sleep 0.05
+          end
+        end
+
+        def flush
+          # websocket-driver writes directly via SocketWrapper
+        end
+
+        # Minimal wrapper for websocket-driver.
+        class SocketWrapper
+          attr_reader :url
+
+          def initialize(socket, url)
+            @socket = socket
+            @url = url
+          end
+
+          def write(data)
+            @socket.write(data)
+            @socket.flush
+          rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+            nil
+          end
+        end
+      end
+    end
+  end
+end
+
+Superkick::Attach.register_client(:hosted, Superkick::Hosted::Attach::Client)