yrby-agent 0.1.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc39c696ec3eda40ebaa1aca8cbca2193d47f45fa255d03684276b6b3d1f0830
+  data.tar.gz: eff30a5794a471040bcc6bae86a359c1b89d34c7727e9b69ef3aeb848d56b8c2
+SHA512:
+  metadata.gz: 3c76f601752b0fd45c385897eaec1e8dfdd6119703a4eb7c193a25bfd514a383cbcec851bbcd89e0e1bcad07c4efda2958303d3aeebe692fd51a8553f0a382e2
+  data.tar.gz: 71dadfd11c7920843dc982d6659d644f022af574306dcdc19bc99c84d748234e737643daec03f40e8cd35d9e37e001af60048517688c957a5c3c3dd53183cdf0

data/CHANGELOG-agent.md

@@ -0,0 +1,37 @@
+# Changelog: yrby-agent
+
+All notable changes to the `yrby-agent` gem are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+The first release. Everything here is experimental and may change in any
+release. See [docs/experimental.md](docs/experimental.md).
+
+### Added
+
+- `Y::ActionCable::Client` joins a document over the cable's websocket with a
+  grant, as a browser does. `edit` sends a change, every update is resent
+  until acked, and a dropped socket reconnects. `presence=` shows the client
+  to others and renews itself. It sends the URL's origin, and `headers:`
+  add anything else the connection checks.
+- `Y::Collaborator` takes part in a document the way a person does, from a
+  job or anywhere else. A subclass defines `joined` and `changed(blocks)`,
+  where an AI agent calls its model, and sets `self.presence =`.
+  `Reviewer.run(post.collaborative_document(:body), url:, headers:)` joins
+  with a grant, calls `changed` with live handles to the blocks people
+  changed once their typing settles, and returns when nobody else has been
+  present for `idle` seconds, after `max_stay`, or on `leave`. One
+  collaborator works on a document at a time, through a lock in
+  `Rails.cache`, or one per person with `as: person`. An error in `joined`
+  or `changed` ends the collaborator and raises out of `run`.
+  `require "y/collaborator"` to use it.
+- `Y::Agent`, a `Y::Collaborator` with a model. A subclass sets `model` and
+  `instructions`, which are RubyLLM::Agent's, and runs from a job. When
+  people's typing settles, `changed` asks the model about the blocks they
+  changed, in a fresh chat with tools that read the document
+  (`read_document`) and edit its blocks (`rewrite_block`, `insert_paragraph`,
+  `delete_block`). The tools name blocks by short ids that stay on their
+  blocks, and write through `edit`. `ask` asks anything else, and
+  `document_tools` picks which tools the model gets.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/y/action_cable/client/outbox.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
+  class Client
+    # The local updates the server has not acknowledged yet, in the order
+    # they were made. Each carries the id the server acks, and an ack
+    # confirms only its own update: the server may record the updates of one
+    # connection out of order, so an ack for a later update says nothing about
+    # an earlier one. Nothing here touches the socket: the session sends what
+    # `pending` holds and this drops what `ack` confirms. A retransmit sends
+    # the pending updates one by one, in order.
+    class Outbox
+      Pending = Data.define(:id, :update)
+
+      def initialize
+        @pending = []
+        @next_id = 1
+      end
+
+      def pending = @pending.dup
+
+      def pending? = !@pending.empty?
+
+      # Queue a local update. Returns it with the id it will be acked by.
+      def push(update)
+        entry = Pending.new(id: @next_id, update: update)
+        @next_id += 1
+        @pending << entry
+        entry
+      end
+
+      # Confirm delivery of the update sent as `id`. The value comes off the
+      # wire: one that is not an integer, or names an id not pending, drops
+      # nothing. Returns true when something was confirmed.
+      def ack(id) # rubocop:disable Naming/PredicateMethod -- an action that reports whether it did anything
+        return false unless id.is_a?(Integer)
+
+        !@pending.reject! { |entry| entry.id == id }.nil?
+      end
+    end
+  end
+end

