terret-ws 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9317837e6392b15e05b940ab03670aff9cb6ad3a9f4566f06c7ab358400c4cec
+  data.tar.gz: e575b34d528824fc811d2c7f0297adef5871994dc0490117cc4bf4f4d1c760b6
+SHA512:
+  metadata.gz: 42e8fbeca7c9862fce9e637335a15c2120601038709c1966f0895474183a24c1589c85c714a2cdb6faafdb9ad9e1912205859588952ef365518df7e9069913a1
+  data.tar.gz: 0e85c16e7aaafaa627d0944d7b09c9b78191495eb43a4ff09892f48a88ff0f4a3011238037ccccfec69a1d3cbc294d138b7d2bd58fdcbcb09da96402a9d4b983

data/lib/terret/ws/bounded_queue.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "async/notification"
+
+module Terret
+  module WS
+    # Outbound frame queue: non-blocking producer, waiting consumer. push
+    # returns false when full instead of blocking, because the producer is
+    # session/event dispatch and a slow socket must never stall the agent
+    # loop (plan §9.3).
+    class BoundedQueue
+      def initialize(limit)
+        @limit = limit
+        @items = []
+        @closed = false
+        @waiting = Async::Notification.new
+        @space = Async::Notification.new
+      end
+
+      def push(item)
+        return false if @closed || @items.size >= @limit
+
+        @items << item
+        @waiting.signal
+        true
+      end
+
+      # Blocking push for the connection's own replay fiber: waits for the
+      # writer to drain instead of dropping. Dispatch-path pushes must stay
+      # non-blocking — only replay may use this. False when closed.
+      def wait_push(item)
+        loop do
+          return false if @closed
+          return true if push(item)
+
+          @space.wait
+        end
+      end
+
+      # Blocks until an item arrives or the queue closes; nil means
+      # closed-and-drained.
+      def pop
+        loop do
+          unless @items.empty?
+            item = @items.shift
+            @space.signal
+            return item
+          end
+          return nil if @closed
+
+          @waiting.wait
+        end
+      end
+
+      def clear = @items.clear
+
+      def closed? = @closed
+
+      def close
+        @closed = true
+        @waiting.signal
+        @space.signal
+      end
+    end
+  end
+end

