robot_lab 0.0.1 → 0.0.6

data/docs/api/mcp/transports.md

@@ -1,264 +1,252 @@
 # MCP Transports
 
-Communication methods for MCP connections.
+Communication methods for MCP client-server connections.
 
 ## Overview
 
-Transports handle the low-level communication between MCP clients and servers. RobotLab supports multiple transport types for different deployment scenarios.
+Transports handle the low-level communication between `MCP::Client` and external MCP servers. All transports implement the same interface defined by `Transports::Base`, using JSON-RPC 2.0 for message exchange and the MCP protocol version `2024-11-05` for initialization.
 
-## Transport Types
+RobotLab provides four built-in transport types:
 
-### Stdio
+| Transport | Class | Use Case |
+|-----------|-------|----------|
+| Stdio | `Transports::Stdio` | Local subprocess servers |
+| WebSocket | `Transports::WebSocket` | Real-time bidirectional |
+| SSE | `Transports::SSE` | Server-sent events |
+| Streamable HTTP | `Transports::StreamableHTTP` | HTTP with session support |
 
-Standard input/output for local process communication.
+## Base Interface
 
-```ruby
-{
-  type: "stdio",
-  command: "npx",
-  args: ["@modelcontextprotocol/server-filesystem", "/path"],
-  env: { "DEBUG" => "true" }
-}
-```
+All transports inherit from `RobotLab::MCP::Transports::Base` and implement:
 
-**Options:**
+```ruby
+class RobotLab::MCP::Transports::Base
+  attr_reader :config  # => Hash (symbolized keys)
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `command` | `String` | Executable command |
-| `args` | `Array` | Command arguments |
-| `env` | `Hash` | Environment variables |
-| `cwd` | `String` | Working directory |
+  def connect        # Establish connection, returns self
+  def send_request(message)  # Send JSON-RPC message, returns Hash response
+  def close          # Close connection, returns self
+  def connected?     # Returns Boolean
+end
+```
 
-**Use Cases:**
+## Stdio Transport
 
-- Local development
-- CLI tools
-- Subprocess servers
+**Class:** `RobotLab::MCP::Transports::Stdio`
 
-### WebSocket
+Spawns a subprocess and communicates via stdin/stdout using JSON-RPC messages (one per line). Automatically sends MCP `initialize` and `notifications/initialized` on connect.
 
-Bidirectional real-time communication.
+### Configuration
 
 ```ruby
 {
-  type: "websocket",
-  url: "wss://mcp.example.com/ws",
-  headers: { "Authorization" => "Bearer token" }
+  type: "stdio",
+  command: "mcp-server-filesystem",      # Required: executable command
+  args: ["--root", "/data"],             # Optional: command arguments
+  env: { "DEBUG" => "true" }             # Optional: environment variables
 }
 ```
 
-**Options:**
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `command` | `String` | Yes | Executable command to spawn |
+| `args` | `Array<String>` | No | Command arguments |
+| `env` | `Hash` | No | Environment variables (merged with current env) |
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `url` | `String` | WebSocket endpoint |
-| `headers` | `Hash` | HTTP headers |
-| `ping_interval` | `Integer` | Keep-alive interval (seconds) |
+### Behavior
 
-**Use Cases:**
+- Uses `Open3.popen3` to spawn the subprocess
+- Writes JSON-RPC messages to stdin (one per line)
+- Reads responses from stdout, skipping notifications (messages without `id`)
+- `connected?` returns `true` when the subprocess is alive
+- `close` terminates stdin, stdout, stderr, and kills the subprocess
 
-- Remote servers
-- Real-time applications
-- Long-running connections
+### Example
 