data/lib/y/action_cable/client/session.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "y/action_cable/sync"
+require "y/action_cable/client/outbox"
+
+module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
+  class Client
+    # The client side of the protocol with no socket: cable messages in,
+    # cable messages out through the block, and the document kept current.
+    # It is what the JS provider's session is, in Ruby, so it can be driven
+    # in a test with nothing listening. The client feeds it every message
+    # the socket delivers and every command the caller makes, all on one
+    # reactor, so its own state needs no lock.
+    #
+    # Messages are the JSON hashes the cable carries. A command goes out as
+    # { command:, identifier:, data: } and a channel message comes in as
+    # { identifier:, message: }, the message being Sync's envelope.
+    class Session
+      # The second byte of a sync frame is y-protocols' sync type; 1 is
+      # SyncStep2, the server's answer to our SyncStep1.
+      SYNC_STEP2 = 1
+
+      # `root:` names the root XmlText whose top-level blocks on_update
+      # reports as changed; nil turns block tracking off.
+      def initialize(doc, identifier, root: "root", &transmit)
+        @doc = doc
+        @identifier = identifier
+        @root = root
+        @transmit = transmit
+        @outbox = Outbox.new
+        @subscribed = false
+        @synced = false
+        @loaded = false
+        @presence = nil
+        @asked = nil
+        @on_update = nil
+        @on_awareness = nil
+      end
+
+      def on_update(&block) = @on_update = block
+      def on_awareness(&block) = @on_awareness = block
+      def synced? = @synced
+      def pending? = @outbox.pending?
+
+      # One message from the server. Returns what it was: :welcome, :ping,
+      # :confirmed, :rejected, :disconnect, :synced for the message that
+      # completed a handshake, :ack, :update, or :awareness for a message of
+      # this subscription, :message for one it ignored, and nil for anything
+      # else. The connection acts on :synced, :rejected, and :disconnect.
+      def receive(message)
+        case message["type"]
+        when "welcome" then welcome
+        when "ping" then :ping
+        when "confirm_subscription" then confirmed if mine?(message)
+        when "reject_subscription" then :rejected if mine?(message)
+        when "disconnect" then :disconnect
+        else
+          payload = message["message"]
+          receive_payload(payload) || :message if mine?(message) && payload.is_a?(Hash)
+        end
+      end
+
+      # The socket dropped. Pending updates stay for the next confirmation.
+      def dropped
+        @subscribed = false
+        @synced = false
+      end
+
+      # A local update: kept until the server acks it, sent now when
+      # subscribed and otherwise when the subscription is next confirmed.
+      def send_update(update)
+        entry = @outbox.push(update)
+        send_entry(entry) if @subscribed
+      end
+
+      # Presence goes out as is. The last frame is said again on a reconnect,
+      # so peers see this client back without waiting for its next refresh.
+      def send_awareness(frame)
+        @presence = frame
+        send_frame(frame) if @subscribed
+      end
+
+      # Send everything unacked, in order. The retransmit timer calls this.
+      def resend
+        return unless @subscribed
+
+        @outbox.pending.each { |entry| send_entry(entry) }
+      end
+
+      def unsubscribe
+        command("unsubscribe") if @subscribed
+        @subscribed = false
+      end
+
+      private
+
+      # The server says welcome once the socket is up, and takes commands
+      # from then on.
+      def welcome
+        command("subscribe")
+        :welcome
+      end
+
+      # The subscription is confirmed: answer the server's opening SyncStep1
+      # if it came first, send ours, say who we are, and replay what is
+      # still unacked. The server's SyncStep2 completes the handshake.
+      def confirmed
+        @subscribed = true
+        send_frame(@doc.handle_sync_message(@asked)[2]) if @asked
+        @asked = nil
+        send_frame(@doc.sync_step1)
+        send_frame(@presence) if @presence
+        resend
+        :confirmed
+      end
+
+      def receive_payload(payload)
+        return @outbox.ack(payload["ack"]) && :ack if payload.key?("ack")
+
+        # AnyCable whispers presence under its own key; the server relays
+        # document frames under "update".
+        encoded = payload["awareness"] || payload["update"]
+        frame = decode(encoded) if encoded.is_a?(String)
+        receive_frame(frame) if frame
+      end
+
+      def decode(encoded)
+        Base64.strict_decode64(encoded)
+      rescue ArgumentError
+        nil
+      end
+
+      # A malformed frame is dropped by Y.message_kind. The server's SyncStep1
+      # is answered with our full state, the way a browser answers it; one
+      # that arrives before the subscription is confirmed (Action Cable sends
+      # it from `subscribed`) waits for the confirmation.
+      def receive_frame(frame)
+        case Y.message_kind(frame)
+        when Sync::MSG_KIND_SYNC_STEP1
+          @subscribed ? send_frame(@doc.handle_sync_message(frame)[2]) : @asked = frame
+          nil
+        when Sync::MSG_KIND_UPDATE then receive_update(frame)
+        when Sync::MSG_KIND_AWARENESS
+          @on_awareness&.call(frame)
+          :awareness
+        end
+      end
+
+      # Apply what the doc does not already hold (its own updates come back
+      # from the server too) and report it. The first SyncStep2 is the load,
+      # not a change, so it does not fire on_update; a later one, after a
+      # reconnect, carries what was missed and does.
+      def receive_update(frame)
+        update = Y.update_from_message(frame)
+        apply(update) if update && @doc.update_advances?(update)
+        return :update unless frame.getbyte(1) == SYNC_STEP2 && !@synced
+
+        @synced = true
+        @loaded = true
+        :synced
+      end
+
+      def apply(update)
+        changed = @root ? @doc.apply_update_changes(update, @root) : (@doc.apply_update(update) && nil)
+        @on_update&.call(update, @doc, changed) if @loaded
+      end
+
+      def send_entry(entry)
+        message("update" => Base64.strict_encode64(Y.wrap_update(entry.update)), "id" => entry.id)
+      end
+
+      def send_frame(bytes) = message("update" => Base64.strict_encode64(bytes))
+
+      def message(data)
+        @transmit.call("command" => "message", "identifier" => @identifier, "data" => JSON.generate(data))
+      end
+
+      def command(name) = @transmit.call("command" => name, "identifier" => @identifier)
+
+      def mine?(message) = message["identifier"] == @identifier
+    end
+  end
+end

