robot_lab-a2a 0.1.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b79d098ef9b24711b48d41af7140e3bf331594f427b5518814e4ff58cde38a2d
-  data.tar.gz: e38b9117d0b2d2dae5f3483ff7dd826ef25e0f7525738cf30941aead87214f77
+  metadata.gz: 508cfed94ac09af2dc3aef1bdce245e1ec12e561dc1af58e1a11c37c362c3e9a
+  data.tar.gz: 7014425d58923f5cf00f74e96242f0f77890e4342ea1cd06022cbab8d13dbdad
 SHA512:
-  metadata.gz: 13b98611d8ef81ce10a0bddb1010a932e4b52a032546beb44eb3791d94f82d02fb3691a40c42222e3931824278cf31511fa9ec2fa864243dcbacdcf7779a2895
-  data.tar.gz: a284690e28a7967c3784bbeebee40fd4019ca9c0c1f712d48f6cf5c0e42b33cc41881ddb866e9f7f7ad77b399d52b35da2ee92d2e55d3bc059de77b20714e473
+  metadata.gz: 3604a8078469267732f02a7bd7d5bd52d00e1980a2bac92c38c7c495947d11404fe1dc1614f166589e3be6a75afa98d5889485ad01121fc87e14e1107911ada1
+  data.tar.gz: c87c24bf66e2d1490d3e51b4d6155e753d5f1e24083fa2a3c93b1341506c8927f813b509c72d82224d319931fdea3c4b3026c5a1109343478645a9830fb3356a

data/.envrc

@@ -1 +1,3 @@
+source_up
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-a2a — Agent2Agent protocol adapter over HTTP+SSE.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-a2a".freeze
+
+  header "robot_lab-a2a v#{gem_version} — A2A protocol adapter"
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,6 @@
+2	lib/robot_lab/a2a/ask_user_tool.rb
+1	lib/robot_lab/a2a/io_bridge.rb
+2	lib/robot_lab/a2a/network_adapter.rb
+2	lib/robot_lab/a2a/registry.rb
+7	lib/robot_lab/a2a/robot_adapter.rb
+8	lib/robot_lab/a2a/server.rb

data/.rubocop.yml

@@ -1,29 +1 @@
-AllCops:
-  NewCops: enable
-  SuggestExtensions: false
-  Exclude:
-    - 'examples/**/*'
-
-Style/Documentation:
-  Enabled: false
-
-Layout/ExtraSpacing:
-  Enabled: false
-
-Metrics/MethodLength:
-  Max: 25
-  CountAsOne:
-    - heredoc
-    - array
-    - hash
-
-Metrics/AbcSize:
-  Max: 25
-
-Metrics/ClassLength:
-  Max: 150
-
-Metrics/BlockLength:
-  Exclude:
-    - 'Rakefile'
-    - '*.gemspec'
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+### Added
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, and `console` tasks via the Asgard task runner
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` and `minitest-reporters` gems added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
+## [0.2.1] - 2026-05-19
+
 ### Added
 
 - Demo examples infrastructure: `examples/run` lifecycle script, shared `examples/common_config.rb`, and three complete demos:
@@ -13,6 +25,7 @@
 ### Changed
 
 - Interactive mode `:acp_tool` renamed to `:a2a_tool` across all source, tests, and documentation
+- Version synchronized with robot_lab core 0.2.1
 
 ### Fixed
 

data/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-a2a` is an Agent2Agent (A2A) protocol adapter that exposes RobotLab robots and networks as A2A agents over HTTP+SSE. It bridges RobotLab's terminal-based `AskUser` tool to A2A's `input_required`/resume lifecycle, enabling multi-turn conversational flows without terminal dependency. It delegates HTTP serving to the `simple_a2a` gem.
+
+## Commands
+
+```bash
+rake test              # Run full test suite (default rake task)
+rake build             # Build the gem package
+rake install           # Install gem locally
+
+bin/setup              # Install dependencies
+bin/console            # IRB session with gem loaded
+
+# Run a single test file
+ruby -Ilib -Itest test/robot_lab/test_a2a.rb
+
+# Run a single test by name
+ruby -Ilib -Itest test/robot_lab/test_a2a.rb -n test_registry_stores_and_retrieves
+```
+
+## Architecture
+
+All source lives under `lib/robot_lab/a2a/`. The gem uses an adapter pattern — the two adapters both implement the `A2A::Server::AgentExecutor` interface with a single `call(context)` method.
+
+### Key Abstractions
+
+**Registry** (`registry.rb`) — Thread-safe singleton tracking active robot sessions across HTTP requests. Entries are `Data.define(:thread, :event_queue, :answer_queue)` stored by session ID. Required because A2A `tasks/send` resumes an in-flight robot thread.
+
+**RobotAdapter** (`robot_adapter.rb`) — Wraps a `RobotLab::Robot` as an executor. Supports three interactive modes:
+- `:none` — Synchronous, robot runs to completion with no input prompts.
+- `:a2a_tool` — Injects `AskUserTool` into the robot's `@local_tools`, converting terminal blocking to Queue signaling. Restores original tools on teardown.
+- `:io_bridge` — Replaces the robot's I/O streams with an `IoBridge` instance; works with robots that use `puts`/`gets` directly.
+
+**AskUserTool** (`ask_user_tool.rb`) — Drop-in replacement for `RobotLab::AskUser`. On `call`, pushes `{type: :ask, prompt:}` to the event_queue then blocks on answer_queue until the A2A client sends a resume.
+
+**IoBridge** (`io_bridge.rb`) — IO-compatible object. Buffers all writes; on `gets`, flushes the buffer as the prompt event and blocks on answer_queue. Enables interactive mode for robots that don't use the AskUser tool directly.
+
+**NetworkAdapter** (`network_adapter.rb`) — Wraps a `RobotLab::Network`. Currently supports only `:none` mode; interactive mode per network node is not yet implemented.
+
+**Server** (`server.rb`) — Fluent builder. `add_robot` / `add_network` register adapters keyed by DNS-safe path labels (underscores→hyphens, RFC 1123). `run(port:)` starts the HTTP server; `to_app` returns a Rack app for embedding in Rails/Puma.
+
+### Thread Safety
+
+Interactive modes run each robot on its own Ruby Thread. `Registry` uses a `Mutex`. `AskUserTool` and `IoBridge` use Ruby's `Queue` for producer/consumer coordination between the robot thread and the HTTP request handler.
+
+### Extension Registration
+
+The gem hooks into RobotLab's extension system at require time (`a2a.rb`) and registers itself as the `:a2a` extension.
+
+## Tests
+
+Tests live in `test/robot_lab/test_a2a.rb` using Minitest with autorun. The test helper is `test/test_helper.rb`. There is no `.rspec` or RuboCop config — no linter is configured.

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/testtask'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
   t.verbose = true
   t.ruby_opts << '-rtest_helper'
 end