-### SSE (Server-Sent Events)
+```ruby
+transport = RobotLab::MCP::Transports::Stdio.new(
+  command: "mcp-server-filesystem",
+  args: ["--root", "/data"],
+  env: { "DEBUG" => "true" }
+)
 
-Unidirectional server-to-client streaming.
+transport.connect
+response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
+transport.close
+```
+
+## WebSocket Transport
+
+**Class:** `RobotLab::MCP::Transports::WebSocket`
+
+Uses `async-websocket` for non-blocking bidirectional communication. Requires the `async-websocket` gem.
+
+### Configuration
 
 ```ruby
 {
-  type: "sse",
-  url: "https://mcp.example.com/sse",
-  headers: { "Authorization" => "Bearer token" }
+  type: "ws",                              # or "websocket"
+  url: "wss://mcp.example.com/ws"          # Required: WebSocket endpoint
 }
 ```
 
-**Options:**
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `url` | `String` | Yes | WebSocket endpoint URL |
+
+### Behavior
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `url` | `String` | SSE endpoint |
-| `headers` | `Hash` | HTTP headers |
-| `post_url` | `String` | Endpoint for client messages |
+- Uses `Async::WebSocket::Client.connect` within an `Async` block
+- Sends JSON-RPC messages as JSON strings
+- Reads responses synchronously within the async context
+- Raises `MCPError` if the `async-websocket` gem is not installed
 
-**Use Cases:**
+### Example
 
-- Firewall-friendly connections
-- Browser-based clients
-- Streaming responses
+```ruby
+transport = RobotLab::MCP::Transports::WebSocket.new(
+  url: "ws://localhost:8080"
+)
+
+transport.connect
+response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
+transport.close
+```
 
-### HTTP
+## SSE Transport
 
-Request/response communication.
+**Class:** `RobotLab::MCP::Transports::SSE`
+
+Uses `async-http` for HTTP-based communication. Sends requests via HTTP POST and reads responses. Requires the `async-http` gem.
+
+### Configuration
 
 ```ruby
 {
-  type: "http",
-  url: "https://mcp.example.com/mcp",
-  headers: { "Authorization" => "Bearer token" },
-  timeout: 30
+  type: "sse",
+  url: "http://localhost:8080/sse"         # Required: SSE endpoint
 }
 ```
 
-**Options:**
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `url` | `String` | Yes | SSE/HTTP endpoint URL |
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `url` | `String` | HTTP endpoint |
-| `headers` | `Hash` | HTTP headers |
-| `timeout` | `Integer` | Request timeout (seconds) |
-| `retry` | `Integer` | Retry attempts |
+### Behavior
 
-**Use Cases:**
+- Creates an `Async::HTTP::Client` on connect
+- Sends JSON-RPC messages via HTTP POST with `Content-Type: application/json`
+- Reads and parses JSON response body
+- Raises `MCPError` if the `async-http` gem is not installed
 
-- Simple integrations
-- Stateless operations
-- Load-balanced servers
-
-## Examples
-
-### Local Server with Stdio
+### Example
 
 ```ruby
-network = RobotLab.create_network do
-  mcp [
-    {
-      name: "filesystem",
-      transport: {
-        type: "stdio",
-        command: "npx",
-        args: ["@modelcontextprotocol/server-filesystem", "/home/user/docs"]
-      }
-    }
-  ]
-end
+transport = RobotLab::MCP::Transports::SSE.new(
+  url: "http://localhost:8080/sse"
+)
+
+transport.connect
+response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
+transport.close
 ```
 
-### Remote Server with WebSocket
+## Streamable HTTP Transport
 
-```ruby
-network = RobotLab.create_network do
-  mcp [
-    {
-      name: "remote_tools",
-      transport: {
-        type: "websocket",
-        url: "wss://tools.example.com/mcp",
-        headers: {
-          "Authorization" => "Bearer #{ENV['MCP_TOKEN']}"
-        }
-      }
-    }
-  ]
-end
-```
+**Class:** `RobotLab::MCP::Transports::StreamableHTTP`
+
+HTTP-based transport with session management and optional authentication. Supports session IDs for maintaining server-side state across requests. Requires the `async-http` gem.
 
