robot_lab 0.2.1 → 0.2.7

data/docs/guides/using-tools.md

@@ -85,16 +85,29 @@ weather_tool = RobotLab::Tool.create(
 
 `RobotLab::AskUser` lets a robot ask the user a question via the terminal. The LLM decides when it needs human input and calls the tool with a question, optional choices, and an optional default.
 
+`AskUser` reads its IO from `robot.input` / `robot.output`, and it finds the
+robot through its own `robot` accessor — which is only populated when you attach
+an **instance constructed with `robot:`**. Build the robot first, then attach:
+
 ```ruby
 robot = RobotLab.build(
   name: "onboarding",
-  system_prompt: "Walk the user through project setup. Ask questions to understand their needs.",
-  local_tools: [RobotLab::AskUser]
+  system_prompt: "Walk the user through project setup. Ask questions to understand their needs."
 )
-robot.run("Help the user set up a new project")
+robot.local_tools << RobotLab::AskUser.new(robot: robot)
+
+robot.run("Help the user set up a new project", tools: :inherit)
 ```
 
-The tool displays the robot's name and question, then waits for terminal input:
+> [!WARNING]
+> Passing the bare class — `local_tools: [RobotLab::AskUser]` — leaves
+> `tool.robot` as `nil`. The tool then ignores `robot.input`/`robot.output`,
+> reads from the real `$stdin` (blocking your process, and hanging any test
+> suite), and labels its prompt `[Robot]` instead of the robot's name.
+> Note also the `tools: :inherit` above: a plain `run()` sends **zero** tools,
+> so the LLM would never see `AskUser` at all.
+
+The tool displays the robot's name and question, then waits for input:
 
 ```
 [onboarding] What programming language will you use?
@@ -110,13 +123,27 @@ Features:
 - **Multiple choice**: numbered options, user types the number or text
 - **Default value**: shown in the prompt, used when user presses Enter
 
-IO is sourced from `robot.input` / `robot.output` (defaulting to `$stdin` / `$stdout`), making it easy to test with `StringIO`:
+Because the IO is sourced from the robot, a `StringIO` pair makes the tool
+testable without a terminal:
 
 ```ruby
 robot.input  = StringIO.new("2\n")
 robot.output = StringIO.new
+
+# ... the LLM calls ask_user(question: "Which language?", choices: %w[Ruby Python Go])
+robot.output.string
+# => "\n[onboarding] Which language?\n  1. Ruby\n  2. Python\n  3. Go\n> "
 ```
 
+> [!NOTE]
+> The name the LLM sees is **`robot_lab--ask_user`**, not `ask_user`. RubyLLM
+> derives tool names from the full class name including its namespace, so
+> `RobotLab::AskUser` becomes `robot_lab--ask_user`. (A trailing `Tool` is
+> stripped: a top-level `WeatherTool` is exposed as `weather`.) These derived
+> names are what an allowlist must match **for tools attached as instances** —
+> a tool attached as a class matches its class name instead. See
+> [Runtime Tool Filtering](#runtime-tool-filtering).
+
 See the [AskUser API reference](../api/core/tool.md#built-in-askuser) for full details.
 
 ## Attaching Tools to Robots
@@ -133,6 +160,15 @@ robot = RobotLab.build(
 )
 ```
 
+`local_tools:` and `tools:` are different mechanisms — don't confuse them. `local_tools:` attaches tool **instances or classes**; `tools:` (see [Runtime Tool Filtering](#runtime-tool-filtering) below) is a **name allowlist** that filters which of the already-attached tools are sent for a given turn. Passing an instance or class to `tools:` raises `ArgumentError` immediately, naming the offending class and pointing you at `local_tools:` instead:
+
+```ruby
+RobotLab.build(name: "bot", tools: [GetWeather.new])
+# => ArgumentError: `tools:` expects tool names (String/Symbol) to allow, but
+#    received GetWeather. To attach tool instances or classes, pass them as
+#    `local_tools:` (e.g. RobotLab.build(local_tools: [MyTool.new])).
+```
+
 ### Via Template Front Matter
 
 Declare tool class names in the template's YAML front matter. RobotLab resolves each string to a Ruby constant via `Object.const_get` and instantiates it:
@@ -156,13 +192,156 @@ Tool classes must be defined and loaded before building the robot. Unresolvable
 
 ### Via Chaining
 
-You can also add tools dynamically with chaining:
+`with_tools` is delegated straight to the underlying `RubyLLM::Chat`, so it
+writes tools onto the chat rather than onto the robot's `local_tools`:
 
 ```ruby
 robot = RobotLab.build(name: "assistant", system_prompt: "...")
 robot.with_tools(GetWeather, CalculatorTool)
 ```
 
+> [!WARNING]
+> Chained tools do not survive a `run`. Because `run` defaults to
+> `tools: :none`, it replaces the chat's tool list with an empty one before
+> asking the LLM — wiping whatever `with_tools` put there:
+>
+> ```ruby
+> robot.with_tools(GetWeather, CalculatorTool)
+> robot.chat.tools.keys   # => [:get_weather, :calculator]
+> robot.run("Hello")
+> robot.chat.tools.keys   # => []   <- cleared by the run
+> ```
+>
+> For tools that should persist across runs, attach them with `local_tools:`
+> and pass `tools: :inherit` on each `run`.
+
+## Runtime Tool Filtering
+
+`tools:` (and `mcp:`) also work as a **per-run** override, passed to `run()` itself, on top of the build-time/network/global hierarchy described in [Hierarchical MCP and Tools](../getting-started/configuration.md#hierarchical-mcp-and-tools):
+
+```ruby
+robot.run("What's the weather?", tools: :inherit)        # every attached tool
+robot.run("Just chat, no tools needed.", tools: :none)    # zero tools this turn
+# Allowlist. This robot attached its tools as CLASSES, so match the class names:
+robot.run("Only use the calculator.", tools: %w[CalculatorTool])
+```
+
+| Value | Meaning |
+|-------|---------|
+| `:inherit` | Propagate the parent level's allowlist (build-time / network / global) |
+| `:none`, `[]` | Send **zero** tools this turn |
+| `nil` | No filter at all — every attached tool, **discarding** any parent allowlist |
+| `["name", ...]` | Only these tools, matched against how each was attached |
+
+> [!CAUTION]
+> `tools: nil` does **not** send zero tools, and it is **not** the same as
+> `:inherit`. `:inherit` carries the parent's allowlist down; `nil` throws the
+> filter away entirely. With a robot built `tools: %w[GetWeather]` holding
+> `GetWeather` and `CalculatorTool`:
+>
+> ```
+> run(tools: :inherit)  -> [:get_weather]                  # parent allowlist honored
+> run(tools: nil)       -> [:get_weather, :calculator]     # allowlist discarded
+> ```
+>
+> If you mean zero tools, write `:none`.
+
+> [!IMPORTANT]
+> An allowlist entry must match **how the tool was attached**, because the
+> comparison uses `tool.name` and `Class#name` differs from `RubyLLM::Tool#name`:
+>
+> | Attached as | Allowlist that matches |
+> |---|---|
+> | `local_tools: [CalculatorTool]` (class) | `[CalculatorTool]` or `%w[CalculatorTool]` |
+> | `local_tools: [CalculatorTool.new]` (instance) | `%w[calculator]` |
+>
+> Note the constructor's `tools:` is validated and **rejects** classes and
+> instances outright (`ArgumentError`); only task-level and `run()` values accept
+> them.
+
+An explicit `:none`/`[]` is useful for a relevance filter that decided no tool is useful for the current message — it now genuinely sends zero tools for that turn (previously an empty allowlist was silently treated as "all tools," which could overflow small-context local models with the full tool set). Each turn's resolved tool set fully **replaces** the chat's tools rather than accumulating, so a later `:none` turn correctly clears whatever a prior turn attached.
+
+> [!CAUTION]
+> **Watch the default.** Both `Robot.new`'s and `run()`'s `tools:`/`mcp:`
+> parameters default to `:none`, not `:inherit`. If you build a robot with
+> `local_tools:` and then call `robot.run(message)` with no `tools:` override at
+> all, the runtime default takes the explicit-`:none` path above — sending no
+> tools for that turn. **Pass `tools: :inherit` on the `run()` call** (or on the
+> network `task`, which is forwarded to `run()`) anywhere you need the robot's
+> attached tools available.
+
+> [!WARNING]
+> For a **standalone** robot, do not pass `tools: :inherit` at *build* time as a
+> way to turn tools on. Build-time `:inherit` resolves against the level above
+> it, which for a standalone robot is the global `:none` — producing an
+> allowlist of `["none"]` that matches nothing, and the empty result then
+> carries into the runtime pass. Leave build-time `tools:` unset:
+>
+> ```ruby
+> # build tools: unset      + run(tools: :inherit)  -> [:t1]   correct
+> # build tools: :inherit   + run(tools: :inherit)  -> []      the standalone trap
+> # build tools: :none      + run(tools: :inherit)  -> [:t1]   also fine
+> ```
+>
+> This applies to a robot run on its own. Inside a **network** whose `config:`
+> supplies `tools:`/`mcp:`, the parent level is that network list rather than
+> `:none`, and build-time `:inherit` is *required* — it is the robot's opt-in to
+> the network value. See
+> [Network-Wide Tool and MCP Defaults](creating-networks.md#network-wide-tool-and-mcp-defaults).
+
+### Tool Capping and Per-Turn Filtering
+
+Most LLM providers reject a tool array longer than 128 entries and fail the whole turn. RobotLab clamps the fully-resolved tool list to a ceiling right before handing it to the chat provider — the definitive choke point regardless of how the tools were configured, filtered, or MCP-connected:
+
+```ruby
+robot = RobotLab.build(
+  name: "power_user",
+  system_prompt: "...",
+  local_tools: many_tools,       # say, 150 tools
+  config: RobotLab::RunConfig.new(max_tools: 50)  # override the default ceiling
+)
+```
+
+- Default ceiling: **128** tools per turn (`RobotLab::Robot::DEFAULT_MAX_TOOLS`)
+- Override with a **positive** `max_tools:` on `RunConfig` (or the `max_tools:` cascade field — see [Available Fields](../getting-started/configuration.md#available-fields))
+- When a turn's resolved tools exceed the cap, RobotLab logs a warning naming how many were dropped and sends the first `max_tools` entries
+
+> [!WARNING]
+> The cap **cannot be disabled.** `max_tools: nil`, `0`, or a negative number
+> all fall back to the 128 default — only a positive integer changes the
+> ceiling. If you attach more than 128 tools and set `max_tools: 0` expecting
+> "unlimited", you get the first 128.
+>
+> The truncation is not silent, though — `cap_tools` logs it at `WARN` through
+> `RobotLab.config.logger` every time it fires:
+>
+> ```
+> [power_user] tool list (150) exceeds max_tools (128); sending 128, dropping 22
+> ```
+
+## Skill Scripts and Sandboxing
+
+A skill bundle (a directory with a `SKILL.md` plus `scripts/`, discovered via `AgentSkill`) can expose its scripts as tools (`ScriptTool`). Because those scripts run as real OS processes, each `SKILL.md` can declare the capabilities its scripts need directly in front matter, alongside `name`/`description`:
+
+```markdown title="skills/deploy-checker/SKILL.md"
+---
+name: deploy-checker
+description: Verifies a deployment's health before promoting it.
+fs_read: ["./data", "/etc/hosts"]
+fs_write: ["./out"]
+network: true
+timeout: 30
+trust: external   # or "core" for trusted, always-unconfined skills
+---
+```
+
+Sandboxing itself is **opt-in and off by default** — see the [`sandbox:` config section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section). When disabled, scripts run exactly as they always have, unconfined. When enabled:
+
+- The global `sandbox:` config is a **ceiling** (`fs_read`, `fs_write`, `network`, `timeout`); each skill's front matter is its **declared** request. The script actually runs under the **intersection** of the two — a path outside the ceiling's roots is dropped even if the skill declares it, `network` requires both sides to allow it, and `timeout` is the smaller of the two.
+- On macOS, confinement is enforced with a generated `sandbox-exec` (Seatbelt) profile: deny-by-default, with narrow allowances for the interpreter to boot, the granted read/write paths, and (optionally) the network. Notably, `$HOME` is never implicitly readable — SSH keys and cloud credentials stay out of reach unless a path under `$HOME` is explicitly granted.
+- Off macOS, or for any skill declaring `trust: core`, sandboxing is a passthrough — confinement is currently macOS-only and is always skipped for trusted "core" skills regardless of platform.
+- A script that runs past its `timeout` is killed (its whole process group) and reported back to the LLM as a timed-out error rather than hanging the turn.
+
 ## Parameter Types
 
 Define parameters on `RubyLLM::Tool` subclasses using `param`:
@@ -197,10 +376,22 @@ param :active, type: :boolean, desc: "Whether the user is active"
 param :tags, type: :array, desc: "List of tags"
 ```
 
-### Enum
+### Enumerated Values
+
+`param` has **no `enum:` option**. Its full signature is
+`param(name, type: "string", desc: nil, description: nil, required: true)` —
+anything else raises `ArgumentError: unknown keyword: :enum`. Express the
+allowed values in the description instead, and validate in `execute`:
 
 ```ruby
-param :status, type: :string, desc: "Order status", enum: %w[pending active completed]
+STATUSES = %w[pending active completed].freeze
+
+param :status, type: :string, desc: "Order status — one of: pending, active, completed"
+
+def execute(status:)
+  return { error: "status must be one of #{STATUSES.join(', ')}" } unless STATUSES.include?(status)
+  # ...
+end
 ```
 
 ### Required vs Optional
@@ -347,7 +538,39 @@ result = tool.call({ "id" => "missing" })
 # => "Error (fetch_resource): connection refused"
 ```
 
-This applies to all `RobotLab::Tool` variants — subclasses, `Tool.create` factory tools, and MCP tools. Errors are also logged via `RobotLab.config.logger` at `:warn` level.
+This applies to all `RobotLab::Tool` variants — subclasses, `Tool.create` factory tools, and MCP tools.
+
+### RobotLab::ToolError and Retryability
+
+`RobotLab::ToolError` is handled on a separate path from ordinary
+`StandardError`s. Raising one with `retryable: true` appends `" (retryable)"`
+to the text the LLM sees, hinting that another attempt may succeed:
+
+```ruby
+class FetchResource < RobotLab::Tool
+  description "Fetch a resource from an external API"
+  param :id, type: :string, desc: "Resource ID"
+
+  def execute(id:)
+    raise RobotLab::ToolError.new("upstream 503", retryable: true)
+  end
+end
+
+FetchResource.new.call({ "id" => "1" })
+# => "Error (fetch_resource): upstream 503 (retryable)"
+
+# Without retryable:, no suffix is appended:
+#   raise RobotLab::ToolError, "bad input"
+#   => "Error (fetch_resource): bad input"
+```
+
+> [!WARNING]
+> Only the ordinary `StandardError` path writes to the log
+> (`RobotLab.config.logger.warn("Tool 'name' error: RuntimeError: …")`).
+> A `RobotLab::ToolError` is turned into text for the LLM and logged
+> **nowhere** — if you rely on `ToolError` for expected failures, add your own
+> logging inside `execute`, or those failures leave no trace outside the
+> transcript.
 
 ### Critical Tools (Opt-Out)
 
@@ -368,6 +591,24 @@ end
 
 `raise_on_error` is per-class and defaults to `false`. Setting it on one class does not affect others.
 
+> [!WARNING]
+> `raise_on_error` does **not** walk the inheritance chain. A subclass of a
+> class that set it silently reverts to `false`:
+>
+> ```ruby
+> class CriticalBase < RobotLab::Tool
+>   self.raise_on_error = true
+> end
+>
+> class ChargeCard < CriticalBase; end
+>
+> CriticalBase.raise_on_error?   # => true
+> ChargeCard.raise_on_error?     # => false   <- NOT inherited
+> ```
+>
+> Set `self.raise_on_error = true` on every class that needs it. (This differs
+> from `ractor_safe`, below, which *does* consult the superclass.)
+
 ### Manual Error Handling
 
 You can still handle specific errors inside `execute` for domain-specific responses:
@@ -389,20 +630,68 @@ class FetchResource < RobotLab::Tool
 end
 ```
 
+## Ractor-Safe Tools
+
+A tool class can declare itself safe to run inside a Ractor. When it is, and the
+[`robot_lab-ractor`](https://github.com/MadBomber/robot_lab-ractor) extension
+gem is loaded, `call` dispatches the work to `RobotLab.ractor_pool` instead of
+running it inline on the calling thread — giving real CPU parallelism for
+compute-bound tools.
+
+```ruby
+class Fibonacci < RobotLab::Tool
+  ractor_safe true
+
+  description "Compute the nth Fibonacci number"
+  param :n, type: :integer, desc: "Which Fibonacci number to compute"
+
+  def execute(n:)
+    a, b = 0, 1
+    n.times { a, b = b, a + b }
+    a
+  end
+end
+
+Fibonacci.ractor_safe?   # => true
+```
+
+Dispatch to the pool happens only when **all three** hold:
+
+1. `ractor_safe?` is true
+2. the class has a resolvable name — anonymous classes (including every tool
+   built by `Tool.create`) fall back to the inline path
+3. the `robot_lab-ractor` extension is loaded
+
+Otherwise `execute` runs inline, exactly as an ordinary tool would. Pool size
+comes from the `ractor_pool_size` `RunConfig` field (`:auto` when unset).
+
+> [!WARNING]
+> A Ractor-safe tool must be genuinely stateless: it is instantiated **fresh
+> inside the Ractor worker** for every call, so `robot`, captured closures, and
+> mutable class-level state are not available to it, and the result comes back
+> frozen. Do not set `ractor_safe true` on a tool that touches its robot.
+
+Unlike `raise_on_error`, `ractor_safe` **does** walk the inheritance chain — a
+subclass of a Ractor-safe tool is Ractor-safe unless it says otherwise.
+
 ## Tool Callbacks
 
-Robots support `on_tool_call` and `on_tool_result` callbacks for monitoring tool usage:
+Robots support `on_tool_call` and `on_tool_result` callbacks for monitoring tool usage. Each receives exactly **one** argument — `on_tool_result` gets the result only, not the originating call:
 
 ```ruby
 robot = RobotLab.build(
   name: "assistant",
   system_prompt: "...",
   local_tools: [GetWeather],
-  on_tool_call: ->(call) { puts "Calling: #{call}" },
+  on_tool_call: ->(tool_call) { puts "Calling: #{tool_call.name}" },
   on_tool_result: ->(result) { puts "Result: #{result}" }
 )
+
+robot.run("What's the weather in Tokyo?", tools: :inherit)
 ```
 
+See [Streaming](streaming.md#tool-callbacks) for details, including the RubyLLM deprecation warning these emit.
+
 ## RobotLab::Tool.create with Schema
 
 For dynamic tools via `Tool.create`, pass parameters as a JSON Schema hash:

data/docs/index.md

@@ -50,7 +50,7 @@ Each robot is backed by a persistent LLM chat, configured with keyword arguments
 
     Mix reusable prompt behaviors into any robot. Skills expand depth-first with automatic cycle detection and config cascading.
 
-    [:octicons-arrow-right-24: Skills Guide](guides/building-robots.md#skills)
+    [:octicons-arrow-right-24: Skills Guide](guides/building-robots.md#composable-skills)
 
 -   :material-tools:{ .lg .middle } **Extensible Tools**
 
@@ -142,16 +142,35 @@ Each robot is backed by a persistent LLM chat, configured with keyword arguments
 
 </div>
 
+> [!NOTE]
+> A few of the features above need a gem the core `robot_lab` gem does not install.
+> **Knowledge & Retrieval** (`memory.store_document` / `memory.search_documents`)
+> and **Runtime Skill Matching** (`AgentSkill` catalogs) both require
+> `robot_lab-document_store`; the Redis backing for **Reactive Memory** requires
+> `redis`; Ractor parallelism requires `robot_lab-ractor`; and
+> `robot.compress_history` requires `classifier`. See
+> [Optional Dependencies](getting-started/installation.md#optional-dependencies).
+
 ## Extension Gems
 
 These optional gems extend RobotLab with additional capabilities:
 
 | Gem | What it adds |
 |-----|-------------|
-| [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) | Rails Engine, generators, `RobotLab::Job` base class, Turbo Stream broadcasting |
-| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | CPU parallelism for `ractor_safe` tools and robot networks via Ruby Ractors |
-| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | Cross-session knowledge persistence — robots accumulate and recall learned facts |
+| [robot_lab-a2a](https://github.com/MadBomber/robot_lab-a2a) | Agent2Agent (A2A) protocol adapter over HTTP + SSE |
+| [robot_lab-audit](https://github.com/MadBomber/robot_lab-audit) | SQLite-backed execution audit log, wired through the Hook system |
+| [robot_lab-discovery](https://github.com/MadBomber/robot_lab-discovery) | Zero-configuration mDNS/DNS-SD robot discovery on the local network |
 | [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | Embedding-based semantic document search powered by fastembed |
+| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | HTM-backed long-term memory — robots accumulate and recall learned facts across sessions |
+| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | CPU parallelism for `ractor_safe` tools and robot networks via Ruby Ractors |
+| [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) | Rails Engine, generators, `RobotLab::Job` base class, Turbo Stream broadcasting |
+| [robot_lab-to](https://github.com/MadBomber/robot_lab-to) | Autonomous overnight agent loop — iterate a robot toward an objective, committing each step |
+| [robot_lab-web](https://github.com/MadBomber/robot_lab-web) | Rails-free Sinatra + HTMX browser console that streams a robot's run over SSE |
+
+> [!NOTE]
+> The Rails Engine, generators, `RobotLab::Job`, and Turbo broadcasting are
+> **only** in `robot_lab-rails`. The core gem ships no Railtie and no generators.
+> The former `robot_lab-acp` gem is retired and superseded by `robot_lab-a2a`.
 
 ## Quick Example
 
@@ -162,7 +181,10 @@ require "robot_lab"
 # Set API keys via env vars:
 #   ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
 #
-# Or place a config file at ~/.config/robot_lab/config.yml
+# Or place a config file at ~/.config/robot_lab/robot_lab.yml
+# (the filename repeats the app name; config.yml is never read). Keys go at the
+# top level, or under a section named for the current environment
+# (development:/test:/production:). Only a `defaults:` wrapper is ignored.
 # Access config values: RobotLab.config.ruby_llm.model  #=> "claude-sonnet-4"
 
 # Create a robot with keyword arguments
@@ -188,6 +210,16 @@ puts result.last_text_content
 robot.with_instructions("Be extra concise.").with_temperature(0.3).run("Explain Ruby in one sentence.")
 ```
 
+> [!IMPORTANT]
+> `Robot#run` defaults to `tools: :none` and `mcp: :none`, so a plain
+> `robot.run("...")` sends the model **no tools** even when you attached them
+> with `local_tools:` or `mcp:` at build time. Ask for them on the run:
+>
+> ```ruby
+> robot.run("...", tools: :inherit)                  # attached local tools
+> robot.run("...", mcp: :inherit, tools: :inherit)   # MCP servers and their tools
+> ```
+
 ## Supported LLM Providers
 
 RobotLab supports multiple LLM providers through the [ruby_llm](https://github.com/crmne/ruby_llm) library:

data/examples/01_simple_robot.rb

@@ -6,13 +6,13 @@
 # Demonstrates creating and running a basic robot with a template.
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/01_simple_robot.rb
+#   ruby examples/01_simple_robot.rb
 
 require_relative "common"
 
 # Create a simple robot using a template
 robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "helper",
   template: :helper
 )

data/examples/02_tools.rb

@@ -6,7 +6,7 @@
 # Demonstrates creating a robot with custom tools using RubyLLM::Tool.
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/02_tools.rb
+#   ruby examples/02_tools.rb
 
 require_relative "common"
 
@@ -78,7 +78,7 @@ end
 
 # Create robot with tools
 robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "assistant",
   template: :assistant,
   local_tools: [Calculator, FortuneCookie]
@@ -86,11 +86,21 @@ robot = RobotLab.build(
 
 banner "Robot with Tools"
 
-# Run the robot
-result = robot.run("What is 15 multiplied by 7? Also, give me a fortune about my career.")
+# Run the robot.
+#
+# tools: :inherit is REQUIRED to actually offer the tools to the model.
+# Robot#run defaults to tools: :none, which means "send zero tools this turn"
+# — the robot still holds them in local_tools, but the provider never sees
+# them and the LLM answers from memory instead of calling Calculator.
+# :inherit means "no per-turn filter, use every attached tool".
+result = robot.run(
+  "What is 15 multiplied by 7? Also, give me a fortune about my career.",
+  tools: :inherit
+)
 
 # Display results
 puts "Robot: #{robot.name}"
+puts "Tools offered: #{robot.local_tools.map(&:name).join(', ')}"
 puts "\nOutput:"
 result.output.each do |message|
   puts "  #{message.content}" if message.respond_to?(:content)

data/examples/03_network.rb

@@ -7,10 +7,12 @@
 # using SimpleFlow's optional step activation.
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key ruby examples/03_network.rb
+#   ruby examples/03_network.rb
 
 require_relative "common"
 
+SPECIALIST_TASKS = %i[billing technical general].freeze
+
 # Classifier robot that activates the appropriate specialist
 class ClassifierRobot < RobotLab::Robot
   def call(result)
@@ -36,32 +38,37 @@ class ClassifierRobot < RobotLab::Robot
   end
 end
 
-# Shared RunConfig — all robots in this network use the same model
-shared_config = RobotLab::RunConfig.new(model: LLM[:default].model)
+# Shared RunConfig — operational defaults every robot in this network inherits.
+#
+# RunConfig has no `provider` field (see RunConfig::FIELDS), and an Ollama
+# model is absent from RubyLLM's registry, so provider and model still travel
+# together on each robot via **llm_opts. The RunConfig carries the settings
+# that genuinely are shared.
+shared_config = RobotLab::RunConfig.new(temperature: 0.3, max_tool_rounds: 5)
 
-# Create specialized robots (no model: needed — inherited from RunConfig)
 classifier = ClassifierRobot.new(
+  **llm_opts,
   name: "classifier",
   template: :classifier,
   config: shared_config
 )
 
 billing_robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "billing",
   template: :billing,
   config: shared_config
 )
 
 technical_robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "technical",
   template: :technical,
   config: shared_config
 )
 
 general_robot = RobotLab.build(
-  model: LLM[:default].model,
+  **llm_opts,
   name: "general",
   template: :general,
   config: shared_config
@@ -76,8 +83,13 @@ network = RobotLab.create_network(name: "support_network", config: shared_config
 end
 
 banner "Multi-Robot Network"
-puts "Network structure:"
-puts network.visualize
+puts "Routing plan:"
+puts "  Entry task: classifier"
+puts "  Optional specialists: #{SPECIALIST_TASKS.join(', ')}"
+puts "  Runtime behavior: classifier activates exactly one specialist"
+puts
+puts "Underlying SimpleFlow structure:"
+puts "  Optional tasks: #{network.to_h[:optional_tasks].join(', ')}"
 hr
 
 # Run the network with a billing question
@@ -85,6 +97,8 @@ result = network.run(message: "I was charged twice for my subscription last mont
 
 # Display results
 puts "Network: #{network.name}"
+puts "Executed tasks: #{result.context.keys.grep_v(:run_params).join(', ')}"
+puts "Skipped specialists: #{(SPECIALIST_TASKS - result.context.keys).join(', ')}"
 puts "\nConversation flow:"
 
 # Show classifier result

data/examples/04_mcp.rb

@@ -9,11 +9,10 @@
 # Prerequisites:
 #   1. Install the GitHub MCP server: brew install github-mcp-server
 #   2. Set environment variables:
-#      - ANTHROPIC_API_KEY: Your Anthropic API key
 #      - GITHUB_PERSONAL_ACCESS_TOKEN: Your GitHub personal access token
 #
 # Usage:
-#   ANTHROPIC_API_KEY=your_key GITHUB_PERSONAL_ACCESS_TOKEN=your_token ruby examples/04_mcp.rb
+#   GITHUB_PERSONAL_ACCESS_TOKEN=your_token ruby examples/04_mcp.rb
 #
 # The GitHub MCP server provides tools for:
 #   - Searching repositories, code, issues, and users
@@ -136,7 +135,7 @@ begin
   # connect_mcp! forces eager connection; without it MCP clients initialize
   # lazily on the first run() call, leaving mcp_clients empty until then.
   robot = RobotLab.build(
-    model: LLM[:default].model,
+    **llm_opts,
     name: "github_assistant",
     template: :github_assistant,
     mcp_servers: [github_server]
@@ -164,7 +163,15 @@ begin
   puts "Query: 'What are the top 3 most starred Ruby web frameworks on GitHub?'"
   hr
 
-  result = robot.run("What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.")
+  # mcp: :inherit and tools: :inherit are both required. Both keywords default
+  # to :none on run(), which resolves to "no MCP servers this turn" and "send
+  # zero tools this turn" — the discovered MCP tools would never reach the
+  # provider and the model would answer from its training data.
+  result = robot.run(
+    "What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.",
+    mcp:   :inherit,
+    tools: :inherit
+  )
 
   puts
   puts "Robot Response:"