robot_lab 0.0.9 → 0.0.12

data/examples/30_ractor_network.rb

@@ -0,0 +1,256 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 30: Ractor Network Scheduler
+#
+# Demonstrates Track 2 of RobotLab's Ractor parallelism: running a
+# multi-robot pipeline under RactorNetworkScheduler, which dispatches
+# independent tasks in parallel waves and respects depends_on ordering.
+#
+# Concepts covered:
+#   - Network.new(parallel_mode: :ractor) — opt the network into Ractor dispatch
+#   - Dependency waves                    — independent tasks run concurrently,
+#                                           dependent tasks wait for their wave
+#   - RobotSpec                           — frozen, Ractor-shareable robot descriptor
+#   - RactorNetworkScheduler              — direct use for testing / custom wiring
+#   - Result Hash                         — run_pipeline returns { name => result }
+#
+# Part 1 — simulated scheduler, no API key needed.
+#   Overrides execute_spec with a sleep-based stub so the wave ordering and
+#   timing characteristics are visible without real LLM calls.
+#
+# Part 2 — Network.new(parallel_mode: :ractor) API walkthrough.
+#   Shows how to configure the network and inspects the dependency graph.
+#   No run() call is made, so no API key is required.
+#
+# Part 3 — live LLM run (optional).
+#   Executes automatically when ANTHROPIC_API_KEY is set.
+#
+# Usage:
+#   bundle exec ruby examples/30_ractor_network.rb              # Parts 1 & 2
+#   ANTHROPIC_API_KEY=key ruby examples/30_ractor_network.rb    # Parts 1, 2 & 3
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+puts "=" * 62
+puts "Example 30: Ractor Network Scheduler"
+puts "=" * 62
+puts
+
+DIVIDER = ("─" * 54).freeze
+
+# =============================================================================
+# Part 1: Simulated scheduler — dependency waves and timing
+# =============================================================================
+#
+# Pipeline topology:
+#
+#   headline_finder  ─────────────────────────────────┐
+#                                                      ├──► report_writer
+#   background_brief ─────────────────────────────────┤
+#                                                      │
+#   fact_checker     ─────────────────────────────────┘
+#
+# Wave 1 — headline_finder, background_brief, fact_checker: parallel (none depend on each other)
+# Wave 2 — report_writer: sequential (depends on all three)
+#
+# Simulated latencies (seconds):
+LATENCIES = {
+  "headline_finder"   => 0.60,
+  "background_brief"  => 0.50,
+  "fact_checker"      => 0.40,
+  "report_writer"     => 0.70
+}.freeze
+#
+# Expected times:
+#   Parallel   — wave1 = max(0.60, 0.50, 0.40) = 0.60s
+#                wave2 = 0.70s
+#                total ≈ 1.30s
+#
+#   Sequential — 0.60 + 0.50 + 0.40 + 0.70 = 2.20s
+#
+#   Speedup    ≈ 1.7×
+
+puts "── Part 1: Simulated parallel run (no API key) ───────────"
+puts
+
+# SimulatedScheduler overrides execute_spec so that instead of
+# constructing a real Robot and calling the LLM, it just sleeps for
+# the robot's configured latency and returns a synthetic result string.
+# All dependency-ordering and wave-dispatch logic is inherited unchanged.
+class SimulatedScheduler < RobotLab::RactorNetworkScheduler
+  private
+
+  def execute_spec(spec, _message)
+    delay = LATENCIES[spec.name] || 0.30
+    sleep delay
+    "#{spec.name}: completed after #{delay}s".freeze
+  end
+end
+
+# Build RobotSpec objects directly.
+# (Normally Network#run_with_ractor_scheduler builds these from Task wrappers.)
+def make_spec(name, deps = :none)
+  spec = RobotLab::RobotSpec.new(
+    name:          name.freeze,
+    template:      nil,
+    system_prompt: "You are the #{name} robot.".freeze,
+    config_hash:   {}.freeze
+  )
+  { spec: spec, depends_on: deps }
+end
+
+specs_with_deps = [
+  make_spec("headline_finder"),
+  make_spec("background_brief"),
+  make_spec("fact_checker"),
+  make_spec("report_writer", ["headline_finder", "background_brief", "fact_checker"])
+]
+
+memory    = RobotLab::Memory.new
+scheduler = SimulatedScheduler.new(memory: memory)
+
+topic = "artificial intelligence regulation in 2025"
+
+t0      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+results = scheduler.run_pipeline(specs_with_deps, message: topic)
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+scheduler.shutdown
+
+sequential_total = LATENCIES.values.sum
+
+puts "  Pipeline topology:"
+puts "    Wave 1 (parallel): headline_finder · background_brief · fact_checker"
+puts "    Wave 2 (sequential): report_writer  ← waits for all three"
+puts
+
+puts "  Results (Hash { name => result_string }):"
+results.each { |name, val| puts "    \"#{name}\" => #{val.inspect}" }
+puts
+
+puts "  Wall time:         #{"%.3f" % elapsed}s"
+puts "  Sequential equiv:  #{"%.3f" % sequential_total}s  (#{LATENCIES.map { |n, d| "#{n}=#{d}" }.join(' + ')})"
+puts "  Speedup:           #{(sequential_total / elapsed).round(1)}×"
+puts
+
+# =============================================================================
+# Part 2: Network.new(parallel_mode: :ractor) API
+# =============================================================================
+
+puts "── Part 2: Network.new(parallel_mode: :ractor) ───────────"
+puts
+
+# When parallel_mode: :ractor is set on a Network, network.run(message:)
+# routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
+# The default mode is :async (unchanged SimpleFlow behavior).
+
+model = "claude-haiku-4-5-20251001"
+
+network = RobotLab::Network.new(name: "research_pipeline", parallel_mode: :ractor) do
+  task :headline_finder,  RobotLab.build(name: "headline_finder",
+                                          system_prompt: "Find the 3 most relevant news headlines. Be concise.",
+                                          model: model),
+       depends_on: :none
+
+  task :background_brief, RobotLab.build(name: "background_brief",
+                                          system_prompt: "Provide a 2-sentence background on the topic.",
+                                          model: model),
+       depends_on: :none
+
+  task :fact_checker,     RobotLab.build(name: "fact_checker",
+                                          system_prompt: "List 3 verifiable facts about the topic.",
+                                          model: model),
+       depends_on: :none
+
+  task :report_writer,    RobotLab.build(name: "report_writer",
+                                          system_prompt: "Synthesize the provided context into a 3-sentence report.",
+                                          model: model),
+       depends_on: ["headline_finder", "background_brief", "fact_checker"]
+end
+
+puts "  network.name          => #{network.name.inspect}"
+puts "  network.parallel_mode => #{network.parallel_mode.inspect}"
+puts
+puts "  Dependency graph (from network.pipeline.step_dependencies):"
+
+network.pipeline.step_dependencies.each do |step, deps|
+  dep_str = deps.empty? ? "(entry point — Wave 1)" : "depends on: #{deps.join(', ')}"
+  puts "    :#{step.to_s.ljust(18)}  #{dep_str}"
+end
+puts
+puts "  When network.run(message: ...) is called:"
+puts "    • RactorNetworkScheduler is created with the network's memory"
+puts "    • Each task is converted to a frozen RobotSpec"
+puts "    • Wave 1 tasks are dispatched concurrently (Thread per task)"
+puts "    • Each Thread submits a RactorJob to the worker queue"
+puts "    • A Ractor worker pops the job, constructs a fresh Robot from the"
+puts "      spec, calls robot.run(message), and returns the frozen result"
+puts "    • Wave 2 begins once all Wave 1 results are available"
+puts "    • Return value is a Hash { robot_name => result_string }"
+puts
+
+# =============================================================================
+# Part 3: Live LLM run (optional — requires ANTHROPIC_API_KEY)
+# =============================================================================
+
+unless ENV["ANTHROPIC_API_KEY"]
+  puts "── Part 3: Live LLM run ──────────────────────────────────"
+  puts "   Set ANTHROPIC_API_KEY to run the real pipeline."
+  puts "   Expected behavior: headline_finder, background_brief, and"
+  puts "   fact_checker run in parallel; report_writer follows."
+  puts
+  puts "=" * 62
+  puts "Example 30 complete."
+  puts "=" * 62
+  exit 0
+end
+
+puts "── Part 3: Live LLM run (ANTHROPIC_API_KEY detected) ─────"
+puts
+
+puts "  Running 4-robot research pipeline on:"
+puts "  \"#{topic}\""
+puts
+puts "  Wave 1 (parallel): headline_finder · background_brief · fact_checker"
+puts "  Wave 2:            report_writer"
+puts
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+begin
+  result = network.run(message: topic)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+  puts "  Completed in #{"%.2f" % elapsed}s"
+  puts
+  puts "  Results:"
+  result.each do |name, text|
+    snippet = text.to_s.strip.lines.first.to_s.strip
+    puts "    [#{name}]  #{snippet[0..90]}#{snippet.length > 90 ? '…' : ''}"
+  end
+
+rescue Ractor::IsolationError, Ractor::Error => e
+  puts "  Ractor error: #{e.class}: #{e.message[0..100]}"
+  puts
+  puts "  ruby_llm is not yet Ractor-safe: it uses Procs in class"
+  puts "  definitions that cannot cross Ractor boundaries."
+  puts "  Track this at: https://github.com/crmne/ruby_llm"
+
+rescue RobotLab::Error => e
+  if e.message.include?("un-shareable Proc")
+    puts "  Live LLM runs require ruby_llm to be Ractor-safe."
+    puts "  ruby_llm stores Procs in class-level hooks that cannot cross"
+    puts "  Ractor boundaries. Part 1 (SimulatedScheduler) demonstrates wave"
+    puts "  ordering today; Part 3 will work once ruby_llm gains Ractor support."
+  else
+    puts "  RobotLab::Error: #{e.message}"
+  end
+end
+
+puts
+puts "=" * 62
+puts "Example 30 complete."
+puts "=" * 62

