robot_lab 0.3.0 → 0.5.0

data/lib/robot_lab/mcp/transports/stdio.rb

@@ -1,170 +0,0 @@
-# frozen_string_literal: true
-
-require "open3"
-require "json"
-require "timeout"
-
-module RobotLab
-  module MCP
-    module Transports
-      # StdIO transport for local MCP servers
-      #
-      # Spawns a subprocess and communicates via stdin/stdout.
-      # All blocking I/O is wrapped with a configurable timeout
-      # so a missing or hung server cannot block the caller forever.
-      #
-      # @example
-      #   transport = Stdio.new(
-      #     { command: "mcp-server-filesystem", args: ["--root", "/data"] },
-      #     timeout: 10
-      #   )
-      #
-      # :reek:InstanceVariableAssumption -- @config and @timeout are assigned in Base#initialize (reek does not trace super).
-      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every IO operation must check it.
-      class Stdio < Base
-        # Creates a new Stdio transport.
-        #
-        # @param config [Hash] transport configuration
-        # @option config [String] :command the command to execute
-        # @option config [Array<String>] :args command arguments
-        # @option config [Hash] :env environment variables
-        # @option config [Numeric] :timeout request timeout in seconds (default: 15)
-        def initialize(config)
-          super
-          @stdin = nil
-          @stdout = nil
-          @stderr = nil
-          @wait_thread = nil
-          @connected = false
-        end
-
-        # Connect to the MCP server via stdio.
-        #
-        # @return [self]
-        # @raise [MCPError] if the server process cannot be started or does not
-        #   respond to the MCP initialize handshake within the timeout period
-        # :reek:TooManyStatements -- linear spawn/verify/handshake sequence with per-failure-mode rescues.
-        def connect
-          return self if @connected
-
-          command = @config[:command]
-          args = @config[:args] || []
-          env = @config[:env] || {}
-
-          full_env = ENV.to_h.merge(env.transform_keys(&:to_s))
-
-          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(full_env, command, *args)
-
-          # Verify the process actually started
-          unless @wait_thread.alive?
-            raise MCPError, "MCP server process exited immediately (command: #{command})"
-          end
-
-          @connected = true
-
-          # Initialize MCP protocol — this must complete within the timeout
-          send_initialize
-
-          self
-        rescue Errno::ENOENT => e
-          cleanup_process
-          raise MCPError, "MCP server command not found: #{command} (#{e.message})"
-        rescue Timeout::Error
-          cleanup_process
-          raise MCPError, "MCP server '#{command}' did not respond within #{@timeout}s"
-        end
-
-        # Send a JSON-RPC request to the MCP server.
-        #
-        # @param message [Hash] JSON-RPC message
-        # @return [Hash] the response
-        # @raise [MCPError] if not connected, no response, or timeout
-        # :reek:TooManyStatements -- write-then-read loop must stay inside the one Timeout block.
-        def send_request(message)
-          raise MCPError, "Not connected" unless @connected
-
-          Timeout.timeout(@timeout, Timeout::Error) do
-            json = message.to_json
-            @stdin.puts(json)
-            @stdin.flush
-
-            loop do
-              response_line = @stdout.gets
-              raise MCPError, "No response from MCP server (EOF on stdout)" unless response_line
-
-              parsed = JSON.parse(response_line, symbolize_names: true)
-
-              # Skip notifications (messages without an id)
-              next if parsed[:method] && !parsed.key?(:id)
-
-              return parsed
-            end
-          end
-        rescue Timeout::Error
-          raise MCPError, "MCP server did not respond within #{@timeout}s"
-        rescue Errno::EPIPE, IOError => e
-          @connected = false
-          raise MCPError, "MCP server connection lost: #{e.message}"
-        end
-
-        # Close the connection to the MCP server.
-        #
-        # @return [self]
-        def close
-          return self unless @connected
-
-          cleanup_process
-          self
-        end
-
-        # Check if the transport is connected.
-        #
-        # @return [Boolean] true if connected and process is alive
-        def connected?
-          @connected && @wait_thread&.alive?
-        end
-
-        # Expose the underlying IO objects so ConnectionPoller can
-        # register them in its IO.select loop.
-        #
-        # @api private
-        attr_reader :stdin, :stdout
-
-        private
-
-        def send_initialize
-          send_request(
-            jsonrpc: "2.0",
-            id: 0,
-            method: "initialize",
-            params: {
-              protocolVersion: "2024-11-05",
-              capabilities: {},
-              clientInfo: {
-                name: "RobotLab",
-                version: RobotLab::VERSION
-              }
-            }
-          )
-
-          # Send initialized notification
-          @stdin.puts({ jsonrpc: "2.0", method: "notifications/initialized" }.to_json)
-          @stdin.flush
-        end
-
-        # :reek:TooManyStatements -- best-effort teardown; each handle is closed and nilled independently.
-        def cleanup_process
-          @connected = false
-          @stdin&.close  rescue nil
-          @stdout&.close rescue nil
-          @stderr&.close rescue nil
-          @wait_thread&.kill if @wait_thread&.alive?
-          @stdin = nil
-          @stdout = nil
-          @stderr = nil
-          @wait_thread = nil
-        end
-      end
-    end
-  end
-end

