robot_lab 0.2.1 → 0.2.7

data/docs/api/mcp/transports.md

@@ -8,12 +8,19 @@ Transports handle the low-level communication between `MCP::Client` and external
 
 RobotLab provides four built-in transport types:
 
-| 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 |
+| Transport | Class | Use Case | Status |
+|-----------|-------|----------|--------|
+| Stdio | `Transports::Stdio` | Local subprocess servers | Fully working |
+| WebSocket | `Transports::WebSocket` | Real-time bidirectional | **Broken** — see below |
+| SSE | `Transports::SSE` | Server-sent events | Working, but `connect` reports success unconditionally |
+| Streamable HTTP | `Transports::StreamableHTTP` | HTTP with session support | Working, but `connect` reports success unconditionally |
+
+> **Read this before using a non-stdio transport.** Only `Stdio` performs its
+> connection and MCP handshake synchronously. The other three wrap that work in
+> an `Async do ... end` block whose result is never awaited, so any error raised
+> inside — including a refused TCP connection — is discarded. `connect` returns
+> `self` regardless. The specific consequences are documented per transport
+> below.
 
 ## Base Interface
 
@@ -35,6 +42,12 @@ end
 
 The `timeout` is extracted from the config hash during initialization (and removed from `config`). If not provided, it defaults to `DEFAULT_TIMEOUT` (15 seconds). The timeout is propagated from `MCP::Server` through `MCP::Client` to the transport.
 
+**Only `Stdio` enforces the timeout.** `SSE`, `WebSocket`, and `StreamableHTTP`
+store `@timeout` and expose it through the `timeout` reader, but never reference
+it — their requests are not time-bounded by this value. If you need a bound on a
+non-stdio transport, wrap the call yourself, or route the client through an
+`MCP::ConnectionPoller` (stdio only).
+
 ## Stdio Transport
 
 **Class:** `RobotLab::MCP::Transports::Stdio`
@@ -90,7 +103,23 @@ transport.close
 
 **Class:** `RobotLab::MCP::Transports::WebSocket`
 
-Uses `async-websocket` for non-blocking bidirectional communication. Requires the `async-websocket` gem.
+Intended to use `async-websocket` for non-blocking bidirectional communication.
+
+> **This transport does not currently work.** `connect` calls
+> `Async::HTTP::Endpoint.parse`, but only requires `async` and
+> `async/websocket/client` — the `Async::HTTP` namespace is never loaded, so the
+> call raises `NameError`. That happens inside an un-awaited `Async` block, so
+> the error is swallowed: `connect` returns `self`, no `MCPError` is raised, and
+> `connected?` stays `false`. Every subsequent `send_request` then raises
+> `MCPError, "Not connected"`.
+>
+> Verified: `WebSocket.new(url: "ws://127.0.0.1:9/ws").connect.connected?` is
+> `false` with no exception surfacing.
+>
+> The rescue on `connect` only catches `LoadError`, which is raised if
+> `async-websocket` is missing. Because of the `Async::HTTP::Endpoint` call, this
+> transport also needs `async-http` even once `async-websocket` is installed —
+> both are declared as runtime dependencies of the gem.
 
 ### Configuration
 
@@ -107,10 +136,16 @@ Uses `async-websocket` for non-blocking bidirectional communication. Requires th
 
 ### Behavior
 
-- 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
+- Intends to use `Async::WebSocket::Client.connect` within an `Async` block, then
+  send the MCP `initialize` handshake
+- In practice the block raises `NameError` on `Async::HTTP::Endpoint` before the
+  connection is created, and the un-awaited block discards it
+- `send_request` sends JSON-RPC messages as JSON strings and reads the response
+  inside an awaited `Async` block — but it raises `MCPError, "Not connected"`
+  because `@connected` was never set
+- `connect` raises `MCPError` only for `LoadError` (missing `async-websocket`);
+  it does not raise for a connection failure
+- `close` is a no-op while `@connected` is `false`
 
 ### Example
 
@@ -120,8 +155,10 @@ transport = RobotLab::MCP::Transports::WebSocket.new(
 )
 
 transport.connect