@@ -24,16 +24,6 @@ task :test_file, [:file] do |_t, args|
   ruby "test/#{args[:file]}"
 end
 
-desc 'Check code style with RuboCop'
-task :rubocop do
-  sh 'bundle exec rubocop'
-end
-
-desc 'Auto-correct RuboCop offenses'
-task :rubocop_fix do
-  sh 'bundle exec rubocop -a'
-end
-
 desc 'Check code complexity with Flog (warn >=20, fail >=50)'
 task :flog_check do
   require 'flog'
@@ -71,34 +61,72 @@ task :flog_check do
   end
 end
 
-desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
+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
-  results = {}
+  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
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Tests + Coverage'
-  puts '=' * 60
-  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+  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: RuboCop'
+  puts 'Quality Gate Summary'
   puts '=' * 60
-  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
+  end
+  puts '-' * 60
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Flog Complexity'
+  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
-  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Summary'
-  puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
+  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
-  puts '=' * 60
 
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
 end

data/docs/examples.md

@@ -5,6 +5,7 @@
 ```
 examples/
   run                     # launcher script
+  common_config.rb        # shared $LOAD_PATH + require, loaded by every example
   01_sync_robot/
     server.rb             # starts the A2A server
     client.rb             # sends a task and prints the result
@@ -14,6 +15,16 @@ examples/
   03_robot_network/
     server.rb
     client.rb
+  04_io_bridge/
+    server.rb
+    client.rb
+  05_multi_agent/
+    server.rb
+    client.rb
+  06_rack_mount/
+    server.rb
+    config.ru             # standalone Rack/Rails mount reference (not used by run)
+    client.rb
 ```
 
 ## How to run
