robot_lab 0.0.9 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c852fcf7f4aed4ce95fabdc5b0296723ca8aa10e780dabaa7759e618a22bc640
-  data.tar.gz: 1bcb205c958ede9967886dae78a1d1a6d47da42e4cd9bd29d7bdd3e094b0a088
+  metadata.gz: 3a8ae2e2cf690116950548d732987e16756870f8444c91504ea14fe039f25996
+  data.tar.gz: 115694d1449233b3a17a28e87deda8bd3d0ac204f51301aee7781156a3b2003e
 SHA512:
-  metadata.gz: 5620e7798ac04441cb23c6a7cc5f0cdad7447103825db35ef6f3a3987785b8ff5fb355ec03a309ef9c8a5ce5b0b7a29d9f5adef0e6a5d9de5cd66d3c94fb0469
-  data.tar.gz: 9300b1f5ed98e70226c7c670bcf2e3dee033310db6b2182b2705085f02474a1ea6157a011c93906da1d45ba38b4c9f8b9e62545cdb5fd304ca1550734f7dc043
+  metadata.gz: d512eea2ce533c92b4f791c0d3527fe61805fdca2638e926c0869e0e8f5b0c9a9dc5bac0791db2e5bae8a326b46eaea31c5ffae9ba761b17d1b93b3113735087
+  data.tar.gz: 7e6025d5bbe7252e61e4d7922eea639cda523d7c197535e46400caeeec7f30e7554a015cada107eef796a47c10564d286cdb1d2d4b539a7ac51cc71975b65352

data/CHANGELOG.md

@@ -8,6 +8,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.12] - 2026-04-18
+
+### Added
+
+- **README: Context Window Compression section** — documents `robot.compress_history` with threshold tuning (`recent_turns`, `keep_threshold`, `drop_threshold`) and summarizer lambda pattern
+- **README: Convergence Detection section** — documents `RobotLab::Convergence.detected?` / `.similarity` with network router fast-path example
+- **README: Structured Delegation section** — documents `robot.delegate(to:, task:)` sync and async modes, `DelegationFuture` fan-out pattern, and timeout handling
+- **README: Ractor Parallelism section** — documents `ractor_safe true` tool macro and `parallel_mode: :ractor` network mode with link to full guide
+- **`docs/guides/building-robots.md`** — added matching sections for all four features above with expanded API detail, `DelegationFuture` method table, and convergence router example
+- **`docs/api/core/result.md`** — new API reference for `RobotResult`: attributes, token tracking, delegation metadata, persistence (`export`, `from_hash`, `checksum`), and debug fields
+- **`docs/api/errors.md`** — new error hierarchy reference covering all `RobotLab::Error` subclasses (`ConfigurationError`, `DependencyError`, `InferenceError`, `ToolLoopError`, `ToolNotFoundError`, `MCPError`, `BusError`, `RactorBoundaryError`, `ToolError`, `DelegationFuture::DelegationTimeout`) with rescue examples
+
+### Changed
+
+- Bumped version to 0.0.12
+- Updated `bigdecimal` to 4.1.2
+- Updated `protocol-http` to 0.62.2
+- Updated `protocol-websocket` to 0.21.0
+- Updated `rake` to 13.4.2
+- Updated `sqlite3` to 2.9.3
+
+## [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

data/README.md

@@ -26,7 +26,13 @@
 - <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>
