robot_lab 0.2.1 → 0.2.6

data/docs/guides/index.md

@@ -42,6 +42,10 @@ If you're new to RobotLab, start here:
 
     Token tracking, circuit breakers, doom loop detection, auto compaction, and learning accumulation
 
+-   [:octicons-zap-24: **Hook System**](hooks.md)
+
+    Lifecycle hooks for instrumentation, response caching, extensions, and cross-cutting concerns
+
 -   [:octicons-search-24: **Knowledge & Retrieval**](knowledge.md)
 
     Chat history search and embedding-based document store for RAG workflows
@@ -59,6 +63,7 @@ If you're new to RobotLab, start here:
 | [Streaming](streaming.md) | Real-time responses | 5 min |
 | [Memory](memory.md) | Shared data store | 5 min |
 | [Observability & Safety](observability.md) | Token tracking, circuit breaker, doom loop detection, auto compaction, learning loop | 10 min |
+| [Hook System](hooks.md) | Lifecycle hooks, extensions, response caching, instrumentation | 15 min |
 | [Knowledge & Retrieval](knowledge.md) | Chat history search and embedding-based document store (RAG) | 10 min |
 
 ## Extension Gems

data/docs/guides/knowledge.md

@@ -184,5 +184,5 @@ This gem bundles `fastembed` for ONNX-based embeddings. The `BAAI/bge-small-en-v
 ## See Also
 
 - [Observability Guide](observability.md)
-- [Example 25 — Chat History Search](../../examples/25_history_search.rb)
-- [Example 26 — Embedding-Based Document Store](../../examples/26_document_store.rb)
+- [examples/25_history_search.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/25_history_search.rb) — Chat History Search
+- [examples/26_document_store.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/26_document_store.rb) — Embedding-Based Document Store

data/docs/guides/observability.md

@@ -10,6 +10,7 @@ Facilities that help you monitor, control, improve, and scale robot behaviour:
 - **Context Window Compression** — prune irrelevant history to stay within token budgets
 - **Convergence Detection** — detect when independent agents reach the same conclusion
 - **Structured Delegation** — synchronous inter-robot calls with duration and token metadata
+- **Live Narration** — an opt-in console feed of what a robot is doing as it happens
 
 ---
 
@@ -91,6 +92,38 @@ result = fresh.run("Explain memoization.")
 puts result.input_tokens  # smallest possible — no prior history
 ```
 
