superkick 0.1.0

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Buffer
+      # WebSocket client for sending buffer commands to remote agents.
+      #
+      # In hosted mode, agents maintain persistent WebSocket connections to the
+      # server. The server holds a Relay per agent. This client sends
+      # commands through those relays.
+      #
+      # This is a server-side component — it routes commands to agents via
+      # their WebSocket connections, not over Unix sockets.
+      class Client < Superkick::Buffer::Client
+        def self.from(relay_store:, **_kwargs)
+          new(relay_store:)
+        end
+
+        def initialize(relay_store:)
+          @relay_store = relay_store
+        end
+
+        # Send a command to the agent via its WebSocket relay and return the response.
+        def request(agent_id, command, **params)
+          relay = resolve_relay(agent_id)
+          relay.request(command, **params)
+        end
+
+        # Fire-and-forget: send a command through the relay without waiting
+        # for a response. Overrides the base class to use the relay's
+        # fire-and-forget method instead of the request/response path.
+        def send_command(agent_id, command, **params)
+          relay = resolve_relay(agent_id)
+          relay.send_command(command, **params)
+        rescue AgentUnreachable => e
+          Superkick.logger.debug(log_tag) { "Send failed for #{agent_id}: #{e.message}" }
+          nil
+        end
+
+        # Check if the agent has an active WebSocket relay connection.
+        def reachable?(agent_id)
+          relay = @relay_store&.get(agent_id)
+          relay&.connected? || false
+        end
+
+        private
+
+        def log_tag
+          "buffer:hosted"
+        end
+
+        def resolve_relay(agent_id)
+          relay = @relay_store&.get(agent_id)
+          raise AgentUnreachable, "No relay for agent #{agent_id}" unless relay&.connected?
+
+          relay
+        end
+      end
+    end
+  end
+end
+
+Superkick::Buffer.register_client(:hosted, Superkick::Hosted::Buffer::Client)

data/lib/superkick/hosted/buffer/relay.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Superkick
+  module Hosted
+    module Buffer
+      # Server-side relay that bridges the Injector/Supervisor to a remote agent
+      # over a persistent raw WebSocket connection (not ActionCable).
+      #
+      # In hosted mode, the agent opens a raw WebSocket to the server and
+      # authenticates via the shared auth protocol (see Hosted::Bridge). The
+      # server creates a Relay for each connected agent. Server-side components
+      # send buffer commands through the Relay, which forwards them as JSON
+      # text frames and (for request/response commands) waits for the reply.
+      #
+      # The Relay is transport-agnostic — it sends/receives JSON hashes through
+      # a websocket object that responds to #send(String).
+      class Relay
+        RESPONSE_TIMEOUT = 5 # seconds
+
+        def initialize(agent_id:)
+          @agent_id = agent_id
+          @websocket = nil
+          @mutex = Mutex.new
+          @pending = {}
+          @pending_mutex = Mutex.new
+        end
+
+        # Called by the WebSocket handler when an agent connects.
+        def attach(websocket)
+          @mutex.synchronize { @websocket = websocket }
+          Superkick.logger.info("buffer:relay") { "Agent #{@agent_id} attached" }
+        end
+
+        # Called when the WebSocket connection closes.
+        def detach
+          @mutex.synchronize { @websocket = nil }
+
+          # Wake up any pending request/response waiters
+          @pending_mutex.synchronize do
+            @pending.each_value { it[:condition]&.broadcast }
+          end
+
+          Superkick.logger.info("buffer:relay") { "Agent #{@agent_id} detached" }
+        end
+
+        def connected?
+          @mutex.synchronize { !@websocket.nil? }
+        end
+
+        # Send a command and wait for the response (request/response pattern).
+        def request(command, **params)
+          ws = @mutex.synchronize { @websocket }
+          raise Superkick::Buffer::Client::AgentUnreachable, "Agent #{@agent_id} not connected" unless ws
+
+          request_id = SecureRandom.uuid
+          message = {command:, request_id:, **params}
+
+          # Register a pending response slot
+          entry = {response: nil, condition: ConditionVariable.new, mutex: Mutex.new}
+          @pending_mutex.synchronize { @pending[request_id] = entry }
+
+          begin
+            ws.send(JSON.generate(message))
+
+            # Wait for the response with timeout
+            entry[:mutex].synchronize do
+              deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + RESPONSE_TIMEOUT
+              while entry[:response].nil?
+                remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                break if remaining <= 0
+                entry[:condition].wait(entry[:mutex], remaining)
+              end
+            end
+
+            entry[:response] || raise(Superkick::Buffer::Client::AgentUnreachable, "Response timeout for #{@agent_id}")
+          ensure
+            @pending_mutex.synchronize { @pending.delete(request_id) }
+          end
+        end
+
+        # Fire-and-forget: send a command without waiting for a response.
+        def send_command(command, **params)
+          ws = @mutex.synchronize { @websocket }
+          raise Superkick::Buffer::Client::AgentUnreachable, "Agent #{@agent_id} not connected" unless ws
+
+          message = {command:, **params}
+          ws.send(JSON.generate(message))
+          {ok: true}
+        end
+
+        # Called when the agent sends a message back over the WebSocket.
+        # Routes responses to pending request/response waiters, and handles
+        # unsolicited messages (e.g. injection_result IPC).
+        def handle_message(message)
+          request_id = message[:request_id]
+
+          if request_id
+            entry = @pending_mutex.synchronize { @pending[request_id] }
+            if entry
+              entry[:mutex].synchronize do
+                entry[:response] = message
+                entry[:condition].broadcast
+              end
+              return
+            end
+          end
+
+          # Unsolicited message from agent (e.g. injection_result)
+          handle_agent_event(message)
+        end
+
+        private
+
+        # Handle unsolicited agent-to-server messages.
+        # In hosted mode, injection_result and report_cost are sent back over
+        # the WebSocket rather than opening separate control connections.
+        def handle_agent_event(message)
+          Superkick.logger.debug("buffer:relay") { "Agent event from #{@agent_id}: #{message[:command]}" }
+          # Future: route to control server command handlers
+        end
+      end
+    end
+  end
+end