@@ -621,6 +627,209 @@ 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
+```
+
+## Context Window Compression
+
+`robot.compress_history` prunes old conversation turns using TF-IDF cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+
+```ruby
+# Basic compression: protect the 3 most recent turns, drop unrelated old turns
+robot.compress_history
+
+# Tune the thresholds
+robot.compress_history(
+  recent_turns:   5,    # protect this many recent user+assistant pairs
+  keep_threshold: 0.6,  # turns scoring >= this are kept verbatim
+  drop_threshold: 0.2   # turns scoring < this are dropped
+)
+
+# Summarize medium-relevance turns instead of dropping them
+summarizer_bot = RobotLab.build(name: "summarizer", system_prompt: "Summarize concisely.")
+robot.compress_history(
+  summarizer: ->(text) { summarizer_bot.run("One sentence: #{text}").reply }
+)
+```
+
+Requires the optional `classifier` gem (`~> 2.3`). Add it to your Gemfile:
+
+```ruby
+gem "classifier", "~> 2.3"
+```
+
+## Convergence Detection
+
+`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using TF-IDF cosine similarity. Use it as a router fast-path to skip an expensive reconciler LLM call when verifiers already agree.
+
+```ruby
+# Check similarity directly
+score = RobotLab::Convergence.similarity(result_a.reply, result_b.reply)
+# => 0.92
+
+# Boolean check against a threshold (default: 0.85)
+RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
+# => true
+
+# Use a custom threshold
+RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
+```
+
+A common pattern is wiring convergence into a network router to skip reconciliation:
+
+```ruby
+router = ->(args) do
+  a = args.context[:verifier_a]&.reply.to_s
+  b = args.context[:verifier_b]&.reply.to_s
+  RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+end
+
+network = RobotLab.create_network(name: "verify", router: router) do
+  # ...
+end
+```
+
+Requires the `classifier` gem (`~> 2.3`).
+
+## Structured Delegation
+
+`robot.delegate(to:, task:)` dispatches work to another robot and returns the result, with duration and token metadata attached. Pass `async: true` for non-blocking fan-out.
+
+```ruby
+analyst  = RobotLab.build(name: "analyst",  system_prompt: "Analyze data.")
+writer   = RobotLab.build(name: "writer",   system_prompt: "Write reports.")
+manager  = RobotLab.build(name: "manager",  system_prompt: "Coordinate work.")
+
+# Synchronous delegation — blocks until done
+result = manager.delegate(to: analyst, task: "Analyze Q3 sales data")
+puts result.reply
+puts "%.2fs, %d tokens" % [result.duration, result.output_tokens]
+
+# Asynchronous fan-out — returns immediately
+f1 = manager.delegate(to: analyst, task: "Analyze Q3 sales", async: true)
+f2 = manager.delegate(to: writer,  task: "Draft Q3 summary", async: true)
+
+# Do other work here while both run in parallel...
+
+analysis = f1.value           # blocks until resolved
+summary  = f2.value           # blocks until resolved
+
+# With a timeout
+result = f1.value(timeout: 30)  # raises DelegationFuture::DelegationTimeout if too slow
+```
+
+`DelegationFuture` attributes:
+
+```ruby
+future.resolved?      # => true/false (non-blocking poll)
+future.robot_name     # => "analyst"
+future.delegated_by   # => "manager"
+```
+
+## Ractor Parallelism
+
+RobotLab supports true CPU parallelism via Ruby Ractors — isolated execution contexts that bypass the GVL. Two modes are available:
+
+**CPU-bound tools** — mark a tool `ractor_safe true` and RobotLab automatically routes its calls through a global `RactorWorkerPool` instead of running inline:
+
+```ruby
+class TranscribeAudio < RubyLLM::Tool
+  ractor_safe true
+  description "Transcribe an audio file"
+  param :path, type: :string, desc: "Path to audio file"
+
+  def execute(path:)
+    AudioTranscriber.run(path)  # pure computation, no shared mutable state
+  end
+end
+```
+
+**Parallel robot networks** — pass `parallel_mode: :ractor` when creating a network to dispatch independent robots across hardware threads simultaneously:
+
+```ruby
+network = RobotLab.create_network(name: "analysis", parallel_mode: :ractor) do
+  task :fetch,     fetcher_robot,    depends_on: :none
+  task :sentiment, sentiment_robot,  depends_on: [:fetch]
+  task :entities,  entity_robot,     depends_on: [:fetch]   # runs in parallel with sentiment
+  task :summarize, summary_robot,    depends_on: [:sentiment, :entities]
+end
+
+results = network.run(message: "Analyze customer feedback")
+# => { "fetch" => "...", "sentiment" => "positive", "entities" => "...", "summarize" => "..." }
+```
+
+See the [Ractor Parallelism guide](https://madbomber.github.io/robot_lab/guides/ractor-parallelism) for constraints, the frozen-data contract, and `RactorMemoryProxy` for shared state.
+
 ## 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/result.md

@@ -0,0 +1,123 @@
+# RobotResult
+
+`RobotResult` is returned by every `robot.run()` call. It carries the LLM output, tool call results, token usage, timing, and delegation metadata for that execution.
+
+## Accessing the Response
+
+```ruby
+result = robot.run("What is the capital of France?")
+
+result.reply              # => "The capital of France is Paris."
+result.last_text_content  # => alias for reply
+result.output             # => Array of Message objects (full turn)
+result.tool_calls         # => Array of ToolResultMessage objects
+```
+
+`reply` / `last_text_content` returns the content of the last text message in `output`. This is the string you want for the vast majority of use cases.
+
+## Token & Cost Tracking
+
+```ruby
+result.input_tokens   # => Integer — tokens sent to the LLM this run
+result.output_tokens  # => Integer — tokens generated this run
+```
+
+Token counts are zero for providers that do not return usage data.
+
+## Timing
+
+`duration` is set when the result travels through a network pipeline or a `delegate` call. It is `nil` when calling `robot.run()` directly.
+
+```ruby
+result.duration  # => Float (elapsed seconds) or nil
+```
+
+## Delegation Metadata
+
+When a result comes back through `robot.delegate(to:, task:)`, two additional fields are populated:
+
+```ruby
+result.delegated_by  # => "manager"  (the robot that issued the delegation)
+result.duration      # => 2.34       (always set by delegate)
+```
+
+## Identity & Status
+
+```ruby
+result.robot_name   # => "analyst"
+result.id           # => "550e8400-e29b-..."  (UUID, unique per run)
+result.created_at   # => Time instance
+result.stop_reason  # => "end_turn", "tool_use", or nil
+```
+
+## Inspecting the Full Output
+
+```ruby
+result.output.each do |message|
+  puts message.role     # :assistant, :tool, etc.
+  puts message.content  # String or Array
+end
+
+result.has_tool_calls?  # => true if the LLM called any tools
+result.stopped?         # => true if execution ended naturally (not mid-tool-call)
+```
+
+## Persistence
+
+Export for serialization (excludes debug fields):
+
+```ruby
+hash = result.export
+# {
+#   robot_name: "analyst",
+#   output: [...],
+#   tool_calls: [...],
+#   created_at: "2026-04-18T12:00:00Z",
+#   id: "550e8400-...",
+#   checksum: "a1b2c3...",
+#   stop_reason: "end_turn",
+#   duration: 2.34,
+#   input_tokens: 512,
+#   output_tokens: 128
+# }
+
+json = result.to_json
+
+# Reconstruct from hash
+restored = RobotLab::RobotResult.from_hash(hash)
+```
+
+`checksum` is a SHA-256 digest of `output + tool_calls + created_at`. Use it for deduplication when persisting results.
+
+## Debug Fields
+
+These are `nil` by default and only populated when explicitly set for debugging:
+
+```ruby
+result.prompt   # Array<Message> — prompt sent to the LLM
+result.history  # Array<Message> — history used
+result.raw      # raw LLM response object from ruby_llm
+```
+
+## Attribute Reference
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `robot_name` | String | Name of the robot that produced this result |
+| `reply` | String, nil | Last text content (alias: `last_text_content`) |
+| `output` | Array\<Message\> | All output messages from this run |
+| `tool_calls` | Array\<ToolResultMessage\> | Tool call results |
+| `input_tokens` | Integer | Tokens sent to LLM |
+| `output_tokens` | Integer | Tokens generated |
+| `duration` | Float, nil | Elapsed seconds (set by delegate/pipeline) |
+| `delegated_by` | String, nil | Delegating robot's name |
+| `id` | String | UUID |
+| `created_at` | Time | Creation timestamp |
+| `stop_reason` | String, nil | LLM stop reason |
+| `checksum` | String | SHA-256 of output content |
+
+## Related
+
+- [Robot API](robot.md) — `run`, `delegate`, `compress_history`
+- [Building Robots](../../guides/building-robots.md) — Robot construction patterns
+- [Structured Delegation](../../guides/building-robots.md#structured-delegation) — `DelegationFuture` and async fan-out

data/docs/api/core/robot.md

@@ -33,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,
@@ -65,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 |
@@ -113,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)
 
@@ -902,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))