-### Multiple Transports
+### Configuration
 
 ```ruby
-network = RobotLab.create_network do
-  mcp [
-    # Local filesystem
-    {
-      name: "fs",
-      transport: { type: "stdio", command: "mcp-fs" }
-    },
-    # Remote API
-    {
-      name: "api",
-      transport: {
-        type: "http",
-        url: "https://api.example.com/mcp"
-      }
-    },
-    # Real-time service
-    {
-      name: "realtime",
-      transport: {
-        type: "websocket",
-        url: "wss://realtime.example.com/mcp"
-      }
-    }
-  ]
-end
+{
+  type: "streamable-http",                 # or "http"
+  url: "https://server.smithery.ai/neon/mcp",  # Required: HTTP endpoint
+  session_id: "abc123",                    # Optional: session identifier
+  auth_provider: -> { "Bearer #{token}" }  # Optional: auth callback
+}
 ```
 
-### Custom Transport
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `url` | `String` | Yes | HTTP endpoint URL |
+| `session_id` | `String` | No | Pre-existing session identifier |
+| `auth_provider` | `Proc` | No | Callback returning Authorization header value |
+
+### Behavior
+
+- Creates an `Async::HTTP::Client` on connect
+- Sends MCP `initialize` on connect; if no session ID was provided, extracts it from the server response (`serverInfo.sessionId`)
+- Sends `X-Session-ID` header with each request when a session ID is available
+- Calls `auth_provider` for each request to populate the `Authorization` header
+- Exposes `session_id` reader for accessing the current session ID
+- Raises `MCPError` if the `async-http` gem is not installed
+
+### Example
 
 ```ruby
-class CustomTransport
-  def initialize(options)
-    @options = options
-  end
-
-  def connect
-    # Establish connection
-  end
-
-  def disconnect
-    # Close connection
-  end
-
-  def send(message)
-    # Send message to server
-  end
-
-  def receive
-    # Receive message from server
-  end
-end
+transport = RobotLab::MCP::Transports::StreamableHTTP.new(
+  url: "https://server.smithery.ai/neon/mcp",
+  auth_provider: -> { "Bearer #{ENV['MCP_TOKEN']}" }
+)
 
-RobotLab::MCP.register_transport(:custom, CustomTransport)
+transport.connect
+puts transport.session_id  # => assigned by server or pre-configured
 
-# Use custom transport
-{
-  type: "custom",
-  option1: "value1"
-}
+response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
+transport.close
 ```
 
 ## Connection Lifecycle
 
-```mermaid
-sequenceDiagram
-    participant C as Client
-    participant T as Transport
-    participant S as Server
+All transports follow the same lifecycle:
 
-    C->>T: connect()
-    T->>S: Establish connection
-    S-->>T: Connection established
-    T-->>C: Connected
+1. **Create** -- instantiate with configuration hash
+2. **Connect** -- establish connection and perform MCP protocol initialization
+3. **Request/Response** -- send JSON-RPC requests, receive responses
+4. **Close** -- tear down connection and release resources
 
-    C->>T: send(request)
-    T->>S: Forward request
-    S-->>T: Response
-    T-->>C: receive() → response
+Each transport sends the MCP `initialize` message during connect:
 
-    C->>T: disconnect()
-    T->>S: Close connection
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "RobotLab",
+      "version": "<current version>"
+    }
+  }
+}
 ```
 
 ## Error Handling
 
+All transports raise `RobotLab::MCPError` for connection and communication failures:
+
 ```ruby
 begin
-  client.connect
-rescue RobotLab::MCP::ConnectionError => e
-  case e.transport
-  when "stdio"
-    puts "Command failed: #{e.message}"
-  when "websocket"
-    puts "WebSocket error: #{e.message}"
-  when "http"
-    puts "HTTP error: #{e.status} - #{e.message}"
-  end
+  transport.connect
+  transport.send_request(message)
+rescue RobotLab::MCPError => e
+  puts "Transport error: #{e.message}"
+ensure
+  transport.close
 end
 ```
 