data/lib/superkick/hosted/buffer/relay_store.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Buffer
+      # Thread-safe registry of Hosted::Buffer::Relay instances, one per connected agent.
+      # Created at server startup in hosted mode and passed to Buffer::Client.
+      class RelayStore
+        def initialize
+          @relays = {}
+          @mutex = Mutex.new
+        end
+
+        # Get or create a relay for the given agent.
+        def get_or_create(agent_id)
+          @mutex.synchronize do
+            @relays[agent_id] ||= Relay.new(agent_id:)
+          end
+        end
+
+        # Get an existing relay (nil if none).
+        def get(agent_id)
+          @mutex.synchronize { @relays[agent_id] }
+        end
+
+        # Remove a relay when the agent disconnects permanently.
+        def remove(agent_id)
+          @mutex.synchronize { @relays.delete(agent_id) }
+        end
+
+        # Iterate over all relays.
+        def each(&block)
+          @mutex.synchronize { @relays.each_value(&block) }
+        end
+
+        def size
+          @mutex.synchronize { @relays.size }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Hosted
+    module Control
+      # HTTPS client for communicating with a remote Superkick control server.
+      # Implements the same interface as Superkick::Control::Client so callers
+      # are transport-agnostic.
+      #
+      # All control commands go through POST /api/v1/control with the command
+      # name in the JSON body — no per-command HTTP routes.
+      class Client < Superkick::Control::Client
+        TIMEOUT = 10 # seconds
+
+        def self.from(config: Superkick.config, connection: nil, **_kwargs)
+          server = config.server
+          new(
+            url: server[:url],
+            api_key: server[:api_key],
+            connection:
+          )
+        end
+
+        # @param url     [String] base URL of the hosted server
+        # @param api_key [String] bearer token for authentication
+        # @param connection [Faraday::Connection, nil] optional pre-built connection (for testing)
+        def initialize(url:, api_key:, connection: nil)
+          raise ArgumentError, "url is required for hosted transport" unless url
+          raise ArgumentError, "api_key is required for hosted transport" unless api_key
+
+          @url = url.chomp("/")
+          @api_key = api_key
+          @connection = connection || build_connection
+        end
+
+        # Send a command to the hosted 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)
+          response = @connection.post("/api/v1/control", {command:, **params})
+
+          case response.status
+          when 200 then Superkick::Control::Reply.new(response.body)
+          when 401 then raise AuthenticationError, "Authentication failed — check your API key"
+          else raise ServerUnavailable, "Server returned HTTP #{response.status}"
+          end
+        rescue Faraday::ConnectionFailed => e
+          raise ServerUnavailable, "Connection failed: #{e.message}"
+        rescue Faraday::TimeoutError => e
+          raise ServerUnavailable, "Request timed out: #{e.message}"
+        end
+
+        # Returns true if the hosted server is reachable and authenticated.
+        def alive?
+          request("ping").success?
+        rescue ServerUnavailable
+          false
+        end
+
+        # Close the underlying Faraday connection.
+        def close
+          @connection.close
+        end
+
+        private
+
+        def build_connection
+          Faraday.new(url: @url) do |f|
+            f.request :authorization, "Bearer", @api_key
+            f.request :json
+            f.response :json, parser_options: {symbolize_names: true}
+            f.options.timeout = TIMEOUT
+            f.options.open_timeout = TIMEOUT
+          end
+        end
+      end
+    end
+  end
+end
+
+Superkick::Control.register_client(:hosted, Superkick::Hosted::Control::Client)

