robot_lab 0.0.7 → 0.0.9

data/docs/api/core/robot.md

@@ -23,13 +23,16 @@ Robot.new(
   description: nil,
   local_tools: [],
   model: nil,
+  provider: nil,
   mcp_servers: [],
   mcp: :none,
   tools: :none,
   on_tool_call: nil,
   on_tool_result: nil,
+  on_content: nil,
   enable_cache: true,
   bus: nil,
+  skills: nil,
   temperature: nil,
   top_p: nil,
   top_k: nil,
@@ -52,13 +55,16 @@ Robot.new(
 | `description` | `String`, `nil` | `nil` | Human-readable description of what the robot does |
 | `local_tools` | `Array` | `[]` | Tools defined locally (`RubyLLM::Tool` subclasses or `RobotLab::Tool` instances) |
 | `model` | `String`, `nil` | `nil` | LLM model ID (falls back to `RobotLab.config.ruby_llm.model`) |
+| `provider` | `String`, `Symbol`, `nil` | `nil` | LLM provider for local providers (e.g., `:ollama`, `:gpustack`). Automatically sets `assume_model_exists: true` |
 | `mcp_servers` | `Array` | `[]` | Legacy MCP server configurations |
 | `mcp` | `Symbol`, `Array` | `:none` | Hierarchical MCP config (`:none`, `:inherit`, or server array) |
 | `tools` | `Symbol`, `Array` | `:none` | Hierarchical tools config (`:none`, `:inherit`, or tool name array) |
 | `on_tool_call` | `Proc`, `nil` | `nil` | Callback invoked when a tool is called |
 | `on_tool_result` | `Proc`, `nil` | `nil` | Callback invoked when a tool returns a result |
+| `on_content` | `Proc`, `nil` | `nil` | Stored streaming callback invoked with each content chunk (see [Streaming](#streaming)) |
 | `enable_cache` | `Boolean` | `true` | Whether to enable semantic caching |
 | `bus` | `TypedBus::MessageBus`, `nil` | `nil` | Optional message bus for inter-robot communication |
+| `skills` | `Symbol`, `Array<Symbol>`, `nil` | `nil` | Skill templates to prepend (see [Skills](#skills)) |
 | `config` | `RunConfig`, `nil` | `nil` | Shared config merged with explicit kwargs (see [RunConfig](#runconfig)) |
 | `temperature` | `Float`, `nil` | `nil` | Controls randomness (0.0-1.0) |
 | `top_p` | `Float`, `nil` | `nil` | Nucleus sampling threshold |
@@ -80,6 +86,7 @@ robot = RobotLab.build(
   context: {},
   enable_cache: true,
   bus: nil,           # Optional TypedBus::MessageBus
+  skills: nil,        # Optional skill templates
   **options           # All other Robot.new parameters
 )
 # => RobotLab::Robot
@@ -95,6 +102,8 @@ If `name` is omitted, it defaults to `"robot"`.
 | `description` | `String`, `nil` | Human-readable description |
 | `template` | `Symbol`, `nil` | Prompt template identifier |
 | `system_prompt` | `String`, `nil` | Inline system prompt |
+| `skills` | `Array<Symbol>`, `nil` | Constructor-provided skill template IDs (nil if none) |
+| `provider` | `String`, `nil` | LLM provider name (e.g., `"ollama"`) — set when using local providers |
 | `local_tools` | `Array` | Locally defined tools |
 | `mcp_clients` | `Hash<String, MCP::Client>` | Connected MCP clients, keyed by server name |
 | `mcp_tools` | `Array<Tool>` | Tools discovered from MCP servers |
@@ -119,7 +128,7 @@ Used by tools like [`AskUser`](tool.md#built-in-askuser) that need terminal IO.
 ### run
 
 ```ruby
-result = robot.run(message, **kwargs)
+result = robot.run(message, **kwargs, &block)
 # => RobotResult
 ```
 
@@ -136,6 +145,9 @@ Primary execution method. Sends a message to the LLM with memory/MCP/tools resol
 | `mcp` | `Symbol`, `Array` | `:none` | Runtime MCP override |
 | `tools` | `Symbol`, `Array` | `:none` | Runtime tools override |
 | `**kwargs` | `Hash` | `{}` | Additional keyword arguments passed to `Agent#ask` |
+| `&block` | `Proc` | `nil` | Per-call streaming block, receives each content chunk |
+
+When both a stored `on_content` callback and a runtime block are provided, both fire (stored first, then runtime block).
 
 **Returns:** `RobotResult`
 
@@ -148,8 +160,8 @@ result = robot.run("What is 2+2?")
 # With runtime memory
 result = robot.run("Summarize the data", memory: { data: report })
 
-# With streaming block
-result = robot.run("Tell me a story") { |event| print event.text }
+# With per-call streaming block
+result = robot.run("Tell me a story") { |chunk| print chunk.content }
 
 # With runtime overrides
 result = robot.run("Help me", mcp: :none, tools: :none)
@@ -230,7 +242,9 @@ robot.call(result)
 # => SimpleFlow::Result
 ```
 
-SimpleFlow step interface. Extracts the message from `result.context[:run_params]`, calls `run`, and wraps the output in a continued `SimpleFlow::Result`.
+SimpleFlow step interface. Extracts the message from `result.context[:run_params]`, calls `run`, and wraps the output in a continued `SimpleFlow::Result`. Automatically records `RobotResult#duration` (elapsed seconds).
+
+If the robot raises any exception during execution, the error is caught and wrapped in a `RobotResult` with the error message as content. This ensures one failing robot does not crash the entire network pipeline.
 
 Override this method in subclasses for custom routing logic (e.g., classifiers).
 
@@ -392,6 +406,142 @@ bot.with_bus(bus1)  # joins bus1
 bot.with_bus(bus2)  # leaves bus1, joins bus2
 ```
 
+### connect_mcp!
+
+```ruby
+robot.connect_mcp!
+# => self
+```
+
+Eagerly connect to configured MCP servers and discover tools. Normally MCP connections are lazy (established on first `run`). Call this to connect early, e.g., to display connection status at startup.
+
+**Returns:** `self`
+
+### failed_mcp_server_names
+
+```ruby
+robot.failed_mcp_server_names
+# => Array<String>
+```
+
+Returns server names that failed to connect. Useful for displaying connection status or deciding whether to retry.
+
+### inject_mcp!
+
+```ruby
+robot.inject_mcp!(clients: mcp_clients, tools: mcp_tools)
+# => self
+```
+
+Inject pre-connected MCP clients and their tools into this robot. Used by host applications that manage MCP connections externally and need to pass them to robots without re-connecting.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `clients` | `Hash<String, MCP::Client>` | Connected MCP clients keyed by server name |
+| `tools` | `Array<Tool>` | Tools discovered from the MCP servers |
+
+**Returns:** `self`
+
+**Example:**
+
+```ruby
+# Host app manages MCP connections
+clients = { "github" => github_client }
+tools   = github_client.list_tools.map { |t| RobotLab::Tool.from_mcp(t) }
+
+robot.inject_mcp!(clients: clients, tools: tools)
+```
+
+### chat
+
+```ruby
+robot.chat
+# => RubyLLM::Chat
+```
+
+Access the underlying `RubyLLM::Chat` instance. Useful for checkpoint/restore operations that need direct access to conversation state.
+
+### messages
+
+```ruby
+robot.messages
+# => Array<RubyLLM::Message>
+```
+
+Return the conversation messages from the underlying chat.
+
+### clear_messages
+
+```ruby
+robot.clear_messages(keep_system: true)
+# => self
+```
+
+Clear conversation messages, optionally keeping the system prompt.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `keep_system` | `Boolean` | `true` | Whether to preserve the system message |
+
+**Returns:** `self`
+
+### replace_messages
+
+```ruby
+robot.replace_messages(messages)
+# => self
+```
+
+Replace conversation messages with a saved set. Useful for checkpoint/restore workflows.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `messages` | `Array<RubyLLM::Message>` | The messages to restore |
+
+**Returns:** `self`
+
+**Example:**
+
+```ruby
+# Save a checkpoint
+saved = robot.messages.dup
+
+# ... later, restore it
+robot.replace_messages(saved)
+```
+
+### chat_provider
+
+```ruby
+robot.chat_provider
+# => String or nil
+```
+
+Return the provider for this robot's chat. Useful for displaying model/provider info without reaching into chat internals.
+
+### mcp_client
+
+```ruby
+robot.mcp_client("github")
+# => MCP::Client or nil
+```
+
+Find an MCP client by server name.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `server_name` | `String` | The MCP server name |
+
+**Returns:** `MCP::Client` or `nil`
+
 ### disconnect
 
 ```ruby
@@ -408,7 +558,7 @@ robot.to_h
 # => Hash
 ```
 
-Returns a hash representation of the robot including name, description, template, system_prompt, local_tools, mcp_tools, mcp_config, tools_config, mcp_servers, model, and bus (true if configured, omitted otherwise).
+Returns a hash representation of the robot including name, description, template, skills, system_prompt, local_tools, mcp_tools, mcp_config, tools_config, mcp_servers, model, and bus (true if configured, omitted otherwise). Nil values are compacted out.
 
 ## Memory Behavior
 
@@ -437,7 +587,7 @@ Front matter supports two categories of keys:
 
 **LLM Config:** `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` — applied to the underlying chat.
 
-**Robot Extras:** `robot_name`, `description`, `tools`, `mcp` — applied to the robot's identity and capabilities. Constructor-provided values always take precedence.
+**Robot Extras:** `robot_name`, `description`, `tools`, `mcp`, `skills` — applied to the robot's identity and capabilities. Constructor-provided values always take precedence.
 
 | Key | Type | Description |
 |-----|------|-------------|
@@ -445,6 +595,40 @@ Front matter supports two categories of keys:
 | `description` | `String` | Human-readable description |
 | `tools` | `Array<String>` | Tool class names resolved via `Object.const_get` |
 | `mcp` | `Array<Hash>` | MCP server configurations |
+| `skills` | `Array<Symbol>` | Skill templates to prepend (recursive, with cycle detection) |
+
+## Skills
+
+Skills compose robot behaviors from reusable templates. Each skill is a standard `.md` template whose prompt body is prepended before the main template. Skills are expanded depth-first with automatic cycle detection.
+
+**Constructor:** `skills:` accepts `Symbol` or `Array<Symbol>`:
+
+```ruby
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  skills: [:clarifier, :json_responder]
+)
+```
+
+**Front matter:** templates can declare skills via `skills:` key:
+
+```markdown
+---
+skills:
+  - clarifier
+  - json_responder
+---
+Main template body here.
+```
+
+Constructor `skills:` and front matter `skills:` are combined (constructor first, then front matter). Skills can nest (a skill can declare its own `skills:` in front matter).
+
+**Config cascade:** skill config merges in processing order (deepest first). Later values override earlier. Constructor kwargs always win.
+
+**Prompt order:** skill bodies are concatenated in expansion order, followed by the main template body. All are joined with `"\n\n"` and set as system instructions via a single `with_instructions` call.
+
+**Cycle detection:** if skills form a cycle, the duplicate is skipped with a logger warning.
 
 ## RunConfig
 
@@ -463,10 +647,78 @@ robot = RobotLab.build(
 robot.config  #=> RunConfig with model: "claude-sonnet-4", temperature: 0.9, ...
 ```
 
-RunConfig fields: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`, `mcp`, `tools`, `on_tool_call`, `on_tool_result`, `bus`, `enable_cache`.
+RunConfig fields: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`, `mcp`, `tools`, `on_tool_call`, `on_tool_result`, `on_content`, `bus`, `enable_cache`.
 
 See [Configuration: RunConfig](../../getting-started/configuration.md#runconfig-shared-operational-defaults) for full details.
 
+## Streaming
+
+Robots support two complementary approaches for streaming LLM content in real-time.
+
+### The Chunk Object
+
+Both callbacks and blocks receive a [`RubyLLM::Chunk`](https://rubyllm.com/streaming/#basic-streaming) (subclass of `RubyLLM::Message`). Key accessors:
+
+| Accessor | Type | Description |
+|----------|------|-------------|
+| `content` | `String`, `nil` | The text delta for this chunk (`nil` on tool-call or usage-only chunks) |
+| `role` | `Symbol` | Always `:assistant` |
+| `model_id` | `String` | The LLM model ID |
+| `tool_calls` | `Array`, `nil` | Tool call deltas (partial JSON arguments) |
+| `tool_call?` | `Boolean` | Whether this chunk contains tool call data |
+| `thinking` | `Thinking`, `nil` | Extended thinking delta (Anthropic only) |
+| `input_tokens` | `Integer`, `nil` | Input token count (populated on final chunk) |
+| `output_tokens` | `Integer`, `nil` | Output token count (populated on final chunk) |
+| `cached_tokens` | `Integer`, `nil` | Cached prompt tokens (final chunk) |
+
+Most chunks carry only `content` (the text delta). The final chunk(s) carry token usage counts. Tool call chunks have `tool_calls` instead of `content`.
+
+### Stored Callback (`on_content:`)
+
+Wired at build time via constructor or RunConfig. Fires on every `run()` call automatically:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { broadcast(chunk.content) }
+)
+robot.run("Tell me a story")  # streams via stored callback
+```
+
+The `on_content` callback participates in the RunConfig cascade:
+
+```ruby
+config = RobotLab::RunConfig.new(
+  on_content: ->(chunk) { log(chunk.content) }
+)
+robot = RobotLab.build(name: "bot", config: config)
+```
+
+Constructor `on_content:` overrides RunConfig `on_content`.
+
+### Per-Call Block
+
+Pass a block to `run()` for one-off streaming:
+
+```ruby
+robot.run("Tell me a story") { |chunk| print chunk.content }
+```
+
+### Both Together
+
+When both exist, both fire — stored callback first, then runtime block:
+
+```ruby
+robot = RobotLab.build(
+  name: "bot",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { log(chunk.content) }
+)
+robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
+# log() fires first, then stream_to_client()
+```
+
 ## Configuration Hierarchy
 
 Tools and MCP servers use hierarchical resolution: **runtime > robot > network > global config**.
@@ -542,6 +794,18 @@ robot = RobotLab.build(
 result = robot.run("What is 15 * 7?")
 ```
 
+### Robot with Local Provider
+
+```ruby
+robot = RobotLab.build(
+  name: "local_bot",
+  model: "llama3.2",
+  provider: :ollama,
+  system_prompt: "You are helpful."
+)
+result = robot.run("Hello!")
+```
+
 ### Robot with MCP
 
 ```ruby
@@ -559,6 +823,18 @@ result = robot.run("Search for popular Ruby repos")
 robot.disconnect
 ```
 
+### Robot with Skills
+
+```ruby
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  skills: [:clarifier, :safety, :json_responder],
+  context: { company: "Acme Corp" }
+)
+result = robot.run("I need help with my order")
+```
+
 ### Bare Robot with Chaining
 
 ```ruby
@@ -628,6 +904,6 @@ bot.send_message(to: :someone, content: "Hello!")
 
 ## See Also
 
-- [Building Robots Guide](../../guides/building-robots.md)
+- [Building Robots Guide](../../guides/building-robots.md) (includes [Composable Skills](../../guides/building-robots.md#composable-skills))
 - [Tool](tool.md)
 - [Network](network.md)

data/docs/api/core/tool.md

@@ -4,7 +4,7 @@ Callable function that robots can use to interact with external systems.
 
 ## Class: `RobotLab::Tool < RubyLLM::Tool`
 
-RobotLab::Tool inherits from RubyLLM::Tool, adding a `robot:` constructor parameter and a `Tool.create` factory for dynamic tools.
+RobotLab::Tool inherits from RubyLLM::Tool, adding a `robot:` constructor parameter, a `Tool.create` factory for dynamic tools, and graceful error handling that returns plain-text errors to the LLM instead of crashing the run.
 
 ### Subclass Pattern
 
@@ -51,6 +51,15 @@ Tool.new(robot: nil)
 
 ## Class Methods
 
+### raise_on_error / raise_on_error?
+
+```ruby
+MyTool.raise_on_error = true
+MyTool.raise_on_error?  # => true
+```
+
+Per-class flag controlling whether `call` propagates exceptions from `execute` instead of catching them. Defaults to `false`. Does not affect other tool classes.
+
 ### Tool.create
 
 Factory for dynamic tools (MCP wrappers, inline tools).
@@ -169,7 +178,24 @@ Whether this is an MCP-provided tool.
 result = tool.call(args_hash)
 ```
 
-Inherited from RubyLLM::Tool. Converts string keys to symbols and calls `execute(**args)`.
+Overrides `RubyLLM::Tool#call` with graceful error handling. Converts string keys to symbols and calls `execute(**args)`. If `execute` raises a `StandardError`, the error is caught and returned as a plain-text string the LLM can reason about:
+
+```
+Error (tool_name): exception message
+```
+
+The error is also logged via `RobotLab.config.logger` at `:warn` level.
+
+To propagate exceptions instead of catching them (for critical tools), set `raise_on_error` on the class:
+
+```ruby
+class CriticalTool < RobotLab::Tool
+  self.raise_on_error = true
+  # ...
+end
+```
+
+`raise_on_error` is per-class (defaults to `false`) and does not affect other tool classes.
 
 ### params_schema
 

data/docs/api/mcp/client.md

@@ -36,6 +36,7 @@ Accepts either a `Server` instance or a Hash configuration. When a Hash is provi
 |-----|------|----------|-------------|
 | `name` | `String` | Yes | Server identifier |
 | `transport` | `Hash` | Yes | Transport configuration (must include `type`) |
+| `timeout` | `Numeric` | No | Request timeout in seconds (default: 15). Propagated to the transport layer |
 
 **Raises:** `ArgumentError` if the config is neither a `Server` nor a `Hash`.
 

data/docs/api/mcp/server.md

@@ -13,31 +13,42 @@ server = RobotLab::MCP::Server.new(
   name: "filesystem",
   transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
 )
+
+# With custom timeout
+server = RobotLab::MCP::Server.new(
+  name: "slow_server",
+  transport: { type: "stdio", command: "heavy-mcp-server" },
+  timeout: 30
+)
 ```
 
 ## Constructor
 
 ```ruby
-Server.new(name:, transport:)
+Server.new(name:, transport:, timeout: nil, **_extra)
 ```
 
 **Parameters:**
 
-| Name | Type | Description |
-|------|------|-------------|
-| `name` | `String` | Unique server identifier |
-| `transport` | `Hash` | Transport configuration (must include `type`) |
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `String` | **required** | Unique server identifier |
+| `transport` | `Hash` | **required** | Transport configuration (must include `type`) |
+| `timeout` | `Numeric`, `nil` | `15` | Request timeout in seconds. Values >= 1000 are auto-converted from milliseconds. Minimum 1 second |
 
 **Raises:** `ArgumentError` if:
 - The transport type is not one of the valid types
 - A stdio transport is missing the `:command` key
 - A network transport (ws, websocket, sse, streamable-http, http) is missing the `:url` key
 
-## Valid Transport Types
+## Constants
 
 ```ruby
 RobotLab::MCP::Server::VALID_TRANSPORT_TYPES
 # => ["stdio", "sse", "ws", "websocket", "streamable-http", "http"]
+
+RobotLab::MCP::Server::DEFAULT_TIMEOUT
+# => 15  (seconds)
 ```
 
 ## Attributes
@@ -58,6 +69,14 @@ server.transport  # => Hash
 
 The normalized transport configuration hash (keys are symbols, type is downcased).
 
+### timeout
+
+```ruby
+server.timeout  # => Numeric
+```
+
+Request timeout in seconds. Defaults to `DEFAULT_TIMEOUT` (15). Values >= 1000 passed to the constructor are auto-converted from milliseconds to seconds. The minimum is 1 second.
+
 ## Methods
 
 ### transport_type
@@ -71,10 +90,10 @@ Returns the transport type string (e.g., `"stdio"`, `"ws"`, `"sse"`).
 ### to_h
 
 ```ruby
-server.to_h  # => { name: "...", transport: { ... } }
+server.to_h  # => { name: "...", transport: { ... }, timeout: 15 }
 ```
 
-Converts the server configuration to a hash representation.
+Converts the server configuration to a hash representation (includes `timeout`).
 
 ## Transport Configuration Options
 

data/docs/api/mcp/transports.md

@@ -21,7 +21,10 @@ All transports inherit from `RobotLab::MCP::Transports::Base` and implement:
 
 ```ruby
 class RobotLab::MCP::Transports::Base
-  attr_reader :config  # => Hash (symbolized keys)
+  DEFAULT_TIMEOUT = 15  # seconds
+
+  attr_reader :config   # => Hash (symbolized keys, :timeout removed)
+  attr_reader :timeout  # => Numeric (seconds, extracted from config)
 
   def connect        # Establish connection, returns self
   def send_request(message)  # Send JSON-RPC message, returns Hash response
@@ -30,11 +33,13 @@ class RobotLab::MCP::Transports::Base
 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.
+
 ## Stdio Transport
 
 **Class:** `RobotLab::MCP::Transports::Stdio`
 
-Spawns a subprocess and communicates via stdin/stdout using JSON-RPC messages (one per line). Automatically sends MCP `initialize` and `notifications/initialized` on connect.
+Spawns a subprocess and communicates via stdin/stdout using JSON-RPC messages (one per line). Automatically sends MCP `initialize` and `notifications/initialized` on connect. All blocking I/O is wrapped with `Timeout.timeout` so a missing or hung server cannot block the caller forever.
 
 ### Configuration
 
@@ -43,7 +48,8 @@ Spawns a subprocess and communicates via stdin/stdout using JSON-RPC messages (o
   type: "stdio",
   command: "mcp-server-filesystem",      # Required: executable command
   args: ["--root", "/data"],             # Optional: command arguments
-  env: { "DEBUG" => "true" }             # Optional: environment variables
+  env: { "DEBUG" => "true" },            # Optional: environment variables
+  timeout: 10                            # Optional: request timeout in seconds (default: 15)
 }
 ```
 
@@ -52,14 +58,18 @@ Spawns a subprocess and communicates via stdin/stdout using JSON-RPC messages (o
 | `command` | `String` | Yes | Executable command to spawn |
 | `args` | `Array<String>` | No | Command arguments |
 | `env` | `Hash` | No | Environment variables (merged with current env) |
+| `timeout` | `Numeric` | No | Request timeout in seconds (default: 15) |
 
 ### Behavior
 
 - Uses `Open3.popen3` to spawn the subprocess
+- Verifies the process actually started (raises `MCPError` if it exits immediately)
 - Writes JSON-RPC messages to stdin (one per line)
 - Reads responses from stdout, skipping notifications (messages without `id`)
+- All blocking reads are wrapped with `Timeout.timeout` — raises `MCPError` if the server does not respond within the timeout period
 - `connected?` returns `true` when the subprocess is alive
-- `close` terminates stdin, stdout, stderr, and kills the subprocess
+- `close` calls `cleanup_process` to reliably close stdin, stdout, stderr and kill the subprocess
+- Handles `Errno::ENOENT` (command not found), `Errno::EPIPE` / `IOError` (broken pipe / connection lost), and `Timeout::Error` (hung server) with clear error messages
 
 ### Example
 
@@ -67,7 +77,8 @@ Spawns a subprocess and communicates via stdin/stdout using JSON-RPC messages (o
 transport = RobotLab::MCP::Transports::Stdio.new(
   command: "mcp-server-filesystem",
   args: ["--root", "/data"],
-  env: { "DEBUG" => "true" }
+  env: { "DEBUG" => "true" },
+  timeout: 10
 )
 
 transport.connect
@@ -243,7 +254,11 @@ 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
+- **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
+- **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
 
 ## See Also
 

data/docs/architecture/core-concepts.md

@@ -9,7 +9,7 @@ A Robot is the primary unit of computation in RobotLab. It is a subclass of `Rub
 - A unique identity (name, description)
 - A personality (system prompt and/or template)
 - Capabilities (tools, MCP connections)
-- Model and inference configuration
+- Model, provider, and inference configuration
 - Inherent memory (key-value store)
 
 ### Robot Anatomy

data/docs/architecture/robot-execution.md

@@ -164,7 +164,8 @@ def build_result(response, _memory)
     robot_name: @name,
     output: output,
     tool_calls: normalize_tool_calls(tool_calls),
-    stop_reason: response.respond_to?(:stop_reason) ? response.stop_reason : nil
+    stop_reason: response.respond_to?(:stop_reason) ? response.stop_reason : nil,
+    raw: response
   )
 end
 ```
@@ -182,9 +183,12 @@ result.tool_calls       # => [ToolResultMessage, ...]
 result.stop_reason      # => "stop" or nil
 result.created_at       # => Time
 result.id               # => UUID string
+result.duration         # => Float or nil (elapsed seconds, set in pipeline execution)
+result.raw              # => raw LLM response object
 
 # Convenience methods
 result.last_text_content  # => "Hi there!" (last text message content)
+result.reply              # => alias for last_text_content
 result.has_tool_calls?    # => false
 result.stopped?           # => true
 ```
@@ -275,17 +279,31 @@ sequenceDiagram
     Robot-->>SF: result.continue(robot_result)
 ```
 
-The `Task` wrapper deep-merges per-task configuration (context, mcp, tools) before delegating to the robot's `call`. The base `Robot#call` extracts the message and calls `run`:
+The `Task` wrapper deep-merges per-task configuration (context, mcp, tools) before delegating to the robot's `call`. The base `Robot#call` extracts the message, calls `run`, and records the elapsed time in `RobotResult#duration`. If the robot raises any exception, the error is caught and wrapped in a `RobotResult` so one failing robot does not crash the entire pipeline:
 
 ```ruby
 def call(result)
   run_context = extract_run_context(result)
   message = run_context.delete(:message)
+
+  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   robot_result = run(message, **run_context)
+  robot_result.duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
   result
     .with_context(@name.to_sym, robot_result)
     .continue(robot_result)
+rescue Exception => e
+  # Error is wrapped in a RobotResult with the elapsed duration
+  error_result = RobotResult.new(
+    robot_name: @name,
+    output: [TextMessage.new(role: 'assistant', content: "Error: #{e.class}: #{e.message}")]
+  )
+  error_result.duration = elapsed
+
+  result
+    .with_context(@name.to_sym, error_result)
+    .continue(error_result)
 end
 ```