robot_lab 0.0.8 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37a044eb81a0e5c56aa7c5c00f9b4eff600c56eecda8bb2deb18058919a18267
-  data.tar.gz: a48253bbceb5ac99f1babf9c4538045886e038fb0c4a827b96b219b5363bf5c8
+  metadata.gz: f4b2a3fafbdf3a54de3044b57597b42d86c68bd2afdad6ce866ac82483e61091
+  data.tar.gz: 5137cff56485a26fabe5ab6606b144c4c3c21c1673ecec1d2254a392e015c25c
 SHA512:
-  metadata.gz: 9f84d7c82598d281e8c88a4e67b2b0c13bac1142e8dae9834a1b0e84d1055e16837c62b452398da615d477aec834b153ca74f6313c67b806fe174aacd3a0999b
-  data.tar.gz: 549afa0eb2e622ad8caf0d928559bb881b3f1307d2e427074a2f96f943418784e580ef9d5b2a06534f9ec57873682189ec6890cd0ed1790e19b66c159fff572e
+  metadata.gz: 33045f27ec803094a020caee4133c1d6c65887446330c294d9a9babd56a0fe7e71979fe0d032c2421488d1dcae886ad784a78dae579ba01b2786b5f9f91c0172
+  data.tar.gz: 5554296590bfb3dea031c95090ef8a47e946ac1c7a92b3efc6924439f55df7267e0b04d385e2332ea827099c37688c4988aa908caf5bb9d2f21eabc2c50c3167

data/CHANGELOG.md

