Merge pull request #13 from MadBomber/develop

feat(phase-3): structured delegation and memory notification coalescing

Author: MadBomber

README.md

@@ -31,7 +31,8 @@
 - <strong>Tool Loop Circuit Breaker</strong> - <code>max_tool_rounds:</code> guards against runaway tool call loops<br>
 - <strong>Learning Accumulation</strong> - <code>robot.learn()</code> builds up cross-run observations with deduplication<br>
 - <strong>Context Window Compression</strong> - <code>robot.compress_history()</code> prunes irrelevant old turns via TF cosine scoring<br>
-- <strong>Convergence Detection</strong> - <code>RobotLab::Convergence</code> detects when independent agents agree, enabling reconciler fast-path
+- <strong>Convergence Detection</strong> - <code>RobotLab::Convergence</code> detects when independent agents agree, enabling reconciler fast-path<br>
+- <strong>Structured Delegation</strong> - <code>robot.delegate(to:, task:)</code> sync or async inter-robot calls with duration and token metadata; async fan-out via <code>DelegationFuture</code>
 </td>
 </tr>
 </table>

docs/guides/observability.md

@@ -7,6 +7,7 @@ Facilities that help you monitor, control, improve, and scale robot behaviour:
 - **Learning Accumulation** — build up cross-run observations that guide future runs
 - **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
 
 ---
 
@@ -392,6 +393,88 @@ gem "classifier", "~> 2.3"
 
 ---
 
