pinecall 0.0.1

data/lib/pinecall/call_world.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "call_world/room"
+require_relative "call_world/answers"
+
+module Pinecall
+  # The call as an agent sees it: room, turns, and the commands it can send.
+  #
+  # State is reduced from received entries; each verb is one wire command. No LiveKit access by
+  # design: a missing capability should become a new command of the wire.
+  class CallWorld
+    attr_reader :id, :contact, :from, :channel, :medium, :room, :turns, :today, :claimed
+
+    # `send` puts one command on the wire for this call; `searching` asks the gateway to search for
+    # it. Both are supplied by the bridge. `today` is the day the call opened, YYYY-MM-DD. `medium` is
+    # spoken (`voice`) or written (`text`); a gateway that does not say gets it from the channel.
+    def initialize(id:, contact: nil, from: nil, channel: nil, medium: nil, today: Time.now.strftime("%Y-%m-%d"),
+                   claimed: nil, searching: nil, &send)
+      @id = id
+      @contact = contact
+      @from = from
+      @channel = channel
+      @medium = (medium || (channel.to_s == "whatsapp" ? "text" : "voice")).to_s
+      @today = today
+      @claimed = claimed
+      @searching = searching
+      @send = send
+      @room = { participants: [], caller: nil }
+      @turns = []
+      @waiting = Waiting.new
+      @cause = nil
+      @events = 0
+    end
+
+    # The external event being handled, if any; logged as the cause of state changes.
+    attr_accessor :cause
+
+    # Next per-call event sequence number (not the wire's seq).
+    def numbered = @events += 1
+
+    # ── commands ─────────────────────────────────────────────────────────────
+
+    # Speak `text` verbatim now. Returns true once the turn arrives, false after `LANDS_WITHIN_S`.
+    def say(text, **options)
+      @waiting.wait(:spoken, LANDS_WITHIN_S, false) { @send.call("agent.say", { text: }.merge(options)) }
+    end
+
+    # Make the model speak now, guided by instructions the caller does not hear.
+    def reply(instructions, **options)
+      @waiting.wait(:spoken, LANDS_WITHIN_S, false) { @send.call("agent.reply", { instructions: }.merge(options)) }
+    end
+
+    # Search the knowledge bases attached to this agent; the gateway runs it and logs the results.
+    # `k` defaults to each base's own setting.
+    def search(query, k: nil)
+      raise Error, NO_GATEWAY_TO_SEARCH if @searching.nil?
+
+      @searching.call(query, k).map { |chunk| Found.new(path: chunk[:path], heading: chunk[:heading], text: chunk[:text]) }
+    end
+
+    # Transfer the caller to a number: sent on (cold) on a phone call, dialled into the call (warm)
+    # in a browser; `mode:` forces one. `ok: false` means the caller is still with the agent.
+    def transfer(to, mode: nil)
+      wanted = mode.nil? ? { to: } : { to:, mode: mode.to_s }
+      lapsed = Transferred.new(to:, mode: nil, ok: false, error: NO_ANSWER)
+      @waiting.wait(:transfers, TRANSFER_WITHIN_S, lapsed) { @send.call("call.transfer", wanted) }
+    end
+
+    # Ask for a supervisor; the caller waits until someone takes the line or `wait_s` passes.
+    # `reason` is shown to the supervisor. The calling tool runs the whole time.
+    def attention(reason, wait_s:)
+      lapsed = Attended.new(ok: false, by: nil, error: NO_ANSWER)
+      @waiting.wait(:asks, wait_s + A_MOMENT_S, lapsed) { @send.call("call.attention", { reason:, wait_s: }) }
+    end
+
+    # Put the caller on hold: they hear hold music and the agent neither speaks nor listens.
+    def hold = @send.call("call.hold", {})
+
+    # Take the caller off hold.
+    def unhold = @send.call("call.unhold", {})
+
+    # Send DTMF tones: `0-9`, `*`, `#`, and `,` for a pause.
+    def dtmf(digits) = @send.call("call.dtmf", { digits: })
+
+    # Bind this call to the four-digit code shown on the caller's page; `claimed` is set when the
+    # log says it took. A code that is not four digits never reaches the wire.
+    def claim(code) = @send.call("call.claim", { code: })
+
+    # Record a callback request in the call's log for the backend to dial. `at:` is the wire's `when`.
+    def callback(number, at: nil, note: nil)
+      @send.call("call.callback", { number:, when: at, note: }.compact)
+    end
+
+    # Send a payload to browsers in the room. The log records its size, not its content.
+    def send_to(topic, data, to: nil)
+      payload = { topic:, data: }
+      payload[:to] = Array(to) unless to.nil?
+      @send.call("room.send", payload)
+    end
+
+    # A participant handle by identity.
+    def participant(identity) = Seat.new(identity, @send)
+
+    # Invite a second SIP leg or a person.
+    def invite(to, kind: nil)
+      wanted = { to: }
+      wanted[:kind] = kind.to_s unless kind.nil?
+      @send.call("room.invite", wanted)
+    end
+
+    # Append an application entry to the call's log.
+    def log(name, data = {})
+      @send.call("call.log", { name: name.to_s, data: data.is_a?(Hash) ? data : { value: data } })
+    end
+
+    # The caller asked never to be called again: their number joins the org's do-not-call list, and no
+    # call of the org reaches it until a consent is recorded. Tell them it is done.
+    def opt_out(note = nil)
+      @send.call("call.opt_out", note.nil? ? {} : { note: })
+    end
+
+    # End the call; `call.ended` follows with reason `agent_hung_up`.
+    def hangup(reason = nil)
+      @send.call("call.hangup", reason.nil? ? {} : { reason: })
+    end
+
+    # ── entries ──────────────────────────────────────────────────────────────
+
+    # Apply one log entry to the room, the turns and the verbs waiting on it.
+    def take(type, data, at)
+      case type
+      when "participant.joined" then joined(data, at)
+      when "participant.left" then @room[:participants].reject! { |one| one.identity == data[:identity] }
+      when "participant.speaking" then speaking(data)
+      when "turn.user" then remember("user", data, at)
+      when "turn.agent" then remember("agent", data, at).tap { @waiting.settle(:spoken, true) }
+      when "call.claimed" then @claimed = data[:code].to_s
+      when "call.transferred" then @waiting.settle(:transfers, transferred(data))
+      when "attention.answered" then @waiting.settle(:asks, Attended.new(ok: data[:ok] == true, by: data[:by], error: data[:error]))
+      when "call.ended" then @waiting.end_all
+      end
+    end
+
+    def participants = @room[:participants].dup
+
+    # The caller's participant, or nil.
+    def caller_seat = @room[:participants].find { |one| one.kind == "caller" }
+
+    def last_turn = @turns.last
+
+    private
+
+    def joined(data, at)
+      @room[:participants] << Participant.new(
+        identity: data[:identity], kind: data[:kind], name: data[:name], joined_at: at, speaking: false
+      )
+    end
+
+    def speaking(data)
+      who = @room[:participants].find { |one| one.identity == data[:identity] }
+      who.speaking = data[:speaking] unless who.nil?
+    end
+
+    def remember(who, data, at)
+      turn = Turn.new(who:, text: data[:text], speech_id: data[:speech_id],
+                      interrupted: data[:interrupted] || false, at:)
+      @turns << turn
+      turn
+    end
+
+    def transferred(data)
+      Transferred.new(to: data[:to].to_s, mode: data[:mode], ok: data[:ok] == true, error: data[:error])
+    end
+  end
+end