@@ -8,6 +8,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.11] - 2026-04-14
+
+### Added
+
+- **Ractor parallelism — Track 1: CPU-bound tools** (`RactorWorkerPool`)
+  - `ractor_safe true` class macro on `Tool` — opts a tool class into Ractor execution; subclasses inherit automatically
+  - `RobotLab.ractor_pool` — global `RactorWorkerPool` singleton, one Ractor worker per CPU core by default
+  - `ractor_pool_size` field on `RunConfig` for configuring pool capacity
+  - `RactorWorkerPool#submit(tool_name, args)` — submits a job and blocks for the frozen result; raises `ToolError` on failure
+  - Tool dispatch routes `ractor_safe` tools through the pool automatically, bypassing the GVL for CPU-intensive work
+  - `RactorBoundary.freeze_deep(obj)` — deep-freezes nested hashes/arrays/strings to make them Ractor-shareable; raises `RactorBoundaryError` for non-shareable objects (Procs, IOs, etc.)
+- **Ractor parallelism — Track 2: parallel robot pipelines** (`RactorNetworkScheduler`)
+  - `parallel_mode: :ractor` on `Network.new` — routes `network.run` through `RactorNetworkScheduler` instead of `SimpleFlow::Pipeline`
+  - `RactorNetworkScheduler` dispatches dependency waves: independent tasks run concurrently (one Thread per task); dependent tasks wait for their wave to complete
+  - `RobotSpec` — frozen `Data.define` descriptor carrying robot name, template, system prompt, and config; safely crosses Ractor boundaries
+  - `RactorNetworkScheduler#run_pipeline` returns `Hash { robot_name => result_string }` for the full pipeline
+  - `RactorNetworkScheduler#run_spec` for single-spec dispatch
+  - `RactorNetworkScheduler#shutdown` for graceful poison-pill cleanup
+  - `network.parallel_mode` reader exposes the configured mode (default `:async`)
+- **Ractor memory proxy** — `RactorMemoryProxy` wraps `Memory` via `ractor-wrapper` for safe cross-Ractor memory access
+- **Infrastructure data classes** — `RactorJob`, `RactorJobError` (`Data.define` structs) for job submission and error propagation across Ractor boundaries
+- **`RactorBoundaryError`** — raised by `freeze_deep` when a non-shareable value (Proc, IO, etc.) would cross a Ractor boundary
+- **`ToolError`** — raised by `RactorWorkerPool#submit` when a tool raises inside a Ractor; propagates message and frozen backtrace
+- **Dependencies** — `ractor_queue` (~> 0.1) and `ractor-wrapper` (~> 0.4) added to gemspec
+- **Ractor Parallelism guide** (`docs/guides/ractor-parallelism.md`) — covers architecture, two-track design, configuration, error handling, constraints, and best practices
+- **Example 29: Ractor-Safe CPU Tools** (`examples/29_ractor_tools.rb`) — demonstrates `ractor_safe` flag, inheritance, `freeze_deep`, pool submissions, `ToolError` propagation, and parallel batch timing; no API key required
+- **Example 30: Ractor Network Scheduler** (`examples/30_ractor_network.rb`) — demonstrates `RactorNetworkScheduler` wave ordering with simulated latencies, `Network.new(parallel_mode: :ractor)` API, and dependency graph inspection; no API key required for Parts 1 & 2
+
+### Fixed
+
+- `ToolConfig::NONE_VALUES` constant was not Ractor-shareable because its inner empty array `[]` was mutable; fixed by replacing `[]` with `[].freeze` so the entire constant is deeply frozen and safe to read from any Ractor
+
+## [0.0.9] - 2026-03-02
+
+### Added
+
+- **Provider passthrough** — `provider:` parameter on Robot constructor for local LLM providers (Ollama, GPUStack, etc.)
+  - Automatically sets `assume_model_exists: true` when provider is specified
+  - Exposed via `robot.provider` accessor
+- **MCP request timeouts** — configurable timeout for all MCP transports
+  - `MCP::Server` accepts `timeout:` parameter (default 15s); auto-converts millisecond values
+  - `MCP::Transports::Base` extracts and exposes `timeout` from config
+  - `MCP::Transports::Stdio` wraps all blocking I/O with `Timeout.timeout` — hung servers no longer block the caller forever
+  - Timeout propagated from `MCP::Server` through `MCP::Client` to transport layer
+- **MCP connection resilience** — improved error handling and retry logic
+  - `ensure_mcp_clients` retries previously failed servers on subsequent calls
+  - `@failed_mcp_configs` tracks servers that failed to connect
+  - `robot.failed_mcp_server_names` — query which MCP servers are down
+  - `robot.connect_mcp!` — eagerly connect to MCP servers (normally lazy)
+  - `init_mcp_client` rescues `StandardError` so one bad server doesn't prevent others from connecting
+  - `cleanup_process` in Stdio transport for reliable resource cleanup
+  - Better error messages for command-not-found (`Errno::ENOENT`), broken pipe (`Errno::EPIPE`), and EOF conditions
+- **`robot.inject_mcp!`** — inject pre-connected MCP clients and tools from an external host application
+- **Conversation management APIs** on Robot
+  - `robot.chat` — access the underlying `RubyLLM::Chat` instance
+  - `robot.messages` — return conversation messages
+  - `robot.clear_messages(keep_system:)` — clear history, optionally preserving the system prompt
+  - `robot.replace_messages(messages)` — restore a saved conversation (checkpoint/restore)
+  - `robot.chat_provider` — query the provider name without reaching into chat internals
+  - `robot.mcp_client(server_name)` — find an MCP client by server name
+- **`RobotResult#duration`** — elapsed seconds for a robot run, set automatically during pipeline execution
+- **`RobotResult#raw`** — raw LLM response stored on every result (previously only settable via accessor)
+- **Pipeline error resilience** — `Robot#call` (pipeline step) rescues all exceptions so one failing robot doesn't crash the entire network; error is captured in a `RobotResult` with the elapsed duration
+
+### Changed
+
+- Bumped version to 0.0.9
+- Display `scout_path` in Rusty Circuit example updated to use `output/` subdirectory
+- Updated `onnxruntime` dependency to 0.11.0
+- Updated Gemfile.lock dependencies (erb, minitest, rails-html-sanitizer, json_schemer)
+
 ## [0.0.8] - 2026-02-22
 
 ### Added

data/README.md

@@ -20,12 +20,19 @@
 - <strong>Extensible Tools</strong> - Custom capabilities with graceful error handling<br>
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
-- <strong>MCP Integration</strong> - Connect to external tool servers<br>
+- <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
+- <strong>Local LLM Providers</strong> - Ollama, GPUStack, LM Studio via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
 - <strong>Layered Configuration</strong> - Cascading YAML, env vars, and RunConfig<br>
-- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting
+- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting<br>
+- <strong>Token &amp; Cost Tracking</strong> - Per-run and cumulative token counts on every robot<br>
+- <strong>Tool Loop Circuit Breaker</strong> - <code>max_tool_rounds:</code> guards against runaway tool call loops<br>
+- <strong>Learning Accumulation</strong> - <code>robot.learn()</code> builds up cross-run observations with deduplication<br>
+- <strong>Context Window Compression</strong> - <code>robot.compress_history()</code> prunes irrelevant old turns via TF cosine scoring<br>
+- <strong>Convergence Detection</strong> - <code>RobotLab::Convergence</code> detects when independent agents agree, enabling reconciler fast-path<br>
+- <strong>Structured Delegation</strong> - <code>robot.delegate(to:, task:)</code> sync or async inter-robot calls with duration and token metadata; async fan-out via <code>DelegationFuture</code>
 </td>
 </tr>
 </table>