data/lib/terret/ws/connection.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require "async"
+require "json"
+require_relative "frames"
+require_relative "bounded_queue"
+
+module Terret
+  module WS
+    # The per-client protocol engine (docs/protocol.md). Transport is
+    # injectable exactly like the openrouter adapter's: tests drive it with
+    # an in-memory socket; the real endpoint adapts async-websocket to the
+    # same io contract — read -> String|nil (nil on close), write(String),
+    # close. One Connection serves one agent. Frames land on existing seams;
+    # everything outbound is a durable session event serialized as-is.
+    class Connection
+      # The bearer this client presented. Kept so a token rotation can sweep
+      # the connections it just invalidated (Service#reconfigure).
+      attr_reader :agent, :token
+
+      # A set_policy is durable and every future tool call scans what it
+      # installs, so the frame is bounded: a client must not be able to write
+      # megabytes of patterns into the log.
+      MAX_PATTERNS = 128
+      MAX_PATTERN_LENGTH = 256
+
+      def initialize(ctx:, agent:, io:, runner:, resumer: ->(_agent) {}, queue_limit: 256,
+                     token: nil, replay_limit: nil, replay_gate: nil)
+        @ctx = ctx
+        @agent = agent
+        @token = token
+        @io = io
+        @runner = runner # ->(agent, text) { start a turn task owned by the server }
+        @resumer = resumer # ->(agent) { re-enter the log's open turn, same rooting }
+        @sid = agent.session_id
+        @queue_limit = queue_limit
+        @replay_limit = replay_limit
+        @replay_gate = replay_gate
+        @queue = BoundedQueue.new(queue_limit)
+        @tail = nil
+        @live = false
+        @floor = 0
+      end
+
+      # Serve until the client goes away. A writer task drains the bounded
+      # queue so a slow socket never blocks session/event dispatch.
+      def run
+        Sync do |task|
+          writer = task.async do
+            while (text = @queue.pop)
+              @io.write(text)
+            end
+          rescue StandardError => e
+            warn "terret-ws: #{@sid}: writer failed: #{e.class}: #{e.message}"
+          ensure
+            @io.close
+          end
+
+          hello
+          while (text = @io.read)
+            begin
+              dispatch(text)
+            rescue StandardError => e
+              # docs/protocol.md: any unexpected server-side failure while
+              # serving this connection surfaces as internal, then closes.
+              warn "terret-ws: #{@sid}: dropping connection on dispatch error: #{e.class}: #{e.message}"
+              shutdown(code: "internal")
+              break
+            end
+          end
+        ensure
+          dispose
+          writer&.wait
+        end
+      end
+
+      # Queue an error and stop; the writer drains first so the client sees
+      # why it was dropped (superseded, lagged). Idempotent: the tail is
+      # disposed so later appends cannot re-enter and wipe the error frame.
+      def shutdown(code:)
+        @tail&.call
+        @tail = nil
+        return if @queue.closed?
+
+        @queue.clear
+        @queue.push(Frames.error(code: code))
+        @queue.close
+      end
+
+      private
+
+      def sessions = @ctx[:sessions]
+
+      # Precondition: the session is resolved (Sessions#create/resume) before
+      # a Connection is built — fetch here never sees an unknown sid.
+      def hello
+        last = sessions.fetch(@sid).events.last&.seq || -1
+        push_frame(Frames.hello(session_id: @sid, last_seq: last))
+      end
+
+      def dispatch(text)
+        frame = Frames.decode(text)
+        case frame[:type]
+        when "subscribe" then handle_subscribe(frame[:from_seq])
+        when "inject" then handle_inject(frame[:text], frame.fetch(:wake, false))
+        when "cancel" then handle_cancel(frame[:reason])
+        when "approve" then handle_resolution(frame[:call_id], "approved", nil)
+        when "deny"    then handle_resolution(frame[:call_id], "denied", frame[:reason])
+        when "set_model" then handle_set_model(frame[:role], frame[:model])
+        when "set_policy" then handle_set_policy(frame[:patterns])
+        else
+          raise Frames::BadFrame, "#{frame[:type]} is not supported yet"
+        end
+      rescue Frames::BadFrame => e
+        push_frame(Frames.error(code: "bad_frame", message: e.message))
+      end
+
+      # A client that can't even take protocol frames is gone.
+      def push_frame(text)
+        return if @queue.push(text)
+
+        shutdown(code: "lagged")
+      end
+
+      # Replay-then-tail with no gap and no duplicate. Live events buffer
+      # while the replay reads and flushes; the flush loops until it drains
+      # because wait_push yields, and the final empty-check-to-flip is pure
+      # array work — nothing can slip between them on one reactor.
+      def handle_subscribe(from_seq)
+        @tail&.call
+        @live = false
+        # The replay window may start later than the client asked: a from_seq
+        # reaching further back than replay_limit is capped to the newest
+        # window, and the client is told (capped_start). The floor tracks the
+        # real start so the live tail stays contiguous with what was replayed.
+        start_seq = capped_start(from_seq)
+        @floor = start_seq
+        buffered = []
+        @tail = @ctx.on("session/event") do |ev|
+          next unless ev.session_id == @sid && ev.seq >= @floor
+
+          if @live
+            push_event(ev)
+          elsif buffered.size >= @queue_limit
+            # too far behind before the tail even started
+            shutdown(code: "lagged")
+          else
+            buffered << ev
+          end
+        rescue StandardError => e
+          # a socket-side failure must never surface into Sessions#append
+          warn "terret-ws: #{@sid}: dropping connection on listener error: #{e.class}: #{e.message}"
+          shutdown(code: "internal")
+        end
+
+        replayed = read_history(start_seq)
+        return unless replay(replayed)
+
+        last = replayed.empty? ? start_seq - 1 : replayed.last.seq
+        until buffered.empty?
+          batch = buffered.select { |ev| ev.seq > last }.sort_by(&:seq)
+          buffered.clear
+          return unless replay(batch)
+
+          last = batch.last.seq unless batch.empty?
+        end
+        @live = true
+      end
+
+      # Bound a single reconnect's replay. tip comes from the in-memory working
+      # set (O(1), no store read), so the cap is decided before any history is
+      # touched: a from_seq more than replay_limit events behind the tip is
+      # pulled forward to the newest replay_limit window, and the client is told
+      # where that window really begins so it does not believe it holds the
+      # skipped history. Without a replay_limit the client's from_seq stands.
+      def capped_start(from_seq)
+        return from_seq unless @replay_limit
+
+        tip = sessions.fetch(@sid).events.last&.seq || -1
+        return from_seq if tip - from_seq + 1 <= @replay_limit
+
+        start_seq = tip - @replay_limit + 1
+        push_frame(Frames.replay_truncated(requested_from_seq: from_seq, from_seq: start_seq))
+        start_seq
+      end
+
+      # Read the replay window under the shared concurrency gate: at most
+      # max_concurrent_replays of these run at once, the rest park their fiber
+      # (never the reactor) until a slot frees, so a reconnect storm cannot turn
+      # into N simultaneous log reads. The gate wraps only the read — the
+      # expensive, resource-bound step (plan §9.4) — so a slow client draining
+      # its replay never holds a slot and starves other reconnects. Absent a
+      # gate the read runs straight through.
+      def read_history(from_seq)
+        return sessions.read(@sid, from_seq: from_seq) unless @replay_gate
+
+        @replay_gate.acquire { sessions.read(@sid, from_seq: from_seq) }
+      end
+
+      # Replay runs in the connection's own fiber, so it waits for the writer
+      # to drain instead of dropping the client — a long log must never look
+      # like a slow reader. False when the queue closed mid-replay.
+      def replay(events)
+        events.each { |ev| return false unless @queue.wait_push(Frames.event(ev)) }
+        true
+      end
+
+      # A wake on an idle agent whose log holds an open turn resumes that
+      # turn — the text rides its next step as context/injected — instead of
+      # starting a new one. That is the autonomous restart story: after a
+      # deploy, the first stimulus picks the turn back up.
+      def handle_inject(text, wake)
+        if wake && @agent.status == :idle && @ctx[:loop].resumable?(@sid)
+          @agent.inject(text)
+          @resumer.call(@agent)
+        elsif wake && @agent.status == :idle
+          @runner.call(@agent, text)
+        else
+          @agent.inject(text)
+        end
+      end
+
+      def handle_cancel(reason)
+        case @agent.status
+        # :stopping is a cancel already standing on a turn that has not
+        # reached its boundary yet (docs/subagents.md §8). A client that sends
+        # a second frame into that window is not cancelling nothing — the turn
+        # is still running — so the frame is honored again with the newer
+        # reason rather than answered `not_running`.
+        when :running, :stopping
+          @agent.cancel(reason)
+        when :waiting_approval
+          # cancel first, THEN deny: the parked fiber unparks into a turn
+          # that already knows it is cancelled; each denial is durable
+          @agent.cancel(reason)
+          # nothing can be parked without the row, but every reference to an
+          # optional service is guarded, including the unreachable ones
+          if @ctx.service?(:approvals)
+            @ctx[:approvals].deny_pending!(@sid, reason: reason || "cancelled")
+          end
+        else
+          push_frame(Frames.error(code: "not_running"))
+        end
+      end
+
+      # call_id is deliberately not id: it is a foreign key to the tool/call
+      # event's id, and the wire-facing name in docs/protocol.md.
+      #
+      # Approvals are an opt-in row: without it, approve/deny is unsupported.
+      # With it, only a call with a standing approval/requested (and no
+      # verdict yet) accepts one — anything else answers stale_call and
+      # appends nothing, so a double approve or a typo cannot pollute the
+      # log. A verdict landing for an idle agent whose turn is still open in
+      # the log means no fiber is parked (the process restarted since it
+      # parked) — resume the turn.
+      def handle_resolution(call_id, verdict, reason)
+        unless @ctx.service?(:approvals)
+          return push_frame(Frames.error(code: "unsupported",
+                                         message: "no approvals service is mounted"))
+        end
+        unless @ctx[:approvals].pending?(@sid, call_id)
+          return push_frame(Frames.error(code: "stale_call",
+                                         message: "#{call_id} has no pending approval"))
+        end
+
+        payload = { call_id: call_id, verdict: verdict }
+        payload[:reason] = reason if reason
+        sessions.append(@sid, "approval/resolved", payload)
+        @resumer.call(@agent) if @agent.status == :idle && @ctx[:loop].resumable?(@sid)
+      end
+
+      def handle_set_model(role, model)
+        @ctx[:llm].set_role(role, model)
+      rescue ArgumentError => e
+        push_frame(Frames.error(code: "bad_frame", message: e.message))
+      end
+
+      def handle_set_policy(patterns)
+        unless patterns.is_a?(Array) && patterns.all? { |p| p.is_a?(String) }
+          return push_frame(Frames.error(code: "bad_frame",
+                                         message: "patterns must be an array of strings"))
+        end
+        if patterns.length > MAX_PATTERNS
+          return push_frame(Frames.error(code: "bad_frame",
+                                         message: "at most #{MAX_PATTERNS} patterns"))
+        end
+        if patterns.any? { |p| p.length > MAX_PATTERN_LENGTH }
+          return push_frame(Frames.error(code: "bad_frame",
+                                         message: "a pattern is at most #{MAX_PATTERN_LENGTH} characters"))
+        end
+
+        Tools::AllowList.update(@ctx, @sid, patterns)
+      end
+
+      def push_event(ev)
+        return if @queue.push(Frames.event(ev))
+
+        # the client fell too far behind: drop it rather than stall the loop
+        shutdown(code: "lagged")
+      end
+
+      def dispose
+        @tail&.call
+        @tail = nil
+        @queue.close
+      end
+    end
+  end
+end

