robot_lab-cyborg 0.2.7

data/examples/05_listening_and_duplex.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Always-on listening + the duplex boundary.
+#
+# Earlier demos had the network ask the human questions. Here nobody asks the
+# human anything — yet a listening Cyborg still hears them. `converse` puts the
+# Cyborg in always-on listen mode: a background reader captures whatever the
+# human types and routes it to peers by @mention (no mention => broadcast). The
+# peers' replies come *back* to the human's channel automatically, because a
+# Cyborg delivers inbound bus traffic to its channel (the output half of the
+# duplex). Neither direction is wired by this demo — both live in the library.
+#
+# The human's "keystrokes" are scripted here (a StringIO) so the demo runs
+# deterministically; in a real session this is your live terminal.
+#
+#   ruby examples/05_listening_and_duplex.rb
+
+require "stringio"
+
+# Prefer the local robot_lab checkout (with the latest fixes: serve/respond_to_tasks)
+# over any installed gem, so the demo runs from a fresh monorepo checkout.
+core_lib = File.expand_path("../../robot_lab/lib", __dir__)
+$LOAD_PATH.unshift(core_lib) if File.directory?(core_lib)
+
+require "robot_lab"
+require_relative "../lib/robot_lab/cyborg"
+
+Cyborg   = RobotLab::Cyborg
+Terminal = RobotLab::Cyborg::Channel::Terminal
+
+bus = TypedBus::MessageBus.new
+
+# What the human types, unprompted, over time.
+keystrokes = StringIO.new(<<~INPUT)
+  @ops what's the current status?
+  heads up everyone, deploying at 15:00
+INPUT
+
+you = Cyborg.new(name: "you", bus: bus, channel: Terminal.new(input: keystrokes, output: $stdout, name: "network"))
+
+# Two key-free robot peers that serve bus tasks (respond_to_tasks — no LLM call),
+# cooperating on the same bus as the human.
+RobotLab.build(name: "ops",    bus: bus).respond_to_tasks { |_m| "all systems green" }
+RobotLab.build(name: "deploy", bus: bus).respond_to_tasks { |_m| "roger, holding for go/no-go" }
+
+# Start listening: unprompted human input is now routed by @mention; replies come
+# back on the channel on their own.
+you.converse(peers: %w[ops deploy])
+
+# Let the background reader consume the scripted input and the replies land.
+sleep 1.0
+you.unlisten