-response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
-transport.close
+transport.connected?  # => false, even against a live server
+
+# Raises MCPError: "Not connected"
+transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
 ```
 
 ## SSE Transport
@@ -145,10 +182,20 @@ Uses `async-http` for HTTP-based communication. Sends requests via HTTP POST and
 
 ### Behavior
 
-- Creates an `Async::HTTP::Client` on connect
+- Creates an `Async::HTTP::Client` on connect, then sends the MCP `initialize`
+  handshake
 - 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
+- Raises `MCPError` if the `async-http` gem is not installed (`LoadError` only)
+- The `timeout` from the server config is stored but never applied
+
+> **`connect` always reports success.** `@connected = true` is assigned *before*
+> `send_initialize` runs, and the whole sequence is inside an un-awaited `Async`
+> block. Against an unreachable host, `connect` returns `self`, `connected?`
+> returns `true`, and the handshake failure is never surfaced. The first real
+> `send_request` is where the failure appears.
+>
+> Verified: `SSE.new(url: "http://127.0.0.1:9/sse").connect.connected?` is `true`.
 
 ### Example
 
@@ -158,6 +205,8 @@ transport = RobotLab::MCP::Transports::SSE.new(
 )
 
 transport.connect
+# connected? is true here whether or not the server exists
+
 response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
 transport.close
 ```
@@ -192,7 +241,17 @@ HTTP-based transport with session management and optional authentication. Suppor
 - 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
+- Raises `MCPError` if the `async-http` gem is not installed (`LoadError` only)
+- The `timeout` from the server config is stored but never applied
+
+> **`connect` always reports success**, for the same reason as SSE:
+> `@connected = true` precedes `send_initialize`, and the enclosing `Async` block
+> is never awaited. `connected?` returns `true` against an unreachable host, and
+> `session_id` stays at whatever you configured (`nil` if you configured nothing)
+> because the handshake result was discarded.
+>
+> Verified: `StreamableHTTP.new(url: "http://127.0.0.1:9/mcp").connect` yields
+> `connected? == true`, `session_id == nil`.
 
 ### Example
 
@@ -203,7 +262,7 @@ transport = RobotLab::MCP::Transports::StreamableHTTP.new(
 )
 
 transport.connect
-puts transport.session_id  # => assigned by server or pre-configured
+puts transport.session_id  # => pre-configured value, or nil until a request lands
 
 response = transport.send_request({ jsonrpc: "2.0", id: 1, method: "tools/list" })
 transport.close
@@ -211,14 +270,26 @@ transport.close
 
 ## Connection Lifecycle
 
-All transports follow the same lifecycle:
+All transports expose the same four-step lifecycle:
 
 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
 
-Each transport sends the MCP `initialize` message during connect:
+Step 2 behaves differently per transport:
+
+| Transport | `connect` is synchronous | Errors surface from `connect` | `connected?` reflects reality |
+|-----------|--------------------------|-------------------------------|-------------------------------|
+| `Stdio` | Yes | Yes (`MCPError`) | Yes — also checks the process is alive |
+| `SSE` | No (un-awaited `Async`) | No | No — always `true` after `connect` |
+| `StreamableHTTP` | No (un-awaited `Async`) | No | No — always `true` after `connect` |
+| `WebSocket` | No (un-awaited `Async`) | No | No — always `false` after `connect` |
+
+Only `Stdio` gives you a trustworthy answer at connect time. For the other three,
+treat the first `send_request` as the real connection test.
+
+Each transport builds the same MCP `initialize` message during connect:
 
 ```json
 {
@@ -252,11 +323,12 @@ 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
+- **Not connected** -- calling `send_request` before `connect` raises `MCPError` (all transports)
+- **Missing gem** -- WebSocket, SSE, and HTTP transports raise `MCPError` with a `LoadError` message if the required gem (`async-websocket` / `async-http`) is not installed. This is the *only* error `connect` re-raises on those three
+- **Connection refused / unreachable host** -- **not** reported by SSE, WebSocket, or StreamableHTTP `connect`; the error is discarded with the un-awaited `Async` block
 - **No response** -- Stdio transport raises `MCPError` if the subprocess produces no output (EOF on stdout)
 - **Command not found** -- Stdio transport raises `MCPError` with the original `Errno::ENOENT` message
-- **Timeout** -- Stdio transport raises `MCPError` if the server does not respond within the configured timeout
+- **Timeout** -- Stdio transport raises `MCPError` if the server does not respond within the configured timeout. No other transport enforces a timeout
 - **Broken pipe** -- Stdio transport raises `MCPError` and marks itself disconnected on `Errno::EPIPE` or `IOError`
 - **Immediate exit** -- Stdio transport raises `MCPError` if the server process exits immediately after spawn
 

data/docs/api/messages/index.md

@@ -27,22 +27,45 @@ Message (base)
 ├── ToolCallMessage     - role + Array<ToolMessage>
 └── ToolResultMessage   - tool + result content
 
-UserMessage             - Standalone (not a Message subclass)
-ToolMessage             - Standalone (not a Message subclass)
+UserMessage             - Standalone PORO (superclass Object)
+ToolMessage             - Standalone PORO (superclass Object)
 ```
 