data/lib/y/action_cable/client.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+begin
+  require "async"
+  require "async/http/endpoint"
+  require "async/websocket/client"
+rescue LoadError => e
+  raise LoadError, "Y::ActionCable::Client needs the async-websocket gem, which yrby-agent depends on. (#{e.message})"
+end
+require "json"
+require "logger"
+require "y/action_cable/client/session"
+
+# y/collaborator and y/agent load this file too, so one warning covers all three.
+warn "yrby-agent: Y::ActionCable::Client, Y::Collaborator, and Y::Agent are experimental " \
+     "and may change in any release. Warning[:experimental] = false turns this off.", category: :experimental
+
+module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
+  # Joins a document the way a browser does: over the
+  # cable's websocket, as a client of the document channel. It holds a
+  # Y::Doc, follows the document, and sends its own edits and presence
+  # through the channel, so the server records, acks, and distributes them
+  # like anyone else's. The process touches neither the pubsub nor the
+  # store. It needs the cable URL and the same way in a browser has: the
+  # channel's name and params, such as a grant the app minted with
+  # record.collaborative_document(name).grant.
+  #
+  #   client = Y::ActionCable::Client.new("wss://example.com/cable",
+  #                                       params: { grant: post.collaborative_document(:body).grant, name: "body" })
+  #   client.on_update { |update, doc, changed| ... } # changed: block ordinals touched
+  #   client.subscribe # connects and returns once the document has arrived
+  #   client.presence = { "user" => { "name" => "Reviewer", "color" => "#7c3aed" } }
+  #   client.edit { |doc| Y::Lexxy.append_paragraph(doc, "hello") }
+  #   client.unsubscribe # waits for acks, clears presence, and closes
+  #
+  # The client sends the URL's own origin as its Origin, which Action Cable
+  # accepts. `headers:` go on the websocket request for anything more: an
+  # Origin when the cable is reached at another address than the site's, or
+  # a token for an ApplicationCable::Connection that requires a login, since
+  # the process has no cookie.
+  #
+  # The client runs as a task of the reactor `subscribe` is called from
+  # when there is one (Falcon, or an Async block), and in a thread of its
+  # own otherwise (Puma, a script). Callbacks run on that reactor; keep
+  # them short. edit and presence= may be called from any thread or fiber.
+  #
+  # Delivery is at least once, as in the JS provider: every update carries
+  # an id and is kept until the server acks it, resent on a timer and after
+  # a reconnect. A dropped socket reconnects with backoff. A rejected
+  # subscription, or a server asking not to reconnect, ends the client.
+  class Client
+    PROTOCOL = "actioncable-v1-json"
+    RESEND = 1     # seconds between retransmits of unacked updates
+    STALE = 15     # seconds without a message before the socket is given up; the server pings every 3
+    RENEW = 15     # seconds between presence renewals; peers drop a client they haven't heard from in 30
+    LEAVE_GRACE = 0.25 # seconds between clearing presence and unsubscribing
+    BACKOFF = [1, 2, 4, 8].freeze # seconds before each reconnect, then the last for good
+    UNACKED = "unsubscribed before the server acked every update"
+
+    # `channel:` and `params:` make the subscription identifier, the way
+    # yrby-client's provider does. `root:` is the root XmlText on_update
+    # reports changed blocks for; nil turns that off.
+    def initialize(url, params:, channel: "Y::DocumentChannel", headers: {}, doc: Y::Doc.new, root: "root", logger: nil) # rubocop:disable Metrics/ParameterLists -- the subscription's parts and the doc's
+      @endpoint = Async::HTTP::Endpoint.parse(url)
+      subscription = { "channel" => channel }.merge(params.transform_keys(&:to_s))
+      @identifier = JSON.generate(subscription)
+      # What logs and errors name the subscription by. The grant opens the
+      # document, so it stays out of them.
+      @label = JSON.generate(subscription.except("grant"))
+      @headers = headers.map { |name, value| [name.to_s.downcase, value.to_s] }
+      @doc = doc
+      @awareness = Y::Awareness.new(doc.client_id)
+      @presence = nil
+      @session = Session.new(doc, @identifier, root: root) do |message|
+        @outgoing << JSON.generate(message)
+      end
+      @logger = logger || Logger.new($stderr)
+      @commands = Thread::Queue.new # from any thread to the reactor
+      @outgoing = Thread::Queue.new # from the reactor to the socket
+      @events = Thread::Queue.new   # from the reactor to whoever waits in subscribe
+      @queued = 0                   # updates handed over but not yet taken up by the reactor
+      @lock = Mutex.new
+      @closed = false
+      @turned_away = false # the server closed the client, not the caller
+    end
+
+    def on_update(&block)
+      @session.on_update { |*args| callback(block, args) }
+      self
+    end
+
+    def on_awareness(&block)
+      @session.on_awareness { |*args| callback(block, args) }
+      self
+    end
+
+    def synced? = @session.synced?
+
+    # True while updates are in flight: handed over, sent, but not yet acked.
+    def pending? = @lock.synchronize { @queued.positive? } || @session.pending?
+
+    # True once the client has left, or the server ended its subscription
+    # (rejected it on a reconnect, or asked it not to reconnect).
+    def closed? = @closed
+
+    # Connect, subscribe, and wait up to `timeout` seconds for the document
+    # to arrive. Raises Y::Error when the subscription is rejected or the
+    # server does not answer in time.
+    def subscribe(timeout: 10)
+      raise Y::Error, "the client was closed" if @closed
+
+      @runner = Async::Task.current? ? Async { run } : Thread.new { Sync { run } }
+      event = @events.pop(timeout: timeout)
+      case event
+      when :synced then self
+      when :rejected then close_and_raise("subscription rejected for #{@label}")
+      when String then close_and_raise("the server closed the connection: #{event}")
+      else close_and_raise("no sync within #{timeout}s for #{@label}")
+      end
+    end
+
+    # Leave: wait up to `timeout` seconds for acks of what is still in
+    # flight, tell the channel, and close the socket. Nothing is delivered
+    # after this. Raises Y::Error when an update was still unacked, since
+    # it may never have reached the server.
+    def unsubscribe(timeout: 5)
+      # The server may have closed the client already, turning it away on a
+      # reconnect. What it never acked is lost all the same, and the first
+      # unsubscribe says so.
+      if @closed
+        lost = @turned_away && pending?
+        @turned_away = false
+        raise Y::Error, UNACKED if lost
+
+        return self
+      end
+
+      @closed = true
+      # From inside a callback the runner is the caller, so it can't be
+      # waited on. It finishes leaving once the callback returns, and logs
+      # an update still unacked instead.
+      inside = Thread.current[:yrby_client_callback].equal?(self)
+      @commands << [:close, [timeout, inside]]
+      return self if inside
+
+      @runner.is_a?(Thread) ? @runner.join(timeout + 5) : @runner&.wait
+      raise Y::Error, UNACKED if pending?
+
+      self
+    rescue Async::Stop
+      self
+    end
+
+    # Edit the document and send what the block changed. Returns the update,
+    # or nil when there's nothing to send. A remote update applied while the
+    # block runs stays out of it (see Y::Doc#edit). Raises Y::Error once the
+    # client is closed, since nothing it edits then would reach anyone.
+    def edit
+      raise Y::Error, "the client was closed" if @closed
+
+      # Only the block can be interrupted, so an update is never taken from
+      # the document and then dropped before it's handed over.
+      Thread.handle_interrupt(Object => :never) do
+        update = @doc.edit { Thread.handle_interrupt(Object => :immediate) { yield @doc } }
+        send_update(update)
+        update
+      end
+    end
+
+    # Show this client to the document's other participants, the way a
+    # browser's presence does. `state` is the hash editors render, such as
+    # { "user" => { "name" => "Reviewer", "color" => "#7c3aed" } }, plus a
+    # caret if you have one. The client renews it every RENEW seconds and
+    # clears it when it leaves.
+    def presence=(state)
+      @presence = JSON.generate(state)
+      send_awareness(@awareness.set_local_state(@presence))
+    end
+
+    private
+
+    attr_reader :doc
+
+    # Hand a document update to the reactor, which keeps it until the server
+    # acks it.
+    def send_update(update)
+      return unless update
+      raise Y::Error, "the client closed before this update was sent" if @closed
+
+      @lock.synchronize { @queued += 1 }
+      @commands << [:update, update]
+    end
+
+    def send_awareness(frame)
+      @commands << [:awareness, frame] if frame && !@closed
+    end
+
+    # Runs a caller's callback, marked so `unsubscribe` knows it is inside one.
+    def callback(block, args)
+      Thread.current[:yrby_client_callback] = self
+      block.call(*args)
+    ensure
+      Thread.current[:yrby_client_callback] = nil
+    end
+
+    def close_and_raise(reason)
+      @closed = true
+      @commands << [:close, [0, false]]
+      raise Y::Error, reason
+    end
+
+    # The whole life of the client, on its reactor: commands from callers
+    # are applied to the session as they arrive, and the socket is kept
+    # connected until the client is closed.
+    def run
+      @task = Async::Task.current
+      pump = @task.async { each_command }
+      renewal = @task.async { renew_presence }
+      attempts = 0
+      until @closed
+        if connection == :stop
+          @closed = @turned_away = true
+          break
+        end
+
+        attempts += 1
+        sleep BACKOFF[[attempts, BACKOFF.size].min - 1]
+      end
+    ensure
+      pump&.stop
+      renewal&.stop
+    end
+
+    # One socket: reader here, a writer task for the outgoing queue, and a
+    # timer that resends unacked updates. Returns :stop when the client
+    # should not reconnect, :dropped otherwise.
+    def connection
+      Async::WebSocket::Client.connect(@endpoint, headers: request_headers, protocols: [PROTOCOL]) do |socket|
+        writer = @task.async { each_outgoing(socket) }
+        timer = @task.async { retransmit }
+        read_loop(socket)
+      ensure
+        writer&.stop
+        timer&.stop
+        @session.dropped
+        @outgoing.clear
+      end
+    rescue Async::Stop
+      raise
+    rescue StandardError => e
+      @logger.warn("Y::ActionCable::Client #{@label}: #{e.class}: #{e.message}")
+      :dropped
+    end
+
+    def read_loop(socket)
+      loop do
+        message = @task.with_timeout(STALE) { socket.read } or return :dropped
+        data = JSON.parse(message.to_str)
+        case @session.receive(data)
+        when :synced then @events << :synced
+        when :rejected
+          @events << :rejected
+          return :stop
+        when :disconnect
+          return :dropped unless data["reconnect"] == false
+
+          # Such as "unauthorized" from a connection that failed to connect.
+          @events << data["reason"].to_s
+          return :stop
+        end
+      end
+    rescue Async::TimeoutError, JSON::ParserError => e
+      @logger.warn("Y::ActionCable::Client #{@label}: #{e.class}: #{e.message}")
+      :dropped
+    end
+
+    # y-protocols peers drop a client whose presence goes quiet for 30
+    # seconds, so a client with presence says it again on a timer.
+    def renew_presence
+      loop do
+        sleep RENEW
+        @session.send_awareness(@awareness.set_local_state(@presence)) if @presence
+      end
+    end
+
+    def retransmit
+      loop do
+        sleep RESEND
+        @session.resend
+      end
+    end
+
+    def each_outgoing(socket)
+      while (text = @outgoing.pop)
+        socket.write(text)
+        socket.flush
+      end
+    end
+
+    def each_command
+      while (command, argument = @commands.pop)
+        case command
+        when :update
+          @session.send_update(argument)
+          @lock.synchronize { @queued -= 1 }
+        when :awareness then @session.send_awareness(argument)
+        when :close then return leave(*argument)
+        end
+      end
+    end
+
+    # Give in-flight updates a moment to be acked, say goodbye, let the
+    # goodbye reach the socket, and stop the reactor task.
+    #
+    # Action Cable runs one connection's messages on a worker pool, so an
+    # unsubscribe sent right behind the presence removal can be handled first,
+    # and the server then drops the removal. The client lets the removal go
+    # out and waits LEAVE_GRACE before unsubscribing. If it is lost anyway,
+    # peers drop the presence after 30 seconds.
+    def leave(timeout, inside_callback)
+      deadline = now + timeout
+      sleep 0.05 while @session.pending? && now < deadline
+      @logger.error(UNACKED) if inside_callback && @session.pending?
+      if @presence
+        @session.send_awareness(@awareness.clear_local_state)
+        flush
+        sleep LEAVE_GRACE
+      end
+      @session.unsubscribe
+      flush
+      @task.stop
+    end
+
+    def flush
+      deadline = now + 1
+      sleep 0.05 until @outgoing.empty? || now > deadline
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # The caller's headers, plus an Origin unless they set one. It's a new
+    # array each time, because async-websocket adds the handshake's key to
+    # the one it's given, and a reconnect has to send only its own key.
+    def request_headers
+      headers = @headers.dup
+      headers.unshift(["origin", origin]) unless headers.any? { |name, _| name == "origin" }
+      headers
+    end
+
+    # Action Cable checks the origin against the host unless forgery
+    # protection is off; the socket's own host is always allowed.
+    def origin
+      "#{@endpoint.secure? ? "https" : "http"}://#{@endpoint.authority}"
+    end
+  end
+end