data/lib/superkick/hosted/mcp_proxy.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Superkick
+  module Hosted
+    # Transparent MCP stdio-to-HTTP proxy for hosted mode.
+    #
+    # Runs as a local stdio subprocess (same as McpServer) but instead of
+    # handling tool calls locally, forwards all JSON-RPC messages to the
+    # hosted server's Streamable HTTP MCP endpoint. Stamps the agent identity
+    # header on every request so the hosted server knows which agent is calling.
+    #
+    # The AI CLI sees a normal stdio MCP server — it has no idea it's talking
+    # to a remote endpoint. This avoids teaching every driver about remote MCP
+    # URL configuration.
+    #
+    # Protocol flow:
+    #   AI CLI → stdin (JSON-RPC) → McpProxy → POST /api/v1/mcp → Hosted Server
+    #   Hosted Server → HTTP response → McpProxy → stdout (JSON-RPC) → AI CLI
+    #
+    # Streamable HTTP responses may be:
+    #   - application/json — single JSON-RPC response (written directly to stdout)
+    #   - text/event-stream — SSE stream of JSON-RPC messages (each event written to stdout)
+    #   - 202 Accepted — notification acknowledged, no response body
+    class McpProxy
+      TIMEOUT = 30 # seconds — tool calls may take a while
+
+      def self.start
+        new.run
+      end
+
+      # @param connection [Faraday::Connection, nil] optional pre-built connection (for testing)
+      def initialize(connection: nil)
+        @agent_id = ENV["SUPERKICK_AGENT_ID"]
+        raise "SUPERKICK_AGENT_ID must be set. The MCP proxy should be started via `superkick agent`." unless @agent_id
+
+        server_config = Superkick.config.server
+        @url = server_config[:url]
+        @api_key = server_config[:api_key]
+        raise "server.url is required for hosted MCP proxy" unless @url
+        raise "server.api_key is required for hosted MCP proxy" unless @api_key
+
+        @url = @url.chomp("/")
+        @connection = connection || build_connection
+        @session_id = nil
+      end
+
+      def run
+        $stdin.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          forward(line)
+        end
+      end
+
+      private
+
+      def forward(json_body)
+        headers = {"Content-Type" => "application/json", "Accept" => "application/json, text/event-stream"}
+        headers["Mcp-Session-Id"] = @session_id if @session_id
+
+        response = @connection.post("/api/v1/mcp", json_body, headers)
+
+        # Track session ID from server
+        if response.headers["mcp-session-id"]
+          @session_id = response.headers["mcp-session-id"]
+        end
+
+        case response.status
+        when 200
+          content_type = response.headers["content-type"].to_s
+          if content_type.include?("text/event-stream")
+            write_sse_events(response.body)
+          else
+            write_line(response.body)
+          end
+        when 202
+          # Notification accepted — no response to write
+          nil
+        else
+          # Return a JSON-RPC error for the request if we can extract the id
+          write_jsonrpc_error(json_body, response)
+        end
+      rescue Faraday::ConnectionFailed => e
+        write_jsonrpc_error(json_body, nil, message: "Connection failed: #{e.message}")
+      rescue Faraday::TimeoutError => e
+        write_jsonrpc_error(json_body, nil, message: "Request timed out: #{e.message}")
+      end
+
+      # Parse SSE stream and write each "message" event as a line to stdout.
+      def write_sse_events(body)
+        event_type = nil
+        body.each_line do |line|
+          line = line.rstrip
+          if line.start_with?("event:")
+            event_type = line.sub("event:", "").strip
+          elsif line.start_with?("data:")
+            data = line.sub("data:", "").strip
+            write_line(data) if event_type == "message" && !data.empty?
+          elsif line.empty?
+            event_type = nil
+          end
+        end
+      end
+
+      def write_line(data)
+        $stdout.write(data)
+        $stdout.write("\n")
+        $stdout.flush
+      end
+
+      # Best-effort JSON-RPC error response when the hosted server fails.
+      # Only writes if the original message was a request (has an "id" field).
+      def write_jsonrpc_error(json_body, response, message: nil)
+        parsed = begin
+          JSON.parse(json_body)
+        rescue JSON::ParserError
+          nil
+        end
+        return unless parsed.is_a?(Hash) && parsed.key?("id")
+
+        error_message = message || "Hosted server returned HTTP #{response&.status}"
+        error_response = {
+          "jsonrpc" => "2.0",
+          "id" => parsed["id"],
+          "error" => {"code" => -32603, "message" => error_message}
+        }
+        write_line(JSON.generate(error_response))
+      end
+
+      def build_connection
+        Faraday.new(url: @url) do |f|
+          f.request :authorization, "Bearer", @api_key
+          f.headers["X-Superkick-Agent-Id"] = @agent_id
+          f.options.timeout = TIMEOUT
+          f.options.open_timeout = TIMEOUT
+        end
+      end
+    end
+  end
+end