data/lib/robot_lab/mcp/transports/streamable_http.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module MCP
-    module Transports
-      # Streamable HTTP transport for MCP servers
-      #
-      # Supports session management and reconnection.
-      #
-      # @example
-      #   transport = StreamableHTTP.new(
-      #     url: "https://server.smithery.ai/neon/mcp",
-      #     session_id: "abc123"
-      #   )
-      #
-      # :reek:InstanceVariableAssumption -- @config is assigned in Base#initialize (reek does not trace super).
-      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every operation must check it.
-      class StreamableHTTP < Base
-        # Creates a new StreamableHTTP transport.
-        #
-        # @param config [Hash] transport configuration
-        # @option config [String] :url HTTP server URL
-        # @option config [String] :session_id optional session identifier
-        # @option config [Proc] :auth_provider optional authentication callback
-        def initialize(config)
-          super
-          @client = nil
-          @connected = false
-          @session_id = config[:session_id]
-        end
-
-        # Connect to the MCP server via HTTP.
-        #
-        # @return [self]
-        # @raise [MCPError] if async-http gem is not available
-        # :reek:TooManyStatements -- linear require/connect/handshake sequence inside the Async block.
-        def connect
-          return self if @connected
-
-          require "async"
-          require "async/http/client"
-          require "async/http/endpoint"
-
-          url = @config[:url]
-
-          Async do
-            endpoint = Async::HTTP::Endpoint.parse(url)
-            @client = Async::HTTP::Client.new(endpoint)
-            @connected = true
-
-            # Initialize MCP protocol
-            result = send_initialize
-            @session_id ||= result.dig(:serverInfo, :sessionId)
-          end
-
-          self
-        rescue LoadError => e
-          raise MCPError, "async-http gem required for HTTP transport: #{e.message}"
-        end
-
-        # Send a JSON-RPC request to the MCP server.
-        #
-        # @param message [Hash] JSON-RPC message
-        # @return [Hash] the response
-        # @raise [MCPError] if not connected
-        # :reek:TooManyStatements -- header assembly and POST must stay inside the one Async block.
-        def send_request(message)
-          raise MCPError, "Not connected" unless @connected
-
-          require "async"
-
-          Async do
-            headers = {
-              "Content-Type" => "application/json",
-              "Accept" => "application/json"
-            }
-            headers["X-Session-ID"] = @session_id if @session_id
-
-            # Add auth if configured
-            if @config[:auth_provider]
-              auth_header = @config[:auth_provider].call
-              headers["Authorization"] = auth_header if auth_header
-            end
-
-            response = @client.post(
-              @config[:url],
-              headers,
-              [message.to_json]
-            )
-
-            body = response.read
-            JSON.parse(body, symbolize_names: true)
-          end.wait
-        end
-
-        # Close the HTTP connection.
-        #
-        # @return [self]
-        def close
-          return self unless @connected
-
-          @client&.close
-          @connected = false
-          @client = nil
-
-          self
-        end
-
-        # Check if the transport is connected.
-        #
-        # @return [Boolean] true if connected
-        def connected?
-          @connected
-        end
-
-        # Returns the session identifier.
-        #
-        # @return [String, nil] the session ID
-        attr_reader :session_id
-
-        private
-
-        def send_initialize
-          send_request(
-            jsonrpc: "2.0",
-            id: 0,
-            method: "initialize",
-            params: {
-              protocolVersion: "2024-11-05",
-              capabilities: {},
-              clientInfo: {
-                name: "RobotLab",
-                version: RobotLab::VERSION
-              }
-            }
-          )
-        end
-      end
-    end
-  end
-end