@@ -114,3 +125,46 @@ Sending task to network...
 Reply: [synthesised answer from the final pipeline stage]
 Done.
 ```
+
+## 04_io_bridge
+
+**Demonstrates:** `:io_bridge` interactive mode. `QuoteRobot` has no knowledge of A2A at all — it just calls `@output.puts` and `@input.gets` (falling back to `$stdout`/`$stdin` when not injected), so the same class also runs fine interactively in a terminal. The server injects an `IoBridge` as `robot.input`/`robot.output` before each run.
+
+**Two-turn flow:**
+
+1. Client sends a topic (`"stoicism"`) → `QuoteRobot` writes its question to the buffered output, then calls `gets` → `IoBridge` flushes the buffer as the `input_required` prompt and blocks.
+2. Client resumes with the same `task_id` and an answer (`"Ada"`) → `IoBridge` unblocks `gets` → the robot completes and returns a quote addressed to that name.
+
+**What it shows:**
+
+- `interactive: :io_bridge` server setup
+- A robot written against plain Ruby IO, with no A2A-specific code
+- The same two-turn `task_id` resume pattern as `:a2a_tool`
+
+**Note:** Turn 2 requires a `simple_a2a` build with `ResumeContext` support (>= 0.3.1). On older versions the client still demonstrates Turn 1's `input_required` suspension.
+
+## 05_multi_agent
+
+**Demonstrates:** Multiple independent A2A agents served from a single process via the fluent builder API with explicit `path:` overrides — `HeadlineRobot` at `/headline` and `TagRobot` at `/tags`.
+
+**What it shows:**
+
+- Chaining `add_robot` calls with explicit `path:` values on one `Server` instance
+- Two separate `A2A.client` instances, one per agent path, each with its own agent card
+- That co-located agents are indistinguishable from independently hosted ones at the protocol level
+
+**Expected output (client):** both clients discover their agent card, send the same input text, and print each robot's distinct reply (a capitalised headline vs. a list of `#hashtag` keywords) alongside pass/fail assertions.
+
+## 06_rack_mount
+
+**Demonstrates:** `server.to_app`, which returns a `Rack::URLMap` instead of starting a dedicated server — for embedding A2A agents inside a larger Rack application (Rails, Sinatra, Puma, etc.) rather than running `server.run` standalone.
+
+The demo composes the A2A agent (`EchoRobot`, mounted via `to_app`) with a plain `/health` JSON Rack endpoint on the same combined app, run via `A2A::Server::FalconRunner`. `config.ru` in this directory is a copy-paste reference for mounting the same `to_app` result under Rackup or a Rails `config/routes.rb` — it is not used by `examples/run`.
+
+**What it shows:**
+
+- `add_robot(...).to_app` returning a `Rack::URLMap`
+- Composing that map with unrelated Rack routes
+- That both A2A and non-A2A routes work correctly side by side on the composed app
+
+**Expected output (client):** a passing health check against `/health` followed by a normal A2A `send_task` round trip against `/echo-robot`, each reported with a pass/fail assertion.

data/docs/interactive-modes.md

@@ -102,3 +102,7 @@ RobotLab::A2A::Server.new(interactive: :io_bridge)
 | `:io_bridge` | `robot.run(text)` + settable `robot.input=` / `robot.output=` | Robots that interact via raw stdin/stdout streams |
 
 When in doubt, start with `:none`. Upgrade to `:a2a_tool` if your robot uses `AskUser`, or `:io_bridge` if it uses raw IO.
+
+## Cancelling an in-progress task
+
+While a robot is suspended waiting on `answer_queue` (i.e. between an `input_required` event and the client's resume), the A2A client may send `tasks/cancel` instead of resuming. `RobotAdapter#cancel` looks the task up in `Registry` by task ID, kills the robot thread with `Thread#kill`, and removes the entry from `Registry` before delegating to the default `AgentExecutor#cancel` behaviour. If no entry is found (e.g. the task already completed or was never interactive), `cancel` is a no-op aside from the default behaviour.

data/docs/server-api.md

@@ -27,8 +27,8 @@ Valid `interactive` values: `:none`, `:a2a_tool`, `:io_bridge`. See [Interactive
 ```ruby
 server.add_robot(
   robot,
-  name:        required,   # String — human-readable agent name
-  description: required,   # String — agent capability description
+  name:        nil,        # String — human-readable agent name; defaults to robot.name
+  description: nil,        # String — agent capability description; defaults to robot.description
   path:        nil         # String — URL path segment; derived from name if nil
 ) → self
 ```
@@ -51,12 +51,12 @@ Wraps `robot` in a `RobotAdapter` using the server's `interactive` setting and r
 server.add_network(
   network,
   name:        required,   # String — human-readable agent name
-  description: required,   # String — agent capability description
+  description: nil,        # String — agent capability description; defaults to name
   path:        nil         # String — URL path segment; derived from name if nil
 ) → self
 ```
 
-Wraps `network` in a `NetworkAdapter`. Only `:none` mode is supported for networks; the `interactive` setting is ignored.
+Wraps `network` in a `NetworkAdapter`, always constructed with `interactive: :none`. If the server's own `interactive` setting is anything other than `:none`, `add_network` raises `ArgumentError` instead of silently ignoring it — networks do not support interactive modes. Wrap individual robots with `RobotAdapter` (via `add_robot`) for interactive flows.
 
 **`network` must respond to:**
 

data/lib/robot_lab/a2a/version.rb

@@ -2,6 +2,6 @@
 
 module RobotLab
   module A2A
-    VERSION = '0.1.1'
+    VERSION = '0.2.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab-a2a
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -27,16 +27,16 @@ dependencies:
   name: robot_lab
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: simple_a2a
   requirement: !ruby/object:Gem::Requirement
@@ -63,8 +63,11 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - COMMITS.md
 - LICENSE.txt
 - README.md
@@ -122,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Agent2Agent (A2A) protocol adapter for RobotLab
 test_files: []