+`UserMessage` and `ToolMessage` are plain objects — their superclass is `Object`,
+not `Message`. They do not respond to `type`, `role`, or any of the predicates
+below.
+
 ## Common Interface
 
 All Message subclasses implement:
 
 ```ruby
-message.role       # => String ("user", "assistant", "tool_result")
+message.role       # => String ("system", "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
 ```
 
+Valid values are fixed by constants on `Message`, and the constructor raises
+`ArgumentError` for anything else:
+
+```ruby
+RobotLab::Message::VALID_TYPES         # => ["text", "tool_call", "tool_result"]
+RobotLab::Message::VALID_ROLES         # => ["system", "user", "assistant", "tool_result"]
+RobotLab::Message::VALID_STOP_REASONS  # => ["tool", "stop"]
+```
+
+### Nil keys and `to_h`
+
+`Message#to_h` — used as-is by `TextMessage` — ends in `.compact`, so any key
+whose value is `nil` is **absent** from the hash, not present with a `nil` value.
+A `TextMessage` built without a `stop_reason` produces a three-key hash. The same
+applies to `UserMessage#to_h`.
+
+`ToolCallMessage`, `ToolResultMessage`, and `ToolMessage` override `to_h` without
+compacting, so their keys are always present.
+
 Type and role predicates:
 
 ```ruby

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

@@ -64,17 +64,17 @@ The stop reason, if any.
 message.to_h  # => Hash
 ```
 
-Hash representation.
+Hash representation. Inherited from `Message#to_h`, which ends in `.compact` — a
+`nil` `stop_reason` is **omitted** rather than serialized as `nil`.
 
 **Returns:**
 
 ```ruby
-{
-  type: "text",
-  role: "assistant",
-  content: "Hello! How can I help you today?",
-  stop_reason: "stop"
-}
+TextMessage.new(role: "assistant", content: "Hello! How can I help you today?").to_h
+# => { type: "text", role: "assistant", content: "Hello! How can I help you today?" }
+
+TextMessage.new(role: "assistant", content: "Done.", stop_reason: "stop").to_h
+# => { type: "text", role: "assistant", content: "Done.", stop_reason: "stop" }
 ```
 
 ### to_json
@@ -125,13 +125,35 @@ message.stopped?    # => true
 
 ### In Robot Results
 
+`Robot#run` returns a `RobotResult`, **not** a `TextMessage`. `RobotResult` has no
+`text?` and no `content` — calling either raises `NoMethodError`. Read the reply
+with `last_text_content` (aliased as `reply`):
+
 ```ruby
 result = robot.run("Tell me a joke")
 
-# The result is a TextMessage when the assistant replies with text
-if result.text?
-  puts result.content
-end
+puts result.last_text_content   # => the assistant's text
+puts result.reply               # => same thing
+result.stopped?                 # => true whenever there are no tool calls
+result.has_tool_calls?          # => whether the final message carried tool calls
+```
+
+!!! note "`RobotResult#stopped?` is not driven by `stop_reason`"
+    A `RobotResult` produced by `Robot#run` always has `stop_reason == nil`
+    (`RubyLLM::Message` does not define the method, so `build_result` falls back
+    to `nil`), and the `TextMessage` it wraps is built without a `stop_reason`
+    too. `stopped?` therefore reduces to `!has_tool_calls?` — it never becomes
+    true because a `stop_reason` of `"stop"` was reported. The
+    `stop_reason: "stop"` form shown above only applies to `TextMessage`
+    instances you construct yourself.
+
+`result.output` is an `Array` holding a single `TextMessage` rebuilt from the
+final response text — it is not the full turn:
+
+```ruby
+msg = result.output.first
+msg.text?      # => true
+msg.content    # => the assistant's text
 ```
 
 ### Filtering Text Content