data/lib/pinecall/client/agent.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # The socket-level handle for one agent slug: its declaration, tool runners and listeners.
+    # (`Pinecall::Agent` is the class a developer writes; `Bridge` connects the two.)
+    #
+    # The gateway's registry is in memory, so the declaration is re-sent on every reconnect.
+    # Several sockets may hold one slug; unclaimed calls go to the newest that `takes_unclaimed`,
+    # so a rolling deploy serves immediately and a console never gets calls it did not open.
+    class Agent
+      ANSWERS_WITHIN_S = 10
+
+      NO_DEV_HANDLER = "this process answers no dev verbs: it is not a `pinecall start` in the agent's directory"
+
+      attr_reader :slug, :calls, :config, :app
+
+      def initialize(slug, options, client)
+        @slug = slug
+        @client = client
+        @routes = options[:routes] || []
+        @takes_unclaimed = options.fetch(:takes_unclaimed, true)
+        @tools = {}
+        @waiting = []
+        @config = options.reject { |key, _| %i[routes tools takes_unclaimed].include?(key) }
+        @app = nil
+        @running = []
+        @dev = nil
+        @lock = Mutex.new
+        declare(options[:tools] || [])
+        @calls = CallBook.new(self)
+        @listeners = Listeners.new { |error| on_error(error) }
+      end
+
+      # Listen for one event type across this agent's calls.
+      def on(type, &listener) = @listeners.on(type, &listener)
+
+      # Listen for every event of this agent.
+      def on_any(&listener) = @listeners.on_any(&listener)
+
+      # Answer the console's `dev.request` asks: the block takes the verb and its data and returns the
+      # answer, or raises `DevRefused` to refuse with a status. Without one every ask is a 501.
+      def on_dev(&handler)
+        @dev = handler
+      end
+
+      # Replace the tools; sent with the next `configure`.
+      #
+      # A tool is `{ **spec, run: ->(arguments, call) { … } }`.
+      def declare(tools)
+        @tools = tools.to_h { |tool| [tool[:name].to_s, tool] }
+        @config = @config.merge(tools: tools.map { |tool| tool.reject { |key, _| key == :run } })
+      end
+
+      # Update the agent config. Only the given fields change; live calls keep their session.
+      def configure(changes = {})
+        @config = @config.merge(changes)
+        ask("agent.configure", lands_as: "agent.configured", data: { config: @config })
+      end
+
+      # Register the slug and send the config. Runs on every reconnect.
+      def open
+        registered = ask("agent.register", lands_as: "agent.registered", data: {
+                           routes: @routes, sdk: @client.sdk, host: Socket.gethostname,
+                           takes_unclaimed: @takes_unclaimed
+                         })
+        # Each connection gets a new app id.
+        @app = registered[:app]
+        configure
+        self
+      end
+
+      # ── called by the client ───────────────────────────────────────────────
+
+      # Apply an entry to its call and notify listeners.
+      def take(entry)
+        event = Wire.event_of(entry)
+        call = entry.call.nil? ? nil : @calls.of(entry.call, entry.ts)
+        settle(event)
+        call&.take(event)
+        @listeners.emit(event, call)
+        @client.seen(event, call)
+        return answer_the_console(event.data) if event.type == "dev.request"
+        return if call.nil?
+
+        run_tool(event, call) if event.type == "tool.call"
+        @calls.forget(call)
+      end
+
+      def command(type, call, data)
+        @client.send_command(type:, agent: @slug, call:, data:, id: "#{@slug}:#{type}")
+      end
+
+      def on_error(error) = @client.on_error(error)
+
+      # Agent-scoped heartbeat; answered with `pong`.
+      def ping = command("ping", nil, {})
+
+      # Stop taking new calls and hand the live ones to another holder, or park them for the next.
+      # Running tools still answer. Returns where the calls went: `{ handed:, parked: }`.
+      def drain(answer_s: ANSWERS_WITHIN_S) = ask("agent.drain", lands_as: "agent.draining", data: {}, within_s: answer_s)
+
+      # How many tool runs have not sent their `tool.result` yet.
+      def in_flight = @lock.synchronize { @running.count(&:alive?) }
+
+      # Wait until every running tool has answered, or `within_s` passed.
+      def settled(within_s: nil)
+        deadline = within_s && (now + within_s)
+        @lock.synchronize { @running.dup }.each { |thread| thread.join(deadline && [deadline - now, 0].max) }
+        nil
+      end
+
+      private
+
+      # Always answer with exactly one `tool.result`: without one the turn waits forever.
+      # Runs on its own thread so a slow tool does not block the socket reader.
+      def run_tool(event, call)
+        call_id, name, arguments = event.data.values_at(:call_id, :name, :arguments)
+        tool = @tools[name.to_s]
+        return call.tool_result({ call_id:, name:, error: "this app declares no tool called #{name}" }) if tool.nil?
+
+        running = Thread.new do
+          started = now
+          begin
+            output = tool[:run].call(arguments || {}, call)
+            call.tool_result({ call_id:, name:, output:, duration_s: now - started })
+          rescue StandardError => e
+            # Report the exception to the model as the tool's `error`.
+            call.tool_result({ call_id:, name:, error: e.message, duration_s: now - started })
+          end
+        end
+        @lock.synchronize { (@running << running).select!(&:alive?) }
+      end
+
+      # Every ask needs one answer, or the console's request hangs until the gateway gives up. On a
+      # thread of its own: a panel reads the tenant's systems, and this is the socket's reader.
+      def answer_the_console(asked)
+        id, verb, data = asked.values_at(:id, :verb, :data)
+        Thread.new do
+          raise DevRefused.new(501, NO_DEV_HANDLER) if @dev.nil?
+
+          command("dev.answer", nil, { id:, result: @dev.call(verb, data || {}) })
+        rescue DevRefused => e
+          command("dev.answer", nil, { id:, refused: { status: e.status, detail: e.detail } })
+        rescue StandardError => e
+          command("dev.answer", nil, { id:, refused: { status: 500, detail: e.message } })
+        end
+      end
+
+      # Await the reply event, or an `error` carrying our id. Only register/configure are awaited;
+      # other commands are fire-and-forget.
+      def ask(type, lands_as:, data:, within_s: ANSWERS_WITHIN_S)
+        id = "#{@slug}:#{type}"
+        answer = Thread::Queue.new
+        @waiting << { type: lands_as, id:, answer: }
+        @client.send_command(type:, agent: @slug, call: nil, data:, id:)
+        settled = answer.pop(timeout: within_s)
+        raise NotConnected, "#{type}: the gateway did not answer in #{within_s}s" if settled.nil?
+        raise settled if settled.is_a?(Exception)
+
+        settled
+      ensure
+        @waiting.reject! { |one| one[:answer].equal?(answer) }
+      end
+
+      def settle(event)
+        @waiting.dup.each do |waiting|
+          if event.type == waiting[:type]
+            waiting[:answer].push(event.data)
+          elsif event.type == "error" && event.data[:id] == waiting[:id]
+            waiting[:answer].push(Refused.new(event.data))
+          end
+        end
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/pinecall/client/call.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # A call being served: line details read from the log, and the commands it can send.
+    #
+    # Commands are not awaited; their effects arrive later as log entries.
+    class Call
+      attr_reader :id, :today, :claimed, :run, :medium
+      attr_accessor :status, :channel, :from, :to, :contact, :state
+
+      def initialize(id, agent, opened_at)
+        @id = id
+        @agent = agent
+        @today = Time.at(opened_at).strftime("%Y-%m-%d")
+        @status = "ringing"
+        @channel = nil
+        # Spoken or written, as `call.started` says; nil before it, and from a gateway that does not say.
+        @medium = nil
+        @from = nil
+        @to = nil
+        @contact = nil
+        @claimed = nil
+        @run = nil
+        @state = {}
+        @listeners = Listeners.new { |error| agent.on_error(error) }
+      end
+
+      def agent_slug = @agent.slug
+
+      # Listen for one event type on this call; the returned lambda unsubscribes.
+      def on(type, &listener) = @listeners.on(type, &listener)
+
+      # Listen for every event on this call.
+      def on_any(&listener) = @listeners.on_any(&listener)
+
+      # ── commands ───────────────────────────────────────────────────────────
+
+      # Speak `text` verbatim now, as a `turn.agent`.
+      def say(text, **options) = command("agent.say", { text: }.merge(options))
+
+      # Make the model speak now, guided by instructions the caller does not hear.
+      def reply(instructions, **options) = command("agent.reply", { instructions: }.merge(options))
+
+      # Replace one prompt block by name.
+      def set_prompt(name, text) = command("prompt.set", { name: name.to_s, text: })
+
+      # Set the tools currently visible to the model (a subset of the declared ones).
+      def set_tools(tools) = command("tools.set", { tools: })
+
+      # Send the full state; answered with `state.changed`.
+      def set_state(state, changed = nil)
+        @state = state
+        wire = { state: }
+        wire[:changed] = Array(changed).map(&:to_s) unless changed.nil?
+        command("state.set", wire)
+      end
+
+      def tool_result(result) = command("tool.result", result)
+
+      # Send an event from the application's backend; the agent must declare `name`.
+      def event(name, data) = command("call.event", { name: name.to_s, data: })
+
+      # End the call; `call.ended` follows with reason `agent_hung_up`.
+      def hangup(reason = nil) = command("call.hangup", reason.nil? ? {} : { reason: })
+
+      # Append an application entry to the call's log, as a `custom` entry.
+      def log(name, data = {}) = command("call.log", { name: name.to_s, data: })
+
+      # Send any call-scoped command of the wire.
+      def command(type, data) = @agent.command(type, @id, data)
+
+      # ── entries ────────────────────────────────────────────────────────────
+
+      # Apply an event to the call, then notify listeners.
+      def take(event)
+        learn(event)
+        @listeners.emit(event, self)
+      end
+
+      private
+
+      def learn(event)
+        case event.type
+        when "call.ringing" then the_line(event.data, "ringing")
+        when "call.dialing" then the_line(event.data, "dialing")
+        when "call.started" then started(event.data)
+        when "call.attached" then attached(event.data)
+        when "call.ended" then @status = "ended"
+        when "state.changed" then @state = event.data[:state].dup
+        when "call.claimed" then @claimed = event.data[:code]
+        end
+      end
+
+      # Handed over mid-conversation: the call's own start, the state it is in, the code it claimed.
+      def attached(data)
+        line = data[:started]
+        started(line)
+        @state = data[:state].dup
+        @today = Time.at(line[:started_at]).strftime("%Y-%m-%d")
+        @claimed = data[:claimed]
+      end
+
+      def started(line)
+        the_line(line, "active")
+        @medium = line[:medium]
+      end
+
+      def the_line(line, status)
+        @status = status
+        @channel = line[:channel]
+        @from = line[:from]
+        @to = line[:to]
+        @contact = line[:caller]
+        @run = line[:run]
+      end
+    end
+
+    # Live calls by id; a call is dropped once it has ended.
+    class CallBook
+      def initialize(agent)
+        @agent = agent
+        @live = {}
+        @lock = Mutex.new
+      end
+
+      def live = @lock.synchronize { @live.values.dup }
+
+      # Find or create the call for an entry.
+      def of(id, at)
+        @lock.synchronize { @live[id] ||= Call.new(id, @agent, at) }
+      end
+
+      # Drop an ended call; `call.ended` listeners have already run.
+      def forget(call)
+        @lock.synchronize { @live.delete(call.id) } if call.status == "ended"
+      end
+    end
+  end
+end