+### Budgets (Token & Cost)
+
+Where token/cost tracking above is purely observational, `token_budget:` and `cost_budget:` make it enforceable — a `Robot` refuses to keep spending once a configured limit is reached:
+
+```ruby
+robot = RobotLab.build(
+  name: "capped",
+  system_prompt: "You are a concise assistant.",
+  token_budget: 10_000,  # cumulative input + output tokens
+  cost_budget: 0.50      # cumulative $ across all runs
+)
+```
+
+Enforcement happens in two layers, backed by a thread-safe `RobotLab::Budget::Ledger`:
+
+- **Before the call** — `run()` reserves whatever remains of each configured dimension. If a *prior* call already exhausted the budget, the reservation raises `RobotLab::BudgetExceeded` immediately, refusing the call outright before spending anything on it.
+- **After the call** — actual usage (tokens from the result, cost from the response, when the provider reports pricing) replaces the reservation. If *this* call's actual usage pushes cumulative usage over budget, `RobotLab::InferenceError` is raised (unavoidable for the call that causes the overage, since totals aren't known until the response comes back) — the same error `token_budget` alone has always raised.
+
+```ruby
+begin
+  robot.run("Another expensive task")
+rescue RobotLab::BudgetExceeded => e
+  puts e.message  # "budget exceeded for cost: 0.51 > 0.5" — refused before spending
+rescue RobotLab::InferenceError => e
+  puts e.message  # "Cost budget exceeded: $0.5231 used, budget is $0.5" — this call pushed it over
+end
+```
+
+A dimension with no configured limit (e.g. `cost_budget` when only `token_budget` is set) is treated as unlimited and never raises. Both fields are also available on `RunConfig` and cascade through the same global → network → robot hierarchy as other infrastructure fields (see [RunConfig](../getting-started/configuration.md#runconfig-shared-operational-defaults)).
+
+This is a native alternative to the hand-rolled `BudgetHook` pattern in the [Hooks guide](hooks.md#cost-enforcement) for the common case of a per-robot token or dollar ceiling; reach for a hook instead when you need cross-robot session totals or custom accounting.
+
 ---
 
 ## Tool Loop Circuit Breaker
@@ -606,13 +639,47 @@ puts "#{analysis.robot_name} (#{analysis.duration.round(2)}s): #{analysis.reply}
 
 ---
 
+## Live Narration (`RobotLab::Narrator`)
+
+`RobotLab::Narrator` is an opt-in [Hook](hooks.md) that narrates what a robot is doing as it happens, to `$stderr` (or any `IO`), so a run is never silent between events. It complements `RobotLab::Audit` (the `robot_lab-audit` gem, which records a persistent history for post-mortem analysis) with a live, human-facing console feed — the two are independent hooks and can both be registered at once.
+
+Enable it globally (applies to every robot run, including networks):
+
+```ruby
+RobotLab::Narrator.enable!                       # narrate to $stderr
+RobotLab::Narrator.enable!(output: $stdout)       # or any IO
+```
+
+Or register it like any hook for a narrower scope:
+
+```ruby
+robot.on(RobotLab::Narrator)
+network.on(RobotLab::Narrator)
+```
+
+Once registered, a run prints a line per event:
+
+```
+  · math_bot: thinking…
+  · → calculate operation="add"
+  · math_bot: thinking…
+```
+
+- Before each LLM call: `"<robot name>: thinking…"`
+- Before each tool call: `"→ <tool name> <first arg>=<value>"` — only the *first* argument is shown, truncated to 80 characters
+- After a tool call: `"  ✗ <error message>"` — printed only when the tool raised; silent on success
+
+Narrator uses `IO#puts` rather than `Kernel#warn`, since `warn` is silenced whenever Ruby warnings are disabled (`$VERBOSE` is `nil`, the common case under `bundle exec`). All three hooks rescue internally, so a narration failure never breaks the underlying run.
+
+---
+
 ## See Also
 
-- [Robot API](../api/core/robot.md#token--cost-tracking)
-- [Example 19 — Token & Cost Tracking](../../examples/19_token_tracking.rb)
-- [Example 20 — Tool Loop Circuit Breaker](../../examples/20_circuit_breaker.rb)
-- [Example 21 — Learning Accumulation Loop](../../examples/21_learning_loop.rb)
-- [Example 22 — Context Window Compression](../../examples/22_context_compression.rb)
-- [Example 23 — Convergence Detection](../../examples/23_convergence.rb)
-- [Example 24 — Structured Delegation](../../examples/24_structured_delegation.rb)
+- [Robot API](../api/core/robot.md#token-cost-tracking)
+- [examples/19_token_tracking.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/19_token_tracking.rb) — Token & Cost Tracking
+- [examples/20_circuit_breaker.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/20_circuit_breaker.rb) — Tool Loop Circuit Breaker
+- [examples/21_learning_loop.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/21_learning_loop.rb) — Learning Accumulation Loop
+- [examples/22_context_compression.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/22_context_compression.rb) — Context Window Compression
+- [examples/23_convergence.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/23_convergence.rb) — Convergence Detection
+- [examples/24_structured_delegation.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/24_structured_delegation.rb) — Structured Delegation
 - [RunConfig reference](../getting-started/configuration.md#runconfig-shared-operational-defaults)

data/docs/guides/using-tools.md

@@ -133,6 +133,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:
@@ -163,6 +172,66 @@ robot = RobotLab.build(name: "assistant", system_prompt: "...")
 robot.with_tools(GetWeather, CalculatorTool)
 ```
 
+## 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
+robot.run("Only use the calculator.", tools: %w[calculator])  # allowlist by name
+```
+
+| Value | Meaning |
+|-------|---------|
+| `:inherit` | No filter — use every tool attached at the robot/network/global level |
+| `:none`, `[]`, `nil` | Send **zero** tools this turn |
+| `["name", ...]` | Only these tool names, by exact match |
+
+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.
+
+> **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 current runtime default takes the explicit-`:none` path above — sending no tools for that turn. Pass `tools: :inherit` explicitly (at build time, per network task, or per `run()` call — wherever fits your call site) anywhere you need the robot's attached tools available.
+
+### 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 `max_tools:` on `RunConfig` (or the `max_tools:` cascade field — see [Available Fields](../getting-started/configuration.md#available-fields)); `nil` or `<= 0` disables the cap
+- 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
+
+## 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`:

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**
 

data/examples/03_network.rb

@@ -11,6 +11,8 @@
 
 require_relative "common"
 
+SPECIALIST_TASKS = %i[billing technical general].freeze
+
 # Classifier robot that activates the appropriate specialist
 class ClassifierRobot < RobotLab::Robot
   def call(result)
@@ -76,8 +78,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 +92,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/35_hooks.rb

@@ -0,0 +1,256 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 35: Hooks Architecture with robot_lab-xyzzy
+#
+# Demonstrates the hook handler class pattern. Hooks are named classes that
+# inherit from RobotLab::Hook and implement class methods for each lifecycle
+# phase they care about. All hooks are Ractor-safe by default.
+#
+# Usage:
+#   bundle exec ruby examples/35_hooks.rb
+
+require_relative "common"
+require_relative "xyzzy"
+
+XYZZY_LOG = File.join(__dir__, "xyzzy_hooks.log")
+RobotLab::Xyzzy.logger = Logger.new(XYZZY_LOG)
+
+# ---------------------------------------------------------------------------
+# Handler classes used in this demo
+# ---------------------------------------------------------------------------
+
+class RuntimeDemoHook < RobotLab::Hook
+  self.namespace = :runtime_demo
+
+  def self.after_run(ctx)
+    ctx.local.reply_seen = ctx.response.reply
+  end
+end
+
+class LocalDemoHook < RobotLab::Hook
+  self.namespace = :local_demo
+
+  def self.before_run(ctx)
+    ctx.local.note = "local robot hook state"
+    ctx.local.demo = "robot_run"
+  end
+end
+
+class PerfHook < RobotLab::Hook
+  self.namespace = :perf
+  @timings = []
+  @mutex = Mutex.new
+
+  class << self
+    def reset!
+      @mutex.synchronize { @timings = [] }
+    end
+
+    def timings
+      @mutex.synchronize { @timings.dup }
+    end
+
+    def around_run(ctx, &block)
+      t0     = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = block.call
+      elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1_000).round(3)
+      @mutex.synchronize { @timings << elapsed }
+      puts "  [perf]      #{ctx.request.inspect} — #{elapsed}ms"
+      result
+    end
+  end
+end
+
+class GenerationTracerHook < RobotLab::Hook
+  self.namespace = :tracer
+
+  def self.before_llm_generation(ctx)
+    puts "  [tracer]    llm_generation start  request=#{ctx.request.inspect}"
+  end
+
+  def self.after_llm_generation(ctx)
+    msg = ctx.generation_response
+    puts "  [tracer]    llm_generation done   model=#{msg&.model_id}  tokens=#{msg&.output_tokens}"
+  end
+end
+
+class GenCacheHook < RobotLab::Hook
+  self.namespace = :gen_cache
+  @cache = {}
+  @mutex = Mutex.new
+  @call_count = 0
+
+  class << self
+    def reset!
+      @mutex.synchronize do
+        @cache = {}
+        @call_count = 0
+      end
+    end
+
+    def call_count
+      @mutex.synchronize { @call_count }
+    end
+
+    def around_llm_generation(ctx, &block)
+      cached = @mutex.synchronize { @cache[ctx.request] }
+      if cached
+        puts "  [gen_cache] HIT  — skipping LLM"
+        cached
+      else
+        puts "  [gen_cache] MISS — calling LLM"
+        @mutex.synchronize { @call_count += 1 }
+        block.call.tap { |r| @mutex.synchronize { @cache[ctx.request] = r } }
+      end
+    end
+  end
+end
+
+class NetworkDemoHook < RobotLab::Hook
+  self.namespace = :network_demo
+
+  def self.before_task(ctx)
+    ctx.local.task_note = "network-scoped task hook"
+  end
+end
+
+# ---------------------------------------------------------------------------
+
+HookDemoResponse = Data.define(:content, :tool_calls, :stop_reason) do
+  def initialize(content:, tool_calls: nil, stop_reason: "end_turn")
+    super
+  end
+end
+
+class HookDemoTool < RobotLab::Tool
+  description "Returns a deterministic hook demo value"
+  param :label, type: "string", desc: "The label to echo"
+
+  def execute(label:)
+    { label: label, status: "handled by HookDemoTool" }
+  end
+end
+
+class HookDemo
+  def run
+    banner "Hooks Architecture with robot_lab-xyzzy"
+
+    explain_setup
+    run_robot
+    run_llm_loop
+    run_tool
+    run_network
+    run_error
+
+    hr
+    puts "Hook demo complete."
+  end
+
+  private
+
+  def explain_setup
+    section "Extension Registration"
+    puts <<~TEXT
+      xyzzy.rb is a single-file hook extension loaded from examples/.
+
+      It is a RobotLab::Hook subclass registered under namespace :#{RobotLab::Xyzzy.namespace}.
+      stdout  : [xyzzy] timestamp hook_name  (one line per call)
+      logfile : full context snapshot  →  #{XYZZY_LOG}
+    TEXT
+  end
+
+  def run_robot
+    section "Robot Run Hooks"
+    robot = hooked_robot("hook_demo_robot")
+    robot.on(LocalDemoHook)
+
+    result = robot.run("show the hook pipeline", hooks: RuntimeDemoHook)
+
+    puts "Robot reply: #{result.reply}"
+  end
+
+  def run_llm_loop
+    section "LLM Request/Response Loop"
+    puts <<~TEXT
+      Demonstrates before/around/after_llm_generation hooks.
+      GenCacheHook implements around_llm_generation: on a cache hit the block
+      (the real LLM call) is never invoked. PerfHook times each robot.run call.
+    TEXT
+
+    GenCacheHook.reset!
+    PerfHook.reset!
+
+    puts "  provider=#{LLM[:default].provider}  model=#{LLM[:default].model}\n\n"
+
+    robot = RobotLab.build(
+      name: "loop_demo_robot",
+      system_prompt: "You are a helpful assistant. Answer every question in one concise sentence."
+    ).with_model(LLM[:default].model)
+
+    robot.on(PerfHook)
+    robot.on(GenerationTracerHook)
+    robot.on(GenCacheHook)
+
+    queries = [
+      "what is the boiling point of water?",
+      "what is 6 * 7?",
+      "what is the boiling point of water?",
+      "what is 6 * 7?"
+    ]
+
+    queries.each_with_index do |query, i|
+      puts "\n--- query #{i + 1}: #{query.inspect} ---"
+      result = robot.run(query)
+      puts "  reply:      #{result.reply}"
+    end
+
+    timings     = PerfHook.timings
+    cache_hits  = queries.size - GenCacheHook.call_count
+    avg_ms      = (timings.sum / timings.size).round(3)
+    puts "\n--- summary ---"
+    puts "  robot.run calls : #{queries.size}"
+    puts "  LLM calls made  : #{GenCacheHook.call_count}  (#{cache_hits} served from gen_cache)"
+    puts "  avg run time    : #{avg_ms}ms"
+  end
+
+  def run_tool
+    section "Tool Call Hooks"
+    tool   = HookDemoTool.new
+    result = tool.call({ "label" => "tool hook payload" })
+    puts "Tool result: #{result.inspect}"
+  end
+
+  def run_network
+    section "Network and Task Hooks"
+    network = RobotLab::Network.new(name: "hook_demo_network")
+    network.on(NetworkDemoHook)
+    network.task(:summarize, hooked_robot("network_worker"), depends_on: :none)
+
+    result = network.run(message: "summarize hook activity")
+    reply = result.respond_to?(:reply) ? result.reply : result&.value&.reply
+    puts "Network result: #{reply}"
+  end
+
+  def run_error
+    section "Error Hook"
+    failing_robot = RobotLab.build(name: "failing_hook_robot", system_prompt: "raise")
+    failing_robot.instance_variable_get(:@chat).define_singleton_method(:ask) do |_message = nil, **_kwargs|
+      raise "planned hook demo failure"
+    end
+
+    failing_robot.run("trigger the on_error hook")
+  rescue RuntimeError => e
+    puts "Caught expected error: #{e.message}"
+  end
+
+  def hooked_robot(name)
+    RobotLab.build(name: name, system_prompt: "deterministic hook demo").tap do |robot|
+      robot.instance_variable_get(:@chat).define_singleton_method(:ask) do |message = nil, **_kwargs, &_block|
+        HookDemoResponse.new(content: "deterministic response to #{message.inspect}")
+      end
+    end
+  end
+end
+
+HookDemo.new.run

data/examples/README.md

@@ -58,6 +58,7 @@ examples/
   29_ractor_tools.rb          # Ractor-safe tools: worker pool, freeze_deep, parallel batch
   30_ractor_network.rb        # Ractor network scheduler: dependency waves, parallel_mode
   31_launch_assessment.rb     # 6 parallel analysts, max_concurrent_robots: 4 semaphore cap
+  35_hooks.rb                 # Hook architecture demo using robot_lab-xyzzy
   18_rails/                   # Minimal Rails 8 demo app (full integration)
     app/robots/chat_robot.rb  #   Robot factory with system prompt + TimeTool
     app/tools/time_tool.rb    #   Custom RobotLab::Tool subclass
@@ -306,6 +307,12 @@ Demonstrates: `max_concurrent_robots:` on `RunConfig`, `Async::Semaphore` back-p
 
 **Requires:** LLM API key
 
+### 35 — Hooks Architecture
+
+Loads the local `robot_lab-xyzzy` extension, which registers for every hook and logs each callback with the context it receives. Demonstrates robot run, LLM generation, tool call, network run, task, and error hooks with deterministic stubbed responses.
+
+**Requires:** None (no LLM calls)
+
 ### 18 — Rails Integration Demo
 
 A minimal, hand-built Rails 8 app that exercises every piece of RobotLab's Rails integration end-to-end. No `rails new` — every file is hand-crafted for minimum size.

data/examples/common.rb

@@ -10,14 +10,18 @@ require_relative "../lib/robot_lab"
 LlmConfig = Data.define(:provider, :model)
 
 LLM = {
-  default:   LlmConfig.new(provider: "openai",    model: "gpt-5.4"),
+  default:   LlmConfig.new(provider: "openai",    model: "gpt-4.1-mini"),
   local:     LlmConfig.new(provider: "ollama",    model: "llama3.2"),
   anthropic: LlmConfig.new(provider: "anthropic", model: "claude-opus-4-7")
 }.freeze
 
 RubyLLM.configure do |c|
-  c.logger        = Logger.new(File::NULL)
-  c.default_model = LLM[:default].model
+  c.logger                  = Logger.new(File::NULL)
+  c.default_model           = LLM[:default].model
+  c.openai_api_key          = ENV['OPENAI_API_KEY']
+  c.openai_organization_id  = ENV['OPENAI_ORGANIZATION_ID']
+  c.openai_project_id       = ENV['OPENAI_PROJECT_ID']
+  c.anthropic_api_key       = ENV['ANTHROPIC_API_KEY']
 end
 
 RobotLab.configure do |c|

data/examples/xyzzy.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# xyzzy.rb — single-file RobotLab hook extension demo
+#
+# Demonstrates the Hook handler class pattern: implement class methods for
+# every hook under a dedicated namespace and log each callback with its
+# context snapshot. Useful as a live trace of the full hook pipeline during
+# development.
+#
+# Fully Ractor-safe: no class-level mutable state. LOG_PATH is a frozen
+# string constant (shareable); each call opens its own file handle.
+#
+# stdout : one tagline per hook call  →  [xyzzy] HH:MM:SS.mmm hook_name
+# logfile: full context snapshot written to LOG_PATH via PP.pp
+#
+# Usage (from any example that requires common):
+#   require_relative "xyzzy"
+
+require "pp"
+require "fileutils"
+
+module RobotLab
+  class Xyzzy < Hook
+    self.namespace = :xyzzy
+
+    LOG_PATH = File.expand_path("~/.robot_lab/xyzzy_hooks.log").freeze
+    FileUtils.mkdir_p(File.dirname(LOG_PATH))
+
+    class << self
+      def before_run(ctx)               = log_hook(:before_run, ctx)
+      def after_run(ctx)                = log_hook(:after_run, ctx)
+      def on_error(ctx)                 = log_hook(:on_error, ctx)
+      def before_llm_generation(ctx)    = log_hook(:before_llm_generation, ctx)
+      def after_llm_generation(ctx)     = log_hook(:after_llm_generation, ctx)
+      def before_tool_call(ctx)         = log_hook(:before_tool_call, ctx)
+      def after_tool_call(ctx)          = log_hook(:after_tool_call, ctx)
+      def before_network_run(ctx)       = log_hook(:before_network_run, ctx)
+      def after_network_run(ctx)        = log_hook(:after_network_run, ctx)
+      def before_task(ctx)              = log_hook(:before_task, ctx)
+      def after_task(ctx)               = log_hook(:after_task, ctx)
+
+      def around_run(ctx, &block)
+        log_hook(:around_run, ctx)
+        block.call
+      end
+
+      def around_llm_generation(ctx, &block)
+        log_hook(:around_llm_generation, ctx)
+        block.call
+      end
+
+      def around_tool_call(ctx, &block)
+        log_hook(:around_tool_call, ctx)
+        block.call
+      end
+
+      def around_network_run(ctx, &block)
+        log_hook(:around_network_run, ctx)
+        block.call
+      end
+
+      def around_task(ctx, &block)
+        log_hook(:around_task, ctx)
+        block.call
+      end
+
+      private
+
+      def log_hook(hook_name, ctx)
+        ts       = Time.now.strftime('%H:%M:%S.%3N')
+        snapshot = context_snapshot(ctx)
+        $stdout.puts "  [xyzzy] #{ts} #{hook_name}"
+        File.open(LOG_PATH, "a") { |f| f.puts "#{ts} #{hook_name} | #{PP.pp(snapshot, +"").chomp}" }
+      end
+
+      def context_snapshot(ctx)
+        {
+          robot:   ctx.respond_to?(:robot)   ? ctx.robot&.name    : nil,
+          request: ctx.respond_to?(:request) ? ctx.request        : nil,
+          network: ctx.respond_to?(:network) ? ctx.network&.name  : nil,
+          task:    ctx.respond_to?(:task)    ? ctx.task           : nil,
+          error:   ctx.respond_to?(:error)   ? ctx.error&.message : nil
+        }.compact
+      end
+    end
+  end
+end
+
+RobotLab.register_extension(:xyzzy, RobotLab::Xyzzy) if RobotLab.respond_to?(:register_extension)
+RobotLab.on(RobotLab::Xyzzy)