data/lib/terret/ws/endpoint.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/http/server"
+require "async/http/endpoint"
+require "async/websocket/adapters/http"
+require "protocol/http/response"
+require_relative "frames"
+
+module Terret
+  module WS
+    # The real transport: async-websocket bound to GET /agents/{id}/ws.
+    # Everything protocol-shaped lives in Connection; this file only adapts
+    # a websocket to Connection's io contract and keeps the link alive with
+    # pings under load-balancer idle timeouts (plan §9.4).
+    class Endpoint
+      PATH = %r{\A/agents/([^/]+)/ws\z}
+
+      def initialize(service, host:, port:)
+        @service = service
+        @host = host
+        @port = port
+      end
+
+      def run
+        Sync do |task|
+          http = Async::HTTP::Endpoint.parse("http://#{@host}:#{@port}")
+          app = ->(request) { upgrade(request, task) }
+          Async::HTTP::Server.new(app, http).run
+        end
+      end
+
+      private
+
+      def upgrade(request, root_task)
+        m = request.path.match(PATH) or
+          return Protocol::HTTP::Response[404, {}, ["not found"]]
+
+        token = bearer(request)
+        response = Async::WebSocket::Adapters::HTTP.open(request) do |ws|
+          io = SocketIO.new(ws)
+          pinger = root_task.async do
+            loop do
+              sleep @service.heartbeat
+              ws.send_ping("")
+            end
+          end
+          begin
+            @service.attach(session_id: m[1], token: token, io: io, runner_task: root_task)
+          ensure
+            pinger.stop
+          end
+        end
+        response || Protocol::HTTP::Response[400, {}, ["websocket upgrade required"]]
+      end
+
+      def bearer(request)
+        request.headers["authorization"]&.[](/\ABearer (.+)\z/i, 1)
+      end
+
+      # Adapts Async::WebSocket::Connection to Connection's io contract.
+      class SocketIO
+        def initialize(ws) = @ws = ws
+
+        def read
+          message = @ws.read
+          return nil if message.nil?
+          # The wire contract is JSON text frames only (docs/protocol.md). A
+          # binary frame degrades to an invalid frame so the client gets a
+          # bad_frame answer instead of being silently interpreted as text.
+          return "\x00" unless message.is_a?(Protocol::WebSocket::TextMessage)
+
+          message.to_str
+        rescue EOFError, Errno::ECONNRESET, Protocol::WebSocket::ClosedError
+          nil
+        end
+
+        def write(text)
+          @ws.write(text)
+          @ws.flush
+        end
+
+        def close(*) = @ws.close
+      end
+    end
+  end
+end