data/lib/pinecall/client/connection.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # The gateway websocket: auth, reconnect with backoff, heartbeat, and one reader thread.
+    #
+    # The key goes in the `Authorization` header, never the URL (URLs end up in access logs).
+    # A bad key closes with 1008 and no body. `websocket-driver` handles framing over a plain
+    # TCP/TLS socket, so no event loop is needed.
+    class Connection
+      FIRST_WAIT_S = 0.5
+      LONGEST_WAIT_S = 30.0
+      GROWS_BY = 2
+      PINGS_EVERY_S = 30
+
+      Handlers = Data.define(:on_open, :on_entry, :on_error, :on_heartbeat)
+
+      attr_reader :url
+
+      def initialize(url:, api_key:, handlers:, env: nil, ping_every: PINGS_EVERY_S, backoff: {})
+        @url = Endpoints.apps(url)
+        @api_key = api_key
+        @env = env
+        @handlers = handlers
+        @ping_every = ping_every
+        @backoff = { first: FIRST_WAIT_S, longest: LONGEST_WAIT_S, grows_by: GROWS_BY }.merge(backoff)
+        @lock = Mutex.new
+        @open = false
+        @closed = false
+        @attempt = 0
+      end
+
+      def open? = @open
+
+      # Connect and return once `on_open` has run; reconnects are handled internally afterwards.
+      def start
+        @closed = false
+        @opened = Thread::Queue.new
+        @reader = Thread.new { dial_until_closed }
+        @reader.abort_on_exception = false
+        answer = @opened.pop(timeout: 30)
+        # Later failures go to `on_error`, not to this caller.
+        @opened = nil
+        raise NotConnected, "the gateway did not answer in 30s: #{@url}" if answer.nil?
+        raise answer if answer.is_a?(Exception)
+
+        self
+      end
+
+      # Raises when disconnected instead of queueing: a queued command could land after its call ended.
+      def send_frame(command)
+        @lock.synchronize do
+          raise NotConnected, "#{command.type}: the gateway is not connected" unless @open
+
+          @driver.text(Wire.encode(command))
+        end
+      end
+
+      # A drain was asked: the gateway closing the socket from now on is not dialled back.
+      def leaving! = @leaving = true
+
+      # Close without reconnecting.
+      def close
+        @closed = true
+        @open = false
+        @heartbeat&.kill
+        @socket&.close
+        # A stop is read on the reader thread itself, which cannot wait for its own end.
+        @reader&.join(1) unless Thread.current.equal?(@reader)
+        nil
+      end
+
+      # Called by websocket-driver.
+      def write(bytes)
+        @socket.write(bytes)
+      rescue IOError, SystemCallError => e
+        @handlers.on_error.call(e)
+      end
+
+      private
+
+      def dial_until_closed
+        until @closed
+          begin
+            dial
+          rescue StandardError => e
+            fail_the_first_dial(e)
+          end
+          break if @closed || @leaving
+
+          sleep(wait_s)
+        end
+      end
+
+      def dial
+        @socket = connect_to(URI.parse(@url))
+        @driver = WebSocket::Driver.client(self)
+        @driver.set_header("Authorization", "Bearer #{@api_key}")
+        @driver.set_header(Rest::ENV_HEADER, @env) unless @env.nil?
+        @driver.on(:open) { opened }
+        @driver.on(:message) { |event| took(event.data) }
+        @driver.on(:close) { |event| shut(event) }
+        @driver.start
+        read_until_closed
+      end
+
+      def connect_to(url)
+        port = url.port || (url.scheme == "wss" ? 443 : 80)
+        socket = TCPSocket.new(url.host, port)
+        return socket unless url.scheme == "wss"
+
+        context = OpenSSL::SSL::SSLContext.new
+        context.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+        tls = OpenSSL::SSL::SSLSocket.new(socket, context)
+        tls.hostname = url.host
+        tls.sync_close = true
+        tls.connect
+        tls
+      end
+
+      def read_until_closed
+        loop do
+          bytes = @socket.readpartial(4096)
+          @driver.parse(bytes)
+        end
+      rescue EOFError, IOError, SystemCallError, OpenSSL::SSL::SSLError
+        @open = false
+      end
+
+      # Registration runs on its own thread: this is the reader thread, and `agent.register` is
+      # answered by an entry it has to read.
+      def opened
+        @open = true
+        @attempt = 0
+        @heartbeat = Thread.new { beat }
+        Thread.new { declare }
+      end
+
+      def declare
+        @handlers.on_open.call
+        @opened&.push(:open)
+      rescue StandardError => e
+        # First connection: raise from `start`. Reconnect: report via `on_error`.
+        @opened.nil? || @opened.closed? ? @handlers.on_error.call(e) : @opened.push(e)
+      end
+
+      def took(raw)
+        @handlers.on_entry.call(Wire.decode_entry(JSON.parse(raw, symbolize_names: true)))
+      rescue StandardError => e
+        @handlers.on_error.call(e)
+      end
+
+      def shut(event)
+        @open = false
+        @heartbeat&.kill
+        return if @closed
+
+        # Only a failed first connection is reported to `start`; later closes just retry.
+        return unless @opened && !@opened.closed? && @attempt.zero?
+
+        @opened.push(NotConnected.new("the gateway refused the socket: closed with #{event.code}"))
+      end
+
+      def fail_the_first_dial(error)
+        @open = false
+        return @handlers.on_error.call(error) unless @opened && !@opened.closed? && @attempt.zero?
+
+        @opened.push(NotConnected.new("#{@url}: #{error.message}"))
+      end
+
+      def beat
+        loop do
+          sleep(@ping_every)
+          break unless @open
+
+          @handlers.on_heartbeat.call
+        end
+      rescue StandardError => e
+        @handlers.on_error.call(e)
+      end
+
+      # Full jitter, so clients do not reconnect in lockstep.
+      def wait_s
+        window = [@backoff[:longest], @backoff[:first] * (@backoff[:grows_by]**@attempt)].min
+        @attempt += 1
+        rand * window
+      end
+    end
+  end
+end