data/docs/api/messages/tool-call-message.md

@@ -24,22 +24,44 @@ ToolCallMessage.new(role:, tools:, stop_reason: nil)
 | Name | Type | Description |
 |------|------|-------------|
 | `role` | `String` | Message role (typically "assistant") |
-| `tools` | `Array<ToolMessage>` | Array of tool call objects |
+| `tools` | `Array<ToolMessage, Hash>` | Tool calls; plain Hashes are normalized via `ToolMessage.from_hash` |
 | `stop_reason` | `String`, `nil` | Stop reason (defaults to "tool") |
 
+Each entry in `tools` may be a `ToolMessage` **or** a Hash. Anything else raises
+`ArgumentError: Invalid tool: must be ToolMessage or Hash`. The `tools` reader
+always returns `ToolMessage` objects.
+
+```ruby
+ToolCallMessage.new(
+  role: "assistant",
+  tools: [{ id: "call_1", name: "get_weather", arguments: { city: "NYC" } }]
+).tools.first.input
+# => { city: "NYC" }
+```
+
+`ToolMessage.from_hash` symbolizes keys and accepts either `input:` or
+`arguments:` for the parameter hash (`input` wins), defaulting to `{}` when
+neither is present. This makes raw provider tool-call payloads usable directly.
+
 ## ToolMessage
 
-Each tool call is represented by a standalone `ToolMessage` object:
+Each tool call is represented by a standalone `ToolMessage` object. It is a plain
+Ruby object — its superclass is `Object`, **not** `Message` — so it has no
+`type`, `role`, or predicate methods:
 
 ```ruby
 ToolMessage.new(id:, name:, input:)
+ToolMessage.from_hash(hash)
 ```
 
 | Name | Type | Description |
 |------|------|-------------|
 | `id` | `String` | Unique call identifier |
 | `name` | `String` | Tool name |
-| `input` | `Hash` | Tool parameters |
+| `input` | `Hash`, `nil` | Tool parameters; `nil` becomes `{}` |
+
+`ToolMessage#to_h` returns `{ type: "tool", id:, name:, input: }`. It is not
+compacted, so every key is always present.
 
 ## Attributes
 
@@ -91,7 +113,8 @@ Defaults to `"tool"` indicating the conversation stopped for tool execution.
 message.to_h  # => Hash
 ```
 
-Hash representation.
+Hash representation. `ToolCallMessage` overrides `Message#to_h` and does **not**
+compact, so all four keys are always present (`content` is not included at all).
 
 **Returns:**
 

data/docs/api/messages/tool-result-message.md

@@ -23,10 +23,26 @@ ToolResultMessage.new(tool:, content:, stop_reason: nil)
 
 | Name | Type | Description |
 |------|------|-------------|
-| `tool` | `ToolMessage` | The tool call that was executed |
+| `tool` | `ToolMessage`, `Hash` | The tool call that was executed; a Hash is normalized via `ToolMessage.from_hash` |
 | `content` | `Hash` | Result with `:data` key (success) or `:error` key (failure) |
 | `stop_reason` | `String`, `nil` | Stop reason (defaults to "tool") |
 