data/lib/superkick/inject_handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Superkick
+  # InjectHandler — dispatches monitor events to the Injector.
+  #
+  # Implements the handler contract (handle/flush_pending) used by Monitor.
+  # The Injector sends events to the agent's InjectionQueue (fire-and-forget).
+  # Pending event management is handled agent-side by the InjectionQueue.
+  class InjectHandler
+    def initialize(injector:, agent:)
+      @injector = injector
+      @agent = agent
+    end
+
+    # Handle a single event. Returns :enqueued, :skipped, or :error.
+    def handle(event:)
+      @injector.inject(agent_id: @agent.id, event:)
+    end
+
+    # No-op — pending events are managed agent-side by the InjectionQueue.
+    def flush_pending
+    end
+  end
+end

data/lib/superkick/injection_guard.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Superkick
+  # PatternGuard matches pty output lines and signals the InputBuffer to
+  # suppress injection while the guard is active.
+  #
+  # name           — unique Symbol used as the hash key in InputBuffer#guards
+  # pattern        — Regexp matched against ANSI-stripped output
+  # reason         — human-readable explanation shown in superkick status
+  # clear_on_submit — if true, the guard is cleared when the user hits Enter/C-c
+  PatternGuard = Data.define(:name, :pattern, :reason, :clear_on_submit) do
+    def initialize(name:, pattern:, reason:, clear_on_submit: true)
+      super
+    end
+
+    # Match against text that has already been stripped of ANSI codes.
+    def match?(stripped_text)
+      pattern.match?(stripped_text)
+    end
+  end
+
+  # Factory helper so callers don't need to remember keyword names.
+  def self.pattern_guard(name, pattern, reason, clear_on_submit: true)
+    PatternGuard.new(name:, pattern:, reason:, clear_on_submit:)
+  end
+end