data/examples/README.md

@@ -25,6 +25,8 @@ bundle exec ruby examples/01_simple_robot.rb
 
 ```
 examples/
+  27_incident_response/       # Phase 5 infra — BusPoller, reactive memory, poller groups
+    incident_response.rb      #   Main entrypoint — wires up the war room
   01_simple_robot.rb          # Basic robot with template
   02_tools.rb                 # Robot with custom tools
   03_network.rb               # Multi-robot network with routing
@@ -45,6 +47,16 @@ examples/
     scout.rb                  #   Talent scout with analyst spawning
     display.rb                #   Terminal formatting (color, wrapping, file output)
     prompts/                  #   Templates for comic, heckler, and scout
+  19_token_tracking.rb        # Per-robot token & cost tracking
+  20_circuit_breaker.rb       # Tool loop circuit breaker with max_tool_rounds
+  21_learning_loop.rb         # Learning accumulation across runs with robot.learn
+  22_context_compression.rb   # Context window compression with HistoryCompressor
+  23_convergence.rb           # Debate convergence detection and reconciler fast-path
+  24_structured_delegation.rb # Structured delegation with duration and token tracking
+  25_history_search.rb        # Semantic search over a robot's conversation history
+  26_document_store.rb        # Embedding-based document store (RAG) via fastembed
+  29_ractor_tools.rb          # Ractor-safe tools: worker pool, freeze_deep, parallel batch
+  30_ractor_network.rb        # Ractor network scheduler: dependency waves, parallel_mode
   18_rails/                   # Minimal Rails 8 demo app (full integration)
     app/robots/chat_robot.rb  #   Robot factory with system prompt + TimeTool
     app/tools/time_tool.rb    #   Custom RobotLab::Tool subclass
@@ -161,6 +173,130 @@ Demonstrates: Robot subclasses, self-modification via tool side effects, dynamic
 
 **Requires:** LLM API key
 
+### 19 — Token & Cost Tracking
+
+Track token usage across runs using `result.input_tokens` / `result.output_tokens` for per-run counts and `robot.total_input_tokens` / `robot.total_output_tokens` for running totals. Demonstrates `reset_token_totals` to start a fresh batch and includes a simple cost estimate using per-provider pricing constants.
+
+**Requires:** LLM API key
+
+### 20 — Tool Loop Circuit Breaker
+
+Guards against runaway tool call loops using `max_tool_rounds:`. A step processor tool is designed to always return "more steps remain", which would loop indefinitely without a guard. The circuit breaker fires after the configured limit and raises `RobotLab::ToolLoopError`. Shows how to rescue the error gracefully and confirms the robot is fully reusable after a breaker trip.
+
+**Requires:** LLM API key
+
+### 21 — Learning Accumulation Loop
+
+Builds up cross-run observations with `robot.learn(text)`. A code reviewer accumulates one key insight after each review. On subsequent runs, learnings are automatically prepended to the user message as a "LEARNINGS FROM PREVIOUS RUNS:" block. Demonstrates bidirectional substring deduplication (broader learnings replace narrower ones), the `robot.learnings` accessor, and how learnings survive a robot rebuild via the shared `Memory` object.
+
+**Requires:** LLM API key
+
+### 22 — Context Window Compression
+
+Demonstrates `robot.compress_history()` for reducing token usage in long conversations. Old turns are scored against the recent context using stemmed term-frequency cosine similarity (via the `classifier` gem). High-relevance turns are kept verbatim; irrelevant turns are dropped; medium-relevance turns can optionally be summarized by a second robot. Shows both drop-mode and summarizer-lambda patterns, plus the LLM summarizer integration recipe.
+
+**Requires:** `gem 'classifier', '~> 2.3'` in your Gemfile (no LLM calls in the demo itself)
+
+### 24 — Structured Delegation
+
+A manager robot delegates sub-tasks to a summarizer and an analyst. Each `delegate()` call returns a `RobotResult` annotated with `delegated_by`, `duration`, and token counts. Includes a comparison table of when to use delegation vs. bus messaging vs. pipelines.
+
+**Requires:** LLM API key
+
+### 23 — Debate Convergence Detection
+
+Demonstrates `RobotLab::Convergence` for detecting when two independent agents have reached the same conclusion. Scores pairs of texts from identical → semantically similar → partially related → unrelated, showing how the similarity metric varies. Includes the router fast-path pattern: when two verifier robots agree above a threshold, the expensive reconciler LLM call is skipped entirely.
+
+**Requires:** `gem 'classifier', '~> 2.3'` in your Gemfile (no LLM calls in the demo itself)
+
+### 24 — Structured Delegation
+
+Demonstrates `robot.delegate(to:, task:)` for synchronous and asynchronous inter-robot delegation. The manager robot delegates document analysis to a summarizer and an analyst. Shows synchronous (sequential, blocking) and asynchronous (parallel fan-out, `DelegationFuture`) modes with wall-time comparison.
+
+**Requires:** LLM API key
+
+### 25 — Chat History Search
+
+Demonstrates `robot.search_history(query, limit:)` — semantic search over accumulated conversation turns using stemmed TF cosine similarity. No LLM calls: messages are injected directly. Shows relevance ranking, role preservation, short-message filtering, and the `DependencyError` guard.
+
+**Requires:** `gem 'classifier', '~> 2.3'` in your Gemfile (no LLM calls)
+
+### 26 — Embedding-Based Document Store
+
+Demonstrates `memory.store_document(key, text)` and `memory.search_documents(query, limit:)` — a lightweight RAG store using `fastembed` (BAAI/bge-small-en-v1.5). Documents are embedded once; queries are compared by cosine similarity at search time. Includes the `RobotLab::DocumentStore` standalone API and a RAG pattern sketch showing how to pass retrieved context to a robot.
+
+**Requires:** `fastembed` gem (already a core dependency); downloads the ~23 MB ONNX model on first run (cached in `~/.cache/fastembed/`)
+
+### 27 — Production Incident War Room
+
+Three SRE scout robots investigate a payment-service outage in parallel — database layer, network layer, and application layer. Each scout stores its findings in shared reactive memory and broadcasts a status update to a war-room coordinator via TypedBus.
+
+Demonstrates all four Phase 5 infrastructure improvements together:
+
+| Feature | How it shows up |
+|---------|----------------|
+| **IO.pipe Waiter** (#13) | Commander blocks on `memory.get(:db_finding, :net_finding, :app_finding, wait: 60)`; wakes the instant the last scout writes its key |
+| **BusPoller** (#14) | All three scouts send bus messages to the war room; BusPoller serializes delivery so war_room processes them one at a time, in arrival order, with no dropped messages |
+| **Poller Groups** (#15) | Scout tasks labeled `poller_group: :investigation`; commander task labeled `poller_group: :command`; group list printed before the run |
+| **Reactive Memory** | `memory.subscribe` callbacks fire in real-time as each scout writes, while the blocking waiter runs independently |
+
+**Run:**
+```bash
+bundle exec ruby examples/27_incident_response/incident_response.rb
+# or
+bundle exec rake examples:run[27]
+```
+
+**Requires:** LLM API key
+
+### 28 — MCP Server Discovery
+
+When a robot has many MCP servers configured, connecting to all of them upfront is wasteful. `mcp_discovery: true` enables semantic server selection: before the first connection, `MCP::ServerDiscovery` scores each server's `name + description` against the user query using TF cosine similarity and connects only the relevant subset.
+
+Demonstrates: `MCP::ServerDiscovery.select(query, from:, threshold:)`, the `description:` field on MCP server configs, `mcp_discovery: true` on Robot, and all four fallback cases (no descriptions, blank query, classifier unavailable, no match above threshold).
+
+**Requires:** None (no LLM calls — exercises the discovery module directly)
+
+### 29 — Ractor-Safe CPU Tools
+
+Demonstrates Track 1 of RobotLab's Ractor parallelism: CPU-bound tool classes that
+bypass the GVL by routing through a pool of Ractor workers.
+
+| Section | What it shows |
+|---------|--------------|
+| `ractor_safe?` flags | `WordStatsTool`, `ReadabilityTool`, `HeavyDigestTool` inherit `ractor_safe true` from `TextTool`; `RequestCounterTool` (mutable class variable) does not |
+| `RactorBoundary.freeze_deep` | Deep-freezes nested hashes/arrays; raises `RactorBoundaryError` on `StringIO` |
+| Single pool submit | Direct `RobotLab.ractor_pool.submit(class_name, args)` calls |
+| `ToolError` propagation | `nil.scan(...)` inside a Ractor worker → `NoMethodError` → `RobotLab::ToolError` |
+| Parallel batch | 6 threads each submitting a `HeavyDigestTool` job (5 000 SHA-256 rounds) simultaneously vs sequentially; speedup visible on multi-core hardware |
+
+**Requires:** None (no LLM calls)
+
+### 30 — Ractor Network Scheduler
+
+Demonstrates Track 2 of RobotLab's Ractor parallelism: running a multi-robot
+pipeline under `parallel_mode: :ractor`, which dispatches independent tasks in
+true parallel waves and respects `depends_on` ordering.
+
+Pipeline topology (4 robots):
+```
+headline_finder  ──┐
+background_brief ──┼──► report_writer
+fact_checker     ──┘
+```
+Wave 1 (headline_finder + background_brief + fact_checker) runs in parallel;
+Wave 2 (report_writer) runs after all three complete.
+
+**Part 1** — `SimulatedScheduler` (overrides `execute_spec` with `sleep`) shows
+wave ordering and timing without any API calls.  Expected: ~1.3 s parallel vs 2.2 s sequential.
+
+**Part 2** — Walks through `Network.new(parallel_mode: :ractor)` configuration
+and the `pipeline.step_dependencies` dependency graph inspection.
+
+**Part 3** — Live LLM run (enabled automatically when `ANTHROPIC_API_KEY` is set).
+
+**Requires:** None for Parts 1 & 2.  LLM API key for Part 3.
+
 ### 18 — Rails Integration Demo
 
 A minimal, hand-built Rails 8 app that exercises every piece of RobotLab's Rails integration end-to-end. No `rails new` — every file is hand-crafted for minimum size.

data/examples/prompts/skill_with_mcp_test.md

@@ -0,0 +1,9 @@
+---
+description: Skill that sets mcp via frontmatter
+mcp:
+  - name: skill_server
+    transport: stdio
+    command: echo
+    args: ["hello"]
+---
+You have the MCP skill capabilities.

data/examples/prompts/skill_with_robot_name_test.md

@@ -0,0 +1,5 @@
+---
+description: Skill that sets robot_name via frontmatter
+robot_name: skill_named_bot
+---
+You have the named skill capabilities.

data/examples/prompts/skill_with_tools_test.md

@@ -0,0 +1,6 @@
+---
+description: Skill that sets tools via frontmatter
+tools:
+  - FrontmatterTestTool
+---
+You have the tools skill capabilities.

data/lib/robot_lab/bus_poller.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "ractor_queue"
+
+module RobotLab
+  # Centralizes bus delivery serialization for robots.
+  #
+  # Each robot's TypedBus subscription calls enqueue() instead of
+  # handling deliveries inline. BusPoller ensures per-robot sequential
+  # processing: if a robot is already processing a delivery, new ones
+  # are queued and drained after the current one completes.
+  #
+  # Unlike the old per-robot @bus_processing flag, BusPoller is mutex-
+  # protected and shared across robots, giving a single point of control
+  # for delivery ordering. Delivery still happens in the caller's
+  # execution context (Async fiber or OS thread), so synchronous test
+  # semantics are preserved.
+  #
+  # == Poller Groups
+  #
+  # Robots can be assigned to named groups via the Network DSL:
+  #
+  #   task :fast_bot, fast_robot, depends_on: :none
+  #   task :slow_bot, slow_robot, depends_on: :none, poller_group: :slow
+  #
+  # Groups are purely organizational — they share the same mutex-based
+  # drain mechanism. In Async contexts, slow robots naturally yield during
+  # LLM HTTP calls without blocking fast robots.
+  #
+  # @api private
+  class BusPoller
+    # Capacity of per-robot RactorQueue delivery queues.
+    QUEUE_CAPACITY = 512
+
+    # Creates a new BusPoller.
+    def initialize
+      @mutex        = Mutex.new
+      @robot_busy   = {}   # robot_name => Boolean
+      @robot_queues = {}   # robot_name => RactorQueue<delivery>
+      @groups       = [:default]
+    end
+
+    # No-op — BusPoller has no background threads to start.
+    # Kept for API symmetry with the old design.
+    #
+    # @return [self]
+    def start
+      self
+    end
+
+    # No-op — no threads to stop.
+    #
+    # @return [self]
+    def stop(*)
+      self
+    end
+
+    # Enqueue a delivery for a robot.
+    #
+    # If the robot is not currently processing, the delivery is handled
+    # immediately in the caller's context (Async fiber or OS thread).
+    # If the robot is busy, the delivery is queued and will be drained
+    # after the current delivery completes.
+    #
+    # @param robot    [Robot]   the robot that will process the delivery
+    # @param delivery [Object]  the TypedBus delivery object
+    # @param group    [Symbol]  poller group label (informational only)
+    # @return [void]
+    #
+    def enqueue(robot:, delivery:, group: :default)
+      should_process = @mutex.synchronize do
+        name = robot.name
+        @robot_queues[name] ||= RactorQueue.new(capacity: QUEUE_CAPACITY)
+        @robot_busy[name]   ||= false
+
+        if @robot_busy[name]
+          @robot_queues[name].push(delivery)
+          false
+        else
+          @robot_busy[name] = true
+          true
+        end
+      end
+
+      process_and_drain(robot, delivery) if should_process
+    end
+
+    # Add a named poller group.
+    #
+    # Idempotent. Groups are informational labels — they do not create
+    # separate queues or threads.
+    #
+    # @param name [Symbol]
+    # @return [void]
+    def add_group(name)
+      @mutex.synchronize { @groups << name unless @groups.include?(name) }
+    end
+
+    # Names of all registered poller groups.
+    #
+    # @return [Array<Symbol>]
+    def groups
+      @mutex.synchronize { @groups.dup }
+    end
+
+    # Always true — BusPoller needs no background threads.
+    #
+    # @return [Boolean]
+    def running?
+      true
+    end
+
+    private
+
+    # Process one delivery, then drain any queued deliveries for the robot.
+    def process_and_drain(robot, delivery)
+      robot.send(:process_delivery, delivery)
+
+      loop do
+        next_delivery = @mutex.synchronize do
+          name  = robot.name
+          queue = @robot_queues[name]
+
+          if queue && !queue.empty?
+            entry = queue.try_pop
+            entry.equal?(RactorQueue::EMPTY) ? nil : entry
+          else
+            @robot_busy[name] = false
+            nil
+          end
+        end
+
+        break unless next_delivery
+
+        begin
+          robot.send(:process_delivery, next_delivery)
+        rescue BusError => e
+          RobotLab.config.logger.warn("BusPoller: delivery error: #{e.message}")
+        end
+      end
+    rescue BusError => e
+      @mutex.synchronize { @robot_busy[robot.name] = false }
+      RobotLab.config.logger.warn("BusPoller: delivery error: #{e.message}")
+    rescue => e
+      @mutex.synchronize { @robot_busy[robot.name] = false }
+      RobotLab.config.logger.warn("BusPoller: unexpected error: #{e.message}")
+    end
+  end
+end

data/lib/robot_lab/convergence.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # TF-IDF cosine similarity utilities for detecting semantic convergence
+  # between two texts.
+  #
+  # Common use cases:
+  # - Checking whether two independent verifiers have reached the same conclusion
+  # - Skipping a reconciler LLM call when verifiers already agree (fast-path)
+  # - Detecting when a multi-robot debate has converged on a consensus
+  #
+  # Requires the optional 'classifier' gem (~> 2.3).
+  #
+  # @example Skip reconciler when verifiers agree
+  #   score = RobotLab::Convergence.similarity(result_a.reply, result_b.reply)
+  #
+  #   router = ->(args) do
+  #     a = args.context[:verifier_a]&.reply.to_s
+  #     b = args.context[:verifier_b]&.reply.to_s
+  #     RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+  #   end
+  module Convergence
+    # Default cosine similarity threshold above which texts are convergent.
+    DEFAULT_THRESHOLD = 0.85
+
+    # Minimum text length (characters) for meaningful TF-IDF scoring.
+    # Texts shorter than this always return 0.0 similarity.
+    MIN_TEXT_LENGTH = 30
+
+    # Determine whether two texts are semantically convergent.
+    #
+    # @param text_a [String]
+    # @param text_b [String]
+    # @param threshold [Float] minimum similarity to declare convergence (default 0.85)
+    # @return [Boolean]
+    # @raise [DependencyError] if the 'classifier' gem is not installed
+    # @raise [ArgumentError] if threshold is outside [0.0, 1.0]
+    def self.detected?(text_a, text_b, threshold: DEFAULT_THRESHOLD)
+      unless (0.0..1.0).cover?(threshold)
+        raise ArgumentError, "threshold must be in [0.0, 1.0], got #{threshold}"
+      end
+
+      similarity(text_a, text_b) >= threshold
+    end
+
+    # Compute cosine similarity between two texts using stemmed term frequencies.
+    #
+    # Uses +String#word_hash+ (provided by the classifier gem) to build
+    # stemmed, stopword-filtered term-frequency vectors, then computes
+    # L2-normalized cosine similarity. Term frequencies (no IDF) are used
+    # because IDF on a 2-document corpus collapses shared terms to zero,
+    # which would incorrectly penalize texts that agree on the same topic.
+    #
+    # Returns 0.0 when either text is blank or shorter than +MIN_TEXT_LENGTH+.
+    #
+    # @param text_a [String]
+    # @param text_b [String]
+    # @return [Float] in [0.0, 1.0]
+    # @raise [DependencyError] if the 'classifier' gem is not installed
+    def self.similarity(text_a, text_b)
+      a = text_a.to_s.strip
+      b = text_b.to_s.strip
+
+      return 0.0 if a.length < MIN_TEXT_LENGTH || b.length < MIN_TEXT_LENGTH
+
+      TextAnalysis.tf_cosine_similarity(a, b)
+    end
+  end
+end