@@ -71,6 +78,19 @@ puts result.last_text_content
 # => "The capital of France is Paris."
 ```
 
+### Local LLM Providers
+
+For local LLM providers (Ollama, GPUStack, LM Studio, etc.), use the `provider:` parameter:
+
+```ruby
+robot = RobotLab.build(
+  name: "local_bot",
+  model: "llama3.2",
+  provider: :ollama,
+  system_prompt: "You are a helpful assistant."
+)
+```
+
 ### Configuration
 
 RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. There is no `configure` block. Configuration is loaded automatically from multiple sources in priority order:
@@ -443,14 +463,15 @@ puts result.value.last_text_content
 Connect to external tool servers via Model Context Protocol:
 
 ```ruby
-# Configure MCP server
+# Configure MCP server (with optional timeout)
 filesystem_server = {
   name: "filesystem",
   transport: {
     type: "stdio",
     command: "mcp-server-filesystem",
     args: ["/path/to/allowed/directory"]
-  }
+  },
+  timeout: 30  # seconds (default: 15)
 }
 
 # Create robot with MCP server - tools are auto-discovered
@@ -460,10 +481,18 @@ robot = RobotLab.build(
   mcp: [filesystem_server]
 )
 
+# Optionally connect eagerly (default is lazy on first run)
+robot.connect_mcp!
+
+# Check connection status
+puts "Failed: #{robot.failed_mcp_server_names}" if robot.failed_mcp_server_names.any?
+
 # Robot can now use filesystem tools
 result = robot.run("List the files in the current directory")
 ```
 
+MCP connections are resilient: failed servers are automatically retried on subsequent `run()` calls, and one failing server does not prevent others from connecting.
+
 ## Message Bus
 
 Robots can communicate bidirectionally via an optional message bus, independent of the Network pipeline. This enables negotiation loops, convergence patterns, and cyclic workflows.
@@ -598,6 +627,79 @@ robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
 
 The `on_content:` callback participates in the RunConfig cascade, so it can be set at the network or config level and inherited by robots.
 
+## Token & Cost Tracking
+
+Every `robot.run()` returns a `RobotResult` that carries token usage for that call. The robot itself accumulates running totals across all runs.
+
+```ruby
+robot = RobotLab.build(name: "analyst", system_prompt: "You are helpful.")
+
+result = robot.run("What is a stack?")
+puts result.input_tokens   # tokens sent to the LLM this run
+puts result.output_tokens  # tokens generated this run
+
+puts robot.total_input_tokens   # cumulative across all runs
+puts robot.total_output_tokens
+```
+
+To start a fresh cost batch without rebuilding the robot, call `reset_token_totals`. This resets the **accounting counter only** — the chat history keeps accumulating, so subsequent `input_tokens` will reflect the full context window sent to the API:
+
+```ruby
+robot.reset_token_totals
+puts robot.total_input_tokens  # => 0
+```
+
+Token counts are zero for providers that do not return usage data.
+
+## Tool Loop Circuit Breaker
+
+Set `max_tool_rounds:` to prevent a robot from looping indefinitely through tool calls. When the limit is exceeded, `RobotLab::ToolLoopError` is raised.
+
+```ruby
+robot = RobotLab.build(
+  name: "runner",
+  system_prompt: "Execute every step.",
+  local_tools: [StepTool],
+  max_tool_rounds: 10
+)
+
+begin
+  robot.run("Run all steps.")
+rescue RobotLab::ToolLoopError => e
+  puts e.message  # "Tool call limit of 10 exceeded"
+end
+```
+
+After a `ToolLoopError` the chat contains a dangling `tool_use` block with no matching `tool_result`. Most providers (including Anthropic) will reject any subsequent request with that history. Call `clear_messages` before reusing the robot:
+
+```ruby
+robot.clear_messages   # flushes broken history; system prompt is kept
+result = robot.run("Something new.")  # robot is healthy again
+```
+
+## Learning Accumulation
+
+`robot.learn(text)` records a cross-run observation. On each subsequent `run()`, active learnings are automatically prepended to the user message as a `LEARNINGS FROM PREVIOUS RUNS:` block so the LLM can incorporate prior context without needing a persistent chat:
+
+```ruby
+reviewer = RobotLab.build(
+  name: "reviewer",
+  system_prompt: "You are a Ruby code reviewer."
+)
+
+reviewer.run("Review snippet A")
+reviewer.learn("This codebase prefers map/collect over manual array accumulation")
+
+reviewer.run("Review snippet B")  # learning is injected automatically
+```
+
+Learnings deduplicate bidirectionally: if a broader learning is added that contains an existing narrower one, the narrower one is dropped. Learnings are persisted to the robot's `Memory` and survive a robot rebuild when the same `Memory` object is reused.
+
+```ruby
+reviewer.learnings          # => ["This codebase prefers map/collect..."]
+reviewer.learn("new fact")  # deduplicates before storing
+```
+
 ## Rails Integration
 
 ```bash