data/lib/robot_lab/mcp/transports/websocket.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module MCP
-    module Transports
-      # WebSocket transport for MCP servers
-      #
-      # Uses async-websocket for non-blocking communication.
-      #
-      # @example
-      #   transport = WebSocket.new(url: "ws://localhost:8080")
-      #
-      # :reek:InstanceVariableAssumption -- @config is assigned in Base#initialize (reek does not trace super).
-      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every operation must check it.
-      class WebSocket < Base
-        # Creates a new WebSocket transport.
-        #
-        # @param config [Hash] transport configuration
-        # @option config [String] :url WebSocket server URL
-        def initialize(config)
-          super
-          @connection = nil
-          @connected = false
-          @pending_requests = {}
-        end
-
-        # Connect to the MCP server via WebSocket.
-        #
-        # @return [self]
-        # @raise [MCPError] if async-websocket gem is not available
-        # :reek:TooManyStatements -- linear require/connect/handshake sequence inside the Async block.
-        def connect
-          return self if @connected
-
-          require "async"
-          require "async/websocket/client"
-
-          url = @config[:url]
-
-          Async do
-            endpoint = Async::HTTP::Endpoint.parse(url)
-            @connection = Async::WebSocket::Client.connect(endpoint)
-            @connected = true
-
-            # Initialize MCP protocol
-            send_initialize
-          end
-
-          self
-        rescue LoadError => e
-          raise MCPError, "async-websocket gem required for WebSocket transport: #{e.message}"
-        end
-
-        # Send a JSON-RPC request to the MCP server.
-        #
-        # @param message [Hash] JSON-RPC message
-        # @return [Hash] the response
-        # @raise [MCPError] if not connected
-        def send_request(message)
-          raise MCPError, "Not connected" unless @connected
-
-          Async do
-            @connection.write(message.to_json)
-            @connection.flush
-
-            response_text = @connection.read
-            JSON.parse(response_text, symbolize_names: true)
-          end.wait
-        end
-
-        # Close the WebSocket connection.
-        #
-        # @return [self]
-        def close
-          return self unless @connected
-
-          @connection&.close
-          @connected = false
-          @connection = nil
-
-          self
-        end
-
-        # Check if the transport is connected.
-        #
-        # @return [Boolean] true if connected
-        def connected?
-          @connected
-        end
-
-        private
-
-        def send_initialize
-          send_request(
-            jsonrpc: "2.0",
-            id: 0,
-            method: "initialize",
-            params: {
-              protocolVersion: "2024-11-05",
-              capabilities: {},
-              clientInfo: {
-                name: "RobotLab",
-                version: RobotLab::VERSION
-              }
-            }
-          )
-        end
-      end
-    end
-  end
-end

data/logfile

@@ -1,8 +0,0 @@
-2026-02-25 20:56:30.644 CST [47152] LOG:  starting PostgreSQL 18.2 (Homebrew) on aarch64-apple-darwin25.2.0, compiled by Apple clang version 17.0.0 (clang-1700.6.3.2), 64-bit
-2026-02-25 20:56:30.646 CST [47152] LOG:  could not bind IPv6 address "::1": Address already in use
-2026-02-25 20:56:30.646 CST [47152] HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
-2026-02-25 20:56:30.646 CST [47152] LOG:  could not bind IPv4 address "127.0.0.1": Address already in use
-2026-02-25 20:56:30.646 CST [47152] HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
-2026-02-25 20:56:30.646 CST [47152] WARNING:  could not create listen socket for "localhost"
-2026-02-25 20:56:30.646 CST [47152] FATAL:  could not create any TCP/IP sockets
-2026-02-25 20:56:30.646 CST [47152] LOG:  database system is shut down

data/mkdocs.yml