data/lib/y/agent/tools.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Y
+  class Agent < Collaborator
+    # The RubyLLM tools an agent gives its model. The model names blocks by
+    # the ids read_document lists, and every write goes through the agent's
+    # `edit`, so it reaches people as the model makes it.
+    module Tools
+      # `blocks` as the model reads them: one line per block, "b3 (paragraph): text".
+      def self.listing(agent, blocks)
+        blocks.map do |block|
+          kind = block.attributes.values_at("__type", "__tag").compact.join(" ")
+          "#{agent.block_id(block)} (#{kind}): #{block.text}"
+        end.join("\n")
+      end
+
+      class Tool < RubyLLM::Tool
+        def self.tool_name = name.split("::").last.gsub(/(?<=[a-z])(?=[A-Z])/, "_").downcase
+
+        def initialize(agent)
+          super()
+          @agent = agent
+        end
+
+        private
+
+        def missing(id) = { error: "There's no block #{id}. Call read_document for the blocks there are now." }
+      end
+
+      class ReadDocument < Tool
+        description "Lists the document's blocks in order, one per line, as `id (type): text`. " \
+                    "Name a block by its id in the other tools. Ids stay on their blocks while people edit."
+
+        def execute
+          blocks = @agent.document_blocks
+          blocks.empty? ? "The document is empty." : Tools.listing(@agent, blocks)
+        end
+      end
+
+      class RewriteBlock < Tool
+        description "Replaces the text of one block with `text`, as plain text. " \
+                    "The block's formatting, such as bold or links, is lost."
+        parameter :id, description: "The block's id, such as b3"
+        parameter :text, description: "The block's new text"
+
+        def execute(id:, text:)
+          block = @agent.block(id) or return missing(id)
+          @agent.edit { Lexical.replace_runs(block, text) }
+          "Rewrote #{id}."
+        end
+      end
+
+      class InsertParagraph < Tool
+        description "Adds a paragraph holding `text`, after the block `after`, or at the end of the document."
+        parameter :text, description: "The paragraph's text"
+        parameter :after, description: "The id of the block it goes after. Leave it out to add it at the end.",
+                          required: false
+
+        def execute(text:, after: nil)
+          block = nil
+          @agent.edit do |doc|
+            at = after ? @agent.ordinal(after)&.succ : -1
+            block = Lexical.insert_paragraph(doc, at, text) if at
+          end
+          block ? "Added #{@agent.block_id(block)}." : missing(after)
+        end
+      end
+
+      class DeleteBlock < Tool
+        description "Deletes one block."
+        parameter :id, description: "The block's id, such as b3"
+
+        def execute(id:)
+          deleted = false
+          @agent.edit do |doc|
+            ordinal = @agent.ordinal(id)
+            deleted = Lexical.delete_block(doc, ordinal) if ordinal
+          end
+          deleted ? "Deleted #{id}." : missing(id)
+        end
+      end
+
+      ALL = [ReadDocument, RewriteBlock, InsertParagraph, DeleteBlock].freeze
+    end
+  end
+end

