robot_lab-cyborg 0.2.7

data/docs/how_it_works.md

@@ -0,0 +1,211 @@
+# How It Works
+
+## The Means and the Process: Channel and Interviewer
+
+Reaching the human is deliberately split into two small, separately-testable concerns:
+
+- **`Channel`** is the *means* — a dumb, bidirectional pipe. It knows how to `deliver` a message **out** to the human and how to `receive` a message the human sends **in**. It has no concept of a "question" or an "answer" — just messages crossing a boundary.
+- **`Interviewer`** is the *process* — it conducts the interaction over whatever channel is injected. It tracks which questions are outstanding, decides which inbound message answers which question, and surfaces everything else as unsolicited human *initiative*.
+
+This split is why `$stdin`/`$stdout` live **only** inside `Channel::Terminal` — nothing else in the gem assumes a terminal. Swapping in a Slack, email, or web-form channel changes nothing about how `Interviewer`, `Cyborg`, or `Conversation` work. See [Building Custom Channels](custom_channels.md) to write one.
+
+### `ChannelMessage`
+
+The one data shape that crosses the boundary in both directions:
+
+```ruby
+ChannelMessage = Data.define(:id, :content, :in_reply_to, :sender, :kind, :at)
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | the question id this message carries (outbound) or answers (inbound, when the channel can correlate) |
+| `content` | the human-readable text |
+| `in_reply_to` | set by the channel when it can tie an inbound answer to a specific question (a Slack thread, an email `In-Reply-To`) |
+| `sender` | who the message is from/for, for display |
+| `kind` | `:question` \| `:answer` \| `:message` \| `:notice` |
+| `at` | `Time.now` unless given |
+
+`kind == :question` (checked via the `question?` predicate) is what tells `Channel::Terminal` to print a `> ` prompt after the line; other kinds (inbound peer messages, notices) print without one, so unsolicited traffic doesn't spam the input cursor.
+
+### Built-in Channels
+
+**`Channel::Terminal`** — the human at a keyboard, and the default when no `channel:` is given.
+
+- `input:`/`output:` are injectable (default `$stdin`/`$stdout`); inject `StringIO` in tests.
+- `deliver` is synchronized with a `Mutex` so a question and an inbound peer message never interleave on screen.
+- `receive(timeout:)` uses `IO.wait_readable` on a real IO so timeouts, shutdown, and question expiry all work; a non-selectable stream (a `StringIO` in tests) returns immediately from `#gets`, which is equally responsive.
+- A `nil` line from `#gets` (EOF) is treated as "nothing arrived" and propagates as `nil`.
+- `correlates?` is `false` — a bare terminal carries no correlation, so `in_reply_to` always stays `nil` on what it produces.
+
+**`Channel::Scripted`** — canned answers for tests, automation, and replay.
+
+- Constructed with an array (or single value) of answers, consumed in order.
+- `correlates?` is `true` — each delivered question is paired with the *next* scripted answer **at delivery time** and stamped with that question's id, so correlation is exact and deterministic.
+- Every question shown is recorded in `#asked`, so tests can assert on what the human saw: `cyborg.channel.asked`.
+- When the script runs dry, a delivered question simply goes unanswered — modeling a human who never replies — and the `Interviewer`'s timeout (if any) takes over. Supply enough answers, or an `ask_timeout`, for any code path that asks more questions than you scripted.
+
+## Asking Asynchronously
+
+Asking is **always** asynchronous, whatever the channel — a human's answer may be the very next message, may arrive several messages later (after they say other things first), or may never come at all. So `Interviewer#ask` never blocks: it delivers the question and returns a `Question`, a one-shot future, immediately.
+
+```ruby
+question = interviewer.ask("Deploy now?")   # returns instantly
+# ... do other things ...
+answer = question.answer(timeout: 30)       # blocks here, not before
+```
+
+`Interviewer#ask_and_wait` (and `Cyborg#ask`) combine both steps into one call for the common synchronous case — this is the boundary a pipeline step or a bus task handler actually needs: block *this* thread, but don't block the channel's consumer thread.
+
+`Cyborg#ask_async` exposes the non-blocking primitive directly, returning the pending `Question` so the caller decides when (and whether) to wait — the primitive a durable/suspendable human step would need to persist (see [Roadmap: Durable Human Steps](#roadmap-durable-human-steps)).
+
+### The Background Consumer
+
+`Interviewer` lazily starts a single background thread (`ensure_consumer`) the first time a question is outstanding, or when `#listen` is called. It polls `channel.receive(timeout: 0.05)` in a loop and, for each inbound message, either resolves the question it answers or calls the `on_initiative` handler.
+
+The consumer is deliberately hard to kill:
+
+- **A handler or channel error never wedges it.** Any `StandardError` raised while dispatching a message (in a channel read, in `on_initiative`, in interpreting an answer) is caught, recorded in `Interviewer#last_error`, and the loop keeps running. Before this, a throwing handler used to kill the consumer thread and hang every future `ask` — this was fixed as part of a design review (see `CHANGELOG.md`, item *A1*).
+- **It stops itself once idle**, unless `#listen` has been called: no questions outstanding and not in always-on mode → the loop exits and `@running` resets, so the next `#ask` (or `#listen`) restarts it cleanly. Both the start and stop paths flip `@running` under the same mutex, so a restart can never race a shutdown.
+- **`#close`** stops it for good and closes the channel — call this when a `Cyborg`/`Interviewer` is done and its channel resources (a socket, a file handle) need releasing.
+
+### Correlation vs. Serialization
+
+Whether more than one question can be outstanding at once depends entirely on the channel:
+
+- A channel that **can** tie an inbound answer back to its question (`correlates? == true` — Slack threads, email `In-Reply-To`, `Channel::Scripted`) lets any number of questions be outstanding concurrently. Each is delivered immediately; `Interviewer#dispatch` resolves whichever one an inbound message's `in_reply_to` names.
+- A channel that **cannot** (`correlates? == false` — a bare terminal) gets **serialized**: only one question is ever "on the wire" at a time (`@active_id`). Additional `ask` calls queue in `@pending` and are delivered one at a time as the active question resolves or expires (`pump_pending`/`release_active`). An inbound message with no `in_reply_to` resolves whichever question is currently active. This makes mis-attribution — a fast second answer accidentally resolving the first question — impossible.
+
+An inbound message that names no outstanding question (an unknown/expired id, or an answer arriving when nothing is active) matches nothing and is routed to `on_initiative` instead — the human speaking as a peer, unprompted.
+
+### Interpreting an Answer
+
+Before resolving a `Question`, the `Interviewer` runs the raw text through `interpret`:
+
+- An empty answer falls back to the question's `default`, when one was given.
+- If the question had `choices:`, a bare number is mapped to the corresponding choice (1-indexed) — out-of-range numbers, and any non-numeric text, pass through unchanged as free text.
+- The result is always coerced to a `String`, so a genuine empty answer (`""`) is never confused with a timeout (`nil`).
+
+### Timeouts and Expiry
+
+`Question#answer(timeout:)` blocks on an internal `Thread::Queue` (the mailbox `Interviewer#dispatch` pushes into). If nothing arrives within `timeout`:
+
+1. The question calls back into `Interviewer#expire(self)`, which removes it from the outstanding set (so a later, unrelated answer can never claim it) and, on a serialized channel, advances the queue to the next pending question.
+2. `#answer` returns the question's `default` (`nil` if none was given).
+
+`nil` from `#answer` is therefore unambiguous: it means "no answer, no default" — never "the human answered with an empty string."
+
+## Cyborg: The Human Peer
+
+### Network Member and Bus Contracts
+
+`Cyborg` satisfies the same two contracts a `Robot` does, so a network (or another peer) never has to know which one it's talking to:
+
+- **The `SimpleFlow` step contract** — `#call(result)`. The network invokes this when a pipeline reaches the human's task; `Cyborg` extracts the incoming message and shared memory from the pipeline `Result` (`extract_run_context`), calls its own `#run`, and threads a `RobotResult` back into the pipeline the same way a robot's step would (`result.with_context(name, robot_result).continue(robot_result)`). Any exception is caught and turned into an error-shaped `RobotResult` rather than raising through the pipeline.
+- **The `#run` contract** — `run(message = nil, network_memory: nil, memory: nil, **)`. This is what makes a `Cyborg` a valid `delegate`/`spawn` target anywhere a `Robot` is: it asks the human the given message (via `#ask`) and wraps the answer in a `RobotResult`, so `result.reply` works identically regardless of which kind of peer produced it.
+
+`Cyborg` also **includes `RobotLab::Robot::BusMessaging` verbatim** — the same module `Robot` uses for `send_message`/`send_reply`/`on_message`/`spawn`/bus-poller wiring. This is why a robot and a human are wire-compatible peers on the same `TypedBus`: there is only one implementation of "how a member talks on the bus," shared by both.
+
+**Caveat:** `Cyborg#initialize` wires its own inbound handler — `@message_handler = method(:handle_incoming)` — to get its default human-in-the-loop behavior (surface the task, ask, auto-reply). `BusMessaging#on_message`, `#respond_to_tasks`, and `#serve` all *replace* `@message_handler` wholesale. Calling any of them on a `Cyborg` overwrites `handle_incoming` and disables the built-in ask/auto-reply flow — those three methods are meant for `Robot`s opting *into* task-serving behavior a `Cyborg` already has by default. If you need custom bus-message handling on a `Cyborg`, build it around `#on_task`/`#on_human` instead (see below), not `#on_message`.
+
+### The Inbound Task Lifecycle
+
+`handle_incoming(message)` — the private method wired as `@message_handler` — is what runs on the bus poller's drain thread for every message addressed to this peer:
+
+1. The message is recorded in `#inbox` (thread-safe, for later inspection).
+2. If it's a **reply** to something this peer sent earlier, it's shown to the human via the channel (`kind: :message`) and handling stops there — replies don't get re-asked as tasks.
+3. Otherwise it's a **fresh task**, handled by `respond_to_task`.
+
+`respond_to_task` never blocks the poller:
+
+- If the peer is `!available?` (offline), it declines immediately — a reply saying `"(name is unavailable)"` is sent back at once (if `auto_reply` and a bus are configured) rather than waiting on a human who won't answer.
+- Otherwise, it spawns a **new thread** that asks the human (`ask(task_prompt(message))`), sends the answer back as a reply once it arrives (again, if `auto_reply` and a bus are configured, and only if there is an answer), and invokes the `#on_task` callback with the original message and the answer. Any error in that thread is caught and logged with `warn`, not raised — a slow or crashing human-answer thread can never take down the bus poller.
+
+This is the fix for a real deadlock: before it, an inbound task ran synchronously on the poller thread, so a slow (or absent) human blocked delivery of every other message to every other peer sharing that poller group.
+
+### Duplex: Talking Back to the Human
+
+Two directions, both automatic in the common case:
+
+- **Network → human**: any inbound bus message or reply is shown on the channel via `deliver_to_human`, best-effort (a channel error here is swallowed — a broken display must never break message intake). Call `Cyborg#tell(text, kind: :notice)` yourself to push an unprompted line (a status update, a warning) the same way.
+- **Human → network**: an inbound channel message that answers no outstanding question is *initiative* — the human speaking unprompted. `Interviewer#on_initiative` routes it to `Cyborg#handle_human_initiative`, which in turn calls the `#on_human` callback you register. `Conversation` (below) is the built-in way to turn that initiative into addressed bus tasks; you can also register `#on_human` directly for custom routing.
+
+### Always-On Listening
+
+By default, the `Interviewer`'s consumer thread only runs while a question is outstanding — there's nothing to read otherwise. `Cyborg#listen` (and `Conversation#start`, which calls it) keeps the consumer alive with *no* question pending, so the human can address the network unprompted at any time; their input arrives via `#on_human`. `#unlisten` (and `Conversation#stop`) turn this back off; the consumer then winds down once nothing is outstanding, same as normal.
+
+### Presence and Availability
+
+```ruby
+cyborg.online!      # taking work now (default)
+cyborg.away!         # present but slow — still asked, use a generous timeout
+cyborg.offline!      # not taking work — inbound tasks declined immediately
+cyborg.available?    # => false only when :offline
+```
+
+Presence is plain in-memory state (`@presence`, guarded by a mutex) — it doesn't itself change *how* a question is asked, only what `respond_to_task` does with an inbound bus task before asking at all. A network or dispatcher can check `available?` before routing work to a specific human, to pick another peer or escalate instead of tasking someone who will just decline (or, if `:away`, take a long time).
+
+### Typed and Validated Answers
+
+```ruby
+cyborg.ask("Deploy?")                                    # raw text (or the default)
+cyborg.ask_int("How many replicas?")                      # re-asks until a parseable Integer
+cyborg.ask_confirm("Proceed?")                            # => true / false / nil
+cyborg.ask("Pick one", choices: %w[a b c])                # numbered choices; a bare digit maps to one
+cyborg.ask("Env?", validate: ->(a) { %w[dev prod].include?(a) ? a : nil }, retries: 2)
+```
+
+`#ask`'s `validate:` contract: return the (optionally coerced) value when the answer is acceptable, or `nil` to reject it. On rejection, `Cyborg` tells the human why (`"Sorry, I couldn't use ..."`) and re-asks, up to `retries` extra attempts, after which it falls back to `default`. `ask_int`/`ask_confirm` are just `ask` with a pre-built `validate:`.
+
+### Delegation
+
+```ruby
+result = cyborg.delegate(to: some_robot_or_cyborg, task: "Summarize this")     # blocks, returns RobotResult
+future = cyborg.delegate(to: some_robot_or_cyborg, task: "Summarize this", async: true)  # returns a DelegationFuture
+future.value            # blocks here instead; raises DelegationFuture::DelegationTimeout if value(timeout:) expires
+```
+
+`delegate` works against **any** target that responds to `#run` — a `Robot` or another `Cyborg` — because both satisfy the same `#run` contract. The synchronous form calls `to.run(task, **)` directly and stamps `delegated_by` on the result. The async form spawns a `Thread`, resolves or rejects a `RobotLab::DelegationFuture` from it, and returns the future immediately — so a human (or a robot) can fan a task out to several peers in parallel and collect results later.
+
+`assign(to:, task:)` is the fire-and-forget bus counterpart — an alias for `BusMessaging#send_message`, named for how a human hands off work; correlate its reply later via `cyborg.outbox[message.key]`.
+
+### Shared Memory
+
+```ruby
+cyborg.remember(:decision, "ship it")       # writes to the active memory
+cyborg.recall(:sentiment, wait: 30)         # reads from it, optionally blocking for up to 30s
+cyborg.attach_memory(some_network_memory)   # explicit target (a network run does this for you)
+cyborg.detach_memory                        # back to this peer's own standalone memory
+```
+
+"The active memory" is the network's shared memory while attached, and this peer's own standalone `memory:` otherwise (`current_memory`, mutex-guarded). `#run` calls `attach_memory` automatically whenever a `network_memory:` is passed in — which is how a network run wires it up without you doing so by hand. Detaching explicitly matters when a peer might otherwise keep writing to a finished network's memory after that run has ended.
+
+`remember`/`recall` additionally set/restore the memory's `current_writer` around the call (`with_writer`, a no-op for memory implementations that don't track one) — a no-op for memories that don't track a writer, and otherwise how downstream consumers know a given memory write came from this human rather than a robot.
+
+## Conversation: Multi-Peer Chat by @mention
+
+`Conversation` turns a listening `Cyborg` into an interactive participant among several named peers:
+
+```ruby
+you  = RobotLab::Cyborg.new(name: "you", bus: bus)
+chat = you.converse(peers: %w[analyst scribe])
+# human types: "hey @analyst and @scribe: status?"  -> both are tasked
+# human types: "status?"                             -> broadcasts to both (no mention = everyone)
+```
+
+`Cyborg#converse(peers:)` is sugar for `Conversation.new(cyborg: self, peers: peers).start`. `#start` registers an `#on_human` handler that routes each unprompted line and calls `#listen`; `#stop` calls `#unlisten`.
+
+Routing rules (`Conversation#route`):
+
+- Every `@name` mention in the line (via the `MENTION = /@(\w+)/` pattern, in order of first appearance, deduplicated) addresses that peer.
+- A line with **no** mention broadcasts to **every** known peer.
+- A line whose mentions are *all* unknown peers is **not sent** — `Conversation` tells the human which name(s) weren't recognized, and (if there were no other, valid mentions) which peers *are* known.
+- A line mixing known and unknown mentions still sends to the known ones, after reporting the unknown ones.
+
+Replies come back automatically — `Cyborg`'s duplex delivers inbound bus traffic to the channel regardless of how the outbound task was sent, so `Conversation` only has to handle the human → network direction; it never polls for or renders replies itself.
+
+`add_peer(name)` grows the addressable roster after construction (e.g. as new robots join a running session).
+
+## Roadmap: Durable Human Steps
+
+A human step currently holds a thread while it waits (`ask`/`ask_and_wait` block; the underlying `Question#answer` sits on a blocking `Thread::Queue#pop`). `ask_async` returns the pending `Question` without blocking — the primitive a durable integration would need to persist across a process restart. The intended path, per the gem's `CHANGELOG.md` and `README.md`, is to store a pending decision through **`robot_lab-durable`** (and `robot_lab-to`'s `DecisionManager`) so a human decision survives a restart without pinning a thread for the duration. Per-peer cryptographic identity/attribution (signed events), building on the existing per-message `sender`/`from`, is a complementary but separate direction. Neither is implemented in this gem as of this writing — treat this section as intent, not a shipped feature.

