robot_lab 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d401853bc5fff2646793cfff4fbda7082b18b0e07b833b3f4de6545fca574125
-  data.tar.gz: f9964095406885bed329d8f2e7189cbb582e1c4665e3d53781b83371ee9016c7
+  metadata.gz: 36b770d963e004a951cdf35d07a2e867e4e661a9e342e8047184cfd9dafd6e15
+  data.tar.gz: f53bb5c52efcd6169bf36afc69306a9c03e9cfcabdaf5b0a94871802e2909f55
 SHA512:
-  metadata.gz: dd29d885c9ea4e0b91bffe49b757808213e8011302fac48b4632c37d0cc95315a559f80240fabca92c0a309fead3f1f72b1da3ac7eccdb440059451fc53c5a0e
-  data.tar.gz: 518c45909e25437da64e16ad69a5bfe5f361ddd602dc64c0ad475acde1c0b7946a0773fa36960a0baea3294ae7a7cef1835b6d08be2034e3a4a905fa74715eb2
+  metadata.gz: 850bde0e9ac1b7d65176bd067f42751d6d9db64517ca665d4765837fc5493e204f9b333cac08019cb451962d4d95789f986dee2ff08e55ae5e6a0d3d034f4f50
+  data.tar.gz: 97eb4dc66458a9a43f861e3f9c927eb6cfa63d33ddfff150b4181a45dc2c0db9570095f2e71d1182b76b4ee85e7086a6014b5536e805d9956f0860f9b4a03f50

data/README.md

@@ -1,7 +1,7 @@
 # RobotLab
 
-> [!INFO]
-> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section  of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
+> [!NOTE]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
 
 <br>
 <table>
@@ -21,7 +21,7 @@
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
-- <strong>Local LLM Providers</strong> - Ollama, GPUStack, LM Studio via provider passthrough<br>
+- <strong>Local LLM Providers</strong> - Ollama and GPUStack via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
@@ -30,6 +30,7 @@
 - <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>Doom Loop Detection</strong> - always-on detection of repeated or cyclic tool call patterns, tunable via <code>doom_loop_threshold:</code><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>
@@ -38,7 +39,7 @@
 </tr>
 </table>
 
-<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) snd explore the [many examples](examples/README.md) available as working demo applications.</p>
+<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) and explore the [many examples](examples/README.md) available as working demo applications.</p>
 
 ## Installation
 
@@ -81,7 +82,11 @@ puts result.last_text_content
 
 ### Local LLM Providers
 
-For local LLM providers (Ollama, GPUStack, LM Studio, etc.), use the `provider:` parameter:
+For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are the local ones (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The provider's API base must be configured first, or building the robot raises `RubyLLM::ConfigurationError`:
+
+```bash
+export ROBOT_LAB_RUBY_LLM__OLLAMA_API_BASE=http://localhost:11434/v1
+```
 
 ```ruby
 robot = RobotLab.build(
@@ -92,13 +97,15 @@ robot = RobotLab.build(
 )
 ```
 
+Specifying `provider:` also sets `assume_model_exists`, so the model name is not validated against a known-model list.
+
 ### Configuration
 
 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)
-3. XDG user config (`~/.config/robot_lab/config.yml`)
+3. XDG user config (`~/.config/robot_lab/robot_lab.yml` — note the filename repeats the app name)
 4. Project config (`./config/robot_lab.yml`)
 5. Environment variables (`ROBOT_LAB_*` prefix)
 
@@ -113,7 +120,6 @@ export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
 # Access configuration values
 RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
 RobotLab.config.ruby_llm.request_timeout  #=> 120
-RobotLab.config.streaming_enabled         #=> true
 ```
 
 Or create a project config file at `./config/robot_lab.yml`:
@@ -192,9 +198,10 @@ tools:
   - CodeSearchTool
 mcp:
   - name: github
-    transport: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-github"]
+    transport:
+      type: stdio
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-github"]
 model: claude-sonnet-4
 ---
 You are a GitHub assistant. Use available tools to help with repository tasks.
@@ -205,7 +212,10 @@ You are a GitHub assistant. Use available tools to help with repository tasks.
 robot = RobotLab.build(template: :github_assistant)
 ```
 
-Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys. Constructor-provided values always take precedence over front matter.
+
+> [!IMPORTANT]
+> Of the LLM config keys, only **`model`** and **`temperature`** currently take effect from front matter. `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, and `stop` are parsed but not applied — set those as constructor kwargs (or via `config:`), where they do work.
 
 ### Composable Skills
 
@@ -237,7 +247,7 @@ Skills are expanded depth-first and can reference other skills (with automatic c
 
 ### Combining Templates with System Prompts
 
-The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
+The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended, producing a single combined system message. The appended text also survives template re-rendering, so it persists across `run()` calls that supply runtime context. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
 
 ```ruby
 robot = RobotLab.build(
@@ -250,7 +260,7 @@ robot = RobotLab.build(
 
 ### Shared Configuration with RunConfig
 
-`RunConfig` lets you define operational defaults that flow through the hierarchy: Network -> Robot -> Template -> Task -> Runtime. Use it to share LLM settings across multiple robots or an entire network.
+`RunConfig` lets you define operational defaults. For a single robot they cascade from least- to most-specific: template front matter -> `config:` -> constructor kwargs. Front matter is the *base*, not an override — constructor kwargs always win.
 
 ```ruby
 # Create a shared config
@@ -267,7 +277,7 @@ robot = RobotLab.build(
   config: shared
 )
 
-# Apply to an entire network (all robots inherit these defaults)
+# Apply at the network level (see the note below on what actually propagates)
 network = RobotLab.create_network(name: "pipeline", config: shared) do
   task :analyzer, analyzer_robot, depends_on: :none
   task :writer, writer_robot, depends_on: [:analyzer]
@@ -282,6 +292,11 @@ robot = RobotLab.build(
 )
 ```
 
+> [!IMPORTANT]
+> A network-level `config:` propagates only `mcp` and `tools` down to its robots, and only when the robot opts in with `mcp: :inherit` / `tools: :inherit` — `:none` at any level resolves to an empty list. LLM fields (`model`, `temperature`, `max_tokens`, …) and callbacks (`on_content`) are read from each robot's own config at construction time, so they are **not** inherited from the network. To share LLM settings, pass the same `RunConfig` to each robot via `config:`.
+>
+> `max_concurrent_robots` is the one field the network itself consumes.
+
 RunConfig supports keyword construction, block DSL, and merge semantics:
 
 ```ruby
@@ -301,7 +316,7 @@ effective.model        #=> "claude-sonnet-4"
 
 ### Chaining Configuration
 
-Robots support method chaining to adjust configuration after creation:
+Robots support method chaining to adjust configuration after creation. The `with_*` methods are delegated dynamically from the underlying `RubyLLM::Chat`, so the available set is whatever that class defines — currently `with_context`, `with_headers`, `with_instructions`, `with_model`, `with_params`, `with_schema`, `with_temperature`, `with_thinking`, `with_tool`, and `with_tools`. Each returns the robot, so calls chain.
 
 ```ruby
 robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer.")
@@ -309,10 +324,18 @@ robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer
 result = robot
   .with_temperature(0.9)
   .with_model("claude-sonnet-4")
-  .with_max_tokens(2000)
   .run("Write a haiku about Ruby programming")
 ```
 
+There is no `with_max_tokens`. Set token limits in the constructor, or pass them through `with_params`:
+
+```ruby
+robot = RobotLab.build(name: "writer", system_prompt: "...", max_tokens: 2000)
+
+# or, after creation
+robot.with_params(max_tokens: 2000)
+```
+
 ## Graceful Tool Error Handling
 
 `RobotLab::Tool` automatically catches exceptions in `execute` and returns a plain-text error to the LLM instead of crashing the run. The LLM can then reason about the error and try an alternative approach.
@@ -368,9 +391,22 @@ robot = RobotLab.build(
   local_tools: [Magic8Ball]
 )
 
-result = robot.run("Should I start learning Rust?")
+# NOTE the `tools: :inherit` — see the warning below
+result = robot.run("Should I start learning Rust?", tools: :inherit)
 ```
 
+> [!WARNING]
+> `run()` defaults to `tools: :none` and `mcp: :none`, and `:none` means **send zero tools this turn**. Attaching tools with `local_tools:` (or servers with `mcp:`) is therefore not enough on its own — a plain `robot.run("...")` sends the LLM no tools at all and connects no MCP servers.
+>
+> Pass `tools: :inherit` / `mcp: :inherit` on each run to use what the robot has attached:
+>
+> ```ruby
+> robot.run("...", tools: :inherit)              # send attached tools
+> robot.run("...", mcp: :inherit, tools: :inherit)  # connect MCP + send its tools
+> ```
+>
+> `:inherit` means "no filter, use everything attached"; an explicit array acts as a name allowlist. Note that `tools: :inherit` at *build* time behaves differently — it resolves against the parent level, so keep `:inherit` on the `run()` call.
+
 ## Orchestrating Multiple Robots
 
 Networks use [SimpleFlow](https://github.com/MadBomber/simple_flow) pipelines with optional task activation for intelligent routing:
@@ -423,24 +459,29 @@ puts result.value.last_text_content
 
 ## Memory
 
-Both robots and networks have inherent memory that persists across runs:
+Two independent mechanisms carry state across runs, and it is worth keeping them straight:
+
+- **Chat history** — each robot owns a persistent `RubyLLM::Chat`, so conversational context carries forward automatically with no work on your part.
+- **`RobotLab::Memory`** — an explicit key-value store you read and write yourself, shared across robots when they run inside a network.
 
 ```ruby
-# Standalone robot with inherent memory
 robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
 
 robot.run("My name is Alice")
-robot.run("What's my name?")  # Memory persists automatically
+robot.run("What's my name?")  # answered from the persistent chat history
 
-# Access robot's memory
+# Access robot's memory (the explicit key-value store)
 robot.memory[:user_id] = 123
 robot.memory.data[:category] = "billing"
 
 # Runtime memory injection
 robot.run("Help me", memory: { session_id: "abc123", tier: "premium" })
 
-# Reset memory when needed
+# Reset the key-value store (does NOT clear chat history)
 robot.reset_memory
+
+# Clear chat history instead, keeping the system prompt
+robot.clear_messages
 ```
 
 Networks pass context through SimpleFlow::Result:
@@ -467,6 +508,8 @@ billing_result = result.context[:billing]
 puts result.value.last_text_content
 ```
 
+Results are keyed in `result.context` by the **robot's** `name`, not by the task name given to `task`. Keep the two identical unless you have a reason not to.
+
 ## MCP Integration
 
 Connect to external tool servers via Model Context Protocol:
@@ -490,17 +533,18 @@ robot = RobotLab.build(
   mcp: [filesystem_server]
 )
 
-# Optionally connect eagerly (default is lazy on first run)
+# Connect. Do this explicitly — run() defaults to mcp: :none, so a plain
+# run() never connects the servers configured above.
 robot.connect_mcp!
 
 # Check connection status
 puts "Failed: #{robot.failed_mcp_server_names}" if robot.failed_mcp_server_names.any?
 
-# Robot can now use filesystem tools
-result = robot.run("List the files in the current directory")
+# Robot can now use filesystem tools — :inherit is required on the run
+result = robot.run("List the files in the current directory", mcp: :inherit, tools: :inherit)
 ```
 
-MCP connections are resilient: failed servers are automatically retried on subsequent `run()` calls, and one failing server does not prevent others from connecting.
+MCP connections are resilient: failed servers are automatically retried on subsequent `run(mcp: :inherit)` calls, and one failing server does not prevent others from connecting. Connection failures are logged and recorded in `failed_mcp_server_names` rather than raised, so a robot whose servers all failed still builds and runs — just without those tools.
 
 ## Message Bus
 
@@ -634,7 +678,7 @@ robot = RobotLab.build(
 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.
+The `on_content:` callback is a `RunConfig` field, so it can also be supplied through a robot's `config:` instead of as a constructor kwarg. It is read from the robot's own config at construction time — a network-level `config:` does not supply it.
 
 ## Token & Cost Tracking
 
@@ -675,7 +719,8 @@ robot = RobotLab.build(
 begin
   robot.run("Run all steps.")
 rescue RobotLab::ToolLoopError => e
-  puts e.message  # "Tool call limit of 10 exceeded"
+  puts e.message
+  # "Circuit breaker triggered: 11 tool calls exceeded max_tool_rounds (10)"
 end
 ```
 
@@ -688,14 +733,16 @@ 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:
+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.
+
+Unlike the circuit breaker, doom loop detection is **always active** — it is installed on every run. `doom_loop_threshold:` tunes the sensitivity; it does not switch the feature on. The default threshold is `3`.
 
 ```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
+  doom_loop_threshold: 5   # tolerate more repetition before warning (default: 3)
 )
 ```
 
@@ -710,27 +757,33 @@ robot  = RobotLab.build(name: "runner", system_prompt: "...", config: config)
 
 `auto_compact` triggers context window compression automatically before each `run()`, preventing context overflow without manual intervention.
 
+`auto_compact` and `compact_threshold` are `RunConfig` fields, not constructor keywords — pass them via `config:`:
+
 ```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
+  config: RobotLab::RunConfig.new(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
+  config: RobotLab::RunConfig.new(
+    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 }
+  config: RobotLab::RunConfig.new(
+    auto_compact: ->(r) { r.compress_history(recent_turns: 5) if r.chat.messages.size > 40 }
+  )
 )
 ```
 
@@ -740,12 +793,7 @@ robot = RobotLab.build(
 | `: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)
-```
+`compact_threshold` defaults to `0.80` (80%). The built-in `:context_window` strategy uses the optional `classifier` gem; if it is missing, compaction is skipped with a logged warning rather than raising.
 
 ## Learning Accumulation
 
@@ -763,18 +811,9 @@ 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"
-)
-```
+Cross-session learning promotion is provided by the [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) gem, which hooks the `:learn` lifecycle family. See that gem's documentation for setup.
 
-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.
+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` for the lifetime of that robot.
 
 ```ruby
 reviewer.learnings          # => ["This codebase prefers map/collect..."]
@@ -783,7 +822,9 @@ 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.
+`robot.compress_history` prunes old conversation turns using term-frequency cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+
+Scoring uses raw term frequencies without IDF weighting — on a topic-focused conversation, IDF would suppress exactly the recurring terms that signal relevance.
 
 ```ruby
 # Basic compression: protect the 3 most recent turns, drop unrelated old turns
@@ -811,7 +852,7 @@ 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.
+`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using term-frequency cosine similarity (no IDF — on a two-document comparison, IDF collapses the shared terms to zero). Use it to skip an expensive reconciler LLM call when verifiers already agree.
 
 ```ruby
 # Check similarity directly
@@ -826,18 +867,30 @@ RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
 RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
 ```
 
-A common pattern is wiring convergence into a network router to skip reconciliation:
+`similarity` returns `0.0` if either text is blank or shorter than 30 characters (`Convergence::MIN_TEXT_LENGTH`), since term-frequency scoring is not meaningful on very short strings. Short replies like `"yes"` will therefore never register as converged.
+
+A common pattern is a gate robot that decides whether reconciliation is needed. Routing is done by overriding `call` and activating an `depends_on: :optional` task — networks have no separate router parameter:
 
 ```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"]
+class ConvergenceGate < RobotLab::Robot
+  def call(result)
+    a = result.context[:verifier_a]&.reply.to_s
+    b = result.context[:verifier_b]&.reply.to_s
+
+    # Converged? Pass the result straight through and leave :reconciler dormant.
+    RobotLab::Convergence.detected?(a, b) ? result : result.activate(:reconciler)
+  end
 end
 
-network = RobotLab.create_network(name: "verify", router: router) do
-  # ...
+network = RobotLab.create_network(name: "verify") do
+  task :verifier_a, verifier_a, depends_on: :none
+  task :verifier_b, verifier_b, depends_on: :none
+  task :gate,       ConvergenceGate.new(name: "gate"), depends_on: [:verifier_a, :verifier_b]
+  task :reconciler, reconciler,  depends_on: :optional
 end
+
+result = network.run(message: "Audit this change")
+result.context.key?(:reconciler)  # => false when the verifiers agreed
 ```
 
 Requires the `classifier` gem (`~> 2.3`).
@@ -943,11 +996,18 @@ RobotLab's optional capabilities are packaged as separate gems:
 
 | 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-a2a](https://github.com/MadBomber/robot_lab-a2a) | Expose robots and networks as Agent2Agent (A2A) protocol services 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 local networks |
+| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | Embedding-based semantic document store for search / RAG |
+| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | HTM-backed long-term memory and cross-session knowledge persistence |
+| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | Ractor-based parallel tool execution 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 |
+| [robot_lab-to](https://github.com/MadBomber/robot_lab-to) | Autonomous overnight agent loop — iterate a robot toward an objective |
+| [robot_lab-web](https://github.com/MadBomber/robot_lab-web) | Browser console — stream a robot's run over Server-Sent Events |
+
+> [!NOTE]
+> `robot_lab-acp` is retired; its functionality is superseded by `robot_lab-a2a`.
 
 ## Documentation
 

data/docs/api/core/index.md

@@ -10,16 +10,28 @@ classDiagram
         +name: String
         +description: String
         +model: String
-        +template: String
-        +tools: Array~Tool~
-        +run(message) Message
+        +template: Symbol
+        +local_tools: Array~Tool~
+        +mcp_tools: Array~Tool~
+        +tools_config: Symbol_or_Array
+        +run(message) RobotResult
+    }
+
+    class RobotResult {
+        +robot_name: String
+        +reply: String
+        +output: Array~TextMessage~
+        +input_tokens: Integer
+        +output_tokens: Integer
+        +export() Hash
     }
 
     class Network {
         +name: String
         +robots: Hash
         +config: RunConfig
-        +run(message)
+        +memory: Memory
+        +run(message) SimpleFlow_Result
     }
 
     class RunConfig {
@@ -32,8 +44,9 @@ classDiagram
     class Tool {
         +name: String
         +description: String
-        +parameters: Hash
-        +handler: Proc
+        +robot: Robot
+        +mcp: String
+        +call(args)
     }
 
     class Memory {
@@ -60,22 +73,28 @@ classDiagram
     Robot --> RunConfig : uses
     Robot --> Tool : has
     Robot --> Memory : uses
+    Robot ..> RobotResult : returns
     Network --> Memory : uses
     Robot ..> RobotMessage : sends/receives
+    Memory --> StateProxy : data
 ```
 
 ## Classes
 
 | Class | Purpose |
 |-------|---------|
-| [Robot](robot.md) | LLM agent with personality, tools, and model configuration |
-| [Network](network.md) | Container for robots with routing and orchestration |
-| RunConfig | Shared configuration for LLM, tools, callbacks, and infrastructure |
-| [Tool](tool.md) | Callable function with parameters and handler |
+| [Robot](robot.md) | LLM agent with templates, tools, memory, and model configuration |
+| [RobotResult](result.md) | Value object returned by `Robot#run` |
+| [Network](network.md) | Container for robots with DAG orchestration |
+| [RunConfig](robot.md#runconfig) | Shared configuration for LLM, tools, callbacks, and infrastructure |
+| [Tool](tool.md) | Callable function with parameters and an `execute` method |
 | [AskUser](tool.md#built-in-askuser) | Built-in tool for terminal-based user interaction |
 | [Memory](memory.md) | Reactive key-value store for sharing data |
+| [StateProxy](state.md) | Hash/method-access wrapper returned by `memory.data` |
 | RobotMessage | Typed envelope for bus-based inter-robot communication |
-| `RobotLab::Runnable` | Shared interface (`crew`, `chief`, `run`) implemented by both `Robot` and `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) |
+| `RobotLab::Runnable` | Shared interface (`crew`, `chief`, `robot_count`, `network?`, `single?`) implemented by both `Robot` and `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) |
+
+There is no `RobotLab::State` class and no `RobotLab::NetworkRun` class.
 
 ## Quick Examples
 
@@ -89,18 +108,25 @@ robot = RobotLab.build(
   local_tools: [greet_tool]
 )
 
-result = robot.run("Hello!")
+result = robot.run("Hello!")              # no tools sent — run() defaults to tools: :none
+result = robot.run("Hello!", tools: :inherit)  # sends greet_tool
+result.reply                              # => String
 ```
 
+`Robot#run` returns a [`RobotLab::RobotResult`](result.md), not a `Message`.
+
 ### Network
 
+The builder DSL method is `task` (there is no `step`):
+
 ```ruby
 network = RobotLab.create_network(name: "my_network") do
-  step :analyzer, analyzer_robot, depends_on: :none
-  step :writer, writer_robot, depends_on: [:analyzer]
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyzer]
 end
 
-result = network.run(message: "Process this")
+result = network.run(message: "Process this")  # => SimpleFlow::Result
+result.value                                   # => RobotResult of the last task
 ```
 
 ### Memory