+`tool:` accepts a plain Hash as well as a `ToolMessage`; anything else raises
+`ArgumentError: Invalid tool: must be ToolMessage or Hash`. As with
+`ToolCallMessage`, `from_hash` symbolizes keys and accepts `input:` or
+`arguments:` for the parameter hash.
+
+```ruby
+ToolResultMessage.new(
+  tool: { id: "call_1", name: "get_weather", arguments: { city: "NYC" } },
+  content: { data: { temperature: 72 } }
+).tool.input
+# => { city: "NYC" }
+```
+
+`role` is hard-coded to `"tool_result"` — the value you pass for `tool:` has no
+bearing on it.
+
 ## Attributes
 
 ### tool
@@ -77,7 +93,9 @@ Defaults to `"tool"`.
 message.success?  # => Boolean
 ```
 
-Returns `true` if the content contains a `:data` key.
+Returns `true` if `content` is a Hash containing the **symbol** key `:data`.
+`content` is stored verbatim — it is not symbolized — so a result built with
+`content: { "data" => ... }` reports `success? == false` and `data == nil`.
 
 ### error?
 
@@ -85,7 +103,7 @@ Returns `true` if the content contains a `:data` key.
 message.error?  # => Boolean
 ```
 
-Returns `true` if the content contains an `:error` key.
+Returns `true` if `content` is a Hash containing the **symbol** key `:error`.
 
 ### data
 
@@ -109,7 +127,8 @@ Returns the error message if there was an error, `nil` otherwise.
 message.to_h  # => Hash
 ```
 
-Hash representation.
+Hash representation. `ToolResultMessage` overrides `Message#to_h` and does
+**not** compact, so all five keys are always present.
 
 **Returns:**
 

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

@@ -89,19 +89,38 @@ Message creation timestamp.
 message.to_h  # => Hash
 ```
 
-Hash representation.
+Hash representation. The hash ends in `.compact`, so keys whose value is `nil`
+are **omitted** — a message built without `session_id:` or `system_prompt:` has
+no such keys at all. `metadata` always survives because it defaults to `{}`.
+
+`created_at` is serialized with `Time#iso8601`, which carries the **local** UTC
+offset. It is not normalized to `Z`/UTC.
 
 **Returns:**
 
 ```ruby
-{
-  content: "What's my order status?",
+UserMessage.new(
+  "What's my order status?",
   session_id: "session_123",
   system_prompt: "Be concise",
-  metadata: { source: "web" },
-  id: "uuid-here",
-  created_at: "2024-01-15T10:30:00Z"
-}
+  metadata: { source: "web" }
+).to_h
+# => {
+#      content: "What's my order status?",
+#      session_id: "session_123",
+#      system_prompt: "Be concise",
+#      metadata: { source: "web" },
+#      id: "uuid-here",
+#      created_at: "2026-07-31T13:04:42-05:00"
+#    }
+
+UserMessage.new("hi").to_h
+# => {
+#      content: "hi",
+#      metadata: {},
+#      id: "uuid-here",
+#      created_at: "2026-07-31T13:04:42-05:00"
+#    }
 ```
 
 ### to_json
@@ -134,7 +153,18 @@ Returns the content string.
 UserMessage.from(input)  # => UserMessage
 ```
 
-Creates a `UserMessage` from a String, Hash, or existing `UserMessage`.
+Normalizes any input into a `UserMessage`:
+
+| Input | Result |
+|-------|--------|
+| `UserMessage` | Returned unchanged (same object) |
+| `String` | `new(input)` |
+| `Hash` | Keys symbolized, then `new(content, session_id:, system_prompt:, metadata:, id:)` |
+| `TextMessage` | `new(input.content)` — role and stop reason are dropped |
+| anything else | `new(input.to_s)` |
+
+There is no "unsupported input" branch: `from` never raises for an unrecognized
+type, it falls through to `to_s`.
 
 ## Examples
 
@@ -187,6 +217,13 @@ msg = UserMessage.from(content: "Hello!", session_id: "123")
 
 # From an existing UserMessage (returns as-is)
 msg = UserMessage.from(existing_message)
+
+# From a TextMessage (only the content is carried over)
+msg = UserMessage.from(TextMessage.new(role: "user", content: "Hello!"))
+msg.content  # => "Hello!"
+
+# Anything else falls back to to_s
+UserMessage.from(42).content  # => "42"
 ```
 
 ## See Also