data/lib/terret/ws/frames.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Terret
+  module WS
+    # Wire codec for docs/protocol.md. Server frames are durable session
+    # events serialized as-is, plus hello and error; client frames are the
+    # closed §9.2 set. Anything else is BadFrame.
+    module Frames
+      class BadFrame < StandardError; end
+
+      PROTO = 1
+
+      MAX_FRAME_BYTES = 1 << 20 # nothing legitimate on this wire is bigger
+
+      # required keys per client frame type
+      CLIENT = {
+        "subscribe" => [:from_seq],
+        "inject"    => [:text],
+        "cancel"    => [],
+        "approve"   => [:call_id],
+        "deny"      => [:call_id],
+        "set_model" => %i[role model],
+        "set_policy" => [:patterns]
+      }.freeze
+
+      module_function
+
+      def decode(text)
+        raise BadFrame, "frame must be a string" unless text.is_a?(String)
+        raise BadFrame, "frame exceeds #{MAX_FRAME_BYTES} bytes" if text.bytesize > MAX_FRAME_BYTES
+
+        h = begin
+          JSON.parse(text, symbolize_names: true)
+        rescue JSON::ParserError
+          raise BadFrame, "frame is not valid JSON"
+        end
+        raise BadFrame, "frame is not an object" unless h.is_a?(Hash)
+
+        required = CLIENT[h[:type]] or raise BadFrame, "unknown frame type #{h[:type].inspect}"
+        missing = required.reject { |k| h.key?(k) }
+        raise BadFrame, "#{h[:type]} frame missing #{missing.join(', ')}" unless missing.empty?
+
+        if h[:type] == "subscribe" && !(h[:from_seq].is_a?(Integer) && h[:from_seq] >= 0)
+          raise BadFrame, "from_seq must be a non-negative integer"
+        end
+        # every other typed field degrades to BadFrame here, so junk can never
+        # reach a seam as the wrong type and crash the read loop
+        %i[text call_id role model reason].each do |k|
+          next unless h.key?(k)
+
+          raise BadFrame, "#{k} must be a UTF-8 string" unless h[k].is_a?(String) && h[k].valid_encoding?
+        end
+        if h.key?(:wake) && ![true, false].include?(h[:wake])
+          raise BadFrame, "wake must be true or false"
+        end
+
+        h
+      end
+
+      def event(ev)
+        JSON.generate(id: ev.id, session_id: ev.session_id, seq: ev.seq,
+                      at: ev.at.iso8601(6), type: ev.type, payload: ev.payload)
+      end
+
+      def hello(session_id:, last_seq:)
+        JSON.generate(type: "hello", proto: PROTO, session_id: session_id, last_seq: last_seq)
+      end
+
+      def error(code:, message: nil)
+        h = { type: "error", code: code }
+        h[:message] = message if message
+        JSON.generate(h)
+      end
+
+      # Honest truncation: a subscribe reaching further back than the server's
+      # replay_limit gets only the newest window, and this frame tells the
+      # client the seq its replay actually begins at (`from_seq`) versus the one
+      # it asked for (`requested_from_seq`), so it never believes it holds the
+      # history in between. Sent before that window's first event.
+      def replay_truncated(requested_from_seq:, from_seq:)
+        JSON.generate(type: "replay_truncated", requested_from_seq: requested_from_seq,
+                      from_seq: from_seq)
+      end
+    end
+  end
+end