data/lib/y/agent.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "y/collaborator"
+require "yrby/agent/version"
+require "y/agent/tools"
+
+module Y
+  # A collaborator with a model. It joins a document the way Y::Collaborator
+  # does, and when people's typing settles it hands the blocks they changed to
+  # a model through RubyLLM, with tools that read and edit the document:
+  #
+  #   class Proofreader < Y::Agent
+  #     model "gpt-5.6-luna"
+  #     instructions "Fix typos in the blocks people change. Change nothing else."
+  #   end
+  #
+  #   class ProofreadJob < ApplicationJob
+  #     def perform(post) = Proofreader.run(post.collaborative_document(:body), url: "wss://example.com/cable")
+  #   end
+  #
+  # `model`, `instructions`, `tools`, `thinking`, and `temperature` are
+  # RubyLLM::Agent's, and `llm` is the RubyLLM::Agent itself, for any other
+  # setting. Each ask is a fresh chat: the tools read the document as it is
+  # now, so the model needs no history, and a stay of hours never grows one.
+  class Agent < Collaborator
+    class << self
+      # The RubyLLM::Agent this agent's chats come from. A subclass starts
+      # with a copy of its parent's.
+      def llm
+        @llm ||= Class.new(superclass.respond_to?(:llm) ? superclass.llm : RubyLLM::Agent)
+      end
+
+      %i[model instructions tools thinking temperature].each do |setting|
+        define_method(setting) { |*args, **options, &block| llm.public_send(setting, *args, **options, &block) }
+      end
+    end
+
+    def initialize(document, **)
+      super
+      @anchors = {} # block id => anchor
+      @ids = {}     # anchor => block id
+    end
+
+    # Asks the model `message` in a fresh chat with the document tools, and
+    # returns the reply, a RubyLLM::Message. A block gets each chunk as it
+    # streams in. The model's edits go through `edit`, so they reach people
+    # as it makes them.
+    def ask(message, &) = chat.ask(message, &)
+
+    # Asks the model about the blocks people changed. Override it to ask
+    # something else, or to call `ask` only sometimes.
+    def changed(blocks)
+      ask("People changed these blocks:\n\n#{Tools.listing(self, blocks)}") if blocks.any?
+    end
+
+    # The tools the model gets with each ask: Tools::ALL, which read the
+    # document and edit its blocks. Override it to give the model fewer,
+    # such as [Tools::ReadDocument.new(self)] for an agent that only answers.
+    def document_tools = Tools::ALL.map { |tool| tool.new(self) }
+
+    # Live handles to the document's top-level blocks, in order.
+    def document_blocks
+      root = doc.get_xml_text(ROOT)
+      (0...root.size).map { |ordinal| root.xml_text(ordinal) }
+    end
+
+    # A short id for `block`, such as "b3", that the model can name it by.
+    # The id stays on its block for the whole stay, wherever people move it.
+    def block_id(block)
+      anchor = block.anchor
+      @ids[anchor] ||= "b#{@ids.size + 1}".tap { |id| @anchors[id] = anchor }
+    end
+
+    # The live handle to the block `id` names, or nil once it's deleted.
+    def block(id) = (anchor = @anchors[id]) && doc.find(anchor)
+
+    # Where the block `id` names is now, or nil once it's deleted.
+    def ordinal(id) = (anchor = @anchors[id]) && doc.block_at(anchor)
+
+    # A fresh RubyLLM chat with the model, the instructions, and the
+    # document tools. `ask` asks one; take one to set more on it first.
+    def chat = self.class.llm.chat.with_tools(*document_tools)
+  end
+end