+---
+
+## Structured Delegation
+
+### The Problem
+
+RobotLab has two existing patterns for one robot to involve another:
+
+- **Pipelines** — predefined sequences where robots share memory and run in order
+- **Bus messaging** — fire-and-forget pub/sub with no return value
+
+Neither gives you a synchronous call that returns a result with provenance and cost metadata. `delegate` fills that gap.
+
+### Synchronous delegation
+
+Blocks until the delegatee finishes and returns a `RobotResult` annotated with provenance and timing:
+
+```ruby
+result = manager.delegate(to: specialist, task: "Analyze this data: ...")
+
+puts result.reply          # specialist's answer
+puts result.robot_name     # => "specialist"   (who did the work)
+puts result.delegated_by   # => "manager"      (who asked)
+puts result.duration       # => 1.43           (wall-clock seconds)
+puts result.input_tokens   # => 812
+puts result.output_tokens  # => 94
+```
+
+All keyword arguments are forwarded to the delegatee's `run()`:
+
+```ruby
+result = manager.delegate(to: worker, task: "hello", company_name: "Acme")
+```
+
+### Asynchronous delegation — parallel fan-out
+
+Pass `async: true` to get a `DelegationFuture` back immediately. The delegatee runs in a background thread. Call `future.value` to block for the result, or `future.resolved?` to poll without blocking.
+
+```ruby
+# Fire both delegations simultaneously
+f1 = manager.delegate(to: summarizer, task: "Summarize: #{doc}", async: true)
+f2 = manager.delegate(to: analyst,    task: "Key metric: #{doc}", async: true)
+
+# Both are running in parallel here
+puts f1.resolved?   # false (probably)
+
+# Collect when ready (optional timeout in seconds)
+summary  = f1.value(timeout: 30)
+analysis = f2.value(timeout: 30)
+```
+
+If the delegatee raises an error, `future.value` re-raises it. If `timeout:` expires before the result arrives, `DelegationFuture::DelegationTimeout` is raised.
+
+### When to Use Each Pattern
+
+| Pattern | Return value | Concurrent | Use when |
+|---|---|---|---|
+| `pipeline` | shared memory | yes (parallel groups) | fixed workflow graph |
+| `bus` messaging | none (fire-and-forget) | yes | notify without waiting for a reply |
+| `delegate` | `RobotResult` with metadata | no | need the result back, one at a time |
+| `delegate(async: true)` | `DelegationFuture` | yes | parallel fan-out, collect results later |
+
+### Full Example
+
+```ruby
+manager    = RobotLab.build(name: "manager",    system_prompt: "You are a project manager.")
+summarizer = RobotLab.build(name: "summarizer", system_prompt: "Summarize in 1-2 sentences.")
+analyst    = RobotLab.build(name: "analyst",    system_prompt: "Identify the key metric.")
+
+# Parallel fan-out
+f1 = manager.delegate(to: summarizer, task: "Summarize: #{document}", async: true)
+f2 = manager.delegate(to: analyst,    task: "Key metric: #{document}", async: true)
+
+summary  = f1.value(timeout: 60)
+analysis = f2.value(timeout: 60)
+
+puts "#{summary.robot_name} (#{summary.duration.round(2)}s): #{summary.reply}"
+puts "#{analysis.robot_name} (#{analysis.duration.round(2)}s): #{analysis.reply}"
+```
+
+---
+
 ## See Also
 
 - [Robot API](../api/core/robot.md#token--cost-tracking)
@@ -400,3 +483,4 @@ gem "classifier", "~> 2.3"
 - [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)

examples/24_structured_delegation.rb

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 24: Structured Delegation
+#
+# Demonstrates robot.delegate(to:, task:) for structured inter-robot calls,
+# in both synchronous (blocking) and asynchronous (parallel fan-out) modes.
+#
+# Demonstrates:
+#   - robot.delegate(to:, task:)              — sync: blocks, returns RobotResult
+#   - robot.delegate(to:, task:, async: true) — async: returns DelegationFuture
+#   - future.value / future.value(timeout: N) — block until result ready
+#   - future.resolved?                        — non-blocking poll
+#   - result.delegated_by — which robot delegated
+#   - result.robot_name   — which robot did the work
+#   - result.duration     — wall-clock seconds for the delegated call
+#   - result.input_tokens / result.output_tokens — delegatee's token usage
+#   - Contrast with bus messaging (fire-and-forget) and pipelines (predefined)
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/24_structured_delegation.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+puts "=" * 60
+puts "Example 24: Structured Delegation"
+puts "=" * 60
+puts
+
+# ---------------------------------------------------------------------------
+# Build a manager and two specialist robots
+# ---------------------------------------------------------------------------
+manager = RobotLab.build(
+  name:          "manager",
+  system_prompt: "You are a project manager. Delegate tasks concisely."
+)
+
+summarizer = RobotLab.build(
+  name:          "summarizer",
+  system_prompt: "You are a concise summarizer. Produce a 1-2 sentence summary."
+)
+
+analyst = RobotLab.build(
+  name:          "analyst",
+  system_prompt: "You are a data analyst. Identify the key metric in one sentence."
+)
+
+# ---------------------------------------------------------------------------
+# Manager delegates to each specialist in turn
+# ---------------------------------------------------------------------------
+document = <<~TEXT
+  Q4 revenue came in at $4.2M, up 18% year-over-year. Customer acquisition
+  cost dropped to $120, the lowest in three years. Churn held steady at 2.1%.
+  Net promoter score improved from 42 to 58. The mobile app drove 34% of new
+  sign-ups, compared to 19% in Q3.
+TEXT
+
+puts "Document:"
+puts document
+puts "-" * 60
+
+# ---------------------------------------------------------------------------
+# Synchronous delegation — sequential, blocks until each result arrives
+# ---------------------------------------------------------------------------
+puts "── Synchronous (sequential) ──────────────────────────────"
+puts
+
+puts "Delegating to summarizer (blocking)..."
+summary_result = manager.delegate(to: summarizer, task: "Summarize this report:\n\n#{document}")
+
+puts "Summary (from #{summary_result.robot_name}, delegated by #{summary_result.delegated_by}):"
+puts "  #{summary_result.reply}"
+puts "  Duration: #{"%.2f" % summary_result.duration}s | " \
+     "Tokens: #{summary_result.input_tokens} in / #{summary_result.output_tokens} out"
+puts
+
+puts "Delegating to analyst (blocking)..."
+analysis_result = manager.delegate(to: analyst, task: "What is the single most important metric here?\n\n#{document}")
+
+puts "Analysis (from #{analysis_result.robot_name}, delegated by #{analysis_result.delegated_by}):"
+puts "  #{analysis_result.reply}"
+puts "  Duration: #{"%.2f" % analysis_result.duration}s | " \
+     "Tokens: #{analysis_result.input_tokens} in / #{analysis_result.output_tokens} out"
+puts
+
+# ---------------------------------------------------------------------------
+# Asynchronous delegation — parallel fan-out, results collected later
+# ---------------------------------------------------------------------------
+puts "── Asynchronous (parallel fan-out) ───────────────────────"
+puts
+
+# Fresh robots — each delegate call should start from a clean slate
+async_summarizer = RobotLab.build(
+  name:          "summarizer",
+  system_prompt: "You are a concise summarizer. Produce a 1-2 sentence summary."
+)
+async_analyst = RobotLab.build(
+  name:          "analyst",
+  system_prompt: "You are a data analyst. Identify the key metric in one sentence."
+)
+
+puts "Firing both delegations in parallel..."
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+f_summary  = manager.delegate(to: async_summarizer, task: "Summarize this report:\n\n#{document}",                     async: true)
+f_analysis = manager.delegate(to: async_analyst,    task: "What is the single most important metric?\n\n#{document}", async: true)
+
+puts "Both futures launched. Futures resolved? " \
+     "summary=#{f_summary.resolved?} analysis=#{f_analysis.resolved?}"
+puts "Collecting results..."
+
+summary  = f_summary.value(timeout: 60)
+analysis = f_analysis.value(timeout: 60)
+
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+puts
+puts "Summary  (#{summary.robot_name}):  #{summary.reply}"
+puts "Analysis (#{analysis.robot_name}): #{analysis.reply}"
+puts
+puts "Total wall time with parallelism: #{"%.2f" % elapsed}s " \
+     "(vs ~#{"%.2f" % (summary.duration + analysis.duration)}s sequential)"
+puts
+
+# ---------------------------------------------------------------------------
+# Contrast with the alternatives
+# ---------------------------------------------------------------------------
+puts "=" * 60
+puts "When to use delegate vs. the alternatives"
+puts "=" * 60
+puts <<~TEXT
+
+  bus messaging       — fire-and-forget; no return value; async
+                        use when: you want to notify without waiting
+
+  pipeline            — predefined sequence; robots share memory
+                        use when: you have a fixed workflow graph
+
+  delegate()          — synchronous; blocks; returns RobotResult with metadata
+                        use when: one robot needs the result of another's work
+
+  delegate(async:true) — returns DelegationFuture immediately
+                         use when: you want to run multiple delegates in
+                         parallel and collect results when ready
+
+TEXT
+
+puts "Done."

examples/README.md

@@ -50,6 +50,7 @@ examples/
   21_learning_loop.rb         # Learning accumulation across runs with robot.learn
   22_context_compression.rb   # Context window compression with HistoryCompressor
   23_convergence.rb           # Debate convergence detection and reconciler fast-path
+  24_structured_delegation.rb # Structured delegation with duration and token tracking
   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
@@ -190,6 +191,12 @@ Demonstrates `robot.compress_history()` for reducing token usage in long convers
 
 **Requires:** `gem 'classifier', '~> 2.3'` in your Gemfile (no LLM calls in the demo itself)
 
+### 24 — Structured Delegation
+
+A manager robot delegates sub-tasks to a summarizer and an analyst. Each `delegate()` call returns a `RobotResult` annotated with `delegated_by`, `duration`, and token counts. Includes a comparison table of when to use delegation vs. bus messaging vs. pipelines.
+
+**Requires:** LLM API key
+
 ### 23 — Debate Convergence Detection
 
 Demonstrates `RobotLab::Convergence` for detecting when two independent agents have reached the same conclusion. Scores pairs of texts from identical → semantically similar → partially related → unrelated, showing how the similarity metric varies. Includes the router fast-path pattern: when two verifier robots agree above a threshold, the expensive reconciler LLM call is skipped entirely.

lib/robot_lab/delegation_future.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # A promise-like object returned by robot.delegate(async: true).
+  #
+  # The delegated task runs in a background thread. The caller can check
+  # whether the result is ready with +resolved?+ and block until it arrives
+  # with +value+ (or its alias +wait+).
+  #
+  # @example Fan-out to two specialists in parallel
+  #   f1 = manager.delegate(to: summarizer, task: "summarize ...", async: true)
+  #   f2 = manager.delegate(to: analyst,    task: "analyze ...",   async: true)
+  #
+  #   # Other work here while both run in parallel
+  #
+  #   summary  = f1.value           # blocks if not yet done
+  #   analysis = f2.value
+  #
+  # @example With a timeout
+  #   result = future.value(timeout: 10)   # raises DelegationTimeout if too slow
+  #
+  class DelegationFuture
+    # Raised when +value(timeout: N)+ expires before the result arrives.
+    class DelegationTimeout < Error; end
+
+    # @return [String] name of the robot that was delegated to
+    attr_reader :robot_name
+
+    # @return [String] name of the robot that created this future
+    attr_reader :delegated_by
+
+    # @param robot_name [String]
+    # @param delegated_by [String]
+    def initialize(robot_name:, delegated_by:)
+      @robot_name   = robot_name
+      @delegated_by = delegated_by
+      @mutex        = Mutex.new
+      @cv           = ConditionVariable.new
+      @result       = nil
+      @error        = nil
+      @resolved     = false
+    end
+
+    # True once the delegated task has completed (successfully or with an error).
+    #
+    # @return [Boolean]
+    def resolved?
+      @mutex.synchronize { @resolved }
+    end
+
+    # Block until the result is available and return it.
+    #
+    # @param timeout [Numeric, nil] maximum seconds to wait; nil means wait forever
+    # @return [RobotResult]
+    # @raise [DelegationTimeout] if +timeout+ is given and expires
+    # @raise [StandardError] re-raises any error thrown by the delegated task
+    def value(timeout: nil)
+      @mutex.synchronize do
+        unless @resolved
+          @cv.wait(@mutex, timeout)
+        end
+
+        unless @resolved
+          raise DelegationTimeout,
+                "Delegation to '#{@robot_name}' timed out after #{timeout}s"
+        end
+
+        raise @error if @error
+
+        @result
+      end
+    end
+    alias_method :wait, :value
+
+    # @api private — called by Robot#delegate from the worker thread
+    def resolve!(result)
+      @mutex.synchronize do
+        @result   = result
+        @resolved = true
+        @cv.broadcast
+      end
+    end
+
+    # @api private — called by Robot#delegate from the worker thread on error
+    def reject!(error)
+      @mutex.synchronize do
+        @error    = error
+        @resolved = true
+        @cv.broadcast
+      end
+    end
+  end
+end