@@ -1,209 +0,0 @@
-# MkDocs Configuration for RobotLab Documentation
-site_name: RobotLab
-site_description: Multi-robot LLM workflow orchestration for Ruby
-site_author: Dewayne VanHoozer
-site_url: https://madbomber.github.io/robot_lab
-copyright: Copyright © 2025 Dewayne VanHoozer
-
-# Repository information
-repo_name: madbomber/robot_lab
-repo_url: https://github.com/madbomber/robot_lab
-edit_uri: edit/main/docs/
-
-# Configuration
-theme:
-  name: material
-
-  # Color scheme
-  palette:
-    - scheme: default
-      primary: deep purple
-      accent: amber
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-
-    - scheme: slate
-      primary: deep purple
-      accent: amber
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-
-  # Typography
-  font:
-    text: Roboto
-    code: Roboto Mono
-
-  # Logo and icon
-  icon:
-    repo: fontawesome/brands/github
-    logo: material/robot
-
-  # Theme features
-  features:
-    - navigation.instant
-    - navigation.tracking
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.path
-    - navigation.indexes
-    - navigation.top
-    - navigation.footer
-    - toc.follow
-    - search.suggest
-    - search.highlight
-    - search.share
-    - header.autohide
-    - content.code.copy
-    - content.code.annotate
-    - content.tabs.link
-    - content.tooltips
-    - content.action.edit
-    - content.action.view
-
-# Plugins
-plugins:
-  - search:
-      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
-  - tags
-
-# Extensions
-markdown_extensions:
-  - abbr
-  - admonition
-  - attr_list
-  - def_list
-  - footnotes
-  - md_in_html
-  - tables
-  - toc:
-      permalink: true
-      title: On this page
-
-  - pymdownx.arithmatex:
-      generic: true
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.critic
-  - pymdownx.details
-  - pymdownx.emoji:
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.keys
-  - pymdownx.magiclink:
-      repo_url_shorthand: true
-      user: madbomber
-      repo: robot_lab
-      normalize_issue_symbols: true
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.snippets:
-      check_paths: true
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-
-# Extra CSS
-extra_css:
-  - assets/css/custom.css
-
-# Social media and extra configuration
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/madbomber/robot_lab
-      name: RobotLab on GitHub
-    - icon: fontawesome/solid/gem
-      link: https://rubygems.org/gems/robot_lab
-      name: RobotLab on RubyGems
-
-  analytics:
-    feedback:
-      title: Was this page helpful?
-      ratings:
-        - icon: material/emoticon-happy-outline
-          name: This page was helpful
-          data: 1
-          note: Thanks for your feedback!
-        - icon: material/emoticon-sad-outline
-          name: This page could be improved
-          data: 0
-          note: Thanks for your feedback! Help us improve by creating an issue.
-
-# Navigation
-nav:
-  - Home:
-      - Overview: index.md
-      - Concepts: concepts.md
-  - Getting Started:
-      - getting-started/index.md
-      - Installation: getting-started/installation.md
-      - Quick Start: getting-started/quick-start.md
-      - Configuration: getting-started/configuration.md
-  - Architecture:
-      - architecture/index.md
-      - Core Concepts: architecture/core-concepts.md
-      - Robot Execution: architecture/robot-execution.md
-      - Network Orchestration: architecture/network-orchestration.md
-      - State Management: architecture/state-management.md
-      - Message Flow: architecture/message-flow.md
-  - Guides:
-      - guides/index.md
-      - Building Robots: guides/building-robots.md
-      - Creating Networks: guides/creating-networks.md
-      - Using Tools: guides/using-tools.md
-      - MCP Integration: guides/mcp-integration.md
-      - Streaming Responses: guides/streaming.md
-      - Memory System: guides/memory.md
-      - Observability & Safety: guides/observability.md
-      - Hook System: guides/hooks.md
-      - Knowledge Search: guides/knowledge.md
-  - API Reference:
-      - api/index.md
-      - Core Classes:
-          - api/core/index.md
-          - Robot: api/core/robot.md
-          - RobotResult: api/core/result.md
-          - Network: api/core/network.md
-          - Tool: api/core/tool.md
-          - Memory: api/core/memory.md
-          - StateProxy: api/core/state.md
-      - Hooks: api/hooks.md
-      - Skills: api/skills.md
-      - Support Classes: api/support.md
-      - Errors: api/errors.md
-      - Messages:
-          - api/messages/index.md
-          - UserMessage: api/messages/user-message.md
-          - TextMessage: api/messages/text-message.md
-          - ToolCallMessage: api/messages/tool-call-message.md
-          - ToolResultMessage: api/messages/tool-result-message.md
-      - MCP:
-          - api/mcp/index.md
-          - Client: api/mcp/client.md
-          - Server: api/mcp/server.md
-          - Transports: api/mcp/transports.md
-      - Streaming:
-          - api/streaming/index.md
-          - Context: api/streaming/context.md
-          - Events: api/streaming/events.md
-  - Examples:
-      - examples/index.md
-      - Basic Chat: examples/basic-chat.md
-      - Multi-Robot Network: examples/multi-robot-network.md
-      - Tool Usage: examples/tool-usage.md
-      - MCP Server: examples/mcp-server.md

