robot_lab 0.1.0 → 0.2.6

data/CHANGELOG.md

@@ -8,6 +8,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `BusMessaging#respond_to_tasks` and `#serve` — a member auto-answers inbound
+  (non-reply) bus tasks and replies to the sender. `serve` runs each task through
+  `#run`; `respond_to_tasks { |m| ... }` is the generic form. Makes a Robot a
+  first-class bus responder (symmetric with how a Cyborg answers its human)
+  without hand-wiring `on_message`.
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, `integration`, `docs`, and `examples` tasks via the Asgard task runner
+
+### Fixed
+- `BusMessaging` now synchronizes its message counter and outbox with a mutex, so
+  concurrent sends and poller-thread reply correlation can't clobber each other.
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` gem added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
+## [0.2.6] - 2026-05-23
+
+### Added
+
+- **`:compaction` hook family** — fires when `maybe_compact` determines that conversation history should be compressed. Provides `before_compaction`, `around_compaction`, `after_compaction`, and `on_compaction` callbacks.
+  - `on_compaction` allows an extension to supply a complete replacement message set via `ctx.compacted_messages`; when set, the core skips its own compaction strategy entirely (`ctx.handled?` returns true).
+  - `CompactionHookContext` — carries `robot`, `messages_before` (frozen snapshot), `config`, `strategy` (`:context_window`, `:custom`, or other symbol), `compacted_messages`, and `handled?`.
+- **`:learn` hook family** — fires on every `robot.learn(text)` call with non-empty text. Provides `before_learn`, `around_learn`, `after_learn`, and `on_learn` callbacks.
+  - `on_learn` fires after the text has been stored and `ctx.stored = true`, giving extensions a reliable hook point for cross-session persistence.
+  - `LearnHookContext` — carries `robot`, `text`, `learnings_before` (frozen snapshot), and `stored`.
+- **`over_compact_threshold?`** private predicate extracted from `compact_if_over_context_window` for independent testability.
+- Hook tests for both new families added to `test/robot_lab/hooks_test.rb` (18 new tests across `RobotLabCompactionHooksTest` and `RobotLabLearnHooksTest`).
+- Documentation for `:compaction` and `:learn` hook families added to `docs/guides/hooks.md`.
+
+### Changed
+
+- **`Robot#on`** now accepts and forwards `context:` to `HookRegistry#on`, allowing extensions to pass per-registration domain config at registration time (e.g. `robot.on(MyHook, context: { domain: "finance" })`). Previously `context:` was silently dropped.
+- **`maybe_compact`** refactored to dispatch through the `:compaction` hook family and delegate to `on_compaction` before falling back to the built-in strategy.
+- **`Robot#learn`** refactored to dispatch through the `:learn` hook family; `on_learn` fires after deduplication with `ctx.stored` reflecting whether the text was actually added.
+
+### Added
+
+- **`RobotLab::Hook` base class** (`lib/robot_lab/hook.rb`) — all hook handlers inherit from this class. Subclasses define lifecycle callbacks as `class << self` methods (`before_run`, `after_run`, etc.). Namespace is auto-derived from the class name via snake_case conversion of the final class name segment (e.g. `AuditHook` → `:audit_hook`); override with `self.namespace = :custom`. Ractor-safe by design: handler classes are Ruby constants, not Procs, so registrations are natively serializable across Ractor boundaries.
+- **Hook system** — lifecycle hooks across all execution boundaries. Register handler classes with `RobotLab.on`, `network.on`, or `robot.on` for five families: `:run`, `:llm_generation`, `:tool_call`, `:network_run`, and `:task`, each with `before_*`, `around_*`, `after_*`, and (where applicable) `on_error` variants.
+  - `HookRegistry::Registration` — `Data.define(:handler_class, :context)`; stores a handler class reference and optional per-registration default `DotState` values. No Proc, no namespace field — namespace is read from the handler class.
+  - `HookContext` and five typed subclasses: `RunHookContext`, `LlmGenerationHookContext`, `ToolCallHookContext`, `NetworkRunHookContext`, `TaskHookContext` — unchanged
+  - `DotState` / `ExtensionState` — namespace-isolated dot-access state carried on every context object; `ctx.local` reads/writes state for the active handler's namespace
+  - `context:` parameter on `on(handler_class, context: {...})` — sets per-registration default `DotState` values merged in before each callback fires
+  - Around hooks chain correctly across handler class registrations; return value is propagated up the chain
+  - Per-run hooks via `robot.run("msg", hooks: MyHook)` or `robot.run("msg", hooks: [MyHook, OtherHook])`
+  - `on_error` fires for `:run`, `:network_run`, and `:task` families; exception is re-raised after all error handlers complete
+- **`examples/xyzzy.rb`** — updated reference extension: `RobotLab::Xyzzy < RobotLab::Hook` with `class << self` methods for every hook family; logs each callback with a timestamped stdout tagline and a structured logger context snapshot; registered globally with `RobotLab.on(RobotLab::Xyzzy)`
+- **Example 35** (`examples/35_hooks.rb`) — updated full hook pipeline demo: xyzzy extension tracing all hooks, `around_run` perf timer handler class, `around_llm_generation` response cache handler class (cache hits skip the LLM entirely), `before/after_llm_generation` tracer, tool call hooks, network/task hooks, and `on_error`
+- **`examples/common.rb`** — added explicit `openai_api_key`, `openai_organization_id`, and `openai_project_id` to `RubyLLM.configure` to match provider configurator expectations; updated default model to `gpt-4.1-mini`
+
+## [0.2.1] - 2026-05-19
+
+### Added
+
+- **`examples/common.rb`** — shared setup file required by all numbered examples. Defines:
+  - `LlmConfig = Data.define(:provider, :model)` and a frozen `LLM` hash with `:default` (OpenAI/gpt-5.4), `:local` (Ollama/llama3.2), and `:anthropic` (claude-opus-4-7) entries — access as `LLM[:default].model`
+  - `RubyLLM.configure` with null logger and `LLM[:default].model` as `default_model`
+  - `RobotLab.configure` with null logger
+  - Output helpers: `banner(title)`, `section(title)`, `hr`, `show_code(ruby_string, label:)` using `rouge` for syntax highlighting
+- **`rouge` gem** added to development group for syntax-highlighted example output
+- **`.envrc` files** in `examples/`, `examples/14_rusty_circuit/`, `examples/15_memory_network_and_bus/`, and `examples/16_writers_room/` — each exports `ROBOT_LAB_TEMPLATE_PATH` pointing at the local `prompts/` directory for use with [direnv](https://direnv.net/)
+
+### Changed
+
+- **All 27+ numbered examples** refactored to `require_relative "common"` instead of requiring the gem directly, and to use `LLM[:default].model` instead of the hardcoded string `"gpt-5.4"`
+- **Example 04 (MCP)** now calls `robot.connect_mcp!` before inspecting MCP attributes, fixing a lazy-initialization issue where `mcp_clients` and `mcp_tools` were empty until the first `run()` call
+
+## [0.2.1] - 2026-05-11 (unreleased)
+
+### Added
+
+- **`flog` complexity gate** — `flog_check` Rake task enforces method-level complexity limits (warn ≥20, fail ≥50); `quality` task runs tests, RuboCop, and Flog in sequence with a unified pass/fail summary
+- `flog` gem added to development/test group
+- Branch coverage enabled unconditionally (previously CI-only) with minimum thresholds: line 95%, branch 75%
+
+### Changed
+
+- Bumped version to 0.2.1
+- **`Robot#initialize` decomposed** into focused private methods: `assign_identity_ivars`, `build_effective_config`, `extract_config_ivars`, `initialize_runtime_state`, `initialize_memory`, `configure_learning`, `apply_template`, `apply_system_prompt`, `apply_chat_params`, `register_chat_callbacks`
+- **`Robot#run` decomposed** into: `resolve_run_memory`, `prepare_tools`, `invoke_ask`, `enforce_token_budget!`
+- **`BusPoller#process_and_drain`** split into `drain_queued_deliveries` and `release_robot` for independent testability
+- **`TemplateRendering#apply_skills_and_template_to_chat`** split into `collect_prompt_content` (pure computation) and `apply_prompt_to_chat` (pure mutation)
+- Removed `.serena/` project configuration files from version control
+- Removed `.claude/memory.sqlite3` database files from version control
+
+## [0.2.0] - 2026-05-07
+
+### Added
+
+- **`Durable::Learning`** — cross-session and within-session learning capability for robots. Robots accept `learn: true` and `learn_domain:` constructor params to persist knowledge across sessions via `~/.robot_lab/durable/` YAML files.
+- **`Durable::Store`** — YAML-backed knowledge store with file locking, keyword recall, and confidence tracking.
+- **`Durable::Entry`** — immutable value object for knowledge records with confidence progression.
+- **`Durable::Reflector`** — promotes session learnings to durable storage at end of each run.
+- **`RecallKnowledge` tool** — robots query past knowledge before uncertain decisions.
+- **`RecordKnowledge` tool** — robots persist new knowledge learned during a session.
+- **`AgentSkill`** — value object for discoverable skills defined by `SKILL.md` files with YAML front matter (name, description, version, dependencies, parameters)
+- **`AgentSkillCatalog`** — service for locating and indexing `AgentSkills/` directories at runtime
+- **`AgentSkillMatching`** — `Robot` mixin enabling runtime embedding-based skill injection: the robot selects the most relevant skills from a catalog based on semantic similarity before each run
+- **`ScriptTool`** — factory that wraps shell scripts as robot tools; auto-generates JSON schema from script `--help` output
+- **`DoomLoopDetector`** — detects consecutive and cyclic tool-call repetition; wired into `Robot#run` via singleton `execute_tool` override
+- **`doom_loop_threshold`** field on `RunConfig` — configures the repetition threshold before a `ToolLoopError` is raised
+- **`auto_compact` and `compact_threshold`** fields on `RunConfig` — `:context_window` mode estimates token usage before each run and calls `compress_history` when usage exceeds the threshold (default 80%); a `Proc` value delegates the decision and strategy entirely to the caller
+
+### Changed
+
+- Bumped version to 0.2.0
+- **Extension gems extracted** — `robot_lab-document_store`, `robot_lab-durable`, `robot_lab-ractor`, and `robot_lab-rails` are now separate gems distributed via rubygems.org; the core gemspec drops `fastembed`, `ractor_queue`, and `ractor-wrapper` as hard dependencies
+- **`Durable::Learning` inclusion** is now conditional on the `robot_lab-durable` gem being loaded
+- **Tool Ractor routing** guarded on `RobotLab.respond_to?(:ractor_pool)` so the core gem runs without the ractor extension
+- **Memory drainer scheduling** — `@drainer_scheduled` remains `true` when rescheduling to prevent concurrent writers from spawning competing drain fibers
+- `@chat` state reset now uses `reset_messages!` / `add_message` public API instead of internal instance variable manipulation
+- Rails generators moved to `robot_lab-rails` extension gem
+
+### Fixed
+
+- Memory drainer double-schedule race when concurrent writers triggered overlapping drain cycles
+- `DocumentStore` instantiation guarded with a `LoadError` message when the extension gem is absent
+- `AgentSkill` YAML parsing hardened against empty strings and non-Hash front matter
+- Missing requires added to examples after gem extraction
+- `doom_loop_threshold` and `auto_compact` documented in README and guides
+- `learn:` parameter and `robot_lab-acp` documented in README
+
 ## [0.1.0] - 2026-04-29
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+RobotLab is a Ruby framework for building and orchestrating multi-robot LLM workflows. It provides:
+- **Robots**: LLM agents with tools, templates, and memory
+- **Networks**: Orchestration of multiple robots with routing logic
+- **MCP Integration**: Model Context Protocol for external tool servers
+- **Rails Integration**: Generators and ActiveRecord support for conversation history
+
+Built on top of [ruby_llm](https://rubyllm.com) and uses Zeitwerk for autoloading.
+
+## Commands
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run a single test file
+bundle exec rake test_file[robot_lab/robot_test.rb]
+
+# Run tests with verbose output
+bundle exec rake test_verbose
+
+# Run integration tests only
+bundle exec rake integration
+
+# Lint with RuboCop
+bundle exec rubocop
+
+# Auto-fix RuboCop offenses
+bundle exec rubocop -a
+
+# Run all examples
+bundle exec rake examples:all
+
+# Run specific example by number (e.g., 01, 02)
+bundle exec rake examples:run[1]
+```
+
+## Architecture
+
+### Core Classes
+
+- **`RobotLab`** (`lib/robot_lab.rb`): Module entry point with factory methods `build()` for robots and `create_network()` for networks
+- **`Robot`** (`lib/robot_lab/robot.rb`): Subclass of `RubyLLM::Agent` with template-based prompts, tools, MCP clients, and memory. Creates a persistent chat on initialization. Use `robot.run("...")` to interact. When standalone uses its own memory; when in a network uses shared network memory
+- **`Network`** (`lib/robot_lab/network.rb`): Orchestrates multiple robots with routing logic. Robots execute sequentially sharing memory. Router is a lambda that returns robot names
+- **`NetworkRun`** (`lib/robot_lab/network_run.rb`): Stateful execution of a network run with isolated memory clone
+
+### RunConfig
+
+- **`RunConfig`** (`lib/robot_lab/run_config.rb`): Shared configuration object for LLM, tools, callbacks, and infrastructure settings. Flows through the hierarchy: `RobotLab.config -> Network -> Robot -> Template front matter -> Task -> Runtime`. Supports keyword construction, block DSL, merge semantics (more-specific wins), and `apply_to(chat)` for LLM field application. Both Robot and Network accept `config:` parameter. Infrastructure fields include: `bus`, `enable_cache`, `max_tool_rounds`, `token_budget`, `ractor_pool_size`, `max_concurrent_robots`, `doom_loop_threshold`, `auto_compact`, `compact_threshold`.
+
+### Memory System
+
+- **`Memory`** (`lib/robot_lab/memory.rb`): Key-value store with reserved keys (`:data`, `:results`, `:messages`, `:session_id`, `:cache`). Supports Redis backend. Includes semantic caching via RubyLLM::SemanticCache
+
+### MCP (Model Context Protocol)
+
+- **`MCP::Client`** (`lib/robot_lab/mcp/client.rb`): Connects to MCP servers
+- **Transports** (`lib/robot_lab/mcp/transports/`): stdio, websocket, SSE, streamable HTTP
+
+### Built-in Tools
+
+- **`AskUser`** (`lib/robot_lab/ask_user.rb`): Tool that lets a robot ask the user a question via the terminal. Supports open-ended text, multiple choice, and default values. IO sourced from `robot.input`/`robot.output` (defaults to `$stdin`/`$stdout`)
+
+### Adapters
+
+Provider adapters in `lib/robot_lab/adapters/`: Anthropic, OpenAI, Gemini (for provider-specific formatting)
+
+### Configuration Hierarchy
+
+Tools and MCP servers use hierarchical configuration: `runtime > robot > network > global config`. Values can be `:none`, `:inherit`, or explicit arrays.
+
+## Key Patterns
+
+### Creating Robots
+
+```ruby
+# Bare robot (no template or prompt)
+robot = RobotLab.build
+robot.with_instructions("You are helpful.").run("Hello!")
+
+# With template (.md file in prompts directory with YAML front matter)
+robot = RobotLab.build(name: "helper", template: :helper, context: { key: "value" })
+result = robot.run("Hello!")
+
+# With inline system prompt
+robot = RobotLab.build(name: "bot", system_prompt: "You are helpful.")
+result = robot.run("What can you do?")
+
+# With tools
+robot = RobotLab.build(name: "bot", system_prompt: "...", local_tools: [my_tool])
+
+# Chaining with_* methods
+robot.with_temperature(0.9).with_model("claude-sonnet-4").run("Be creative!")
+```
+
+### Creating Networks
+
+```ruby
+router = ->(args) { args.call_count.zero? ? ["classifier"] : nil }
+network = RobotLab.create_network(name: "support", robots: [robot1, robot2], router: router)
+result = network.run(message: "Hello")
+```
+
+### Router Args
+
+Router receives `Router::Args` with: `context`, `network`, `stack`, `call_count`, `last_result`
+
+## Testing
+
+- Uses Minitest with SimpleCov for coverage
+- Test helper at `test/test_helper.rb` provides `build_robot`, `build_network`, `build_tool` helpers
+- Templates for tests are in `examples/prompts/`
+- VCR and WebMock for HTTP stubbing
+
+## Dependencies
+
+Core: zeitwerk, ruby_llm (~> 1.12), ruby_llm-mcp, prompt_manager, ruby_llm-schema, ruby_llm-semantic_cache, async, simple_flow, state_machines
+
+### Templates
+
+Templates use prompt_manager format: single `.md` files with YAML front matter in the configured prompts directory.
+
+```markdown
+---
+description: A helpful assistant
+parameters:
+  company_name: null
+  tone: friendly
+---
+You are a helpful assistant for <%= company_name %>.
+Respond in a <%= tone %> manner.
+```
+
+Front matter supports: `description`, `parameters` (null = required), LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, etc.), and robot extras (`robot_name`, `tools`, `mcp`). Constructor-provided values always override front matter.

data/README.md

@@ -25,8 +25,9 @@
 - <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>Hook System</strong> - Lifecycle hooks across every execution boundary for instrumentation, caching, and extensions<br>
 - <strong>Layered Configuration</strong> - Cascading YAML, env vars, and RunConfig<br>
-- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting<br>
+- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting (via <a href="https://github.com/MadBomber/robot_lab-rails">robot_lab-rails</a>)<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>
@@ -93,7 +94,7 @@ robot = RobotLab.build(
 
 ### 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:
+RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. Configuration is loaded automatically from multiple sources in priority order:
 
 1. Bundled defaults (`lib/robot_lab/config/defaults.yml`)
 2. Environment-specific overrides (development, test, production)
@@ -124,6 +125,14 @@ ruby_llm:
   request_timeout: 180
 ```
 
+Runtime-only attributes (such as the logger) can be set with a `configure` block:
+
+```ruby
+RobotLab.configure do |c|
+  c.logger = Logger.new(File::NULL)   # silence logging
+end
+```
+
 ### Using Templates
 
 For production applications, RobotLab supports a template system built on [PromptManager](https://github.com/MadBomber/prompt_manager). Templates allow you to:
@@ -677,6 +686,67 @@ robot.clear_messages   # flushes broken history; system prompt is kept
 result = robot.run("Something new.")  # robot is healthy again
 ```
 
+## Doom Loop Detection
+
+Doom loop detection catches the subtler failure mode where a robot repeats the same tool call pattern indefinitely — not hitting `max_tool_rounds`, but cycling through the same sequence over and over. Set `doom_loop_threshold:` to enable it:
+
+```ruby
+robot = RobotLab.build(
+  name: "runner",
+  system_prompt: "Execute steps.",
+  local_tools: [StepTool],
+  doom_loop_threshold: 3   # alert after 3 identical consecutive or cyclic sequences
+)
+```
+
+When a doom loop is detected, a warning is embedded directly into the tool result, prompting the LLM to try a different approach. Detection covers both consecutive repetition (`A,A,A`) and cyclic patterns (`A,B,C,A,B,C`). Via `RunConfig`:
+
+```ruby
+config = RobotLab::RunConfig.new(doom_loop_threshold: 3)
+robot  = RobotLab.build(name: "runner", system_prompt: "...", config: config)
+```
+
+## Automatic Context Compaction
+
+`auto_compact` triggers context window compression automatically before each `run()`, preventing context overflow without manual intervention.
+
+```ruby
+# Built-in trigger: compact when estimated token usage exceeds 80% of context window
+robot = RobotLab.build(
+  name: "analyst",
+  system_prompt: "You are a research analyst.",
+  auto_compact: :context_window
+)
+
+# Tune the threshold (here: compact at 70%)
+robot = RobotLab.build(
+  name: "analyst",
+  system_prompt: "You are a research analyst.",
+  auto_compact:      :context_window,
+  compact_threshold: 0.70
+)
+
+# Application-owned compaction: full control over when and how
+robot = RobotLab.build(
+  name: "analyst",
+  system_prompt: "You are a research analyst.",
+  auto_compact: ->(r) { r.compress_history(recent_turns: 5) if r.chat.messages.size > 40 }
+)
+```
+
+| Value | Behaviour |
+|-------|-----------|
+| `nil` / `:none` | No automatic compaction (default) |
+| `:context_window` | Compact when estimated token usage exceeds `compact_threshold` fraction of model's context window |
+| `Proc` | Called with the robot before each `run()`; application decides when and how to compact |
+
+`compact_threshold` defaults to `0.80` (80%). Requires the `classifier` gem when using the built-in `:context_window` strategy. Via `RunConfig`:
+
+```ruby
+config = RobotLab::RunConfig.new(auto_compact: :context_window, compact_threshold: 0.75)
+robot  = RobotLab.build(name: "analyst", system_prompt: "...", config: config)
+```
+
 ## 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:
@@ -693,6 +763,17 @@ reviewer.learn("This codebase prefers map/collect over manual array accumulation
 reviewer.run("Review snippet B")  # learning is injected automatically
 ```
 
+Pass `learn: true` in the constructor to enable automatic end-of-session learning promotion via the `robot_lab-durable` gem:
+
+```ruby
+reviewer = RobotLab.build(
+  name: "reviewer",
+  system_prompt: "You are a Ruby code reviewer.",
+  learn: true,
+  learn_domain: "ruby_review"
+)
+```
+
 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
@@ -796,101 +877,77 @@ 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:
+## Hook System
 
-**CPU-bound tools** — mark a tool `ractor_safe true` and RobotLab automatically routes its calls through a global `RactorWorkerPool` instead of running inline:
+RobotLab's hook system lets you intercept any point in a robot's execution pipeline without modifying framework code. Hooks use handler classes — subclasses of `RobotLab::Hook` that define lifecycle callbacks as class methods.
 
 ```ruby
-class TranscribeAudio < RubyLLM::Tool
-  ractor_safe true
-  description "Transcribe an audio file"
-  param :path, type: :string, desc: "Path to audio file"
+class TimerHook < RobotLab::Hook
+  # namespace is auto-derived: TimerHook → :timer_hook
+  # override with: self.namespace = :timer
 
-  def execute(path:)
-    AudioTranscriber.run(path)  # pure computation, no shared mutable state
+  def self.before_run(ctx)
+    ctx.local.start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
-end
-```
 
-**Parallel robot networks** — pass `parallel_mode: :ractor` when creating a network to dispatch independent robots across hardware threads simultaneously:
+  def self.after_run(ctx)
+    elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx.local.start) * 1000).round(1)
+    puts "[timer] #{ctx.robot.name} #{elapsed}ms"
+  end
 
-```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]
+  def self.on_error(ctx)
+    puts "[timer] #{ctx.robot.name} failed: #{ctx.error.message}"
+  end
 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
+Register at the global, network, or robot level — or for a single call:
 
-```bash
-rails generate robot_lab:install
-rails db:migrate
+```ruby
+RobotLab.on(TimerHook)              # every robot in this process
+network.on(TimerHook)               # robots inside this network only
+robot.on(TimerHook)                 # this robot only
+robot.run("msg", hooks: TimerHook)  # this call only
+robot.run("msg", hooks: [TimerHook, OtherHook])
 ```
 
-This creates:
-- `config/initializers/robot_lab.rb` - Configuration
-- `app/robots/` - Directory for your robots
-- Database tables for conversation history
-
-### Background Jobs
-
-RobotLab ships with `RobotLab::Job`, an `ActiveJob::Base` subclass that handles the full robot-run lifecycle: robot class resolution, Turbo Stream wiring, thread-record persistence, and completion/error broadcasting.
-
-**Generic job** (robot class supplied at enqueue time):
-
-```bash
-rails generate robot_lab:install   # creates app/jobs/robot_run_job.rb
-```
+Pass `context:` to set default `DotState` values for the handler's namespace before each callback fires:
 
 ```ruby
-# app/jobs/robot_run_job.rb  (generated)
-class RobotRunJob < RobotLab::Job
-  queue_as :default
-end
-
-# Enqueue from a controller:
-RobotRunJob.perform_later(
-  robot_class: "SupportRobot",
-  message:     params[:message],
-  thread_id:   session_id
-)
+RobotLab.on(TimerHook, context: { threshold_ms: 500 })
 ```
 
-**Dedicated job** (robot class bound at the class level via DSL):
-
-```bash
-rails generate robot_lab:job Support            # binds to SupportRobot, queue: default
-rails generate robot_lab:job Support --queue ai # custom queue
-```
+Around hooks receive a block and must call it — and return its value — so the actual work executes:
 
 ```ruby
-# app/jobs/support_job.rb  (generated)
-class SupportJob < RobotLab::Job
-  queue_as :default
-  robot_class SupportRobot
-end
+class PerfHook < RobotLab::Hook
+  self.namespace = :perf
 
-# Enqueue (no robot_class: needed):
-SupportJob.perform_later(message: params[:message], thread_id: session_id)
+  def self.around_run(ctx, &block)
+    t0     = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = block.call   # executes the run
+    ms     = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
+    $stderr.puts "[perf] #{ctx.robot.name} #{ms}ms"
+    result                # must return the result
+  end
+end
 ```
 
-When `thread_id` is provided and [turbo-rails](https://github.com/hotwired/turbo-rails) is installed, `RobotLab::Job` automatically:
+Because handler classes are Ruby constants (not Procs), all hook registrations are natively Ractor-serializable.
+
+See the [full Hook System guide](docs/guides/hooks.md) for all hook families, context objects, and extension patterns.
+
+## Extension Gems
 
-- Wires `on_content` / `on_tool_call` Turbo Stream callbacks so the UI updates in real time
-- Broadcasts a **completion** event to `"robot_lab_thread_#{thread_id}"` when the run finishes
-- Broadcasts an **error** event (HTML-escaped) if the job raises
+RobotLab's optional capabilities are packaged as separate gems:
 
-Omitting `thread_id` runs the robot in fire-and-forget mode — no persistence, no broadcasting.
+| Gem | Description |
+|-----|-------------|
+| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | CPU parallelism via Ruby Ractors — `ractor_safe` tools and DAG-scheduled parallel networks |
+| [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) | Rails Engine, generators, `RobotLab::Job` ActiveJob base with Turbo Stream broadcasting |
+| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | Cross-session knowledge persistence via YAML-backed durable store |
+| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | In-memory vector store with fastembed embeddings for semantic search / RAG |
+| [robot_lab-acp](https://github.com/MadBomber/robot_lab-acp) | Expose robots and networks as ACP (Agent Communication Protocol) HTTP+SSE services |
 
 ## Documentation