robot_lab-a2a 0.1.0

data/docs/server-api.md

@@ -0,0 +1,118 @@
+# Server API Reference
+
+`RobotLab::A2A::Server` is a fluent builder. Every mutating method returns `self` so calls can be chained.
+
+## Constructor
+
+```ruby
+RobotLab::A2A::Server.new(
+  host:        "localhost",  # String  — bind address
+  port:        9292,         # Integer — TCP port
+  storage:     nil,          # Object  — task storage backend (simple_a2a compatible); nil uses in-memory default
+  interactive: :none         # Symbol  — default interactive mode for all registered adapters
+)
+```
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `host` | `String` | `"localhost"` | Passed through to `simple_a2a` / Falcon |
+| `port` | `Integer` | `9292` | TCP port to listen on |
+| `storage` | Object / nil | `nil` | Pluggable task persistence; defaults to an in-memory store |
+| `interactive` | `Symbol` | `:none` | Applies to all adapters unless overridden per-registration |
+
+Valid `interactive` values: `:none`, `:a2a_tool`, `:io_bridge`. See [Interactive Modes](interactive-modes.md) for details.
+
+## `add_robot`
+
+```ruby
+server.add_robot(
+  robot,
+  name:        required,   # String — human-readable agent name
+  description: required,   # String — agent capability description
+  path:        nil         # String — URL path segment; derived from name if nil
+) → self
+```
+
+Wraps `robot` in a `RobotAdapter` using the server's `interactive` setting and registers it with `simple_a2a`.
+
+**`robot` must respond to:**
+
+- `robot.name` → `String`
+- `robot.description` → `String`
+- `robot.run(text)` → object responding to `.reply`
+- For `:a2a_tool`: `robot.local_tools` → mutable `Array` (backed by `@local_tools`)
+- For `:io_bridge`: `robot.input=` and `robot.output=`
+
+**Path defaulting:** If `path:` is omitted, it is derived from `name` by applying the DNS label conversion rule (see below). Example: `name: "My Robot"` → path `/my-robot`.
+
+## `add_network`
+
+```ruby
+server.add_network(
+  network,
+  name:        required,   # String — human-readable agent name
+  description: required,   # String — agent capability description
+  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.
+
+**`network` must respond to:**
+
+- `network.run(message: text)` → object responding to `.last_text_content`
+
+**Path defaulting:** Same DNS label conversion as `add_robot`.
+
+## `add_robot` — optional keyword details
+
+`name:` and `description:` default to `robot.name` and `robot.description` when omitted. `path:` always defaults to the DNS label of the name used.
+
+## `run`
+
+```ruby
+server.run
+```
+
+Starts the Falcon HTTP server (blocking). Host and port are set in the constructor. Does not return until the server is stopped.
+
+## `to_app`
+
+```ruby
+app = server.to_app  # → Rack::URLMap
+```
+
+Returns a `Rack::URLMap` instead of starting a server. Use this to embed `robot_lab-a2a` inside an existing Rack application such as Rails or Puma.
+
+Example `config.ru`:
+
+```ruby
+require "robot_lab/a2a"
+require_relative "my_robot"
+
+robot = MyRobot.new
+a2a = RobotLab::A2A::Server.new
+        .add_robot(robot, name: "Assistant", description: "General assistant")
+
+run Rack::URLMap.new(
+  "/"     => MyRailsApp,
+  "/a2a"  => a2a.to_app
+)
+```
+
+## DNS label conversion rule
+
+Agent names are converted to RFC 1123-compatible path segments:
+
+1. Convert to lowercase.
+2. Replace underscores with hyphens.
+3. Drop any character that is not an ASCII letter, digit, or hyphen.
+4. Strip leading/trailing hyphens.
+
+Examples:
+
+| Name | Path |
+|---|---|
+| `"My Robot"` | `/my-robot` |
+| `"order_processor"` | `/order-processor` |
+| `"GPT-4 Agent!"` | `/gpt-4-agent` |

data/examples/01_sync_robot/client.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/01_sync_robot/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/01_sync_robot/server.rb
+#
+# Or run both together:
+#   bundle exec ruby examples/run 01_sync_robot
+#
+# What this demo shows:
+#
+#   Discovery  — client.agent_card fetches the agent's name, description, and
+#                skills declared by the robot and published over A2A.
+#
+#   Task send  — client.send_task dispatches a user message and returns a
+#                completed task whose artifact holds the robot's reply.
+#
+#   Task list  — client.list_tasks returns all tasks the agent has processed,
+#                demonstrating the A2A task-store query interface.
+#
+#   Task get   — client.get_task(id) retrieves a specific completed task by ID,
+#                confirming the reply is durable and addressable after the fact.
+
+require_relative '../common_config'
+
+URL = 'http://localhost:9292/echo-robot'
+
+client = A2A.client(url: URL)
+
+# ---------------------------------------------------------------------------
+# 1. Discover the agent
+# ---------------------------------------------------------------------------
+puts '=== Agent Card ==='
+card = client.agent_card
+puts <<~HEREDOC
+    Name:        #{card.name}
+    Description: #{card.description}
+    Skills:      #{card.skills.map(&:name).join(', ')}
+
+HEREDOC
+
+# ---------------------------------------------------------------------------
+# 2. Send tasks and inspect replies
+# ---------------------------------------------------------------------------
+messages = [
+  'hello from robot_lab-a2a',
+  'the agent2agent protocol',
+  'RobotLab makes multi-robot workflows easy'
+]
+
+puts '=== Sending Tasks ==='
+task_ids = messages.map do |text|
+  task  = client.send_task(message: A2A::Models::Message.user(text))
+  reply = task.artifacts.first&.parts&.first&.text || '(no reply)'
+  puts <<~HEREDOC
+    [#{task.status.state}]
+      sent: #{text.inspect}
+      got:  #{reply.inspect}
+
+  HEREDOC
+  task.id
+end
+
+# ---------------------------------------------------------------------------
+# 3. List all tasks
+# ---------------------------------------------------------------------------
+puts '=== Task List ==='
+all_tasks = client.list_tasks
+all_tasks.each { |t| puts "  #{t.id}  state=#{t.status.state}" }
+puts "  Total: #{all_tasks.size}"
+puts
+
+# ---------------------------------------------------------------------------
+# 4. Retrieve a task by ID
+# ---------------------------------------------------------------------------
+puts '=== Retrieve Task ==='
+retrieved = client.get_task(task_ids.first)
+puts <<~HEREDOC
+    id:    #{retrieved.id}
+    state: #{retrieved.status.state}
+    reply: #{retrieved.artifacts.first&.parts&.first&.text.inspect}
+
+HEREDOC
+
+# ---------------------------------------------------------------------------
+# 5. Verify
+# ---------------------------------------------------------------------------
+puts '=== Verification ==='
+all_completed = task_ids.all? do |id|
+  client.get_task(id).status.state == 'completed'
+end
+puts(all_completed ? 'All tasks completed. PASS' : 'Some tasks did not complete. FAIL')

data/examples/01_sync_robot/server.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/01_sync_robot/server.rb
+#
+# Wraps a plain Ruby robot object as an A2A agent in :none (synchronous) mode.
+# The robot receives the task message, processes it, and returns a reply in a
+# single call — no interactive turns, no LLM required.
+#
+# Swap EchoRobot for a real RobotLab.build(...) robot to connect a live LLM.
+
+require_relative '../common_config'
+
+# ---------------------------------------------------------------------------
+# Robot — any object that responds to #name, #description, and #run(input).
+# run() must return an object with a #reply method.
+# ---------------------------------------------------------------------------
+class EchoRobot
+  Result = Struct.new(:reply)
+
+  def name        = 'echo_robot'
+  def description = 'Transforms every message: upcases it and reports character count'
+
+  def run(input)
+    text = input.strip
+    Result.new("#{text.upcase}  [#{text.length} chars, processed by EchoRobot]")
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Build and start the A2A server.
+#
+# RobotLab::A2A::Server wraps each robot in a RobotAdapter, builds an AgentCard
+# from the robot's name and description, and delegates HTTP serving to simple_a2a.
+# ---------------------------------------------------------------------------
+server = RobotLab::A2A::Server.new(host: 'localhost', port: 9292)
+server.add_robot(EchoRobot.new)
+
+puts <<~HEREDOC
+  Starting EchoRobot on http://localhost:9292/echo-robot
+  Press Ctrl-C to stop.
+
+HEREDOC
+
+server.run

data/examples/02_interactive_a2a_tool/client.rb

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/02_interactive_a2a_tool/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/02_interactive_a2a_tool/server.rb
+#
+# Or run both together:
+#   bundle exec ruby examples/run 02_interactive_a2a_tool
+#
+# What this demo shows:
+#
+#   Turn 1 — client sends an initial topic.
+#             The robot calls AskUserTool with question:, choices:, and default:,
+#             which suspends the robot thread and returns an input_required task.
+#             The status message contains the formatted prompt — question text,
+#             a numbered choice list, and the default value.
+#
+#   Turn 2 — client reads the prompt and sends a follow-up with task_id: pointing
+#             at the same task. The adapter resumes the robot thread with the
+#             answer, the robot completes, and the task reaches "completed".
+#
+# Note: Turn 2 requires simple_a2a >= 0.3.1 to route the follow-up to the
+# waiting robot thread via a ResumeContext. With earlier versions Turn 1 still
+# demonstrates the input_required suspension.
+
+require_relative '../common_config'
+
+URL = 'http://localhost:9292/personal-greeter'
+
+client = A2A.client(url: URL)
+
+def divider = puts('─' * 60)
+
+# ---------------------------------------------------------------------------
+# Discover the agent
+# ---------------------------------------------------------------------------
+puts
+puts '=== Agent Card ==='
+card = client.agent_card
+puts <<~HEREDOC
+    Name:        #{card.name}
+    Description: #{card.description}
+
+HEREDOC
+
+divider
+
+# ---------------------------------------------------------------------------
+# Turn 1 — initial request; expect input_required
+# ---------------------------------------------------------------------------
+puts <<~HEREDOC
+
+  === Turn 1: Initial request ===
+    Sending topic: 'the A2A protocol'
+
+HEREDOC
+
+task1 = client.send_task(message: A2A::Models::Message.user('the A2A protocol'))
+
+state1   = task1.status.state
+question = task1.status.message&.parts&.first&.text
+
+puts "  Task ID: #{task1.id}"
+puts "  State:   #{state1}"
+puts "  Question: #{question}" if question
+puts
+
+if state1 != 'input_required'
+  puts "Expected input_required — got #{state1.inspect}."
+  puts 'The robot may not have an AskUserTool injected (check server interactive: mode).'
+  exit 1
+end
+
+divider
+
+# ---------------------------------------------------------------------------
+# Turn 2 — answer the robot's question using the same task ID
+# ---------------------------------------------------------------------------
+puts <<~HEREDOC
+
+  === Turn 2: Answer ===
+    Answering: 'Alice'
+
+HEREDOC
+
+begin
+  task2 = client.send_task(
+    message: A2A::Models::Message.user('Alice'),
+    task_id: task1.id
+  )
+
+  state2    = task2.status.state
+  reply     = task2.artifacts&.first&.parts&.first&.text
+  new_task  = task2.id != task1.id # simple_a2a created a fresh task instead of resuming
+
+  puts "  Task ID: #{task2.id}"
+  puts "  State:   #{state2}"
+  puts "  Reply:   #{reply}" if reply
+  puts
+
+  divider
+  puts
+
+  puts '=== Verification ==='
+  if new_task
+    puts <<~HEREDOC
+        Turn 1 returned input_required : PASS
+        Turn 2 skipped — server created a new task instead of resuming
+              (simple_a2a >= 0.3.1 required for full two-turn resume)
+
+      Turn 1 passed. Upgrade simple_a2a to >= 0.3.1 for the full two-turn demo.
+    HEREDOC
+  else
+    turn1_ok   = state1 == 'input_required'
+    turn2_ok   = state2 == 'completed'
+    reply_ok   = reply&.include?('Alice')
+    choices_ok = question&.include?('1. Alice')
+    default_ok = question&.include?('Default: Friend')
+
+    puts <<~HEREDOC
+        Turn 1 returned input_required   : #{turn1_ok   ? 'PASS' : 'FAIL'}
+        Prompt contains numbered choices : #{choices_ok ? 'PASS' : 'FAIL'}
+        Prompt shows default value       : #{default_ok ? 'PASS' : 'FAIL'}
+        Turn 2 completed after answer    : #{turn2_ok   ? 'PASS' : 'FAIL'}
+        Reply mentions the caller name   : #{reply_ok   ? 'PASS' : 'FAIL'}
+
+    HEREDOC
+
+    all_ok = turn1_ok && turn2_ok && reply_ok && choices_ok && default_ok
+    puts(all_ok ? 'All assertions passed.' : 'One or more assertions failed.')
+  end
+rescue A2A::Error => e
+  puts <<~HEREDOC
+      A2A error on Turn 2: #{e.message}
+
+    === Verification ===
+      Turn 1 returned input_required : #{state1 == 'input_required' ? 'PASS' : 'FAIL'}
+      Turn 2 skipped (server does not yet support resume via task_id)
+
+    Turn 1 passed. Upgrade simple_a2a to >= 0.3.1 for full two-turn demo.
+  HEREDOC
+end

data/examples/02_interactive_a2a_tool/server.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/02_interactive_a2a_tool/server.rb
+#
+# Demonstrates :a2a_tool interactive mode.
+#
+# RobotLab::A2A::RobotAdapter injects an AskUserTool into the robot's local_tools
+# before calling robot.run(). When the robot calls that tool, the adapter suspends
+# the robot thread and returns an input_required task to the caller. A subsequent
+# resume call (from an A2A client that supports task resume) unblocks the thread
+# and allows the robot to finish.
+#
+# This demo shows the full two-turn flow: the robot enters input_required when
+# the injected tool is called; the client resumes using the same task ID; the
+# robot unblocks and completes the task (requires simple_a2a >= 0.3.1).
+#
+# AskUserTool is invoked with optional choices: and default: params. These are
+# formatted into the input_required status message as a numbered choice list
+# and a default-value hint, which the client receives and can display.
+#
+# To use a real LLM robot instead:
+#   require "robot_lab"
+#   robot = RobotLab.build(name: "greeter", system_prompt: "You are a friendly greeter...")
+#   # Add RobotLab::AskUser to the robot's tools so the LLM can call it.
+#   server = RobotLab::A2A::Server.new(interactive: :a2a_tool)
+#   server.add_robot(robot)
+
+require_relative '../common_config'
+
+# ---------------------------------------------------------------------------
+# Robot — calls the injected AskUserTool to pause and ask the caller a question.
+#
+# In a real RobotLab robot the LLM decides when to call AskUser. Here we call it
+# directly to keep the demo self-contained.
+# ---------------------------------------------------------------------------
+class PersonalGreeterRobot
+  Result = Struct.new(:reply)
+
+  def initialize
+    @local_tools = []
+  end
+
+  def name        = 'personal_greeter'
+  def description = 'Asks your name before composing a personalised greeting'
+  attr_reader :local_tools
+
+  def run(topic)
+    ask_tool = @local_tools.find { |t| t.is_a?(RobotLab::A2A::AskUserTool) }
+
+    name = if ask_tool
+             ask_tool.execute(
+               question: 'What is your name?',
+               choices:  %w[Alice Bob Charlie],
+               default:  'Friend'
+             )
+           else
+             'stranger'
+           end
+
+    Result.new("Hello, #{name}! You wanted to know about: #{topic}")
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Server — :a2a_tool mode injects AskUserTool before each robot.run() call.
+# ---------------------------------------------------------------------------
+server = RobotLab::A2A::Server.new(host: 'localhost', port: 9292, interactive: :a2a_tool)
+server.add_robot(PersonalGreeterRobot.new)
+
+puts <<~HEREDOC
+  Starting PersonalGreeterRobot on http://localhost:9292/personal-greeter
+  Interactive mode: :a2a_tool  (AskUserTool injection)
+  Press Ctrl-C to stop.
+
+HEREDOC
+
+server.run

data/examples/03_robot_network/client.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/03_robot_network/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/03_robot_network/server.rb
+#
+# Or run both together:
+#   bundle exec ruby examples/run 03_robot_network
+#
+# What this demo shows:
+#
+#   A RobotLab::Network (a pipeline of cooperating robots) exposed as a single
+#   A2A agent via NetworkAdapter. The client sends raw text and receives output
+#   that has passed through all three pipeline stages in sequence. From the A2A
+#   protocol's point of view this is one agent with one task — the internal
+#   multi-robot structure is completely invisible across the HTTP boundary.
+
+require_relative '../common_config'
+
+URL = 'http://localhost:9292/editorial-pipeline'
+
+client = A2A.client(url: URL)
+
+# ---------------------------------------------------------------------------
+# 1. Discover the agent
+# ---------------------------------------------------------------------------
+puts '=== Agent Card ==='
+card = client.agent_card
+puts <<~HEREDOC
+    Name:        #{card.name}
+    Description: #{card.description}
+    Skills:      #{card.skills.map(&:name).join(', ')}
+
+HEREDOC
+
+# ---------------------------------------------------------------------------
+# 2. Send documents through the pipeline
+# ---------------------------------------------------------------------------
+documents = [
+  'the quick brown fox jumps over the lazy dog',
+  'ruby is a dynamic object-oriented programming language',
+  'the agent2agent protocol enables robots to communicate over http'
+]
+
+puts '=== Pipeline Results ==='
+results = documents.map do |doc|
+  task   = client.send_task(message: A2A::Models::Message.user(doc))
+  output = task.artifacts.first&.parts&.first&.text || '(no output)'
+
+  puts <<~HEREDOC
+    Input:  #{doc.inspect}
+    Output: #{output.inspect}
+    State:  #{task.status.state}
+
+  HEREDOC
+  { task: task, output: output }
+end
+
+# ---------------------------------------------------------------------------
+# 3. Verify all pipeline stages ran
+# ---------------------------------------------------------------------------
+puts '=== Verification ==='
+checks = results.map do |r|
+  output = r[:output]
+  completed  = r[:task].status.state == 'completed'
+  analysed   = output.match?(/\[analysed:/i)
+  formatted  = output.match?(/[A-Z]/)
+  summarised = output.start_with?('SUMMARY')
+
+  puts <<~HEREDOC
+    completed  : #{completed  ? 'PASS' : 'FAIL'}
+    analysed   : #{analysed   ? 'PASS' : 'FAIL'}
+    formatted  : #{formatted  ? 'PASS' : 'FAIL'}
+    summarised : #{summarised ? 'PASS' : 'FAIL'}
+
+  HEREDOC
+
+  completed && analysed && formatted && summarised
+end
+
+puts(checks.all? ? 'All pipeline checks passed.' : 'One or more checks failed.')

data/examples/03_robot_network/server.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/03_robot_network/server.rb
+#
+# Wraps a RobotLab-style network (a pipeline of robots) as a single A2A agent.
+# The network processes the input through multiple stages in sequence and returns
+# the final output. From the A2A client's perspective it looks like one agent.
+#
+# NetworkAdapter only supports :none (synchronous) mode. For interactive networks
+# wrap individual robots with RobotAdapter instead.
+#
+# To use a real RobotLab::Network:
+#   require "robot_lab"
+#   network = RobotLab.create_network(name: "pipeline") do
+#     step :analyst, analyst_robot, depends_on: :none
+#     step :writer,  writer_robot,  depends_on: [:analyst]
+#   end
+#   server = RobotLab::A2A::Server.new
+#   server.add_network(network, name: "pipeline")
+
+require_relative '../common_config'
+
+# ---------------------------------------------------------------------------
+# Individual robots — each transforms the text in a distinct way.
+# ---------------------------------------------------------------------------
+class AnalyserRobot
+  Result = Struct.new(:reply)
+  def run(input) = Result.new("[analysed: #{input.split.length} words] #{input}")
+end
+
+class FormatterRobot
+  Result = Struct.new(:reply)
+  def run(input) = Result.new(input.gsub(/\b\w/, &:upcase))
+end
+
+class SummaryRobot
+  Result = Struct.new(:reply)
+  def run(input) = Result.new("SUMMARY → #{input}")
+end
+
+# ---------------------------------------------------------------------------
+# Pipeline network — runs robots in sequence, passing output as the next input.
+#
+# Implements the interface expected by NetworkAdapter:
+#   network.run(message: String) → object responding to #last_text_content
+# ---------------------------------------------------------------------------
+class EditorialPipeline
+  NetworkResult = Struct.new(:last_text_content)
+
+  STAGES = [AnalyserRobot, FormatterRobot, SummaryRobot].freeze
+
+  def run(message:)
+    output = STAGES.reduce(message) { |text, klass| klass.new.run(text).reply }
+    NetworkResult.new(output)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Server — add_network requires an explicit name: for the agent card.
+# The path defaults to "/editorial-pipeline" (DNS-safe label of the name).
+# ---------------------------------------------------------------------------
+server = RobotLab::A2A::Server.new(host: 'localhost', port: 9292)
+server.add_network(
+  EditorialPipeline.new,
+  name: 'editorial_pipeline',
+  description: 'Three-stage text pipeline: analyse → format → summarise'
+)
+
+puts <<~HEREDOC
+  Starting EditorialPipeline on http://localhost:9292/editorial-pipeline
+  Stages: AnalyserRobot → FormatterRobot → SummaryRobot
+  Press Ctrl-C to stop.
+
+HEREDOC
+
+server.run