data/lib/y/collaborator/lock.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "async"
+require "securerandom"
+
+module Y
+  class Collaborator
+    # The collaborator lock: a key in an ActiveSupport::Cache store holding
+    # this collaborator's token. It is written only if absent, and a task on
+    # the collaborator's reactor renews it every LOCK_TTL / 3 seconds while
+    # the collaborator stays, so a handler waiting on a model call doesn't
+    # let it lapse. It lapses LOCK_TTL seconds after the last renewal, so a
+    # collaborator whose process died doesn't hold the document for good.
+    #
+    # Cache stores have no atomic compare-and-set, so a renewal and a release
+    # read the key and then write or delete it. That leaves one gap: a process
+    # that stalls longer than LOCK_TTL loses the lock, and while it comes
+    # back, it can briefly overlap the collaborator that took over. Its next
+    # renewal sees the other token and it stops.
+    class Lock
+      # One key per document, or per document and `as` when it's given. A
+      # record is named by its GlobalID, so a Person and a Team with the same
+      # id don't share a key.
+      def self.key(document, as)
+        return "yrby:collaborator:#{document.key}" if as.nil?
+
+        "yrby:collaborator:#{document.key}:#{as.respond_to?(:to_global_id) ? as.to_global_id : as}"
+      end
+
+      def initialize(store, key)
+        @store = store
+        @key = key
+        @token = SecureRandom.uuid
+        @held = false
+      end
+
+      # Takes the lock if nobody holds it, and starts renewing it in a task
+      # of the current reactor. `release` stops the task.
+      def take
+        @held = @store.write(@key, @token, unless_exist: true, expires_in: LOCK_TTL) ? true : false
+        @renewer = Async::Task.current.async { renew_until_lost } if @held
+        @held
+      end
+
+      # False once another collaborator holds the lock.
+      def held? = @held
+
+      def release
+        @renewer&.stop
+        @store.delete(@key) if @held && @store.read(@key) == @token
+        @held = false
+      end
+
+      private
+
+      def renew_until_lost
+        while @held
+          sleep LOCK_TTL / 3.0
+          renew
+        end
+      end
+
+      def renew
+        holder = @store.read(@key)
+        return @held = false if holder && holder != @token
+
+        @store.write(@key, @token, expires_in: LOCK_TTL)
+      end
+    end
+  end
+end