data/docs/index.md

@@ -0,0 +1,57 @@
+# robot_lab-cyborg
+
+A [RobotLab](https://github.com/MadBomber/robot_lab) extension gem that puts a **human** into the network as a peer worker.
+
+Robots on a RobotLab network are LLM-backed workers. A **`Cyborg`** is a *human*-backed worker that sits at exactly the same level as the robots: it registers as a network task, speaks on the same [TypedBus](https://github.com/MadBomber/typed_bus) channels, reads and writes the same shared memory, **receives tasking** (as a pipeline step and as bus messages), and **issues tasking** to the other members — humans and robots alike.
+
+```ruby
+require "robot_lab"
+require "robot_lab/cyborg"
+
+dewayne = RobotLab::Cyborg.new(name: "dewayne")
+
+network = RobotLab.create_network(name: "release") do
+  task :draft,   writer_robot, depends_on: :none
+  task :approve, dewayne,      depends_on: [:draft]   # the human signs off
+end
+
+network.run(message: "Draft the release notes")
+```
+
+A `Cyborg` reuses `RobotLab::Robot::BusMessaging` verbatim, so its bus behavior is byte-for-byte identical to a robot's. It deliberately does **not** subclass `Robot`: a human needs no LLM, no model, and no API key. The human *is* the "model," reached across an injectable **`Channel`** (the *means* — terminal today, Slack/email/web later) by an **`Interviewer`** (the *process* that conducts the asynchronous ask-and-answer).
+
+## Navigation
+
+- [Getting Started](getting_started.md) — installation, creating a Cyborg, pipeline steps, bus messaging, running the bundled examples
+- [How It Works](how_it_works.md) — the Channel/Interviewer split, correlation vs. serialization, the consumer thread, the duplex channel, presence, memory, the network-member contract, delegation
+- [API Reference](api_reference.md) — every public class and method, grouped by concern
+- [Building Custom Channels](custom_channels.md) — bridging a Cyborg to Slack, email, a web form, or any other transport
+
+## At a Glance
+
+| | |
+|---|---|
+| **Core class** | `RobotLab::Cyborg` — a human peer worker |
+| **Bus behavior** | Identical to `Robot`'s — reuses `RobotLab::Robot::BusMessaging` |
+| **Reaches the human via** | An injectable `Channel` (`Terminal` by default, `Scripted` for tests, or your own) |
+| **Conducts the interaction via** | `Interviewer` — async ask/answer, question correlation, serialization on dumb channels |
+| **Network roles** | Pipeline step (`task :name, cyborg`), bus peer (`assign`/`delegate`), shared-memory participant (`remember`/`recall`) |
+| **Presence** | `online!` / `away!` / `offline!` / `available?` |
+| **Multi-peer chat** | `Conversation` — `@mention` addressing, no-mention broadcast |
+| **Typed answers** | `ask`, `ask_int`, `ask_confirm`, `ask(validate:, retries:)` |
+| **Dependency** | `robot_lab ~> 0.2, >= 0.2.6` |
+
+## Why a Cyborg, Not Just a Human-Shaped Robot?
+
+A `Robot` is built around an LLM chat: model, provider, tokens, a `ruby_llm` chat object. None of that applies to a human. Rather than force a human through `Robot`'s LLM-shaped constructor and stub out everything that doesn't apply, `Cyborg` is a separate, smaller class that:
+
+- Includes only the one piece of `Robot` it genuinely needs and shares byte-for-byte — `BusMessaging` (send/receive over `TypedBus`, spawn, bus poller wiring).
+- Replaces "call the model" with "ask a human," via an injectable `Channel` + `Interviewer` pair instead of a `ruby_llm` chat.
+- Still satisfies the same *network member* contract (`call`/`run`) so it is a drop-in peer anywhere a `Robot` is expected — a pipeline `task`, a `delegate` target, a `spawn`-style bus peer.
+
+## Links
+
+- [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [RubyGems](https://rubygems.org/gems/robot_lab-cyborg)
+- [GitHub](https://github.com/MadBomber/robot_lab-cyborg)
+- [Changelog](https://github.com/MadBomber/robot_lab-cyborg/blob/main/CHANGELOG.md)

data/examples/01_human_in_the_network.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Human-in-the-network demo.
+#
+# A Cyborg is a human peer worker. It reaches its human across an injectable
+# Channel (the *means*: terminal now, Slack/email/web later). This example
+# injects a Scripted channel so it runs end-to-end without a live human — omit
+# `channel:` to get the default terminal channel and answer the prompts yourself.
+#
+#   ruby examples/01_human_in_the_network.rb
+
+# Prefer the local robot_lab checkout (with the latest fixes) over any installed gem.
+core_lib = File.expand_path("../../robot_lab/lib", __dir__)
+$LOAD_PATH.unshift(core_lib) if File.directory?(core_lib)
+
+require "robot_lab"
+require_relative "../lib/robot_lab/cyborg"
+
+Scripted = RobotLab::Cyborg::Channel::Scripted
+
+# --- 1. A human as a pipeline step ------------------------------------------
+# The human is interchangeable with a robot: it registers as a network task and
+# its answer flows downstream like any RobotResult.
+
+approver = RobotLab::Cyborg.new(name: "approver", channel: Scripted.new(["approved: ship it"]))
+
+network = RobotLab.create_network(name: "release") do
+  task :approve, approver, depends_on: :none
+end
+
+result = network.run(message: "Approve the v1.0 release notes?")
+puts "Pipeline result : #{result.value.reply}"
+puts "Human was asked : #{approver.channel.asked.first}"
+
+# --- 2. Two peers messaging over a shared bus -------------------------------
+# A robot would normally be on this bus too; here both peers are humans to keep
+# the example key-free. The message plumbing is identical either way.
+
+bus  = TypedBus::MessageBus.new
+lead = RobotLab::Cyborg.new(name: "lead", bus: bus, channel: Scripted.new([]))
+# oncall just needs to exist on the bus to receive the task and reply; it is
+# addressed by name (:oncall), so no local reference is kept.
+RobotLab::Cyborg.new(name: "oncall", bus: bus, channel: Scripted.new(["yes, go ahead"]))
+
+msg = lead.assign(to: :oncall, task: "Safe to deploy right now?")
+
+# Wait for the async round-trip (task out, human answer, reply back).
+50.times do
+  break if lead.outbox[msg.key][:status] == :replied
+
+  sleep 0.02
+end
+
+reply = lead.outbox[msg.key][:replies].first
+puts "\nlead asked oncall : Safe to deploy right now?"
+puts "oncall replied    : #{reply&.content}"
+
+# --- 3. Shared memory --------------------------------------------------------
+lead.remember(:decision, "deploy at 15:00")
+puts "\nShared memory :decision => #{lead.recall(:decision)}"

data/examples/02_terminal_mentions.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Addressing peers by @mention, driven by the library Conversation.
+#
+# A live human (a Cyborg on the terminal channel) shares a bus with several
+# peers. Address them by mentioning them — "@name" — anywhere in a message, as
+# many as you like; the whole message is fanned out to everyone you mention. A
+# message with NO mention broadcasts to every peer.
+#
+# The addressing/fan-out/broadcast logic lives in RobotLab::Cyborg::Conversation
+# now, not here. Replies come back to your terminal on their own: a Cyborg
+# delivers inbound bus traffic to its channel (the output half of the duplex),
+# so this demo never has to poll or render replies.
+#
+# @assistant is a real LLM robot (Ollama) that cooperates via #serve — the
+# one-call symmetric responder. @analyst and @scribe are key-free canned peers.
+# Set OLLAMA_API_BASE/OLLAMA_MODEL, or run without Ollama and just use the canned
+# peers (@assistant will simply not answer).
+#
+#   ruby examples/02_terminal_mentions.rb
+#   # then type:  @analyst and @scribe: status?
+#   #             @assistant one-line haiku about deploys
+#   #             @quit
+
+require "logger"
+
+# Prefer the local robot_lab checkout (with serve/respond_to_tasks) over any
+# installed gem, so the demo runs from a fresh monorepo checkout.
+core_lib = File.expand_path("../../robot_lab/lib", __dir__)
+$LOAD_PATH.unshift(core_lib) if File.directory?(core_lib)
+
+require "robot_lab"
+require_relative "../lib/robot_lab/cyborg"
+
+Cyborg   = RobotLab::Cyborg
+Channel  = RobotLab::Cyborg::Channel
+
+RubyLLM.configure do |c|
+  c.ollama_api_base = ENV.fetch("OLLAMA_API_BASE", "http://localhost:11434/v1")
+  c.logger          = Logger.new(File::NULL)
+end
+RobotLab.configure { |c| c.logger = Logger.new(File::NULL) }
+
+# A canned automated peer: a Channel whose "human" is a block.
+class Autobot < Channel
+  def initialize(&reply)
+    @reply = reply
+    @inbox = Thread::Queue.new
+    super()
+  end
+
+  def correlates? = true
+  def deliver(message) = message.question? ? @inbox.push(reply_to(message)) : message
+  def receive(timeout: nil) = timeout ? @inbox.pop(timeout: timeout) : @inbox.pop
+  def close = @inbox.close
+
+  private
+
+  def reply_to(message)
+    Cyborg::ChannelMessage.new(content: @reply.call(message.content), in_reply_to: message.id, kind: :answer)
+  end
+end
+
+bus = TypedBus::MessageBus.new
+
+# The live human. Its terminal labels inbound lines by their sender.
+you = Cyborg.new(name: "you", bus: bus, channel: Channel::Terminal.new(name: "network"))
+
+# A real LLM robot that serves bus tasks — the symmetric counterpart to how the
+# Cyborg answers its human. One call, no hand-wired on_message.
+RobotLab.build(name: "assistant", bus: bus, provider: "ollama",
+               model: ENV.fetch("OLLAMA_MODEL", "qwen3.6"),
+               system_prompt: "You are a concise teammate. Answer in 1-2 sentences.").serve
+
+# Two key-free canned peers.
+Cyborg.new(name: "analyst", bus: bus, channel: Autobot.new { |_q| "error rate is 0.2% over the last hour." })
+Cyborg.new(name: "scribe",  bus: bus, channel: Autobot.new { |_q| "noted — logged to the record." })
+
+chat = Cyborg::Conversation.new(cyborg: you, peers: %w[assistant analyst scribe])
+
+you.tell("Mention peers with @name (one or more, anywhere); no mention broadcasts to all. " \
+         "Known: @assistant, @analyst, @scribe. (@quit to exit)")
+
+# The human drives the read loop; replies arrive on their own via the channel.
+loop do
+  message = you.channel.receive
+  break if message.nil?
+
+  line = message.content.strip
+  next if line.empty?
+  break if line == "@quit"
+
+  chat.route(line)
+end

data/examples/03_robot_interviews_cyborg.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# A robot interviews a cyborg (the Interviewer, the other way round).
+#
+# Examples 1 and 2 had the human drive. Here the *robot* drives: an LLM-backed
+# RobotLab robot (ProfileBot, on a local Ollama model) conducts an interview to
+# learn as much as the human is willing to share, then classifies them across
+# several categories. Each question the robot invents is delegated to the Cyborg,
+# whose Interviewer conducts it on the terminal and hands the answer back — so
+# the robot never touches $stdin/$stdout; the Cyborg's Interviewer is the whole
+# bridge between the robot's intent and the person at the keyboard.
+#
+# You can answer each question, type "skip" to pass on one, or "done" to end the
+# interview early. The robot builds the profile from whatever you chose to share.
+#
+# Requires a running Ollama with the model pulled:  ollama pull qwen3.6
+# Override with OLLAMA_MODEL / OLLAMA_API_BASE if yours differ.
+#
+#   ruby examples/03_robot_interviews_cyborg.rb
+
+require "logger"
+# Prefer the local robot_lab checkout (with the latest fixes) over any installed gem.
+core_lib = File.expand_path("../../robot_lab/lib", __dir__)
+$LOAD_PATH.unshift(core_lib) if File.directory?(core_lib)
+
+require "robot_lab"
+require_relative "../lib/robot_lab/cyborg"
+
+Cyborg  = RobotLab::Cyborg
+Channel = RobotLab::Cyborg::Channel
+
+OLLAMA_API_BASE = ENV.fetch("OLLAMA_API_BASE", "http://localhost:11434/v1")
+OLLAMA_MODEL    = ENV.fetch("OLLAMA_MODEL", "qwen3.6")
+MAX_QUESTIONS   = Integer(ENV.fetch("MAX_QUESTIONS", "5"))
+
+ENDING_WORDS   = %w[done stop quit exit].freeze
+SKIPPING_WORDS = %w[skip pass].freeze
+
+RubyLLM.configure do |c|
+  c.ollama_api_base = OLLAMA_API_BASE
+  c.logger          = Logger.new(File::NULL)
+end
+RobotLab.configure { |c| c.logger = Logger.new(File::NULL) }
+
+# The interviewer robot. Its system prompt fixes the categories it is building
+# toward and keeps it to one question at a time so each turn maps cleanly onto a
+# single Interviewer ask.
+robot = RobotLab.build(
+  name: "ProfileBot",
+  provider: "ollama",
+  model: OLLAMA_MODEL,
+  system_prompt: <<~PROMPT
+    You are ProfileBot, a warm, concise interviewer. Your goal is to learn as much
+    as the person is willing to share so you can later classify them across these
+    categories: technical proficiency, professional role, communication style,
+    interests, and decision-making style.
+
+    Rules:
+    - Ask exactly ONE short, friendly question per turn.
+    - Output only the question itself — no preamble, numbering, or commentary.
+    - Build on what they have already told you; do not repeat a topic.
+    - Do not classify or summarize until you are explicitly asked to.
+  PROMPT
+)
+
+# The human peer. Its terminal shows each question under a "[ProfileBot]" label,
+# since in this demo everything the human hears comes from the robot.
+you = Cyborg.new(name: "you", channel: Channel::Terminal.new(name: "ProfileBot"), ask_timeout: 300)
+
+# Ask the human one question by delegating it to the Cyborg. The Cyborg's
+# Interviewer delivers it over the terminal channel and returns the answer.
+def interview_turn(robot, human, question)
+  robot.delegate(to: human, task: question).reply.to_s.strip
+end
+
+you.tell("Hi! I'd like to ask you a few questions.")
+
+# A short *typed* intake first — the Cyborg validates and re-asks on bad input.
+unless you.ask_confirm("Ready to begin?")
+  you.tell("No problem — maybe another time.")
+  exit
+end
+years = you.ask_int("Roughly how many years have you worked in your field?")
+you.tell("Thanks. Answer freely from here, say \"skip\" to pass, or \"done\" to finish.")
+
+# Seed the robot with the structured intake so it shows up in the profile.
+robot.run(%(Context: they have about #{years || "an unstated number of"} years of experience. Acknowledge in one word.))
+
+question       = robot.run("Ask your first question.").reply.to_s.strip
+answers_given  = 0
+
+until answers_given >= MAX_QUESTIONS
+  answer = interview_turn(robot, you, question)
+  break if ENDING_WORDS.include?(answer.downcase)
+
+  answers_given += 1
+  feedback = if answer.empty? || SKIPPING_WORDS.include?(answer.downcase)
+               "They preferred to skip that. Ask a different, lighter question."
+             elsif answers_given >= MAX_QUESTIONS
+               %(They answered: "#{answer}". That was the final question — reply with just "Thanks!")
+             else
+               %(They answered: "#{answer}". Ask your next question.)
+             end
+  # Feeding the answer back both records it in the robot's memory and produces
+  # the next question (the last one is discarded once the quota is reached).
+  question = robot.run(feedback).reply.to_s.strip
+end
+
+puts "\n  …ProfileBot is building your profile…"
+profile = robot.run(<<~PROMPT).reply.to_s.strip
+  The interview is complete. Using only what they told you, build their profile.
+  For each category give your classification and a one-line reason grounded in
+  their answers; write "insufficient information" where they did not reveal enough.
+
+  Technical proficiency:
+  Professional role:
+  Communication style:
+  Interests:
+  Decision-making style:
+
+  End with a one-sentence overall summary.
+PROMPT
+
+you.tell("Here is the profile I built from what you shared:\n\n#{profile}")

data/examples/04_presence_and_availability.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Presence & availability: routing work to a human who is actually there.
+#
+# A human peer publishes a presence — :online, :away, or :offline — that the
+# network can use to route around or escalate for someone who isn't available,
+# instead of blocking on a person who will never answer.
+#
+#   :online   takes work now
+#   :away      still asked, but the caller should use a bounded timeout
+#   :offline   declines inbound bus tasks immediately
+#
+# Key-free: the "humans" here are scripted, so the demo runs deterministically.
+#
+#   ruby examples/04_presence_and_availability.rb
+
+# Prefer the local robot_lab checkout (with the latest fixes) over any installed gem.
+core_lib = File.expand_path("../../robot_lab/lib", __dir__)
+$LOAD_PATH.unshift(core_lib) if File.directory?(core_lib)
+
+require "robot_lab"
+require_relative "../lib/robot_lab/cyborg"
+
+Cyborg   = RobotLab::Cyborg
+Scripted = RobotLab::Cyborg::Channel::Scripted
+
+bus = TypedBus::MessageBus.new
+
+dispatcher = Cyborg.new(name: "dispatcher", bus: bus, channel: Scripted.new)
+alice = Cyborg.new(name: "alice", bus: bus, channel: Scripted.new(["Approved — ship it.", "Signed off."])) # online
+bob   = Cyborg.new(name: "bob",   bus: bus, channel: Scripted.new(["(bob should never be asked)"]))  # offline
+sam   = Cyborg.new(name: "sam",   bus: bus, channel: Scripted.new, ask_timeout: 0.4)                 # away, never answers
+
+bob.offline!
+sam.away!
+
+# Wait briefly for a reply to a sent task; return its text or nil.
+def await_reply(peer, key, timeout: 3)
+  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+  loop do
+    entry = peer.outbox[key]
+    return entry[:replies].first&.content if entry && entry[:status] == :replied
+    return nil if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+    sleep 0.02
+  end
+end
+
+def ask_over_bus(dispatcher, name, task)
+  message = dispatcher.assign(to: name, task: task)
+  await_reply(dispatcher, message.key)
+end
+
+puts "Presence of each peer:"
+[alice, bob, sam].each { |p| puts "  #{p.name.ljust(6)} #{p.presence}  (available? #{p.available?})" }
+
+puts "\n1) Route to the first *available* peer among [bob, alice]:"
+approver = [bob, alice].find(&:available?)
+puts "   picked @#{approver.name} (bob is offline) -> asked over the bus"
+puts "   @#{approver.name} says: #{ask_over_bus(dispatcher, approver.name, 'Approve the deploy?')}"
+
+puts "\n2) Ask @bob anyway (offline) — declined immediately, no hanging:"
+puts "   @bob replies: #{ask_over_bus(dispatcher, 'bob', 'Approve the deploy?')}"
+
+puts "\n3) Ask @sam (away) with a 0.4s bound — times out, so escalate:"
+if ask_over_bus(dispatcher, "sam", "Quick sign-off?").nil?
+  puts "   @sam did not answer in time -> escalating to @alice"
+  puts "   @alice says: #{ask_over_bus(dispatcher, 'alice', 'Quick sign-off?')}"
+end