data/lib/robot_lab/cyborg/channel.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Cyborg
+    # A message crossing the human boundary, in either direction.
+    #
+    # Outbound (network -> human): the Interviewer/Cyborg stamps +content+ and a
+    # +kind+ (:question for a prompt awaiting an answer, :message/:notice for
+    # everything else) plus, when known, the +sender+ it is on behalf of.
+    # Inbound (human -> network): the Channel fills +content+ and, when the
+    # transport can correlate a reply to a specific question (a Slack thread, an
+    # email In-Reply-To), sets +in_reply_to+ to that question's id. A dumb
+    # transport (a bare terminal) leaves +in_reply_to+ nil.
+    #
+    # @!attribute id           [Integer, nil] question id this message carries/answers
+    # @!attribute content      [String] the human-readable payload
+    # @!attribute in_reply_to  [Integer, nil] id of the question an inbound answer replies to
+    # @!attribute sender       [String, nil] who the message is from/for (for display)
+    # @!attribute kind         [Symbol] :question | :answer | :message | :notice
+    # @!attribute at           [Time] when the message was created
+    ChannelMessage = Data.define(:id, :content, :in_reply_to, :sender, :kind, :at) do
+      def initialize(content:, id: nil, in_reply_to: nil, sender: nil, kind: :message, at: nil)
+        super(id:, content: content.to_s, in_reply_to:, sender:, kind:, at: at || Time.now)
+      end
+
+      # @return [Boolean] true when this is a prompt the human is expected to answer
+      def question? = kind == :question
+    end
+
+    # A Channel is the *means* by which a Cyborg reaches its human: a dumb,
+    # bidirectional pipe. It knows how to {#deliver} a message *out* to the human
+    # and to surface messages the human sends *in* — nothing more. It has no
+    # concept of a "question" or an "answer"; correlating replies to questions is
+    # the {Interviewer}'s job (the *process*), not the channel's.
+    #
+    # The same small API backs a terminal today and Slack, email, SMS, or a web
+    # form later — each is just a different Channel. Because the boundary is the
+    # injected channel, +$stdin+/+$stdout+ live *only* inside {Terminal}; nothing
+    # else in the Cyborg assumes a terminal.
+    #
+    # A channel that can tie an inbound answer back to the question it answers
+    # (Slack threads, email In-Reply-To) reports {#correlates?} true; the
+    # Interviewer then lets several questions be outstanding at once. A dumb
+    # channel reports false, and the Interviewer serializes questions — one on the
+    # wire at a time — so an answer is never mis-attributed.
+    #
+    # @abstract Subclass and implement {#deliver} and {#receive}.
+    class Channel
+      # Send a message out to the human (network -> human).
+      #
+      # @param message [ChannelMessage] the outbound message
+      # @return [ChannelMessage] the delivered message
+      def deliver(message)
+        raise NotImplementedError, "#{self.class} must implement #deliver"
+      end
+
+      # Return the next message from the human (human -> network), waiting up to
+      # +timeout+ seconds. Returns nil when nothing arrives in that window — nil
+      # is transient ("not yet"), not "closed"; the Interviewer keeps polling.
+      # Implementations MUST honor +timeout+ so the consumer can stay responsive
+      # to shutdown and question expiry.
+      #
+      # @param timeout [Numeric, nil] seconds to wait; nil = block indefinitely
+      # @return [ChannelMessage, nil]
+      def receive(timeout: nil)
+        raise NotImplementedError, "#{self.class} must implement #receive"
+      end
+
+      # Whether the transport tags inbound answers with the question they reply to
+      # (sets +in_reply_to+). Dumb channels return false and get one-question-at-
+      # a-time serialization from the Interviewer.
+      #
+      # @return [Boolean]
+      def correlates? = false
+
+      # Release any resources. Default: no-op.
+      def close; end
+
+      # Terminal-backed channel: the human is at a keyboard. This is the only
+      # place +$stdin+/+$stdout+ are assumed; inject StringIO in tests.
+      class Terminal < Channel
+        # @param input [IO] stream to read the human's messages from
+        # @param output [IO] stream to write messages to the human on
+        # @param name [String] label shown when a message has no explicit sender
+        def initialize(input: $stdin, output: $stdout, name: "cyborg")
+          @input = input
+          @output = output
+          @name = name
+          @write_mutex = Mutex.new
+          super()
+        end
+
+        # Print the message. A :question is followed by a "> " prompt; other kinds
+        # (inbound peer messages, notices) are not, so unsolicited traffic does not
+        # spam the input cursor. Synchronized so concurrent deliveries (a question
+        # and an inbound peer message) never interleave on screen.
+        def deliver(message)
+          @write_mutex.synchronize do
+            @output.puts "\n[#{message.sender || @name}] #{message.content}"
+            @output.print "> " if message.question?
+            @output.flush
+          end
+          message
+        end
+
+        # Read a line, honoring +timeout+ so the consumer can poll for shutdown and
+        # expiry. Uses IO.select on a real IO; a non-selectable stream (StringIO in
+        # tests) returns immediately from #gets, which is equally responsive. A nil
+        # line means EOF. A bare terminal carries no correlation, so +in_reply_to+
+        # stays nil.
+        def receive(timeout: nil)
+          return nil if timeout && selectable? && !@input.wait_readable(timeout)
+          return nil unless (line = @input.gets)
+
+          ChannelMessage.new(content: line.chomp, kind: :answer)
+        rescue IOError
+          nil
+        end
+
+        private
+
+        # Only a real IO can be waited on for readiness; a StringIO (tests) is not,
+        # and #gets returns from it immediately anyway.
+        def selectable? = @input.is_a?(IO)
+      end
+
+      # Scripted channel: canned human answers for tests, automation, and replay.
+      #
+      # Each delivered question is paired with the next scripted answer *at
+      # delivery time* and stamped with that question's id, so correlation is exact
+      # and deterministic (hence {#correlates?} is true). When the script runs dry,
+      # delivered questions simply go unanswered — modeling a human who never
+      # replies — and the Interviewer's timeout takes over. Every question shown is
+      # recorded in {#asked} so tests can assert on what the human saw.
+      class Scripted < Channel
+        # @return [Array<String>] questions delivered so far, in order
+        attr_reader :asked
+
+        # @param answers [Array<String>, String] answers to return, in order
+        def initialize(answers = [])
+          @answers = Array(answers).dup
+          @asked   = []
+          @inbox   = Thread::Queue.new
+          @mutex   = Mutex.new
+          super()
+        end
+
+        def correlates? = true
+
+        def deliver(message)
+          # A scripted human answers questions; notices and inbound peer messages
+          # are shown, not answered (and don't consume a scripted answer).
+          return message unless message.question?
+
+          @mutex.synchronize do
+            @asked << message.content
+            unless @answers.empty?
+              @inbox.push(ChannelMessage.new(content: @answers.shift, in_reply_to: message.id, kind: :answer))
+            end
+          end
+          message
+        end
+
+        def receive(timeout: nil)
+          timeout ? @inbox.pop(timeout: timeout) : @inbox.pop
+        end
+
+        def close
+          @inbox.close
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/cyborg/conversation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Cyborg
+    # A Conversation turns a listening {Cyborg} into an interactive participant in
+    # a multi-peer network. It reads the human's unprompted messages and routes
+    # each by @mention:
+    #
+    # - "@name ..." (one or more mentions, anywhere in the line) fans the whole
+    #   message out to every mentioned peer.
+    # - a line with no mention is a broadcast to every known peer.
+    #
+    # Replies come *back* to the human's channel automatically — the Cyborg
+    # delivers inbound bus traffic to the channel (the output half of the duplex)
+    # — so a Conversation only has to handle the human -> network direction.
+    #
+    # The addressing convention that used to live in example code now lives here,
+    # so every channel (terminal, Slack, ...) gets it for free.
+    #
+    # @example
+    #   you  = RobotLab::Cyborg.new(name: "you", bus: bus)
+    #   chat = RobotLab::Cyborg::Conversation.new(cyborg: you, peers: %w[analyst scribe]).start
+    #   # human types "hey @analyst and @scribe: status?" -> both are tasked
+    class Conversation
+      MENTION = /@(\w+)/ # every @name in a message, in order of first appearance
+
+      # @return [Array<String>] names this conversation can address
+      attr_reader :peers
+
+      # @param cyborg [Cyborg] the human peer whose channel/bus this drives
+      # @param peers [Array<String, Symbol>] known addressable member names
+      def initialize(cyborg:, peers: [])
+        @cyborg = cyborg
+        @peers  = peers.map(&:to_s)
+      end
+
+      # Add an addressable peer by name.
+      # @return [self]
+      def add_peer(name)
+        @peers << name.to_s unless @peers.include?(name.to_s)
+        self
+      end
+
+      # Begin routing the human's unprompted input by @mention (always-on listen).
+      # Idempotent.
+      # @return [self]
+      def start
+        @cyborg.on_human { |message| route(message.content) }
+        @cyborg.listen
+        self
+      end
+
+      # Stop routing (winds down listening).
+      # @return [self]
+      def stop
+        @cyborg.unlisten
+        self
+      end
+
+      # Route one line of human input onto the bus. Unknown mentions are reported
+      # back to the human; a line mentioning only unknown peers is not sent.
+      #
+      # @param line [String]
+      # @return [Array<String>] the peers the message was sent to
+      def route(line)
+        line = line.to_s.strip
+        return [] if line.empty?
+
+        mentioned  = line.scan(MENTION).flatten.uniq
+        recipients = recipients_for(mentioned)
+        return [] if recipients.nil?
+
+        recipients.each { |name| @cyborg.assign(to: name, task: line) }
+        recipients
+      end
+
+      private
+
+      # Resolve the recipients for a line, or nil when there is nothing to send
+      # (after telling the human why).
+      def recipients_for(mentioned)
+        unknown = mentioned - @peers
+        @cyborg.tell("No such peer: #{unknown.map { |n| "@#{n}" }.join(', ')}") unless unknown.empty?
+
+        recipients = mentioned.empty? ? @peers : (mentioned & @peers)
+        return recipients unless recipients.empty?
+
+        @cyborg.tell("No known peer to address. Known: #{roster}.")
+        nil
+      end
+
+      def roster
+        @peers.map { |name| "@#{name}" }.join(", ")
+      end
+    end
+  end
+end

data/lib/robot_lab/cyborg/interviewer.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Cyborg
+    # An Interviewer is the *process* of conducting a human interaction over a
+    # {Channel} (the *means*). The channel moves opaque messages; the Interviewer
+    # gives them meaning — it tracks which questions are outstanding, decides
+    # which inbound message answers which question, and surfaces the rest as
+    # unsolicited human initiative.
+    #
+    # Asking is *always asynchronous*, whatever the channel. A human's answer may
+    # be the very next message, may arrive several messages later (after they say
+    # other things first), or may never come at all. So {#ask} does not block for
+    # an answer — it delivers the question and returns a {Question} you can wait
+    # on, with a timeout, whenever you are ready. A background consumer drains the
+    # channel and resolves questions as their answers arrive.
+    #
+    # Correlation:
+    # - On a channel that {Channel#correlates?} (Slack threads, email), any number
+    #   of questions may be outstanding; each inbound answer names the question it
+    #   replies to via +in_reply_to+.
+    # - On a dumb channel (a bare terminal) answers carry no correlation, so the
+    #   Interviewer serializes: only ONE question is on the wire at a time, and an
+    #   answer resolves that active question. Extra asks queue and are delivered as
+    #   the active one resolves or expires. This makes mis-attribution impossible.
+    class Interviewer
+      # How often the background consumer wakes to poll the channel.
+      POLL_INTERVAL = 0.05
+
+      # @return [StandardError, nil] last error a handler/channel raised in the consumer
+      attr_reader :last_error
+
+      # @param channel [Channel] the injected means of reaching the human
+      # @param default_timeout [Numeric, nil] default seconds {#ask_and_wait} waits
+      def initialize(channel:, default_timeout: nil)
+        @channel         = channel
+        @default_timeout = default_timeout
+        @outstanding     = {}
+        @pending         = []   # registered-but-not-yet-delivered (serialized channels)
+        @active_id       = nil  # the one delivered question awaiting an answer (serialized)
+        @counter         = 0
+        @mutex           = Mutex.new
+        @on_initiative   = nil
+        @consumer        = nil
+        @running         = false
+        @closing         = false
+        @listening       = false
+        @last_error      = nil
+      end
+
+      # Ask the human a question, asynchronously.
+      #
+      # @param content [String] the question text
+      # @param choices [Array<String>, nil] optional multiple-choice options
+      # @param default [String, nil] value to use when the human answers empty
+      # @return [Question] a handle whose {Question#answer} waits for the reply
+      def ask(content, choices: nil, default: nil)
+        question = register(content, choices, default)
+        if @channel.correlates?
+          @channel.deliver(question_message(question))
+        else
+          @mutex.synchronize { @pending << question }
+          pump_pending
+        end
+        ensure_consumer
+        question
+      end
+
+      # Ask and block for the answer — the synchronous boundary a pipeline step
+      # needs. Returns the human's answer, or the default (nil when none) if no
+      # answer arrives within +timeout+.
+      #
+      # @param content [String] the question text
+      # @param timeout [Numeric, nil] seconds to wait; nil = wait indefinitely
+      # @return [String, nil]
+      def ask_and_wait(content, timeout: @default_timeout, **)
+        ask(content, **).answer(timeout: timeout)
+      end
+
+      # Register a handler for inbound messages that answer no outstanding
+      # question — the human acting as a peer (raising something unprompted).
+      #
+      # @yield [ChannelMessage] the unsolicited message
+      # @return [self]
+      def on_initiative(&block)
+        @on_initiative = block
+        self
+      end
+
+      # Keep the consumer alive even with no questions outstanding, so unsolicited
+      # human input is captured as initiative (human -> network). Idempotent.
+      #
+      # @return [self]
+      def listen
+        @mutex.synchronize { @listening = true }
+        ensure_consumer
+        self
+      end
+
+      # Stop always-on listening. The consumer winds down once nothing is
+      # outstanding. Does not close the channel.
+      #
+      # @return [self]
+      def unlisten
+        @mutex.synchronize { @listening = false }
+        self
+      end
+
+      # Stop the background consumer and close the channel.
+      # @return [void]
+      def close
+        @mutex.synchronize { @closing = true }
+        @channel.close
+        @consumer&.join(1)
+        @consumer = nil
+      end
+
+      # Remove a question from the outstanding set (so a later, unrelated answer
+      # cannot claim it) and advance the serialized queue. Called by
+      # {Question#answer} on timeout.
+      #
+      # @param question [Question]
+      # @return [void]
+      def expire(question)
+        @mutex.synchronize { @outstanding.delete(question.id) }
+        release_active(question.id)
+      end
+
+      private
+
+      def register(content, choices, default)
+        @mutex.synchronize do
+          id = (@counter += 1)
+          @outstanding[id] = Question.new(
+            id: id, content: content, choices: choices, default: default, interviewer: self
+          )
+        end
+      end
+
+      def question_message(question)
+        ChannelMessage.new(id: question.id, content: render(question), kind: :question)
+      end
+
+      # Deliver the next queued question if nothing is currently on the wire.
+      # (Serialized/non-correlating channels only.)
+      def pump_pending
+        question = @mutex.synchronize do
+          next nil if @active_id || @pending.empty?
+
+          nxt = @pending.shift
+          @active_id = nxt.id
+          nxt
+        end
+        @channel.deliver(question_message(question)) if question
+      end
+
+      # If +id+ was the active question, clear it and deliver the next queued one.
+      def release_active(id)
+        advanced = @mutex.synchronize do
+          next false unless @active_id == id
+
+          @active_id = nil
+          true
+        end
+        pump_pending if advanced
+      end
+
+      # Lazily start the single consumer thread. It runs only while questions are
+      # outstanding, so it stops on its own once every ask has been answered or has
+      # timed out; the next {#ask} restarts it. (For always-on listening — capturing
+      # idle human initiative — a Cyborg keeps a question-free consumer alive; see
+      # Cyborg#listen.) Both start and stop flip +@running+ under the mutex, so a
+      # restart never races a shutdown.
+      def ensure_consumer
+        @mutex.synchronize do
+          return if @running
+
+          @running  = true
+          @consumer = Thread.new { consume }
+        end
+      end
+
+      # Drain the channel until there is nothing to serve. A handler or channel
+      # error must never kill the consumer (that would wedge every future ask), so
+      # errors are caught, recorded, and the loop continues. The +ensure+ resets
+      # +@running+ on any exit so {#ensure_consumer} can always restart.
+      def consume
+        until stop?
+          begin
+            message = @channel.receive(timeout: POLL_INTERVAL)
+            message ? dispatch(message) : sleep(POLL_INTERVAL)
+          rescue ClosedQueueError
+            break
+          rescue StandardError => e
+            @last_error = e
+          end
+        end
+      ensure
+        @mutex.synchronize { @running = false }
+      end
+
+      # Decide, atomically, whether the consumer should stop: when closing, or when
+      # nothing is outstanding and it is not in always-on listen mode.
+      def stop?
+        @mutex.synchronize do
+          next true if @closing
+          next false if @listening
+
+          @outstanding.empty?.tap { |idle| @running = false if idle }
+        end
+      end
+
+      # Resolve the question this message answers, or route it as initiative.
+      def dispatch(message)
+        question = claim(message)
+        if question
+          question.resolve(interpret(message.content, question))
+          release_active(question.id)
+        else
+          @on_initiative&.call(message)
+        end
+      end
+
+      # The outstanding question this message answers: an explicit +in_reply_to+
+      # when the channel provides one, otherwise the single active (serialized)
+      # question. A correlated id naming no outstanding question, or an answer with
+      # no active question, matches nothing (the message becomes initiative).
+      def claim(message)
+        reply_to = message.in_reply_to
+        @mutex.synchronize do
+          id = if reply_to && @outstanding.key?(reply_to)
+                 reply_to
+               elsif reply_to.nil? && @active_id && @outstanding.key?(@active_id)
+                 @active_id
+               end
+          id ? @outstanding.delete(id) : nil
+        end
+      end
+
+      # Turn a raw human reply into an answer: fall back to the default on an empty
+      # reply, and map a bare number to its choice. Always returns a String so a
+      # genuine empty answer is never confused with a timeout (which is nil).
+      def interpret(text, question)
+        default = question.default
+        text = default if empty_answer?(text) && !default.nil?
+        resolve_choice(text.to_s, question.choices)
+      end
+
+      def empty_answer?(text)
+        text.nil? || text.empty?
+      end
+
+      def render(question)
+        return question.content unless question.choices&.any?
+
+        numbered = question.choices.each_with_index.map { |choice, i| "  #{i + 1}. #{choice}" }
+        [question.content, *numbered].join("\n")
+      end
+
+      def resolve_choice(text, choices)
+        return text unless choices&.any?
+        return text unless text.match?(/\A\d+\z/)
+
+        index = text.to_i - 1
+        index.between?(0, choices.size - 1) ? choices[index] : text
+      end
+    end
+
+    # A pending question handed to the human. It carries the question's text and
+    # options and acts as a one-shot future for the human's answer.
+    class Question
+      # @return [Integer] correlation id, unique within an Interviewer
+      attr_reader :id
+      # @return [String] the question text
+      attr_reader :content
+      # @return [Array<String>, nil] multiple-choice options, if any
+      attr_reader :choices
+      # @return [String, nil] value used when the human answers empty / times out
+      attr_reader :default
+
+      def initialize(id:, content:, choices: nil, default: nil, interviewer: nil)
+        @id          = id
+        @content     = content
+        @choices     = choices
+        @default     = default
+        @interviewer = interviewer
+        @mailbox     = Thread::Queue.new
+      end
+
+      # Deliver the human's (already interpreted) answer. Called by the
+      # Interviewer's consumer.
+      #
+      # @param answer [String]
+      # @return [void]
+      def resolve(answer)
+        @mailbox.push(answer)
+      end
+
+      # Block up to +timeout+ seconds for the human's answer. On timeout, expire
+      # the question and return the default (nil when there is none) — this is how
+      # "the human may never answer" surfaces to the caller.
+      #
+      # @param timeout [Numeric, nil] seconds to wait; nil = wait indefinitely
+      # @return [String, nil]
+      def answer(timeout: nil)
+        result = timeout ? @mailbox.pop(timeout: timeout) : @mailbox.pop
+        return result unless result.nil?
+
+        @interviewer&.expire(self)
+        @default
+      end
+    end
+  end
+end

data/lib/robot_lab/cyborg/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # RobotLab::Cyborg is a class (a human peer worker), so its VERSION and the
+  # nested helper classes hang off the class itself rather than a module.
+  class Cyborg
+    VERSION = "0.2.7"
+  end
+end