data/lib/y/collaborator.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "active_support/duration"
+require "logger"
+require "y/action_cable/client"
+require "y/collaborator/lock"
+
+module Y
+  # Takes part in a document the way a person does. It joins over the cable
+  # with a grant, shows up among the people editing, hears what they write
+  # once their typing settles, and leaves when they do. It has no model of its
+  # own: an AI agent is a collaborator whose `changed` calls one. Subclass it,
+  # and run it from a job:
+  #
+  #   class Reviewer < Y::Collaborator
+  #     def joined
+  #       self.presence = { "user" => { "name" => "Reviewer", "color" => "#7c3aed" } }
+  #       edit { |doc| Y::Lexxy.append_paragraph(doc, "Reviewing.") }
+  #     end
+  #
+  #     def changed(blocks) # live handles to the top-level blocks people changed
+  #       edit { |doc| Y::Lexxy.append_paragraph(doc, "Saw #{blocks.map(&:text).join(" / ")}.") }
+  #     end
+  #   end
+  #
+  #   class ReviewJob < ApplicationJob
+  #     def perform(post) = Reviewer.run(post.collaborative_document(:body), url: "wss://example.com/cable")
+  #   end
+  #
+  # `run` follows the document until nobody else has been present for `idle`
+  # seconds, the collaborator has stayed `max_stay` seconds, or `leave` is
+  # called. It always clears its presence and unsubscribes on the way out. An
+  # error in `joined` or `changed` ends the collaborator and raises out of
+  # `run`; rescue it in the method to carry on.
+  #
+  # Only one collaborator works on a document at a time. Pass `as:` to allow
+  # one per person instead, such as `as: person` for the collaborator a person
+  # brought. The lock lives in `lock:`, Rails.cache by default, so it holds
+  # across processes when the cache is shared. `run` returns :busy without
+  # joining when another collaborator holds it.
+  class Collaborator
+    SETTLE = 1.5          # seconds of quiet before changed sees a burst of edits
+    SETTLE_AT_MOST = 5    # seconds of steady typing before changed sees it anyway
+    IDLE = 120            # seconds with nobody else present before it leaves
+    MAX_STAY = 2 * 60 * 60
+    GONE = 30             # a person whose presence hasn't renewed in this long has left
+    LOCK_TTL = 60         # the lock lapses this long after its last renewal
+    ROOT = "root"         # the root XmlText Lexical and Lexxy edit, whose blocks changed reports
+
+    # Runs a collaborator until it leaves. Returns :left, or :busy when another
+    # collaborator holds the document.
+    def self.run(document, **) = new(document, **).run
+
+    attr_reader :document
+
+    # `document` is a record's collaborative document, such as
+    # post.collaborative_document(:body), which names its own grant and
+    # channel.
+    def initialize(document, url:, headers: {}, idle: IDLE, max_stay: MAX_STAY, as: nil, # rubocop:disable Metrics/ParameterLists -- the document, the connection, and how long to stay
+                   lock: Collaborator.default_lock)
+      @document = document
+      @url = url
+      @headers = headers
+      @idle = idle
+      @max_stay = max_stay
+      @lock = lock && Lock.new(lock, Lock.key(document, as))
+      @changes = Thread::Queue.new
+      @people = Y::Awareness.new
+      @renewals = {} # client id => [clock, when it last moved]
+      @people_lock = Mutex.new
+      @leaving = false
+    end
+
+    # Runs as a task of the caller's reactor when there is one. Otherwise it
+    # starts one on the calling thread, such as a job's, and holds that
+    # thread until the collaborator leaves.
+    def run
+      Sync do
+        next :busy if @lock && !@lock.take
+
+        begin
+          join
+          joined
+          follow
+          @client.unsubscribe # raises when an update was never acked
+          :left
+        ensure
+          leave_after_error
+          @lock&.release
+        end
+      end
+    end
+
+    # How the collaborator appears to the people in the document: the hash
+    # editors render, such as { "user" => { "name" => "Reviewer" } }. nil, the
+    # default, keeps it out of their roster. Set it in `joined`, or in
+    # `initialize` to show up as the collaborator joins, and again to change
+    # it.
+    attr_reader :presence
+
+    def presence=(state)
+      @presence = state
+      @client&.presence = state
+    end
+
+    # Called once the collaborator has joined and the document has loaded.
+    def joined; end
+
+    # Called with live handles (Y::XmlText) to the top-level blocks people
+    # changed, in document order, once their typing has paused for SETTLE
+    # seconds, or after SETTLE_AT_MOST seconds of steady typing. A handle
+    # stays on its block while people edit around it, and writing to one
+    # whose block was deleted raises Y::Error. A change outside the root,
+    # such as to a map, comes right away with an empty list: it's a click,
+    # not typing. The collaborator's own edits never show up here.
+    def changed(blocks); end
+
+    # Edit the document. Returns the update, or nil when nothing changed.
+    # Raises Y::Error once another collaborator holds the document, so a
+    # collaborator that outlived the lock stops writing.
+    def edit(&)
+      raise Y::Error, "another collaborator holds #{@document.key}" unless holding?
+
+      @client.edit(&)
+    end
+
+    # Everyone else in the document, as { client_id => their presence state }.
+    def people
+      own = doc.client_id
+      @people_lock.synchronize do
+        @people.states.select do |id, state|
+          id != own && state && (renewed = @renewals[id]) && now - renewed.last < GONE
+        end
+      end
+    end
+
+    # Leave once `joined` or `changed` returns.
+    def leave = @leaving = true
+
+    def self.default_lock = (Rails.cache if defined?(Rails.cache))
+    def self.default_logger = (defined?(Rails.logger) && Rails.logger) || Logger.new($stderr)
+
+    private
+
+    # The collaborator's copy of the document, for its hooks to read.
+    attr_reader :doc
+
+    def join
+      grant = @document.grant(expires_in: ActiveSupport::Duration.build(@max_stay + LOCK_TTL))
+      params = { grant:, name: @document.name }
+      @doc = Y::Doc.new
+      @client = Y::ActionCable::Client.new(@url, params:, headers: @headers, channel: @document.channel, doc: @doc,
+                                                 root: ROOT, logger: Collaborator.default_logger)
+      @client.on_update { |_update, doc, touched| @changes << anchors(doc, touched || []) }
+      @client.on_awareness { |frame| see(frame) }
+      @client.subscribe
+      @client.presence = @presence if @presence
+    end
+
+    def follow
+      started = now
+      alone_since = nil
+      until @leaving || @client.closed? || now - started > @max_stay || !holding?
+        alone_since = alone?(started) ? alone_since || now : nil
+        break if alone_since && now - alone_since > @idle
+
+        touched = @changes.pop(timeout: 1)
+        next unless touched
+
+        touched = settle(touched) unless touched.empty?
+        changed(blocks(touched)) if holding?
+      end
+    end
+
+    # Unsubscribe on the way out of an error, which says more than an unacked
+    # update would. After a normal leave this does nothing.
+    def leave_after_error
+      @client&.unsubscribe
+    rescue Y::Error => e
+      Collaborator.default_logger.error(e.message)
+    end
+
+    def holding? = @lock.nil? || @lock.held?
+
+    # People already in the document announce themselves only when they next
+    # renew their presence, so the collaborator can't know it is alone until one
+    # renewal window has passed since it joined.
+    def alone?(started) = now - started > Y::ActionCable::Client::RENEW && people.empty?
+
+    # Anchors to the blocks an update touched, taken as it arrives: a later
+    # update that adds or removes a block moves an ordinal, not an anchor.
+    def anchors(doc, ordinals)
+      root = doc.get_xml_text(ROOT) unless ordinals.empty?
+      ordinals.filter_map { |ordinal| root.xml_text(ordinal)&.anchor }
+    end
+
+    # Waits for a burst of edits to pause, or for SETTLE_AT_MOST seconds of
+    # steady typing, and returns the anchors of every block it touched.
+    def settle(anchors)
+      deadline = now + SETTLE_AT_MOST
+      while (wait = [SETTLE, deadline - now].min).positive? && (more = @changes.pop(timeout: wait))
+        anchors |= more
+      end
+      anchors
+    end
+
+    # Live handles to the blocks, in document order, leaving out any that
+    # were deleted while the edits settled.
+    def blocks(anchors)
+      anchors.filter_map { |anchor| (ordinal = doc.block_at(anchor)) && [ordinal, doc.find(anchor)] }
+             .sort_by(&:first).map(&:last)
+    end
+
+    # Presence frames from everyone, this collaborator's own included. A
+    # person's editor renews their presence every 15 seconds, so a clock that
+    # stops moving means they left without saying so.
+    def see(frame)
+      @people_lock.synchronize do
+        @people.apply_update(frame)
+        @people.clocks.each do |id, clock|
+          @renewals[id] = [clock, now] unless @renewals[id]&.first == clock
+        end
+      end
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/yrby/agent/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Yrby
+  module Agent
+    VERSION = "0.1.0.alpha1"
+  end
+end