+Specific error cases:
+- **Not connected** -- calling `send_request` before `connect` raises `MCPError`
+- **Missing gem** -- WebSocket, SSE, and HTTP transports raise `MCPError` with a `LoadError` message if required gems are not installed
+- **No response** -- Stdio transport raises `MCPError` if the subprocess produces no output
+
 ## See Also
 
 - [MCP Overview](index.md)
 - [MCP Client](client.md)
-- [MCP Server](server.md)
+- [Server Configuration](server.md)

data/docs/api/messages/index.md

@@ -8,60 +8,75 @@ RobotLab uses a structured message system to represent conversations between use
 
 ```ruby
 # User input
-user_msg = UserMessage.new("Hello", thread_id: "123")
+user_msg = UserMessage.new("Hello", session_id: "123")
 
 # Assistant response
-text_msg = TextMessage.new("Hi there!")
+text_msg = TextMessage.new(role: "assistant", content: "Hi there!")
 
 # Tool interaction
-tool_call = ToolCallMessage.new(id: "call_1", name: "get_weather", input: { city: "NYC" })
-tool_result = ToolResultMessage.new(id: "call_1", result: { temp: 72 })
+tool = ToolMessage.new(id: "call_1", name: "get_weather", input: { city: "NYC" })
+tool_call = ToolCallMessage.new(role: "assistant", tools: [tool])
+tool_result = ToolResultMessage.new(tool: tool, content: { data: { temp: 72 } })
 ```
 
 ## Message Hierarchy
 
 ```
 Message (base)
-├── UserMessage      - User input with metadata
-├── TextMessage      - Assistant text response
-├── ToolMessage      - Tool-related messages
-│   ├── ToolCallMessage   - Tool invocation
-│   └── ToolResultMessage - Tool result
-└── SystemMessage    - System prompts
+├── TextMessage         - role + text content
+├── ToolCallMessage     - role + Array<ToolMessage>
+└── ToolResultMessage   - tool + result content
+
+UserMessage             - Standalone (not a Message subclass)
+ToolMessage             - Standalone (not a Message subclass)
 ```
 
 ## Common Interface
 
-All messages implement:
+All Message subclasses implement:
 
 ```ruby
-message.role       # => Symbol (:user, :assistant, :tool)
+message.role       # => String ("user", "assistant", "tool_result")
 message.content    # => String or structured data
+message.type       # => String ("text", "tool_call", "tool_result")
 message.to_h       # => Hash representation
 message.to_json    # => JSON string
 ```
 
+Type and role predicates:
+
+```ruby
+message.text?       # => true if type is "text"
+message.tool_call?  # => true if type is "tool_call"
+message.tool_result? # => true if type is "tool_result"
+message.system?     # => true if role is "system"
+message.user?       # => true if role is "user"
+message.assistant?  # => true if role is "assistant"
+message.stopped?    # => true if stop_reason is "stop"
+message.tool_stop?  # => true if stop_reason is "tool"
+```
+
 ## Classes
 
 | Class | Description |
 |-------|-------------|
-| [UserMessage](user-message.md) | User input with thread and metadata |
-| [TextMessage](text-message.md) | Assistant text response |
-| [ToolCallMessage](tool-call-message.md) | Tool invocation request |
+| [UserMessage](user-message.md) | User input with session and metadata |
+| [TextMessage](text-message.md) | Text message with role (system, user, or assistant) |
+| [ToolCallMessage](tool-call-message.md) | Tool invocation request containing ToolMessage objects |
 | [ToolResultMessage](tool-result-message.md) | Tool execution result |
 
-## Usage in State
+## Usage in Memory
 
