robot_lab-cyborg 0.2.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5289e0bf089059f451300a62b776b06141d684bb60ed6df407624313a695500
+  data.tar.gz: eab4d957cbd19ca2fb66e97d2ba2ddd806167c0dab6ffb623fad10204386cdd4
+SHA512:
+  metadata.gz: f6a29be1c412e3005a55e25bfaacfbb60d6a535a636e9692f188da47ee09da8736268561570beba5d2164066dca8abbbac68f8f538a8171be2815697e8929d41
+  data.tar.gz: 01b49e8eed2356da4eafb1bf7e48dc408a84e877bcd52aae5e5a75a80927dab83a8d4daf73ad875199cf44ef5e5bcf33b8d9b0aa2379d7e8d9b52433ba7bf17c

data/.envrc

@@ -0,0 +1 @@
+export RR=$(pwd)

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-cyborg — human-in-the-network peer worker for RobotLab.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-cyborg".freeze
+
+  header "robot_lab-cyborg v#{gem_version} — human peer worker"
+end

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed (from the design/architecture review)
+- **Consumer no longer wedges on a handler error.** An exception in an
+  `on_initiative`/channel path used to kill the Interviewer's consumer thread and
+  hang every future ask; it is now caught (recorded in `Interviewer#last_error`)
+  and the loop keeps serving. *(A1)*
+- **Inbound bus tasks no longer block the poller.** A Cyborg answers an inbound
+  task on its own thread, so a slow or absent human never stalls bus intake, and
+  the default no longer deadlocks. *(A2)*
+- **No more mis-attributed answers on a dumb channel.** On a channel that can't
+  correlate replies (`Channel#correlates? == false`, e.g. a terminal), questions
+  are *serialized* — one on the wire at a time — and an answer resolves that
+  active question. A `Terminal` now honors `receive(timeout:)` (via
+  `wait_readable`), so timeouts, `close`, and expiry actually work. *(A3, A4)*
+- **Shared memory no longer leaks across runs.** `attach_memory`/`detach_memory`
+  make the target explicit, and access is thread-safe. *(A5)*
+- Core `RobotLab::Robot::BusMessaging` synchronizes its message counter/outbox,
+  and gains `respond_to_tasks`/`serve` so a **Robot** auto-answers bus tasks the
+  way a Cyborg does — man/machine peers are now symmetric on the bus. *(A6, B1)*
+
+### Added
+- **Duplex to the human's channel.** Inbound bus messages/replies are now
+  delivered to the human's channel (`Cyborg#tell` for the output direction);
+  `ChannelMessage` carries `sender`/`kind`/`at` so a terminal can label who is
+  speaking and only prompt on questions. *(B2, B5)*
+- **Always-on listening.** `Cyborg#listen`/`converse` keep reading the channel
+  with no question outstanding, so a human can address the network unprompted;
+  their input arrives via `on_human`. *(B3)*
+- **`Conversation`** — `@mention` addressing, multi-mention fan-out, and
+  no-mention broadcast now live in the library (`Cyborg#converse`), not in
+  example code. Replies flow back via the duplex. *(B4)*
+- **Typed/validated answers** — `Cyborg#ask(validate:, retries:)` plus
+  `ask_int`/`ask_confirm` re-ask on bad input and return coerced values. *(C)*
+- **Presence** — `online!`/`away!`/`offline!`/`available?`; an offline human
+  declines inbound tasks immediately so the network can route around/escalate.
+  *(B8)*
+- `Cyborg#ask_async` returns the pending `Question` for non-blocking waits — the
+  primitive a durable/suspendable human step would persist (see README, *Durable
+  human steps*, for the intended `robot_lab-durable` integration — *B7*).
+
+### Changed
+- Split reaching the human into two concerns: **`Channel`** (the *means* — a
+  dumb bidirectional pipe: `deliver` out, `receive` in) and **`Interviewer`**
+  (the *process* that conducts the ask over a channel). `$stdin`/`$stdout` now
+  live only inside `Channel::Terminal`; `Cyborg` depends on an injected
+  `channel:` and no longer takes `input:`/`output:`.
+  - `Interviewer::Terminal` / `Interviewer::Scripted` moved to
+    `Channel::Terminal` / `Channel::Scripted`. `Cyborg.new` takes `channel:`
+    instead of `interviewer:` (an `interviewer:` may still be injected for full
+    control).
+  - Read the questions a Scripted human was shown via `cyborg.channel.asked`
+    (was `cyborg.interviewer.asked`).
+
+### Added
+- **Asynchronous asking.** A human's answer may be the next inbound message, a
+  later one, or never. `Interviewer#ask` now returns a `Question` (a one-shot
+  future); `Cyborg#ask_async` exposes it. The synchronous `Cyborg#ask` /
+  `Interviewer#ask_and_wait` wait with an optional timeout.
+- **Reply correlation.** Inbound messages carry an optional `in_reply_to` so a
+  rich transport (Slack threads, email) resolves the exact question; a bare
+  terminal falls back to oldest-outstanding (FIFO).
+- **Bounded waiting.** `Cyborg.new(ask_timeout:)` and per-call `timeout:` give a
+  slow or absent human a deadline, after which the answer is the default (or nil).
+- `Cyborg#on_human` — surfaces unsolicited human messages (initiative) that
+  answer no outstanding question. (Routing initiative onto the bus is future work.)
+
+## [0.1.0] - 2026-07-24
+
+### Added
+- `RobotLab::Cyborg` — a human peer worker that joins a RobotLab network at the
+  same level as the robots. It reuses `RobotLab::Robot::BusMessaging`, so its bus
+  behavior is identical to a robot's, but requires no LLM, model, or API key.
+  - **Receives tasking** as a pipeline step (`network.task :name, cyborg`) via the
+    `call`/`run` member contract, and over the bus (inbound messages are surfaced
+    to the human and answered, with optional `auto_reply`).
+  - **Issues tasking** to other members with `assign` (bus) and `delegate` (sync or
+    async, returning a `RobotResult` / `DelegationFuture`).
+  - **Shares memory** with the network via `remember` / `recall`.
+- `RobotLab::Cyborg::Interviewer` — the pluggable human interface, with
+  `Terminal` (injectable IO) and `Scripted` (tests/automation) implementations.
+- Registers itself with core via `RobotLab.register_extension(:cyborg, …)`.
+- Minitest suite covering the interviewers, the network-member contract and shared
+  memory, the bus task/reply round-trip, and delegation.
+
+[Unreleased]: https://github.com/MadBomber/robot_lab-cyborg/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MadBomber/robot_lab-cyborg/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# 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 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.
+
+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 model and no API key. The human is the "model," reached across an injectable **`Channel`** (the *means* — terminal now, Slack/email/web later) by an **`Interviewer`** (the *process* that conducts the ask).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "robot_lab"
+gem "robot_lab-cyborg"
+```
+
+## Usage
+
+```ruby
+require "robot_lab"
+require "robot_lab/cyborg"
+
+# A human peer. By default it talks to a terminal; inject a Channel to
+# reach the human over a web form, a queue, a chat app, or a test.
+dewayne = RobotLab::Cyborg.new(name: "dewayne")
+```
+
+### A human as a pipeline step
+
+The human is interchangeable with a robot anywhere a member is expected:
+
+```ruby
+writer = RobotLab.build(name: "writer", template: :writer)
+
+network = RobotLab.create_network(name: "release") do
+  task :draft,   writer,  depends_on: :none
+  task :approve, dewayne, depends_on: [:draft]   # the human signs off
+end
+
+network.run(message: "Draft the release notes")
+```
+
+### Peers messaging over a shared bus
+
+Robots and cyborgs talk to each other by name over one shared bus:
+
+```ruby
+bus     = TypedBus::MessageBus.new
+analyst = RobotLab.build(name: "analyst", bus: bus)
+dewayne = RobotLab::Cyborg.new(name: "dewayne", bus: bus)
+
+# The robot asks the human a question; the human's answer comes back as a reply.
+analyst.send_message(to: :dewayne, content: "Approve the deploy? (yes/no)")
+
+# The human issues work to the robot, too.
+dewayne.assign(to: :analyst, task: "Summarize today's error budget.")
+```
+
+### Shared memory
+
+```ruby
+dewayne.remember(:decision, "ship it")   # visible to every member
+dewayne.recall(:sentiment, wait: 30)     # block until a robot writes it
+```
+
+### Channels and the Interviewer
+
+Reaching the human is split into two concerns:
+
+- A **`Channel`** is the *means* — a dumb bidirectional pipe with two jobs: `deliver` a message **out** to the human, and surface messages the human sends **in**. It knows nothing about questions or answers. This is the injection point; `$stdin`/`$stdout` live only inside `Channel::Terminal`.
+- An **`Interviewer`** is the *process* — it conducts the interaction over whatever channel is injected. Asking is **always asynchronous**: the human's answer may be the next inbound message, a later one, or never. So `ask` delivers the question and returns a `Question` you can wait on with a timeout; a background consumer matches answers to questions (by the channel's correlation id when it has one, else oldest-first) and routes anything unsolicited as human *initiative*.
+
+Built-in channels:
+
+- `Channel::Terminal` — the human at a keyboard (the default); IO is injectable.
+- `Channel::Scripted` — canned answers in order, with exact correlation (tests, automation, replay).
+- `Channel` — the abstract base; subclass it (implement `deliver`/`receive`) to bridge to Slack, email, a web UI, or a task queue.
+
+A channel that can tie an answer back to its question (Slack threads, email) reports `correlates? == true`, and the Interviewer lets several questions be outstanding at once. A dumb channel (a bare terminal) reports `false`, and the Interviewer **serializes** — one question on the wire at a time — so an answer is never mis-attributed.
+
+```ruby
+scripted = RobotLab::Cyborg::Channel::Scripted.new(["yes", "ship it"])
+bot      = RobotLab::Cyborg.new(name: "dewayne", channel: scripted)
+
+# Give a slow or absent human a bounded wait:
+oncall   = RobotLab::Cyborg.new(name: "oncall", ask_timeout: 30)   # nil answer if no reply
+```
+
+### Cooperating in a network
+
+- **Symmetric bus membership.** A Cyborg answers inbound bus tasks out of the box; a Robot opts in with one call — `robot.serve` (run each task through the model and reply) or `robot.respond_to_tasks { |m| ... }`. Both are first-class responders.
+- **Duplex.** Inbound messages/replies are shown to the human on their channel automatically; `cyborg.tell("...")` pushes a line out yourself.
+- **Addressing.** `cyborg.converse(peers: %w[analyst scribe])` starts a `Conversation`: the human addresses peers by `@mention` anywhere in a message (fan-out to all mentioned; **no mention broadcasts to everyone**), and replies come back on the channel.
+- **Listening.** `converse`/`listen` keep reading the channel with no question pending, so the human can speak to the network unprompted (delivered via `on_human`).
+- **Typed answers.** `ask_int`, `ask_confirm`, or `ask(validate:, retries:)` re-ask on bad input and return coerced values.
+- **Presence.** `online!` / `away!` / `offline!` / `available?` — an offline human declines inbound tasks immediately, so the network can route around or escalate.
+
+```ruby
+you = RobotLab::Cyborg.new(name: "you", bus: bus)
+you.converse(peers: %w[analyst scribe])         # @mention to address, no mention = broadcast
+ready = you.ask_confirm("Deploy now?")          # => true / false
+you.away!                                        # still asked, but use a bounded timeout
+```
+
+#### Durable human steps (roadmap)
+
+A human step currently holds a thread while it waits. `ask_async` returns the pending `Question` without blocking — the primitive a durable integration would persist. The intended path is to store a pending decision through **`robot_lab-durable`** (and `robot_lab-to`'s `DecisionManager`) so a human decision survives a process restart and doesn't pin a thread. Per-peer cryptographic identity/attribution (signed events) is the complementary trust direction, on top of the existing per-message `sender`/`from`.
+
+## Examples
+
+Runnable demos in [`examples/`](examples) — one feature area each:
+
+- `01_human_in_the_network.rb` — a human as a pipeline step, peers messaging over a bus, shared memory (network → human). Key-free.
+- `02_terminal_mentions.rb` — a **live** human addresses peers by `@mention` via the library `Conversation` (fan-out, and no-mention broadcast); replies return on their own through the duplex. Includes a real **LLM robot** (`@assistant`, Ollama) cooperating via `serve`, plus key-free canned peers.
+- `03_robot_interviews_cyborg.rb` — the Interviewer the *other* way round: an **LLM robot** (Ollama) interviews the human via `delegate`, starting with a **typed** intake (`ask_confirm`/`ask_int`, which re-ask on bad input), then builds a categorized profile.
+- `04_presence_and_availability.rb` — routing to a peer who's actually there: `online`/`away`/`offline`, an offline human declining immediately, and a bounded-timeout escalation. Key-free.
+- `05_listening_and_duplex.rb` — always-on `listen`: the human speaks to the network **unprompted** and replies come back on the channel — both directions handled by the library. Key-free.
+
+```bash
+ruby examples/01_human_in_the_network.rb
+ruby examples/04_presence_and_availability.rb
+ruby examples/05_listening_and_duplex.rb
+
+# Examples 2 and 3 use a real robot on Ollama (ollama pull qwen3.6; override with
+# OLLAMA_MODEL / OLLAMA_API_BASE). In example 2 the canned peers still work
+# without it — only @assistant needs Ollama.
+ruby examples/02_terminal_mentions.rb        # then type: @analyst and @scribe: status?
+ruby examples/03_robot_interviews_cyborg.rb  # the robot asks you the questions
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake test` to run the tests, or `rake quality` to run the full gate (tests, RuboCop, Flog, Flay). `bin/console` gives an interactive prompt.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
+
+task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+task :test_file, [:file] do |_t, args|
+  ruby "test/#{args[:file]}"
+end
+
+desc 'Check code complexity with Flog (warn >=20, fail >=50)'
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
+
+  mass_threshold = 50
+
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
+
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate Summary'
+  puts '=' * 60
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
+  end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
+  puts '=' * 60
+
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
+end
+
+namespace :docs do
+  desc 'Build MkDocs documentation'
+  task :build do
+    sh 'mkdocs build'
+  end
+
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
+end