data/robot_concurrency.md

@@ -1,38 +0,0 @@
-# Ruby Concurrency Review — RobotLab
-
-Source: https://paolino.me/ruby-concurrency-what-actually-happens/
-
-## What Applies to RobotLab
-
-### 1. You're Already in the Right Model — Lean Into It
-
-RobotLab uses `async (~> 2.0)`, which is exactly the fiber-based scheduler the article describes. LLM calls are pure I/O-bound work (HTTP streaming), so fibers are the correct and lowest-cost primitive. The article validates this architecture choice. No changes needed here — but be deliberate about not mixing blocking thread-style calls into the `Async` reactor unnecessarily.
-
-### 2. The Ractor Caution Is Real (Recent Commit: `feat(ractor-parallelism)`)
-
-The article is clear: Ractors in Ruby 4.0 are still experimental and practically incompatible with gems that use global state. RobotLab's dependencies (`ruby_llm`, `prompt_manager`, `zeitwerk`) almost certainly use global state. Worth auditing whether the new Ractor code hits `Ractor::IsolationError` under realistic load. The article's recommendation: **use Processes** for CPU parallelism if Rails-style gems are involved.
-
-### 3. ~~The `Waiter` Class May Be Misfit in Fiber Context~~ — RESOLVED
-
-`lib/robot_lab/waiter.rb` was updated to use `IO.pipe` + `IO.select` instead of `ConditionVariable`. `IO.select` is hooked by the Ruby 3.1+ fiber scheduler protocol, so it correctly yields to the Async scheduler when called from within an Async task, and correctly blocks the calling thread when used outside one. `Async::Condition` was considered but rejected: it only works inside an Async block, whereas `Memory` is intentionally usable from both plain threads and Async fibers.
-
-### 4. Parallel Network Execution — Check the Primitive
-
-`call_parallel()` in `Network` (built on `SimpleFlow::Pipeline`) — if it spawns OS threads rather than async tasks, you get heavier overhead than necessary for I/O-bound robot calls. The article's guidance: for I/O work, fiber-based `Async::Barrier` with concurrent tasks is 10-20x cheaper than threads.
-
-### 5. Resource Semaphores for Parallel Networks
-
-When a Network runs multiple robots concurrently, each making LLM API calls, you can exhaust API rate limits or connection pools with no back-pressure. The article's semaphore pattern applies directly — cap in-flight robot tasks to match your API tier's concurrency limit. This is worth adding to `RunConfig` as a `max_concurrent_robots` infra field.
-
-### 6. Colorless Concurrency — This Is Already Your Story
-
-The article's main point about Ruby fibers being "colorless" (no `async/await` propagation required) is directly reflected in how `robot.run("...")` stays synchronous-looking whether run standalone or in a parallel network. This is an underappreciated design strength worth highlighting in docs/README.
-
----
-
-## Summary
-
-The async/fiber architecture is correct for LLM I/O work. The two actionable concerns are:
-
-1. **Audit the Ractor code** for isolation errors with gem dependencies (`ruby_llm`, `prompt_manager`, `zeitwerk`).
-2. **Check `Waiter`** (condition variable in `lib/robot_lab/waiter.rb`) — if called inside an `Async` reactor block, replace with `Async::Condition` to avoid stalling the reactor.