data/Rakefile

@@ -49,7 +49,8 @@ namespace :examples do
   SUBDIR_ENTRY_POINTS = {
     "14_rusty_circuit" => "open_mic.rb",
     "15_memory_network_and_bus" => "editorial_pipeline.rb",
-    "16_writers_room" => "writers_room.rb"
+    "16_writers_room" => "writers_room.rb",
+    "27_incident_response" => "incident_response.rb"
   }.freeze
 
   # Subdirectory demos that are standalone apps (not run via `ruby`)

data/docs/api/core/robot.md

@@ -23,6 +23,7 @@ Robot.new(
   description: nil,
   local_tools: [],
   model: nil,
+  provider: nil,
   mcp_servers: [],
   mcp: :none,
   tools: :none,
@@ -32,6 +33,8 @@ Robot.new(
   enable_cache: true,
   bus: nil,
   skills: nil,
+  max_tool_rounds: nil,
+  token_budget: nil,
   temperature: nil,
   top_p: nil,
   top_k: nil,
@@ -54,6 +57,7 @@ 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) |
@@ -63,6 +67,8 @@ Robot.new(
 | `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)) |
+| `max_tool_rounds` | `Integer`, `nil` | `nil` | Circuit breaker: raise `ToolLoopError` after this many tool calls in one `run()` (see [Tool Loop Circuit Breaker](#tool-loop-circuit-breaker)) |
+| `token_budget` | `Integer`, `nil` | `nil` | Raise `InferenceError` if cumulative input tokens exceed this limit |
 | `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 |
@@ -101,6 +107,7 @@ If `name` is omitted, it defaults to `"robot"`.
 | `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 |
@@ -110,6 +117,9 @@ If `name` is omitted, it defaults to `"robot"`.
 | `config` | `RunConfig` | Effective RunConfig (merged from constructor kwargs and passed-in config) |
 | `mcp_config` | `Symbol`, `Array` | Build-time MCP configuration (raw, unresolved) |
 | `tools_config` | `Symbol`, `Array` | Build-time tools configuration (raw, unresolved) |
+| `total_input_tokens` | `Integer` | Cumulative input tokens sent across all `run()` calls |
+| `total_output_tokens` | `Integer` | Cumulative output tokens received across all `run()` calls |
+| `learnings` | `Array<String>` | Accumulated cross-run observations (see [Learning Accumulation](#learning-accumulation)) |
 
 ## Attributes (Read-Write)
 
@@ -239,7 +249,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).
 
@@ -401,6 +413,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
@@ -653,6 +801,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
@@ -749,6 +909,181 @@ bot.with_bus(bus)
 bot.send_message(to: :someone, content: "Hello!")
 ```
 
+## Token & Cost Tracking
+
+Every `robot.run()` returns a `RobotResult` with token counts for that call. The robot accumulates running totals across all runs.
+
+### RobotResult Token Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `input_tokens` | `Integer` | Input tokens sent to the LLM in this run (0 if provider doesn't report usage) |
+| `output_tokens` | `Integer` | Output tokens received from the LLM in this run (0 if not reported) |
+
+### Robot Cumulative Totals
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `total_input_tokens` | `Integer` | Cumulative input tokens across all `run()` calls |
+| `total_output_tokens` | `Integer` | Cumulative output tokens across all `run()` calls |
+
+### reset_token_totals
+
+```ruby
+robot.reset_token_totals
+# => nil
+```
+
+Reset the cumulative accounting counters to zero. Useful when you want to measure cost for a specific task batch while keeping the robot alive for the next batch.
+
+> **Note:** This resets the *accounting counter only* — the underlying chat history keeps growing. The next run's `input_tokens` will reflect the full accumulated chat context sent to the API.
+
+**Example:**
+
+```ruby
+robot = RobotLab.build(name: "analyst", system_prompt: "You are helpful.")
+
+result = robot.run("What is a stack?")
+puts result.input_tokens    # e.g. 120
+puts result.output_tokens   # e.g. 45
+
+result2 = robot.run("And a queue?")
+puts result2.input_tokens   # larger — full chat history sent
+
+puts robot.total_input_tokens   # 120 + result2.input_tokens
+puts robot.total_output_tokens
+
+# Start a fresh accounting batch
+robot.reset_token_totals
+puts robot.total_input_tokens   # => 0
+```
+
+## Tool Loop Circuit Breaker
+
+Set `max_tool_rounds:` to guard against a robot looping indefinitely through tool calls. After the limit is reached, `RobotLab::ToolLoopError` is raised.
+
+### max_tool_rounds Parameter
+
+```ruby
+robot = RobotLab.build(
+  name: "runner",
+  system_prompt: "Execute every step.",
+  local_tools: [StepTool],
+  max_tool_rounds: 10
+)
+```
+
+`max_tool_rounds` can also be set via `RunConfig`:
+
+```ruby
+config = RobotLab::RunConfig.new(max_tool_rounds: 10)
+robot = RobotLab.build(name: "runner", system_prompt: "...", config: config)
+```
+
+### ToolLoopError
+
+`RobotLab::ToolLoopError < RobotLab::InferenceError`
+
+Raised when the number of tool calls in a single `run()` exceeds `max_tool_rounds`. The error message includes the limit that was exceeded.
+
+### Recovery after ToolLoopError
+
+After a `ToolLoopError`, the chat contains a dangling `tool_use` block with no matching `tool_result`. Anthropic and most providers will reject any subsequent request with that broken history.
+
+**You must call `clear_messages` before reusing the robot:**
+
+```ruby
+begin
+  robot.run("Execute all steps.")
+rescue RobotLab::ToolLoopError => e
+  puts "Circuit breaker fired: #{e.message}"
+end
+
+# Flush the corrupted chat (system prompt is kept)
+robot.clear_messages
+puts robot.config.max_tool_rounds  # still set — config unchanged
+
+# Robot is healthy again
+result = robot.run("Something new.")
+```
+
+## Learning Accumulation
+
+`robot.learn(text)` records a cross-run observation. On each subsequent `run()`, active learnings are automatically prepended to the user message as a `LEARNINGS FROM PREVIOUS RUNS:` block.
+
+### learn
+
+```ruby
+robot.learn(text)
+# => self
+```
+
+Add a learning to the robot's accumulated observations. Learnings are automatically deduplicated:
+
+- If the new text is a substring of an existing learning, it is dropped (the existing broader learning already covers it).
+- If an existing learning is a substring of the new text, the narrower one is replaced.
+
+Learnings are persisted to `memory[:learnings]` and survive a robot rebuild when the same `Memory` object is reused.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `text` | `String` | The observation or insight to record |
+
+**Returns:** `self`
+
+### learnings
+
+```ruby
+robot.learnings
+# => Array<String>
+```
+
+Returns the list of accumulated learning strings in insertion order.
+
+### How Learnings Are Injected
+
+When learnings are present, each `run(message)` prepends them to the message before sending to the LLM:
+
+```
+LEARNINGS FROM PREVIOUS RUNS:
+- This codebase prefers map/collect over manual array accumulation
+- Explicit nil comparisons appear frequently here
+
+<original user message>
+```
+
+**Example:**
+
+```ruby
+reviewer = RobotLab.build(
+  name: "reviewer",
+  system_prompt: "You are a Ruby code reviewer."
+)
+
+# Run 1 — no learnings yet
+reviewer.run("Review snippet A")
+reviewer.learn("Prefer map/collect over manual accumulation")
+
+# Run 2 — learning injected automatically
+reviewer.run("Review snippet B")
+reviewer.learn("Avoid explicit nil comparisons")
+
+# Run 3 — both learnings injected
+reviewer.run("Review snippet C")
+
+puts reviewer.learnings.size  # => 2
+```
+
+### Deduplication Example
+
+```ruby
+robot.learn("avoid using puts")
+robot.learn("avoid using puts and p in production code")
+# => broader learning replaces narrower; robot.learnings.size == 1
+```
+
 ## See Also
 
 - [Building Robots Guide](../../guides/building-robots.md) (includes [Composable Skills](../../guides/building-robots.md#composable-skills))

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`.