data/lib/yrby-agent.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `Bundler.require` loads it automatically.
+require "y/agent"

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: yrby-agent
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha1
+platform: ruby
+authors:
+- JP Camara
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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'
+- !ruby/object:Gem::Dependency
+  name: yrby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: yrby-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Y::ActionCable::Client joins a yrby document over Action Cable the way
+  a browser does. Y::Collaborator takes part in a document the way a person does.
+  Y::Agent is a collaborator that hands what people changed to a model through RubyLLM,
+  with tools that read the document and edit its blocks live.
+email:
+- johnpcamara@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG-agent.md
+- LICENSE
+- lib/y/action_cable/client.rb
+- lib/y/action_cable/client/outbox.rb
+- lib/y/action_cable/client/session.rb
+- lib/y/agent.rb
+- lib/y/agent/tools.rb
+- lib/y/collaborator.rb
+- lib/y/collaborator/lock.rb
+- lib/yrby-agent.rb
+- lib/yrby/agent/version.rb
+homepage: https://github.com/jpcamara/yrby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/jpcamara/yrby
+  changelog_uri: https://github.com/jpcamara/yrby/blob/main/CHANGELOG-agent.md
+  bug_tracker_uri: https://github.com/jpcamara/yrby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby processes and AI agents that edit yrby documents alongside people
+test_files: []