data/lib/superkick/injection_queue.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Agent-side injection queue with TTL, supersede, and priority semantics.
+  #
+  # The server sends injection requests (rendered prompts) to the agent via
+  # `enqueue_injection`.  The queue drains locally, checking preconditions
+  # (idle state, guards) with zero network latency before writing to the PTY.
+  #
+  # Queue semantics:
+  #   - TTL:        Stale injections are dropped silently after their TTL expires.
+  #   - Supersede:  A new injection with the same supersede_key replaces any
+  #                 existing queued entry with that key.
+  #   - Priority:   :high (spawn kickoffs, team messages), :normal (monitor
+  #                 events), :low (cost polling).  Higher priority drains first.
+  #   - Max size:   Oldest low-priority entries are dropped when the queue is full.
+  class InjectionQueue
+    Entry = Data.define(:id, :prompt, :monitor_type, :monitor_name,
+      :priority, :enqueued_at, :ttl, :supersede_key)
+
+    PRIORITIES = {high: 0, normal: 1, low: 2}.freeze
+    DEFAULT_TTL = 300        # seconds
+    DEFAULT_DRAIN_INTERVAL = 0.5  # seconds
+    MAX_SIZE = 50
+
+    attr_reader :entries
+
+    def initialize(pty_proxy:, idle_threshold:, inject_clear_delay:, control_client: nil,
+      drain_interval: DEFAULT_DRAIN_INTERVAL)
+      @pty_proxy = pty_proxy
+      @idle_threshold = idle_threshold
+      @inject_clear_delay = inject_clear_delay
+      @control_client = control_client
+      @drain_interval = drain_interval
+      @entries = []
+      @mutex = Mutex.new
+      @drain_thread = nil
+    end
+
+    # Enqueue an injection request.  Supersedes existing entries with matching key.
+    # Returns the Entry or nil if rejected.
+    def enqueue(id:, prompt:, monitor_type: nil, monitor_name: nil,
+      priority: :normal, ttl: DEFAULT_TTL, supersede_key: nil)
+      key = supersede_key || monitor_name.to_s
+      pri = PRIORITIES.fetch(priority.to_sym, PRIORITIES[:normal])
+
+      entry = Entry.new(
+        id:, prompt:, monitor_type:, monitor_name:,
+        priority: pri,
+        enqueued_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+        ttl:, supersede_key: key
+      )
+
+      @mutex.synchronize do
+        # Supersede: remove existing entries with the same key
+        superseded = @entries.select { it.supersede_key == key }
+        @entries.reject! { it.supersede_key == key }
+        superseded.each { report_result(it.id, :superseded) }
+
+        @entries << entry
+        drop_oldest_if_full
+      end
+
+      entry
+    end
+
+    def start
+      @drain_thread = Thread.new { drain_loop }
+      self
+    end
+
+    def stop
+      @drain_thread&.kill
+      @drain_thread&.join(2)
+      @drain_thread = nil
+    end
+
+    def size
+      @mutex.synchronize { @entries.size }
+    end
+
+    private
+
+    def drain_loop
+      loop do
+        entry = next_ready_entry
+        if entry
+          attempt_injection(entry)
+        else
+          sleep(@drain_interval)
+        end
+      end
+    rescue => e
+      Superkick.logger.error("injection_queue") { "Drain loop error: #{e.message}" }
+      retry
+    end
+
+    def next_ready_entry
+      @mutex.synchronize do
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # Remove expired entries
+        expired, @entries = @entries.partition { (now - it.enqueued_at) > it.ttl }
+        expired.each { report_result(it.id, :expired) }
+
+        # Sort by priority (lower number = higher priority), then by age (oldest first)
+        @entries.sort_by! { [it.priority, it.enqueued_at] }
+        @entries.first
+      end
+    end
+
+    def attempt_injection(entry)
+      # All checks are LOCAL — no network calls
+      idle = @pty_proxy.idle_state
+      seconds_idle = idle[:seconds_idle]
+      at_prompt = idle[:at_prompt]
+
+      threshold = @idle_threshold
+
+      unless seconds_idle && seconds_idle >= threshold
+        sleep(@drain_interval)
+        return
+      end
+
+      # Conservative: if not at prompt, require 2× threshold
+      unless at_prompt || seconds_idle >= threshold * 2
+        sleep(@drain_interval)
+        return
+      end
+
+      unless @pty_proxy.guards_clear?
+        sleep(@drain_interval)
+        return
+      end
+
+      # Remove from queue
+      @mutex.synchronize { @entries.delete(entry) }
+
+      # Execute injection sequence (same as the old Injector)
+      partial_input = @pty_proxy.partial_input
+      delay = @inject_clear_delay
+
+      @pty_proxy.enqueue_inject("\x03")
+      sleep(delay)
+      @pty_proxy.enqueue_inject("\r")
+      sleep(delay)
+      @pty_proxy.enqueue_inject("#{entry.prompt}\r")
+      sleep(delay)
+      @pty_proxy.enqueue_inject(partial_input) unless partial_input.empty?
+
+      Superkick.logger.info("injection_queue") { "Injected #{entry.monitor_type}:#{entry.id}" }
+      report_result(entry.id, :injected)
+    end
+
+    def report_result(id, status)
+      return unless @control_client
+
+      Thread.new do
+        @control_client.request("injection_result", id:, status: status.to_s, agent_id: @pty_proxy.agent_id)
+      rescue => e
+        Superkick.logger.debug("injection_queue") { "Result report failed: #{e.message}" }
+      end
+    end
+
+    def drop_oldest_if_full
+      return if @entries.size <= MAX_SIZE
+
+      # Sort so lowest-priority (highest number), oldest entries come first
+      @entries.sort_by! { [-it.priority, it.enqueued_at] }
+      dropped = @entries.shift(@entries.size - MAX_SIZE)
+      dropped.each { report_result(it.id, :dropped) }
+
+      # Re-sort for drain order
+      @entries.sort_by! { [it.priority, it.enqueued_at] }
+    end
+  end
+end