-Messages are typically accessed through state:
+Messages are typically accessed through memory:
 
 ```ruby
-state.messages  # => Array<Message>
+memory.messages  # => Array<Message>
 
 # Format for LLM
-state.format_history  # => Array<Hash>
+memory.format_history  # => Array<Message>
 ```
 
 ## See Also
 
-- [State](../core/state.md)
+- [Memory](../core/memory.md)
 - [Message Flow Architecture](../../architecture/message-flow.md)

data/docs/api/messages/text-message.md

@@ -1,24 +1,26 @@
 # TextMessage
 
-Assistant text response.
+Text message from system, user, or assistant.
 
 ## Class: `RobotLab::TextMessage`
 
 ```ruby
-message = TextMessage.new("Hello! How can I help you today?")
+message = TextMessage.new(role: "assistant", content: "Hello! How can I help you today?")
 ```
 
 ## Constructor
 
 ```ruby
-TextMessage.new(content)
+TextMessage.new(role:, content:, stop_reason: nil)
 ```
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `content` | `String` | Response text |
+| `role` | `String` | Message role ("system", "user", or "assistant") |
+| `content` | `String` | The text content |
+| `stop_reason` | `String`, `nil` | Stop reason ("stop" or "tool") |
 
 ## Attributes
 
@@ -28,15 +30,31 @@ TextMessage.new(content)
 message.content  # => String
 ```
 
-The response text.
+The text content.
 
 ### role
 
 ```ruby
-message.role  # => :assistant
+message.role  # => "assistant"
 ```
 
-Always returns `:assistant`.
+Returns a String: `"system"`, `"user"`, or `"assistant"`.
+
+### type
+
+```ruby
+message.type  # => "text"
+```
+
+Always returns `"text"`.
+
+### stop_reason
+
+```ruby
+message.stop_reason  # => "stop" or nil
+```
+
+The stop reason, if any.
 
 ## Methods
 
@@ -52,8 +70,10 @@ Hash representation.
 
 ```ruby
 {
-  role: :assistant,
-  content: "Hello! How can I help you today?"
+  type: "text",
+  role: "assistant",
+  content: "Hello! How can I help you today?",
+  stop_reason: "stop"
 }
 ```
 
@@ -65,34 +85,60 @@ message.to_json  # => String
 
 JSON representation.
 
+### Predicates
+
+```ruby
+message.text?       # => true
+message.tool_call?  # => false
+message.assistant?  # => true (if role is "assistant")
+message.user?       # => false
+message.stopped?    # => true (if stop_reason is "stop")
+```
+
 ## Examples
 
-### Basic Response
+### System Message
+
+```ruby
+message = TextMessage.new(role: "system", content: "You are a helpful assistant")
+message.system?  # => true
+```
+
+### User Message
+
+```ruby
+message = TextMessage.new(role: "user", content: "What's the weather?")
+message.user?  # => true
+```
+
+### Assistant Response
 
 ```ruby
-message = TextMessage.new("Your order has shipped!")
+message = TextMessage.new(
+  role: "assistant",
+  content: "Your order has shipped!",
+  stop_reason: "stop"
+)
+message.assistant?  # => true
+message.stopped?    # => true
 ```
 
 ### In Robot Results
 
 ```ruby
-result = robot.run(state: state)
+result = robot.run("Tell me a joke")
 
-# Extract text messages
-result.output.each do |msg|
-  if msg.is_a?(TextMessage)
-    puts msg.content
-  end
+# The result is a TextMessage when the assistant replies with text
+if result.text?
+  puts result.content
 end
 ```
 
 ### Filtering Text Content
 
 ```ruby
-# Get only text responses from results
-text_responses = state.results.flat_map(&:output).select do |msg|
-  msg.is_a?(TextMessage)
-end.map(&:content)
+# Get only text messages from memory
+text_messages = memory.messages.select(&:text?).map(&:content)
 ```
 
 ## See Also