data/lib/terret/ws/service.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "async/semaphore"
+require_relative "connection"
+
+module Terret
+  module WS
+    # ctx[:ws] — the socket interface plugin. Owns bearer auth, the
+    # one-connection-per-agent rule, and turn tasks. Turn tasks are rooted on
+    # the server, never on a connection: a dropped client must not cancel a
+    # turn (plan §9.3). In v1 the agent id names the session.
+    class Service < Hames::Service
+      service_key :ws
+      inject :sessions, :loop, :llm
+      config_schema tokens:      { type: Hash, default: {},
+                                   doc: "token => agent-id map authorizing socket connections" },
+                    queue_limit: { type: Integer, default: 256,
+                                   doc: "max frames buffered per connection before backpressure" },
+                    heartbeat:   { type: Numeric, default: 20, doc: "seconds between server heartbeats" },
+                    replay_limit: { type: Integer, default: 10_000,
+                                    doc: "max events replayed on one subscribe; a from_seq reaching " \
+                                         "further back gets the newest replay_limit and a replay_truncated frame" },
+                    max_concurrent_replays: { type: Integer, default: 4,
+                                              doc: "max subscribe replays reading the log at once; " \
+                                                   "surplus connections park until a slot frees" }
+
+      def start(ctx)
+        @ctx = ctx
+        @tokens = config[:tokens] || {}
+        @queue_limit = config[:queue_limit] || 256
+        @heartbeat = config[:heartbeat] || 20
+        @replay_limit = config[:replay_limit] || 10_000
+        # One shared gate across every connection is what makes the cap global;
+        # it is created once and its limit adjusted in place (never replaced),
+        # or old and new connections would each get their own allowance.
+        @replay_gate = Async::Semaphore.new(config[:max_concurrent_replays] || 4)
+        @connections = {}
+      end
+
+      def reconfigure(config)
+        @tokens = config[:tokens] || {}
+        @queue_limit = config[:queue_limit] || 256
+        @heartbeat = config[:heartbeat] || 20
+        @replay_limit = config[:replay_limit] || 10_000
+        @replay_gate.limit = config[:max_concurrent_replays] || 4
+        revoke_stale_connections
+      end
+
+      attr_reader :heartbeat
+
+      # Constant-time bearer check, per agent id, before the agent exists.
+      def authorized?(session_id, token)
+        expected = @tokens[session_id.to_s]
+        return false unless expected && token
+
+        OpenSSL::Digest::SHA256.digest(expected.to_s) ==
+          OpenSSL::Digest::SHA256.digest(token.to_s)
+      end
+
+      # Serve one client over io until it closes. runner_task owns the turn
+      # tasks so they outlive the connection handler.
+      def attach(session_id:, token:, io:, runner_task: Async::Task.current)
+        unless authorized?(session_id, token)
+          io.write(Frames.error(code: "unauthorized"))
+          io.close
+          return
+        end
+
+        sid = session_id.to_s
+        resolve_session(sid)
+        begin
+          agent = @ctx[:loop].agent("agent-#{sid}") || @ctx[:loop].spawn_agent(session_id: sid)
+        rescue AgentExists, AgentCapExceeded => e
+          # a registry refusal is this process's business, not the client's
+          # fault; it still deserves an answer rather than a dropped socket
+          io.write(Frames.error(code: "internal", message: e.message))
+          io.close
+          return
+        end
+        @connections[sid]&.shutdown(code: "superseded")
+        conn = Connection.new(ctx: @ctx, agent: agent, io: io,
+                              runner: runner(runner_task), resumer: resumer(runner_task),
+                              queue_limit: @queue_limit, token: token,
+                              replay_limit: @replay_limit, replay_gate: @replay_gate)
+        @connections[sid] = conn
+        conn.run
+      ensure
+        @connections.delete(sid) if sid && @connections[sid].equal?(conn)
+      end
+
+      # Blocks serving websocket upgrades. Lazily requires the endpoint so
+      # nothing needs async-websocket until something listens.
+      def serve(port:, host: "127.0.0.1")
+        require_relative "endpoint"
+        Endpoint.new(self, host: host, port: port).run
+      end
+
+      private
+
+      # A rotation that only locks out the next connection is not a
+      # revocation: every live connection whose presented bearer no longer
+      # authorizes its session goes, with the same frame it would have got at
+      # the door.
+      def revoke_stale_connections
+        stale = @connections.reject { |sid, conn| authorized?(sid, conn.token) }
+        stale.each do |sid, conn|
+          conn.shutdown(code: "unauthorized")
+          @connections.delete(sid)
+        end
+      end
+
+      def resolve_session(sid)
+        sessions = @ctx[:sessions]
+        sessions.session_ids.include?(sid) ? sessions.resume(sid) : sessions.create(id: sid)
+      end
+
+      def runner(task)
+        lambda do |agent, text|
+          task.async do
+            @ctx[:loop].run_turn(agent, text)
+          rescue TurnAlreadyRunning
+            # two wake frames in one read burst both saw :idle before either
+            # task ran; the loser's text rides the winner's next step (or the
+            # next turn) via the inbox instead of dropping
+            agent.inject(text)
+          rescue => e
+            warn "terret-ws: turn failed for #{agent.id}: #{e.class}: #{e.message}"
+          end
+        end
+      end
+
+      # Re-enter an open turn (a wake or a verdict arrived for an agent with
+      # no live fiber — the process restarted mid-turn). Rooted on the server
+      # task for the same reason turns are: a dropped client must not kill it.
+      def resumer(task)
+        lambda do |agent|
+          task.async do
+            @ctx[:loop].resume_turn(agent)
+          rescue TurnAlreadyRunning
+            nil # something else got there first; nothing is lost
+          rescue => e
+            warn "terret-ws: resume failed for #{agent.id}: #{e.class}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/terret/ws.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+begin
+  require "terret"
+rescue LoadError
+  require_relative "../../../terret-core/lib/terret" # monorepo path source
+end
+
+require_relative "ws/frames"
+require_relative "ws/bounded_queue"
+require_relative "ws/connection"
+require_relative "ws/service"

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: terret-ws
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terret-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: async-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.30'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.30'
+description: 'The v1 interface: one connection per agent, durable session events out,
+  five client frames in, exact replay-then-tail reconnect on the append-only log,
+  bounded-queue backpressure, heartbeat, and bearer auth. Ships as a plugin because
+  the primary interface being a plugin is the architecture''s point.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terret/ws.rb
+- lib/terret/ws/bounded_queue.rb
+- lib/terret/ws/connection.rb
+- lib/terret/ws/endpoint.rb
+- lib/terret/ws/frames.rb
+- lib/terret/ws/service.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret
+  bug_tracker_uri: https://github.com/terret-org/terret/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: WebSocket interface for the Terret agent harness
+test_files: []